NAME
SDL2::video - SDL Video Functions
SYNOPSIS
use SDL2 qw[:version];
SDL_GetVersion( my $ver = SDL2::version->new );
CORE::say sprintf 'SDL version %d.%d.%d', $ver->major, $ver->minor, $ver->patch;DESCRIPTION
SDL2::version represents the library's version as three levels: major, minor, and patch level.
Functions
These may be imported by name or with the :video tag.
SDL_GetNumVideoDrivers( )
Get the number of video drivers compiled into SDL.
my $num = SDL_GetNumVideoDrivers( );Returns a number >= 1 on success or a negative error code on failure; call SDL_GetError( ) for more information.
SDL_GetVideoDriver( ... )
Get the name of a built in video driver.
CORE::say SDL_GetVideoDriver($_) for 0 .. SDL_GetNumVideoDrivers( ) - 1;The video drivers are presented in the order in which they are normally checked during initialization.
Expected parameters include:
Returns the name of the video driver with the given index.
SDL_VideoInit( ... )
Initialize the video subsystem, optionally specifying a video driver.
SDL_VideoInit( 'x11' );This function initializes the video subsystem, setting up a connection to the window manager, etc, and determines the available display modes and pixel formats, but does not initialize a window or graphics mode.
If you use this function and you haven't used the SDL_INIT_VIDEO flag with either SDL_Init( ... ) or SDL_InitSubSystem( ... ), you should call SDL_VideoQuit( ) before calling SDL_Quit( ).
It is safe to call this function multiple times. SDL_VideoInit( ) will call SDL_VideoQuit( ) itself if the video subsystem has already been initialized.
You can use SDL_GetNumVideoDrivers( ) and SDL_GetVideoDriver( ) to find a specific driver_name.
Expected parameters include:
Returns 0 on success or a negative error code on failure; call SDL_GetError( ) for more information.
SDL_VideoQuit( )
Shut down the video subsystem, if initialized with SDL_VideoInit().
SDL_VideoQuit( );This function closes all windows, and restores the original video mode.
SDL_GetCurrentVideoDriver( ... )
Get the name of the currently initialized video driver.
my $driver = SDL_GetCurrentVideoDriver( );Returns the name of the current video driver or undef if no driver has been initialized.
SDL_GetNumVideoDisplays( ... )
Get the number of available video displays.
my $screens = SDL_GetNumVideoDisplays( );Returns a number >= 1 or a negative error code on failure; call SDL_GetError( ) for more information.
SDL_GetDisplayName( ... )
Get the name of a display in UTF-8 encoding.
my $screen = SDL_GetDisplayName( 0 );Expected parameters include:
Returns the name of a display or undef for an invalid display index or failure; call SDL_GetError( ) for more information.
SDL_GetDisplayBounds( ... )
Get the desktop area represented by a display.
SDL_GetDisplayBounds( 0, my $rect );The primary display (displayIndex zero) is always located at 0,0.
Expected parameters include:
displayIndex- the index of the display to queryrect- the SDL2::Rect structure filled in with the display bounds
Returns 0 on success or a negative error code on failure; call SDL_GetError( ) for more information.
SDL_GetDisplayUsableBounds( ... )
Get the usable desktop area represented by a display.
SDL_GetDisplayUsableBounds( 0, my $rect );The primary display (displayIndex zero) is always located at 0,0.
This is the same area as SDL_GetDisplayBounds( ... ) reports, but with portions reserved by the system removed. For example, on Apple's macOS, this subtracts the area occupied by the menu bar and dock.
Setting a window to be fullscreen generally bypasses these unusable areas, so these are good guidelines for the maximum space available to a non-fullscreen window.
The parameter rect is ignored if it is undef.
This function also returns -1 if the parameter displayIndex is out of range.
Expected parameters include:
displayIndex- the index of the display to query the usable bounds fromrect- the SDL2::Rect structure filled in with the display bounds
Returns 0 on success or a negative error code on failure; call SDL_GetError( ) for more information.
SDL_GetDisplayDPI( ... )
Get the dots/pixels-per-inch for a display.
SDL_GetDisplayDPI( 0, \my $ddpi, \my $hdpi, \my $vdpi );Diagonal, horizontal and vertical DPI can all be optionally returned if the appropriate parameter is non-NULL.
A failure of this function usually means that either no DPI information is available or the displayIndex is out of range.
Expected parameters include:
displayIndex- the index of the display from which DPI information should be queriedddpi- a pointer filled in with the diagonal DPI of the display; may beundefhdpi- a pointer filled in with the horizontal DPI of the display; may beundefvdpi- a pointer filled in with the vertical DPI of the display; may beundef
Returns 0 on success or a negative error code on failure; call SDL_GetError( ) for more information.
SDL_GetDisplayOrientation( ... )
Get the orientation of a display.
Expected parameters include:
Returns The SDL_DisplayOrientation enum value of the display, or SDL_ORIENTATION_UNKNOWN if it isn't available.
SDL_GetNumDisplayModes( ... )
Get the number of available display modes.
The displayIndex needs to be in the range from 0 to SDL_GetNumVideoDisplays( ) - 1.
Expected parameters include:
Returns a number >= 1 on success or a negative error code on failure; call SDL_GetError( ) for more information.
SDL_GetDisplayMode( ... )
Get information about a specific display mode.
The display modes are sorted in this priority:
- - width -> largest to smallest
- - height -> largest to smallest
- - bits per pixel -> more colors to fewer colors
- - packed pixel layout -> largest to smallest
- - refresh rate -> highest to lowest
Expected parameters include:
displayIndex- the index of the display to querymodeIndex- the index of the display mode to querymode- an SDL2::DisplayMode structure filled in with the mode atmodeIndex
Returns 0 on success or a negative error code on failure; call SDL_GetError( ) for more information.
SDL_GetDesktopDisplayMode( ... )
Get information about the desktop's display mode.
There's a difference between this function and SDL_GetCurrentDisplayMode( ... ) when SDL runs fullscreen and has changed the resolution. In that case this function will return the previous native display mode, and not the current display mode.
Expected parameters include:
displayIndex- the index of the display to querymode- an SDL2::DisplayMode structure filled in with the current display mode
Returns 0 on success or a negative error code on failure; call SDL_GetError( ) for more information.
SDL_GetCurrentDisplayMode( ... )
Get information about the current display mode.
There's a difference between this function and SDL_GetDesktopDisplayMode( ... ) when SDL runs fullscreen and has changed the resolution. In that case this function will return the current display mode, and not the previous native display mode.
Expected parameters include:
displayIndex- the index of the display to querymode- an SDL2::DisplayMode structure filled in with the current display mode
Returns 0 on success or a negative error code on failure; call SDL_GetError( ) for more information.
SDL_GetClosestDisplayMode( ... )
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 undef is returned.
Expected parameters include:
displayIndex- the index of the display to querymode- an SDL2::DisplayMode structure containing the desired display modeclosest- an SDL2::DisplayMode structure filled in with the closest match of the available display modes
Returns the passed in value closest or undef if no matching video mode was available; call SDL_GetError( ) for more information.
SDL_GetWindowDisplayIndex( ... )
Get the index of the display associated with a window.
Expected parameters include:
Returns the index of the display containing the center of the window on success or a negative error code on failure; call SDL_GetError( ) for more information.
SDL_SetWindowDisplayMode( ... )
Set the display mode to use when a window is visible at fullscreen.
This only affects the display mode used when the window is fullscreen. To change the window size when the window is not fullscreen, use SDL_SetWindowSize().
Expected parameters include:
window- the window to affectmode- the SDL2::DisplayMode structure representing the mode to use, orundefto use the window's dimensions and the desktop's format and refresh rate
Returns 0 on success or a negative error code on failure; call SDL_GetError( ) for more information.
SDL_GetWindowDisplayMode( ... )
Query the display mode to use when a window is visible at fullscreen.
Expected parameters include:
window- the window to querymode- an SDL2::DisplayMode structure filled in with the fullscreen display mode
Returns 0 on success or a negative error code on failure; call SDL_GetError( ) for more information.
SDL_GetWindowPixelFormat( ... )
Get the pixel format associated with the window.
Expected parameters include:
Returns the pixel format of the window on success or SDL_PIXELFORMAT_UNKNOWN on failure; call SDL_GetError( ) for more information.
SDL_CreateWindow( ... )
Create a window with the specified position, dimensions, and flags.
my $window = SDL_CreateWindow( 'Example',
SDL_WINDOWPOS_UNDEFINED, SDL_WINDOWPOS_UNDEFINED,
1280, 720,
SDL_WINDOW_SHOWN
);flags may be any of the following OR'd together:
SDL_WINDOW_FULLSCREEN- fullscreen windowSDL_WINDOW_FULLSCREEN_DESKTOP- fullscreen window at desktop resolutionSDL_WINDOW_OPENGL- window usable with an OpenGL contextSDL_WINDOW_VULKAN- window usable with a Vulkan instanceSDL_WINDOW_METAL- window usable with a Metal instanceSDL_WINDOW_HIDDEN- window is not visibleSDL_WINDOW_BORDERLESS- no window decorationSDL_WINDOW_RESIZABLE- window can be resizedSDL_WINDOW_MINIMIZED- window is minimizedSDL_WINDOW_MAXIMIZED- window is maximizedSDL_WINDOW_INPUT_GRABBED- window has grabbed input focusSDL_WINDOW_ALLOW_HIGHDPI- window should be created in high-DPI mode if supported (>= SDL 2.0.1)
SDL_WINDOW_SHOWN is ignored by SDL_CreateWindow( ). The SDL_Window is implicitly shown if SDL_WINDOW_HIDDEN is not set. SDL_WINDOW_SHOWN may be queried later using SDL_GetWindowFlags( ... ).
On Apple's macOS, you must set the NSHighResolutionCapable Info.plist property to YES, otherwise you will not receive a High-DPI OpenGL canvas.
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.
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 platforms at window creation.
If the window is created with any of the SDL_WINDOW_OPENGL or SDL_WINDOW_VULKAN flags, then the corresponding LoadLibrary function (SDL_GL_LoadLibrary( ... ) or SDL_Vulkan_LoadLibrary( ... )) is called and the corresponding UnloadLibrary function is called by SDL_DestroyWindow( ... ).
If SDL_WINDOW_VULKAN is specified and there isn't a working Vulkan driver, SDL_CreateWindow( ... ) will fail because SDL_Vulkan_LoadLibrary( ... ) will fail.
If SDL_WINDOW_METAL is specified on an OS that does not support Metal, SDL_CreateWindow( ... ) will fail.
On non-Apple devices, SDL requires you to either not link to the Vulkan loader or link to a dynamic library version. This limitation may be removed in a future version of SDL.
Expected parameters include:
title- the title of the window, in UTF-8 encodingx- the x position of the window,SDL_WINDOWPOS_CENTERED, orSDL_WINDOWPOS_UNDEFINEDy- the y position of the window,SDL_WINDOWPOS_CENTERED, orSDL_WINDOWPOS_UNDEFINEDw- the width of the window, in screen coordinatesh- the height of the window, in screen coordinatesflags-0, or one or moreSDL_WindowFlagsOR'd together
Returns the window that was created or NULL on failure; call SDL_GetError( ) for more information.
SDL_CreateWindowFrom( ... )
Create an SDL window from an existing native window.
In some cases (e.g. OpenGL) and on some platforms (e.g. Microsoft Windows) the hint SDL_HINT_VIDEO_WINDOW_SHARE_PIXEL_FORMAT needs to be configured before using SDL_CreateWindowFrom( ... ).
Expected parameters include:
data- a pointer to driver-dependent window creation data, typically your native window cast to a void*
Returns the window that was created or NULL on failure; call SDL_GetError( ) for more information.
SDL_GetWindowID( ... )
Get the numeric ID of a window.
The numeric ID is what SDL2::WindowEvent references, and is necessary to map these events to specific SDL2::Window objects.
Expected parameters include:
Returns the ID of the window on success or 0 on failure; call SDL_GetError( ) for more information.
SDL_GetWindowFromID( ... )
Get a window from a stored ID.
The numeric ID is what SDL2::WindowEvent references, and is necessary to map these events to specific SDL2::Window objects.
Expected parameters include:
Returns the window associated with id or undef if it doesn't exist; call SDL_GetError( ) for more information.
SDL_GetWindowFlags( ... )
Get the window flags.
Expected parameters include:
Returns a mask of the SDL_WindowFlags associated with window.
SDL_SetWindowTitle( ... )
Set the title of a window.
This string is expected to be in UTF-8 encoding.
Expected parameters include:
SDL_GetWindowTitle( ... )
Get the title of a window.
Expected parameters include:
Returns the title of the window in UTF-8 format or "" if there is no title.
SDL_SetWindowIcon( ... )
Set the icon for a window.
Expected parameters include:
window- the window to changeicon- an SDL2::Surface structure containing the icon for the window
SDL_SetWindowData( ... )
Associate an arbitrary named pointer with a window.
name is case-sensitive.
Expected parameters include:
window- the window to associate with the pointername- the name of the pointeruserdata- the associated pointer
Returns the previous value associated with name.
SDL_GetWindowData( ... )
Retrieve the data pointer associated with a window.
Expected parameters include:
Returns the value associated with name.
SDL_SetWindowPosition( ... )
Set the position of a window.
The window coordinate origin is the upper left of the display.
Expected parameters include:
window- the window to repositionx- the x coordinate of the window in screen coordinates, orSDL_WINDOWPOS_CENTEREDorSDL_WINDOWPOS_UNDEFINEDy- the y coordinate of the window in screen coordinates, orSDL_WINDOWPOS_CENTEREDorSDL_WINDOWPOS_UNDEFINED
SDL_GetWindowPosition( ... )
Get the position of a window.
If you do not need the value for one of the positions a undef may be passed in the x or y parameter.
Expected parameters include:
window- the window to queryx- a pointer filled in with the x position of the window, in screen coordinates, may beundefy- a pointer filled in with the y position of the window, in screen coordinates, may beundef
SDL_SetWindowSize( ... )
Set the size of a window's client area.
The window size in screen coordinates may differ from the size in pixels, if the window was created with SDL_WINDOW_ALLOW_HIGHDPI on a platform with high-dpi support (e.g. iOS or macOS). Use SDL_GL_GetDrawableSize( ... ) or SDL_GetRendererOutputSize( ... ) to get the real client area size in pixels.
Fullscreen windows automatically match the size of the display mode, and you should use SDL_SetWindowDisplayMode( ... ) to change their size.
Expected parameters include:
window- the window to changew- the width of the window in pixels, in screen coordinates, must be > 0h- the height of the window in pixels, in screen coordinates, must be > 0
SDL_GetWindowSize( ... )
Get the size of a window's client area.
undef can safely be passed as the w or h parameter if the width or height value is not desired.
The window size in screen coordinates may differ from the size in pixels, if the window was created with SDL_WINDOW_ALLOW_HIGHDPI on a platform with high-dpi support (e.g. iOS or macOS). Use SDL_GL_GetDrawableSize(), SDL_Vulkan_GetDrawableSize( ... ), or SDL_GetRendererOutputSize( ... ) to get the real client area size in pixels.
Expected parameters include:
window- the window to query the width and height fromw- a pointer filled in with the width of the window, in screen coordinates, may beundefh- a pointer filled in with the height of the window, in screen coordinates, may beundef
SDL_GetWindowBordersSize( ... )
Get the size of a window's borders (decorations) around the client area.
Note: If this function fails (returns -1), the size values will be initialized to 0, 0, 0, 0 (if a non-NULL pointer is provided), as if the window in question was borderless.
Note: This function may fail on systems where the window has not yet been decorated by the display server (for example, immediately after calling SDL_CreateWindow( ... )). It is recommended that you wait at least until the window has been presented and composited, so that the window system has a chance to decorate the window and provide the border dimensions to SDL.
This function also returns -1 if getting the information is not supported.
Expected parameters include:
window- the window to query the size values of the border (decorations) fromtop- pointer to variable for storing the size of the top border;undefis permittedleft- pointer to variable for storing the size of the left border;undefis permittedbottom- pointer to variable for storing the size of the bottom border;undefis permittedright- pointer to variable for storing the size of the right border;undefis permitted
Returns 0 on success or a negative error code on failure; call SDL_GetError( ) for more information.
SDL_SetWindowMinimumSize( ... )
Set the minimum size of a window's client area.
Expected parameters include:
window- the window to changemin_w- the minimum width of the window in pixelsmin_h- the minimum height of the window in pixels
SDL_GetWindowMinimumSize( ... )
Get the minimum size of a window's client area.
Expected parameters include:
window- the window to queryw- a pointer filled in with the minimum width of the window, may beundefh- a pointer filled in with the minimum height of the window, may beundef
SDL_SetWindowMaximumSize( ... )
Set the maximum size of a window's client area.
Expected parameters include:
window- the window to changemax_w- the maximum width of the window in pixelsmax_h- the maximum height of the window in pixels
SDL_GetWindowMaximumSize( ... )
Get the maximum size of a window's client area.
Expected parameters include:
window- the window to queryw- a pointer filled in with the maximum width of the window, may beundefh- a pointer filled in with the maximum height of the window, may beundef
SDL_SetWindowBordered( ... )
Set the border state of a window.
This will add or remove the window's SDL_WINDOW_BORDERLESS flag and add or remove the border from the actual window. This is a no-op if the window's border already matches the requested state.
You can't change the border state of a fullscreen window.
Expected parameters include:
window- the window of which to change the border statebordered-SDL_FALSEto remove border,SDL_TRUEto add border
SDL_SetWindowResizable( ... )
Set the user-resizable state of a window.
This will add or remove the window's `SDL_WINDOW_RESIZABLE` flag and allow/disallow user resizing of the window. This is a no-op if the window's resizable state already matches the requested state.
You can't change the resizable state of a fullscreen window.
Expected parameters include:
window- the window of which to change the resizable stateresizable-SDL_TRUEto allow resizing,SDL_FALSEto disallow
SDL_SetWindowAlwaysOnTop( ... )
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.
Expected parameters include:
window- window of which to change the always on top stateon_top-SDL_TRUEto set the window always on top,SDL_FALSEto disable
SDL_ShowWindow( ... )
Show a window.
Expected parameters include:
SDL_HideWindow( ... )
Hide a window.
Expected parameters include:
SDL_RaiseWindow( ... )
Raise a window above other windows and set the input focus.
Expected parameters include:
SDL_MaximizeWindow( ... )
Make a window as large as possible.
Expected parameters include:
SDL_MinimizeWindow( ... )
Minimize a window to an iconic representation.
Expected parameters include:
SDL_RestoreWindow( ... )
Restore the size and position of a minimized or maximized window.
Expected parameters include:
SDL_SetWindowFullscreen( ... )
Set a window's fullscreen state.
flags may be SDL_WINDOW_FULLSCREEN, for "real" fullscreen with a videomode change; SDL_WINDOW_FULLSCREEN_DESKTOP for "fake" fullscreen that takes the size of the desktop; and 0 for windowed mode.
Expected parameters include:
Returns 0 on success or a negative error code on failure; call SDL_GetError( ) for more information.
SDL_GetWindowSurface( ... )
Get the SDL surface associated with the window.
A new surface will be created with the optimal format for the window, if necessary. This surface will be freed when the window is destroyed. Do not free this surface.
This surface will be invalidated if the window is resized. After resizing a window this function must be called again to return a valid surface.
You may not combine this with 3D or the rendering API on this window.
This function is affected by SDL_HINT_FRAMEBUFFER_ACCELERATION.
Expected parameters include:
Returns the surface associated with the window, or NULL on failure; call SDL_GetError( ) for more information.
SDL_UpdateWindowSurface( ... )
Copy the window surface to the screen.
This is the function you use to reflect any changes to the surface on the screen.
Expected parameters include:
Returns 0 on success or a negative error code on failure; call SDL_GetError( ) for more information.
SDL_UpdateWindowSurfaceRects( ... )
Copy areas of the window surface to the screen.
This is the function you use to reflect changes to portions of the surface on the screen.
Expected parameters include:
window- the window to updaterects- an array of SDL2::Rect structures representing areas of the surface to copynumrects- the number of rectangles
Returns 0 on success or a negative error code on failure; call SDL_GetError( ) for more information.
SDL_SetWindowGrab( ... )
Set a window's input grab mode.
When input is grabbed the mouse is confined to the 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.
Expected parameters include:
window- the window for which the input grab mode should be setgrabbed-SDL_TRUEto grab input orSDL_FALSEto release input
SDL_SetWindowKeyboardGrab( ... )
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.
Expected parameters include:
window- window for which the keyboard grab mode should be setgrabbed-SDL_TRUEto grab keyboard,SDL_FALSEto release
SDL_SetWindowMouseGrab( ... )
Set a window's mouse grab mode.
Expected parameters include:
SDL_GetWindowGrab( ... )
Get a window's input grab mode.
Expected parameters include:
Returns SDL_TRUE if input is grabbed, SDL_FALSE otherwise.
SDL_GetWindowKeyboardGrab( ... )
Get a window's keyboard grab mode.
Expected parameters include:
Returns SDL_TRUE if keyboard is grabbed, and SDL_FALSE otherwise.
SDL_GetWindowMouseGrab( ... )
Get a window's mouse grab mode.
Expected parameters include:
Returns SDL_TRUE if mouse is grabbed, and SDL_FALSE otherwise.
SDL_GetGrabbedWindow( )
Get the window that currently has an input grab enabled.
Returns the window if input is grabbed or undef otherwise.
SDL_SetWindowBrightness( ... )
Set the brightness (gamma multiplier) for a given window's display.
Despite the name and signature, this method sets the brightness 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 brightness set will not follow the window if it is moved to another display.
Many platforms will refuse to set the display brightness in modern times. You are better off using a shader to adjust gamma during rendering, or something similar.
Expected parameters include:
window- the window used to select the display whose brightness will be changedbrightness- the brightness (gamma multiplier) value to set where0.0is completely dark and1.0is normal brightness
Returns 0 on success or a negative error code on failure; call SDL_GetError( ) for more information.
SDL_GetWindowBrightness( ... )
Get the brightness (gamma multiplier) for a given window's display.
Despite the name and signature, this method retrieves the brightness 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( ... ).)
Expected parameters include:
Returns the brightness for the display where 0.0 is completely dark and 1.0 is normal brightness.
SDL_SetWindowOpacity( ... )
Set the opacity for a window.
The parameter opacity will be clamped internally between 0.0 (transparent) and 1.0 (opaque).
This function also returns -1 if setting the opacity isn't supported.
Expected parameters include:
window- the window which will be made transparent or opaqueopacity- the opacity value (0.0- transparent,1.0- opaque)
Returns 0 on success or a negative error code on failure; call SDL_GetError( ) for more information.
SDL_GetWindowOpacity( ... )
Get the opacity of a window.
If transparency isn't supported on this platform, opacity will be reported as 1.0 without error.
The parameter opacity is ignored if it is undef.
This function also returns -1 if an invalid window was provided.
Expected parameters include:
window- the window to get the current opacity value fromout_opacity- the float filled in (0.0f - transparent, 1.0f - opaque)
Returns 0 on success or a negative error code on failure; call SDL_GetError( ) for more information.
SDL_SetWindowModalFor( ... )
Set the window as a modal for another window.
Expected parameters include:
modal_window- the window that should be set modalparent_window- the parent window for the modal window
Returns 0 on success or a negative error code on failure; call SDL_GetError( ) for more information.
SDL_SetWindowInputFocus( ... )
Explicitly set input focus to the window.
You almost certainly want SDL_RaiseWindow( ... ) instead of this function. Use this with caution, as you might give focus to a window that is completely obscured by other windows.
Expected parameters include:
Returns 0 on success or a negative error code on failure; call SDL_GetError( ) for more information.
SDL_SetWindowGammaRamp( ... )
Set the gamma ramp for the display that owns a given window.
Set the gamma translation table for the red, green, and blue channels of 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.
Expected parameters include:
window- the window used to select the display whose gamma ramp will be changedred- a 256 element array of 16-bit quantities representing the translation table for the red channel, orundefgreen- a 256 element array of 16-bit quantities representing the translation table for the green channel, orundefblue- a 256 element array of 16-bit quantities representing the translation table for the blue channel, orundef
Returns 0 on success or a negative error code on failure; call SDL_GetError( ) for more information.
SDL_GetWindowGammaRamp( ... )
Get the gamma ramp for a given window's display.
Despite the name and signature, this method retrieves 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( ... ).)
Expected parameters include:
window- the window used to select the display whose gamma ramp will be queriedred- a 256 element array of 16-bit quantities filled in with the translation table for the red channel, orundefgreen- a 256 element array of 16-bit quantities filled in with the translation table for the green channel, orundefblue- a 256 element array of 16-bit quantities filled in with the translation table for the blue channel, orundef
Returns 0 on success or a negative error code on failure; call SDL_GetError( ) for more information.
SDL_SetWindowHitTest( ... )
Provide a callback that decides if a window region has special properties.
Normally windows are dragged and resized by decorations provided by the system window manager (a title bar, borders, etc), but for some apps, it makes sense to drag them from somewhere else inside the window itself; for example, one might have a borderless window that wants to be draggable from any part, or simulate its own title bar, etc.
This function lets the app provide a callback that designates pieces of a given window as special. This callback is run during event processing if we need to tell the OS to treat a region of the window specially; the use of this callback is known as "hit testing."
Mouse input may not be delivered to your application if it is within a special area; the OS will often apply that input to moving the window or resizing the window and not deliver it to the application.
Specifying undef for a callback disables hit-testing. Hit-testing is disabled by default.
Platforms that don't support this functionality will return -1 unconditionally, even if you're attempting to disable hit-testing.
Your callback may fire at any time, and its firing does not indicate any specific behavior (for example, on Windows, this certainly might fire when the OS is deciding whether to drag your window, but it fires for lots of other reasons, too, some unrelated to anything you probably care about _and when the mouse isn't actually at the location it is testing_). Since this can fire at any time, you should try to keep your callback efficient, devoid of allocations, etc.
Expected parameters include:
window- the window to set hit-testing oncallback- the function to call when doing a hit-testcallback_data- an app-defined void pointer passed tocallback
Returns 0 on success or -1 on error (including unsupported); call SDL_GetError( ) for more information.
SDL_FlashWindow( ... )
Request a window to demand attention from the user.
Expected parameters include:
Returns 0 on success or a negative error code on failure; call SDL_GetError( ) for more information.
SDL_DestroyWindow( ... )
Destroy a window.
If window is undef, this function will return immediately after setting the SDL error message to "Invalid window". See SDL_GetError( ).
Expected parameters include:
SDL_IsScreenSaverEnabled( )
Check whether the screensaver is currently enabled.
The screensaver is disabled by default since SDL 2.0.2. Before SDL 2.0.2 the screensaver was enabled by default.
The default can also be changed using `SDL_HINT_VIDEO_ALLOW_SCREENSAVER`.
Returns SDL_TRUE if the screensaver is enabled, SDL_FALSE if it is disabled.
SDL_EnableScreenSaver( )
Allow the screen to be blanked by a screen saver.
SDL_EnableScreenSaver( );SDL_DisableScreenSaver( )
Prevent the screen from being blanked by a screen saver.
SDL_DisableScreenSaver( );If you disable the screensaver, it is automatically re-enabled when SDL quits.
SDL_GL_LoadLibrary( ... )
Dynamically load an OpenGL library.
This should be done after initializing the video driver, but before creating any OpenGL windows. If no OpenGL library is loaded, the default library will be loaded upon creation of the first OpenGL window.
If you do this, you need to retrieve all of the GL functions used in your program from the dynamic library using SDL_GL_GetProcAddress( ... ).
Expected parameters include:
Returns 0 on success or a negative error code on failure; call SDL_GetError( ) for more information.
SDL_GL_GetProcAddress( ... )
Get an OpenGL function by name.
If the GL library is loaded at runtime with SDL_GL_LoadLibrary( ... ), then all GL functions must be retrieved this way. Usually this is used to retrieve function pointers to OpenGL extensions.
There are some quirks to looking up OpenGL functions that require some extra care from the application. If you code carefully, you can handle 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.
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.
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.
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.
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.
Expected parameters include:
Returns a pointer to the named OpenGL function. The returned pointer should be cast to the appropriate function signature.
SDL_GL_UnloadLibrary( )
Unload the OpenGL library previously loaded by SDL_GL_LoadLibrary( ... ).
SDL_GL_ExtensionSupported( ... )
Check if an OpenGL extension is supported for the current context.
This function operates on the current GL context; you must have created a context and it must be current before calling this function. Do not assume that all contexts you create will have the same set of extensions available, or that recreating an existing context will offer the same extensions again.
While it's probably not a massive overhead, this function is not an O(1) operation. Check the extensions you care about after creating the GL context and save that information somewhere instead of calling the function every time you need to know.
Expected parameters include:
Returns SDL_TRUE if the extension is supported, SDL_FALSE otherwise.
SDL_GL_ResetAttributes( )
Reset all previously set OpenGL context attributes to their default values.
<SDL_GL_SetAttribute( ... )>
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.
Expected parameters include;
attr- anSDL_GLattrenum value specifying the OpenGL attribute to setvalue- the desired value for the attribute
Returns 0 on success or a negative error code on failure; call SDL_GetError( ) for more information.
SDL_GL_GetAttribute( ... )
Get the actual value for an attribute from the current context.
Expected parameters include:
attr- an SDL_GLattr enum value specifying the OpenGL attribute to getvalue- a pointer filled in with the current value ofattr
Returns 0 on success or a negative error code on failure; call SDL_GetError( ) for more information.
SDL_GL_CreateContext( ... )
Create an OpenGL context for an OpenGL window, and make it current.
Windows users new to OpenGL should note that, for historical reasons, GL functions added after OpenGL version 1.1 are not available by default. Those functions must be loaded at run-time, either with an OpenGL extension-handling library or with SDL_GL_GetProcAddress( ... ) and its related functions.
SDL_GLContext is an alias for void *. It's opaque to the application.
Expected parameters include:
Returns the OpenGL context associated with window or NULL on error; call SDL_GetError( ) for more details.
SDL_GL_MakeCurrent( ... )
Set up an OpenGL context for rendering into an OpenGL window.
The context must have been created with a compatible window.
Expected parameters include:
window- the window to associate with the contextcontext- the OpenGL context to associate with the window
Returns 0 on success or a negative error code on failure; call SDL_GetError( ) for more information.
SDL_GL_GetCurrentWindow( )
Get the currently active OpenGL window.
Returns the currently active OpenGL window on success or undef on failure; call SDL_GetError( ) for more information.
SDL_GL_GetCurrentContext( )
Get the currently active OpenGL context.
Returns the currently active OpenGL context or undef on failure; call SDL_GetError( ) for more information.
SDL_GL_GetDrawableSize( ... )
Get the size of a window's underlying drawable in pixels.
This returns info useful for calling glViewport( ).
This may differ from SDL_GetWindowSize( ... ) if we're rendering to a high-DPI drawable, i.e. the window was created with SDL_WINDOW_ALLOW_HIGHDPI on a platform with high-DPI support (Apple calls this "Retina"), and not disabled by the SDL_HINT_VIDEO_HIGHDPI_DISABLED hint.
Expected parameters include:
window- the window from which the drawable size should be queriedw- a pointer to variable for storing the width in pixels, may beundefh- a pointer to variable for storing the height in pixels, may beundef
SDL_GL_SetSwapInterval( ... )
Set the swap interval for the current OpenGL context.
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, this function will fail and return -1. In such a case, you should probably 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
Read more on the Khronos wiki: https://www.khronos.org/opengl/wiki/Swap_Interval#Adaptive_Vsync
Expected parameters include:
interval-0for immediate updates,1for updates synchronized with the vertical retrace,-1for adaptive vsync
Returns 0 on success or -1 if setting the swap interval is not supported; call SDL_GetError( ) for more information.
SDL_GL_GetSwapInterval( )
Get the swap interval for the current OpenGL context.
If the system can't determine the swap interval, or there isn't a valid current context, this function will return 0 as a safe default.
Returns 0 if there is no vertical retrace synchronization, 1 if the buffer swap is synchronized with the vertical retrace, and -1 if late swaps happen immediately instead of waiting for the next retrace; call SDL_GetError( ) for more information.
SDL_GL_SwapWindow( ... )
Update a window with OpenGL rendering.
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 glBindFramebuffer( ), this is the default and you won't have to do anything extra.
Expected parameters include:
SDL_GL_DeleteContext( ... )
Delete an OpenGL context.
Expected parameters include:
Defined values and enumerations
These may be imported with their given tags.
Window position flags
SDL_WINDOWPOS_UNDEFINED-
Used to indicate that you don't care what the window position is.
SDL_WINDOWPOS_CENTERED-
Used to indicate that the window position should be centered.
SDL_WindowFlags
The flags on a window. These may be imported with the :windowflags tag.
SDL_WINDOW_FULLSCREEN- Fullscreen windowSDL_WINDOW_OPENGL- Window usable with OpenGL contextSDL_WINDOW_SHOWN- Window is visibleSDL_WINDOW_HIDDEN- Window is not visibleSDL_WINDOW_BORDERLESS- No window decorationSDL_WINDOW_RESIZABLE- Window can be resizedSDL_WINDOW_MINIMIZED- Window is minimizedSDL_WINDOW_MAXIMIZED- Window is maximizedSDL_WINDOW_MOUSE_GRABBED- Window has grabbed mouse inputSDL_WINDOW_INPUT_FOCUS- Window has input focusSDL_WINDOW_MOUSE_FOCUS- Window has mouse focusSDL_WINDOW_FULLSCREEN_DESKTOP- Fullscreen window without frameSDL_WINDOW_FOREIGN- Window not created by SDLSDL_WINDOW_ALLOW_HIGHDPI- Window should be created in high-DPI mode if supported.-
On macOS NSHighResolutionCapable must be set true in the application's Info.plist for this to have any effect.
SDL_WINDOW_ALWAYS_ON_TOP- Window should always be above othersSDL_WINDOW_SKIP_TASKBAR- Window should not be added to the taskbarSDL_WINDOW_UTILITY- Window should be treated as a utility windowSDL_WINDOW_TOOLTIP- Window should be treated as a tooltipSDL_WINDOW_KEYBOARD_GRABBED- Window has grabbed keyboard inputSDL_WINDOW_VULKAN- Window usable for Vulkan surfaceSDL_WINDOW_METAL- Window usable for Metal viewSDL_WINDOW_INPUT_GRABBED- Equivalent toSDL_WINDOW_MOUSE_GRABBEDfor compatibility
SDL_WindowEventID
Event subtype for window events. These may be imported with the :windowEventID tag.
SDL_WINDOWEVENT_NONE- Never usedSDL_WINDOWEVENT_SHOWN- Window has been shownSDL_WINDOWEVENT_EXPOSED- Window has been exposed and should be redrawnSDL_WINDOWEVENT_MOVED- Window has been moved todata1, data2SDL_WINDOWEVENT_RESIZED- Window has been resized todata1 x data2SDL_WINDOWEVENT_SIZE_CHANGED- The window size has changed, either as a result of an API call or through the system or user changing the window size.SDL_WINDOWEVENT_MINIMIZED- Window has been minimizedSDL_WINDOWEVENT_MAXIMIZED- Window has been maximizedSDL_WINDOWEVENT_RESTORED- Window has been restored to normal size and positionSDL_WINDOWEVENT_ENTER- Window has gained mouse focusSDL_WINDOWEVENT_LEAVE- Window has lost mouse focusSDL_WINDOWEVENT_FOCUS_GAINED- Window has gained keyboard focusSDL_WINDOWEVENT_FOCUS_LOST- Window has lost keyboard focusSDL_WINDOWEVENT_CLOSE- The window manager requests that the window be closedSDL_WINDOWEVENT_TAKE_FOCUS- Window is being offered a focus (shouldSetWindowInputFocus( )on itself or a subwindow, or ignore)SDL_WINDOWEVENT_HIT_TEST- Window had a hit test that wasn'tSDL_HITTEST_NORMAL.
SDL_DisplayEventID
Event subtype for display events. These may be imported with the :displayEventID tag.
SDL_DISPLAYEVENT_NONE- Never usedSDL_DISPLAYEVENT_ORIENTATION- Display orientation has changed to data1SDL_DISPLAYEVENT_CONNECTED- Display has been added to the systemSDL_DISPLAYEVENT_DISCONNECTED- Display has been removed from the system
SDL_DisplayOrientation
These may be imported with the :displayOrientation tag.
SDL_ORIENTATION_UNKNOWN- The display orientation can't be determinedSDL_ORIENTATION_LANDSCAPE- The display is in landscape mode, with the right side up, relative to portrait modeSDL_ORIENTATION_LANDSCAPE_FLIPPED- The display is in landscape mode, with the left side up, relative to portrait modeSDL_ORIENTATION_PORTRAIT- The display is in portrait modeSDL_ORIENTATION_PORTRAIT_FLIPPED- The display is in portrait mode, upside down
SDL_FlashOperation
Window flash operation. These may be imported with the :flashOperation tag.
SDL_FLASH_CANCEL- Cancel any window flash stateSDL_FLASH_BRIEFLY- Flash the window briefly to get attentionSDL_FLASH_UNTIL_FOCUSED- Flash the window until it gets focus
SDL_GLattr
OpenGL configuration attributes. These may be imported with the :glAttr tag.
SDL_GL_RED_SIZESDL_GL_GREEN_SIZESDL_GL_BLUE_SIZESDL_GL_ALPHA_SIZESDL_GL_BUFFER_SIZESDL_GL_DOUBLEBUFFERSDL_GL_DEPTH_SIZESDL_GL_STENCIL_SIZESDL_GL_ACCUM_RED_SIZESDL_GL_ACCUM_GREEN_SIZESDL_GL_ACCUM_BLUE_SIZESDL_GL_ACCUM_ALPHA_SIZESDL_GL_STEREOSDL_GL_MULTISAMPLEBUFFERSSDL_GL_MULTISAMPLESAMPLESSDL_GL_ACCELERATED_VISUALSDL_GL_RETAINED_BACKINGSDL_GL_CONTEXT_MAJOR_VERSIONSDL_GL_CONTEXT_MINOR_VERSIONSDL_GL_CONTEXT_EGLSDL_GL_CONTEXT_FLAGSSDL_GL_CONTEXT_PROFILE_MASKSDL_GL_SHARE_WITH_CURRENT_CONTEXTSDL_GL_FRAMEBUFFER_SRGB_CAPABLESDL_GL_CONTEXT_RELEASE_BEHAVIORSDL_GL_CONTEXT_RESET_NOTIFICATIONSDL_GL_CONTEXT_NO_ERROR
SDL_GLprofile
These may be imported with the :glProfile tag.
SDL_GL_CONTEXT_PROFILE_CORESDL_GL_CONTEXT_PROFILE_COMPATIBILITYSDL_GL_CONTEXT_PROFILE_ES
SDL_GLcontextFlag
These may be imported with the :glContextFlag tag.
SDL_GL_CONTEXT_DEBUG_FLAGSDL_GL_CONTEXT_FORWARD_COMPATIBLE_FLAGSDL_GL_CONTEXT_ROBUST_ACCESS_FLAGSDL_GL_CONTEXT_RESET_ISOLATION_FLAG
SDL_GLcontextReleaseFlag
These may be imported with the :glContextReleaseFlag tag.
SDL_GL_CONTEXT_RELEASE_BEHAVIOR_NONESDL_GL_CONTEXT_RELEASE_BEHAVIOR_FLUSH
SDL_GLContextResetNotification
These may be imported with the :glContextResetNotification tag.
SDL_GL_CONTEXT_RESET_NO_NOTIFICATIONSDL_GL_CONTEXT_RESET_LOSE_CONTEXT
SDL_HitTest
Callback used for hit-testing.
Parameters to expect include:
win- the SDL2::Window where hit-testing was set onarea- an SDL2::Point which should be hit-testeddata- what was passed ascallback_datatoSDL_SetWindowHitTest( ... )
Your callback should return an SDL_HitTestResult value.
SDL_HitTestResult
Possible return values from the SDL_HitTest callback.
SDL_HITTEST_NORMAL- Region is normal. No special propertiesSDL_HITTEST_DRAGGABLE- Region can drag entire windowSDL_HITTEST_RESIZE_TOPLEFTSDL_HITTEST_RESIZE_TOPSDL_HITTEST_RESIZE_TOPRIGHTSDL_HITTEST_RESIZE_RIGHTSDL_HITTEST_RESIZE_BOTTOMRIGHTSDL_HITTEST_RESIZE_BOTTOMSDL_HITTEST_RESIZE_BOTTOMLEFTSDL_HITTEST_RESIZE_LEFT
LICENSE
Copyright (C) Sanko Robinson.
This library is free software; you can redistribute it and/or modify it under the terms found in the Artistic License 2. Other copyrights, terms, and conditions may apply to data transmitted through this module.
AUTHOR
Sanko Robinson <sanko@cpan.org>