projectM-visualizer · doncollins1985 · Jul 21, 2026
diff --git a/.github/workflows/buildcheck.yaml b/.github/workflows/buildcheck.yaml
@@ -1,21 +1,48 @@
 # Build check workflow
 # Used to check if projectMSDL compiles with upstream master of libprojectM.
+# Tests both SDL2 and SDL3 builds on all platforms.
 # The resulting binaries are not considered for public use though.
 name: Build Check
 
 on: [ push, pull_request ]
 
 jobs:
   build-linux:
-    name: Ubuntu Linux, x86_64
+    name: Ubuntu Linux ${{ matrix.sdl_version }}, x86_64
     runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        sdl_version: [SDL2, SDL3]
 
     steps:
-
       - name: Install Build Dependencies
         run: |
           sudo apt update
-          sudo apt install build-essential libgl1-mesa-dev mesa-common-dev libsdl2-dev libpoco-dev ninja-build libssl-dev libfreetype6-dev
+          if [ "${{ matrix.sdl_version }}" = "SDL2" ]; then
+            sudo apt install build-essential libgl1-mesa-dev mesa-common-dev libsdl2-dev libpoco-dev ninja-build libssl-dev libfreetype6-dev
+          else
+            sudo apt install build-essential libgl1-mesa-dev mesa-common-dev libpoco-dev ninja-build libssl-dev libfreetype6-dev libasound2-dev libpulse-dev libx11-dev libxext-dev libxrandr-dev libxcursor-dev libxi-dev libxfixes-dev libxss-dev libxtst-dev libxkbcommon-dev libdrm-dev libgbm-dev libegl1-mesa-dev libdbus-1-dev libibus-1.0-dev libpipewire-0.3-dev libwayland-dev libdecor-0-dev liburing-dev
+          fi
+
+      - 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
 
       # We need to build/link Poco ourselves as static libraries, because Ubuntu Jammy ships with a broken Poco 1.11.0
       - name: Checkout Poco Sources
@@ -64,42 +91,113 @@ jobs:
           cmake --build cmake-build-libprojectm --parallel
           cmake --install "${{ github.workspace }}/cmake-build-libprojectm"
 
-      - name: Checkout frontend-sdl2 Sources
+      - name: Checkout frontend-sdl-cpp Sources
         uses: actions/checkout@v6
         with:
-          path: frontend-sdl2
+          path: frontend-sdl-cpp
           submodules: recursive
 
-      - name: Build frontend-sdl2
+      - name: Build frontend-sdl-cpp
+        env:
+          CMAKE_PREFIX_PATH: "${{ github.workspace }}/install-libprojectm;${{ github.workspace }}/install-poco"
         run: |
-          mkdir cmake-build-frontend-sdl2
-          cmake -G Ninja -S frontend-sdl2 -B cmake-build-frontend-sdl2  \
+          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 frontend-sdl-cpp -B cmake-build-frontend  \
             -DCMAKE_BUILD_TYPE=Release  \
-            "-DCMAKE_PREFIX_PATH=${GITHUB_WORKSPACE}/install-libprojectm;${GITHUB_WORKSPACE}/install-poco"  \
-            "-DCMAKE_INSTALL_PREFIX=${{ github.workspace }}/install-frontend-sdl2"
-          cmake --build cmake-build-frontend-sdl2 --parallel
+            "-DCMAKE_PREFIX_PATH=${CMAKE_PREFIX_PATH}" \
+            "-DCMAKE_INSTALL_PREFIX=${{ github.workspace }}/install-frontend" \
+            -DUSE_SDL=${{ matrix.sdl_version }}
+          cmake --build cmake-build-frontend --parallel
 
       - name: Package projectMSDL
         run: |
-          cd cmake-build-frontend-sdl2
+          cd cmake-build-frontend
           cpack -G DEB
 
       - name: Upload Artifact
         uses: actions/upload-artifact@v6
         with:
-          name: projectMSDL-buildcheck-linux
-          path: cmake-build-frontend-sdl2/*.deb
+          name: projectMSDL-buildcheck-linux-${{ matrix.sdl_version }}
+          path: cmake-build-frontend/*.deb
+
+  build-arch:
+    name: Arch Linux ${{ matrix.sdl_version }}, x86_64
+    runs-on: ubuntu-latest
+    container: archlinux:latest
+    strategy:
+      matrix:
+        sdl_version: [SDL2, SDL3]
+
+    steps:
+      - name: Install Build Dependencies
+        run: |
+          pacman -Syu --noconfirm
+          if [ "${{ matrix.sdl_version }}" = "SDL2" ]; then
+            pacman -S --noconfirm base-devel cmake ninja git poco glew freetype2 sdl2
+          else
+            pacman -S --noconfirm base-devel cmake ninja git poco glew freetype2 sdl3
+          fi
+
+      - name: Checkout libprojectM Sources
+        uses: actions/checkout@v6
+        with:
+          repository: projectM-visualizer/projectm
+          path: projectm
+          submodules: recursive
+
+      - name: Build/Install libprojectM
+        run: |
+          mkdir cmake-build-libprojectm
+          cmake -G Ninja -S projectm -B cmake-build-libprojectm  \
+            -DBUILD_SHARED_LIBS=OFF  \
+            -DCMAKE_BUILD_TYPE=Release  \
+            -DCMAKE_INSTALL_PREFIX=${{ github.workspace }}/install-libprojectm
+          cmake --build cmake-build-libprojectm --parallel
+          cmake --install cmake-build-libprojectm || \
+            cmake --build cmake-build-libprojectm --target install || true
+
+      - name: Checkout frontend-sdl-cpp Sources
+        uses: actions/checkout@v6
+        with:
+          path: frontend-sdl-cpp
+          submodules: recursive
+
+      - name: Build frontend-sdl-cpp
+        run: |
+          mkdir cmake-build-frontend
+          cmake -G Ninja -S frontend-sdl-cpp -B cmake-build-frontend  \
+            -DCMAKE_BUILD_TYPE=Release  \
+            "-DCMAKE_PREFIX_PATH=${{ github.workspace }}/install-libprojectm" \
+            "-DCMAKE_INSTALL_PREFIX=${{ github.workspace }}/install-frontend" \
+            -DUSE_SDL=${{ matrix.sdl_version }}
+          cmake --build cmake-build-frontend --parallel
+
+      - name: Package projectMSDL
+        run: |
+          cd cmake-build-frontend
+          cpack -G TGZ
+
+      - name: Upload Artifact
+        uses: actions/upload-artifact@v6
+        with:
+          name: projectMSDL-buildcheck-arch-${{ matrix.sdl_version }}
+          path: cmake-build-frontend/*.tar.gz
 
   build-windows:
-    name: Windows, x64
-    runs-on: windows-latest
+    name: Windows ${{ matrix.sdl_version }}, x64
+    runs-on: windows-2022
+    strategy:
+      matrix:
+        sdl_version: [SDL2, SDL3]
     env:
       USERNAME: projectM-visualizer
       VCPKG_EXE: ${{ github.workspace }}/vcpkg/vcpkg
       FEED_URL: https://nuget.pkg.github.com/projectM-visualizer/index.json
       VCPKG_BINARY_SOURCES: "clear;nuget,https://nuget.pkg.github.com/projectM-visualizer/index.json,readwrite"
 
-
     steps:
       - name: Checkout vcpkg
         uses: actions/checkout@v6
@@ -143,33 +241,61 @@ jobs:
       - name: Checkout projectMSDL Sources
         uses: actions/checkout@v6
         with:
-          path: frontend-sdl2
+          path: frontend-sdl-cpp
           submodules: recursive
 
       - name: Build projectMSDL
         run: |
-          mkdir cmake-build-frontend-sdl2
-          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 }}
+          cmake --build "${{ github.workspace }}/cmake-build-frontend" --parallel --config Release
 
       - name: Package projectMSDL
         run: |
-          cd cmake-build-frontend-sdl2
+          cd cmake-build-frontend
           cpack -G ZIP
 
       - name: Upload Artifact
         uses: actions/upload-artifact@v6
         with:
-          name: projectMSDL-buildcheck-windows
-          path: cmake-build-frontend-sdl2/*.zip
+          name: projectMSDL-buildcheck-windows-${{ matrix.sdl_version }}
+          path: cmake-build-frontend/*.zip
 
   build-darwin:
-    name: macOS, x86_64
+    name: macOS ${{ matrix.sdl_version }}, x86_64
     runs-on: macos-latest
+    strategy:
+      matrix:
+        sdl_version: [SDL2, SDL3]
 
     steps:
       - name: Install Build Dependencies
-        run: brew install sdl2 ninja googletest poco
+        run: |
+          if [ "${{ matrix.sdl_version }}" = "SDL2" ]; then
+            brew install sdl2 ninja googletest poco
+          else
+            brew install ninja googletest poco
+          fi
+
+      - 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
 
       - name: Checkout libprojectM Sources
         uses: actions/checkout@v6
@@ -188,22 +314,27 @@ jobs:
       - name: Checkout projectMSDL Sources
         uses: actions/checkout@v6
         with:
-          path: frontend-sdl2
+          path: frontend-sdl-cpp
           submodules: recursive
 
       - name: Build projectMSDL
+        env:
+          CMAKE_PREFIX_PATH: "${{ github.workspace }}/install-libprojectm"
         run: |
-          mkdir cmake-build-frontend-sdl2
-          cmake -G Ninja -S "${{ github.workspace }}/frontend-sdl2" -B "${{ github.workspace }}/cmake-build-frontend-sdl2" -DCMAKE_BUILD_TYPE=Release -DCMAKE_PREFIX_PATH="${{ github.workspace }}/install-libprojectm" -DCMAKE_INSTALL_PREFIX="${{ github.workspace }}/install-frontend-sdl2"
-          cmake --build "${{ github.workspace }}/cmake-build-frontend-sdl2" --parallel
+          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
 
       - name: Package projectMSDL
         run: |
-          cd cmake-build-frontend-sdl2
+          cd cmake-build-frontend
           cpack -G TGZ
 
       - name: Upload Artifact
         uses: actions/upload-artifact@v6
         with:
-          name: projectMSDL-buildcheck-macos
-          path: cmake-build-frontend-sdl2/*.tar.gz
+          name: projectMSDL-buildcheck-macos-${{ matrix.sdl_version }}
+          path: cmake-build-frontend/*.tar.gz
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -83,21 +83,60 @@ endif()
 
 set(PACKAGING_CONFIG_FILE "${DEFAULT_PACKAGING_CONFIG}" CACHE FILEPATH "CPack configuration file to use for packaging. This file must \"include(CPack)\" at the end to work properly.")
 
-set(SDL2_LINKAGE "shared" CACHE STRING "Set to either shared or static to specify how libSDL2 should be linked. Defaults to shared.")
-option(ENABLE_FREETYPE "Use the Freetype font rendering library instead of the built-in stb_truetype if available" ON)
+# === SDL version selection ===
+set(USE_SDL "Auto" CACHE STRING "Which SDL version to use: Auto (prefer SDL3, fall back to SDL2), SDL2, or SDL3")
+set_property(CACHE USE_SDL PROPERTY STRINGS "Auto" "SDL2" "SDL3")
 
+option(ENABLE_FREETYPE "Use the Freetype font rendering library instead of the built-in stb_truetype if available" ON)
 
 set(PRESET_DIRS "" CACHE STRING "List of paths with presets. Will be installed in \"presets\" ")
 set(TEXTURE_DIRS "" CACHE STRING "List of paths with presets.")
 
-if(NOT SDL2_LINKAGE STREQUAL "shared" AND NOT SDL2_LINKAGE STREQUAL "static")
-    message(FATAL_ERROR "Invalid libSDL2 linkage provided in SDL2_LINKAGE: \"${SDL2_LINKAGE}\".\n"
-            "Please specify either \"shared\" or \"static\"."
-            )
+find_package(projectM4 REQUIRED COMPONENTS Playlist)
+
+# --- Resolve SDL version ---
+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()
+
+# --- Propagate SDL version to all targets ---
+if(USE_SDL3)
+    add_compile_definitions(USE_SDL3)
 endif()
 
-find_package(projectM4 REQUIRED COMPONENTS Playlist)
-find_package(SDL2 REQUIRED)
 if (NOT ENABLE_GLES)
     find_package(OpenGL REQUIRED)
 else ()
@@ -117,7 +156,6 @@ if(ENABLE_FREETYPE)
     find_package(Freetype)
 endif()
 
-include(SDL2Target)
 include(dependencies_check.cmake)
 include(ImGui.cmake)
 
@@ -133,7 +171,11 @@ if(NOT PACKAGING_CONFIG_FILE STREQUAL "")
     include(${PACKAGING_CONFIG_FILE})
 endif()
 
-message(STATUS "SDL version: ${SDL2_VERSION}")
+if(USE_SDL3)
+    message(STATUS "SDL version: ${SDL3_VERSION} (SDL3)")
+else()
+    message(STATUS "SDL version: ${SDL2_VERSION} (SDL2)")
+endif()
 message(STATUS "Poco version: ${Poco_VERSION}")
 message(STATUS "projectM version: ${projectM4_VERSION}")
 if(Freetype_FOUND)