Table of Contents

Class Display

Namespace
Sdl3Sharp.Video.Windowing
Assembly
Sdl3Sharp.dll

Represents a display connected to the system

public abstract class Display : ISpanFormattable, IFormattable
Inheritance
Display
Implements
Derived
Display<TDriver>
Inherited Members

Remarks

The Id of a display is unique, remains unchanged while the display is connected to the system, and is never reused for the lifetime of the application. If a display is disconnected and then reconnected, it will get assigned a new Id.

For the most part Displays are not thread-safe, and most of their properties and methods should only be accessed from the main thread!

Displays are not driver-agnostic! Most of the time instance of this abstract class are of the concrete Display<TDriver> type with a specific windowing driver as the type argument. However, the Display type exists as a common abstraction.

To specify a concrete display type, use Display<TDriver> with a windowing driver that implements the IWindowingDriver interface (e.g. Display<Windows>).

Properties

Bounds

Gets the desktop area represented by this display

public Rect<int> Bounds { get; }

Property Value

Rect<int>

The desktop area represented by this display

Remarks

The primary display is often located at the origin (0, 0) in virtual screen space, but may be placed differently depending on the monitor layout.

This property should only be accessed from the main thread.

Exceptions

SdlException

Couldn't get the display bounds for the display (check TryGet(out string?) for more information)

ConnectedDisplays

Gets a collection of all the displays that are currently connected to the system

public static Display[] ConnectedDisplays { get; }

Property Value

Display[]

A collection of all the displays that are currently connected to the system

Remarks

The value of this property remains unchanged until an DisplayAdded or DisplayRemoved event is raised. You should not query this property too often, but rather cache the result and update the cache when such an event is raised.

This property should only be accessed from the main thread.

Exceptions

SdlException

Couldn't get the displays connected to the system (check TryGet(out string?) for more information)

ContentScale

Gets the content scale for this display

public float ContentScale { get; }

Property Value

float

The content scale for this display, or 0 if the content scale couldn't be retrieved successfully (check TryGet(out string?) for more information)

Remarks

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, DisplayScale should be used to determine the content scale factor for individual windows instead of content scale of the display for a window. That's because the per-window content scale factor may differ from the content scale factor of the display it is on, particularly on high-DPI and/or multi-monitor desktop configurations.

This property should only be accessed from the main thread.

CurrentDisplayMode

Gets the current display mode used by this display

public DisplayMode CurrentDisplayMode { get; }

Property Value

DisplayMode

The current display mode used by this display

Remarks

There's a difference between this property and DesktopDisplayMode when SDL runs fullscreen and has changed the resolution. In that case the value of this property reflects the current display mode and not the previous native display mode.

This property should only be accessed from the main thread.

Exceptions

SdlException

Couldn't get the current display mode for the display (check TryGet(out string?) for more information)

CurrentOrientation

Gets the current orientation of this display

public DisplayOrientation CurrentOrientation { get; }

Property Value

DisplayOrientation

The current orientation of this display, or Unknown if the orientation isn't available

Remarks

This property should only be accessed from the main thread.

DesktopDisplayMode

Gets the desktop display mode for this display

public DisplayMode DesktopDisplayMode { get; }

Property Value

DisplayMode

The desktop display mode for this display

Remarks

There's a difference between this property and CurrentDisplayMode when SDL runs fullscreen and has changed the resolution. In that case the value of this property reflects the previous native display mode and not the current display mode.

This property should only be accessed from the main thread.

Exceptions

SdlException

Couldn't get the desktop display mode for the display (check TryGet(out string?) for more information)

FullscreenDisplayModes

Gets a collection of the fullscreen display modes available for this display

public DisplayMode[] FullscreenDisplayModes { get; }

Property Value

DisplayMode[]

A collection of the fullscreen display modes available for this display

Remarks

The collection is sorted with the following priority:

  1. WidthLargest to smallest
  2. HeightLargest to smallest
  3. Bits per pixelMore colors to fewer colors
  4. Packed pixel layoutLargest to smallest
  5. RefreshRateHighest to lowest
  6. PixelDensityLowest to highest

This property should only be accessed from the main thread.

Exceptions

SdlException

Couldn't get the fullscreen display modes for the display

Id

Gets the id of this display

public uint Id { get; }

Property Value

uint

The id of this display

Remarks

The Id of a display is unique, remains unchanged while the display is connected to the system, and is never reused for the lifetime of the application. If a display is disconnected and then reconnected, it will get assigned a new Id.

An id of 0 indicates an invalid display.

IsHdrEnabled

Gets a value indicating whether this display has HDR headroom above the SDR white point

public bool IsHdrEnabled { get; }

Property Value

bool

A value indicating whether this display has HDR headroom above the SDR white point

Remarks

This property is for informational and diagnostic purposes only, as not all platforms provide this information at the display level.

This property should only be accessed from the main thread.

Name

Gets the name of this display

public string? Name { get; }

Property Value

string

The name of this display, or null if the name couldn't be retrieved successfully (check TryGet(out string?) for more information)

Remarks

This property should only be accessed from the main thread.

NaturalOrientation

Gets the natural orientation of this display

public DisplayOrientation NaturalOrientation { get; }

Property Value

DisplayOrientation

The natural orientation of this display, or Unknown if the natural orientation isn't available

Remarks

This property should only be accessed from the main thread.

PrimaryDisplay

Gets the primary display of the system

public static Display PrimaryDisplay { get; }

Property Value

Display

The primary display of the system

Remarks

Accessing this property on a system with no displays connected will always throw an SdlException.

This property should only be accessed from the main thread.

Exceptions

SdlException

Couldn't get the primary display (check TryGet(out string?) for more information)

Properties

Gets the properties associated with this display

public Properties? Properties { get; }

Property Value

Properties

The properties associated with this display, or null if the properties could not be retrieved successfully (check TryGet(out string?) for more information)

Remarks

This property should only be accessed from the main thread.

UsableBounds

Gets the usable desktop area represented by this display

public Rect<int> UsableBounds { get; }

Property Value

Rect<int>

The usable desktop area represented by this display

Remarks

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

This property should only be accessed from the main thread.

Exceptions

SdlException

Couldn't get the display usable bounds for the display (check TryGet(out string?) for more information)

Methods

~Display() 

protected ~Display()

ToString()

Returns a string that represents the current object.

public override string ToString()

Returns

string

A string that represents the current object.

ToString(IFormatProvider?)

Formats the value of the current instance using the specified format.

public string ToString(IFormatProvider? formatProvider)

Parameters

formatProvider IFormatProvider

The provider to use to format the value.

-or-

A null reference (Nothing in Visual Basic) to obtain the numeric format information from the current locale setting of the operating system.

Returns

string

The value of the current instance in the specified format.

ToString(string?)

Formats the value of the current instance using the specified format.

public string ToString(string? format)

Parameters

format string

The format to use.

-or-

A null reference (Nothing in Visual Basic) to use the default format defined for the type of the IFormattable implementation.

Returns

string

The value of the current instance in the specified format.

ToString(string?, IFormatProvider?)

Formats the value of the current instance using the specified format.

public string ToString(string? format, IFormatProvider? formatProvider)

Parameters

format string

The format to use.

-or-

A null reference (Nothing in Visual Basic) to use the default format defined for the type of the IFormattable implementation.

formatProvider IFormatProvider

The provider to use to format the value.

-or-

A null reference (Nothing in Visual Basic) to obtain the numeric format information from the current locale setting of the operating system.

Returns

string

The value of the current instance in the specified format.

TryFormat(Span<char>, out int, ReadOnlySpan<char>, IFormatProvider?)

Tries to format the value of the current instance into the provided span of characters.

public bool TryFormat(Span<char> destination, out int charsWritten, ReadOnlySpan<char> format = default, IFormatProvider? provider = null)

Parameters

destination Span<char>

The span in which to write this instance's value formatted as a span of characters.

charsWritten int

When this method returns, contains the number of characters that were written in destination.

format ReadOnlySpan<char>

A span containing the characters that represent a standard or custom format string that defines the acceptable format for destination.

provider IFormatProvider

An optional object that supplies culture-specific formatting information for destination.

Returns

bool

true if the formatting was successful; otherwise, false.

TryGetClosestFullscreenDisplayMode(int, int, out DisplayMode, float, bool)

Tries to get the closest fullscreen match to the specified display mode for this display

public bool TryGetClosestFullscreenDisplayMode(int width, int height, out DisplayMode displayMode, float refreshRate = 0, bool includeHighDensityModes = false)

Parameters

width int

The desired width of the display mode, in pixels

height int

The desired height of the display mode, in pixels

displayMode DisplayMode

The resulting closest matching display mode that is equal to or larger than the specified display mode, if this method returns true

refreshRate float

The desired refresh rate of the display mode, in Hz (hertz), or 0 (the default) for the desktop refresh rate

includeHighDensityModes bool

A value indicating whether high-density display modes should be included in the search

Returns

bool

true, if a matching display mode was found successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

The available display modes are searched and the displayMode parameter will be filled in with the closest mode matching the requested display mode. If refreshRate is 0 then the requested refresh rate will default to the desktop refresh rate. The display modes are searched with size being a first priority, format being a second priority, and finally checking the refresh rate. If all the available display modes are too small, then false is returned.

This method should only be called from the main thread.

TryGetFromPoint(in Point<int>, out Display?)

Tries to get the display that contains the specified point in screen space

public static bool TryGetFromPoint(in Point<int> point, out Display? display)

Parameters

point Point<int>

The point in screen space to get the display for

display Display

The display that contains the specified point in screen space, if this method returns true; otherwise, null

Returns

bool

true, if the display containing the specified point in screen space was found successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

This method should only be called from the main thread.

TryGetFromRect(in Rect<int>, out Display?)

Tries to get the display that contains the majority of the specified rectangle in screen space

public static bool TryGetFromRect(in Rect<int> rect, out Display? display)

Parameters

rect Rect<int>

The rectangle in screen space to get the display for

display Display

The display that contains the majority of the specified rectangle in screen space, if this method returns true; otherwise, null

Returns

bool

true, if a display containing the majority of the specified rectangle in screen space was found successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

This method should only be called from the main thread.