SDL's video subsystem is largely interested in abstracting window management from the underlying operating system. More...

Classes
class	SDL::Display
	This is a unique ID for a display for the time it is connected to the system, and is never reused for the lifetime of the application. More...

struct	SDL::WindowBase
	Represents a handle to a window. More...

struct	SDL::WindowRef
	Handle to a non owned window. More...

struct	SDL::Window
	Handle to an owned window. More...

struct	SDL::GLContextBase
	An opaque handle to an OpenGL context. More...

struct	SDL::GLContextRef
	Handle to a non owned gLContext. More...

struct	SDL::GLContext
	Handle to an owned gLContext. More...

Macros
#define	SDL_WINDOWPOS_UNDEFINED_MASK 0x1FFF0000u
	A magic value used with SDL_WINDOWPOS_UNDEFINED.

#define	SDL_WINDOWPOS_UNDEFINED_DISPLAY(X) (SDL_WINDOWPOS_UNDEFINED_MASK \| (X))
	Used to indicate that you don't care what the window position is.

#define	SDL_WINDOWPOS_UNDEFINED SDL_WINDOWPOS_UNDEFINED_DISPLAY(0)
	Used to indicate that you don't care what the window position/display is.

#define	SDL_WINDOWPOS_ISUNDEFINED(X) (((X) & 0xFFFF0000) == SDL_WINDOWPOS_UNDEFINED_MASK)
	A macro to test if the window position is marked as "undefined.".

#define	SDL_WINDOWPOS_CENTERED_MASK 0x2FFF0000u
	A magic value used with SDL_WINDOWPOS_CENTERED.

#define	SDL_WINDOWPOS_CENTERED_DISPLAY(X) (SDL_WINDOWPOS_CENTERED_MASK \| (X))
	Used to indicate that the window position should be centered.

#define	SDL_WINDOWPOS_CENTERED SDL_WINDOWPOS_CENTERED_DISPLAY(0)
	Used to indicate that the window position should be centered.

#define	SDL_WINDOWPOS_ISCENTERED(X) (((X) & 0xFFFF0000) == SDL_WINDOWPOS_CENTERED_MASK)
	A macro to test if the window position is marked as "centered.".

#define	SDL_WINDOW_SURFACE_VSYNC_DISABLED 0
	Disable vsync.

#define	SDL_WINDOW_SURFACE_VSYNC_ADAPTIVE (-1)
	Adaptative vsync.

Typedefs
using	SDL::DisplayModeData = SDL_DisplayModeData
	Internal display mode data.

using	SDL::DisplayMode = SDL_DisplayMode
	The structure that defines a display mode.

using	SDL::WindowID = SDL_WindowID
	This is a unique ID for a window.

using	SDL::EGLDisplay = SDL_EGLDisplay
	Opaque type for an EGL display.

using	SDL::EGLConfig = SDL_EGLConfig
	Opaque type for an EGL config.

using	SDL::EGLSurface = SDL_EGLSurface
	Opaque type for an EGL surface.

using	SDL::EGLAttrib = SDL_EGLAttrib
	An EGL attribute, used when creating an EGL context.

using	SDL::EGLint = SDL_EGLint
	An EGL integer attribute, used when creating an EGL surface.

using	SDL::EGLAttribArrayCallback = SDL_EGLAttribArrayCallback
	EGL platform attribute initialization callback.

using	SDL::EGLAttribArrayCB = std::function< SDL_EGLAttrib *()>
	EGL platform attribute initialization callback.

using	SDL::EGLIntArrayCallback = SDL_EGLIntArrayCallback
	EGL surface/context attribute initialization callback types.

using	SDL::EGLIntArrayCB = std::function< SDL_EGLint *(SDL_EGLDisplay, SDL_EGLConfig)>
	EGL surface/context attribute initialization callback types.

Functions
int	SDL::GetNumVideoDrivers ()
	Get the number of video drivers compiled into SDL.

const char *	SDL::GetVideoDriver (int index)
	Get the name of a built in video driver.

const char *	SDL::GetCurrentVideoDriver ()
	Get the name of the currently initialized video driver.

SystemTheme	SDL::GetSystemTheme ()
	Get the current system theme.

OwnArray< WindowRef >	SDL::GetWindows ()
	Get a list of valid windows.

bool	SDL::ScreenSaverEnabled ()
	Check whether the screensaver is currently enabled.

void	SDL::EnableScreenSaver ()
	Allow the screen to be blanked by a screen saver.

void	SDL::DisableScreenSaver ()
	Prevent the screen from being blanked by a screen saver.

void	SDL::GL_LoadLibrary (StringParam path)
	Dynamically load an OpenGL library.

FunctionPointer	SDL::GL_GetProcAddress (StringParam proc)
	Get an OpenGL function by name.

FunctionPointer	SDL::EGL_GetProcAddress (StringParam proc)
	Get an EGL library function by name.

void	SDL::GL_UnloadLibrary ()
	Unload the OpenGL library previously loaded by GL_LoadLibrary().

bool	SDL::GL_ExtensionSupported (StringParam extension)
	Check if an OpenGL extension is supported for the current context.

void	SDL::GL_ResetAttributes ()
	Reset all previously set OpenGL context attributes to their default values.

void	SDL::GL_SetAttribute (GLAttr attr, int value)
	Set an OpenGL window attribute before window creation.

void	SDL::GL_GetAttribute (GLAttr attr, int *value)
	Get the actual value for an attribute from the current context.

WindowRef	SDL::GL_GetCurrentWindow ()
	Get the currently active OpenGL window.

GLContextRef	SDL::GL_GetCurrentContext ()
	Get the currently active OpenGL context.

EGLDisplay	SDL::EGL_GetCurrentDisplay ()
	Get the currently active EGL display.

EGLConfig	SDL::EGL_GetCurrentConfig ()
	Get the currently active EGL config.

EGLSurface	SDL::EGL_GetWindowSurface (WindowBase &window)
	Get the EGL surface associated with the window.

void	SDL::EGL_SetAttributeCallbacks (EGLAttribArrayCallback platformAttribCallback, EGLIntArrayCallback surfaceAttribCallback, EGLIntArrayCallback contextAttribCallback, void *userdata)
	Sets the callbacks for defining custom EGLAttrib arrays for EGL initialization.

void	SDL::GL_SetSwapInterval (int interval)
	Set the swap interval for the current OpenGL context.

void	SDL::GL_GetSwapInterval (int *interval)
	Get the swap interval for the current OpenGL context.

void	SDL::GL_SwapWindow (WindowBase &window)
	Update a window with OpenGL rendering.

static WindowRef	SDL::WindowRef::FromID (WindowID id)
	Get a window from a stored ID.

WindowRef	SDL::WindowBase::GetParent () const
	Get parent of a window.

static WindowRef	SDL::WindowRef::GetGrabbed ()
	Get the window that currently has an input grab enabled.

DisplayOrientations
using	SDL::DisplayOrientation = SDL_DisplayOrientation
	Display orientation values; the way a display is rotated.

constexpr DisplayOrientation	SDL::ORIENTATION_UNKNOWN
	The display orientation can't be determined.

constexpr DisplayOrientation	SDL::ORIENTATION_LANDSCAPE = SDL_ORIENTATION_LANDSCAPE
	The display is in landscape mode, with the right side up, relative to portrait mode.

constexpr DisplayOrientation	SDL::ORIENTATION_LANDSCAPE_FLIPPED
	The display is in landscape mode, with the left side up, relative to portrait mode.

constexpr DisplayOrientation	SDL::ORIENTATION_PORTRAIT
	The display is in portrait mode.

constexpr DisplayOrientation	SDL::ORIENTATION_PORTRAIT_FLIPPED
	The display is in portrait mode, upside down.

WindowFlags
using	SDL::WindowFlags = SDL_WindowFlags
	The flags on a window.

constexpr WindowFlags	SDL::WINDOW_FULLSCREEN
	window is in fullscreen mode

constexpr WindowFlags	SDL::WINDOW_OPENGL
	window usable with OpenGL context

constexpr WindowFlags	SDL::WINDOW_OCCLUDED
	window is occluded

constexpr WindowFlags	SDL::WINDOW_HIDDEN = SDL_WINDOW_HIDDEN
	window is neither mapped onto the desktop nor shown in the taskbar/dock/window list; WindowBase.Show() is required for it to become visible

constexpr WindowFlags	SDL::WINDOW_BORDERLESS
	no window decoration

constexpr WindowFlags	SDL::WINDOW_RESIZABLE
	window can be resized

constexpr WindowFlags	SDL::WINDOW_MINIMIZED
	window is minimized

constexpr WindowFlags	SDL::WINDOW_MAXIMIZED
	window is maximized

constexpr WindowFlags	SDL::WINDOW_MOUSE_GRABBED
	window has grabbed mouse input

constexpr WindowFlags	SDL::WINDOW_INPUT_FOCUS
	window has input focus

constexpr WindowFlags	SDL::WINDOW_MOUSE_FOCUS
	window has mouse focus

constexpr WindowFlags	SDL::WINDOW_EXTERNAL
	window not created by SDL

constexpr WindowFlags	SDL::WINDOW_MODAL = SDL_WINDOW_MODAL
	window is modal

constexpr WindowFlags	SDL::WINDOW_HIGH_PIXEL_DENSITY = SDL_WINDOW_HIGH_PIXEL_DENSITY
	window uses high pixel density back buffer if possible

constexpr WindowFlags	SDL::WINDOW_MOUSE_CAPTURE = SDL_WINDOW_MOUSE_CAPTURE
	window has mouse captured (unrelated to MOUSE_GRABBED)

constexpr WindowFlags	SDL::WINDOW_MOUSE_RELATIVE_MODE
	window has relative mode enabled

constexpr WindowFlags	SDL::WINDOW_ALWAYS_ON_TOP
	window should always be above others

constexpr WindowFlags	SDL::WINDOW_UTILITY = SDL_WINDOW_UTILITY
	window should be treated as a utility window, not showing in the task bar and window list

constexpr WindowFlags	SDL::WINDOW_TOOLTIP = SDL_WINDOW_TOOLTIP
	window should be treated as a tooltip and does not get mouse or keyboard focus, requires a parent window

constexpr WindowFlags	SDL::WINDOW_POPUP_MENU = SDL_WINDOW_POPUP_MENU
	window should be treated as a popup menu, requires a parent window

constexpr WindowFlags	SDL::WINDOW_KEYBOARD_GRABBED
	window has grabbed keyboard input

constexpr WindowFlags	SDL::WINDOW_VULKAN
	window usable for Vulkan surface

constexpr WindowFlags	SDL::WINDOW_METAL
	window usable for Metal view

constexpr WindowFlags	SDL::WINDOW_TRANSPARENT
	window with transparent buffer

constexpr WindowFlags	SDL::WINDOW_NOT_FOCUSABLE
	window should not be focusable

FlashOperations
using	SDL::FlashOperation = SDL_FlashOperation
	Window flash operation.

constexpr FlashOperation	SDL::FLASH_CANCEL
	Cancel any window flash state.

constexpr FlashOperation	SDL::FLASH_BRIEFLY
	Flash the window briefly to get attention.

constexpr FlashOperation	SDL::FLASH_UNTIL_FOCUSED
	Flash the window until it gets focus.

HitTestResults
Possible return values from the HitTest callback
using	SDL::HitTestResult = SDL_HitTestResult
	Possible return values from the HitTest callback.

constexpr HitTestResult	SDL::HITTEST_NORMAL
	Region is normal. No special properties.

constexpr HitTestResult	SDL::HITTEST_DRAGGABLE
	Region can drag entire window.

constexpr HitTestResult	SDL::HITTEST_RESIZE_TOPLEFT
	Region is the resizable top-left corner border.

constexpr HitTestResult	SDL::HITTEST_RESIZE_TOP
	Region is the resizable top border.

constexpr HitTestResult	SDL::HITTEST_RESIZE_TOPRIGHT
	Region is the resizable top-right corner border.

constexpr HitTestResult	SDL::HITTEST_RESIZE_RIGHT
	Region is the resizable right border.

constexpr HitTestResult	SDL::HITTEST_RESIZE_BOTTOMRIGHT
	Region is the resizable bottom-right corner border.

constexpr HitTestResult	SDL::HITTEST_RESIZE_BOTTOM
	Region is the resizable bottom border.

constexpr HitTestResult	SDL::HITTEST_RESIZE_BOTTOMLEFT
	Region is the resizable bottom-left corner border.

constexpr HitTestResult	SDL::HITTEST_RESIZE_LEFT
	Region is the resizable left border.

Callbacks for WindowBase::SetHitTest()
using	SDL::HitTest = SDL_HitTest
	Callback used for hit-testing.

using	SDL::HitTestCB = std::function< HitTestResult(WindowRef window, const Point &area)>
	Callback used for hit-testing.

using	SDL::OptionalWindow = OptionalResource< WindowRef, Window >
	A window parameter that might own its value.

SystemThemes
using	SDL::SystemTheme = SDL_SystemTheme
	System theme.

constexpr SystemTheme	SDL::SYSTEM_THEME_UNKNOWN
	Unknown system theme.

constexpr SystemTheme	SDL::SYSTEM_THEME_LIGHT
	Light colored system theme.

constexpr SystemTheme	SDL::SYSTEM_THEME_DARK
	Dark colored system theme.

GLAttrs
using	SDL::GLAttr = SDL_GLAttr
	An enumeration of OpenGL configuration attributes.

constexpr GLAttr	SDL::GL_RED_SIZE = SDL_GL_RED_SIZE
	the minimum number of bits for the red channel of the color buffer; defaults to 8.

constexpr GLAttr	SDL::GL_GREEN_SIZE = SDL_GL_GREEN_SIZE
	the minimum number of bits for the green channel of the color buffer; defaults to 8.

constexpr GLAttr	SDL::GL_BLUE_SIZE = SDL_GL_BLUE_SIZE
	the minimum number of bits for the blue channel of the color buffer; defaults to 8.

constexpr GLAttr	SDL::GL_ALPHA_SIZE = SDL_GL_ALPHA_SIZE
	the minimum number of bits for the alpha channel of the color buffer; defaults to 8.

constexpr GLAttr	SDL::GL_BUFFER_SIZE = SDL_GL_BUFFER_SIZE
	the minimum number of bits for frame buffer size; defaults to 0.

constexpr GLAttr	SDL::GL_DOUBLEBUFFER = SDL_GL_DOUBLEBUFFER
	whether the output is single or double buffered; defaults to double buffering on.

constexpr GLAttr	SDL::GL_DEPTH_SIZE = SDL_GL_DEPTH_SIZE
	the minimum number of bits in the depth buffer; defaults to 16.

constexpr GLAttr	SDL::GL_STENCIL_SIZE = SDL_GL_STENCIL_SIZE
	the minimum number of bits in the stencil buffer; defaults to 0.

constexpr GLAttr	SDL::GL_ACCUM_RED_SIZE = SDL_GL_ACCUM_RED_SIZE
	the minimum number of bits for the red channel of the accumulation buffer; defaults to 0.

constexpr GLAttr	SDL::GL_ACCUM_GREEN_SIZE = SDL_GL_ACCUM_GREEN_SIZE
	the minimum number of bits for the green channel of the accumulation buffer; defaults to 0.

constexpr GLAttr	SDL::GL_ACCUM_BLUE_SIZE = SDL_GL_ACCUM_BLUE_SIZE
	the minimum number of bits for the blue channel of the accumulation buffer; defaults to 0.

constexpr GLAttr	SDL::GL_ACCUM_ALPHA_SIZE = SDL_GL_ACCUM_ALPHA_SIZE
	the minimum number of bits for the alpha channel of the accumulation buffer; defaults to 0.

constexpr GLAttr	SDL::GL_STEREO
	whether the output is stereo 3D; defaults to off.

constexpr GLAttr	SDL::GL_MULTISAMPLEBUFFERS = SDL_GL_MULTISAMPLEBUFFERS
	the number of buffers used for multisample anti-aliasing; defaults to 0.

constexpr GLAttr	SDL::GL_MULTISAMPLESAMPLES = SDL_GL_MULTISAMPLESAMPLES
	the number of samples used around the current pixel used for multisample anti-aliasing.

constexpr GLAttr	SDL::GL_ACCELERATED_VISUAL = SDL_GL_ACCELERATED_VISUAL
	set to 1 to require hardware acceleration, set to 0 to force software rendering; defaults to allow either.

constexpr GLAttr	SDL::GL_RETAINED_BACKING
	not used (deprecated).

constexpr GLAttr	SDL::GL_CONTEXT_MAJOR_VERSION
	OpenGL context major version.

constexpr GLAttr	SDL::GL_CONTEXT_MINOR_VERSION
	OpenGL context minor version.

constexpr GLAttr	SDL::GL_CONTEXT_FLAGS = SDL_GL_CONTEXT_FLAGS
	some combination of 0 or more of elements of the GLContextFlag enumeration; defaults to 0.

constexpr GLAttr	SDL::GL_CONTEXT_PROFILE_MASK = SDL_GL_CONTEXT_PROFILE_MASK
	type of GL context (Core, Compatibility, ES).

constexpr GLAttr	SDL::GL_SHARE_WITH_CURRENT_CONTEXT
	OpenGL context sharing; defaults to 0.

constexpr GLAttr	SDL::GL_FRAMEBUFFER_SRGB_CAPABLE
	requests sRGB capable visual; defaults to 0.

constexpr GLAttr	SDL::GL_CONTEXT_RELEASE_BEHAVIOR = SDL_GL_CONTEXT_RELEASE_BEHAVIOR
	sets context the release behavior.

constexpr GLAttr	SDL::GL_CONTEXT_RESET_NOTIFICATION
	set context reset notification.

constexpr GLAttr	SDL::GL_CONTEXT_NO_ERROR
	GL_CONTEXT_NO_ERROR.

constexpr GLAttr	SDL::GL_FLOATBUFFERS = SDL_GL_FLOATBUFFERS
	GL_FLOATBUFFERS.

constexpr GLAttr	SDL::GL_EGL_PLATFORM = SDL_GL_EGL_PLATFORM
	GL_EGL_PLATFORM.

GLProfiles
using	SDL::GLProfile = Uint32
	Possible values to be set for the GL_CONTEXT_PROFILE_MASK attribute.

constexpr GLProfile	SDL::GL_CONTEXT_PROFILE_CORE
	OpenGL Core Profile context.

constexpr GLProfile	SDL::GL_CONTEXT_PROFILE_COMPATIBILITY
	OpenGL Compatibility Profile context.

constexpr GLProfile	SDL::GL_CONTEXT_PROFILE_ES
	GLX_CONTEXT_ES2_PROFILE_BIT_EXT.

GLContextFlags
using	SDL::GLContextFlag = Uint32
	Possible flags to be set for the GL_CONTEXT_FLAGS attribute.

using	SDL::GLContextReleaseFlag = Uint32
	Possible values to be set for the GL_CONTEXT_RELEASE_BEHAVIOR attribute.

constexpr GLContextFlag	SDL::GL_CONTEXT_DEBUG_FLAG
	DEBUG_FLAG.

constexpr GLContextFlag	SDL::GL_CONTEXT_FORWARD_COMPATIBLE_FLAG
	FORWARD_COMPATIBLE_FLAG.

constexpr GLContextFlag	SDL::GL_CONTEXT_ROBUST_ACCESS_FLAG
	ROBUST_ACCESS_FLAG.

constexpr GLContextFlag	SDL::GL_CONTEXT_RESET_ISOLATION_FLAG
	RESET_ISOLATION_FLAG.

constexpr GLContextReleaseFlag	SDL::GL_CONTEXT_RELEASE_BEHAVIOR_NONE
	BEHAVIOR_NONE.

constexpr GLContextReleaseFlag	SDL::GL_CONTEXT_RELEASE_BEHAVIOR_FLUSH
	BEHAVIOR_FLUSH.

GLContextResetNotifications
using	SDL::GLContextResetNotification = Uint32
	Possible values to be set GL_CONTEXT_RESET_NOTIFICATION attribute.

constexpr GLContextResetNotification	SDL::GL_CONTEXT_RESET_NO_NOTIFICATION
	NO_NOTIFICATION.

constexpr GLContextResetNotification	SDL::GL_CONTEXT_RESET_LOSE_CONTEXT
	LOSE_CONTEXT.

Detailed Description

You can create windows, manage them in various ways, set them fullscreen, and get events when interesting things happen with them, such as the mouse or keyboard interacting with a window.

The video subsystem is also interested in abstracting away some platform-specific differences in OpenGL: context creation, swapping buffers, etc. This may be crucial to your app, but also you are not required to use OpenGL at all. In fact, SDL can provide rendering to those windows as well, either with an easy-to-use 2D API or with a more-powerful GPU API . Of course, it can simply get out of your way and give you the window handles you need to use Vulkan, Direct3D, Metal, or whatever else you like directly, too.

The video subsystem covers a lot of functionality, out of necessity, so it is worth perusing the list of functions just to see what's available, but most apps can get by with simply creating a window and listening for events, so start with SDL_CreateWindow() and SDL_PollEvent().

Macro Definition Documentation

◆ SDL_WINDOWPOS_CENTERED

#define SDL_WINDOWPOS_CENTERED SDL_WINDOWPOS_CENTERED_DISPLAY(0)

This always uses the primary display.

Since: This macro is available since SDL 3.2.0.

◆ SDL_WINDOWPOS_CENTERED_DISPLAY

#define SDL_WINDOWPOS_CENTERED_DISPLAY ( X ) (SDL_WINDOWPOS_CENTERED_MASK | (X))

SDL_WINDOWPOS_CENTERED is the same, but always uses the primary display instead of specifying one.

Parameters

X	the Display of the display to use.

Since: This macro is available since SDL 3.2.0.

◆ SDL_WINDOWPOS_CENTERED_MASK

#define SDL_WINDOWPOS_CENTERED_MASK 0x2FFF0000u

Generally this macro isn't used directly, but rather through SDL_WINDOWPOS_CENTERED or SDL_WINDOWPOS_CENTERED_DISPLAY.

Since: This macro is available since SDL 3.2.0.

◆ SDL_WINDOWPOS_ISCENTERED

#define SDL_WINDOWPOS_ISCENTERED ( X ) (((X) & 0xFFFF0000) == SDL_WINDOWPOS_CENTERED_MASK)

Parameters

X	the window position value.

Since: This macro is available since SDL 3.2.0.

◆ SDL_WINDOWPOS_ISUNDEFINED

#define SDL_WINDOWPOS_ISUNDEFINED ( X ) (((X) & 0xFFFF0000) == SDL_WINDOWPOS_UNDEFINED_MASK)

Parameters

X	the window position value.

Since: This macro is available since SDL 3.2.0.

◆ SDL_WINDOWPOS_UNDEFINED

#define SDL_WINDOWPOS_UNDEFINED SDL_WINDOWPOS_UNDEFINED_DISPLAY(0)

This always uses the primary display.

Since: This macro is available since SDL 3.2.0.

◆ SDL_WINDOWPOS_UNDEFINED_DISPLAY

#define SDL_WINDOWPOS_UNDEFINED_DISPLAY ( X ) (SDL_WINDOWPOS_UNDEFINED_MASK | (X))

If you really don't care, SDL_WINDOWPOS_UNDEFINED is the same, but always uses the primary display instead of specifying one.

Parameters

X	the Display of the display to use.

Since: This macro is available since SDL 3.2.0.

◆ SDL_WINDOWPOS_UNDEFINED_MASK

#define SDL_WINDOWPOS_UNDEFINED_MASK 0x1FFF0000u

Generally this macro isn't used directly, but rather through SDL_WINDOWPOS_UNDEFINED or SDL_WINDOWPOS_UNDEFINED_DISPLAY.

Since: This macro is available since SDL 3.2.0.

Typedef Documentation

◆ DisplayMode

using SDL::DisplayMode = typedef SDL_DisplayMode

Since: This struct is available since SDL 3.2.0.

See also: Display.GetFullscreenModes; Display.GetDesktopMode; Display.GetCurrentMode; WindowBase.SetFullscreenMode; WindowBase.GetFullscreenMode

◆ DisplayModeData

using SDL::DisplayModeData = typedef SDL_DisplayModeData

This lives as a field in DisplayMode, as opaque data.

Since: This struct is available since SDL 3.2.0.

See also: DisplayMode

◆ DisplayOrientation

using SDL::DisplayOrientation = typedef SDL_DisplayOrientation

Since: This enum is available since SDL 3.2.0.

See also: ORIENTATION_LANDSCAPE; ORIENTATION_PORTRAIT; ORIENTATION_UNKNOWN

◆ EGLAttrib

using SDL::EGLAttrib = typedef SDL_EGLAttrib

Since: This datatype is available since SDL 3.2.0.

◆ EGLAttribArrayCallback

using SDL::EGLAttribArrayCallback = typedef SDL_EGLAttribArrayCallback

This is called when SDL is attempting to create an EGL context, to let the app add extra attributes to its eglGetPlatformDisplay() call.

The callback should return a pointer to an EGL attribute array terminated with EGL_NONE. If this function returns nullptr, the WindowBase.WindowBase process will fail gracefully.

The returned pointer should be allocated with malloc() and will be passed to free().

The arrays returned by each callback will be appended to the existing attribute arrays defined by SDL.

Parameters

userdata an app-controlled pointer that is passed to the callback.

Returns: a newly-allocated array of attributes, terminated with EGL_NONE.

Since: This datatype is available since SDL 3.2.0.

See also: EGL_SetAttributeCallbacks

◆ EGLAttribArrayCB

using SDL::EGLAttribArrayCB = typedef std::function<SDL_EGLAttrib*()>

This is called when SDL is attempting to create an EGL context, to let the app add extra attributes to its eglGetPlatformDisplay() call.

The callback should return a pointer to an EGL attribute array terminated with EGL_NONE. If this function returns nullptr, the WindowBase.WindowBase process will fail gracefully.

The returned pointer should be allocated with malloc() and will be passed to free().

The arrays returned by each callback will be appended to the existing attribute arrays defined by SDL.

Returns: a newly-allocated array of attributes, terminated with EGL_NONE.

Since: This datatype is available since SDL 3.2.0.

See also: EGL_SetAttributeCallbacks; EGLAttribArrayCallback

◆ EGLConfig

using SDL::EGLConfig = typedef SDL_EGLConfig

Since: This datatype is available since SDL 3.2.0.

◆ EGLDisplay

using SDL::EGLDisplay = typedef SDL_EGLDisplay

Since: This datatype is available since SDL 3.2.0.

◆ EGLint

using SDL::EGLint = typedef SDL_EGLint

Since: This datatype is available since SDL 3.2.0.

◆ EGLIntArrayCallback

using SDL::EGLIntArrayCallback = typedef SDL_EGLIntArrayCallback

This is called when SDL is attempting to create an EGL surface, to let the app add extra attributes to its eglCreateWindowSurface() or eglCreateContext calls.

For convenience, the EGLDisplay and EGLConfig to use are provided to the callback.

The callback should return a pointer to an EGL attribute array terminated with EGL_NONE. If this function returns nullptr, the WindowBase.WindowBase process will fail gracefully.

The returned pointer should be allocated with malloc() and will be passed to free().

The arrays returned by each callback will be appended to the existing attribute arrays defined by SDL.

Parameters

userdata	an app-controlled pointer that is passed to the callback.
display	the EGL display to be used.
config	the EGL config to be used.

Returns: a newly-allocated array of attributes, terminated with EGL_NONE.

Since: This datatype is available since SDL 3.2.0.

See also: EGL_SetAttributeCallbacks

◆ EGLIntArrayCB

using SDL::EGLIntArrayCB = typedef std::function<SDL_EGLint*(SDL_EGLDisplay, SDL_EGLConfig)>

This is called when SDL is attempting to create an EGL surface, to let the app add extra attributes to its eglCreateWindowSurface() or eglCreateContext calls.

For convenience, the EGLDisplay and EGLConfig to use are provided to the callback.

The callback should return a pointer to an EGL attribute array terminated with EGL_NONE. If this function returns nullptr, the WindowBase.WindowBase process will fail gracefully.

The returned pointer should be allocated with malloc() and will be passed to free().

The arrays returned by each callback will be appended to the existing attribute arrays defined by SDL.

Parameters

display	the EGL display to be used.
config	the EGL config to be used.

Returns: a newly-allocated array of attributes, terminated with EGL_NONE.

Since: This datatype is available since SDL 3.2.0.

See also: EGL_SetAttributeCallbacks; EGLIntArrayCallback

◆ EGLSurface

using SDL::EGLSurface = typedef SDL_EGLSurface

Since: This datatype is available since SDL 3.2.0.

◆ FlashOperation

using SDL::FlashOperation = typedef SDL_FlashOperation

Since: This enum is available since SDL 3.2.0.

See also: FLASH_CANCEL; FLASH_BRIEFLY; FLASH_UNTIL_FOCUSED

◆ GLAttr

using SDL::GLAttr = typedef SDL_GLAttr

While you can set most OpenGL attributes normally, the attributes listed above must be known before SDL creates the window that will be used with the OpenGL context. These attributes are set and read with GL_SetAttribute() and GL_GetAttribute().

In some cases, these attributes are minimum requests; the GL does not promise to give you exactly what you asked for. It's possible to ask for a 16-bit depth buffer and get a 24-bit one instead, for example, or to ask for no stencil buffer and still have one available. Context creation should fail if the GL can't provide your requested attributes at a minimum, but you should check to see exactly what you got.

Since: This enum is available since SDL 3.2.0.

◆ GLContextFlag

using SDL::GLContextFlag = typedef Uint32

Since: This datatype is available since SDL 3.2.0.

◆ GLContextReleaseFlag

using SDL::GLContextReleaseFlag = typedef Uint32

Since: This datatype is available since SDL 3.2.0.

◆ GLContextResetNotification

using SDL::GLContextResetNotification = typedef Uint32

Since: This datatype is available since SDL 3.2.0.

◆ GLProfile

using SDL::GLProfile = typedef Uint32

Since: This datatype is available since SDL 3.2.0.

◆ HitTest

using SDL::HitTest = typedef SDL_HitTest

Parameters

win	the WindowBase where hit-testing was set on.
area	an Point which should be hit-tested.
data	what was passed as `callback_data` to WindowBase.SetHitTest().

Returns: an HitTestResult value.

See also: WindowBase.SetHitTest

◆ HitTestCB

using SDL::HitTestCB = typedef std::function<HitTestResult(WindowRef window, const Point& area)>

Parameters

win	the WindowRef where hit-testing was set on.
area	a Point const reference which should be hit-tested.

Returns: an SDL::HitTestResult value.

See also: HitTest

Category:: Listener callback

◆ HitTestResult

using SDL::HitTestResult = typedef SDL_HitTestResult

Thread safety:: This function should only be called on the main thread.

Since: This enum is available since SDL 3.2.0.

See also: HitTest; HITTEST_NORMAL

◆ OptionalWindow

using SDL::OptionalWindow = typedef OptionalResource<WindowRef, Window>

This is designed to be used on parameter's type and accepts that accepts a std::nullopt, a non-owned WindowRef or an owned Window

◆ SystemTheme

using SDL::SystemTheme = typedef SDL_SystemTheme

Since: This enum is available since SDL 3.2.0.

◆ WindowFlags

using SDL::WindowFlags = typedef SDL_WindowFlags

These cover a lot of true/false, or on/off, window state. Some of it is immutable after being set through WindowBase.WindowBase(), some of it can be changed on existing windows by the app, and some of it might be altered by the user or system outside of the app's control.

Since: This datatype is available since SDL 3.2.0.

See also: WindowBase.GetFlags

◆ WindowID

using SDL::WindowID = typedef SDL_WindowID

The value 0 is an invalid ID.

Since: This datatype is available since SDL 3.2.0.

Function Documentation

◆ DisableScreenSaver()

void SDL::DisableScreenSaver ( )

inline

If you disable the screensaver, it is automatically re-enabled when SDL quits.

The screensaver is disabled by default, but this may by changed by SDL_HINT_VIDEO_ALLOW_SCREENSAVER.

Exceptions

Error on failure.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: EnableScreenSaver; ScreenSaverEnabled

◆ EGL_GetCurrentConfig()

EGLConfig SDL::EGL_GetCurrentConfig ( )

inline

Returns: the currently active EGL config.

Exceptions

Error on failure.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

◆ EGL_GetCurrentDisplay()

EGLDisplay SDL::EGL_GetCurrentDisplay ( )

inline

Returns: the currently active EGL display.

Exceptions

Error on failure.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

◆ EGL_GetProcAddress()

FunctionPointer SDL::EGL_GetProcAddress ( StringParam proc )

inline

If an EGL library is loaded, this function allows applications to get entry points for EGL functions. This is useful to provide to an EGL API and extension loader.

Parameters

proc	the name of an EGL function.

Returns: a pointer to the named EGL function. The returned pointer should be cast to the appropriate function signature.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: EGL_GetCurrentDisplay

◆ EGL_GetWindowSurface()

EGLSurface SDL::EGL_GetWindowSurface ( WindowBase & window )

inline

Parameters

window the window to query.

Returns: the EGLSurface pointer associated with the window.

Exceptions

Error on failure.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

◆ EGL_SetAttributeCallbacks()

void SDL::EGL_SetAttributeCallbacks	(	EGLAttribArrayCallback	platformAttribCallback,
		EGLIntArrayCallback	surfaceAttribCallback,
		EGLIntArrayCallback	contextAttribCallback,
		void *	userdata
	)

inline

Callbacks that aren't needed can be set to nullptr.

NOTE: These callback pointers will be reset after GL_ResetAttributes.

Parameters

platformAttribCallback	callback for attributes to pass to eglGetPlatformDisplay. May be nullptr.
surfaceAttribCallback	callback for attributes to pass to eglCreateSurface. May be nullptr.
contextAttribCallback	callback for attributes to pass to eglCreateContext. May be nullptr.
userdata	a pointer that is passed to the callbacks.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

◆ EnableScreenSaver()

void SDL::EnableScreenSaver ( )

inline

Exceptions

Error on failure.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: DisableScreenSaver; ScreenSaverEnabled

◆ FromID()

WindowRef SDL::WindowRef::FromID ( WindowID id )

inlinestatic

The numeric ID is what WindowEvent references, and is necessary to map these events to specific WindowBase objects.

Parameters

id	the ID of the window.

Returns: the window associated with id or nullptr if it doesn't exist; call GetError() for more information.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: WindowBase.GetID

◆ GetCurrentVideoDriver()

const char * SDL::GetCurrentVideoDriver ( )

inline

The names of drivers are all simple, low-ASCII identifiers, like "cocoa", "x11" or "windows". These never have Unicode characters, and are not meant to be proper names.

Returns: the name of the current video driver or nullptr if no driver has been initialized.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: GetNumVideoDrivers; GetVideoDriver

◆ GetGrabbed()

WindowRef SDL::WindowRef::GetGrabbed ( )

inlinestatic

Returns: the window if input is grabbed or nullptr otherwise.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: WindowBase.SetMouseGrab; WindowBase.SetKeyboardGrab

◆ GetNumVideoDrivers()

int SDL::GetNumVideoDrivers ( )

inline

Returns: the number of built in video drivers.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: GetVideoDriver

◆ GetParent()

WindowRef SDL::WindowBase::GetParent ( ) const

inline

Returns: the parent of the window on success.

Exceptions

Error on failure.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: WindowBase.WindowBase

◆ GetSystemTheme()

SystemTheme SDL::GetSystemTheme ( )

inline

Returns: the current system theme, light, dark, or unknown.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

◆ GetVideoDriver()

const char * SDL::GetVideoDriver ( int index )

inline

The video drivers are presented in the order in which they are normally checked during initialization.

The names of drivers are all simple, low-ASCII identifiers, like "cocoa", "x11" or "windows". These never have Unicode characters, and are not meant to be proper names.

Parameters

index the index of a video driver.

Returns: the name of the video driver with the given index.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: GetNumVideoDrivers

◆ GetWindows()

OwnArray< WindowRef > SDL::GetWindows ( )

inline

Returns: a nullptr terminated array of WindowRef pointers.

Exceptions

Error on failure.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

◆ GL_ExtensionSupported()

bool SDL::GL_ExtensionSupported ( StringParam extension )

inline

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.

Parameters

extension the name of the extension to check.

Returns: true if the extension is supported, false otherwise.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

◆ GL_GetAttribute()

void SDL::GL_GetAttribute	(	GLAttr	attr,
		int *	value
	)

inline

Parameters

attr	an GLAttr enum value specifying the OpenGL attribute to get.
value	a pointer filled in with the current value of `attr`.

Exceptions

Error on failure.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: GL_ResetAttributes; GL_SetAttribute

◆ GL_GetCurrentContext()

GLContextRef SDL::GL_GetCurrentContext ( )

inline

Returns: the currently active OpenGL context.

Exceptions

Error on failure.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: GLContextBase.MakeCurrent

◆ GL_GetCurrentWindow()

WindowRef SDL::GL_GetCurrentWindow ( )

inline

Returns: the currently active OpenGL window on success.

Exceptions

Error on failure.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

◆ GL_GetProcAddress()

FunctionPointer SDL::GL_GetProcAddress ( StringParam proc )

inline

If the GL library is loaded at runtime with 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 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-nullptr 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 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 nullptr if a function isn't supported, but you can't count on this behavior. Check for extensions you use, and if you get a nullptr 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.

Parameters

proc	the name of an OpenGL function.

Returns: a pointer to the named OpenGL function. The returned pointer should be cast to the appropriate function signature.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: GL_ExtensionSupported; GL_LoadLibrary; GL_UnloadLibrary

◆ GL_GetSwapInterval()

void SDL::GL_GetSwapInterval ( int * interval )

inline

If the system can't determine the swap interval, or there isn't a valid current context, this function will set *interval to 0 as a safe default.

Parameters

interval output interval value. 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.

Exceptions

Error on failure.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: GL_SetSwapInterval

◆ GL_LoadLibrary()

void SDL::GL_LoadLibrary ( StringParam path )

inline

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 GL_GetProcAddress().

Parameters

path	the platform dependent OpenGL library name, or nullptr to open the default OpenGL library.

Exceptions

Error on failure.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: GL_GetProcAddress; GL_UnloadLibrary

◆ GL_ResetAttributes()

void SDL::GL_ResetAttributes ( )

inline

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: GL_GetAttribute; GL_SetAttribute

◆ GL_SetAttribute()

void SDL::GL_SetAttribute	(	GLAttr	attr,
		int	value
	)

inline

This function sets the OpenGL attribute attr to value. The requested attributes should be set before creating an OpenGL window. You should use GL_GetAttribute() to check the values after creating the OpenGL context, since the values obtained can differ from the requested ones.

Parameters

attr	an GLAttr enum value specifying the OpenGL attribute to set.
value	the desired value for the attribute.

Exceptions

Error on failure.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: GL_GetAttribute; GL_ResetAttributes

◆ GL_SetSwapInterval()

void SDL::GL_SetSwapInterval ( int interval )

inline

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 false. 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, and for some Windows drivers with WGL_EXT_swap_control_tear.

Read more on the Khronos wiki: https://www.khronos.org/opengl/wiki/Swap_Interval#Adaptive_Vsync

Parameters

interval 0 for immediate updates, 1 for updates synchronized with the vertical retrace, -1 for adaptive vsync.

Exceptions

Error on failure.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: GL_GetSwapInterval

◆ GL_SwapWindow()

void SDL::GL_SwapWindow ( WindowBase & window )

inline

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.

Parameters

window the window to change.

Exceptions

Error on failure.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

◆ GL_UnloadLibrary()

void SDL::GL_UnloadLibrary ( )

inline

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: GL_LoadLibrary

◆ ScreenSaverEnabled()

bool SDL::ScreenSaverEnabled ( )

inline

The screensaver is disabled by default.

The default can also be changed using SDL_HINT_VIDEO_ALLOW_SCREENSAVER.

Returns: true if the screensaver is enabled, false if it is disabled.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: DisableScreenSaver; EnableScreenSaver

SDL_GL_CONTEXT_PROFILE_ES

◆ GL_CONTEXT_PROFILE_MASK

constexpr GLAttr SDL::GL_CONTEXT_PROFILE_MASK = SDL_GL_CONTEXT_PROFILE_MASK

constexpr

constexpr GLAttr SDL::GL_CONTEXT_RESET_NOTIFICATION

constexpr WindowFlags SDL::WINDOW_VULKAN

constexpr

Initial value:

=

SDL_WINDOW_VULKAN

Classes

Macros

Typedefs

Functions

DisplayOrientations

WindowFlags

FlashOperations

HitTestResults

Callbacks for WindowBase::SetHitTest()

SystemThemes

GLAttrs

GLProfiles

GLContextFlags

GLContextResetNotifications

Detailed Description

Macro Definition Documentation

◆ SDL_WINDOWPOS_CENTERED

◆ SDL_WINDOWPOS_CENTERED_DISPLAY

◆ SDL_WINDOWPOS_CENTERED_MASK

◆ SDL_WINDOWPOS_ISCENTERED

◆ SDL_WINDOWPOS_ISUNDEFINED

◆ SDL_WINDOWPOS_UNDEFINED

◆ SDL_WINDOWPOS_UNDEFINED_DISPLAY

◆ SDL_WINDOWPOS_UNDEFINED_MASK

Typedef Documentation

◆ DisplayMode

◆ DisplayModeData

◆ DisplayOrientation

◆ EGLAttrib

◆ EGLAttribArrayCallback

◆ EGLAttribArrayCB

◆ EGLConfig

◆ EGLDisplay

◆ EGLint

◆ EGLIntArrayCallback

◆ EGLIntArrayCB

◆ EGLSurface

◆ FlashOperation

◆ GLAttr

◆ GLContextFlag

◆ GLContextReleaseFlag

◆ GLContextResetNotification

◆ GLProfile

◆ HitTest

◆ HitTestCB

◆ HitTestResult

◆ OptionalWindow

◆ SystemTheme

◆ WindowFlags

◆ WindowID

Function Documentation

◆ DisableScreenSaver()

◆ EGL_GetCurrentConfig()

◆ EGL_GetCurrentDisplay()

◆ EGL_GetProcAddress()

◆ EGL_GetWindowSurface()

◆ EGL_SetAttributeCallbacks()

◆ EnableScreenSaver()

◆ FromID()

◆ GetCurrentVideoDriver()

◆ GetGrabbed()

◆ GetNumVideoDrivers()

◆ GetParent()

◆ GetSystemTheme()

◆ GetVideoDriver()

◆ GetWindows()

◆ GL_ExtensionSupported()

◆ GL_GetAttribute()

◆ GL_GetCurrentContext()

◆ GL_GetCurrentWindow()

◆ GL_GetProcAddress()

◆ GL_GetSwapInterval()

◆ GL_LoadLibrary()

◆ GL_ResetAttributes()

◆ GL_SetAttribute()

◆ GL_SetSwapInterval()

◆ GL_SwapWindow()

◆ GL_UnloadLibrary()

◆ ScreenSaverEnabled()

Variable Documentation