Table of Contents

Class GraphicsDeviceManager

Namespace
Stride.Games
Assembly
Stride.Games.dll

Manages the GraphicsDevice life-cycle, providing access to it and events that can be subscribed to be notified of when the device is created, reset, or disposed.

public class GraphicsDeviceManager : ComponentBase, IDisposable, IComponent, IReferencable, ICollectorHolder, IGraphicsDeviceManager, IGraphicsDeviceService
Inheritance
object
GraphicsDeviceManager
Implements
Inherited Members
Extension Methods

Fields

DefaultBackBufferHeight

Default height for the Back-Buffer.

public static readonly int DefaultBackBufferHeight

Field Value

int

DefaultBackBufferWidth

Default width for the Back-Buffer.

public static readonly int DefaultBackBufferWidth

Field Value

int

Properties

DeviceCreationFlags

Gets or sets the device creation flags that will be used to create the Graphics Device.

public DeviceCreationFlags DeviceCreationFlags { get; set; }

Property Value

DeviceCreationFlags

GraphicsDevice

Gets the Graphics Device associated with this manager.

public GraphicsDevice GraphicsDevice { get; }

Property Value

GraphicsDevice

IsFullScreen

Gets or sets a value indicating whether the Graphics Device should present in full-screen mode.

public bool IsFullScreen { get; set; }

Property Value

bool

true if the device should render is full screen; otherwise, false.

PreferredBackBufferFormat

Gets or sets the preferred pixel format for the Back-Buffers.

public PixelFormat PreferredBackBufferFormat { get; set; }

Property Value

PixelFormat

Remarks

Not all pixel formats are supported for Back-Buffers by all Graphics Devices. Typical formats are R8G8B8A8_UNorm or B8G8R8A8_UNorm, although there are some more advanced formats depending on the Graphics Device capabilities and intended use (e.g. R16G16B16A16_Float for HDR rendering).

PreferredBackBufferHeight

Gets or sets the preferred height of the Back-Buffer, in pixels.

public int PreferredBackBufferHeight { get; set; }

Property Value

int

PreferredBackBufferWidth

Gets or sets the preferred width of the Back-Buffer, in pixels.

public int PreferredBackBufferWidth { get; set; }

Property Value

int

PreferredColorSpace

Gets or sets the preferred color space for the Back-Buffers.

public ColorSpace PreferredColorSpace { get; set; }

Property Value

ColorSpace

PreferredDepthStencilFormat

Gets or sets the preferred format for the Depth-Stencil Buffer.

public PixelFormat PreferredDepthStencilFormat { get; set; }

Property Value

PixelFormat

Remarks

Not all formats are supported for Depth-Stencil Buffers by all Graphics Devices. Typical formats are D24_UNorm_S8_UInt or D32_Float_S8X24_UInt.

The format also determines the number of bits used for the depth and stencil buffers. For example. the D24_UNorm_S8_UInt format uses 24 bits for the Depth-Buffer and 8 bits for the Stencil-Buffer, while D32_Float uses 32 bits for the Depth-Buffer and no Stencil-Buffer.

PreferredFullScreenOutputIndex

Gets or sets the preferred output (monitor) index to use when switching to fullscreen mode. Doesn't have any effect when windowed mode is used.

public int PreferredFullScreenOutputIndex { get; set; }

Property Value

int

PreferredGraphicsProfile

Gets or sets the graphics profiles that are going to be tested when initializing the Graphics Device, in order of preference.

public GraphicsProfile[] PreferredGraphicsProfile { get; set; }

Property Value

GraphicsProfile[]

Remarks

By default, the preferred graphics profiles are, in order of preference, better first: Level_11_1, Level_11_0, Level_10_1, Level_10_0, Level_9_3, Level_9_2, and Level_9_1.

PreferredMultisampleCount

Gets or sets the level of multisampling for the Back-Buffers.

public MultisampleCount PreferredMultisampleCount { get; set; }

Property Value

MultisampleCount

PreferredRefreshRate

Gets or sets the preferred refresh rate, in hertz (number of frames per second).

public Rational PreferredRefreshRate { get; set; }

Property Value

Rational

The preferred refresh rate as a Rational value, where the numerator is the number of frames per second and the denominator is usually 1 (e.g., 60 frames per second is represented as 60 / 1). However, some adapters may support fractional refresh rates, such as 59.94 Hz, which would be represented as 5994 / 100.

RequiredAdapterUid

Gets or sets the unique identifier of the Graphis Adapter that should be used to create the Graphics Device.

public string RequiredAdapterUid { get; set; }

Property Value

string

If this property is set to a non-null string the engine will try to initialize the Graphics Device to present to an adapter with the same unique Id

ShaderProfile

Gets or sets the Shader graphics profile that will be used to compile shaders.

public GraphicsProfile? ShaderProfile { get; set; }

Property Value

GraphicsProfile?

Remarks

If this property is not set, the profile used to compile Shaders will be taken from the Graphics Device. based on the list provided by PreferredGraphicsProfile.

SupportedOrientations

Gets or sets the supported orientations for displaying the Back-Buffers.

public DisplayOrientation SupportedOrientations { get; set; }

Property Value

DisplayOrientation

SynchronizeWithVerticalRetrace

Gets or sets a value indicating whether the Graphics Device should synchronize with the vertical retrace, commonly known as VSync.

public bool SynchronizeWithVerticalRetrace { get; set; }

Property Value

bool

true to synchronize with the vertical retrace, which can help prevent screen tearing and ensure smoother animations by waiting for the monitor to finish displaying the current frame; false to not synchronize, which may result in faster frame rates but can lead to screen tearing.

Methods

ApplyChanges()

Applies the changes in the graphics settings and changes or recreates the GraphicsDevice according to the new values.
Does not have any effect if the GraphicsDevice is null.

public void ApplyChanges()

Exceptions

InvalidOperationException

Thrown if the Graphics Device could not be created or reconfigured.

CanResetDevice(GraphicsDeviceInformation)

Determines whether the Graphics Device is compatible with the the specified new GraphicsDeviceInformation and can be reset with it.

protected virtual bool CanResetDevice(GraphicsDeviceInformation newDeviceInfo)

Parameters

newDeviceInfo GraphicsDeviceInformation

The new device information to check compatibility with.

Returns

bool

true if the Graphics Device is compatible with newDeviceInfo and can be reinitialized with the new settings; otherwise, false.

Destroy()

Disposes the object's resources.

protected override void Destroy()

Remarks

Override in a derived class to implement disposal logic specific to it.

This method is automatically called whenever a call to Dispose() (or to Release()) has decreased the internal reference count to zero, meaning no other objects (hopefully) hold a reference to this one and its resources can be safely released.

FindBestDevice(bool)

Finds the best Graphics Device configuration that is compatible with the set preferences.

protected virtual GraphicsDeviceInformation FindBestDevice(bool anySuitableDevice)

Parameters

anySuitableDevice bool

A value indicating whether to search for any suitable device on any of the available adapters (true) or only from the default adapter (false).

Returns

GraphicsDeviceInformation

The graphics device information.

Exceptions

InvalidOperationException

None of the graphics profiles specified in PreferredGraphicsProfile are supported.

InvalidOperationException

A compatible screen mode could not be found based on the current settings. Check the full-screen mode, the preferred Back-Buffer width and height, and the preferred Back-Buffer format.

IsPreferredProfileAvailable(GraphicsProfile[], out GraphicsProfile)

Determines whether any of the preferred graphics profiles is available on the system.

protected virtual bool IsPreferredProfileAvailable(GraphicsProfile[] preferredProfiles, out GraphicsProfile availableProfile)

Parameters

preferredProfiles GraphicsProfile[]

An array of preferred graphics profiles to check for availability. The profiles should be ordered by preference, with the most preferred profile first.

availableProfile GraphicsProfile

When the method returns, contains the highest graphics profile supported by the system that meets or exceeds the preferences specified in preferredProfiles. If no preferred profile is available, this will contain the lowest supported graphics profile.

Returns

bool

true if a graphics profile that meets or exceeds one of the preferred profiles is available; otherwise, false.

OnDeviceCreated(object, EventArgs)

Method called when the Graphics Device is created. Invokes the DeviceCreated event.

protected virtual void OnDeviceCreated(object sender, EventArgs args)

Parameters

sender object
args EventArgs

OnDeviceDisposing(object, EventArgs)

Method called when the Graphics Device is about to be disposed. Invokes the DeviceDisposing event.

protected virtual void OnDeviceDisposing(object sender, EventArgs args)

Parameters

sender object
args EventArgs

OnDeviceReset(object, EventArgs)

Method called when the Graphics Device is reset. Invokes the DeviceReset event.

protected virtual void OnDeviceReset(object sender, EventArgs args)

Parameters

sender object
args EventArgs

OnDeviceResetting(object, EventArgs)

Method called when the Graphics Device is resetting, but before it is actually reset. Invokes the DeviceResetting event.

protected virtual void OnDeviceResetting(object sender, EventArgs args)

Parameters

sender object
args EventArgs

OnPreparingDeviceSettings(object, PreparingDeviceSettingsEventArgs)

Method called when the Graphics Device is preparing to be created or reset, so the application can examine or modify the device settings before the device is created or reset. Invokes the PreparingDeviceSettings event.

protected virtual void OnPreparingDeviceSettings(object sender, PreparingDeviceSettingsEventArgs args)

Parameters

sender object
args PreparingDeviceSettingsEventArgs

RankDevices(List<GraphicsDeviceInformation>)

Ranks a list of GraphicsDeviceInformations before creating a new Graphics Device.

protected virtual void RankDevices(List<GraphicsDeviceInformation> foundDevices)

Parameters

foundDevices List<GraphicsDeviceInformation>

A list of possible device configurations to be ranked and reordered.

SelectOrientation(DisplayOrientation, int, int, bool)

Determines the appropriate display orientation based on the specified parameters.

protected static DisplayOrientation SelectOrientation(DisplayOrientation orientation, int width, int height, bool allowLandscapeLeftAndRight)

Parameters

orientation DisplayOrientation

The desired display orientation. If set to Default, the orientation will be determined based on the provided dimensions and landscape allowance.

width int

The width of the display area, in pixels.

height int

The height of the display area, in pixels.

allowLandscapeLeftAndRight bool

A value indicating whether both landscape orientations (LandscapeLeft and LandscapeRight) are allowed.

Returns

DisplayOrientation

The selected DisplayOrientation based on the input parameters.

Events

DeviceCreated

Occurs when a new Graphics Device is successfully created.

public event EventHandler<EventArgs> DeviceCreated

Event Type

EventHandler<EventArgs>

DeviceDisposing

Occurs when the Graphics Device is being disposed.

public event EventHandler<EventArgs> DeviceDisposing

Event Type

EventHandler<EventArgs>

DeviceReset

Occurs when the Graphics Device is being reset.

public event EventHandler<EventArgs> DeviceReset

Event Type

EventHandler<EventArgs>

DeviceResetting

Occurs when the Graphics Device is being reset, but before it is actually reset.

public event EventHandler<EventArgs> DeviceResetting

Event Type

EventHandler<EventArgs>

PreparingDeviceSettings

Occurs when the Graphics Device is being initialized to give a chance to the application at adjusting the final settings for the device creation.

public event EventHandler<PreparingDeviceSettingsEventArgs> PreparingDeviceSettings

Event Type

EventHandler<PreparingDeviceSettingsEventArgs>
Edit this page