projectM-visualizer · doncollins1985 · Jul 21, 2026 · Sep 5, 2026 · Sep 5, 2026 · Sep 5, 2026
diff --git a/.github/workflows/buildcheck.yaml b/.github/workflows/buildcheck.yaml
@@ -1,21 +1,32 @@
 # 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
-    runs-on: ubuntu-latest
+    name: Ubuntu ${{ matrix.os }} ${{ matrix.sdl_version }}, x86_64
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        include:
+          - os: ubuntu-24.04
+            sdl_version: SDL2
+          - os: ubuntu-26.04
+            sdl_version: 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 libsdl3-dev libpoco-dev ninja-build libssl-dev libfreetype6-dev
+          fi
 
       # 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 +75,110 @@ 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  \
+          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
+    name: Windows ${{ matrix.sdl_version }}, x64
     runs-on: windows-latest
+    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 +222,42 @@ 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 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 }}
+          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 sdl3 ninja googletest poco
+          fi
+
 
       - name: Checkout libprojectM Sources
         uses: actions/checkout@v6
@@ -188,22 +276,24 @@ 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
+          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
@@ -6,6 +6,21 @@ set(CMAKE_POSITION_INDEPENDENT_CODE YES)
 
 set_property(GLOBAL PROPERTY USE_FOLDERS ON)
 
+# === SDL version selection ===
+# Declared before project() so that the vcpkg toolchain can enable the matching
+# manifest feature when building in manifest mode.
+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")
+
+# Select the vcpkg manifest feature matching the requested SDL version. This only
+# has an effect when building in vcpkg manifest mode. Auto prefers SDL3 so that
+# vcpkg installs libSDL3 instead of libSDL2.
+if(USE_SDL STREQUAL "SDL2")
+    set(VCPKG_MANIFEST_FEATURES "sdl2")
+else()
+    set(VCPKG_MANIFEST_FEATURES "sdl3")
+endif()
+
 project(projectMSDL
         LANGUAGES C CXX
         VERSION 2.0.0
@@ -83,21 +98,48 @@ 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)
 
-
 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_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)
+
+# --- 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 +159,6 @@ if(ENABLE_FREETYPE)
     find_package(Freetype)
 endif()
 
-include(SDL2Target)
 include(dependencies_check.cmake)
 include(ImGui.cmake)
 
@@ -133,7 +174,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)