Upgrade to use SDL3 version of libtcod

Reconfigure CFFI porting scripts for SDL3, add _libtcod.pyi

Many SDL functions were renamed and I'd have to port them blind without
this new `_libtcod.py` file.

Update type ignores for newest Numpy

Enable more strict Mypy settings

SDL_CommonEvent and others needed to be marked as packed/flexible

Remove outdated Sphinx directives

Check if audio devices work before testing them

Update Linux wheel build workflows for SDL3

Author: HexDecimal

.github/workflows/python-package.yml

@@ -44,10 +44,11 @@ jobs:
   sdist:
     runs-on: ubuntu-latest
     steps:
-      - name: APT update
-        run: sudo apt-get update
-      - name: Install APT dependencies
-        run: sudo apt-get install libsdl2-dev
+      - uses: libsdl-org/setup-sdl@6574e20ac65ce362cd12f9c26b3a5e4d3cd31dee
+        with:
+          install-linux-dependencies: true
+          build-type: "Debug"
+          version: "3.2.14"
       - uses: actions/checkout@v4
         with:
           fetch-depth: ${{ env.git-depth }}
@@ -71,7 +72,7 @@ jobs:
     strategy:
       matrix:
         os: ["windows-latest", "macos-latest"]
-        sdl-version: ["2.0.14", "2.0.16", "2.30.0"]
+        sdl-version: ["3.2.10"]
       fail-fast: true
     steps:
       - uses: actions/checkout@v4
@@ -90,7 +91,7 @@ jobs:
           SDL_VERSION: ${{ matrix.sdl-version }}
 
   build:
-    needs: [ruff, mypy]
+    needs: [ruff, mypy, sdist]
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
@@ -122,7 +123,13 @@ jobs:
         if: runner.os == 'Linux'
         run: |
           sudo apt-get update
-          sudo apt-get install libsdl2-dev xvfb
+          sudo apt-get install xvfb
+      - uses: libsdl-org/setup-sdl@6574e20ac65ce362cd12f9c26b3a5e4d3cd31dee
+        if: runner.os == 'Linux'
+        with:
+          install-linux-dependencies: true
+          build-type: "Release"
+          version: "3.2.14"
       - name: Install Python dependencies
         run: |
           python -m pip install --upgrade pip
@@ -157,13 +164,15 @@ jobs:
           compression-level: 0
 
   test-docs:
-    needs: [ruff, mypy]
+    needs: [ruff, mypy, sdist]
     runs-on: ubuntu-latest
     steps:
-      - name: Install APT dependencies
-        run: |
-          sudo apt-get update
-          sudo apt-get install libsdl2-dev
+      - uses: libsdl-org/setup-sdl@6574e20ac65ce362cd12f9c26b3a5e4d3cd31dee
+        if: runner.os == 'Linux'
+        with:
+          install-linux-dependencies: true
+          build-type: "Debug"
+          version: "3.2.14"
       - uses: actions/checkout@v4
         with:
           fetch-depth: ${{ env.git-depth }}
@@ -182,11 +191,11 @@ jobs:
         run: python -m sphinx -T -E -W --keep-going . _build/html
 
   tox:
-    needs: [ruff]
+    needs: [ruff, sdist]
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        os: ["ubuntu-latest", "windows-latest"]
+        os: ["ubuntu-latest"] # "windows-latest" disabled due to free-threaded build issues
     steps:
       - uses: actions/checkout@v4
         with:
@@ -200,17 +209,18 @@ jobs:
       - name: Install Python dependencies
         run: |
           python -m pip install --upgrade pip tox
-      - name: Install APT dependencies
+      - uses: libsdl-org/setup-sdl@6574e20ac65ce362cd12f9c26b3a5e4d3cd31dee
         if: runner.os == 'Linux'
-        run: |
-          sudo apt-get update
-          sudo apt-get install libsdl2-dev
+        with:
+          install-linux-dependencies: true
+          build-type: "Debug"
+          version: "3.2.14"
       - name: Run tox
         run: |
           tox -vv
 
   linux-wheels:
-    needs: [ruff, mypy]
+    needs: [ruff, mypy, sdist]
     runs-on: ${{ matrix.arch == 'aarch64' && 'ubuntu-24.04-arm' || 'ubuntu-latest'}}
     strategy:
       matrix:
@@ -248,7 +258,19 @@ jobs:
           CIBW_BEFORE_ALL_LINUX: >
             yum install -y epel-release &&
             yum-config-manager --enable epel &&
-            yum install -y SDL2-devel
+            yum install -y gcc git-core make cmake \
+                alsa-lib-devel pulseaudio-libs-devel \
+                libX11-devel libXext-devel libXrandr-devel libXcursor-devel libXfixes-devel \
+                libXi-devel libXScrnSaver-devel dbus-devel ibus-devel \
+                systemd-devel mesa-libGL-devel libxkbcommon-devel mesa-libGLES-devel \
+                mesa-libEGL-devel vulkan-devel wayland-devel wayland-protocols-devel \
+                libdrm-devel mesa-libgbm-devel libusb-devel
+            git clone --depth 1 --branch release-3.2.10 https://github.com/libsdl-org/SDL.git sdl_repo &&
+            cmake -S sdl_repo -B sdl_build &&
+            cmake --build sdl_build --config Release &&
+            cmake --install sdl_build --config Release --prefix /usr/local &&
+            cp --verbose /usr/local/lib64/pkgconfig/sdl3.pc /lib64/pkgconfig/sdl3.pc
+          PKG_CONFIG_PATH: "/usr/local/lib64/pkgconfig"
           CIBW_BEFORE_TEST: pip install numpy
           CIBW_TEST_COMMAND: python -c "import tcod.context"
           # Skip test on emulated architectures
@@ -267,7 +289,7 @@ jobs:
           compression-level: 0
 
   build-macos:
-    needs: [ruff, mypy]
+    needs: [ruff, mypy, sdist]
     runs-on: "macos-14"
     strategy:
       fail-fast: true
@@ -287,7 +309,7 @@ jobs:
       - name: Install Python dependencies
         run: pip install -r requirements.txt
       - name: Prepare package
-        # Downloads SDL2 for the later step.
+        # Downloads SDL for the later step.
         run: python build_sdl.py
       - name: Build wheels
         uses: pypa/[email protected]
@@ -298,7 +320,7 @@ jobs:
           CIBW_BEFORE_TEST: pip install numpy
           CIBW_TEST_COMMAND: python -c "import tcod.context"
           CIBW_TEST_SKIP: "pp* *-macosx_arm64 *-macosx_universal2:arm64"
-          MACOSX_DEPLOYMENT_TARGET: "10.11"
+          MACOSX_DEPLOYMENT_TARGET: "10.13"
       - name: Remove asterisk from label
         run: |
           PYTHON_DESC=${{ matrix.python }}

.gitignore

@@ -69,10 +69,10 @@ Release/
 tcod/_*.c
 tcod/_*.pyd
 .benchmarks
-dependencies/SDL2*
+dependencies/SDL*
 tcod/x86
 tcod/x64
-tcod/SDL2.framework
+tcod/SDL?.framework
 deb_dist/
 *.tar.gz
 tcod/version.py

.readthedocs.yaml

@@ -5,11 +5,11 @@
 version: 2
 
 build:
-  os: ubuntu-22.04
+  os: ubuntu-24.04
   tools:
     python: "3.11"
   apt_packages:
-    - libsdl2-dev
+    - libsdl3-dev
 
 submodules:
   include: all

.vscode/settings.json

@@ -96,6 +96,7 @@
         "condlist",
         "consolas",
         "contextdata",
+        "contextlib",
         "CONTROLLERAXISMOTION",
         "CONTROLLERBUTTONDOWN",
         "CONTROLLERBUTTONUP",
@@ -112,6 +113,7 @@
         "dataclasses",
         "datas",
         "DBLAMPERSAND",
+        "DBLAPOSTROPHE",
         "DBLVERTICALBAR",
         "dcost",
         "DCROSS",
@@ -139,6 +141,7 @@
         "dunder",
         "DVLINE",
         "elif",
+        "ENDCALL",
         "endianness",
         "epel",
         "epub",
@@ -250,6 +253,7 @@
         "lerp",
         "letterpaper",
         "LGUI",
+        "LHYPER",
         "libsdl",
         "libtcod",
         "libtcodpy",
@@ -305,6 +309,7 @@
         "neww",
         "noarchive",
         "NODISCARD",
+        "NOMESSAGE",
         "Nonrepresentable",
         "NONUSBACKSLASH",
         "NONUSHASH",
@@ -315,10 +320,12 @@
         "numpy",
         "ogrid",
         "ogrids",
+        "oldnames",
         "onefile",
         "OPENGL",
         "opensearch",
         "OPER",
+        "OVERSCAN",
         "packbits",
         "PAGEDOWN",
         "pagerefs",
@@ -365,6 +372,7 @@
         "repr",
         "rgba",
         "RGUI",
+        "RHYPER",
         "RIGHTBRACE",
         "RIGHTBRACKET",
         "RIGHTDOWN",
@@ -406,6 +414,8 @@
         "SIZEWE",
         "SMILIE",
         "snprintf",
+        "SOFTLEFT",
+        "SOFTRIGHT",
         "soundfile",
         "sourcelink",
         "sphinxstrong",
@@ -444,6 +454,7 @@
         "typestr",
         "undoc",
         "Unifont",
+        "UNISTD",
         "unraisable",
         "unraisablehook",
         "unraiseable",

CHANGELOG.md

@@ -6,9 +6,45 @@ This project adheres to [Semantic Versioning](https://semver.org/) since version
 
 ## [Unreleased]
 
+### Changed
+
+- Switched to SDL3.
+  This will cause several breaking changes such as the names of keyboard constants and other SDL enums.
+- `tcod.sdl.video.Window.grab` has been split into `.mouse_grab` and `.keyboard_grab` attributes.
+- `tcod.event.KeySym` single letter symbols are now all uppercase.
+- Relative mouse mode is set via `tcod.sdl.video.Window.relative_mouse_mode` instead of `tcod.sdl.mouse.set_relative_mode`.
+- `tcod.sdl.render.new_renderer`: Removed `software` and `target_textures` parameters, `vsync` takes `int`, `driver` takes `str` instead of `int`.
+- SDL renderer logical
+- `tcod.sdl.render.Renderer`: `integer_scaling` and `logical_size` are now set with `set_logical_presentation` method.
+- `tcod.sdl.render.Renderer.geometry` now takes float values for `color` instead of 8-bit integers.
+- `tcod.event.Point` and other mouse/tile coordinate types now use `float` instead of `int`.
+  SDL3 has decided that mouse events have subpixel precision.
+  If you see any usual `float` types in your code then this is why.
+- `tcod.sdl.audio` has been affected by major changes to SDL3.
+  - `tcod.sdl.audio.open` has new behavior due to SDL3 and should be avoided.
+  - Callbacks which were assigned to `AudioDevice`'s must now be applied to `AudioStream`'s instead.
+  - `AudioDevice`'s are now opened using references to existing devices.
+  - Sound queueing methods were moved from `AudioDevice` to a new `AudioStream` class.
+  - `BasicMixer` may require manually specifying `frequency` and `channels` to replicate old behavior.
+  - `get_devices` and `get_capture_devices` now return `dict[str, AudioDevice]`.
+
+### Deprecated
+
+- `tcod.sdl.audio.open` was replaced with a newer API, get a default device with `tcod.sdl.audio.get_default_playback().open()`.
+- `tcod.sdl.audio.BasicMixer` should be replaced with `AudioStream`'s.
+- Should no longer use `tcod.sdl.audio.AudioDevice` in a context, use `contextlib.closing` for the old behavior.
+
 ### Removed
 
 - Support dropped for Python 3.8 and 3.9.
+- Removed `Joystick.get_current_power` due to SDL3 changes.
+- `WindowFlags.FULLSCREEN_DESKTOP` is now just `WindowFlags.FULLSCREEN`
+- `tcod.sdl.render.Renderer.integer_scaling` removed.
+- Removed `callback`, `spec`, `queued_samples`, `queue_audio`, and `dequeue_audio` attributes from `tcod.sdl.audio.AudioDevice`.
+
+### Fixed
+
+- `Joystick.get_ball` was broken.
 
 ## [18.1.0] - 2025-05-05
 

README.rst

@@ -48,7 +48,7 @@ For the most part it's just::
 ==============
 * Python 3.10+
 * Windows, Linux, or MacOS X 10.9+.
-* On Linux, requires libsdl2 (2.0.10+).
+* On Linux, requires libsdl3 (3.2.0+).
 
 ===========
  Changelog