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...

Public Member Functions
constexpr	Display (SDL_DisplayID displayID={})
	Wraps Display.

constexpr bool	operator== (const Display &other) const =default
	Default comparison operator.

constexpr bool	operator== (SDL_DisplayID displayID) const
	Compares with the underlying type.

constexpr	operator SDL_DisplayID () const
	Unwraps to the underlying Display.

constexpr	operator bool () const
	Check if valid.

PropertiesRef	GetProperties () const
	Get the properties associated with a display.

const char *	GetName () const
	Get the name of a display in UTF-8 encoding.

Rect	GetBounds () const
	Get the desktop area represented by a display.

Rect	GetUsableBounds () const
	Get the usable desktop area represented by a display, in screen coordinates.

DisplayOrientation	GetNaturalOrientation () const
	Get the orientation of a display when it is unrotated.

DisplayOrientation	GetCurrentOrientation () const
	Get the orientation of a display.

float	GetContentScale () const
	Get the content scale of a display.

OwnArray< DisplayMode * >	GetFullscreenModes () const
	Get a list of fullscreen display modes available on a display.

DisplayMode	GetClosestFullscreenMode (int w, int h, float refresh_rate, bool include_high_density_modes) const
	Get the closest match to the requested display mode.

const DisplayMode *	GetDesktopMode () const
	Get information about the desktop's display mode.

const DisplayMode *	GetCurrentMode () const
	Get information about the current display mode.

Static Public Member Functions
static OwnArray< Display >	GetAll ()
	Get a list of currently connected displays.

static Display	GetPrimary ()
	Return the primary display.

static Display	GetForPoint (const SDL_Point &point)
	Get the display containing a point.

static Display	GetForRect (const SDL_Rect &rect)
	Get the display primarily containing a rect.

static Display	GetForWindow (WindowBase &window)
	Get the display associated with a window.

Detailed Description

If the display is disconnected and reconnected, it will get a new ID.

The value 0 is an invalid ID.

Since: This datatype is available since SDL 3.2.0.

Constructor & Destructor Documentation

◆ Display()

constexpr SDL::Display::Display ( SDL_DisplayID displayID = {} )

inlineconstexpr

Parameters

displayID the value to be wrapped

Member Function Documentation

◆ GetAll()

static OwnArray< Display > SDL::Display::GetAll ( )

inlinestatic

Returns: a 0 terminated array of display instance IDs or nullptr on failure; call GetError() for more information. This should be freed with free() when it is no longer needed.

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

Since: This function is available since SDL 3.2.0.

◆ GetBounds()

Rect SDL::Display::GetBounds ( ) const

inline

The primary display is often located at (0,0), but may be placed at a different location depending on monitor layout.

Returns: the Rect structure filled in with the display bounds 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: Display.GetUsableBounds; Display.GetAll

◆ GetClosestFullscreenMode()

DisplayMode SDL::Display::GetClosestFullscreenMode	(	int	w,
		int	h,
		float	refresh_rate,
		bool	include_high_density_modes
	)		const

inline

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 false is returned.

Parameters

w	the width in pixels of the desired display mode.
h	the height in pixels of the desired display mode.
refresh_rate	the refresh rate of the desired display mode, or 0.0f for the desktop refresh rate.
include_high_density_modes	boolean to include high density modes in the search.

Returns: the closest display mode equal to or larger than the desired mode 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: Display.GetAll; Display.GetFullscreenModes

◆ GetContentScale()

float SDL::Display::GetContentScale ( ) const

inline

The content scale is the expected scale for content based on the DPI settings of the display. For example, a 4K display might have a 2.0 (200%) display scale, which means that the user expects UI elements to be twice as big on this display, to aid in readability.

After window creation, WindowBase.GetDisplayScale() should be used to query the content scale factor for individual windows instead of querying the display for a window and calling this function, as the per-window content scale factor may differ from the base value of the display it is on, particularly on high-DPI and/or multi-monitor desktop configurations.

Returns: the content scale of the display, or 0.0f on failure; 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.GetDisplayScale; Display.GetAll

◆ GetCurrentMode()

const DisplayMode * SDL::Display::GetCurrentMode ( ) const

inline

There's a difference between this function and Display.GetDesktopMode() 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.

Returns: a pointer to the desktop display mode or nullptr on failure; 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: Display.GetDesktopMode; Display.GetAll

◆ GetCurrentOrientation()

DisplayOrientation SDL::Display::GetCurrentOrientation ( ) const

inline

Returns: the DisplayOrientation enum value of the display, or ORIENTATION_UNKNOWN if it isn't available.

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

Since: This function is available since SDL 3.2.0.

See also: Display.GetAll

◆ GetDesktopMode()

const DisplayMode * SDL::Display::GetDesktopMode ( ) const

inline

There's a difference between this function and Display.GetCurrentMode() 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.

Returns: a pointer to the desktop display mode.

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: Display.GetCurrentMode; Display.GetAll

◆ GetForPoint()

static Display SDL::Display::GetForPoint ( const SDL_Point & point )

inlinestatic

Parameters

point the point to query.

Returns: the instance ID of the display containing the point or 0 on failure; 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: Display.GetBounds; Display.GetAll

◆ GetForRect()

static Display SDL::Display::GetForRect ( const SDL_Rect & rect )

inlinestatic

Parameters

rect	the rect to query.

Returns: the instance ID of the display entirely containing the rect or closest to the center of the rect on success or 0 on failure; 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: Display.GetBounds; Display.GetAll

◆ GetForWindow()

static Display SDL::Display::GetForWindow ( WindowBase & window )

static

Parameters

window the window to query.

Returns: the instance ID of the display containing the center of the window on success or 0 on failure; call GetError() for more information.

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

◆ GetFullscreenModes()

OwnArray< DisplayMode * > SDL::Display::GetFullscreenModes ( ) const

inline

The display modes are sorted in this priority:

w -> largest to smallest
h -> largest to smallest
bits per pixel -> more colors to fewer colors
packed pixel layout -> largest to smallest
refresh rate -> highest to lowest
pixel density -> lowest to highest

Returns: a nullptr terminated array of display mode pointers on success.

Exceptions

Error on failure.

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

This automatically calls SDL_free after result is out of scope.

Since: This function is available since SDL 3.2.0.

See also: Display.GetAll

◆ GetName()

const char * SDL::Display::GetName ( ) const

inline

Returns: the name of a display or nullptr on failure; 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: Display.GetAll

◆ GetNaturalOrientation()

DisplayOrientation SDL::Display::GetNaturalOrientation ( ) const

inline

Returns: the DisplayOrientation enum value of the display, or ORIENTATION_UNKNOWN if it isn't available.

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

Since: This function is available since SDL 3.2.0.

See also: Display.GetAll

◆ GetPrimary()

static Display SDL::Display::GetPrimary ( )

inlinestatic

Returns: the instance ID of the primary display 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: Display.GetAll

◆ GetProperties()

PropertiesRef SDL::Display::GetProperties ( ) const

inline

The following read-only properties are provided by SDL:

prop::Display.HDR_ENABLED_BOOLEAN: true if the display has HDR headroom above the SDR white point. This is for informational and diagnostic purposes only, as not all platforms provide this information at the display level.

On KMS/DRM:

prop::Display.KMSDRM_PANEL_ORIENTATION_NUMBER: the "panel orientation" property for the display in degrees of clockwise rotation. Note that this is provided only as a hint, and the application is responsible for any coordinate transformations needed to conform to the requested display orientation.

Returns: a valid property ID 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.

◆ GetUsableBounds()

Rect SDL::Display::GetUsableBounds ( ) const

inline

This is the same area as Display.GetBounds() 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.

Returns: the Rect structure filled in with the display bounds 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: Display.GetBounds; Display.GetAll

◆ operator bool()

constexpr SDL::Display::operator bool ( ) const

inlineexplicitconstexpr

Returns: True if valid state, false otherwise.

◆ operator SDL_DisplayID()

constexpr SDL::Display::operator SDL_DisplayID ( ) const

inlineconstexpr

Returns: the underlying Display.

The documentation for this class was generated from the following file:

SDL3pp/SDL3pp_video.h

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Display()

Member Function Documentation

◆ GetAll()

◆ GetBounds()

◆ GetClosestFullscreenMode()

◆ GetContentScale()

◆ GetCurrentMode()

◆ GetCurrentOrientation()

◆ GetDesktopMode()

◆ GetForPoint()

◆ GetForRect()

◆ GetForWindow()

◆ GetFullscreenModes()

◆ GetName()

◆ GetNaturalOrientation()

◆ GetPrimary()

◆ GetProperties()

◆ GetUsableBounds()

◆ operator bool()

◆ operator SDL_DisplayID()