Class GraphicsDeviceManager
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
-
objectGraphicsDeviceManager
- Implements
- Inherited Members
- Extension Methods
Fields
DefaultBackBufferHeight
Default height for the Back-Buffer.
public static readonly int DefaultBackBufferHeight
Field Value
DefaultBackBufferWidth
Default width for the Back-Buffer.
public static readonly int DefaultBackBufferWidth
Field Value
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
GraphicsDevice
Gets the Graphics Device associated with this manager.
public GraphicsDevice GraphicsDevice { get; }
Property Value
IsFullScreen
Gets or sets a value indicating whether the Graphics Device should present in full-screen mode.
public bool IsFullScreen { get; set; }
Property Value
MaximumPipelineCacheSize
Gets or sets the size in bytes above which the file of an earlier run is not merged (PersistPipelineCache), so the cache starts over from what this run builds. The pipelines of every earlier run stay in the file otherwise, and in development every shader edit adds some. 256 MB by default; set it before the device is created.
public long MaximumPipelineCacheSize { get; set; }
Property Value
Remarks
A game whose own pipelines take more than the limit would never get its file merged: raise the limit for it.
PersistPipelineCache
Gets or sets whether the driver's pipeline cache is kept between runs: the file of an earlier run is merged
into the Graphics Device when it is created, and the device's cache is written when it is disposed, so the
driver does not build the pipelines of the earlier runs again. The file is pipelines-<uuid>.bin in
the application's cache (ApplicationCache), one per device and driver
(PipelineCacheUuid); the file of another version of the driver is not
merged. true by default; set it before the device is created to skip the merge. On an API
without an exposed pipeline cache (Direct3D) nothing is written.
public bool PersistPipelineCache { get; set; }
Property Value
Remarks
The folder is kept small as the file is written: the file of another driver or device that nothing wrote for 30 days is removed, since every driver update has a new UUID, and so is a temporary file a crash left. A driver never drops a pipeline from its cache, so a file over MaximumPipelineCacheSize is not merged and the cache starts over from what the run builds.
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 Stride.Graphics.PixelFormat.R8G8B8A8_UNorm or Stride.Graphics.PixelFormat.B8G8R8A8_UNorm, although there are some more advanced formats depending on the Graphics Device capabilities and intended use (e.g. Stride.Graphics.PixelFormat.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
PreferredBackBufferWidth
Gets or sets the preferred width of the Back-Buffer, in pixels.
public int PreferredBackBufferWidth { get; set; }
Property Value
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 Stride.Graphics.PixelFormat.D24_UNorm_S8_UInt or Stride.Graphics.PixelFormat.D32_Float_S8X24_UInt.
The format also determines the number of bits used for the depth and stencil buffers. For example. the Stride.Graphics.PixelFormat.D24_UNorm_S8_UInt format uses 24 bits for the Depth-Buffer and 8 bits for the Stencil-Buffer, while Stride.Graphics.PixelFormat.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
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: Stride.Graphics.GraphicsProfile.Level_11_1, Stride.Graphics.GraphicsProfile.Level_11_0, Stride.Graphics.GraphicsProfile.Level_10_1, Stride.Graphics.GraphicsProfile.Level_10_0, Stride.Graphics.GraphicsProfile.Level_9_3, Stride.Graphics.GraphicsProfile.Level_9_2, and Stride.Graphics.GraphicsProfile.Level_9_1.
PreferredMultisampleCount
Gets or sets the level of multisampling for the Back-Buffers.
public MultisampleCount PreferredMultisampleCount { get; set; }
Property Value
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 as5994 / 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.
SkipBackBufferClampToWindow
When set, the requested back-buffer size is honoured as-is and any clamp to the host window's client area is skipped (both in ConfirmRenderingSettings(bool) and in the GraphicsPresenter's swap-chain creation).
public bool SkipBackBufferClampToWindow { get; set; }
Property Value
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 by resizing the GraphicsDevice's presenter.
Does not have any effect if the GraphicsDevice is null.
public void ApplyChanges()
Exceptions
- NotSupportedException
The new settings need another Graphics Device (for example another graphics profile): a device is never re-created.
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
newDeviceInfoGraphicsDeviceInformationThe new device information to check compatibility with.
Returns
- bool
true if the Graphics Device is compatible with
newDeviceInfoand 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
anySuitableDeviceboolA 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
preferredProfilesGraphicsProfile[]An array of preferred graphics profiles to check for availability. The profiles should be ordered by preference, with the most preferred profile first.
availableProfileGraphicsProfileWhen 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
senderobjectargsEventArgs
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
senderobjectargsEventArgs
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
senderobjectargsPreparingDeviceSettingsEventArgs
RankDevices(List<GraphicsDeviceInformation>)
Ranks a list of GraphicsDeviceInformations before creating a new Graphics Device.
protected virtual void RankDevices(List<GraphicsDeviceInformation> foundDevices)
Parameters
foundDevicesList<GraphicsDeviceInformation>A list of possible device configurations to be ranked and reordered.
SavePipelineCache()
Writes the device's pipeline cache to its file now, as the device's disposal does, so the pipelines built so far survive a crash or a hard exit: a game calls it after its loading screen, where most of them are built. Does nothing while PersistPipelineCache is off, or before the device is created.
public void SavePipelineCache()
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
orientationDisplayOrientationThe desired display orientation. If set to Stride.Graphics.DisplayOrientation.Default, the orientation will be determined based on the provided dimensions and landscape allowance.
widthintThe width of the display area, in pixels.
heightintThe height of the display area, in pixels.
allowLandscapeLeftAndRightboolA value indicating whether both landscape orientations (Stride.Graphics.DisplayOrientation.LandscapeLeft and Stride.Graphics.DisplayOrientation.LandscapeRight) are allowed.
Returns
- DisplayOrientation
The selected Stride.Graphics.DisplayOrientation based on the input parameters.
- Returns Stride.Graphics.DisplayOrientation.Portrait if the height is greater than or equal to the width.
- If landscape is allowed, returns a combination of Stride.Graphics.DisplayOrientation.LandscapeLeft and Stride.Graphics.DisplayOrientation.LandscapeRight.
- Otherwise, returns Stride.Graphics.DisplayOrientation.LandscapeRight.
Events
DeviceCreated
Occurs when a new Graphics Device is successfully created.
public event EventHandler<EventArgs> DeviceCreated
Event Type
DeviceDisposing
Occurs when the Graphics Device is being disposed.
public event EventHandler<EventArgs> DeviceDisposing
Event Type
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