Finish SDL3 port of API

All known issues with the API resolved and tests pass

Author: HexDecimal

.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,6 +320,7 @@
         "numpy",
         "ogrid",
         "ogrids",
+        "oldnames",
         "onefile",
         "OPENGL",
         "opensearch",
@@ -366,6 +372,7 @@
         "repr",
         "rgba",
         "RGUI",
+        "RHYPER",
         "RIGHTBRACE",
         "RIGHTBRACKET",
         "RIGHTDOWN",
@@ -407,6 +414,8 @@
         "SIZEWE",
         "SMILIE",
         "snprintf",
+        "SOFTLEFT",
+        "SOFTRIGHT",
         "soundfile",
         "sourcelink",
         "sphinxstrong",
@@ -445,6 +454,7 @@
         "typestr",
         "undoc",
         "Unifont",
+        "UNISTD",
         "unraisable",
         "unraisablehook",
         "unraiseable",

CHANGELOG.md

@@ -16,13 +16,31 @@ This project adheres to [Semantic Versioning](https://semver.org/) since version
 - `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
 

build_sdl.py

@@ -48,7 +48,6 @@
 
 # These structs have an unusual size when packed by SDL on 32-bit platforms.
 FLEXIBLE_STRUCTS = (
-    "SDL_AudioCVT",
     "SDL_TouchFingerEvent",
     "SDL_MultiGestureEvent",
     "SDL_DollarGestureEvent",
@@ -237,7 +236,7 @@ def on_directive_handle(
 
 extern "Python" {
 // SDL_AudioCallback callback.
-void _sdl_audio_callback(void* userdata, uint8_t* stream, int len);
+void _sdl_audio_stream_callback(void* userdata, SDL_AudioStream *stream, int additional_amount, int total_amount);
 // SDL to Python log function.
 void _sdl_log_output_function(void *userdata, int category, SDL_LogPriority priority, const char *message);
 // Generic event watcher callback.

examples/audio_tone.py

@@ -1,17 +1,15 @@
 #!/usr/bin/env python
-"""Shows how to use tcod.sdl.audio to play a custom-made audio stream.
+"""Shows how to use tcod.sdl.audio to play audio.
 
-Opens an audio device using SDL and plays a square wave for 1 second.
+Opens an audio device using SDL then plays tones using various methods.
 """
 
 import math
 import time
-from typing import Any
 
 import attrs
 import numpy as np
-from numpy.typing import NDArray
-from scipy import signal  # type: ignore
+from scipy import signal  # type: ignore[import-untyped]
 
 import tcod.sdl.audio
 
@@ -22,28 +20,56 @@
 class PullWave:
     """Square wave stream generator for an SDL audio device in pull mode."""
 
+    frequency: float
     time: float = 0.0
 
-    def __call__(self, device: tcod.sdl.audio.AudioDevice, stream: NDArray[Any]) -> None:
+    def __call__(self, stream: tcod.sdl.audio.AudioStream, request: tcod.sdl.audio.AudioStreamCallbackData) -> None:
         """Stream a square wave to SDL on demand.
 
         This function must run faster than the stream duration.
         Numpy is used to keep performance within these limits.
         """
-        sample_rate = device.frequency
-        n_samples = device.buffer_samples
-        duration = n_samples / sample_rate
-        print(f"{duration=} {self.time=}")
+        duration = request.additional_samples / self.frequency
 
-        t = np.linspace(self.time, self.time + duration, n_samples, endpoint=False)
+        t = np.linspace(self.time, self.time + duration, request.additional_samples, endpoint=False)
         self.time += duration
         wave = signal.square(t * (math.tau * 440)).astype(np.float32)
-        wave *= VOLUME
-
-        stream[:] = device.convert(wave)
+        stream.queue_audio(wave)
 
 
 if __name__ == "__main__":
-    with tcod.sdl.audio.open(callback=PullWave()) as device:
-        print(device)
-        time.sleep(1)
+    device = tcod.sdl.audio.get_default_playback().open(channels=1, frequency=44100)
+    print(f"{device.name=}")
+    device.gain = VOLUME
+    print(device)
+
+    print("Sawtooth wave queued with AudioStream.queue_audio")
+    stream = device.new_stream(format=np.float32, channels=1, frequency=44100)
+    t = np.linspace(0, 1.0, 44100, endpoint=False)
+    wave = signal.sawtooth(t * (math.tau * 440)).astype(np.float32)
+    stream.queue_audio(wave)
+    stream.flush()
+    while stream.queued_samples:
+        time.sleep(0.01)
+
+    print("---")
+    time.sleep(0.5)
+
+    print("Square wave attached to AudioStream.getter_callback")
+    stream = device.new_stream(format=np.float32, channels=1, frequency=44100)
+    stream.getter_callback = PullWave(device.frequency)
+
+    time.sleep(1)
+    stream.getter_callback = None
+
+    print("---")
+    time.sleep(0.5)
+
+    print("Sawtooth wave played with BasicMixer.play")
+    mixer = tcod.sdl.audio.BasicMixer(device, frequency=44100, channels=2)
+    channel = mixer.play(wave)
+    while channel.busy:
+        time.sleep(0.01)
+
+    print("---")
+    device.close()

examples/samples_tcod.py

@@ -757,8 +757,8 @@ def ev_mousemotion(self, event: tcod.event.MouseMotion) -> None:
         mx = event.tile.x - SAMPLE_SCREEN_X
         my = event.tile.y - SAMPLE_SCREEN_Y
         if 0 <= mx < SAMPLE_SCREEN_WIDTH and 0 <= my < SAMPLE_SCREEN_HEIGHT:
-            self.dest_x = mx
-            self.dest_y = my
+            self.dest_x = int(mx)
+            self.dest_y = int(my)
 
 
 #############################################
@@ -1028,9 +1028,9 @@ def on_draw(self) -> None:
         sample_console.print(
             1,
             1,
-            f"Pixel position : {self.motion.position.x:4d}x{self.motion.position.y:4d}\n"
-            f"Tile position  : {self.motion.tile.x:4d}x{self.motion.tile.y:4d}\n"
-            f"Tile movement  : {self.motion.tile_motion.x:4d}x{self.motion.tile_motion.y:4d}\n"
+            f"Pixel position : {self.motion.position.x:4.0f}x{self.motion.position.y:4.0f}\n"
+            f"Tile position  : {self.motion.tile.x:4.0f}x{self.motion.tile.y:4.0f}\n"
+            f"Tile movement  : {self.motion.tile_motion.x:4.0f}x{self.motion.tile_motion.y:4.0f}\n"
             f"Left button    : {'ON' if self.mouse_left else 'OFF'}\n"
             f"Right button   : {'ON' if self.mouse_right else 'OFF'}\n"
             f"Middle button  : {'ON' if self.mouse_middle else 'OFF'}\n",

tcod/_libtcod.pyi

@@ -7717,8 +7717,8 @@ class _lib:
         """void _pycall_sdl_hook(struct SDL_Surface *)"""
 
     @staticmethod
-    def _sdl_audio_callback(userdata: Any, stream: Any, len: int, /) -> None:
-        """void _sdl_audio_callback(void *userdata, uint8_t *stream, int len)"""
+    def _sdl_audio_stream_callback(userdata: Any, stream: Any, additional_amount: int, total_amount: int, /) -> None:
+        """void _sdl_audio_stream_callback(void *userdata, SDL_AudioStream *stream, int additional_amount, int total_amount)"""
 
     @staticmethod
     def _sdl_event_watcher(userdata: Any, event: Any, /) -> int:

tcod/context.py

@@ -220,13 +220,14 @@ def present(
         )
         _check(lib.TCOD_context_present(self._p, console.console_c, viewport_args))
 
-    def pixel_to_tile(self, x: int, y: int) -> tuple[int, int]:
+    def pixel_to_tile(self, x: float, y: float) -> tuple[float, float]:
         """Convert window pixel coordinates to tile coordinates."""
-        with ffi.new("int[2]", (x, y)) as xy:
-            _check(lib.TCOD_context_screen_pixel_to_tile_i(self._p, xy, xy + 1))
+        with ffi.new("double[2]", (x, y)) as xy:
+            _check(lib.TCOD_context_screen_pixel_to_tile_d(self._p, xy, xy + 1))
             return xy[0], xy[1]
 
-    def pixel_to_subtile(self, x: int, y: int) -> tuple[float, float]:
+    @deprecated("Use pixel_to_tile method instead.")
+    def pixel_to_subtile(self, x: float, y: float) -> tuple[float, float]:
         """Convert window pixel coordinates to sub-tile coordinates."""
         with ffi.new("double[2]", (x, y)) as xy:
             _check(lib.TCOD_context_screen_pixel_to_tile_d(self._p, xy, xy + 1))
@@ -262,7 +263,7 @@ def convert_event(self, event: _Event) -> _Event:
                 event.position[1] - event.motion[1],
             )
             event_copy.motion = event._tile_motion = tcod.event.Point(
-                event._tile[0] - prev_tile[0], event._tile[1] - prev_tile[1]
+                int(event._tile[0]) - int(prev_tile[0]), int(event._tile[1]) - int(prev_tile[1])
             )
         return event_copy