Update to SDL 2.24.0 and add separate macOS UB2 dylib

Update mingw and macOS SDL libraries to 2.24.0. (MSVC .lib files and
Xcode project haven't been updated.)

There is now a separate SDL dylib for macOS Universal Binary 1 and 2
because SDL 2.24.0 dropped support for macOS 10.6 (which is last to
support x86). Documentation says SDL 2.24.0 also dropped macOS 10.7
and 10.8 too. So UB2 is now 10.9 or later while 10.5 to 10.8 live in
UB1.

Compiled using osxcross with macOS 11.3 SDK. Ran "strip -x" on Windows
and macOS libraries. Ad-hoc signed dylib using PyOxidizer rcodesign to
fix digest checksums after strip.

code/SDL2/include/SDL_video.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2022 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -174,7 +174,9 @@ typedef enum
     SDL_WINDOWEVENT_FOCUS_LOST,     /**< Window has lost keyboard focus */
     SDL_WINDOWEVENT_CLOSE,          /**< The window manager requests that the window be closed */
     SDL_WINDOWEVENT_TAKE_FOCUS,     /**< Window is being offered a focus (should SetWindowInputFocus() on itself or a subwindow, or ignore) */
-    SDL_WINDOWEVENT_HIT_TEST        /**< Window had a hit test that wasn't SDL_HITTEST_NORMAL. */
+    SDL_WINDOWEVENT_HIT_TEST,       /**< Window had a hit test that wasn't SDL_HITTEST_NORMAL. */
+    SDL_WINDOWEVENT_ICCPROF_CHANGED,/**< The ICC profile of the window's display has changed. */
+    SDL_WINDOWEVENT_DISPLAY_CHANGED /**< Window has been moved to display data1. */
 } SDL_WindowEventID;
 
 /**
@@ -207,7 +209,7 @@ typedef enum
 {
     SDL_FLASH_CANCEL,                   /**< Cancel any window flash state */
     SDL_FLASH_BRIEFLY,                  /**< Flash the window briefly to get attention */
-    SDL_FLASH_UNTIL_FOCUSED,            /**< Flash the window until it gets focus */
+    SDL_FLASH_UNTIL_FOCUSED             /**< Flash the window until it gets focus */
 } SDL_FlashOperation;
 
 /**
@@ -246,7 +248,8 @@ typedef enum
     SDL_GL_FRAMEBUFFER_SRGB_CAPABLE,
     SDL_GL_CONTEXT_RELEASE_BEHAVIOR,
     SDL_GL_CONTEXT_RESET_NOTIFICATION,
-    SDL_GL_CONTEXT_NO_ERROR
+    SDL_GL_CONTEXT_NO_ERROR,
+    SDL_GL_FLOATBUFFERS
 } SDL_GLattr;
 
 typedef enum
@@ -284,6 +287,8 @@ typedef enum
  * \returns a number >= 1 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
+ * \since This function is available since SDL 2.0.0.
+ *
  * \sa SDL_GetVideoDriver
  */
 extern DECLSPEC int SDLCALL SDL_GetNumVideoDrivers(void);
@@ -297,6 +302,8 @@ extern 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**.
  *
+ * \since This function is available since SDL 2.0.0.
+ *
  * \sa SDL_GetNumVideoDrivers
  */
 extern DECLSPEC const char *SDLCALL SDL_GetVideoDriver(int index);
@@ -323,6 +330,8 @@ extern DECLSPEC const char *SDLCALL SDL_GetVideoDriver(int index);
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
+ * \since This function is available since SDL 2.0.0.
+ *
  * \sa SDL_GetNumVideoDrivers
  * \sa SDL_GetVideoDriver
  * \sa SDL_InitSubSystem
@@ -335,6 +344,8 @@ extern DECLSPEC int SDLCALL SDL_VideoInit(const char *driver_name);
  *
  * This function closes all windows, and restores the original video mode.
  *
+ * \since This function is available since SDL 2.0.0.
+ *
  * \sa SDL_VideoInit
  */
 extern DECLSPEC void SDLCALL SDL_VideoQuit(void);
@@ -388,6 +399,8 @@ extern DECLSPEC const char * SDLCALL SDL_GetDisplayName(int displayIndex);
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
+ * \since This function is available since SDL 2.0.0.
+ *
  * \sa SDL_GetNumVideoDisplays
  */
 extern DECLSPEC int SDLCALL SDL_GetDisplayBounds(int displayIndex, SDL_Rect * rect);
@@ -432,6 +445,15 @@ extern DECLSPEC int SDLCALL SDL_GetDisplayUsableBounds(int displayIndex, SDL_Rec
  * A failure of this function usually means that either no DPI information is
  * available or the `displayIndex` is out of range.
  *
+ * **WARNING**: This reports the DPI that the hardware reports, and it is not
+ * always reliable! It is almost always better to use SDL_GetWindowSize() to
+ * find the window size, which might be in logical points instead of pixels,
+ * and then SDL_GL_GetDrawableSize(), SDL_Vulkan_GetDrawableSize(),
+ * SDL_Metal_GetDrawableSize(), or SDL_GetRendererOutputSize(), and compare
+ * the two values to get an actual scaling value between the two. We will be
+ * rethinking how high-dpi details should be managed in SDL3 to make things
+ * more consistent, reliable, and clear.
+ *
  * \param displayIndex the index of the display from which DPI information
  *                     should be queried
  * \param ddpi a pointer filled in with the diagonal DPI of the display; may
@@ -456,6 +478,8 @@ extern DECLSPEC int SDLCALL SDL_GetDisplayDPI(int displayIndex, float * ddpi, fl
  * \returns The SDL_DisplayOrientation enum value of the display, or
  *          `SDL_ORIENTATION_UNKNOWN` if it isn't available.
  *
+ * \since This function is available since SDL 2.0.9.
+ *
  * \sa SDL_GetNumVideoDisplays
  */
 extern DECLSPEC SDL_DisplayOrientation SDLCALL SDL_GetDisplayOrientation(int displayIndex);
@@ -495,6 +519,8 @@ extern DECLSPEC int SDLCALL SDL_GetNumDisplayModes(int displayIndex);
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
+ * \since This function is available since SDL 2.0.0.
+ *
  * \sa SDL_GetNumDisplayModes
  */
 extern DECLSPEC int SDLCALL SDL_GetDisplayMode(int displayIndex, int modeIndex,
@@ -514,6 +540,8 @@ extern DECLSPEC int SDLCALL SDL_GetDisplayMode(int displayIndex, int modeIndex,
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
+ * \since This function is available since SDL 2.0.0.
+ *
  * \sa SDL_GetCurrentDisplayMode
  * \sa SDL_GetDisplayMode
  * \sa SDL_SetWindowDisplayMode
@@ -534,6 +562,8 @@ extern DECLSPEC int SDLCALL SDL_GetDesktopDisplayMode(int displayIndex, SDL_Disp
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
+ * \since This function is available since SDL 2.0.0.
+ *
  * \sa SDL_GetDesktopDisplayMode
  * \sa SDL_GetDisplayMode
  * \sa SDL_GetNumVideoDisplays
@@ -560,11 +590,42 @@ extern DECLSPEC int SDLCALL SDL_GetCurrentDisplayMode(int displayIndex, SDL_Disp
  * \returns the passed in value `closest` or NULL if no matching video mode
  *          was available; call SDL_GetError() for more information.
  *
+ * \since This function is available since SDL 2.0.0.
+ *
  * \sa SDL_GetDisplayMode
  * \sa SDL_GetNumDisplayModes
  */
 extern DECLSPEC SDL_DisplayMode * SDLCALL SDL_GetClosestDisplayMode(int displayIndex, const SDL_DisplayMode * mode, SDL_DisplayMode * closest);
 
+/**
+ * Get the index of the display containing a point
+ *
+ * \param point the point to query
+ * \returns the index of the display containing the point or a negative error
+ *          code on failure; call SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.24.0.
+ *
+ * \sa SDL_GetDisplayBounds
+ * \sa SDL_GetNumVideoDisplays
+ */
+extern DECLSPEC int SDLCALL SDL_GetPointDisplayIndex(const SDL_Point * point);
+
+/**
+ * Get the index of the display primarily containing a rect
+ *
+ * \param rect the rect to query
+ * \returns the index of the display entirely containing the rect or closest
+ *          to the center of the rect on success or a negative error code on
+ *          failure; call SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.24.0.
+ *
+ * \sa SDL_GetDisplayBounds
+ * \sa SDL_GetNumVideoDisplays
+ */
+extern DECLSPEC int SDLCALL SDL_GetRectDisplayIndex(const SDL_Rect * rect);
+
 /**
  * Get the index of the display associated with a window.
  *
@@ -573,6 +634,8 @@ extern DECLSPEC SDL_DisplayMode * SDLCALL SDL_GetClosestDisplayMode(int displayI
  *          success or a negative error code on failure; call SDL_GetError()
  *          for more information.
  *
+ * \since This function is available since SDL 2.0.0.
+ *
  * \sa SDL_GetDisplayBounds
  * \sa SDL_GetNumVideoDisplays
  */
@@ -592,6 +655,8 @@ extern DECLSPEC int SDLCALL SDL_GetWindowDisplayIndex(SDL_Window * window);
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
+ * \since This function is available since SDL 2.0.0.
+ *
  * \sa SDL_GetWindowDisplayMode
  * \sa SDL_SetWindowFullscreen
  */
@@ -607,12 +672,28 @@ extern DECLSPEC int SDLCALL SDL_SetWindowDisplayMode(SDL_Window * window,
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
+ * \since This function is available since SDL 2.0.0.
+ *
  * \sa SDL_SetWindowDisplayMode
  * \sa SDL_SetWindowFullscreen
  */
 extern DECLSPEC int SDLCALL SDL_GetWindowDisplayMode(SDL_Window * window,
                                                      SDL_DisplayMode * mode);
 
+/**
+ * Get the raw ICC profile data for the screen the window is currently on.
+ *
+ * Data returned should be freed with SDL_free.
+ *
+ * \param window the window to query
+ * \param size the size of the ICC profile
+ * \returns the raw ICC profile data on success or NULL on failure; call
+ *          SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.18.
+ */
+extern DECLSPEC void* SDLCALL SDL_GetWindowICCProfile(SDL_Window * window, size_t* size);
+
 /**
  * Get the pixel format associated with the window.
  *
@@ -620,6 +701,8 @@ extern DECLSPEC int SDLCALL SDL_GetWindowDisplayMode(SDL_Window * window,
  * \returns the pixel format of the window on success or
  *          SDL_PIXELFORMAT_UNKNOWN on failure; call SDL_GetError() for more
  *          information.
+ *
+ * \since This function is available since SDL 2.0.0.
  */
 extern DECLSPEC Uint32 SDLCALL SDL_GetWindowPixelFormat(SDL_Window * window);
 
@@ -653,7 +736,10 @@ extern DECLSPEC Uint32 SDLCALL SDL_GetWindowPixelFormat(SDL_Window * window);
  * in pixels may differ from its size in screen coordinates on platforms with
  * high-DPI support (e.g. iOS and macOS). Use SDL_GetWindowSize() to query the
  * client area's size in screen coordinates, and SDL_GL_GetDrawableSize() or
- * SDL_GetRendererOutputSize() to query the drawable size in pixels.
+ * SDL_GetRendererOutputSize() to query the drawable size in pixels. Note that
+ * when this flag is set, the drawable size can vary after the window is
+ * created and should be queried after major window events such as when the
+ * window is resized or moved between displays.
  *
  * If the window is set fullscreen, the width and height parameters `w` and
  * `h` will not be used. However, invalid size parameters (e.g. too large) may
@@ -707,6 +793,8 @@ extern DECLSPEC SDL_Window * SDLCALL SDL_CreateWindow(const char *title,
  * \returns the window that was created or NULL on failure; call
  *          SDL_GetError() for more information.
  *
+ * \since This function is available since SDL 2.0.0.
+ *
  * \sa SDL_CreateWindow
  * \sa SDL_DestroyWindow
  */
@@ -738,6 +826,8 @@ extern DECLSPEC Uint32 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.
  *
+ * \since This function is available since SDL 2.0.0.
+ *
  * \sa SDL_GetWindowID
  */
 extern DECLSPEC SDL_Window * SDLCALL SDL_GetWindowFromID(Uint32 id);
@@ -748,6 +838,8 @@ extern DECLSPEC SDL_Window * SDLCALL SDL_GetWindowFromID(Uint32 id);
  * \param window the window to query
  * \returns a mask of the SDL_WindowFlags associated with `window`
  *
+ * \since This function is available since SDL 2.0.0.
+ *
  * \sa SDL_CreateWindow
  * \sa SDL_HideWindow
  * \sa SDL_MaximizeWindow
@@ -766,6 +858,8 @@ extern DECLSPEC Uint32 SDLCALL SDL_GetWindowFlags(SDL_Window * window);
  * \param window the window to change
  * \param title the desired window title in UTF-8 format
  *
+ * \since This function is available since SDL 2.0.0.
+ *
  * \sa SDL_GetWindowTitle
  */
 extern DECLSPEC void SDLCALL SDL_SetWindowTitle(SDL_Window * window,
@@ -778,6 +872,8 @@ extern DECLSPEC void SDLCALL SDL_SetWindowTitle(SDL_Window * window,
  * \returns the title of the window in UTF-8 format or "" if there is no
  *          title.
  *
+ * \since This function is available since SDL 2.0.0.
+ *
  * \sa SDL_SetWindowTitle
  */
 extern DECLSPEC const char *SDLCALL SDL_GetWindowTitle(SDL_Window * window);
@@ -787,6 +883,8 @@ extern DECLSPEC const char *SDLCALL SDL_GetWindowTitle(SDL_Window * window);
  *
  * \param window the window to change
  * \param icon an SDL_Surface structure containing the icon for the window
+ *
+ * \since This function is available since SDL 2.0.0.
  */
 extern DECLSPEC void SDLCALL SDL_SetWindowIcon(SDL_Window * window,
                                                SDL_Surface * icon);
@@ -801,6 +899,8 @@ extern DECLSPEC void SDLCALL SDL_SetWindowIcon(SDL_Window * window,
  * \param userdata the associated pointer
  * \returns the previous value associated with `name`.
  *
+ * \since This function is available since SDL 2.0.0.
+ *
  * \sa SDL_GetWindowData
  */
 extern DECLSPEC void* SDLCALL SDL_SetWindowData(SDL_Window * window,
@@ -814,6 +914,8 @@ extern DECLSPEC void* SDLCALL SDL_SetWindowData(SDL_Window * window,
  * \param name the name of the pointer
  * \returns the value associated with `name`.
  *
+ * \since This function is available since SDL 2.0.0.
+ *
  * \sa SDL_SetWindowData
  */
 extern DECLSPEC void *SDLCALL SDL_GetWindowData(SDL_Window * window,
@@ -830,6 +932,8 @@ extern DECLSPEC void *SDLCALL SDL_GetWindowData(SDL_Window * window,
  * \param y the y coordinate of the window in screen coordinates, or
  *          `SDL_WINDOWPOS_CENTERED` or `SDL_WINDOWPOS_UNDEFINED`
  *
+ * \since This function is available since SDL 2.0.0.
+ *
  * \sa SDL_GetWindowPosition
  */
 extern DECLSPEC void SDLCALL SDL_SetWindowPosition(SDL_Window * window,
@@ -847,6 +951,8 @@ extern DECLSPEC void SDLCALL SDL_SetWindowPosition(SDL_Window * window,
  * \param y a pointer filled in with the y position of the window, in screen
  *          coordinates, may be NULL
  *
+ * \since This function is available since SDL 2.0.0.
+ *
  * \sa SDL_SetWindowPosition
  */
 extern DECLSPEC void SDLCALL SDL_GetWindowPosition(SDL_Window * window,
@@ -869,6 +975,8 @@ extern DECLSPEC void SDLCALL SDL_GetWindowPosition(SDL_Window * window,
  * \param h the height of the window in pixels, in screen coordinates, must be
  *          > 0
  *
+ * \since This function is available since SDL 2.0.0.
+ *
  * \sa SDL_GetWindowSize
  * \sa SDL_SetWindowDisplayMode
  */
@@ -893,6 +1001,8 @@ extern DECLSPEC void SDLCALL SDL_SetWindowSize(SDL_Window * window, int w,
  * \param h a pointer filled in with the height of the window, in screen
  *          coordinates, may be NULL
  *
+ * \since This function is available since SDL 2.0.0.
+ *
  * \sa SDL_GL_GetDrawableSize
  * \sa SDL_Vulkan_GetDrawableSize
  * \sa SDL_SetWindowSize
@@ -943,6 +1053,8 @@ extern DECLSPEC int SDLCALL SDL_GetWindowBordersSize(SDL_Window * window,
  * \param min_w the minimum width of the window in pixels
  * \param min_h the minimum height of the window in pixels
  *
+ * \since This function is available since SDL 2.0.0.
+ *
  * \sa SDL_GetWindowMinimumSize
  * \sa SDL_SetWindowMaximumSize
  */
@@ -958,6 +1070,8 @@ extern DECLSPEC void SDLCALL SDL_SetWindowMinimumSize(SDL_Window * window,
  * \param h a pointer filled in with the minimum height of the window, may be
  *          NULL
  *
+ * \since This function is available since SDL 2.0.0.
+ *
  * \sa SDL_GetWindowMaximumSize
  * \sa SDL_SetWindowMinimumSize
  */
@@ -971,6 +1085,8 @@ extern DECLSPEC void SDLCALL SDL_GetWindowMinimumSize(SDL_Window * window,
  * \param max_w the maximum width of the window in pixels
  * \param max_h the maximum height of the window in pixels
  *
+ * \since This function is available since SDL 2.0.0.
+ *
  * \sa SDL_GetWindowMaximumSize
  * \sa SDL_SetWindowMinimumSize
  */
@@ -986,6 +1102,8 @@ extern DECLSPEC void SDLCALL SDL_SetWindowMaximumSize(SDL_Window * window,
  * \param h a pointer filled in with the maximum height of the window, may be
  *          NULL
  *
+ * \since This function is available since SDL 2.0.0.
+ *
  * \sa SDL_GetWindowMinimumSize
  * \sa SDL_SetWindowMaximumSize
  */
@@ -1031,25 +1149,29 @@ extern DECLSPEC void SDLCALL SDL_SetWindowResizable(SDL_Window * window,
                                                     SDL_bool resizable);
 
 /**
- *  \brief Set the window to always be above the others.
+ * Set the window to always be above the others.
  *
- *  This will add or remove the window's `SDL_WINDOW_ALWAYS_ON_TOP`
- *  flag. This will bring the window to the front and keep the window above
- *  the rest.
+ * This will add or remove the window's `SDL_WINDOW_ALWAYS_ON_TOP` flag. This
+ * will bring the window to the front and keep the window above the rest.
  *
- *  \param window The window of which to change the always on top state.
- *  \param on_top  SDL_TRUE to set the window always on top, SDL_FALSE to disable.
+ * \param window The window of which to change the always on top state
+ * \param on_top SDL_TRUE to set the window always on top, SDL_FALSE to
+ *               disable
  *
- *  \sa SDL_SetWindowAlwaysOnTop
+ * \since This function is available since SDL 2.0.16.
+ *
+ * \sa SDL_GetWindowFlags
  */
-
 extern DECLSPEC void SDLCALL SDL_SetWindowAlwaysOnTop(SDL_Window * window,
                                                       SDL_bool on_top);
+
 /**
  * Show a window.
  *
  * \param window the window to show
  *
+ * \since This function is available since SDL 2.0.0.
+ *
  * \sa SDL_HideWindow
  * \sa SDL_RaiseWindow
  */
@@ -1060,6 +1182,8 @@ extern DECLSPEC void SDLCALL SDL_ShowWindow(SDL_Window * window);
  *
  * \param window the window to hide
  *
+ * \since This function is available since SDL 2.0.0.
+ *
  * \sa SDL_ShowWindow
  */
 extern DECLSPEC void SDLCALL SDL_HideWindow(SDL_Window * window);
@@ -1068,6 +1192,8 @@ extern DECLSPEC void SDLCALL SDL_HideWindow(SDL_Window * window);
  * Raise a window above other windows and set the input focus.
  *
  * \param window the window to raise
+ *
+ * \since This function is available since SDL 2.0.0.
  */
 extern DECLSPEC void SDLCALL SDL_RaiseWindow(SDL_Window * window);
 
@@ -1076,6 +1202,8 @@ extern DECLSPEC void SDLCALL SDL_RaiseWindow(SDL_Window * window);
  *
  * \param window the window to maximize
  *
+ * \since This function is available since SDL 2.0.0.
+ *
  * \sa SDL_MinimizeWindow
  * \sa SDL_RestoreWindow
  */
@@ -1086,6 +1214,8 @@ extern DECLSPEC void SDLCALL SDL_MaximizeWindow(SDL_Window * window);
  *
  * \param window the window to minimize
  *
+ * \since This function is available since SDL 2.0.0.
+ *
  * \sa SDL_MaximizeWindow
  * \sa SDL_RestoreWindow
  */
@@ -1096,6 +1226,8 @@ extern DECLSPEC void SDLCALL SDL_MinimizeWindow(SDL_Window * window);
  *
  * \param window the window to restore
  *
+ * \since This function is available since SDL 2.0.0.
+ *
  * \sa SDL_MaximizeWindow
  * \sa SDL_MinimizeWindow
  */
@@ -1139,6 +1271,8 @@ extern DECLSPEC int SDLCALL SDL_SetWindowFullscreen(SDL_Window * window,
  * \returns the surface associated with the window, or NULL on failure; call
  *          SDL_GetError() for more information.
  *
+ * \since This function is available since SDL 2.0.0.
+ *
  * \sa SDL_UpdateWindowSurface
  * \sa SDL_UpdateWindowSurfaceRects
  */
@@ -1156,6 +1290,8 @@ extern DECLSPEC SDL_Surface * SDLCALL SDL_GetWindowSurface(SDL_Window * window);
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
+ * \since This function is available since SDL 2.0.0.
+ *
  * \sa SDL_GetWindowSurface
  * \sa SDL_UpdateWindowSurfaceRects
  */
@@ -1176,6 +1312,8 @@ extern DECLSPEC int SDLCALL SDL_UpdateWindowSurface(SDL_Window * window);
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
+ * \since This function is available since SDL 2.0.0.
+ *
  * \sa SDL_GetWindowSurface
  * \sa SDL_UpdateWindowSurface
  */
@@ -1186,7 +1324,9 @@ extern DECLSPEC int SDLCALL SDL_UpdateWindowSurfaceRects(SDL_Window * window,
 /**
  * Set a window's input grab mode.
  *
- * When input is grabbed the mouse is confined to the window.
+ * When input is grabbed, the mouse is confined to the window. This function
+ * will also grab the keyboard if `SDL_HINT_GRAB_KEYBOARD` is set. To grab the
+ * keyboard without also grabbing the mouse, use SDL_SetWindowKeyboardGrab().
  *
  * If the caller enables a grab while another window is currently grabbed, the
  * other window loses its grab in favor of the caller's window.
@@ -1194,6 +1334,8 @@ extern DECLSPEC int SDLCALL SDL_UpdateWindowSurfaceRects(SDL_Window * window,
  * \param window the window for which the input grab mode should be set
  * \param grabbed SDL_TRUE to grab input or SDL_FALSE to release input
  *
+ * \since This function is available since SDL 2.0.0.
+ *
  * \sa SDL_GetGrabbedWindow
  * \sa SDL_GetWindowGrab
  */
@@ -1203,12 +1345,27 @@ extern DECLSPEC void SDLCALL SDL_SetWindowGrab(SDL_Window * window,
 /**
  * Set a window's keyboard grab mode.
  *
+ * Keyboard grab enables capture of system keyboard shortcuts like Alt+Tab or
+ * the Meta/Super key. Note that not all system keyboard shortcuts can be
+ * captured by applications (one example is Ctrl+Alt+Del on Windows).
+ *
+ * This is primarily intended for specialized applications such as VNC clients
+ * or VM frontends. Normal games should not use keyboard grab.
+ *
+ * When keyboard grab is enabled, SDL will continue to handle Alt+Tab when the
+ * window is full-screen to ensure the user is not trapped in your
+ * application. If you have a custom keyboard shortcut to exit fullscreen
+ * mode, you may suppress this behavior with
+ * `SDL_HINT_ALLOW_ALT_TAB_WHILE_GRABBED`.
+ *
  * If the caller enables a grab while another window is currently grabbed, the
  * other window loses its grab in favor of the caller's window.
  *
  * \param window The window for which the keyboard grab mode should be set.
  * \param grabbed This is SDL_TRUE to grab keyboard, and SDL_FALSE to release.
  *
+ * \since This function is available since SDL 2.0.16.
+ *
  * \sa SDL_GetWindowKeyboardGrab
  * \sa SDL_SetWindowMouseGrab
  * \sa SDL_SetWindowGrab
@@ -1219,7 +1376,12 @@ extern DECLSPEC void SDLCALL SDL_SetWindowKeyboardGrab(SDL_Window * window,
 /**
  * Set a window's mouse grab mode.
  *
+ * Mouse grab confines the mouse cursor to the window.
+ *
  * \param window The window for which the mouse grab mode should be set.
+ * \param grabbed This is SDL_TRUE to grab mouse, and SDL_FALSE to release.
+ *
+ * \since This function is available since SDL 2.0.16.
  *
  * \sa SDL_GetWindowMouseGrab
  * \sa SDL_SetWindowKeyboardGrab
@@ -1234,6 +1396,8 @@ extern DECLSPEC void SDLCALL SDL_SetWindowMouseGrab(SDL_Window * window,
  * \param window the window to query
  * \returns SDL_TRUE if input is grabbed, SDL_FALSE otherwise.
  *
+ * \since This function is available since SDL 2.0.0.
+ *
  * \sa SDL_SetWindowGrab
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_GetWindowGrab(SDL_Window * window);
@@ -1244,6 +1408,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GetWindowGrab(SDL_Window * window);
  * \param window the window to query
  * \returns SDL_TRUE if keyboard is grabbed, and SDL_FALSE otherwise.
  *
+ * \since This function is available since SDL 2.0.16.
+ *
  * \sa SDL_SetWindowKeyboardGrab
  * \sa SDL_GetWindowGrab
  */
@@ -1255,6 +1421,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GetWindowKeyboardGrab(SDL_Window * window);
  * \param window the window to query
  * \returns SDL_TRUE if mouse is grabbed, and SDL_FALSE otherwise.
  *
+ * \since This function is available since SDL 2.0.16.
+ *
  * \sa SDL_SetWindowKeyboardGrab
  * \sa SDL_GetWindowGrab
  */
@@ -1272,6 +1440,38 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GetWindowMouseGrab(SDL_Window * window);
  */
 extern DECLSPEC SDL_Window * SDLCALL SDL_GetGrabbedWindow(void);
 
+/**
+ * Confines the cursor to the specified area of a window.
+ *
+ * Note that this does NOT grab the cursor, it only defines the area a cursor
+ * is restricted to when the window has mouse focus.
+ *
+ * \param window The window that will be associated with the barrier.
+ * \param rect A rectangle area in window-relative coordinates. If NULL the
+ *             barrier for the specified window will be destroyed.
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.18.
+ *
+ * \sa SDL_GetWindowMouseRect
+ * \sa SDL_SetWindowMouseGrab
+ */
+extern DECLSPEC int SDLCALL SDL_SetWindowMouseRect(SDL_Window * window, const SDL_Rect * rect);
+
+/**
+ * Get the mouse confinement rectangle of a window.
+ *
+ * \param window The window to query
+ * \returns A pointer to the mouse confinement rectangle of a window, or NULL
+ *          if there isn't one.
+ *
+ * \since This function is available since SDL 2.0.18.
+ *
+ * \sa SDL_SetWindowMouseRect
+ */
+extern DECLSPEC const SDL_Rect * SDLCALL SDL_GetWindowMouseRect(SDL_Window * window);
+
 /**
  * Set the brightness (gamma multiplier) for a given window's display.
  *
@@ -1293,6 +1493,8 @@ extern DECLSPEC SDL_Window * SDLCALL SDL_GetGrabbedWindow(void);
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
+ * \since This function is available since SDL 2.0.0.
+ *
  * \sa SDL_GetWindowBrightness
  * \sa SDL_SetWindowGammaRamp
  */
@@ -1311,6 +1513,8 @@ extern DECLSPEC int SDLCALL SDL_SetWindowBrightness(SDL_Window * window, float b
  * \returns the brightness for the display where 0.0 is completely dark and
  *          1.0 is normal brightness.
  *
+ * \since This function is available since SDL 2.0.0.
+ *
  * \sa SDL_SetWindowBrightness
  */
 extern DECLSPEC float SDLCALL SDL_GetWindowBrightness(SDL_Window * window);
@@ -1410,6 +1614,8 @@ extern DECLSPEC int SDLCALL SDL_SetWindowInputFocus(SDL_Window * window);
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
+ * \since This function is available since SDL 2.0.0.
+ *
  * \sa SDL_GetWindowGammaRamp
  */
 extern DECLSPEC int SDLCALL SDL_SetWindowGammaRamp(SDL_Window * window,
@@ -1436,6 +1642,8 @@ extern DECLSPEC int SDLCALL SDL_SetWindowGammaRamp(SDL_Window * window,
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
+ * \since This function is available since SDL 2.0.0.
+ *
  * \sa SDL_SetWindowGammaRamp
  */
 extern DECLSPEC int SDLCALL SDL_GetWindowGammaRamp(SDL_Window * window,
@@ -1527,6 +1735,8 @@ extern DECLSPEC int SDLCALL SDL_SetWindowHitTest(SDL_Window * window,
  * \param operation the flash operation
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.16.
  */
 extern DECLSPEC int SDLCALL SDL_FlashWindow(SDL_Window * window, SDL_FlashOperation operation);
 
@@ -1538,6 +1748,8 @@ extern DECLSPEC int SDLCALL SDL_FlashWindow(SDL_Window * window, SDL_FlashOperat
  *
  * \param window the window to destroy
  *
+ * \since This function is available since SDL 2.0.0.
+ *
  * \sa SDL_CreateWindow
  * \sa SDL_CreateWindowFrom
  */
@@ -1606,6 +1818,8 @@ extern DECLSPEC void SDLCALL SDL_DisableScreenSaver(void);
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
+ * \since This function is available since SDL 2.0.0.
+ *
  * \sa SDL_GL_GetProcAddress
  * \sa SDL_GL_UnloadLibrary
  */
@@ -1656,6 +1870,8 @@ extern DECLSPEC int 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.
  *
+ * \since This function is available since SDL 2.0.0.
+ *
  * \sa SDL_GL_ExtensionSupported
  * \sa SDL_GL_LoadLibrary
  * \sa SDL_GL_UnloadLibrary
@@ -1665,6 +1881,8 @@ extern DECLSPEC void *SDLCALL SDL_GL_GetProcAddress(const char *proc);
 /**
  * Unload the OpenGL library previously loaded by SDL_GL_LoadLibrary().
  *
+ * \since This function is available since SDL 2.0.0.
+ *
  * \sa SDL_GL_LoadLibrary
  */
 extern DECLSPEC void SDLCALL SDL_GL_UnloadLibrary(void);
@@ -1714,6 +1932,8 @@ extern DECLSPEC void SDLCALL SDL_GL_ResetAttributes(void);
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
+ * \since This function is available since SDL 2.0.0.
+ *
  * \sa SDL_GL_GetAttribute
  * \sa SDL_GL_ResetAttributes
  */
@@ -1727,6 +1947,8 @@ extern DECLSPEC int SDLCALL SDL_GL_SetAttribute(SDL_GLattr attr, int value);
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
+ * \since This function is available since SDL 2.0.0.
+ *
  * \sa SDL_GL_ResetAttributes
  * \sa SDL_GL_SetAttribute
  */
@@ -1747,6 +1969,8 @@ extern DECLSPEC int SDLCALL SDL_GL_GetAttribute(SDL_GLattr attr, int *value);
  * \returns the OpenGL context associated with `window` or NULL on error; call
  *          SDL_GetError() for more details.
  *
+ * \since This function is available since SDL 2.0.0.
+ *
  * \sa SDL_GL_DeleteContext
  * \sa SDL_GL_MakeCurrent
  */
@@ -1763,6 +1987,8 @@ extern DECLSPEC SDL_GLContext SDLCALL SDL_GL_CreateContext(SDL_Window *
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
+ * \since This function is available since SDL 2.0.0.
+ *
  * \sa SDL_GL_CreateContext
  */
 extern DECLSPEC int SDLCALL SDL_GL_MakeCurrent(SDL_Window * window,
@@ -1825,13 +2051,8 @@ extern DECLSPEC void SDLCALL SDL_GL_GetDrawableSize(SDL_Window * window, int *w,
  * retry the call with 1 for the interval.
  *
  * Adaptive vsync is implemented for some glX drivers with
- * GLX_EXT_swap_control_tear:
- *
- * https://www.opengl.org/registry/specs/EXT/glx_swap_control_tear.txt
- *
- * and for some Windows drivers with WGL_EXT_swap_control_tear:
- *
- * https://www.opengl.org/registry/specs/EXT/wgl_swap_control_tear.txt
+ * GLX_EXT_swap_control_tear, and for some Windows drivers with
+ * WGL_EXT_swap_control_tear.
  *
  * Read more on the Khronos wiki:
  * https://www.khronos.org/opengl/wiki/Swap_Interval#Adaptive_Vsync
@@ -1875,6 +2096,8 @@ extern DECLSPEC int SDLCALL SDL_GL_GetSwapInterval(void);
  * extra.
  *
  * \param window the window to change
+ *
+ * \since This function is available since SDL 2.0.0.
  */
 extern DECLSPEC void SDLCALL SDL_GL_SwapWindow(SDL_Window * window);
 
@@ -1883,6 +2106,8 @@ extern DECLSPEC void SDLCALL SDL_GL_SwapWindow(SDL_Window * window);
  *
  * \param context the OpenGL context to be deleted
  *
+ * \since This function is available since SDL 2.0.0.
+ *
  * \sa SDL_GL_CreateContext
  */
 extern DECLSPEC void SDLCALL SDL_GL_DeleteContext(SDL_GLContext context);