early-access version 1988
This commit is contained in:
pineappleEA
152
externals/SDL/include/SDL_video.h
vendored
152
externals/SDL/include/SDL_video.h
vendored
@@ -188,6 +188,9 @@ typedef enum
|
||||
SDL_DISPLAYEVENT_DISCONNECTED /**< Display has been removed from the system */
|
||||
} SDL_DisplayEventID;
|
||||
|
||||
/**
|
||||
* \brief Display orientation
|
||||
*/
|
||||
typedef enum
|
||||
{
|
||||
SDL_ORIENTATION_UNKNOWN, /**< The display orientation can't be determined */
|
||||
@@ -197,6 +200,16 @@ typedef enum
|
||||
SDL_ORIENTATION_PORTRAIT_FLIPPED /**< The display is in portrait mode, upside down */
|
||||
} SDL_DisplayOrientation;
|
||||
|
||||
/**
|
||||
* \brief Window flash operation
|
||||
*/
|
||||
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_FlashOperation;
|
||||
|
||||
/**
|
||||
* \brief An opaque handle to an OpenGL context.
|
||||
*/
|
||||
@@ -443,7 +456,7 @@ 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.
|
||||
*
|
||||
* \sa SDL_GetNumVideoDisplays()
|
||||
* \sa SDL_GetNumVideoDisplays
|
||||
*/
|
||||
extern DECLSPEC SDL_DisplayOrientation SDLCALL SDL_GetDisplayOrientation(int displayIndex);
|
||||
|
||||
@@ -532,12 +545,12 @@ extern DECLSPEC int SDLCALL SDL_GetCurrentDisplayMode(int displayIndex, SDL_Disp
|
||||
/**
|
||||
* Get the closest match to the requested display mode.
|
||||
*
|
||||
* The available display modes are scanned and `closest` is filled in with
|
||||
* the closest mode matching the requested mode and returned. The mode format
|
||||
* and refresh rate default to the desktop mode if they are set to 0. The
|
||||
* modes are scanned with size being first priority, format being second
|
||||
* priority, and finally checking the refresh rate. If all the available modes
|
||||
* are too small, then NULL is returned.
|
||||
* The available display modes are scanned and `closest` is filled in with the
|
||||
* closest mode matching the requested mode and returned. The mode format and
|
||||
* refresh rate default to the desktop mode if they are set to 0. The modes
|
||||
* are scanned with size being first priority, format being second priority,
|
||||
* and finally checking the refresh rate. If all the available modes are too
|
||||
* small, then NULL is returned.
|
||||
*
|
||||
* \param displayIndex the index of the display to query
|
||||
* \param mode an SDL_DisplayMode structure containing the desired display
|
||||
@@ -547,8 +560,8 @@ 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.
|
||||
*
|
||||
* \sa SDL_GetDisplayMode
|
||||
* \sa SDL_GetNumDisplayModes
|
||||
* \sa SDL_GetDisplayMode
|
||||
* \sa SDL_GetNumDisplayModes
|
||||
*/
|
||||
extern DECLSPEC SDL_DisplayMode * SDLCALL SDL_GetClosestDisplayMode(int displayIndex, const SDL_DisplayMode * mode, SDL_DisplayMode * closest);
|
||||
|
||||
@@ -638,13 +651,13 @@ extern DECLSPEC Uint32 SDLCALL SDL_GetWindowPixelFormat(SDL_Window * window);
|
||||
*
|
||||
* If the window is created with the `SDL_WINDOW_ALLOW_HIGHDPI` flag, its size
|
||||
* 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.
|
||||
* 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.
|
||||
*
|
||||
* 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 still fail. Window size is actually limited to 16384 x 16384 for all
|
||||
* `h` will not be used. However, invalid size parameters (e.g. too large) may
|
||||
* still fail. Window size is actually limited to 16384 x 16384 for all
|
||||
* platforms at window creation.
|
||||
*
|
||||
* If the window is created with any of the SDL_WINDOW_OPENGL or
|
||||
@@ -722,8 +735,8 @@ extern DECLSPEC Uint32 SDLCALL SDL_GetWindowID(SDL_Window * window);
|
||||
* these events to specific SDL_Window objects.
|
||||
*
|
||||
* \param id the ID of the window
|
||||
* \returns the window associated with `id` or NULL if it doesn't exist;
|
||||
* call SDL_GetError() for more information.
|
||||
* \returns the window associated with `id` or NULL if it doesn't exist; call
|
||||
* SDL_GetError() for more information.
|
||||
*
|
||||
* \sa SDL_GetWindowID
|
||||
*/
|
||||
@@ -1083,8 +1096,8 @@ extern DECLSPEC void SDLCALL SDL_MinimizeWindow(SDL_Window * window);
|
||||
*
|
||||
* \param window the window to restore
|
||||
*
|
||||
* \sa SDL_MaximizeWindow
|
||||
* \sa SDL_MinimizeWindow
|
||||
* \sa SDL_MaximizeWindow
|
||||
* \sa SDL_MinimizeWindow
|
||||
*/
|
||||
extern DECLSPEC void SDLCALL SDL_RestoreWindow(SDL_Window * window);
|
||||
|
||||
@@ -1190,8 +1203,8 @@ extern DECLSPEC void SDLCALL SDL_SetWindowGrab(SDL_Window * window,
|
||||
/**
|
||||
* Set a window's keyboard grab mode.
|
||||
*
|
||||
* 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.
|
||||
* 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.
|
||||
@@ -1207,10 +1220,6 @@ extern DECLSPEC void SDLCALL SDL_SetWindowKeyboardGrab(SDL_Window * window,
|
||||
* Set a window's mouse grab mode.
|
||||
*
|
||||
* \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.
|
||||
*
|
||||
* 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.
|
||||
*
|
||||
* \sa SDL_GetWindowMouseGrab
|
||||
* \sa SDL_SetWindowKeyboardGrab
|
||||
@@ -1244,7 +1253,7 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GetWindowKeyboardGrab(SDL_Window * window);
|
||||
* Get a window's mouse grab mode.
|
||||
*
|
||||
* \param window the window to query
|
||||
* \returns This returns SDL_TRUE if mouse is grabbed, and SDL_FALSE otherwise.
|
||||
* \returns SDL_TRUE if mouse is grabbed, and SDL_FALSE otherwise.
|
||||
*
|
||||
* \sa SDL_SetWindowKeyboardGrab
|
||||
* \sa SDL_GetWindowGrab
|
||||
@@ -1382,12 +1391,13 @@ extern DECLSPEC int SDLCALL SDL_SetWindowInputFocus(SDL_Window * window);
|
||||
* the video hardware. Each table is an array of 256 16-bit quantities,
|
||||
* representing a mapping between the input and output for that channel. The
|
||||
* input is the index into the array, and the output is the 16-bit gamma value
|
||||
* at that index, scaled to the output color precision. Despite the name and
|
||||
* signature, this method sets the gamma ramp of the entire display, not an
|
||||
* individual window. A window is considered to be owned by the display that
|
||||
* contains the window's center pixel. (The index of this display can be
|
||||
* retrieved using SDL_GetWindowDisplayIndex().) The gamma ramp set will not
|
||||
* follow the window if it is moved to another display.
|
||||
* at that index, scaled to the output color precision.
|
||||
*
|
||||
* Despite the name and signature, this method sets the gamma ramp of the
|
||||
* entire display, not an individual window. A window is considered to be
|
||||
* owned by the display that contains the window's center pixel. (The index of
|
||||
* this display can be retrieved using SDL_GetWindowDisplayIndex().) The gamma
|
||||
* ramp set will not follow the window if it is moved to another display.
|
||||
*
|
||||
* \param window the window used to select the display whose gamma ramp will
|
||||
* be changed
|
||||
@@ -1511,16 +1521,14 @@ extern DECLSPEC int SDLCALL SDL_SetWindowHitTest(SDL_Window * window,
|
||||
void *callback_data);
|
||||
|
||||
/**
|
||||
* Request a window to give a signal, e.g. a visual signal, to demand attention from the user.
|
||||
* Request a window to demand attention from the user.
|
||||
*
|
||||
* \param window the window to be flashed
|
||||
* \param operation the flash operation
|
||||
* \returns 0 on success or a negative error code on failure; call
|
||||
* SDL_GetError() for more information.
|
||||
*
|
||||
* \param window the window to request the flashing for
|
||||
* \param flash_count number of times the window gets flashed on systems that support flashing the
|
||||
* window multiple times, like Windows, else it is ignored
|
||||
*/
|
||||
extern DECLSPEC int SDLCALL SDL_FlashWindow(SDL_Window * window, Uint32 flash_count);
|
||||
extern DECLSPEC int SDLCALL SDL_FlashWindow(SDL_Window * window, SDL_FlashOperation operation);
|
||||
|
||||
/**
|
||||
* Destroy a window.
|
||||
@@ -1615,34 +1623,34 @@ extern DECLSPEC int SDLCALL SDL_GL_LoadLibrary(const char *path);
|
||||
* these quirks without any platform-specific code, though:
|
||||
*
|
||||
* - On Windows, function pointers are specific to the current GL context;
|
||||
* this means you need to have created a GL context and made it current before
|
||||
* calling SDL_GL_GetProcAddress(). If you recreate your context or create a
|
||||
* second context, you should assume that any existing function pointers
|
||||
* aren't valid to use with it. This is (currently) a Windows-specific
|
||||
* limitation, and in practice lots of drivers don't suffer this limitation,
|
||||
* but it is still the way the wgl API is documented to work and you should
|
||||
* expect crashes if you don't respect it. Store a copy of the function
|
||||
* pointers that comes and goes with context lifespan.
|
||||
* this means you need to have created a GL context and made it current
|
||||
* before calling SDL_GL_GetProcAddress(). If you recreate your context or
|
||||
* create a second context, you should assume that any existing function
|
||||
* pointers aren't valid to use with it. This is (currently) a
|
||||
* Windows-specific limitation, and in practice lots of drivers don't suffer
|
||||
* this limitation, but it is still the way the wgl API is documented to
|
||||
* work and you should expect crashes if you don't respect it. Store a copy
|
||||
* of the function pointers that comes and goes with context lifespan.
|
||||
* - On X11, function pointers returned by this function are valid for any
|
||||
* context, and can even be looked up before a context is created at all. This
|
||||
* means that, for at least some common OpenGL implementations, if you look up
|
||||
* a function that doesn't exist, you'll get a non-NULL result that is _NOT_
|
||||
* safe to call. You must always make sure the function is actually available
|
||||
* for a given GL context before calling it, by checking for the existence of
|
||||
* the appropriate extension with SDL_GL_ExtensionSupported(), or verifying
|
||||
* that the version of OpenGL you're using offers the function as core
|
||||
* functionality.
|
||||
* context, and can even be looked up before a context is created at all.
|
||||
* This means that, for at least some common OpenGL implementations, if you
|
||||
* look up a function that doesn't exist, you'll get a non-NULL result that
|
||||
* is _NOT_ safe to call. You must always make sure the function is actually
|
||||
* available for a given GL context before calling it, by checking for the
|
||||
* existence of the appropriate extension with SDL_GL_ExtensionSupported(),
|
||||
* or verifying that the version of OpenGL you're using offers the function
|
||||
* as core functionality.
|
||||
* - Some OpenGL drivers, on all platforms, *will* return NULL if a function
|
||||
* isn't supported, but you can't count on this behavior. Check for extensions
|
||||
* you use, and if you get a NULL anyway, act as if that extension wasn't
|
||||
* available. This is probably a bug in the driver, but you can code
|
||||
* defensively for this scenario anyhow.
|
||||
* isn't supported, but you can't count on this behavior. Check for
|
||||
* extensions you use, and if you get a NULL anyway, act as if that
|
||||
* extension wasn't available. This is probably a bug in the driver, but you
|
||||
* can code defensively for this scenario anyhow.
|
||||
* - Just because you're on Linux/Unix, don't assume you'll be using X11.
|
||||
* Next-gen display servers are waiting to replace it, and may or may not make
|
||||
* the same promises about function pointers.
|
||||
* Next-gen display servers are waiting to replace it, and may or may not
|
||||
* make the same promises about function pointers.
|
||||
* - OpenGL function pointers must be declared `APIENTRY` as in the example
|
||||
* code. This will ensure the proper calling convention is followed on
|
||||
* platforms where this matters (Win32) thereby avoiding stack corruption.
|
||||
* code. This will ensure the proper calling convention is followed on
|
||||
* platforms where this matters (Win32) thereby avoiding stack corruption.
|
||||
*
|
||||
* \param proc the name of an OpenGL function
|
||||
* \returns a pointer to the named OpenGL function. The returned pointer
|
||||
@@ -1690,18 +1698,16 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GL_ExtensionSupported(const char
|
||||
*
|
||||
* \sa SDL_GL_GetAttribute
|
||||
* \sa SDL_GL_SetAttribute
|
||||
* \sa <!-- #Remove this section if empty -->
|
||||
*/
|
||||
extern DECLSPEC void SDLCALL SDL_GL_ResetAttributes(void);
|
||||
|
||||
/**
|
||||
* Set an OpenGL window attribute before window creation.
|
||||
*
|
||||
* This function sets the OpenGL attribute `attr` to `value`. The
|
||||
* requested attributes should be set before creating an OpenGL window. You
|
||||
* should use SDL_GL_GetAttribute() to check the values after creating the
|
||||
* OpenGL context, since the values obtained can differ from the requested
|
||||
* ones.
|
||||
* This function sets the OpenGL attribute `attr` to `value`. The requested
|
||||
* attributes should be set before creating an OpenGL window. You should use
|
||||
* SDL_GL_GetAttribute() to check the values after creating the OpenGL
|
||||
* context, since the values obtained can differ from the requested ones.
|
||||
*
|
||||
* \param attr an SDL_GLattr enum value specifying the OpenGL attribute to set
|
||||
* \param value the desired value for the attribute
|
||||
@@ -1738,8 +1744,8 @@ extern DECLSPEC int SDLCALL SDL_GL_GetAttribute(SDL_GLattr attr, int *value);
|
||||
* SDL_GLContext is an alias for `void *`. It's opaque to the application.
|
||||
*
|
||||
* \param window the window to associate with the context
|
||||
* \returns the OpenGL context associated with `window` or NULL on error;
|
||||
* call SDL_GetError() for more details.
|
||||
* \returns the OpenGL context associated with `window` or NULL on error; call
|
||||
* SDL_GetError() for more details.
|
||||
*
|
||||
* \sa SDL_GL_DeleteContext
|
||||
* \sa SDL_GL_MakeCurrent
|
||||
@@ -1813,8 +1819,8 @@ extern DECLSPEC void SDLCALL SDL_GL_GetDrawableSize(SDL_Window * window, int *w,
|
||||
* Some systems allow specifying -1 for the interval, to enable adaptive
|
||||
* vsync. Adaptive vsync works the same as vsync, but if you've already missed
|
||||
* the vertical retrace for a given frame, it swaps buffers immediately, which
|
||||
* might be less jarring for the user during occasional framerate drops. If
|
||||
* an application requests adaptive vsync and the system does not support it,
|
||||
* might be less jarring for the user during occasional framerate drops. If an
|
||||
* application requests adaptive vsync and the system does not support it,
|
||||
* this function will fail and return -1. In such a case, you should probably
|
||||
* retry the call with 1 for the interval.
|
||||
*
|
||||
@@ -1863,8 +1869,8 @@ extern DECLSPEC int SDLCALL SDL_GL_GetSwapInterval(void);
|
||||
*
|
||||
* This is used with double-buffered OpenGL contexts, which are the default.
|
||||
*
|
||||
* On macOS, make sure you bind 0 to the draw framebuffer before swapping
|
||||
* the window, otherwise nothing will happen. If you aren't using
|
||||
* On macOS, make sure you bind 0 to the draw framebuffer before swapping the
|
||||
* window, otherwise nothing will happen. If you aren't using
|
||||
* glBindFramebuffer(), this is the default and you won't have to do anything
|
||||
* extra.
|
||||
*
|
||||
|
||||
Reference in New Issue
Block a user