SDL: Sync SDL3 wiki -> header (20250)

From 20250aecc5190f0036524b1c04083917fca2e621 Mon Sep 17 00:00:00 2001
From: SDL Wiki Bot <[EMAIL REDACTED]>
Date: Thu, 7 Dec 2023 18:27:25 +0000
Subject: [PATCH] Sync SDL3 wiki -> header

---
 include/SDL3/SDL_video.h | 148 +++++++++++++++++++++------------------
 1 file changed, 79 insertions(+), 69 deletions(-)

diff --git a/include/SDL3/SDL_video.h b/include/SDL3/SDL_video.h
index b6a0e608748c..ab7682001b14 100644
--- a/include/SDL3/SDL_video.h
+++ b/include/SDL3/SDL_video.h
@@ -630,10 +630,11 @@ extern DECLSPEC float SDLCALL SDL_GetWindowDisplayScale(SDL_Window *window);
  * change the window size when the window is not fullscreen, use
  * SDL_SetWindowSize().
  *
- * If the window is currently in the fullscreen state, this request is asynchronous
- * on some windowing systems and the new mode dimensions may not be applied
- * immediately upon the return of this function. If an immediate change is required,
- * call SDL_SyncWindow() to block until the changes have taken effect.
+ * If the window is currently in the fullscreen state, this request is
+ * asynchronous on some windowing systems and the new mode dimensions may not
+ * be applied immediately upon the return of this function. If an immediate
+ * change is required, call SDL_SyncWindow() to block until the changes have
+ * taken effect.
  *
  * When the new mode takes effect, an SDL_EVENT_WINDOW_RESIZED and/or an
  * SDL_EVENT_WINDOOW_PIXEL_SIZE_CHANGED event will be emitted with the new
@@ -1082,25 +1083,27 @@ extern DECLSPEC int SDLCALL SDL_SetWindowIcon(SDL_Window *window, SDL_Surface *i
 /**
  * Request that the window's position be set.
  *
- * If, at the time of this request, the window is in a fixed-size state such as
- * maximized, this request may be deferred until the window returns to a resizable
- * state.
+ * If, at the time of this request, the window is in a fixed-size state such
+ * as maximized, this request may be deferred until the window returns to a
+ * resizable state.
  *
- * This can be used to reposition fullscreen-desktop windows onto a different display,
- * however, exclusive fullscreen windows are locked to a specific display and can
- * only be repositioned programmatically via SDL_SetWindowFullscreenMode().
+ * This can be used to reposition fullscreen-desktop windows onto a different
+ * display, however, exclusive fullscreen windows are locked to a specific
+ * display and can only be repositioned programmatically via
+ * SDL_SetWindowFullscreenMode().
  *
- * On some windowing systems this request is asynchronous and the new coordinates
- * may not have have been applied immediately upon the return of this function.
- * If an immediate change is required, call SDL_SyncWindow() to block until the changes
- * have taken effect.
+ * On some windowing systems this request is asynchronous and the new
+ * coordinates may not have have been applied immediately upon the return of
+ * this function. If an immediate change is required, call SDL_SyncWindow() to
+ * block until the changes have taken effect.
  *
  * When the window position changes, an SDL_EVENT_WINDOW_MOVED event will be
- * emitted with the window's new coordinates. Note that the new coordinates may
- * not match the exact coordinates requested, as some windowing systems can restrict
- * the position of the window in certain scenarios (e.g. constraining the position
- * so the window is always within desktop bounds). Additionally, as this is just a
- * request, it can be denied by the windowing system.
+ * emitted with the window's new coordinates. Note that the new coordinates
+ * may not match the exact coordinates requested, as some windowing systems
+ * can restrict the position of the window in certain scenarios (e.g.
+ * constraining the position so the window is always within desktop bounds).
+ * Additionally, as this is just a request, it can be denied by the windowing
+ * system.
  *
  * \param window the window to reposition
  * \param x the x coordinate of the window, or `SDL_WINDOWPOS_CENTERED` or
@@ -1120,8 +1123,8 @@ extern DECLSPEC int SDLCALL SDL_SetWindowPosition(SDL_Window *window, int x, int
 /**
  * Get the position of a window.
  *
- * This is the current position of the window as last reported by the windowing
- * system.
+ * This is the current position of the window as last reported by the
+ * windowing system.
  *
  * If you do not need the value for one of the positions a NULL may be passed
  * in the `x` or `y` parameter.
@@ -1144,23 +1147,24 @@ extern DECLSPEC int SDLCALL SDL_GetWindowPosition(SDL_Window *window, int *x, in
  * NULL can safely be passed as the `w` or `h` parameter if the width or
  * height value is not desired.
  *
- * If, at the time of this request, the window in a fixed-size state, such
- * as maximized or fullscreen, the request will be deferred until the window
+ * If, at the time of this request, the window in a fixed-size state, such as
+ * maximized or fullscreen, the request will be deferred until the window
  * exits this state and becomes resizable again.
  *
- * To change the fullscreen mode of a window, use SDL_SetWindowFullscreenMode()
+ * To change the fullscreen mode of a window, use
+ * SDL_SetWindowFullscreenMode()
  *
- * On some windowing systems, this request is asynchronous and the new window size
- * may not have have been applied immediately upon the return of this function.
- * If an immediate change is required, call SDL_SyncWindow() to block until the
- * changes have taken effect.
+ * On some windowing systems, this request is asynchronous and the new window
+ * size may not have have been applied immediately upon the return of this
+ * function. If an immediate change is required, call SDL_SyncWindow() to
+ * block until the changes have taken effect.
  *
  * When the window size changes, an SDL_EVENT_WINDOW_RESIZED event will be
  * emitted with the new window dimensions. Note that the new dimensions may
  * not match the exact size requested, as some windowing systems can restrict
- * the window size in certain scenarios (e.g. constraining the size of the content
- * area to remain within the usable desktop bounds). Additionally, as this is just
- * a request, it can be denied by the windowing system.
+ * the window size in certain scenarios (e.g. constraining the size of the
+ * content area to remain within the usable desktop bounds). Additionally, as
+ * this is just a request, it can be denied by the windowing system.
  *
  * \param window the window to change
  * \param w the width of the window, must be > 0
@@ -1421,17 +1425,19 @@ extern DECLSPEC int SDLCALL SDL_RaiseWindow(SDL_Window *window);
  * Non-resizable windows can't be maximized. The window must have the
  * SDL_WINDOW_RESIZABLE flag set, or this will have no effect.
  *
- * On some windowing systems this request is asynchronous and the new window state
- * may not have have been applied immediately upon the return of this function.
- * If an immediate change is required, call SDL_SyncWindow() to block until the
- * changes have taken effect.
+ * On some windowing systems this request is asynchronous and the new window
+ * state may not have have been applied immediately upon the return of this
+ * function. If an immediate change is required, call SDL_SyncWindow() to
+ * block until the changes have taken effect.
  *
- * When the window state changes, an SDL_EVENT_WINDOW_MAXIMIZED event will be emitted.
- * Note that, as this is just a request, the windowing system can deny the state change.
+ * When the window state changes, an SDL_EVENT_WINDOW_MAXIMIZED event will be
+ * emitted. Note that, as this is just a request, the windowing system can
+ * deny the state change.
  *
- * When maximizing a window, whether the constraints set via SDL_SetWindowMaximumSize()
- * are honored depends on the policy of the window manager. Win32 and macOS enforce the
- * constraints when maximizing, while X11 and Wayland window managers may vary.
+ * When maximizing a window, whether the constraints set via
+ * SDL_SetWindowMaximumSize() are honored depends on the policy of the window
+ * manager. Win32 and macOS enforce the constraints when maximizing, while X11
+ * and Wayland window managers may vary.
  *
  * \param window the window to maximize
  * \returns 0 on success or a negative error code on failure; call
@@ -1448,13 +1454,14 @@ extern DECLSPEC int SDLCALL SDL_MaximizeWindow(SDL_Window *window);
 /**
  * Request that the window be minimized to an iconic representation.
  *
- * On some windowing systems this request is asynchronous and the new window state
- * may not have have been applied immediately upon the return of this function.
- * If an immediate change is required, call SDL_SyncWindow() to block until the
- * changes have taken effect.
+ * On some windowing systems this request is asynchronous and the new window
+ * state may not have have been applied immediately upon the return of this
+ * function. If an immediate change is required, call SDL_SyncWindow() to
+ * block until the changes have taken effect.
  *
- * When the window state changes, an SDL_EVENT_WINDOW_MINIMIZED event will be emitted.
- * Note that, as this is just a request, the windowing system can deny the state change.
+ * When the window state changes, an SDL_EVENT_WINDOW_MINIMIZED event will be
+ * emitted. Note that, as this is just a request, the windowing system can
+ * deny the state change.
  *
  * \param window the window to minimize
  * \returns 0 on success or a negative error code on failure; call
@@ -1469,15 +1476,17 @@ extern DECLSPEC int SDLCALL SDL_MaximizeWindow(SDL_Window *window);
 extern DECLSPEC int SDLCALL SDL_MinimizeWindow(SDL_Window *window);
 
 /**
- * Request that the size and position of a minimized or maximized window be restored.
+ * Request that the size and position of a minimized or maximized window be
+ * restored.
  *
- * On some windowing systems this request is asynchronous and the new window state
- * may not have have been applied immediately upon the return of this function.
- * If an immediate change is required, call SDL_SyncWindow() to block until the
- * changes have taken effect.
+ * On some windowing systems this request is asynchronous and the new window
+ * state may not have have been applied immediately upon the return of this
+ * function. If an immediate change is required, call SDL_SyncWindow() to
+ * block until the changes have taken effect.
  *
- * When the window state changes, an SDL_EVENT_WINDOW_RESTORED event will be emitted.
- * Note that, as this is just a request, the windowing system can deny the state change.
+ * When the window state changes, an SDL_EVENT_WINDOW_RESTORED event will be
+ * emitted. Note that, as this is just a request, the windowing system can
+ * deny the state change.
  *
  * \param window the window to restore
  * \returns 0 on success or a negative error code on failure; call
@@ -1497,14 +1506,14 @@ extern DECLSPEC int SDLCALL SDL_RestoreWindow(SDL_Window *window);
  * By default a window in fullscreen state uses fullscreen desktop mode, but a
  * specific display mode can be set using SDL_SetWindowFullscreenMode().
  *
- * On some windowing systems this request is asynchronous and the new fullscreen
- * state may not have have been applied immediately upon the return of this function.
- * If an immediate change is required, call SDL_SyncWindow() to block until the
- * changes have taken effect.
+ * On some windowing systems this request is asynchronous and the new
+ * fullscreen state may not have have been applied immediately upon the return
+ * of this function. If an immediate change is required, call SDL_SyncWindow()
+ * to block until the changes have taken effect.
  *
  * When the window state changes, an SDL_EVENT_WINDOW_ENTER_FULLSCREEN or
- * SDL_EVENT_WINDOW_LEAVE_FULLSCREEN event will be emitted. Note that, as this is
- * just a request, it can be denied by the windowing system.
+ * SDL_EVENT_WINDOW_LEAVE_FULLSCREEN event will be emitted. Note that, as this
+ * is just a request, it can be denied by the windowing system.
  *
  * \param window the window to change
  * \param fullscreen SDL_TRUE for fullscreen mode, SDL_FALSE for windowed mode
@@ -1522,19 +1531,20 @@ extern DECLSPEC int SDLCALL SDL_SetWindowFullscreen(SDL_Window *window, SDL_bool
 /**
  * Block until any pending window state is finalized.
  *
- * On asynchronous windowing systems, this acts as a synchronization barrier for
- * pending window state. It will attempt to wait until any pending window state
- * has been applied and is guaranteed to return within finite time. Note that for
- * how long it can potentially block depends on the underlying window system, as
- * window state changes may involve somewhat lengthy animations that must complete
- * before the window is in its final requested state.
+ * On asynchronous windowing systems, this acts as a synchronization barrier
+ * for pending window state. It will attempt to wait until any pending window
+ * state has been applied and is guaranteed to return within finite time. Note
+ * that for how long it can potentially block depends on the underlying window
+ * system, as window state changes may involve somewhat lengthy animations
+ * that must complete before the window is in its final requested state.
  *
  * On windowing systems where changes are immediate, this does nothing.
  *
- * \param window the window for which to wait for the pending state to be applied
- * \returns 0 on success, a positive value if the operation timed out before the
- *          window was in the requested state, or a negative error code on failure;
- *          call SDL_GetError() for more information.
+ * \param window the window for which to wait for the pending state to be
+ *               applied
+ * \returns 0 on success, a positive value if the operation timed out before
+ *          the window was in the requested state, or a negative error code on
+ *          failure; call SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  *