TSdlDisplay

A display.

Definition

Unit: Neslib.Sdl3.Video

type TSdlDisplay = record ... end;

Properties

Name	Description
Bounds	The desktop area represented by the display.
ContentScale	The content scale of a display.
Count	The number of currently connected displays.
CurrentMode	Information about the current display mode.
CurrentOrientation	The orientation of a display or TSdlDisplayOrientation.Unknown if it isn't available.
DesktopMode	Information about the desktop's display mode.
Displays	The currently connected displays.
FullScreenModes	An array of fullscreen display modes available on the display.
HdrEnabled	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.
Name	The name of a display.
NaturalOrientation	The orientation of a display when it is unrotated or TSdlDisplayOrientation.Unknown if it isn't available.
Primary	The primary display.
UsableBounds	The usable desktop area represented by the display, in screen coordinates.

Methods

Name	Description
ForPoint	Get the display containing a point.
ForRect	Get the display primarily containing a rect.
GetClosestFullscreenMode	Get the closest match to the requested display mode.

Property Descriptions

Bounds

The desktop area represented by the display.

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

property Bounds: TSdlRect read GetBounds

Type: TSdlRect

Exceptions

ESdlError: Raised on failure.

See Also

• UsableBounds

Remarks

This property should only be used on the main thread.

---

ContentScale

The content scale of a display.

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, TSdlWindow.DisplayScale should be used to query the content scale factor for individual windows instead of querying the display for a window and using this property, 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.

property ContentScale: Single read GetContentScale

Type: Single

Exceptions

ESdlError: Raised on failure.

See Also

• TSdlWindow.DisplayScale

Remarks

This property should only be used on the main thread.

---

Count

The number of currently connected displays.

class property Count: Integer read GetCount

Type: Integer

Exceptions

ESdlError: Raised on failure.

Remarks

This property should only be used on the main thread.

---

CurrentMode

Information about the current display mode.

There's a difference between this function and DesktopMode 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.

property CurrentMode: TSdlDisplayMode read GetCurrentMode

Type: TSdlDisplayMode

Exceptions

ESdlError: Raised on failure.

See Also

• DesktopMode

Remarks

This property should only be used on the main thread.

---

CurrentOrientation

The orientation of a display or TSdlDisplayOrientation.Unknown if it isn't available.

property CurrentOrientation: TSdlDisplayOrientation read GetCurrentOrientation

Type: TSdlDisplayOrientation

Remarks

This property should only be used on the main thread.

---

DesktopMode

Information about the desktop's display mode.

There's a difference between this property and CurrentMode when SDL runs fullscreen and has changed the resolution. In that case this property will return the previous native display mode, and not the current display mode.

property DesktopMode: TSdlDisplayMode read GetDesktopMode

Type: TSdlDisplayMode

Exceptions

ESdlError: Raised on failure.

See Also

• CurrentMode

Remarks

This property should only be used on the main thread.

---

Displays

The currently connected displays.

class property Displays[const AIndex: Integer]: TSdlDisplay read GetDisplay; default

Type: TSdlDisplay

Exceptions

ESdlError: Raised on failure.

Remarks

This property should only be used on the main thread.

---

FullScreenModes

An array of fullscreen display modes available on the display.

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

property FullScreenModes: TArray<TSdlDisplayMode> read GetFullScreenModes

Type: TArray<TSdlDisplayMode>

Exceptions

ESdlError: Raised on failure.

Remarks

This property should only be used on the main thread.

---

HdrEnabled

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.

property HdrEnabled: Boolean read GetHdrEnabled

Type: Boolean

Exceptions

ESdlError: Raised on failure.

Remarks

This property should only be used on the main thread.

---

Name

The name of a display.

property Name: String read GetName

Type: String

Exceptions

ESdlError: Raised on failure.

Remarks

This property should only be used on the main thread.

---

NaturalOrientation

The orientation of a display when it is unrotated or TSdlDisplayOrientation.Unknown if it isn't available.

property NaturalOrientation: TSdlDisplayOrientation read GetNaturalOrientation

Type: TSdlDisplayOrientation

Remarks

This property should only be used on the main thread.

---

Primary

The primary display.

class property Primary: TSdlDisplay read GetPrimary

Type: TSdlDisplay

Exceptions

ESdlError: Raised on failure.

Remarks

This function should only be called on the main thread.

---

UsableBounds

The usable desktop area represented by the display, in screen coordinates.

This is the same area as Bounds, 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.

property UsableBounds: TSdlRect read GetUsableBounds

Type: TSdlRect

Exceptions

ESdlError: Raised on failure.

See Also

• Bounds

Remarks

This property should only be used on the main thread.

---

Method Descriptions

ForPoint(TSdlPoint)

Get the display containing a point.

class function ForPoint(const APoint: TSdlPoint): TSdlDisplay; inline; static

Exceptions

ESdlError: Raised on failure.

Parameters

APoint: TSdlPoint : the point to query.

Returns

TSdlDisplay: The display containing the point.

See Also

• Bounds

Remarks

This function should only be called on the main thread.

---

ForRect(TSdlRect)

Get the display primarily containing a rect.

class function ForRect(const ARect: TSdlRect): TSdlDisplay; inline; static

Exceptions

ESdlError: Raised on failure.

Parameters

ARect: TSdlRect : the rect to query.

Returns

TSdlDisplay: The display entirely containing the rect or closest to the center of the rect on success.

See Also

• Bounds

Remarks

This function should only be called on the main thread.

---

GetClosestFullscreenMode(Integer, Integer, Single, Boolean)

Get the closest match to the requested display mode.

The available display modes are scanned and the closest mode matching the requested mode is 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.

function GetClosestFullscreenMode(const AW, AH: Integer; const ARefreshRate: Single = 0; const AIncludeHighDensityModes: Boolean = False): TSdlDisplayMode; inline

Exceptions

ESdlError: Raised on failure.

Parameters

AW: Integer : The width in pixels of the desired display mode.

AH: Integer : The height in pixels of the desired display mode.

ARefreshRate: Single = 0 : (optional) Refresh rate of the desired display mode, or 0.0 (default) for the desktop refresh rate.

AIncludeHighDensityModes: Boolean = False : (optional) Whether to include high density modes in the search (default False).

Returns

TSdlDisplayMode: The closest display mode equal to or larger than the desired mode.

See Also

• FullscreenModes

Remarks

This property should only be used on the main thread.

---