gitea/SDL3_fork
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Sync SDL3 wiki -> header

Browse Source
This commit is contained in:
SDL Wiki Bot
2023-12-07 18:27:25 +00:00
parent 4fd778119b
commit 20250aecc5
1 changed files with 79 additions and 69 deletions
Download Patch File Download Diff File Expand all files Collapse all files

148
include/SDL3/SDL_video.h
View File

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