Table of Contents

Class GraphicsPresenter

Namespace
Stride.Graphics
Assembly
Stride.Graphics.dll

Represents an abstraction over a Swap-Chain.

public abstract class GraphicsPresenter : ComponentBase, IDisposable, IComponent, IReferencable, ICollectorHolder
Inheritance
object
GraphicsPresenter
Implements
Derived
Inherited Members
Extension Methods

Remarks

A Swap-Chain is a collection of same-sized buffers (one front-buffer, one or more -usually one- Back-Buffer, and an optional Depth-Stencil Buffer) that are used to present the final rendered image to the screen.

In order to create a new GraphicsPresenter, a GraphicsDevice should have been initialized first.

Constructors

GraphicsPresenter(GraphicsDevice, PresentationParameters)

Initializes a new instance of the GraphicsPresenter class.

protected GraphicsPresenter(GraphicsDevice device, PresentationParameters presentationParameters)

Parameters

device GraphicsDevice

The Graphics Device.

presentationParameters PresentationParameters

The parameters describing the buffers the device will present to.

Exceptions

ArgumentNullException

device is null.

ArgumentNullException

presentationParameters is null.

NotSupportedException

The Depth-Stencil format specified is not supported.

Properties

BackBuffer

Gets the default Back-Buffer for the Graphics Presenter.

public abstract Texture BackBuffer { get; }

Property Value

Texture

The Texture where rendering will happen, which will then be presented to the front-buffer.

DepthStencilBuffer

Gets the default Depth-Stencil Buffer for the Graphics Presenter.

public Texture DepthStencilBuffer { get; protected set; }

Property Value

Texture

The Texture where depth (Z) values will be written, and optionally also stencil masking values.

Remarks

If the Depth-Stencil Buffer is the one created by this Graphics Presenter, it is attached to it its lifetime is managed by this instance. If a derived class needs to set a custom Depth-Stencil Buffer, it should first call DetachDepthStencilBuffer() to release the current one.

Description

Gets the parameters describing the Resources and behavior of the Graphics Presenter.

public PresentationParameters Description { get; }

Property Value

PresentationParameters

GraphicsDevice

Gets the Graphics Device the Graphics Presenter is associated to.

public GraphicsDevice GraphicsDevice { get; }

Property Value

GraphicsDevice

The Graphics Device that will be used for managing the Buffers and Textures, and starting/ending a frame.

IsFullScreen

Gets or sets a value indicating if the Graphics Presenter is in full-screen mode.

public abstract bool IsFullScreen { get; set; }

Property Value

bool

A value indicating whether the presentation will be in full screen.

  • true if the presentation will be in full screen.
  • false if the presentation will be in a window.

Remarks

This property is only valid on desktop Windows. It has no effect on UWP.

NativePresenter

Gets the underlying native presenter.

public abstract object NativePresenter { get; }

Property Value

object

The native presenter. Depending on platform, for exmaple, it can be a Silk.NET.DXGI.IDXGISwapChain or Silk.NET.DXGI.IDXGISwapChain1 or null.

PresentInterval

Gets or sets the presentation interval of the Graphics Presenter.

public PresentInterval PresentInterval { get; set; }

Property Value

PresentInterval

A value of PresentInterval indicating how often the display should be updated. The default value is Default, which is to wait for one vertical blanking.

Methods

BeginDraw(CommandList)

Marks the beginning of a frame that will be presented later by the Graphics Presenter.

public virtual void BeginDraw(CommandList commandList)

Parameters

commandList CommandList

The Command List where rendering commands will be registered.

Remarks

When overriden in a derived class, this method should prepare the Graphics Presenter to receive graphics commands to be executed at the beginning of the current frame.

CreateDepthStencilBuffer()

Creates the Depth-Stencil Buffer.

protected virtual void CreateDepthStencilBuffer()

Remarks

When overriden in a derived class, this method allows to create a custom Depth-Stencil Buffer when initializing the Graphics Presenter.

By default, if a depth format has been specified, a Depth-Stencil Buffer is created with the same size as the Back-Buffer.

Exceptions

NotSupportedException

The Depth-Stencil format specified is not supported.

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.

DestroyChildrenTextures(Texture)

Calls OnDestroyed(bool) for all children of the specified Texture.

protected List<Texture> DestroyChildrenTextures(Texture parentTexture)

Parameters

parentTexture Texture

The parent Texture whose children are to be destroyed.

Returns

List<Texture>

A list of the children Textures which were destroyed.

DetachDepthStencilBuffer()

Detaches the current Depth-Stencil Buffer from the Graphics Presenter.

protected void DetachDepthStencilBuffer()

Remarks

If DepthStencilBuffer is the Depth-Stencil Buffer created by this Graphics Presenter, it is attached to it its lifetime is managed by this instance. If a derived class needs to set a custom Depth-Stencil Buffer, it should first call this method to detach the current one.

EndDraw(CommandList, bool)

Marks the end of a frame that will be presented later by the Graphics Presenter.

public virtual void EndDraw(CommandList commandList, bool present)

Parameters

commandList CommandList

The Command List where rendering commands will be registered.

present bool

A value indicating whether the frame will be presented, i.e. if the Back-Buffer will be shown to the screen.

Remarks

When overriden in a derived class, this method should prepare the Graphics Presenter to receive graphics commands to be executed at the end of the current frame.

OnDestroyed(bool)

Called when the Graphics Presenter has been destroyed.

protected virtual void OnDestroyed(bool immediately = false)

Parameters

immediately bool

A value indicating whether the resources used by the Graphics Presenter should be destroyed immediately (true), or if it can be deferred until it's safe to do so (false).

Remarks

When overriden in a derived class, this method allows to perform additional cleanup and release of associated resources.

OnRecreated()

Called when the Graphics Presenter has been reinitialized.

public virtual void OnRecreated()

Remarks

When overriden in a derived class, this method allows to perform additional resource creation, configuration, and initialization.

Exceptions

InvalidOperationException

DeviceWindowHandle is null or the Handle is invalid or zero.

Present()

Presents the Back-Buffer to the screen.

public abstract void Present()

Exceptions

GraphicsDeviceException

An unexpected error occurred while presenting. Check the status of the Graphics Device for more information (Status).

ProcessPresentationParameters()

Processes and adjusts the Presentation Parameters before initializing the Graphics Presenter.

protected virtual void ProcessPresentationParameters()

Remarks

When overriden in a derived class, this method allows to modify the specified Presentation Parameters before initializing the internal buffers and resources.

Resize(int, int, PixelFormat)

Resizes the Back-Buffer and the Depth-Stencil Buffer.

public void Resize(int width, int height, PixelFormat format)

Parameters

width int

The new width of the buffers of the Graphics Presenter, in pixels.

height int

The new height of the buffers of the Graphics Presenter, in pixels.

format PixelFormat

The new preferred pixel format for the Back-Buffer. The specified format may be overriden depending on Graphics Device features and configuration (for example, to use sRGB when appropriate).

Exceptions

NotSupportedException

The specified pixel format or size is not supported by the Graphics Device.

ResizeBackBuffer(int, int, PixelFormat)

Resizes the Back-Buffer.

protected abstract void ResizeBackBuffer(int width, int height, PixelFormat format)

Parameters

width int

The new width of the Back-Buffer, in pixels.

height int

The new height of the Back-Buffer, in pixels.

format PixelFormat

The new pixel format for the Back-Buffer.

Remarks

When implementing this method, the derived class should resize the Back-Buffer to the specified size and format.

Exceptions

NotSupportedException

The specified pixel format or size is not supported by the Graphics Device.

ResizeDepthStencilBuffer(int, int, PixelFormat)

Resizes the Depth-Stencil Buffer.

protected abstract void ResizeDepthStencilBuffer(int width, int height, PixelFormat format)

Parameters

width int

The new width of the Depth-Stencil Buffer, in pixels.

height int

The new height of the Depth-Stencil Buffer, in pixels.

format PixelFormat

The new pixel format for the Depth-Stencil Buffer.

Remarks

When implementing this method, the derived class should resize the Depth-Stencil Buffer to the specified size and format.

Exceptions

NotSupportedException

The specified depth format or size is not supported by the Graphics Device.

SetOutputColorSpace(ColorSpaceType, PixelFormat)

Sets the output color space of the Graphics Presenter and the pixel format to use for the Back-Buffer.

public void SetOutputColorSpace(ColorSpaceType colorSpace, PixelFormat format)

Parameters

colorSpace ColorSpaceType

The output color space the Graphics Presenter should use.

format PixelFormat

The pixel format to use for the Back-Buffer.

Remarks

The output color space can be used to render to HDR monitors.

Use the following combinations:

For rendering to a SDR display with gamma 2.2 Set a color space of ColorSpaceType.RgbFullG22NoneP709 with a Back-Buffer format R8G8B8A8_UNorm, R8G8B8A8_UNorm_SRgb, B8G8R8A8_UNorm, or B8G8R8A8_UNorm.
For rendering to a HDR display in scRGB (standard linear), and letting the Windows DWM do the color conversion Set a color space of ColorSpaceType.RgbFullG10NoneP709 with a Back-Buffer format R16G16B16A16_Float.
For rendering to a HDR display in HDR10 / BT.2100, with no color conversion by the Windows DWM, rendering needs to happen in the same color space as the display. Set a color space of ColorSpaceType.RgbFullG2084NoneP2020 with a Back-Buffer format R10G10B10A2_UNorm.

Note that this is currently only supported in Stride when using the Direct3D Graphics API. For more information about High Dynamic Range (HDR) rendering, see https://learn.microsoft.com/en-us/windows/win32/direct3darticles/high-dynamic-range.

Exceptions

NotSupportedException

The specified pixel format or size is not supported by the Graphics Device.

See Also

SwapChainGraphicsPresenter
RenderTargetGraphicsPresenter
Edit this page