[Breaking] Update SDL3 headers and bindings to 3.2.26

Author: hazeycode

libs/sdl3/include/SDL3/SDL.h

@@ -20,7 +20,7 @@
 */
 
 /**
- * Main include header for the SDL library, version 3.2.0
+ * Main include header for the SDL library, version 3.2.26
  *
  * It is almost always best to include just this one header instead of
  * picking out individual headers included here. There are exceptions to

libs/sdl3/include/SDL3/SDL_assert.h

@@ -126,7 +126,7 @@ extern "C" {
  */
 #define SDL_TriggerBreakpoint() TriggerABreakpointInAPlatformSpecificManner
 
-#elif defined(_MSC_VER) && _MSC_VER >= 1310
+#elif defined(__MINGW32__) || (defined(_MSC_VER) && _MSC_VER >= 1310)
     /* Don't include intrin.h here because it contains C++ code */
     extern void __cdecl __debugbreak(void);
     #define SDL_TriggerBreakpoint() __debugbreak()
@@ -149,6 +149,8 @@ extern "C" {
     #define SDL_TriggerBreakpoint() __asm__ __volatile__ ( "bkpt #22\n\t" )
 #elif defined(_WIN32) && ((defined(__GNUC__) || defined(__clang__)) && (defined(__arm64__) || defined(__aarch64__)) )
     #define SDL_TriggerBreakpoint() __asm__ __volatile__ ( "brk #0xF000\n\t" )
+#elif defined(__GNUC__) || defined(__clang__)
+    #define SDL_TriggerBreakpoint() __builtin_trap()  /* older gcc may not support SDL_HAS_BUILTIN(__builtin_trap) above */
 #elif defined(__386__) && defined(__WATCOMC__)
     #define SDL_TriggerBreakpoint() { _asm { int 0x03 } }
 #elif defined(HAVE_SIGNAL_H) && !defined(__WATCOMC__)
@@ -360,7 +362,7 @@ extern SDL_DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData *
 #define SDL_enabled_assert(condition) \
     do { \
         while ( !(condition) ) { \
-            static struct SDL_AssertData sdl_assert_data = { 0, 0, #condition, 0, 0, 0, 0 }; \
+            static struct SDL_AssertData sdl_assert_data = { false, 0, #condition, NULL, 0, NULL, NULL }; \
             const SDL_AssertState sdl_assert_state = SDL_ReportAssertion(&sdl_assert_data, SDL_FUNCTION, SDL_FILE, SDL_LINE); \
             if (sdl_assert_state == SDL_ASSERTION_RETRY) { \
                 continue; /* go again. */ \

libs/sdl3/include/SDL3/SDL_atomic.h

@@ -498,7 +498,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_AddAtomicInt(SDL_AtomicInt *a, int v);
  *
  * ***Note: If you don't know what this macro is for, you shouldn't use it!***
  *
- * \param a a pointer to an SDL_AtomicInt to increment.
+ * \param a a pointer to an SDL_AtomicInt to decrement.
  * \returns true if the variable reached zero after decrementing, false
  *          otherwise.
  *

libs/sdl3/include/SDL3/SDL_audio.h

@@ -781,7 +781,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_IsAudioDevicePlayback(SDL_AudioDeviceID dev
  * Physical devices can not be paused or unpaused, only logical devices
  * created through SDL_OpenAudioDevice() can be.
  *
- * \param dev a device opened by SDL_OpenAudioDevice().
+ * \param devid a device opened by SDL_OpenAudioDevice().
  * \returns true on success or false on failure; call SDL_GetError() for more
  *          information.
  *
@@ -792,7 +792,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_IsAudioDevicePlayback(SDL_AudioDeviceID dev
  * \sa SDL_ResumeAudioDevice
  * \sa SDL_AudioDevicePaused
  */
-extern SDL_DECLSPEC bool SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID dev);
+extern SDL_DECLSPEC bool SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID devid);
 
 /**
  * Use this function to unpause audio playback on a specified device.
@@ -809,7 +809,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID dev);
  * Physical devices can not be paused or unpaused, only logical devices
  * created through SDL_OpenAudioDevice() can be.
  *
- * \param dev a device opened by SDL_OpenAudioDevice().
+ * \param devid a device opened by SDL_OpenAudioDevice().
  * \returns true on success or false on failure; call SDL_GetError() for more
  *          information.
  *
@@ -820,7 +820,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID dev);
  * \sa SDL_AudioDevicePaused
  * \sa SDL_PauseAudioDevice
  */
-extern SDL_DECLSPEC bool SDLCALL SDL_ResumeAudioDevice(SDL_AudioDeviceID dev);
+extern SDL_DECLSPEC bool SDLCALL SDL_ResumeAudioDevice(SDL_AudioDeviceID devid);
 
 /**
  * Use this function to query if an audio device is paused.
@@ -832,7 +832,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_ResumeAudioDevice(SDL_AudioDeviceID dev);
  * created through SDL_OpenAudioDevice() can be. Physical and invalid device
  * IDs will report themselves as unpaused here.
  *
- * \param dev a device opened by SDL_OpenAudioDevice().
+ * \param devid a device opened by SDL_OpenAudioDevice().
  * \returns true if device is valid and paused, false otherwise.
  *
  * \threadsafety It is safe to call this function from any thread.
@@ -842,7 +842,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_ResumeAudioDevice(SDL_AudioDeviceID dev);
  * \sa SDL_PauseAudioDevice
  * \sa SDL_ResumeAudioDevice
  */
-extern SDL_DECLSPEC bool SDLCALL SDL_AudioDevicePaused(SDL_AudioDeviceID dev);
+extern SDL_DECLSPEC bool SDLCALL SDL_AudioDevicePaused(SDL_AudioDeviceID devid);
 
 /**
  * Get the gain of an audio device.
@@ -942,7 +942,10 @@ extern SDL_DECLSPEC void SDLCALL SDL_CloseAudioDevice(SDL_AudioDeviceID devid);
  * Binding a stream to a device will set its output format for playback
  * devices, and its input format for recording devices, so they match the
  * device's settings. The caller is welcome to change the other end of the
- * stream's format at any time with SDL_SetAudioStreamFormat().
+ * stream's format at any time with SDL_SetAudioStreamFormat(). If the other
+ * end of the stream's format has never been set (the audio stream was created
+ * with a NULL audio spec), this function will set it to match the device
+ * end's format.
  *
  * \param devid an audio device to bind a stream to.
  * \param streams an array of audio streams to bind.
@@ -1021,7 +1024,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnbindAudioStream(SDL_AudioStream *stream);
 /**
  * Query 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.
@@ -1583,6 +1586,9 @@ extern SDL_DECLSPEC bool SDLCALL SDL_PauseAudioStreamDevice(SDL_AudioStream *str
  * previously been paused. Once unpaused, any bound audio streams will begin
  * to progress again, and audio can be generated.
  *
+ * Remember, SDL_OpenAudioDeviceStream opens device in a paused state, so this
+ * function call is required for audio playback to begin on such device.
+ *
  * \param 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.
@@ -1714,7 +1720,7 @@ typedef void (SDLCALL *SDL_AudioStreamCallback)(void *userdata, SDL_AudioStream
  * audio to the stream during this call; if needed, the request that triggered
  * this callback will obtain the new data immediately.
  *
- * The callback's `approx_request` argument is roughly how many bytes of
+ * The callback's `additional_amount` argument is roughly how many bytes of
  * _unconverted_ data (in the stream's input format) is needed by the caller,
  * although this may overestimate a little for safety. This takes into account
  * how much is already in the stream and only asks for any extra necessary to
@@ -1759,13 +1765,13 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamGetCallback(SDL_AudioStream *
  * The callback can (optionally) call SDL_GetAudioStreamData() to obtain audio
  * from the stream during this call.
  *
- * The callback's `approx_request` argument is how many bytes of _converted_
- * data (in the stream's output format) was provided by the caller, although
- * this may underestimate a little for safety. This value might be less than
- * what is currently available in the stream, if data was already there, and
- * might be less than the caller provided if the stream needs to keep a buffer
- * to aid in resampling. Which means the callback may be provided with zero
- * bytes, and a different amount on each call.
+ * The callback's `additional_amount` argument is how many bytes of
+ * _converted_ data (in the stream's output format) was provided by the
+ * caller, although this may underestimate a little for safety. This value
+ * might be less than what is currently available in the stream, if data was
+ * already there, and might be less than the caller provided if the stream
+ * needs to keep a buffer to aid in resampling. Which means the callback may
+ * be provided with zero bytes, and a different amount on each call.
  *
  * The callback may call SDL_GetAudioStreamAvailable to see the total amount
  * currently available to read from the stream, instead of the total provided

libs/sdl3/include/SDL3/SDL_camera.h

@@ -119,7 +119,7 @@ typedef struct SDL_CameraSpec
     int width;                  /**< Frame width */
     int height;                 /**< Frame height */
     int framerate_numerator;     /**< Frame rate numerator ((num / denom) == FPS, (denom / num) == duration in seconds) */
-    int framerate_denominator;   /**< Frame rate demoninator ((num / denom) == FPS, (denom / num) == duration in seconds) */
+    int framerate_denominator;   /**< Frame rate denominator ((num / denom) == FPS, (denom / num) == duration in seconds) */
 } SDL_CameraSpec;
 
 /**
@@ -239,7 +239,7 @@ extern SDL_DECLSPEC SDL_CameraID * SDLCALL SDL_GetCameras(int *count);
  * there _is_ a camera until the user has given you permission to check
  * through a scary warning popup.
  *
- * \param devid the camera device instance ID to query.
+ * \param instance_id the camera device instance ID.
  * \param count a pointer filled in with the number of elements in the list,
  *              may be NULL.
  * \returns a NULL terminated array of pointers to SDL_CameraSpec or NULL on
@@ -254,7 +254,7 @@ extern SDL_DECLSPEC SDL_CameraID * SDLCALL SDL_GetCameras(int *count);
  * \sa SDL_GetCameras
  * \sa SDL_OpenCamera
  */
-extern SDL_DECLSPEC SDL_CameraSpec ** SDLCALL SDL_GetCameraSupportedFormats(SDL_CameraID devid, int *count);
+extern SDL_DECLSPEC SDL_CameraSpec ** SDLCALL SDL_GetCameraSupportedFormats(SDL_CameraID instance_id, int *count);
 
 /**
  * Get the human-readable device name for a camera.

libs/sdl3/include/SDL3/SDL_clipboard.h

@@ -106,7 +106,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetClipboardText(const char *text);
 /**
  * Get UTF-8 text from the clipboard.
  *
- * This functions returns an empty string if there was not enough memory left
+ * This function returns an empty string if there is not enough memory left
  * for a copy of the clipboard's content.
  *
  * \returns the clipboard text on success or an empty string on failure; call
@@ -155,7 +155,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetPrimarySelectionText(const char *text);
 /**
  * Get UTF-8 text from the primary selection.
  *
- * This functions returns an empty string if there was not enough memory left
+ * This function returns an empty string if there is not enough memory left
  * for a copy of the primary selection's content.
  *
  * \returns the primary selection text on success or an empty string on
@@ -194,15 +194,14 @@ extern SDL_DECLSPEC bool SDLCALL SDL_HasPrimarySelectionText(void);
  * clipboard is cleared or new data is set. The clipboard is automatically
  * cleared in SDL_Quit().
  *
- * \param userdata a pointer to provided user data.
+ * \param userdata a pointer to the provided user data.
  * \param mime_type the requested mime-type.
  * \param size a pointer filled in with the length of the returned data.
  * \returns a pointer to the data for the provided mime-type. Returning NULL
- *          or setting length to 0 will cause no data to be sent to the
- *          "receiver". It is up to the receiver to handle this. Essentially
- *          returning no data is more or less undefined behavior and may cause
- *          breakage in receiving applications. The returned data will not be
- *          freed so it needs to be retained and dealt with internally.
+ *          or setting the length to 0 will cause zero length data to be sent
+ *          to the "receiver", which should be able to handle this. The
+ *          returned data will not be freed, so it needs to be retained and
+ *          dealt with internally.
  *
  * \since This function is available since SDL 3.2.0.
  *
@@ -211,10 +210,10 @@ extern SDL_DECLSPEC bool SDLCALL SDL_HasPrimarySelectionText(void);
 typedef const void *(SDLCALL *SDL_ClipboardDataCallback)(void *userdata, const char *mime_type, size_t *size);
 
 /**
- * Callback function that will be called when the clipboard is cleared, or new
+ * Callback function that will be called when the clipboard is cleared, or when new
  * data is set.
  *
- * \param userdata a pointer to provided user data.
+ * \param userdata a pointer to the provided user data.
  *
  * \since This function is available since SDL 3.2.0.
  *
@@ -231,15 +230,15 @@ typedef void (SDLCALL *SDL_ClipboardCleanupCallback)(void *userdata);
  * respond with the data for the requested mime-type.
  *
  * The size of text data does not include any terminator, and the text does
- * not need to be null terminated (e.g. you can directly copy a portion of a
+ * not need to be null-terminated (e.g., you can directly copy a portion of a
  * document).
  *
  * \param callback a function pointer to the function that provides the
  *                 clipboard data.
  * \param cleanup a function pointer to the function that cleans up the
  *                clipboard data.
  * \param userdata an opaque pointer that will be forwarded to the callbacks.
- * \param mime_types a list of mime-types that are being offered.
+ * \param mime_types a list of mime-types that are being offered. SDL copies the given list.
  * \param num_mime_types the number of mime-types in the mime_types list.
  * \returns true on success or false on failure; call SDL_GetError() for more
  *          information.
@@ -269,10 +268,10 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetClipboardData(SDL_ClipboardDataCallback
 extern SDL_DECLSPEC bool SDLCALL SDL_ClearClipboardData(void);
 
 /**
- * Get the data from clipboard for a given mime type.
+ * Get the data from the clipboard for a given mime type.
  *
  * The size of text data does not include the terminator, but the text is
- * guaranteed to be null terminated.
+ * guaranteed to be null-terminated.
  *
  * \param mime_type the mime type to read from the clipboard.
  * \param size a pointer filled in with the length of the returned data.
@@ -292,8 +291,8 @@ extern SDL_DECLSPEC void * SDLCALL SDL_GetClipboardData(const char *mime_type, s
 /**
  * Query whether there is data in the clipboard for the provided mime type.
  *
- * \param mime_type the mime type to check for data for.
- * \returns true if there exists data in clipboard for the provided mime type,
+ * \param mime_type the mime type to check for data.
+ * \returns true if data exists in the clipboard for the provided mime type,
  *          false if it does not.
  *
  * \threadsafety This function should only be called on the main thread.
@@ -310,7 +309,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_HasClipboardData(const char *mime_type);
  *
  * \param num_mime_types a pointer filled with the number of mime types, may
  *                       be NULL.
- * \returns a null terminated array of strings with mime types, or NULL on
+ * \returns a null-terminated array of strings with mime types, or NULL on
  *          failure; call SDL_GetError() for more information. This should be
  *          freed with SDL_free() when it is no longer needed.
  *

libs/sdl3/include/SDL3/SDL_dialog.h

@@ -84,8 +84,8 @@ typedef struct SDL_DialogFileFilter
  * - A pointer to NULL, the user either didn't choose any file or canceled the
  *   dialog.
  * - A pointer to non-`NULL`, the user chose one or more files. The argument
- *   is a null-terminated list of pointers to C strings, each containing a
- *   path.
+ *   is a null-terminated array of pointers to UTF-8 encoded strings, each
+ *   containing a path.
  *
  * The filelist argument should not be freed; it will automatically be freed
  * when the callback returns.

libs/sdl3/include/SDL3/SDL_endian.h

@@ -46,7 +46,7 @@
 #if defined(_MSC_VER) && (_MSC_VER >= 1400)
 /* As of Clang 11, '_m_prefetchw' is conflicting with the winnt.h's version,
    so we define the needed '_m_prefetch' here as a pseudo-header, until the issue is fixed. */
-#ifdef __clang__
+#if defined(__clang__) &&  !SDL_HAS_BUILTIN(_m_prefetch)
 #ifndef __PRFCHWINTRIN_H
 #define __PRFCHWINTRIN_H
 static __inline__ void __attribute__((__always_inline__, __nodebug__))
@@ -128,7 +128,7 @@ _m_prefetch(void *__P)
  * \sa SDL_BIG_ENDIAN
  */
 #define SDL_BYTEORDER   SDL_LIL_ENDIAN___or_maybe___SDL_BIG_ENDIAN
-#elif defined(SDL_PLATFORM_LINUX)
+#elif defined(SDL_PLATFORM_LINUX) || defined(__GLIBC__)
 #include <endian.h>
 #define SDL_BYTEORDER  __BYTE_ORDER
 #elif defined(SDL_PLATFORM_SOLARIS)
@@ -486,7 +486,7 @@ SDL_FORCE_INLINE Uint32 SDL_Swap32(Uint32 x) { return x_but_byteswapped; }
  *
  * \since This function is available since SDL 3.2.0.
  */
-SDL_FORCE_INLINE Uint32 SDL_Swap64(Uint64 x) { return x_but_byteswapped; }
+SDL_FORCE_INLINE Uint64 SDL_Swap64(Uint64 x) { return x_but_byteswapped; }
 
 /**
  * Swap a 16-bit value from littleendian to native byte order.

libs/sdl3/include/SDL3/SDL_events.h

@@ -132,7 +132,7 @@ typedef enum SDL_EventType
 
     /* Window events */
     /* 0x200 was SDL_WINDOWEVENT, reserve the number for sdl2-compat */
-    /* 0x201 was SDL_EVENT_SYSWM, reserve the number for sdl2-compat */
+    /* 0x201 was SDL_SYSWMEVENT, reserve the number for sdl2-compat */
     SDL_EVENT_WINDOW_SHOWN = 0x202,     /**< Window has been shown */
     SDL_EVENT_WINDOW_HIDDEN,            /**< Window has been hidden */
     SDL_EVENT_WINDOW_EXPOSED,           /**< Window has been exposed and should be redrawn, and can be redrawn directly from event watchers for this event */
@@ -492,6 +492,8 @@ typedef struct SDL_MouseWheelEvent
     SDL_MouseWheelDirection direction; /**< Set to one of the SDL_MOUSEWHEEL_* defines. When FLIPPED the values in X and Y will be opposite. Multiply by -1 to change them back */
     float mouse_x;      /**< X coordinate, relative to window */
     float mouse_y;      /**< Y coordinate, relative to window */
+    Sint32 integer_x;   /**< The amount scrolled horizontally, accumulated to whole scroll "ticks" (added in 3.2.12) */
+    Sint32 integer_y;   /**< The amount scrolled vertically, accumulated to whole scroll "ticks" (added in 3.2.12) */
 } SDL_MouseWheelEvent;
 
 /**
@@ -1041,7 +1043,7 @@ typedef union SDL_Event
 } SDL_Event;
 
 /* Make sure we haven't broken binary compatibility */
-SDL_COMPILE_TIME_ASSERT(SDL_Event, sizeof(SDL_Event) == sizeof(((SDL_Event *)NULL)->padding));
+SDL_COMPILE_TIME_ASSERT(SDL_Event, sizeof(SDL_Event) == sizeof((SDL_static_cast(SDL_Event *, NULL))->padding));
 
 
 /* Function prototypes */
@@ -1108,7 +1110,7 @@ typedef enum SDL_EventAction
  * \param numevents if action is SDL_ADDEVENT, the number of events to add
  *                  back to the event queue; if action is SDL_PEEKEVENT or
  *                  SDL_GETEVENT, the maximum number of events to retrieve.
- * \param action action to take; see [[#action|Remarks]] for details.
+ * \param action action to take; see [Remarks](#remarks) for details.
  * \param minType minimum value of the event type to be considered;
  *                SDL_EVENT_FIRST is a safe choice.
  * \param maxType maximum value of the event type to be considered;

libs/sdl3/include/SDL3/SDL_gamepad.h

@@ -29,7 +29,7 @@
  * "joysticks" now are actually console-style gamepads. So SDL provides the
  * gamepad API on top of the lower-level joystick functionality.
  *
- * The difference betweena joystick and a gamepad is that a gamepad tells you
+ * The difference between a joystick and a gamepad is that a gamepad tells you
  * _where_ a button or axis is on the device. You don't speak to gamepads in
  * terms of arbitrary numbers like "button 3" or "axis 2" but in standard
  * locations: the d-pad, the shoulder buttons, triggers, A/B/X/Y (or