all: support SDL3 v3.4.0

ci: add libxtst-dev

ci: bump `setup-v` to v1.4

gpu: fix `SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_STENCIL_UINT8` -> `SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_STENCIL_NUMBER`

Author: larpon

.github/workflows/ci.yml

@@ -14,14 +14,14 @@ jobs:
     timeout-minutes: 30
     env:
       VFLAGS: -cc tcc -no-retry-compilation
-      SDL3_VERSION: 3.2.0
+      SDL3_VERSION: 3.4.0
     steps:
       - name: Install dependencies
         run: |
           sudo apt-get update
           sudo apt-get install build-essential git make \
           pkg-config cmake ninja-build gnome-desktop-testing libasound2-dev libpulse-dev \
-          libaudio-dev libjack-dev libsndio-dev libx11-dev libxext-dev \
+          libaudio-dev libjack-dev libsndio-dev libx11-dev libxext-dev libxtst-dev \
           libxrandr-dev libxcursor-dev libxfixes-dev libxi-dev libxss-dev \
           libxkbcommon-dev libdrm-dev libgbm-dev libgl1-mesa-dev libgles2-mesa-dev \
           libegl1-mesa-dev libdbus-1-dev libibus-1.0-dev libudev-dev fcitx-libs-dev \
@@ -37,7 +37,7 @@ jobs:
           sudo cmake --install build
 
       - name: Install V
-        uses: vlang/setup-v@v1
+        uses: vlang/setup-v@v1.4
         with:
           check-latest: true
 
@@ -86,14 +86,14 @@ jobs:
     timeout-minutes: 30
     env:
       VFLAGS: -cc tcc -no-retry-compilation -no-skip-unused
-      SDL3_VERSION: 3.2.0
+      SDL3_VERSION: 3.4.0
     steps:
       - name: Install dependencies
         run: |
           sudo apt-get update
           sudo apt-get install build-essential git make \
           pkg-config cmake ninja-build gnome-desktop-testing libasound2-dev libpulse-dev \
-          libaudio-dev libjack-dev libsndio-dev libx11-dev libxext-dev \
+          libaudio-dev libjack-dev libsndio-dev libx11-dev libxext-dev libxtst-dev \
           libxrandr-dev libxcursor-dev libxfixes-dev libxi-dev libxss-dev \
           libxkbcommon-dev libdrm-dev libgbm-dev libgl1-mesa-dev libgles2-mesa-dev \
           libegl1-mesa-dev libdbus-1-dev libibus-1.0-dev libudev-dev fcitx-libs-dev \
@@ -109,7 +109,7 @@ jobs:
           sudo cmake --install build
 
       - name: Install V
-        uses: vlang/setup-v@v1
+        uses: vlang/setup-v@v1.4
         with:
           check-latest: true
 

README.md

@@ -172,7 +172,7 @@ This will create a directory called "thirdparty" which will be used to download
 extract the required libraries. To successfully run a provided example or your own projects,
 the sdl dlls must be copied to the main application directory. e.g.:
 ```bash
-copy thirdparty\SDL3-3.2.0\lib\x64\SDL3.dll examples\basic_window\
+copy thirdparty\SDL3-3.4.0\lib\x64\SDL3.dll examples\basic_window\
 cd ..
 v run sdl\examples\basic_window\main.v
 ```

atomic.c.v

@@ -380,6 +380,27 @@ pub fn get_atomic_u32(a &AtomicU32) u32 {
 	return C.SDL_GetAtomicU32(a)
 }
 
+// C.SDL_AddAtomicU32 [official documentation](https://wiki.libsdl.org/SDL3/SDL_AddAtomicU32)
+fn C.SDL_AddAtomicU32(a &AtomicU32, v int) u32
+
+// add_atomic_u32 adds to an atomic variable.
+//
+// This function also acts as a full memory barrier.
+//
+// ***NOTE: If you don't know what this function is for, you shouldn't use
+// it!***
+//
+// `a` a a pointer to an SDL_AtomicU32 variable to be modified.
+// `v` v the desired value to add or subtract.
+// returns the previous value of the atomic variable.
+//
+// NOTE: (thread safety) It is safe to call this function from any thread.
+//
+// NOTE: This function is available since SDL 3.4.0.
+pub fn add_atomic_u32(a &AtomicU32, v int) u32 {
+	return C.SDL_AddAtomicU32(a, v)
+}
+
 // C.SDL_CompareAndSwapAtomicPointer [official documentation](https://wiki.libsdl.org/SDL3/SDL_CompareAndSwapAtomicPointer)
 fn C.SDL_CompareAndSwapAtomicPointer(a &voidptr, oldval voidptr, newval voidptr) bool
 

audio.c.v

@@ -529,6 +529,15 @@ fn C.SDL_GetAudioDeviceName(devid AudioDeviceID) &char
 
 // get_audio_device_name gets the human-readable name of a specific audio device.
 //
+// **WARNING**: this function will work with SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK
+// and SDL_AUDIO_DEVICE_DEFAULT_RECORDING, returning the current default
+// physical devices' names. However, as the default device may change at any
+// time, it is likely better to show a generic name to the user, like "System
+// default audio device" or perhaps "default [currently %s]". Do not store
+// this name to disk to reidentify the device in a later run of the program,
+// as the default might change in general, and the string will be the name of
+// a specific device and not the abstract system default.
+//
 // `devid` devid the instance ID of the device to query.
 // returns the name of the audio device, or NULL on failure; call
 //          SDL_GetError() for more information.
@@ -1021,7 +1030,8 @@ fn C.SDL_GetAudioStreamDevice(stream &AudioStream) AudioDeviceID
 
 // get_audio_stream_device querys an audio stream for its currently-bound device.
 //
-// This reports the audio device that an audio stream is currently bound to.
+// This reports the logical audio device that an audio stream is currently
+// bound to.
 //
 // If not bound, or invalid, this returns zero, which is not a valid device
 // ID.
@@ -1069,6 +1079,17 @@ fn C.SDL_GetAudioStreamProperties(stream &AudioStream) PropertiesID
 
 // get_audio_stream_properties gets the properties associated with an audio stream.
 //
+// The application can hang any data it wants here, but the following
+// properties are understood by SDL:
+//
+// - `SDL_PROP_AUDIOSTREAM_AUTO_CLEANUP_BOOLEAN`: if true (the default), the
+//   stream be automatically cleaned up when the audio subsystem quits. If set
+//   to false, the streams will persist beyond that. This property is ignored
+//   for streams created through SDL_OpenAudioDeviceStream(), and will always
+//   be cleaned up. Streams that are not cleaned up will still be unbound from
+//   devices when the audio subsystem quits. This property was added in SDL
+//   3.4.0.
+//
 // `stream` stream the SDL_AudioStream to query.
 // returns a valid property ID on success or 0 on failure; call
 //          SDL_GetError() for more information.
@@ -1080,6 +1101,8 @@ pub fn get_audio_stream_properties(stream &AudioStream) PropertiesID {
 	return C.SDL_GetAudioStreamProperties(stream)
 }
 
+pub const prop_audiostream_auto_cleanup_boolean = &char(C.SDL_PROP_AUDIOSTREAM_AUTO_CLEANUP_BOOLEAN) // 'SDL.audiostream.auto_cleanup'
+
 // C.SDL_GetAudioStreamFormat [official documentation](https://wiki.libsdl.org/SDL3/SDL_GetAudioStreamFormat)
 fn C.SDL_GetAudioStreamFormat(stream &AudioStream, src_spec &AudioSpec, dst_spec &AudioSpec) bool
 
@@ -1167,14 +1190,14 @@ fn C.SDL_SetAudioStreamFrequencyRatio(stream &AudioStream, ratio f32) bool
 //
 // The frequency ratio is used to adjust the rate at which input data is
 // consumed. Changing this effectively modifies the speed and pitch of the
-// audio. A value greater than 1.0 will play the audio faster, and at a higher
-// pitch. A value less than 1.0 will play the audio slower, and at a lower
-// pitch.
+// audio. A value greater than 1.0f will play the audio faster, and at a
+// higher pitch. A value less than 1.0f will play the audio slower, and at a
+// lower pitch. 1.0f means play at normal speed.
 //
 // This is applied during SDL_GetAudioStreamData, and can be continuously
 // changed to create various effects.
 //
-// `stream` stream the stream the frequency ratio is being changed.
+// `stream` stream the stream on which the frequency ratio is being changed.
 // `ratio` ratio the frequency ratio. 1.0 is normal speed. Must be between 0.01
 //              and 100.
 // returns true on success or false on failure; call SDL_GetError() for more
@@ -1351,7 +1374,7 @@ fn C.SDL_SetAudioStreamInputChannelMap(stream &AudioStream, const_chmap &int, co
 // NOTE: (thread safety) It is safe to call this function from any thread, as it holds
 //               a stream-specific mutex while running. Don't change the
 //               stream's format to have a different number of channels from a
-//               a different thread at the same time, though!
+//               different thread at the same time, though!
 //
 // NOTE: This function is available since SDL 3.2.0.
 //
@@ -1368,7 +1391,7 @@ fn C.SDL_SetAudioStreamOutputChannelMap(stream &AudioStream, const_chmap &int, c
 // Channel maps are optional; most things do not need them, instead passing
 // data in the [order that SDL expects](CategoryAudio#channel-layouts).
 //
-// The output channel map reorders data that leaving a stream via
+// The output channel map reorders data that is leaving a stream via
 // SDL_GetAudioStreamData.
 //
 // Each item in the array represents an input channel, and its value is the
@@ -1454,6 +1477,143 @@ pub fn put_audio_stream_data(stream &AudioStream, const_buf voidptr, len int) bo
 	return C.SDL_PutAudioStreamData(stream, const_buf, len)
 }
 
+// AudioStreamDataCompleteCallback as callback that fires for completed SDL_PutAudioStreamDataNoCopy() data.
+//
+// When using SDL_PutAudioStreamDataNoCopy() to provide data to an
+// SDL_AudioStream, it's not safe to dispose of the data until the stream has
+// completely consumed it. Often times it's difficult to know exactly when
+// this has happened.
+//
+// This callback fires once when the stream no longer needs the buffer,
+// allowing the app to easily free or reuse it.
+//
+// `userdata` userdata an opaque pointer provided by the app for their personal
+//                 use.
+// `buf` buf the pointer provided to SDL_PutAudioStreamDataNoCopy().
+// `buflen` buflen the size of buffer, in bytes, provided to
+//               SDL_PutAudioStreamDataNoCopy().
+//
+// NOTE: (thread safety) This callbacks may run from any thread, so if you need to
+//               protect shared data, you should use SDL_LockAudioStream to
+//               serialize access; this lock will be held before your callback
+//               is called, so your callback does not need to manage the lock
+//               explicitly.
+//
+// NOTE: This datatype is available since SDL 3.4.0.
+//
+// See also: set_audio_stream_get_callback (SDL_SetAudioStreamGetCallback)
+// See also: set_audio_stream_put_callback (SDL_SetAudioStreamPutCallback)
+//
+// [Official documentation](https://wiki.libsdl.org/SDL3/SDL_AudioStreamDataCompleteCallback)
+pub type AudioStreamDataCompleteCallback = fn (userdata voidptr, const_buf voidptr, buflen int)
+
+// C.SDL_PutAudioStreamDataNoCopy [official documentation](https://wiki.libsdl.org/SDL3/SDL_PutAudioStreamDataNoCopy)
+fn C.SDL_PutAudioStreamDataNoCopy(stream &AudioStream, const_buf voidptr, len int, callback AudioStreamDataCompleteCallback, userdata voidptr) bool
+
+// put_audio_stream_data_no_copy adds external data to an audio stream without copying it.
+//
+// Unlike SDL_PutAudioStreamData(), this function does not make a copy of the
+// provided data, instead storing the provided pointer. This means that the
+// put operation does not need to allocate and copy the data, but the original
+// data must remain available until the stream is done with it, either by
+// being read from the stream in its entirety, or a call to
+// SDL_ClearAudioStream() or SDL_DestroyAudioStream().
+//
+// The data must match the format/channels/samplerate specified in the latest
+// call to SDL_SetAudioStreamFormat, or the format specified when creating the
+// stream if it hasn't been changed.
+//
+// An optional callback may be provided, which is called when the stream no
+// longer needs the data. Once this callback fires, the stream will not access
+// the data again. This callback will fire for any reason the data is no
+// longer needed, including clearing or destroying the stream.
+//
+// Note that there is still an allocation to store tracking information, so
+// this function is more efficient for larger blocks of data. If you're
+// planning to put a few samples at a time, it will be more efficient to use
+// SDL_PutAudioStreamData(), which allocates and buffers in blocks.
+//
+// `stream` stream the stream the audio data is being added to.
+// `buf` buf a pointer to the audio data to add.
+// `len` len the number of bytes to add to the stream.
+// `callback` callback the callback function to call when the data is no longer
+//                 needed by the stream. May be NULL.
+// `userdata` userdata an opaque pointer provided to the callback for its own
+//                 personal use.
+// returns true on success or false on failure; call SDL_GetError() for more
+//          information.
+//
+// NOTE: (thread safety) It is safe to call this function from any thread, but if the
+//               stream has a callback set, the caller might need to manage
+//               extra locking.
+//
+// NOTE: This function is available since SDL 3.4.0.
+//
+// See also: clear_audio_stream (SDL_ClearAudioStream)
+// See also: flush_audio_stream (SDL_FlushAudioStream)
+// See also: get_audio_stream_data (SDL_GetAudioStreamData)
+// See also: get_audio_stream_queued (SDL_GetAudioStreamQueued)
+pub fn put_audio_stream_data_no_copy(stream &AudioStream, const_buf voidptr, len int, callback AudioStreamDataCompleteCallback, userdata voidptr) bool {
+	return C.SDL_PutAudioStreamDataNoCopy(stream, const_buf, len, callback, userdata)
+}
+
+// C.SDL_PutAudioStreamPlanarData [official documentation](https://wiki.libsdl.org/SDL3/SDL_PutAudioStreamPlanarData)
+fn C.SDL_PutAudioStreamPlanarData(stream &AudioStream, const_channel_buffers voidptr, num_channels int, num_samples int) bool
+
+// put_audio_stream_planar_data adds data to the stream with each channel in a separate array.
+//
+// This data must match the format/channels/samplerate specified in the latest
+// call to SDL_SetAudioStreamFormat, or the format specified when creating the
+// stream if it hasn't been changed.
+//
+// The data will be interleaved and queued. Note that SDL_AudioStream only
+// operates on interleaved data, so this is simply a convenience function for
+// easily queueing data from sources that provide separate arrays. There is no
+// equivalent function to retrieve planar data.
+//
+// The arrays in `channel_buffers` are ordered as they are to be interleaved;
+// the first array will be the first sample in the interleaved data. Any
+// individual array may be NULL; in this case, silence will be interleaved for
+// that channel.
+//
+// `num_channels` specifies how many arrays are in `channel_buffers`. This can
+// be used as a safety to prevent overflow, in case the stream format has
+// changed elsewhere. If more channels are specified than the current input
+// spec, they are ignored. If less channels are specified, the missing arrays
+// are treated as if they are NULL (silence is written to those channels). If
+// the count is -1, SDL will assume the array count matches the current input
+// spec.
+//
+// Note that `num_samples` is the number of _samples per array_. This can also
+// be thought of as the number of _sample frames_ to be queued. A value of 1
+// with stereo arrays will queue two samples to the stream. This is different
+// than SDL_PutAudioStreamData, which wants the size of a single array in
+// bytes.
+//
+// `stream` stream the stream the audio data is being added to.
+// `channel_buffers` channel_buffers a pointer to an array of arrays, one array per
+//                        channel.
+// `num_channels` num_channels the number of arrays in `channel_buffers` or -1.
+// `num_samples` num_samples the number of _samples_ per array to write to the
+//                    stream.
+// returns true on success or false on failure; call SDL_GetError() for more
+//          information.
+//
+// NOTE: (thread safety) It is safe to call this function from any thread, but if the
+//               stream has a callback set, the caller might need to manage
+//               extra locking.
+//
+// NOTE: This function is available since SDL 3.4.0.
+//
+// See also: clear_audio_stream (SDL_ClearAudioStream)
+// See also: flush_audio_stream (SDL_FlushAudioStream)
+// See also: get_audio_stream_data (SDL_GetAudioStreamData)
+// See also: get_audio_stream_queued (SDL_GetAudioStreamQueued)
+pub fn put_audio_stream_planar_data(stream &AudioStream, const_channel_buffers voidptr, num_channels int, num_samples int) bool {
+	return C.SDL_PutAudioStreamPlanarData(stream, const_channel_buffers, num_channels,
+		num_samples)
+}
+
 // C.SDL_GetAudioStreamData [official documentation](https://wiki.libsdl.org/SDL3/SDL_GetAudioStreamData)
 fn C.SDL_GetAudioStreamData(stream &AudioStream, buf voidptr, len int) int
 
@@ -1641,6 +1801,9 @@ fn C.SDL_ResumeAudioStreamDevice(stream &AudioStream) bool
 // previously been paused. Once unpaused, any bound audio streams will begin
 // to progress again, and audio can be generated.
 //
+// SDL_OpenAudioDeviceStream opens audio devices in a paused state, so this
+// function call is required for audio playback to begin on such devices.
+//
 // `stream` stream the audio stream associated with the audio device to resume.
 // returns true on success or false on failure; call SDL_GetError() for more
 //          information.
@@ -1913,7 +2076,7 @@ fn C.SDL_OpenAudioDeviceStream(devid AudioDeviceID, const_spec &AudioSpec, callb
 // Also unlike other functions, the audio device begins paused. This is to map
 // more closely to SDL2-style behavior, since there is no extra step here to
 // bind a stream to begin audio flowing. The audio device should be resumed
-// with `SDL_ResumeAudioStreamDevice(stream);`
+// with SDL_ResumeAudioStreamDevice().
 //
 // This function works with both playback and recording devices.
 //

c/sdl.c.v

@@ -21,12 +21,12 @@ $if !windows {
 }
 
 $if x64 {
-	#flag windows -L @VMODROOT/thirdparty/SDL3-3.2.0/lib/x64
+	#flag windows -L @VMODROOT/thirdparty/SDL3-3.4.0/lib/x64
 } $else {
-	#flag windows -L @VMODROOT/thirdparty/SDL3-3.2.0/lib/x86
+	#flag windows -L @VMODROOT/thirdparty/SDL3-3.4.0/lib/x86
 }
 
-#flag windows -I @VMODROOT/thirdparty/SDL3-3.2.0/include
+#flag windows -I @VMODROOT/thirdparty/SDL3-3.4.0/include
 #flag windows -lSDL3
 
 // NOTE::