Gorgon
Show / Hide Table of Contents

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

| Edit this page View Source

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

| Edit this page View Source

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
| Edit this page View Source

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
| Edit this page View Source

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
| Edit this page View Source

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
| Edit this page View Source

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
| Edit this page View Source

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
| Edit this page View Source

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
| Edit this page View Source

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
| Edit this page View Source

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()
| Edit this page View Source

Name

Property to return the name of this object.

Declaration
public string Name { get; }
Property Value
Type Description
string
See Also
GorgonGraphics
GorgonRenderTarget2DView
| Edit this page View Source

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
| Edit this page View Source

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
| Edit this page View Source

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
| Edit this page View Source

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
| Edit this page View Source

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

| Edit this page View Source

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
| Edit this page View Source

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
| Edit this page View Source

Dispose()

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

Declaration
public void Dispose()
See Also
GorgonGraphics
GorgonRenderTarget2DView
| Edit this page View Source

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)
| Edit this page View Source

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()
| Edit this page View Source

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)
| Edit this page View Source

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
| Edit this page View Source

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

| Edit this page View Source

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
| Edit this page View Source

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
  • Edit this page
  • View Source
In this article
Back to top Copyright 2023 - Licensed under the MIT license by Michael Winsor (Tape_Worm).
Send comments on this topic to the author