Document that video and input functions should be called on the main thread.

This is a hard requirement on Apple platforms and while most other platforms don't have a concept of main thread, all video and input functions should be called on the same thread.
2025-05-15 09:18:27 +00:00 · 2024-12-05 09:45:32 -08:00 · 2024-12-05 09:45:32 -08:00 · bc4185c685
commit bc4185c685
parent fffa6c7a2b
7 changed files with 407 additions and 103 deletions
--- a/include/SDL3/SDL_clipboard.h
+++ b/include/SDL3/SDL_clipboard.h
@ -49,7 +49,7 @@ extern "C" {
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -68,7 +68,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetClipboardText(const char *text);
 *          SDL_GetError() for more information. This should be freed with
 *          SDL_free() when it is no longer needed.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -82,7 +82,7 @@ extern SDL_DECLSPEC char * SDLCALL SDL_GetClipboardText(void);
 *
 * \returns true if the clipboard has text, or false if it does not.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -98,7 +98,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_HasClipboardText(void);
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -117,7 +117,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetPrimarySelectionText(const char *text);
 *          failure; call SDL_GetError() for more information. This should be
 *          freed with SDL_free() when it is no longer needed.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -132,7 +132,7 @@ extern SDL_DECLSPEC char * SDLCALL SDL_GetPrimarySelectionText(void);
 *
 * \returns true if the primary selection has text, or false if it does not.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -199,7 +199,7 @@ typedef void (SDLCALL *SDL_ClipboardCleanupCallback)(void *userdata);
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -215,7 +215,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetClipboardData(SDL_ClipboardDataCallback
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -235,7 +235,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_ClearClipboardData(void);
 *          for more information. This should be freed with SDL_free() when it
 *          is no longer needed.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -251,7 +251,7 @@ extern SDL_DECLSPEC void * SDLCALL SDL_GetClipboardData(const char *mime_type, s
 * \returns true if there exists data in clipboard for the provided mime type,
 *          false if it does not.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -269,7 +269,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_HasClipboardData(const char *mime_type);
 *          failure; call SDL_GetError() for more information. This should be
 *          freed with SDL_free() when it is no longer needed.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
--- a/include/SDL3/SDL_events.h
+++ b/include/SDL3/SDL_events.h
@ -1034,9 +1034,7 @@ SDL_COMPILE_TIME_ASSERT(SDL_Event, sizeof(SDL_Event) == sizeof(((SDL_Event *)NUL
 * polling or waiting for events (e.g. you are filtering them), then you must
 * call SDL_PumpEvents() to force an event queue update.
 *
- * \threadsafety This should only be run in the thread that initialized the
+ * \threadsafety This function should only be called on the main thread.
 *               video subsystem, and for extra safety, you should consider
 *               only doing those things on the main thread in any case.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -1234,9 +1232,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_FlushEvents(Uint32 minType, Uint32 maxType)
 *              the queue, or NULL.
 * \returns true if this got an event or false if there are none available.
 *
- * \threadsafety This should only be run in the thread that initialized the
+ * \threadsafety This function should only be called on the main thread.
 *               video subsystem, and for extra safety, you should consider
 *               only doing those things on the main thread in any case.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -1260,9 +1256,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_PollEvent(SDL_Event *event);
 * \returns true on success or false if there was an error while waiting for
 *          events; call SDL_GetError() for more information.
 *
- * \threadsafety This should only be run in the thread that initialized the
+ * \threadsafety This function should only be called on the main thread.
 *               video subsystem, and for extra safety, you should consider
 *               only doing those things on the main thread in any case.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -1292,9 +1286,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_WaitEvent(SDL_Event *event);
 * \returns true if this got an event or false if the timeout elapsed without
 *          any events available.
 *
- * \threadsafety This should only be run in the thread that initialized the
+ * \threadsafety This function should only be called on the main thread.
 *               video subsystem, and for extra safety, you should consider
 *               only doing those things on the main thread in any case.
 *
 * \since This function is available since SDL 3.1.3.
 *
--- a/include/SDL3/SDL_init.h
+++ b/include/SDL3/SDL_init.h
@ -78,7 +78,7 @@ extern "C" {
 typedef Uint32 SDL_InitFlags;
 #define SDL_INIT_AUDIO      0x00000010u /**< `SDL_INIT_AUDIO` implies `SDL_INIT_EVENTS` */
-#define SDL_INIT_VIDEO      0x00000020u /**< `SDL_INIT_VIDEO` implies `SDL_INIT_EVENTS` */
+#define SDL_INIT_VIDEO      0x00000020u /**< `SDL_INIT_VIDEO` implies `SDL_INIT_EVENTS`, should be initialized on the main thread */
 #define SDL_INIT_JOYSTICK   0x00000200u /**< `SDL_INIT_JOYSTICK` implies `SDL_INIT_EVENTS`, should be initialized on the same thread as SDL_INIT_VIDEO on Windows if you don't set SDL_HINT_JOYSTICK_THREAD */
 #define SDL_INIT_HAPTIC     0x00001000u
 #define SDL_INIT_GAMEPAD    0x00002000u /**< `SDL_INIT_GAMEPAD` implies `SDL_INIT_JOYSTICK` */
@ -139,7 +139,7 @@ typedef void (SDLCALL *SDL_AppQuit_func)(void *appstate, SDL_AppResult result);
 * - `SDL_INIT_AUDIO`: audio subsystem; automatically initializes the events
 *   subsystem
 * - `SDL_INIT_VIDEO`: video subsystem; automatically initializes the events
- *   subsystem
+ *   subsystem, should be initialized on the main thread.
 * - `SDL_INIT_JOYSTICK`: joystick subsystem; automatically initializes the
 *   events subsystem
 * - `SDL_INIT_HAPTIC`: haptic (force feedback) subsystem
--- a/include/SDL3/SDL_keyboard.h
+++ b/include/SDL3/SDL_keyboard.h
@ -61,6 +61,8 @@ typedef Uint32 SDL_KeyboardID;
 *
 * \returns true if a keyboard is connected, false otherwise.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GetKeyboards
@ -81,6 +83,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_HasKeyboard(void);
 *          call SDL_GetError() for more information. This should be freed
 *          with SDL_free() when it is no longer needed.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GetKeyboardNameForID
@ -97,6 +101,8 @@ extern SDL_DECLSPEC SDL_KeyboardID * SDLCALL SDL_GetKeyboards(int *count);
 * \returns the name of the selected keyboard or NULL on failure; call
 *          SDL_GetError() for more information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GetKeyboards
@ -108,6 +114,8 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetKeyboardNameForID(SDL_KeyboardID
 *
 * \returns the window with keyboard focus.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 */
 extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetKeyboardFocus(void);
@ -136,6 +144,8 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetKeyboardFocus(void);
 * \param numkeys if non-NULL, receives the length of the returned array.
 * \returns a pointer to an array of key states.
 *
 * \threadsafety It is safe to call this function from any thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_PumpEvents
@ -148,6 +158,8 @@ extern SDL_DECLSPEC const bool * SDLCALL SDL_GetKeyboardState(int *numkeys);
 *
 * This function will generate key up events for all pressed keys.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GetKeyboardState
@ -160,6 +172,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_ResetKeyboard(void);
 * \returns an OR'd combination of the modifier keys for the keyboard. See
 *          SDL_Keymod for details.
 *
 * \threadsafety It is safe to call this function from any thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GetKeyboardState
@ -180,6 +194,8 @@ extern SDL_DECLSPEC SDL_Keymod SDLCALL SDL_GetModState(void);
 *
 * \param modstate the desired SDL_Keymod for the keyboard.
 *
 * \threadsafety It is safe to call this function from any thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GetModState
@ -201,6 +217,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetModState(SDL_Keymod modstate);
 * \param key_event true if the keycode will be used in key events.
 * \returns the SDL_Keycode that corresponds to the given SDL_Scancode.
 *
 * \threadsafety This function is not thread safe.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GetKeyName
@ -220,6 +238,8 @@ extern SDL_DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromScancode(SDL_Scancode scan
 *                 scancode generates this key, may be NULL.
 * \returns the SDL_Scancode that corresponds to the given SDL_Keycode.
 *
 * \threadsafety This function is not thread safe.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GetKeyFromScancode
@ -237,6 +257,8 @@ extern SDL_DECLSPEC SDL_Scancode SDLCALL SDL_GetScancodeFromKey(SDL_Keycode key,
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
 * \threadsafety This function is not thread safe.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GetScancodeName
@ -259,6 +281,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetScancodeName(SDL_Scancode scancode, cons
 * \returns a pointer to the name for the scancode. If the scancode doesn't
 *          have a name this function returns an empty string ("").
 *
 * \threadsafety This function is not thread safe.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GetScancodeFromKey
@ -274,6 +298,8 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetScancodeName(SDL_Scancode scanco
 * \returns the SDL_Scancode, or `SDL_SCANCODE_UNKNOWN` if the name wasn't
 *          recognized; call SDL_GetError() for more information.
 *
 * \threadsafety This function is not thread safe.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GetKeyFromName
@ -290,6 +316,8 @@ extern SDL_DECLSPEC SDL_Scancode SDLCALL SDL_GetScancodeFromName(const char *nam
 * \param key the desired SDL_Keycode to query.
 * \returns a UTF-8 encoded string of the key name.
 *
 * \threadsafety This function is not thread safe.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GetKeyFromName
@ -305,6 +333,8 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetKeyName(SDL_Keycode key);
 * \returns key code, or `SDLK_UNKNOWN` if the name wasn't recognized; call
 *          SDL_GetError() for more information.
 *
 * \threadsafety This function is not thread safe.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GetKeyFromScancode
@ -330,6 +360,8 @@ extern SDL_DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromName(const char *name);
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_SetTextInputArea
@ -423,6 +455,8 @@ typedef enum SDL_Capitalization
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_SetTextInputArea
@ -444,6 +478,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_StartTextInputWithProperties(SDL_Window *wi
 * \param window the window to check.
 * \returns true if text input events are enabled else false.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_StartTextInput
@ -460,6 +496,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_TextInputActive(SDL_Window *window);
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_StartTextInput
@ -473,6 +511,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_StopTextInput(SDL_Window *window);
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_StartTextInput
@ -494,6 +534,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_ClearComposition(SDL_Window *window);
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GetTextInputArea
@ -514,6 +556,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetTextInputArea(SDL_Window *window, const
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_SetTextInputArea
@ -526,6 +570,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetTextInputArea(SDL_Window *window, SDL_Re
 * \returns true if the platform has some screen keyboard support or false if
 *          not.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_StartTextInput
@ -539,6 +585,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_HasScreenKeyboardSupport(void);
 * \param window the window for which screen keyboard should be queried.
 * \returns true if screen keyboard is shown or false if not.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_HasScreenKeyboardSupport
--- a/include/SDL3/SDL_mouse.h
+++ b/include/SDL3/SDL_mouse.h
@ -139,6 +139,8 @@ typedef Uint32 SDL_MouseButtonFlags;
 *
 * \returns true if a mouse is connected, false otherwise.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GetMice
@ -159,6 +161,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_HasMouse(void);
 *          call SDL_GetError() for more information. This should be freed
 *          with SDL_free() when it is no longer needed.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GetMouseNameForID
@ -175,6 +179,8 @@ extern SDL_DECLSPEC SDL_MouseID * SDLCALL SDL_GetMice(int *count);
 * \returns the name of the selected mouse, or NULL on failure; call
 *          SDL_GetError() for more information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GetMice
@ -186,6 +192,8 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetMouseNameForID(SDL_MouseID insta
 *
 * \returns the window with mouse focus.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 */
 extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetMouseFocus(void);
@ -214,6 +222,8 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetMouseFocus(void);
 * \returns a 32-bit bitmask of the button state that can be bitwise-compared
 *          against the SDL_BUTTON_MASK(X) macro.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GetGlobalMouseState
@ -248,6 +258,8 @@ extern SDL_DECLSPEC SDL_MouseButtonFlags SDLCALL SDL_GetMouseState(float *x, flo
 * \returns a 32-bit bitmask of the button state that can be bitwise-compared
 *          against the SDL_BUTTON_MASK(X) macro.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_CaptureMouse
@ -282,6 +294,8 @@ extern SDL_DECLSPEC SDL_MouseButtonFlags SDLCALL SDL_GetGlobalMouseState(float *
 * \returns a 32-bit bitmask of the button state that can be bitwise-compared
 *          against the SDL_BUTTON_MASK(X) macro.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GetMouseState
@ -304,6 +318,8 @@ extern SDL_DECLSPEC SDL_MouseButtonFlags SDLCALL SDL_GetRelativeMouseState(float
 * \param x the x coordinate within the window.
 * \param y the y coordinate within the window.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_WarpMouseGlobal
@ -327,6 +343,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_WarpMouseInWindow(SDL_Window * window,
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_WarpMouseInWindow
@ -348,6 +366,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_WarpMouseGlobal(float x, float y);
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GetWindowRelativeMouseMode
@ -360,6 +380,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowRelativeMouseMode(SDL_Window *wind
 * \param window the window to query.
 * \returns true if relative mode is enabled for a window or false otherwise.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_SetWindowRelativeMouseMode
@ -406,6 +428,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowRelativeMouseMode(SDL_Window *wind
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GetGlobalMouseState
@ -447,6 +471,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_CaptureMouse(bool enabled);
 * \returns a new cursor with the specified parameters on success or NULL on
 *          failure; call SDL_GetError() for more information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_CreateColorCursor
@ -478,6 +504,8 @@ extern SDL_DECLSPEC SDL_Cursor * SDLCALL SDL_CreateCursor(const Uint8 * data,
 * \returns the new cursor on success or NULL on failure; call SDL_GetError()
 *          for more information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_CreateCursor
@ -496,6 +524,8 @@ extern SDL_DECLSPEC SDL_Cursor * SDLCALL SDL_CreateColorCursor(SDL_Surface *surf
 * \returns a cursor on success or NULL on failure; call SDL_GetError() for
 *          more information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_DestroyCursor
@ -514,6 +544,8 @@ extern SDL_DECLSPEC SDL_Cursor * SDLCALL SDL_CreateSystemCursor(SDL_SystemCursor
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GetCursor
@ -528,6 +560,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetCursor(SDL_Cursor *cursor);
 *
 * \returns the active cursor or NULL if there is no mouse.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_SetCursor
@ -543,6 +577,8 @@ extern SDL_DECLSPEC SDL_Cursor * SDLCALL SDL_GetCursor(void);
 * \returns the default cursor on success or NULL on failuree; call
 *          SDL_GetError() for more information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 */
 extern SDL_DECLSPEC SDL_Cursor * SDLCALL SDL_GetDefaultCursor(void);
@ -555,6 +591,8 @@ extern SDL_DECLSPEC SDL_Cursor * SDLCALL SDL_GetDefaultCursor(void);
 *
 * \param cursor the cursor to free.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_CreateColorCursor
@ -569,6 +607,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyCursor(SDL_Cursor *cursor);
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_CursorVisible
@ -582,6 +622,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_ShowCursor(void);
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_CursorVisible
@ -595,6 +637,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_HideCursor(void);
 * \returns `true` if the cursor is being shown, or `false` if the cursor is
 *          hidden.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_HideCursor
--- a/include/SDL3/SDL_render.h
+++ b/include/SDL3/SDL_render.h
@ -201,7 +201,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetRenderDriver(int index);
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -229,7 +229,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_CreateWindowAndRenderer(const char *title,
 * \returns a valid rendering context or NULL if there was an error; call
 *          SDL_GetError() for more information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -283,7 +283,7 @@ extern SDL_DECLSPEC SDL_Renderer * SDLCALL SDL_CreateRenderer(SDL_Window *window
 * \returns a valid rendering context or NULL if there was an error; call
 *          SDL_GetError() for more information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -320,7 +320,7 @@ extern SDL_DECLSPEC SDL_Renderer * SDLCALL SDL_CreateRendererWithProperties(SDL_
 * \returns a valid rendering context or NULL if there was an error; call
 *          SDL_GetError() for more information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -487,7 +487,7 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetRendererProperties(SDL_Rende
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -509,7 +509,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderOutputSize(SDL_Renderer *renderer,
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -531,7 +531,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetCurrentRenderOutputSize(SDL_Renderer *re
 *          was active, the format was unsupported, or the width or height
 *          were out of range; call SDL_GetError() for more information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -561,7 +561,7 @@ extern SDL_DECLSPEC SDL_Texture * SDLCALL SDL_CreateTexture(SDL_Renderer *render
 * \returns the created texture or NULL on failure; call SDL_GetError() for
 *          more information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -671,7 +671,7 @@ extern SDL_DECLSPEC SDL_Texture * SDLCALL SDL_CreateTextureFromSurface(SDL_Rende
 *          was active, the format was unsupported, or the width or height
 *          were out of range; call SDL_GetError() for more information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -847,7 +847,7 @@ extern SDL_DECLSPEC SDL_Renderer * SDLCALL SDL_GetRendererFromTexture(SDL_Textur
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 */
@ -872,7 +872,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetTextureSize(SDL_Texture *texture, float
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -902,7 +902,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetTextureColorMod(SDL_Texture *texture, Ui
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -923,7 +923,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetTextureColorModFloat(SDL_Texture *textur
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -943,7 +943,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetTextureColorMod(SDL_Texture *texture, Ui
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -969,7 +969,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetTextureColorModFloat(SDL_Texture *textur
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -995,7 +995,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetTextureAlphaMod(SDL_Texture *texture, Ui
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -1013,7 +1013,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetTextureAlphaModFloat(SDL_Texture *textur
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -1031,7 +1031,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetTextureAlphaMod(SDL_Texture *texture, Ui
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -1052,7 +1052,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetTextureAlphaModFloat(SDL_Texture *textur
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -1068,7 +1068,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetTextureBlendMode(SDL_Texture *texture, S
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -1088,7 +1088,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetTextureBlendMode(SDL_Texture *texture, S
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -1104,7 +1104,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetTextureScaleMode(SDL_Texture *texture, S
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -1135,7 +1135,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetTextureScaleMode(SDL_Texture *texture, S
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -1169,7 +1169,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_UpdateTexture(SDL_Texture *texture, const S
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -1201,7 +1201,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_UpdateYUVTexture(SDL_Texture *texture,
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -1236,7 +1236,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_UpdateNVTexture(SDL_Texture *texture,
 *          created with `SDL_TEXTUREACCESS_STREAMING`; call SDL_GetError()
 *          for more information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -1274,7 +1274,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_LockTexture(SDL_Texture *texture,
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -1296,7 +1296,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_LockTextureToSurface(SDL_Texture *texture,
 *
 * \param texture a texture locked by SDL_LockTexture().
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -1318,7 +1318,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnlockTexture(SDL_Texture *texture);
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -1335,7 +1335,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderTarget(SDL_Renderer *renderer, SDL
 * \param renderer the rendering context.
 * \returns the current render target or NULL for the default render target.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -1374,7 +1374,7 @@ extern SDL_DECLSPEC SDL_Texture * SDLCALL SDL_GetRenderTarget(SDL_Renderer *rend
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -1397,7 +1397,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderLogicalPresentation(SDL_Renderer *
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -1419,7 +1419,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderLogicalPresentation(SDL_Renderer *
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -1445,7 +1445,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderLogicalPresentationRect(SDL_Render
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -1474,7 +1474,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_RenderCoordinatesFromWindow(SDL_Renderer *r
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -1504,7 +1504,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_RenderCoordinatesToWindow(SDL_Renderer *ren
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -1527,7 +1527,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_ConvertEventToRenderCoordinates(SDL_Rendere
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -1544,7 +1544,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderViewport(SDL_Renderer *renderer, c
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -1564,7 +1564,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderViewport(SDL_Renderer *renderer, S
 * \returns true if the viewport was set to a specific rectangle, or false if
 *          it was set to NULL (the entire target).
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -1589,7 +1589,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_RenderViewportSet(SDL_Renderer *renderer);
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 */
@ -1604,7 +1604,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderSafeArea(SDL_Renderer *renderer, S
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -1622,7 +1622,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderClipRect(SDL_Renderer *renderer, c
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -1638,7 +1638,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderClipRect(SDL_Renderer *renderer, S
 * \returns true if clipping is enabled or false if not; call SDL_GetError()
 *          for more information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -1664,7 +1664,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_RenderClipEnabled(SDL_Renderer *renderer);
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -1681,7 +1681,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderScale(SDL_Renderer *renderer, floa
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -1705,7 +1705,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderScale(SDL_Renderer *renderer, floa
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -1730,7 +1730,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderDrawColor(SDL_Renderer *renderer,
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -1754,7 +1754,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderDrawColorFloat(SDL_Renderer *rende
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -1778,7 +1778,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderDrawColor(SDL_Renderer *renderer,
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -1803,7 +1803,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderDrawColorFloat(SDL_Renderer *rende
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -1819,7 +1819,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderColorScale(SDL_Renderer *renderer,
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -1837,7 +1837,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderColorScale(SDL_Renderer *renderer,
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -1853,7 +1853,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderDrawBlendMode(SDL_Renderer *render
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -1873,7 +1873,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderDrawBlendMode(SDL_Renderer *render
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -1890,7 +1890,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_RenderClear(SDL_Renderer *renderer);
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -1907,7 +1907,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_RenderPoint(SDL_Renderer *renderer, float x
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -1926,7 +1926,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_RenderPoints(SDL_Renderer *renderer, const
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -1944,7 +1944,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_RenderLine(SDL_Renderer *renderer, float x1
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -1961,7 +1961,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_RenderLines(SDL_Renderer *renderer, const S
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -1979,7 +1979,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_RenderRect(SDL_Renderer *renderer, const SD
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -1997,7 +1997,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_RenderRects(SDL_Renderer *renderer, const S
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -2015,7 +2015,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_RenderFillRect(SDL_Renderer *renderer, cons
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -2036,7 +2036,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_RenderFillRects(SDL_Renderer *renderer, con
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -2065,7 +2065,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_RenderTexture(SDL_Renderer *renderer, SDL_T
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -2095,7 +2095,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_RenderTextureRotated(SDL_Renderer *renderer
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -2129,7 +2129,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_RenderTextureTiled(SDL_Renderer *renderer,
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -2153,7 +2153,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_RenderTexture9Grid(SDL_Renderer *renderer,
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -2185,7 +2185,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_RenderGeometry(SDL_Renderer *renderer,
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -2214,7 +2214,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_RenderGeometryRaw(SDL_Renderer *renderer,
 * \returns a new SDL_Surface on success or NULL on failure; call
 *          SDL_GetError() for more information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 */
@ -2251,7 +2251,7 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_RenderReadPixels(SDL_Renderer *ren
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -2278,7 +2278,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_RenderPresent(SDL_Renderer *renderer);
 *
 * \param texture the texture to destroy.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -2295,7 +2295,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyTexture(SDL_Texture *texture);
 *
 * \param renderer the rendering context.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -2330,7 +2330,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyRenderer(SDL_Renderer *renderer);
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 */
@ -2346,7 +2346,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_FlushRenderer(SDL_Renderer *renderer);
 * \returns a `CAMetalLayer *` on success, or NULL if the renderer isn't a
 *          Metal renderer.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -2369,7 +2369,7 @@ extern SDL_DECLSPEC void * SDLCALL SDL_GetRenderMetalLayer(SDL_Renderer *rendere
 * \returns an `id<MTLRenderCommandEncoder>` on success, or NULL if the
 *          renderer isn't a Metal renderer or there was an error.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -2425,7 +2425,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_AddVulkanRenderSemaphores(SDL_Renderer *ren
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -2445,7 +2445,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderVSync(SDL_Renderer *renderer, int
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
@ -2496,7 +2496,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderVSync(SDL_Renderer *renderer, int
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
- * \threadsafety You may only call this function from the main thread.
+ * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.6.
 *
--- a/include/SDL3/SDL_video.h
+++ b/include/SDL3/SDL_video.h
@ -419,6 +419,8 @@ typedef Uint32 SDL_GLContextResetNotification;
 *
 * \returns the number of built in video drivers.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GetVideoDriver
@ -438,6 +440,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumVideoDrivers(void);
 * \param index the index of a video driver.
 * \returns the name of the video driver with the given **index**.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GetNumVideoDrivers
@ -454,6 +458,8 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetVideoDriver(int index);
 * \returns the name of the current video driver or NULL if no driver has been
 *          initialized.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GetNumVideoDrivers
@ -466,6 +472,8 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetCurrentVideoDriver(void);
 *
 * \returns the current system theme, light, dark, or unknown.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 */
 extern SDL_DECLSPEC SDL_SystemTheme SDLCALL SDL_GetSystemTheme(void);
@ -479,6 +487,8 @@ extern SDL_DECLSPEC SDL_SystemTheme SDLCALL SDL_GetSystemTheme(void);
 *          call SDL_GetError() for more information. This should be freed
 *          with SDL_free() when it is no longer needed.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 */
 extern SDL_DECLSPEC SDL_DisplayID * SDLCALL SDL_GetDisplays(int *count);
@ -489,6 +499,8 @@ extern SDL_DECLSPEC SDL_DisplayID * SDLCALL SDL_GetDisplays(int *count);
 * \returns the instance ID of the primary display on success or 0 on failure;
 *          call SDL_GetError() for more information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GetDisplays
@ -517,6 +529,8 @@ extern SDL_DECLSPEC SDL_DisplayID SDLCALL SDL_GetPrimaryDisplay(void);
 * \returns a valid property ID on success or 0 on failure; call
 *          SDL_GetError() for more information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 */
 extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetDisplayProperties(SDL_DisplayID displayID);
@ -531,6 +545,8 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetDisplayProperties(SDL_Displa
 * \returns the name of a display or NULL on failure; call SDL_GetError() for
 *          more information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GetDisplays
@ -547,6 +563,8 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetDisplayName(SDL_DisplayID displa
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GetDisplayUsableBounds
@ -571,6 +589,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetDisplayBounds(SDL_DisplayID displayID, S
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GetDisplayBounds
@ -585,6 +605,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetDisplayUsableBounds(SDL_DisplayID displa
 * \returns the SDL_DisplayOrientation enum value of the display, or
 *          `SDL_ORIENTATION_UNKNOWN` if it isn't available.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GetDisplays
@ -598,6 +620,8 @@ extern SDL_DECLSPEC SDL_DisplayOrientation SDLCALL SDL_GetNaturalDisplayOrientat
 * \returns the SDL_DisplayOrientation enum value of the display, or
 *          `SDL_ORIENTATION_UNKNOWN` if it isn't available.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GetDisplays
@ -616,6 +640,8 @@ extern SDL_DECLSPEC SDL_DisplayOrientation SDLCALL SDL_GetCurrentDisplayOrientat
 * \returns the content scale of the display, or 0.0f on failure; call
 *          SDL_GetError() for more information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GetDisplays
@ -642,6 +668,8 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetDisplayContentScale(SDL_DisplayID displ
 *          single allocation that should be freed with SDL_free() when it is
 *          no longer needed.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GetDisplays
@ -670,6 +698,8 @@ extern SDL_DECLSPEC SDL_DisplayMode ** SDLCALL SDL_GetFullscreenDisplayModes(SDL
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GetDisplays
@ -689,6 +719,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetClosestFullscreenDisplayMode(SDL_Display
 * \returns a pointer to the desktop display mode or NULL on failure; call
 *          SDL_GetError() for more information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GetCurrentDisplayMode
@ -708,6 +740,8 @@ extern SDL_DECLSPEC const SDL_DisplayMode * SDLCALL SDL_GetDesktopDisplayMode(SD
 * \returns a pointer to the desktop display mode or NULL on failure; call
 *          SDL_GetError() for more information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GetDesktopDisplayMode
@ -722,6 +756,8 @@ extern SDL_DECLSPEC const SDL_DisplayMode * SDLCALL SDL_GetCurrentDisplayMode(SD
 * \returns the instance ID of the display containing the point or 0 on
 *          failure; call SDL_GetError() for more information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GetDisplayBounds
@ -737,6 +773,8 @@ extern SDL_DECLSPEC SDL_DisplayID SDLCALL SDL_GetDisplayForPoint(const SDL_Point
 *          closest to the center of the rect on success or 0 on failure; call
 *          SDL_GetError() for more information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GetDisplayBounds
@ -752,6 +790,8 @@ extern SDL_DECLSPEC SDL_DisplayID SDLCALL SDL_GetDisplayForRect(const SDL_Rect *
 *          on success or 0 on failure; call SDL_GetError() for more
 *          information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GetDisplayBounds
@ -770,6 +810,8 @@ extern SDL_DECLSPEC SDL_DisplayID SDLCALL SDL_GetDisplayForWindow(SDL_Window *wi
 * \returns the pixel density or 0.0f on failure; call SDL_GetError() for more
 *          information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GetWindowDisplayScale
@ -794,6 +836,8 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetWindowPixelDensity(SDL_Window *window);
 * \returns the display scale, or 0.0f on failure; call SDL_GetError() for
 *          more information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 */
 extern SDL_DECLSPEC float SDLCALL SDL_GetWindowDisplayScale(SDL_Window *window);
@ -823,6 +867,8 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetWindowDisplayScale(SDL_Window *window);
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GetWindowFullscreenMode
@ -838,6 +884,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowFullscreenMode(SDL_Window *window,
 * \returns a pointer to the exclusive fullscreen mode to use or NULL for
 *          borderless fullscreen desktop mode.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_SetWindowFullscreenMode
@ -854,6 +902,8 @@ extern SDL_DECLSPEC const SDL_DisplayMode * SDLCALL SDL_GetWindowFullscreenMode(
 *          SDL_GetError() for more information. This should be freed with
 *          SDL_free() when it is no longer needed.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 */
 extern SDL_DECLSPEC void * SDLCALL SDL_GetWindowICCProfile(SDL_Window *window, size_t *size);
@ -866,6 +916,8 @@ extern SDL_DECLSPEC void * SDLCALL SDL_GetWindowICCProfile(SDL_Window *window, s
 *          SDL_PIXELFORMAT_UNKNOWN on failure; call SDL_GetError() for more
 *          information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 */
 extern SDL_DECLSPEC SDL_PixelFormat SDLCALL SDL_GetWindowPixelFormat(SDL_Window *window);
@ -880,6 +932,8 @@ extern SDL_DECLSPEC SDL_PixelFormat SDLCALL SDL_GetWindowPixelFormat(SDL_Window
 *          allocation that should be freed with SDL_free() when it is no
 *          longer needed.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 */
 extern SDL_DECLSPEC SDL_Window ** SDLCALL SDL_GetWindows(int *count);
@ -959,6 +1013,8 @@ extern SDL_DECLSPEC SDL_Window ** SDLCALL SDL_GetWindows(int *count);
 * \returns the window that was created or NULL on failure; call
 *          SDL_GetError() for more information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_CreateWindowAndRenderer
@ -1019,6 +1075,8 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_CreateWindow(const char *title, int
 * \returns the window that was created or NULL on failure; call
 *          SDL_GetError() for more information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_CreateWindow
@ -1137,6 +1195,8 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_CreatePopupWindow(SDL_Window *paren
 * \returns the window that was created or NULL on failure; call
 *          SDL_GetError() for more information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_CreateProperties
@ -1190,6 +1250,8 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_CreateWindowWithProperties(SDL_Prop
 * \returns the ID of the window on success or 0 on failure; call
 *          SDL_GetError() for more information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GetWindowFromID
@ -1206,6 +1268,8 @@ extern SDL_DECLSPEC SDL_WindowID SDLCALL SDL_GetWindowID(SDL_Window *window);
 * \returns the window associated with `id` or NULL if it doesn't exist; call
 *          SDL_GetError() for more information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GetWindowID
@ -1219,6 +1283,8 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetWindowFromID(SDL_WindowID id);
 * \returns the parent of the window on success or NULL if the window has no
 *          parent.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_CreatePopupWindow
@ -1341,6 +1407,8 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetWindowParent(SDL_Window *window)
 * \returns a valid property ID on success or 0 on failure; call
 *          SDL_GetError() for more information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 */
 extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetWindowProperties(SDL_Window *window);
@ -1387,6 +1455,8 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetWindowProperties(SDL_Window
 * \param window the window to query.
 * \returns a mask of the SDL_WindowFlags associated with `window`.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_CreateWindow
@ -1409,6 +1479,8 @@ extern SDL_DECLSPEC SDL_WindowFlags SDLCALL SDL_GetWindowFlags(SDL_Window *windo
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GetWindowTitle
@ -1422,6 +1494,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowTitle(SDL_Window *window, const ch
 * \returns the title of the window in UTF-8 format or "" if there is no
 *          title.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_SetWindowTitle
@ -1446,6 +1520,8 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetWindowTitle(SDL_Window *window);
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 */
 extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowIcon(SDL_Window *window, SDL_Surface *icon);
@ -1483,6 +1559,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowIcon(SDL_Window *window, SDL_Surfa
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GetWindowPosition
@ -1507,6 +1585,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowPosition(SDL_Window *window, int x
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_SetWindowPosition
@ -1541,6 +1621,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowPosition(SDL_Window *window, int *
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GetWindowSize
@ -1562,6 +1644,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowSize(SDL_Window *window, int w, in
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GetRenderOutputSize
@ -1586,6 +1670,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowSize(SDL_Window *window, int *w, i
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 */
 extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowSafeArea(SDL_Window *window, SDL_Rect *rect);
@ -1622,6 +1708,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowSafeArea(SDL_Window *window, SDL_R
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GetWindowAspectRatio
@ -1640,6 +1728,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowAspectRatio(SDL_Window *window, fl
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_SetWindowAspectRatio
@ -1675,6 +1765,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowAspectRatio(SDL_Window *window, fl
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GetWindowSize
@ -1692,6 +1784,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowBordersSize(SDL_Window *window, in
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_CreateWindow
@ -1708,6 +1802,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowSizeInPixels(SDL_Window *window, i
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GetWindowMinimumSize
@ -1726,6 +1822,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowMinimumSize(SDL_Window *window, in
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GetWindowMaximumSize
@ -1742,6 +1840,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowMinimumSize(SDL_Window *window, in
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GetWindowMaximumSize
@ -1760,6 +1860,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowMaximumSize(SDL_Window *window, in
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GetWindowMinimumSize
@ -1781,6 +1883,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowMaximumSize(SDL_Window *window, in
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GetWindowFlags
@ -1801,6 +1905,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowBordered(SDL_Window *window, bool
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GetWindowFlags
@ -1818,6 +1924,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowResizable(SDL_Window *window, bool
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GetWindowFlags
@ -1831,6 +1939,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowAlwaysOnTop(SDL_Window *window, bo
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_HideWindow
@ -1845,6 +1955,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_ShowWindow(SDL_Window *window);
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_ShowWindow
@ -1866,6 +1978,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_HideWindow(SDL_Window *window);
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 */
 extern SDL_DECLSPEC bool SDLCALL SDL_RaiseWindow(SDL_Window *window);
@ -1894,6 +2008,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_RaiseWindow(SDL_Window *window);
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_MinimizeWindow
@ -1918,6 +2034,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_MaximizeWindow(SDL_Window *window);
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_MaximizeWindow
@ -1943,6 +2061,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_MinimizeWindow(SDL_Window *window);
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_MaximizeWindow
@ -1972,6 +2092,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_RestoreWindow(SDL_Window *window);
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GetWindowFullscreenMode
@ -1998,6 +2120,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowFullscreen(SDL_Window *window, boo
 * \returns true on success or false if the operation timed out before the
 *          window was in the requested state.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_SetWindowSize
@ -2017,6 +2141,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SyncWindow(SDL_Window *window);
 * \returns true if there is a surface associated with the window, or false
 *          otherwise.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GetWindowSurface
@ -2041,6 +2167,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_WindowHasSurface(SDL_Window *window);
 * \returns the surface associated with the window, or NULL on failure; call
 *          SDL_GetError() for more information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_DestroyWindowSurface
@ -2068,6 +2196,8 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_GetWindowSurface(SDL_Window *windo
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GetWindowSurfaceVSync
@ -2086,6 +2216,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowSurfaceVSync(SDL_Window *window, i
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_SetWindowSurfaceVSync
@ -2104,6 +2236,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowSurfaceVSync(SDL_Window *window, i
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GetWindowSurface
@ -2131,6 +2265,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_UpdateWindowSurface(SDL_Window *window);
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GetWindowSurface
@ -2145,6 +2281,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_UpdateWindowSurfaceRects(SDL_Window *window
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GetWindowSurface
@ -2176,6 +2314,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_DestroyWindowSurface(SDL_Window *window);
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GetWindowKeyboardGrab
@ -2193,6 +2333,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowKeyboardGrab(SDL_Window *window, b
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GetWindowMouseRect
@ -2208,6 +2350,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowMouseGrab(SDL_Window *window, bool
 * \param window the window to query.
 * \returns true if keyboard is grabbed, and false otherwise.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_SetWindowKeyboardGrab
@ -2220,6 +2364,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowKeyboardGrab(SDL_Window *window);
 * \param window the window to query.
 * \returns true if mouse is grabbed, and false otherwise.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GetWindowMouseRect
@ -2234,6 +2380,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowMouseGrab(SDL_Window *window);
 *
 * \returns the window if input is grabbed or NULL otherwise.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_SetWindowMouseGrab
@ -2253,6 +2401,8 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetGrabbedWindow(void);
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GetWindowMouseRect
@ -2268,6 +2418,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowMouseRect(SDL_Window *window, cons
 * \returns a pointer to the mouse confinement rectangle of a window, or NULL
 *          if there isn't one.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_SetWindowMouseRect
@ -2289,6 +2441,8 @@ extern SDL_DECLSPEC const SDL_Rect * SDLCALL SDL_GetWindowMouseRect(SDL_Window *
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GetWindowOpacity
@ -2305,6 +2459,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowOpacity(SDL_Window *window, float
 * \returns the opacity, (0.0f - transparent, 1.0f - opaque), or -1.0f on
 *          failure; call SDL_GetError() for more information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_SetWindowOpacity
@ -2337,6 +2493,8 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetWindowOpacity(SDL_Window *window);
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_SetWindowModal
@ -2354,6 +2512,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowParent(SDL_Window *window, SDL_Win
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_SetWindowParent
@ -2369,6 +2529,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowModal(SDL_Window *window, bool mod
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 */
 extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowFocusable(SDL_Window *window, bool focusable);
@ -2393,6 +2555,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowFocusable(SDL_Window *window, bool
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 */
 extern SDL_DECLSPEC bool SDLCALL SDL_ShowWindowSystemMenu(SDL_Window *window, int x, int y);
@ -2400,6 +2564,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_ShowWindowSystemMenu(SDL_Window *window, in
 /**
 * Possible return values from the SDL_HitTest callback.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This enum is available since SDL 3.1.3.
 *
 * \sa SDL_HitTest
@ -2470,6 +2636,8 @@ typedef SDL_HitTestResult (SDLCALL *SDL_HitTest)(SDL_Window *win,
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 */
 extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowHitTest(SDL_Window *window, SDL_HitTest callback, void *callback_data);
@ -2496,6 +2664,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowHitTest(SDL_Window *window, SDL_Hi
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 */
 extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowShape(SDL_Window *window, SDL_Surface *shape);
@ -2508,6 +2678,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowShape(SDL_Window *window, SDL_Surf
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 */
 extern SDL_DECLSPEC bool SDLCALL SDL_FlashWindow(SDL_Window *window, SDL_FlashOperation operation);
@ -2520,6 +2692,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_FlashWindow(SDL_Window *window, SDL_FlashOp
 *
 * \param window the window to destroy.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_CreatePopupWindow
@ -2538,6 +2712,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyWindow(SDL_Window *window);
 *
 * \returns true if the screensaver is enabled, false if it is disabled.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_DisableScreenSaver
@ -2551,6 +2727,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_ScreenSaverEnabled(void);
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_DisableScreenSaver
@ -2570,6 +2748,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_EnableScreenSaver(void);
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_EnableScreenSaver
@ -2598,6 +2778,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_DisableScreenSaver(void);
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GL_GetProcAddress
@ -2650,6 +2832,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GL_LoadLibrary(const char *path);
 * \returns a pointer to the named OpenGL function. The returned pointer
 *          should be cast to the appropriate function signature.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GL_ExtensionSupported
@ -2669,6 +2853,8 @@ extern SDL_DECLSPEC SDL_FunctionPointer SDLCALL SDL_GL_GetProcAddress(const char
 * \returns a pointer to the named EGL function. The returned pointer should
 *          be cast to the appropriate function signature.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_EGL_GetCurrentDisplay
@ -2678,6 +2864,8 @@ extern SDL_DECLSPEC SDL_FunctionPointer SDLCALL SDL_EGL_GetProcAddress(const cha
 /**
 * Unload the OpenGL library previously loaded by SDL_GL_LoadLibrary().
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GL_LoadLibrary
@ -2701,6 +2889,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_GL_UnloadLibrary(void);
 * \param extension the name of the extension to check.
 * \returns true if the extension is supported, false otherwise.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 */
 extern SDL_DECLSPEC bool SDLCALL SDL_GL_ExtensionSupported(const char *extension);
@ -2708,6 +2898,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GL_ExtensionSupported(const char *extension
 /**
 * Reset all previously set OpenGL context attributes to their default values.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GL_GetAttribute
@ -2729,6 +2921,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_GL_ResetAttributes(void);
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GL_GetAttribute
@ -2745,6 +2939,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GL_SetAttribute(SDL_GLAttr attr, int value)
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GL_ResetAttributes
@ -2767,6 +2963,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GL_GetAttribute(SDL_GLAttr attr, int *value
 * \returns the OpenGL context associated with `window` or NULL on failure;
 *          call SDL_GetError() for more information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GL_DestroyContext
@ -2784,6 +2982,8 @@ extern SDL_DECLSPEC SDL_GLContext SDLCALL SDL_GL_CreateContext(SDL_Window *windo
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GL_CreateContext
@ -2796,6 +2996,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GL_MakeCurrent(SDL_Window *window, SDL_GLCo
 * \returns the currently active OpenGL window on success or NULL on failure;
 *          call SDL_GetError() for more information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 */
 extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GL_GetCurrentWindow(void);
@ -2806,6 +3008,8 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GL_GetCurrentWindow(void);
 * \returns the currently active OpenGL context or NULL on failure; call
 *          SDL_GetError() for more information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GL_MakeCurrent
@ -2818,6 +3022,8 @@ extern SDL_DECLSPEC SDL_GLContext SDLCALL SDL_GL_GetCurrentContext(void);
 * \returns the currently active EGL display or NULL on failure; call
 *          SDL_GetError() for more information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 */
 extern SDL_DECLSPEC SDL_EGLDisplay SDLCALL SDL_EGL_GetCurrentDisplay(void);
@ -2828,6 +3034,8 @@ extern SDL_DECLSPEC SDL_EGLDisplay SDLCALL SDL_EGL_GetCurrentDisplay(void);
 * \returns the currently active EGL config or NULL on failure; call
 *          SDL_GetError() for more information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 */
 extern SDL_DECLSPEC SDL_EGLConfig SDLCALL SDL_EGL_GetCurrentConfig(void);
@ -2839,6 +3047,8 @@ extern SDL_DECLSPEC SDL_EGLConfig SDLCALL SDL_EGL_GetCurrentConfig(void);
 * \returns the EGLSurface pointer associated with the window, or NULL on
 *          failure.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 */
 extern SDL_DECLSPEC SDL_EGLSurface SDLCALL SDL_EGL_GetWindowSurface(SDL_Window *window);
@ -2859,6 +3069,8 @@ extern SDL_DECLSPEC SDL_EGLSurface SDLCALL SDL_EGL_GetWindowSurface(SDL_Window *
 *                              eglCreateContext. May be NULL.
 * \param userdata a pointer that is passed to the callbacks.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 */
 extern SDL_DECLSPEC void SDLCALL SDL_EGL_SetAttributeCallbacks(SDL_EGLAttribArrayCallback platformAttribCallback,
@ -2888,6 +3100,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_EGL_SetAttributeCallbacks(SDL_EGLAttribArra
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GL_GetSwapInterval
@ -2907,6 +3121,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GL_SetSwapInterval(int interval);
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GL_SetSwapInterval
@ -2927,6 +3143,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GL_GetSwapInterval(int *interval);
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 */
 extern SDL_DECLSPEC bool SDLCALL SDL_GL_SwapWindow(SDL_Window *window);
@ -2938,6 +3156,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GL_SwapWindow(SDL_Window *window);
 * \returns true on success or false on failure; call SDL_GetError() for more
 *          information.
 *
 * \threadsafety This function should only be called on the main thread.
 *
 * \since This function is available since SDL 3.1.3.
 *
 * \sa SDL_GL_CreateContext