Merge upstream SDL 3.1.10

include/SDL3/SDL.h

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

include/SDL3/SDL_assert.h

@@ -118,19 +118,20 @@ extern "C" {
  *
  * If the program is not running under a debugger, SDL_TriggerBreakpoint will
  * likely terminate the app, possibly without warning. If the current platform
- * isn't supported (SDL doesn't know how to trigger a breakpoint), this macro
- * does nothing.
+ * isn't supported, this macro is left undefined.
  *
  * \threadsafety It is safe to call this macro from any thread.
  *
  * \since This macro is available since SDL 3.1.3.
  */
 #define SDL_TriggerBreakpoint() TriggerABreakpointInAPlatformSpecificManner
 
-#elif defined(_MSC_VER)
+#elif 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()
+#elif defined(_MSC_VER) && defined(_M_IX86)
+    #define SDL_TriggerBreakpoint() { _asm { int 0x03 }  }
 #elif defined(ANDROID)
     #include <assert.h>
     #define SDL_TriggerBreakpoint() assert(0)
@@ -152,8 +153,7 @@ extern "C" {
     #include <signal.h>
     #define SDL_TriggerBreakpoint() raise(SIGTRAP)
 #else
-    /* How do we trigger breakpoints on this platform? */
-    #define SDL_TriggerBreakpoint()
+    /* SDL_TriggerBreakpoint is intentionally left undefined on unknown platforms. */
 #endif
 
 #ifdef SDL_WIKI_DOCUMENTATION_SECTION

include/SDL3/SDL_asyncio.h

@@ -67,14 +67,14 @@
  *
  * ## Best Practices
  *
- * Simple non-blocking i/o--for an app that just wants to pick up data
+ * Simple non-blocking I/O--for an app that just wants to pick up data
  * whenever it's ready without losing framerate waiting on disks to spin--can
  * use whatever pattern works well for the program. In this case, simply call
  * SDL_ReadAsyncIO, or maybe SDL_LoadFileAsync, as needed. Once a frame, call
  * SDL_GetAsyncIOResult to check for any completed tasks and deal with the
  * data as it arrives.
  *
- * If two separate pieces of the same program need their own i/o, it is legal
+ * If two separate pieces of the same program need their own I/O, it is legal
  * for each to create their own queue. This will prevent either piece from
  * accidentally consuming the other's completed tasks. Each queue does require
  * some amount of resources, but it is not an overwhelming cost. Do not make a
@@ -83,7 +83,7 @@
  * were submitted, so it doesn't generally matter what order tasks are
  * started.
  *
- * One async i/o queue can be shared by multiple threads, or one thread can
+ * One async I/O queue can be shared by multiple threads, or one thread can
  * have more than one queue, but the most efficient way--if ruthless
  * efficiency is the goal--is to have one queue per thread, with multiple
  * threads working in parallel, and attempt to keep each queue loaded with
@@ -213,7 +213,7 @@ typedef struct SDL_AsyncIOQueue SDL_AsyncIOQueue;
  * \returns a pointer to the SDL_AsyncIO structure that is created or NULL on
  *          failure; call SDL_GetError() for more information.
  *
- * \since This function is available since SDL 3.2.0.
+ * \since This function is available since SDL 3.1.8.
  *
  * \sa SDL_CloseAsyncIO
  * \sa SDL_ReadAsyncIO
@@ -234,7 +234,7 @@ extern SDL_DECLSPEC SDL_AsyncIO * SDLCALL SDL_AsyncIOFromFile(const char *file,
  *
  * \threadsafety It is safe to call this function from any thread.
  *
- * \since This function is available since SDL 3.2.0.
+ * \since This function is available since SDL 3.1.8.
  */
 extern SDL_DECLSPEC Sint64 SDLCALL SDL_GetAsyncIOSize(SDL_AsyncIO *asyncio);
 
@@ -269,7 +269,7 @@ extern SDL_DECLSPEC Sint64 SDLCALL SDL_GetAsyncIOSize(SDL_AsyncIO *asyncio);
  *
  * \threadsafety It is safe to call this function from any thread.
  *
- * \since This function is available since SDL 3.2.0.
+ * \since This function is available since SDL 3.1.8.
  *
  * \sa SDL_WriteAsyncIO
  * \sa SDL_CreateAsyncIOQueue
@@ -306,7 +306,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_ReadAsyncIO(SDL_AsyncIO *asyncio, void *ptr
  *
  * \threadsafety It is safe to call this function from any thread.
  *
- * \since This function is available since SDL 3.2.0.
+ * \since This function is available since SDL 3.1.8.
  *
  * \sa SDL_ReadAsyncIO
  * \sa SDL_CreateAsyncIOQueue
@@ -358,7 +358,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_WriteAsyncIO(SDL_AsyncIO *asyncio, void *pt
  * \threadsafety It is safe to call this function from any thread, but two
  *               threads should not attempt to close the same object.
  *
- * \since This function is available since SDL 3.2.0.
+ * \since This function is available since SDL 3.1.8.
  */
 extern SDL_DECLSPEC bool SDLCALL SDL_CloseAsyncIO(SDL_AsyncIO *asyncio, bool flush, SDL_AsyncIOQueue *queue, void *userdata);
 
@@ -373,7 +373,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_CloseAsyncIO(SDL_AsyncIO *asyncio, bool flu
  *
  * \threadsafety It is safe to call this function from any thread.
  *
- * \since This function is available since SDL 3.2.0.
+ * \since This function is available since SDL 3.1.8.
  *
  * \sa SDL_DestroyAsyncIOQueue
  * \sa SDL_GetAsyncIOResult
@@ -407,7 +407,7 @@ extern SDL_DECLSPEC SDL_AsyncIOQueue * SDLCALL SDL_CreateAsyncIOQueue(void);
  *               no other thread is waiting on the queue with
  *               SDL_WaitAsyncIOResult.
  *
- * \since This function is available since SDL 3.2.0.
+ * \since This function is available since SDL 3.1.8.
  */
 extern SDL_DECLSPEC void SDLCALL SDL_DestroyAsyncIOQueue(SDL_AsyncIOQueue *queue);
 
@@ -431,7 +431,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyAsyncIOQueue(SDL_AsyncIOQueue *queue
  *
  * \threadsafety It is safe to call this function from any thread.
  *
- * \since This function is available since SDL 3.2.0.
+ * \since This function is available since SDL 3.1.8.
  *
  * \sa SDL_WaitAsyncIOResult
  */
@@ -475,7 +475,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetAsyncIOResult(SDL_AsyncIOQueue *queue, S
  *
  * \threadsafety It is safe to call this function from any thread.
  *
- * \since This function is available since SDL 3.2.0.
+ * \since This function is available since SDL 3.1.8.
  *
  * \sa SDL_SignalAsyncIOQueue
  */
@@ -499,7 +499,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_WaitAsyncIOResult(SDL_AsyncIOQueue *queue,
  *
  * \threadsafety It is safe to call this function from any thread.
  *
- * \since This function is available since SDL 3.2.0.
+ * \since This function is available since SDL 3.1.8.
  *
  * \sa SDL_WaitAsyncIOResult
  */
@@ -531,7 +531,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_SignalAsyncIOQueue(SDL_AsyncIOQueue *queue)
  * \returns true on success or false on failure; call SDL_GetError() for more
  *          information.
  *
- * \since This function is available since SDL 3.2.0.
+ * \since This function is available since SDL 3.1.8.
  *
  * \sa SDL_LoadFile_IO
  */

include/SDL3/SDL_audio.h

@@ -745,7 +745,7 @@ extern SDL_DECLSPEC SDL_AudioDeviceID SDLCALL SDL_OpenAudioDevice(SDL_AudioDevic
  *
  * \threadsafety It is safe to call this function from any thread.
  *
- * \since This function is available since SDL 3.2.0.
+ * \since This function is available since SDL 3.1.8.
  */
 extern SDL_DECLSPEC bool SDLCALL SDL_IsAudioDevicePhysical(SDL_AudioDeviceID devid);
 
@@ -759,7 +759,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_IsAudioDevicePhysical(SDL_AudioDeviceID dev
  *
  * \threadsafety It is safe to call this function from any thread.
  *
- * \since This function is available since SDL 3.2.0.
+ * \since This function is available since SDL 3.1.8.
  */
 extern SDL_DECLSPEC bool SDLCALL SDL_IsAudioDevicePlayback(SDL_AudioDeviceID devid);
 
@@ -942,7 +942,7 @@ 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.
+ * stream's format at any time with SDL_SetAudioStreamFormat().
  *
  * \param devid an audio device to bind a stream to.
  * \param streams an array of audio streams to bind.
@@ -1104,6 +1104,12 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetAudioStreamFormat(SDL_AudioStream *strea
  * next sound file, and start putting that new data while the previous sound
  * file is still queued, and everything will still play back correctly.
  *
+ * If a stream is bound to a device, then the format of the side of the stream
+ * bound to a device cannot be changed (src_spec for recording devices,
+ * dst_spec for playback devices). Attempts to make a change to this side will
+ * be ignored, but this will not report an error. The other side's format can
+ * be changed.
+ *
  * \param stream the stream the format is being changed.
  * \param src_spec the new format of the audio input; if NULL, it is not
  *                 changed.
@@ -1298,6 +1304,11 @@ extern SDL_DECLSPEC int * SDLCALL SDL_GetAudioStreamOutputChannelMap(SDL_AudioSt
  * race condition hasn't changed the format while this call is setting the
  * channel map.
  *
+ * Unlike attempting to change the stream's format, the input channel map on a
+ * stream bound to a recording device is permitted to change at any time; any
+ * data added to the stream from the device after this call will have the new
+ * mapping, but previously-added data will still have the prior mapping.
+ *
  * \param stream the SDL_AudioStream to change.
  * \param chmap the new channel map, NULL to reset to default.
  * \param count The number of channels in the map.
@@ -1349,6 +1360,13 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamInputChannelMap(SDL_AudioStre
  * race condition hasn't changed the format while this call is setting the
  * channel map.
  *
+ * Unlike attempting to change the stream's format, the output channel map on
+ * a stream bound to a recording device is permitted to change at any time;
+ * any data added to the stream after this call will have the new mapping, but
+ * previously-added data will still have the prior mapping. When the channel
+ * map doesn't match the hardware's channel layout, SDL will convert the data
+ * before feeding it to the device for playback.
+ *
  * \param stream the SDL_AudioStream to change.
  * \param chmap the new channel map, NULL to reset to default.
  * \param count The number of channels in the map.
@@ -1577,6 +1595,26 @@ extern SDL_DECLSPEC bool SDLCALL SDL_PauseAudioStreamDevice(SDL_AudioStream *str
  */
 extern SDL_DECLSPEC bool SDLCALL SDL_ResumeAudioStreamDevice(SDL_AudioStream *stream);
 
+/**
+ * Use this function to query if an audio device associated with a stream is
+ * paused.
+ *
+ * Unlike in SDL2, audio devices start in an _unpaused_ state, since an app
+ * has to bind a stream before any audio will flow.
+ *
+ * \param stream the audio stream associated with the audio device to query.
+ * \returns true if device is valid and paused, false otherwise.
+ *
+ * \threadsafety It is safe to call this function from any thread.
+ *
+ * \since This function is available since SDL 3.2.0.
+ *
+ * \sa SDL_PauseAudioStreamDevice
+ * \sa SDL_ResumeAudioStreamDevice
+ */
+extern SDL_DECLSPEC bool SDLCALL SDL_AudioStreamDevicePaused(SDL_AudioStream *stream);
+
+
 /**
  * Lock an audio stream for serialized access.
  *

include/SDL3/SDL_bits.h

@@ -78,7 +78,7 @@ SDL_FORCE_INLINE int SDL_MostSignificantBitIndex32(Uint32 x)
         return -1;
     }
     return _SDL_bsr_watcom(x);
-#elif defined(_MSC_VER)
+#elif defined(_MSC_VER) && _MSC_VER >= 1400
     unsigned long index;
     if (_BitScanReverse(&index, x)) {
         return (int)index;

include/SDL3/SDL_dialog.h

@@ -312,7 +312,7 @@ typedef enum SDL_FileDialogType
  *               callback may be invoked from the same thread or from a
  *               different one, depending on the OS's constraints.
  *
- * \since This function is available since SDL 3.2.0.
+ * \since This function is available since SDL 3.1.8.
  *
  * \sa SDL_FileDialogType
  * \sa SDL_DialogFileCallback

include/SDL3/SDL_events.h

@@ -38,10 +38,10 @@
  * at all).
  *
  * There is other forms of control, too: SDL_PeepEvents() has more
- * functionality at the cost of more complexity, and SDL_WaitEvents() can
- * block the process until something interesting happens, which might be
- * beneficial for certain types of programs on low-power hardware. One may
- * also call SDL_AddEventWatch() to set a callback when new events arrive.
+ * functionality at the cost of more complexity, and SDL_WaitEvent() can block
+ * the process until something interesting happens, which might be beneficial
+ * for certain types of programs on low-power hardware. One may also call
+ * SDL_AddEventWatch() to set a callback when new events arrive.
  *
  * The app is free to generate their own events, too: SDL_PushEvent allows the
  * app to put events onto the queue for later retrieval; SDL_RegisterEvents
@@ -1377,8 +1377,11 @@ extern SDL_DECLSPEC bool SDLCALL SDL_PushEvent(SDL_Event *event);
 typedef bool (SDLCALL *SDL_EventFilter)(void *userdata, SDL_Event *event);
 
 /**
- * Set up a filter to process all events before they change internal state and
- * are posted to the internal event queue.
+ * Set up a filter to process all events before they are added to the internal
+ * event queue.
+ *
+ * If you just want to see events without modifying them or preventing them
+ * from being queued, you should use SDL_AddEventWatch() instead.
  *
  * If the filter function returns true when called, then the event will be
  * added to the internal queue. If it returns false, then the event will be
@@ -1392,17 +1395,9 @@ typedef bool (SDLCALL *SDL_EventFilter)(void *userdata, SDL_Event *event);
  * interrupt signal (e.g. pressing Ctrl-C), it will be delivered to the
  * application at the next event poll.
  *
- * There is one caveat when dealing with the SDL_QuitEvent event type. The
- * event filter is only called when the window manager desires to close the
- * application window. If the event filter returns 1, then the window will be
- * closed, otherwise the window will remain open if possible.
- *
  * Note: Disabled events never make it to the event filter function; see
  * SDL_SetEventEnabled().
  *
- * Note: If you just want to inspect events without filtering, you should use
- * SDL_AddEventWatch() instead.
- *
  * Note: Events pushed onto the queue with SDL_PushEvent() get passed through
  * the event filter, but events pushed onto the queue with SDL_PeepEvents() do
  * not.

include/SDL3/SDL_filesystem.h

@@ -313,6 +313,9 @@ typedef enum SDL_EnumerationResult
  * terminate the enumeration early, and dictate the return value of the
  * enumeration function itself.
  *
+ * `dirname` is guaranteed to end with a path separator ('\\' on Windows, '/'
+ * on most other platforms).
+ *
  * \param userdata an app-controlled pointer that is passed to the callback.
  * \param dirname the directory that is being enumerated.
  * \param fname the next entry in the enumeration.
@@ -480,11 +483,14 @@ extern SDL_DECLSPEC char ** SDLCALL SDL_GlobDirectory(const char *path, const ch
  * platforms without this concept, this would cause surprises with file access
  * outside of SDL.
  *
+ * The returned path is guaranteed to end with a path separator ('\\' on
+ * Windows, '/' on most other platforms).
+ *
  * \returns a UTF-8 string of the current working directory in
  *          platform-dependent notation. NULL if there's a problem. This
  *          should be freed with SDL_free() when it is no longer needed.
  *
- * \since This function is available since SDL 3.2.0.
+ * \since This function is available since SDL 3.1.8.
  */
 extern SDL_DECLSPEC char * SDLCALL SDL_GetCurrentDirectory(void);