feat: add dual SDL2/SDL3 support with CMake option - #129
Open
doncollins1985 wants to merge 1 commit into
Open
Conversation
doncollins1985
commented
Jul 21, 2026
doncollins1985
commented
- Add USE_SDL CMake option (Auto/SDL2/SDL3) — prefers SDL3 when available
- All source files use #ifdef USE_SDL3 guards for API differences: Event types, key struct members, modifier keys, timer/window functions, ImGui backend (sdl2/sdl3), GLSL version (150/300 es), audio capture API, OpenGL proc loader, drop file handling
- Conditional SDL linkage: SDL3::SDL3 vs SDL2::SDL2 + SDL2::SDL2main
- New cmake/SDL3Target.cmake for SDL3 target verification
- Updated ImGui.cmake for conditional backend and kept ImGuiDemo target
- Updated dependencies_check.cmake and packaging-linux.cmake for SDL version
- Added audio device hotplug support for SDL3
- Added CurrentAudioLevel() and RefreshDeviceList() to AudioCapture
- Refactored drop file handler into HandleDropFile() method
- SDL3 audio capture uses SDL_AudioStream API
- SDL key constants remapped via #undef/#define for SDL3 naming
- Guarded projectm_create_with_opengl_load_proc for older libprojectM
- CI builds both SDL2 and SDL3 on all four platforms: Ubuntu Linux, Arch Linux, Windows (vcpkg), macOS (Homebrew)
- vcpkg.json includes both sdl2 and sdl3
- Windows runner pinned to windows-2022 for VS 2022 compatibility
- Add USE_SDL CMake option (Auto/SDL2/SDL3) — prefers SDL3 when available - All source files use #ifdef USE_SDL3 guards for API differences: Event types, key struct members, modifier keys, timer/window functions, ImGui backend (sdl2/sdl3), GLSL version (150/300 es), audio capture API, OpenGL proc loader, drop file handling - Conditional SDL linkage: SDL3::SDL3 vs SDL2::SDL2 + SDL2::SDL2main - New cmake/SDL3Target.cmake for SDL3 target verification - Updated ImGui.cmake for conditional backend and kept ImGuiDemo target - Updated dependencies_check.cmake and packaging-linux.cmake for SDL version - Added audio device hotplug support for SDL3 - Added CurrentAudioLevel() and RefreshDeviceList() to AudioCapture - Refactored drop file handler into HandleDropFile() method - SDL3 audio capture uses SDL_AudioStream API - SDL key constants remapped via #undef/#define for SDL3 naming - Guarded projectm_create_with_opengl_load_proc for older libprojectM - CI builds both SDL2 and SDL3 on all four platforms: Ubuntu Linux, Arch Linux, Windows (vcpkg), macOS (Homebrew) - vcpkg.json includes both sdl2 and sdl3 - Windows runner pinned to windows-2022 for VS 2022 compatibility
Author
|
? |
kblaschke
requested changes
Aug 28, 2026
kblaschke
left a comment
kblaschke
left a comment
Member
There was a problem hiding this comment.
Overall, a solid upgrade.
I'm not a huge fan of using #ifdefs everywhere, though given how SDL calls are spread over the code base, I don't see any other simple solution than wrapping SDL again, which doesn't make lots of sense.
I've added some comments, mostly related to the build files, packaging and check workflow. The most important one is adding features to the vcpkg manifest to prevent pulling in both libraries when only one of them is ever needed.
Comment on lines
+98
to
+133
| if(USE_SDL STREQUAL "Auto") | ||
| find_package(SDL3 QUIET) | ||
| if(SDL3_FOUND) | ||
| set(USE_SDL3 ON) | ||
| set(SDL_VERSION "${SDL3_VERSION}") | ||
| message(STATUS "Using SDL3 (found ${SDL3_VERSION})") | ||
| else() | ||
| find_package(SDL2 REQUIRED) | ||
| set(SDL_VERSION "${SDL2_VERSION}") | ||
| message(STATUS "Using SDL2 (found ${SDL2_VERSION})") | ||
| endif() | ||
| elseif(USE_SDL STREQUAL "SDL3") | ||
| find_package(SDL3 REQUIRED) | ||
| set(USE_SDL3 ON) | ||
| set(SDL_VERSION "${SDL3_VERSION}") | ||
| message(STATUS "Using SDL3 (requested, found ${SDL3_VERSION})") | ||
| else() | ||
| find_package(SDL2 REQUIRED) | ||
| set(SDL_VERSION "${SDL2_VERSION}") | ||
| message(STATUS "Using SDL2 (requested, found ${SDL2_VERSION})") | ||
| endif() | ||
|
|
||
| # --- SDL linkage type --- | ||
| if(USE_SDL3) | ||
| set(SDL_LINKAGE "shared" CACHE STRING "Set to either shared or static to specify how libSDL3 should be linked. Defaults to shared.") | ||
| if(NOT SDL_LINKAGE STREQUAL "shared" AND NOT SDL_LINKAGE STREQUAL "static") | ||
| message(FATAL_ERROR "Invalid libSDL3 linkage: \"${SDL_LINKAGE}\". Please specify \"shared\" or \"static\".") | ||
| endif() | ||
| include(SDL3Target) | ||
| else() | ||
| set(SDL_LINKAGE "shared" CACHE STRING "Set to either shared or static to specify how libSDL2 should be linked. Defaults to shared.") | ||
| if(NOT SDL_LINKAGE STREQUAL "shared" AND NOT SDL_LINKAGE STREQUAL "static") | ||
| message(FATAL_ERROR "Invalid libSDL2 linkage: \"${SDL_LINKAGE}\". Please specify \"shared\" or \"static\".") | ||
| endif() | ||
| include(SDL2Target) | ||
| endif() |
Member
There was a problem hiding this comment.
I guess this block can be shortened a bit by by using the value of USE_SDL as a variable, e.g:
Suggested change
| if(USE_SDL STREQUAL "Auto") | |
| find_package(SDL3 QUIET) | |
| if(SDL3_FOUND) | |
| set(USE_SDL3 ON) | |
| set(SDL_VERSION "${SDL3_VERSION}") | |
| message(STATUS "Using SDL3 (found ${SDL3_VERSION})") | |
| else() | |
| find_package(SDL2 REQUIRED) | |
| set(SDL_VERSION "${SDL2_VERSION}") | |
| message(STATUS "Using SDL2 (found ${SDL2_VERSION})") | |
| endif() | |
| elseif(USE_SDL STREQUAL "SDL3") | |
| find_package(SDL3 REQUIRED) | |
| set(USE_SDL3 ON) | |
| set(SDL_VERSION "${SDL3_VERSION}") | |
| message(STATUS "Using SDL3 (requested, found ${SDL3_VERSION})") | |
| else() | |
| find_package(SDL2 REQUIRED) | |
| set(SDL_VERSION "${SDL2_VERSION}") | |
| message(STATUS "Using SDL2 (requested, found ${SDL2_VERSION})") | |
| endif() | |
| # --- SDL linkage type --- | |
| if(USE_SDL3) | |
| set(SDL_LINKAGE "shared" CACHE STRING "Set to either shared or static to specify how libSDL3 should be linked. Defaults to shared.") | |
| if(NOT SDL_LINKAGE STREQUAL "shared" AND NOT SDL_LINKAGE STREQUAL "static") | |
| message(FATAL_ERROR "Invalid libSDL3 linkage: \"${SDL_LINKAGE}\". Please specify \"shared\" or \"static\".") | |
| endif() | |
| include(SDL3Target) | |
| else() | |
| set(SDL_LINKAGE "shared" CACHE STRING "Set to either shared or static to specify how libSDL2 should be linked. Defaults to shared.") | |
| if(NOT SDL_LINKAGE STREQUAL "shared" AND NOT SDL_LINKAGE STREQUAL "static") | |
| message(FATAL_ERROR "Invalid libSDL2 linkage: \"${SDL_LINKAGE}\". Please specify \"shared\" or \"static\".") | |
| endif() | |
| include(SDL2Target) | |
| endif() | |
| if(USE_SDL STREQUAL "Auto") | |
| find_package(SDL3 QUIET) | |
| if(SDL3_FOUND) | |
| set(USE_SDL SDL3) | |
| else() | |
| set(USE_SDL SDL2) | |
| endif() | |
| endif() | |
| if(USE_SDL STREQUAL "SDL3") | |
| find_package(SDL3 REQUIRED) | |
| set(USE_SDL3 ON) | |
| set(SDL_VERSION "${SDL3_VERSION}") | |
| message(STATUS "Using SDL3 (found ${SDL3_VERSION})") | |
| elseif(USE_SDL STREQUAL "SDL2") | |
| find_package(SDL2 REQUIRED) | |
| set(SDL_VERSION "${SDL2_VERSION}") | |
| message(STATUS "Using SDL2 (found ${SDL2_VERSION})") | |
| else() | |
| message(FATAL_ERROR "USE_SDL was not set to Auto, SDL2 or SDL3: ${USE_SDL}") | |
| endif() | |
| # --- SDL linkage type --- | |
| set(SDL_LINKAGE "shared" CACHE STRING "Set to either shared or static to specify how lib${USE_SDL} should be linked. Defaults to shared.") | |
| if(NOT SDL_LINKAGE STREQUAL "shared" AND NOT SDL_LINKAGE STREQUAL "static") | |
| message(FATAL_ERROR "Invalid lib${USE_SDL} linkage: \"${SDL_LINKAGE}\". Please specify \"shared\" or \"static\".") | |
| endif() | |
| include(${USE_SDL}Target) |
| "dependencies": [ | ||
| "glew", | ||
| "sdl2", | ||
| "sdl3", |
Member
There was a problem hiding this comment.
Adding both sdl2 and sdl3 as hard dependencies shouldn't be done, as it takes twice the time to build the dependencies and may pull in additional libraries not required for building the final application, unnecessarily increasing build times and local disk space requirements.
Please wrap these into features (sdl2and sdl3) and set the vcpkg manifest feature variables according to the USE_SDL parameter. If it's set to Auto and vcpkg is being used, we should prefer libSDL3.
| set(CPACK_DEBIAN_PACKAGE_DEPENDS "libsdl2-2.0-0 (>=2.0.16), libgl1, libfreetype6") | ||
| # Require SDL2 2.0.16 or higher, lower versions can't use monitor devices (SDL2 only) | ||
| if(USE_SDL3) | ||
| set(CPACK_DEBIAN_PACKAGE_DEPENDS "libgl1, libfreetype6") |
Member
There was a problem hiding this comment.
We have to use libSDL3 from the OS due to audio server linking, e.g. the vcpkg-built one won't work for running the application. Thus, the final package shouldn't contain libSDL3.so, but rather use the OS-installed one. To make sure users have the proper library installed, it should be added to the DEB package dependencies:
Suggested change
| set(CPACK_DEBIAN_PACKAGE_DEPENDS "libgl1, libfreetype6") | |
| set(CPACK_DEBIAN_PACKAGE_DEPENDS "libsdl3, libgl1, libfreetype6") |
| build-linux: | ||
| name: Ubuntu Linux, x86_64 | ||
| name: Ubuntu Linux ${{ matrix.sdl_version }}, x86_64 | ||
| runs-on: ubuntu-latest |
Member
There was a problem hiding this comment.
Instead of running on ubuntu-latest, we could build SDL2 on ubuntu-24.04 and SDL3 on ubuntu-26.04, which is already available as a GHA runner (in preview). This would enable using the OS-provided libsdl3-dev package and save time to build it ourselves.
Additionally, on Linux, the app will most probably only use the latest SDL release available for the respective distro, or SDL2 as a compatibility solution, sobuilding against SDL3 is only really required where it's also available natively.
| name: Windows, x64 | ||
| runs-on: windows-latest | ||
| name: Windows ${{ matrix.sdl_version }}, x64 | ||
| runs-on: windows-2022 |
Member
There was a problem hiding this comment.
We should keep windows-latest and change the CMake generator to "Visual Studio 18 2026" instead.
Suggested change
| runs-on: windows-2022 | |
| runs-on: windows-latest |
| cmake -G "Visual Studio 17 2022" -A "X64" -S "${{ github.workspace }}/frontend-sdl2" -B "${{ github.workspace }}/cmake-build-frontend-sdl2" -DCMAKE_TOOLCHAIN_FILE="${{ github.workspace }}/vcpkg/scripts/buildsystems/vcpkg.cmake" -DVCPKG_TARGET_TRIPLET=x64-windows-static -DCMAKE_PREFIX_PATH="${{ github.workspace }}/install-libprojectm" -DCMAKE_INSTALL_PREFIX="${{ github.workspace }}/install-frontend-sdl2" -DCMAKE_MSVC_RUNTIME_LIBRARY="MultiThreaded$<$<CONFIG:Debug>:Debug>" -DCMAKE_VERBOSE_MAKEFILE=YES -DSDL2_LINKAGE=static -DBUILD_TESTING=YES | ||
| cmake --build "${{ github.workspace }}/cmake-build-frontend-sdl2" --parallel --config Release | ||
| mkdir cmake-build-frontend | ||
| cmake -G "Visual Studio 17 2022" -A "X64" -S "${{ github.workspace }}/frontend-sdl-cpp" -B "${{ github.workspace }}/cmake-build-frontend" -DCMAKE_TOOLCHAIN_FILE="${{ github.workspace }}/vcpkg/scripts/buildsystems/vcpkg.cmake" -DVCPKG_TARGET_TRIPLET=x64-windows-static -DCMAKE_PREFIX_PATH="${{ github.workspace }}/install-libprojectm" -DCMAKE_INSTALL_PREFIX="${{ github.workspace }}/install-frontend" -DCMAKE_MSVC_RUNTIME_LIBRARY="MultiThreaded$<$<CONFIG:Debug>:Debug>" -DCMAKE_VERBOSE_MAKEFILE=YES -DSDL_LINKAGE=static -DBUILD_TESTING=YES -DUSE_SDL=${{ matrix.sdl_version }} |
Member
There was a problem hiding this comment.
Suggested change
| cmake -G "Visual Studio 17 2022" -A "X64" -S "${{ github.workspace }}/frontend-sdl-cpp" -B "${{ github.workspace }}/cmake-build-frontend" -DCMAKE_TOOLCHAIN_FILE="${{ github.workspace }}/vcpkg/scripts/buildsystems/vcpkg.cmake" -DVCPKG_TARGET_TRIPLET=x64-windows-static -DCMAKE_PREFIX_PATH="${{ github.workspace }}/install-libprojectm" -DCMAKE_INSTALL_PREFIX="${{ github.workspace }}/install-frontend" -DCMAKE_MSVC_RUNTIME_LIBRARY="MultiThreaded$<$<CONFIG:Debug>:Debug>" -DCMAKE_VERBOSE_MAKEFILE=YES -DSDL_LINKAGE=static -DBUILD_TESTING=YES -DUSE_SDL=${{ matrix.sdl_version }} | |
| cmake -G "Visual Studio 18 2026" -A "X64" -S "${{ github.workspace }}/frontend-sdl-cpp" -B "${{ github.workspace }}/cmake-build-frontend" -DCMAKE_TOOLCHAIN_FILE="${{ github.workspace }}/vcpkg/scripts/buildsystems/vcpkg.cmake" -DVCPKG_TARGET_TRIPLET=x64-windows-static -DCMAKE_PREFIX_PATH="${{ github.workspace }}/install-libprojectm" -DCMAKE_INSTALL_PREFIX="${{ github.workspace }}/install-frontend" -DCMAKE_MSVC_RUNTIME_LIBRARY="MultiThreaded$<$<CONFIG:Debug>:Debug>" -DCMAKE_VERBOSE_MAKEFILE=YES -DSDL_LINKAGE=static -DBUILD_TESTING=YES -DUSE_SDL=${{ matrix.sdl_version }} |
| if [ "${{ matrix.sdl_version }}" = "SDL2" ]; then | ||
| brew install sdl2 ninja googletest poco | ||
| else | ||
| brew install ninja googletest poco |
Member
There was a problem hiding this comment.
Homebrew now ships SDL3, so we should use it instead of building it each time to speed up the build check:
Suggested change
| brew install ninja googletest poco | |
| brew install sdl3 ninja googletest poco |
Comment on lines
+280
to
+298
| - name: Checkout SDL3 Sources | ||
| if: matrix.sdl_version == 'SDL3' | ||
| uses: actions/checkout@v6 | ||
| with: | ||
| repository: libsdl-org/SDL | ||
| path: sdl3 | ||
| ref: 'main' | ||
| submodules: recursive | ||
|
|
||
| - name: Build/Install SDL3 | ||
| if: matrix.sdl_version == 'SDL3' | ||
| run: | | ||
| mkdir cmake-build-sdl3 | ||
| cmake -G Ninja -S sdl3 -B cmake-build-sdl3 \ | ||
| -DBUILD_SHARED_LIBS=OFF \ | ||
| -DCMAKE_BUILD_TYPE=Release \ | ||
| -DCMAKE_INSTALL_PREFIX=${{ github.workspace }}/install-sdl3 | ||
| cmake --build cmake-build-sdl3 --parallel | ||
| cmake --install ${{ github.workspace }}/cmake-build-sdl3 |
Member
There was a problem hiding this comment.
Suggested change
| - name: Checkout SDL3 Sources | |
| if: matrix.sdl_version == 'SDL3' | |
| uses: actions/checkout@v6 | |
| with: | |
| repository: libsdl-org/SDL | |
| path: sdl3 | |
| ref: 'main' | |
| submodules: recursive | |
| - name: Build/Install SDL3 | |
| if: matrix.sdl_version == 'SDL3' | |
| run: | | |
| mkdir cmake-build-sdl3 | |
| cmake -G Ninja -S sdl3 -B cmake-build-sdl3 \ | |
| -DBUILD_SHARED_LIBS=OFF \ | |
| -DCMAKE_BUILD_TYPE=Release \ | |
| -DCMAKE_INSTALL_PREFIX=${{ github.workspace }}/install-sdl3 | |
| cmake --build cmake-build-sdl3 --parallel | |
| cmake --install ${{ github.workspace }}/cmake-build-sdl3 |
Comment on lines
+324
to
+329
| if [ "${{ matrix.sdl_version }}" = "SDL3" ]; then | ||
| CMAKE_PREFIX_PATH="${CMAKE_PREFIX_PATH};${{ github.workspace }}/install-sdl3" | ||
| fi | ||
| mkdir cmake-build-frontend | ||
| cmake -G Ninja -S "${{ github.workspace }}/frontend-sdl-cpp" -B "${{ github.workspace }}/cmake-build-frontend" -DCMAKE_BUILD_TYPE=Release "-DCMAKE_PREFIX_PATH=${CMAKE_PREFIX_PATH}" -DCMAKE_INSTALL_PREFIX="${{ github.workspace }}/install-frontend" -DUSE_SDL=${{ matrix.sdl_version }} | ||
| cmake --build "${{ github.workspace }}/cmake-build-frontend" --parallel |
Member
There was a problem hiding this comment.
Suggested change
| if [ "${{ matrix.sdl_version }}" = "SDL3" ]; then | |
| CMAKE_PREFIX_PATH="${CMAKE_PREFIX_PATH};${{ github.workspace }}/install-sdl3" | |
| fi | |
| mkdir cmake-build-frontend | |
| cmake -G Ninja -S "${{ github.workspace }}/frontend-sdl-cpp" -B "${{ github.workspace }}/cmake-build-frontend" -DCMAKE_BUILD_TYPE=Release "-DCMAKE_PREFIX_PATH=${CMAKE_PREFIX_PATH}" -DCMAKE_INSTALL_PREFIX="${{ github.workspace }}/install-frontend" -DUSE_SDL=${{ matrix.sdl_version }} | |
| cmake --build "${{ github.workspace }}/cmake-build-frontend" --parallel | |
| mkdir cmake-build-frontend | |
| cmake -G Ninja -S "${{ github.workspace }}/frontend-sdl-cpp" -B "${{ github.workspace }}/cmake-build-frontend" -DCMAKE_BUILD_TYPE=Release "-DCMAKE_PREFIX_PATH=${CMAKE_PREFIX_PATH}" -DCMAKE_INSTALL_PREFIX="${{ github.workspace }}/install-frontend" -DUSE_SDL=${{ matrix.sdl_version }} | |
| cmake --build "${{ github.workspace }}/cmake-build-frontend" --parallel |
Member
|
Sorry for the late reply, I was swamped with other work in the past weeks/months, and the PRs just kept piling up. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.