sdl3-gpu-starter

KO | EN

gitlite — search

#javascript #python #react #llm #android #machine-learning #docker #windows #awesome #awesome-list #pytorch #security #openai #open-source

sdl3-gpu-starter

(★ 15)

SDL3 GPU C++ cross platform starter project. Supports Windows, Linux, macOS, iOS and Android.

sdl3-gpu-starter Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

## SDL3 GPU C++ Cross Platform Starter Project
<br>
<p align="center">
  <img src="./android/app/src/main/res/mipmap-hdpi/ic_launcher.png"/>
</p>

## About

This project provides a comprehensive starter template for using the new [SDL3](https://github.com/libsdl-org/SDL) [GPU API](https://wiki.libsdl.org/SDL3/CategoryGPU) in a modern C++ and cross-platform environment. It supports multiple target platforms: Windows, Linux, macOS, iOS, and Android. The main build system uses [CMake](https://cmake.org/) with [Ninja](https://ninja-build.org/), while [vcpkg](https://github.com/microsoft/vcpkg) manages dependencies across platforms.

The app loads a star mesh object from local storage and renders it on screen.

## Supported Platforms

The following platforms have been tested and are officially supported:

| Platform | Architecture | Debug | Release | CMake Preset   | Graphical API |
|----------|--------------|:-----:|:-------:|----------------|---------------|
| Windows  | x64          | ✅    | ✅️      | windows-x64     | DirectX 12    |
| Windows  | arm64        | ⚠️    | ⚠️      | windows-arm64   | DirectX 12    |
| Linux    | x64          | ✅️    | ✅️      | linux-x64       | Vulkan        |
| Linux    | arm64        | ⚠️    | ⚠️      | linux-arm64     | Vulkan        |
| macOS    | x64          | ⚠️    | ⚠️      | osx-x64         | Metal         |
| macOS    | arm64        | ✅    | ✅      | osx-arm64       | Metal         |
| iOS      | arm64        | ✅    | ✅      | ios-arm64       | Metal         |
| Android  | arm64        | ✅    | ✅      | android-arm64   | Vulkan        |

✅ = Fully tested and supported.  
⚠️ = Supported but untested.

## Project Structure

```
├── CMakeLists.txt                          # Main project definition
├── CMakePresets.json                       # Build configuration presets
├── src/                                    # C++ source code
├── content/                                # Assets including shaders and models
├── android/                                # Android-specific configuration
│   └── app/libs/SDL3-3.2.16.aar            # libSDL Android archive
├── ios/                                    # iOS-specific configuration
├── scripts/                                # Build and utility scripts
└── third_party/                            # External dependencies (vcpkg, shadercross)
```

## Build

Before building, make sure you update submodules:
```bash
git submodule update --init --recursive
```

The build scripts are written in Python to ensure consistent build behaviour regardless of the host operating system (Windows, Linux, macOS).

To see all available build options:
```bash
python3 scripts/build.py -h
```

Example build commands:
```bash
# Target osx with release config
python3 scripts/build.py --platform osx --arch arm64 --config release

# More verbose build command for linux that also includes shadercross
python3 scripts/build.py --platform linux --arch x64 --clean --verbose --shadercross
```

### Build Dependencies

The following tools are required for building on all platforms:
- [CMake](https://cmake.org/) 3.23 or newer
- [Git](https://git-scm.com/)
- [Ninja](https://ninja-build.org/) build system
- [Python](https://www.python.org/) 3.6 or newer
- A compatible compiler:
  - [Clang](https://clang.llvm.org/) on macOS
  - [GCC](https://gcc.gnu.org/) on Linux
  - [MSVC](https://visualstudio.microsoft.com/vs/features/cplusplus/) on Windows

### Linux development

The following commands are for **Arch Linux**. If you're using Ubuntu or another distribution, the commands and the package names will be different.

Install Vulkan dependencies:
```bash
sudo pacman -S vulkan-devel vulkan-icd-loader
```
Install the Vulkan driver for your GPU:
- NVIDIA: `sudo pacman -S nvidia nvidia-utils`
- AMD: `sudo pacman -S vulkan-radeon`
- Intel: `sudo pacman -S vulkan-intel`

You can check Vulkan support with:
```bash
sudo pacman -S vulkan-tools
vulkaninfo
```

**Note**:
If you choose to install the LunarG SDK instead of using a package manager, you'll also need to export the `VULKAN_SDK` environment variable.

### macOS development

The following command will provide your compiler and other essential build tools:
```bash
xcode-select --install
```

Alternatively you can install Xcode from the App Store.

### iOS development

When targeting iOS, you have two options for app signing:

* **With a paid developer account**: Build using `--platform ios` and the artifacts will be placed in `${output_dir}/ios-{release|debug}`. You'll need to sign the `.app` manually with `codesign` before deploying.

* **With a free personal account**: Use `--platform ios-xcode` to generate an Xcode project. Open the resulting `.xcodeproj` file from `build/ios-xcode/` and configure signing under `Targets > sdl3_gpu_starter_project > Signing & Capabilities`. Select your personal team from the dropdown. If you need to create an account, go to `Preferences > Accounts` and add an Apple ID. You can then deploy and debug to connected iOS devices. From Xcode you can also use the Metal debugger to debug at runtime any rendering issues on your device.

### Android development

For Android development:

1. Install [Android Studio](https://developer.android.com/studio) and use `Tools > SDK Manager > SDK Tools` to install the `NDK (Side by Side)`
2. Install `CMake` from `Tools > SDK Manager > SDK Tools` in Android Studio
3. Install Java JDK 11 or newer
4. Install [Gradle](https://gradle.org/) (used to orchestrate the build). Make sure `gradle` is available to your shell
5. Configure environment variables in your shell or fill in and `source` the `.android_env` file. Example:
```bash
export ANDROID_SDK_ROOT=~/Library/Android/sdk
export ANDROID_HOME="$ANDROID_SDK_ROOT"
export ANDROID_NDK_ROOT=~/Library/Android/sdk/ndk/29.0.13599879
export ANDROID_NDK_HOME="$ANDROID_NDK_ROOT"
export PATH=$PATH:$ANDROID_SDK_ROOT/platform-tools
```

```bash
source android_env.sh
```

You also need to fill in [gradle.properties](android/gradle.properties) with the versions of CMake and the NDK that Android Studio installed. CMake is installed under `$ANDROID_SDK_ROOT/cmake/` and the NDK is under `$ANDROID_SDK_ROOT/ndk/$version`.
`gradle.properties` example:
```bash
cmakeVersion=4.0.2
ndkVersion=29.0.13599879
```

To build for Android, use:
```bash
python3 scripts/build.py --platform android --arch arm64 --config release
```

You can install the resulting `.apk` from Android Studio to an attached (`Developer Mode` enabled) Android device. You can then attach `logcat` to retrieve realtime logs.

**Note**: Gradle will use the CMake version installed with Android Studio **not** the system one.

**Note**: For Android Vulkan dependencies come installed with the NDK.

### Windows development

You can install your C++ toolchain from the Visual Studio Installer. Select `Desktop development with C++` during installation.

Use one of the special command prompts that set up the dev environment when opened.

e.g.: `x64 Native Tools Command Prompt for VS 2019`.

These prompts usually invoke `vcvars64.bat` or similar which sets up `PATH` and other environment variables that make available the correct MSVC compiler, linker, Windows SDK and other tools to your shell. If you want to use a different way to build it make sure you have all the env vars exported.

## CMake

This project uses [CMake's preset feature](https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html) to streamline cross platform support and to facilitate adding support for CI/CD.

- `CMakeLists.txt`: Defines the project structure, targets, and dependencies
- `CMakePresets.json`: Contains platform-specific build configurations including compiler settings, build type, and cache variables

Android builds use [Gradle](https://gradle.org/), which directly uses the CMakeLists.txt but ignores the CMakePresets.json. The build configuration for Android is defined in `android/app/build.gradle`.

## vcpkg

Dependencies are managed through vcpkg, which is included as a Git submodule under `third_party/vcpkg`.

The build system automatically bootstraps vcpkg on first run. Each target platform uses a specific vcpkg triplet determined by the `VCPKG_TARGET_ARCHITECTURE` variable set in the CMake configuration. In order to support other platforms or other configurations you need to create the vcpkg triplet as necessary and add to `third_party/vcpkg/triplets`.

All dependencies are locked down to the versions used to build the project for all the supported platforms.

## Shaders and shadercross

Shaders are written in `HLSL` and then transpiled to the platform required format at build time. [Shadercross](https://github.com/libsdl-org/SDL_shadercross) is used to transpile the `HLSL` shaders to Metal, DirectX 12, and Vulkan shader formats. It is included under `third_party/shadercross` and it is initialized when you update submodules. `HLSL` source shaders are found in `content/shaders/source`.

To transpile all shaders, you need to build with `--shadercross` argument which will include the `SDL_shadercross` project in the build process.

```bash
python3 scripts/build.py --platform windows --arch x64 --shadercross
```

This will gather all the `HLSL` source shaders located under `content/shaders` and generate shaders for all the other supported graphics APIs. The resulting shaders can be found under `content/shaders/transpiled`. They are then automatically bundled up with the rest of the `content/` folder when packaging the app.

On each subsequent build, only the shaders that were modified or newly added will be transpiled.

## Remarks

- **Android Java Files**: The Android archive `android/app/libs/SDL3-3.2.16.aar` was fetched from [libSDL releases](https://github.com/libsdl-org/SDL/releases). This is a manual step that needs to be done each time you want to update the version of SDL you're using (currently the version is locked down in [vcpkg.json](./vcpkg.json)). You can automate the retrieval of the archive if you assume the naming conventions don't change.

You can also choose to directly integrate the `libSDL` java files in your codebase. You would need to copy the files from under:

```
  libSDL/android-project/app/src/main/java/org/libsdl/app
  ```
  to
  ```
  android/app/src/main/java/org/libsdl/app/
  ```

You could then automate the process by executing the copy stage after `vcpkg` fetches the SDL sources. This is not straightforward however since it creates a circular dependency: Gradle invokes in parallel the Java compiler and the NDK native build. The NDK build instructs vcpkg to fetch the SDL sources, but the Java compiler needs those sources before compilation begins. The solution requires complex dependency management, so for now, manually copying the `.aar` archive is good enough.

- **Graphical API**: Currently the backend graphical API is strictly correlated with the platform. If you want to add support for multiple graphical backends, or even switch between them at runtime, take a look at `common.cpp::get_gpu_driver` and `common.cpp::get_shader_format` to understand what assumptions were made. The starter project implements the following configurations:

| Platform | Graphical API|
  |----------|--------------|
  | Windows  | DirectX12    |
  | Linux    | Vulkan       |
  | macOS    | Metal        |
  | iOS      | Metal        |
  | Android  | Vulkan       |

## License

This project is licensed under the MIT License - see the LICENSE file for details.

Third party licenses can be found [here](./THIRD_PARTY_LICENSES).

sdl3-gpu-starter

sdl3-gpu-starter Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

sdl3-gpu-starter

sdl3-gpu-starter Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README