Class GorgonSwapChain

A swap chain used to display graphics to a window.

Inheritance

object

GorgonSwapChain

Implements

IGorgonGraphicsObject

IGorgonSwapChainInfo

IGorgonNamedObject

IDisposable

Inherited Members

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

object.GetType()

Namespace: Gorgon.Graphics.Core

Assembly: Gorgon.Graphics.Core.dll

Syntax

public sealed class GorgonSwapChain : IGorgonGraphicsObject, IGorgonSwapChainInfo, IGorgonNamedObject, IDisposable

Remarks

The swap chain is used to display graphics data into a window either through an exclusive full screen view of the rendering surface, or can be used to display the rendering data in the client area of the window.

By default, if a window loses focus and the swap chain is in full screen, it will revert to windowed mode. The swap chain will attempt to reacquire full screen mode when the window regains focus. This functionality can be disabled with the ExitFullScreenModeOnFocusLoss property if it does not suit the needs of the developer. Setting this value to false is mandatory in full screen multi-monitor applications, if the ExitFullScreenModeOnFocusLoss flag is false in this scenario. Be aware that when this flag is set to false, the behaviour will be unhandled and it will be the responsibility of the developer to handle application focus loss/restoration in multi-monitor environments.

Multiple swap chains can be set to full screen on different video outputs. When setting up for multiple video outputs in full screen, ensure that the window for the extra video output is located on the monitor attached to that video output. Failure to do so will keep the mode from switching.

If the swap chain is currently assigned to the RenderTargets property, and it is resized, it will do its best to ensure it stays bound to the active render target list (this also includes the current DepthStencilView. This only applies to the default RenderTargetView associated with the swap chain. If a user has created a custom GorgonRenderTarget2DView object for the swap chain, and assigned that view to the RenderTargets list, then it is their responsibility to ensure that the view is rebuilt and reassigned. Users may intercept a swap chain back buffer resize by hooking the SwapChainResizing and the SwapChainResized events.

Constructors

GorgonSwapChain(GorgonGraphics, Control, GorgonSwapChainInfo)

Initializes a new instance of the GorgonSwapChain class.

Declaration

public GorgonSwapChain(GorgonGraphics graphics, Control control, GorgonSwapChainInfo info)

Parameters

Type	Name	Description
GorgonGraphics	graphics	The graphics interface that created this object.
Control	control	The control bound to the swap chain.
GorgonSwapChainInfo	info	The information used to create the object.

Exceptions

Type	Condition
ArgumentNullException	Thrown when the graphics, info or the control parameter is null.
GorgonException	Thrown if the Format is not a display format.

See Also

GorgonGraphics

GorgonRenderTarget2DView

Properties

DoNotAutoResizeBackBuffer

Property to set or return whether the application should automatically resize the swap chain back buffers to match the Window client area size.

Declaration

public bool DoNotAutoResizeBackBuffer { get; set; }

Property Value

Type	Description
bool

Remarks

Developers may wish to use a smaller (or larger) back buffer size than is needed for the Window. This flag will enable developers to turn off Gorgon's automatic back buffer resizing and allow users to do their own resize operations via the ResizeBackBuffers(int, int) method when the window size changes.

warning

When setting this value to true, there will be a small performance penalty when the application calls the Present(int) method because the driver will have to scale the contents of the back buffer to fit the client area of the window (if the StretchBackBuffer property for the IGorgonSwapChainInfo passed in to the constructor is set to true).

See Also

GorgonGraphics

GorgonRenderTarget2DView

ExitFullScreenModeOnFocusLoss

Property to set or return whether to exit back into windowed mode when the application loses focus.

Declaration

public bool ExitFullScreenModeOnFocusLoss { get; set; }

Property Value

Type	Description
bool

Remarks

This flag controls the behavior of a full screen swap chain when the application loses focus. When set to true, the swap chain will exit full screen mode upon focus loss, and when the application regains focus, the swap chain will restore full screen mode.

This flag only affects the swap chain when it is in full screen mode. If the swap chain is in windowed mode, no action is taken.

The default value for this flag is true.

important

When using multiple swap chains in a multi-monitor set up (i.e. a swap chain on each monitor in full screen mode), then this flag should be set to false, otherwise the application will reset one of the swap chains back to windowed mode when the window on the other output gains focus.

Users of multi-monitor setups are responsible for handling their own screen state management when focus is lost or gained.

See Also

GorgonGraphics

GorgonRenderTarget2DView

Format

Property to return the format of the swap chain back buffer.

Declaration

public BufferFormat Format { get; }

Property Value

Type	Description
BufferFormat

See Also

GorgonGraphics

GorgonRenderTarget2DView

FullScreenVideoMode

Property to return the currently active full screen video mode.

Declaration

public ref readonly GorgonVideoMode? FullScreenVideoMode { get; }

Property Value

Type	Description
GorgonVideoMode?

Remarks

When IsWindowed is false, this value will be null.

See Also

GorgonGraphics

GorgonRenderTarget2DView

FullscreenOutput

Property to return the output that is currently being used for full screen mode by this swap chain.

Declaration

public IGorgonVideoOutputInfo FullscreenOutput { get; }

Property Value

Type	Description
IGorgonVideoOutputInfo

Remarks

When IsWindowed is false, this value will be null.

See Also

GorgonGraphics

GorgonRenderTarget2DView

Graphics

Property to return the graphics interface that built this object.

Declaration

public GorgonGraphics Graphics { get; }

Property Value

Type	Description
GorgonGraphics

See Also

GorgonGraphics

GorgonRenderTarget2DView

Height

Property to return the height of the swap chain back buffer.

Declaration

public int Height { get; }

Property Value

Type	Description
int

See Also

GorgonGraphics

GorgonRenderTarget2DView

IsInStandBy

Property to return whether the swap chain is in stand by mode.

Declaration

public bool IsInStandBy { get; }

Property Value

Type	Description
bool

Remarks

Stand by mode is entered when the Present(int) method detects that the window is occluded.

See Also

GorgonGraphics

GorgonRenderTarget2DView

IsWindowed

Property to return whether the swap chain is in windowed mode or not.

Declaration

public bool IsWindowed { get; }

Property Value

Type	Description
bool

Remarks

To enter or exit full screen mode on a swap chain, call the EnterFullScreen(in GorgonVideoMode, IGorgonVideoOutputInfo) or ExitFullScreen() methods.

See Also

EnterFullScreen(in GorgonVideoMode, IGorgonVideoOutputInfo)

EnterFullScreen(BufferFormat)

ExitFullScreen()

Name

Property to return the name of this object.

Declaration

public string Name { get; }

Property Value

Type	Description
string

See Also

GorgonGraphics

GorgonRenderTarget2DView

ParentForm

Property to return the parent form of the Window.

Declaration

public Form ParentForm { get; }

Property Value

Type	Description
Form

Remarks

If the Window is a Form, then this property will return the same value as Window.

See Also

GorgonGraphics

GorgonRenderTarget2DView

RenderTargetView

Property to return the default render target view for this swap chain.

Declaration

public GorgonRenderTarget2DView RenderTargetView { get; }

Property Value

Type	Description
GorgonRenderTarget2DView

See Also

GorgonGraphics

GorgonRenderTarget2DView

StretchBackBuffer

Property to return whether the back buffer contents will be stretched to fit the size of the presentation target area (typically the client area of the window).

Declaration

public bool StretchBackBuffer { get; }

Property Value

Type	Description
bool

See Also

GorgonGraphics

GorgonRenderTarget2DView

Width

Property to return the width of the swap chain back buffer.

Declaration

public int Width { get; }

Property Value

Type	Description
int

See Also

GorgonGraphics

GorgonRenderTarget2DView

Window

Property to return the window associated with the swap chain.

Declaration

public Control Window { get; }

Property Value

Type	Description
Control

See Also

GorgonGraphics

GorgonRenderTarget2DView

Methods

CopyBackBufferToImage()

Function to capture the back buffer data and place it into a IGorgonImage.

Declaration

public IGorgonImage CopyBackBufferToImage()

Returns

Type	Description
IGorgonImage	A new IGorgonImage that will contain the back buffer data.

Remarks

This method is similar to the CopyBackBufferToTexture(ResourceUsage, TextureBinding) method, but will instead copy the back buffer data into a IGorgonImage.

See Also

IGorgonImage

CopyBackBufferToTexture(ResourceUsage, TextureBinding)

Function to capture the back buffer data and place it into a new texture.

Declaration

public GorgonTexture2D CopyBackBufferToTexture(ResourceUsage usage, TextureBinding binding)

Parameters

Type	Name	Description
ResourceUsage	usage	The intended usage for the texture.
TextureBinding	binding	The binding mode for the texture.

Returns

Type	Description
GorgonTexture2D	The new texture.

Remarks

This method creates a copy of whatever is in the back buffer for the swap chain, and places that data into a new GorgonTexture2D.

Applications can define the usage and binding of the resulting texture so that the texture data can be displayed as a texture when rendering, or used as a staging texture. If the usage parameter is not Default, or Staging, then an exception will be thrown.

Exceptions

Type	Condition
GorgonException	Thrown when the usage parameter is not Default, or Staging.

See Also

GorgonTexture2D

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

Declaration

public void Dispose()

See Also

GorgonGraphics

GorgonRenderTarget2DView

EnterFullScreen(BufferFormat)

Function to enter full screen mode on the swap chain.

Declaration

public void EnterFullScreen(BufferFormat backbufferFormat = BufferFormat.R8G8B8A8_UNorm)

Parameters

Type	Name	Description
BufferFormat	backbufferFormat	[Optional] The format of the back buffer.

Remarks

This method will set the application up for full screen borderless windowed mode. This allows us to have a full screen experience, but without exclusively taking over the device (which can lead to issues in some cases - notably when Alt+Tabbing). To exit full screen mode, call ExitFullScreen().

When this method enters full screen, the ParentForm is resized to fit the entire screen, and the ParentForm is brought forth to cover the task bar. Any border decoration on the form is also removed.

If full screen exclusive mode is required, users can call the EnterFullScreen(in GorgonVideoMode, IGorgonVideoOutputInfo) overload instead.

Exceptions

Type	Condition
GorgonException	Thrown if the Window is not the same as the ParentForm.

See Also

EnterFullScreen(in GorgonVideoMode, IGorgonVideoOutputInfo)

EnterFullScreen(in GorgonVideoMode, IGorgonVideoOutputInfo)

Function to put the swap chain in full screen mode.

Declaration

public void EnterFullScreen(in GorgonVideoMode desiredMode, IGorgonVideoOutputInfo output)

Parameters

Type	Name	Description
GorgonVideoMode	desiredMode	The video mode to use when entering full screen.
IGorgonVideoOutputInfo	output	The output that will be used for full screen mode.

Remarks

This will transition the swap chain to full screen mode from windowed mode. If a render target view for this swap chain is bound to the pipeline, then it will be unbound before resetting its state.

If the desiredMode parameter does not match a supported video mode for the output, then the closest available video mode will be used and the desiredMode parameter will be updated to reflect the video mode that was chosen.

If the desiredMode parameter is the same as the FullScreenVideoMode property and the output parameter is the same as the FullscreenOutput property, then this method will do nothing.

When the swap chain is bound to a child control (e.g. a panel), then this method will throw an exception if called. Entering full screen is only supported on swap chains bound to a Windows Form.

Exceptions

Type	Condition
ArgumentNullException	Thrown when the output parameter is null.
ArgumentException	Thrown if the output is from a different video adapter than the one specified by VideoAdapter on the GorgonGraphics interface.
GorgonException	Thrown when the Window bound to this swap chain is not the ParentForm.

See Also

EnterFullScreen(BufferFormat)

ExitFullScreen()

ExitFullScreen()

Function to put the swap chain into windowed mode.

Declaration

public void ExitFullScreen()

Remarks

This will restore the swap chain to windowed mode from full screen mode. If a render target view for this swap chain is bound to the pipeline, then it will be unbound before resetting its state.

When the swap chain is already in windowed mode, then this method will do nothing.

See Also

EnterFullScreen(in GorgonVideoMode, IGorgonVideoOutputInfo)

Present(int)

Function to flip the buffers to the front buffer.

Declaration

public void Present(int interval = 0)

Parameters

Type	Name	Description
int	interval	[Optional] The vertical blank interval.

Remarks

If interval parameter is greater than 0, then this method will synchronize to the vertical blank count specified by interval Passing 0 will display the contents of the back buffer as soon as possible.

If the window that the swap chain is bound with is occluded and/or the swap chain is in between a mode switch, then this method will place the swap chain into stand by mode, and will recover (i.e. turn off stand by) once the device is ready for rendering again.

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown when the interval parameter is less than 0 or greater than 4. This is only thrown when Gorgon is compiled in DEBUG mode.
GorgonException	Thrown when the method encounters an unrecoverable error.

See Also

GorgonGraphics

GorgonRenderTarget2DView

ResizeBackBuffers(int, int)

Function to resize the back buffers for the swap chain.

Declaration

public void ResizeBackBuffers(int newWidth, int newHeight)

Parameters

Type	Name	Description
int	newWidth	The new width of the swap chain back buffers.
int	newHeight	The new height of the swap chain back buffers.

Remarks

This method will only resize the back buffers associated with the swap chain, and not the swap chain Window that it is bound with.

Developers who set the DoNotAutoResizeBackBuffer to true should use this method to resize the back buffers manually when a Window is resized. Otherwise, developers should rarely, if ever, have to call this method.

Exceptions

Type	Condition
ArgumentEmptyException	Thrown when the newWidth, or the newHeight parameter is less than 1.

See Also

GorgonGraphics

GorgonRenderTarget2DView

Events

SwapChainResized

Event called before the swap chain has been resized.

Declaration

public event EventHandler<SwapChainResizedEventArgs> SwapChainResized

Event Type

Type	Description
EventHandler<SwapChainResizedEventArgs>

See Also

GorgonGraphics

GorgonRenderTarget2DView

SwapChainResizing

Event called before the swap chain has been resized.

Declaration

public event EventHandler<SwapChainResizingEventArgs> SwapChainResizing

Event Type

Type	Description
EventHandler<SwapChainResizingEventArgs>

See Also

GorgonGraphics

GorgonRenderTarget2DView

Implements

IGorgonGraphicsObject

IGorgonSwapChainInfo

IGorgonNamedObject

IDisposable

Extension Methods

GorgonDebugExtensions.ValidateObject<T>(T, string)

GorgonNullExtensions.AsNullable<T>(object)

GorgonNullExtensions.IfNull<T>(object, T)

GorgonNullExtensions.IsNull(object)

See Also

GorgonGraphics

GorgonRenderTarget2DView