Table of Contents

Class GraphicsDevice

Namespace
Microsoft.Xna.Framework.Graphics
Assembly
MonoGame.Framework.dll

Performs primitive-based rendering, creates resources, handles system-level variables, adjusts gamma ramp levels, and creates shaders.

public class GraphicsDevice : IDisposable
Inheritance
GraphicsDevice
Implements
Inherited Members

Constructors

GraphicsDevice(GraphicsAdapter, GraphicsProfile, PresentationParameters)

Initializes a new instance of the GraphicsDevice class.

public GraphicsDevice(GraphicsAdapter adapter, GraphicsProfile graphicsProfile, PresentationParameters presentationParameters)

Parameters

adapter GraphicsAdapter

The graphics adapter.

graphicsProfile GraphicsProfile

The graphics profile.

presentationParameters PresentationParameters

The presentation options.

Exceptions

ArgumentNullException

presentationParameters is null.

GraphicsDevice(GraphicsAdapter, GraphicsProfile, bool, PresentationParameters)

Initializes a new instance of the GraphicsDevice class.

public GraphicsDevice(GraphicsAdapter adapter, GraphicsProfile graphicsProfile, bool preferHalfPixelOffset, PresentationParameters presentationParameters)

Parameters

adapter GraphicsAdapter

The graphics adapter.

graphicsProfile GraphicsProfile

The graphics profile.

preferHalfPixelOffset bool

Indicates if DX9 style pixel addressing or current standard pixel addressing should be used. This value is passed to UseHalfPixelOffset

presentationParameters PresentationParameters

The presentation options.

Exceptions

ArgumentNullException

presentationParameters is null.

Properties

Adapter

Gets the graphics adapter.

public GraphicsAdapter Adapter { get; }

Property Value

GraphicsAdapter

BlendFactor

The color used as blend factor when alpha blending.

public Color BlendFactor { get; set; }

Property Value

Color

Remarks

When only changing BlendFactor, use this rather than BlendFactor to only update BlendFactor so the whole BlendState does not have to be updated.

BlendState

Gets or sets a system-defined instance of a blend state object initialized for alpha blending. The default value is Opaque.

public BlendState BlendState { get; set; }

Property Value

BlendState

DepthStencilState

Gets or sets a system-defined instance of a depth-stencil state object. The default value is Default.

public DepthStencilState DepthStencilState { get; set; }

Property Value

DepthStencilState

DiscardColor

Get or set the color a RenderTarget2D is cleared to when it is set.

public static Color DiscardColor { get; set; }

Property Value

Color

DisplayMode

Retrieves the display mode's spatial resolution, color resolution, and refresh frequency.

public DisplayMode DisplayMode { get; }

Property Value

DisplayMode

GraphicsDebug

Access debugging APIs for the graphics subsystem.

public GraphicsDebug GraphicsDebug { get; set; }

Property Value

GraphicsDebug

GraphicsDeviceStatus

Retrieves the status of the device.

public GraphicsDeviceStatus GraphicsDeviceStatus { get; }

Property Value

GraphicsDeviceStatus

GraphicsProfile

Gets the graphics profile. The default value is Reach.

public GraphicsProfile GraphicsProfile { get; }

Property Value

GraphicsProfile

Indices

Gets or sets index data. The default value is null.

public IndexBuffer Indices { get; set; }

Property Value

IndexBuffer

IsContentLost

Gets a value that indicates whether the associated content was lost.

public bool IsContentLost { get; }

Property Value

bool

IsDisposed

Gets a value that indicates whether the object is disposed.

public bool IsDisposed { get; }

Property Value

bool

Metrics

The rendering information for debugging and profiling. The metrics are reset every frame after draw within Present().

public GraphicsMetrics Metrics { get; set; }

Property Value

GraphicsMetrics

PresentationParameters

Gets the presentation parameters associated with this graphics device.

public PresentationParameters PresentationParameters { get; }

Property Value

PresentationParameters

RasterizerState

Gets or sets rasterizer state. The default value is CullCounterClockwise.

public RasterizerState RasterizerState { get; set; }

Property Value

RasterizerState

RenderTargetCount

Gets the amount of render targets bound to this device.

public int RenderTargetCount { get; }

Property Value

int

ResourcesLost

Gets a value that indicates whether the resources were lost.

public bool ResourcesLost { get; set; }

Property Value

bool

SamplerStates

Retrieves a collection of SamplerState objects for the current GraphicsDevice.

public SamplerStateCollection SamplerStates { get; }

Property Value

SamplerStateCollection

ScissorRectangle

Gets or sets the rectangle used for scissor testing. By default, the size matches the render target size.

public Rectangle ScissorRectangle { get; set; }

Property Value

Rectangle

Textures

Returns the collection of textures that have been assigned to the texture stages of the device.

public TextureCollection Textures { get; }

Property Value

TextureCollection

UseHalfPixelOffset

Indicates if DX9 style pixel addressing or current standard pixel addressing should be used. This flag is set to false by default. If UseHalfPixelOffset is true you have to add half-pixel offset to a Projection matrix. See also PreferHalfPixelOffset.

public bool UseHalfPixelOffset { get; }

Property Value

bool

Remarks

XNA uses DirectX9 for its graphics. DirectX9 interprets UV coordinates differently from other graphics API's. This is typically referred to as the half-pixel offset. MonoGame replicates XNA behavior if this flag is set to true.

VertexSamplerStates

Returns the collection of vertex sampler states.

public SamplerStateCollection VertexSamplerStates { get; }

Property Value

SamplerStateCollection

VertexTextures

Gets the collection of vertex textures that support texture lookup in the vertex shader using the texldl statement. The vertex engine contains four texture sampler stages.

public TextureCollection VertexTextures { get; }

Property Value

TextureCollection

Viewport

Gets or sets a viewport identifying the portion of the render target to receive draw calls.

public Viewport Viewport { get; set; }

Property Value

Viewport

Methods

Clear(Color)

Clears resource buffers.

public void Clear(Color color)

Parameters

color Color

Set this color value in all buffers.

Clear(ClearOptions, Color, float, int)

Clears resource buffers.

public void Clear(ClearOptions options, Color color, float depth, int stencil)

Parameters

options ClearOptions

Options for clearing a buffer.

color Color

Set this color value in all buffers.

depth float

Set this depth value in the buffer.

stencil int

Set this stencil value in the buffer.

Clear(ClearOptions, Vector4, float, int)

Clears resource buffers.

public void Clear(ClearOptions options, Vector4 color, float depth, int stencil)

Parameters

options ClearOptions

Options for clearing a buffer.

color Vector4

Set this color value in all buffers.

depth float

Set this depth value in the buffer.

stencil int

Set this stencil value in the buffer.

Dispose() 

public void Dispose()

Dispose(bool) 

protected virtual void Dispose(bool disposing)

Parameters

disposing bool

DrawIndexedPrimitives(PrimitiveType, int, int, int)

Draw geometry by indexing into the vertex buffer.

public void DrawIndexedPrimitives(PrimitiveType primitiveType, int baseVertex, int startIndex, int primitiveCount)

Parameters

primitiveType PrimitiveType

The type of primitives in the index buffer.

baseVertex int

Used to offset the vertex range indexed from the vertex buffer.

startIndex int

The index within the index buffer to start drawing from.

primitiveCount int

The number of primitives to render from the index buffer.

DrawIndexedPrimitives(PrimitiveType, int, int, int, int, int)

Draw geometry by indexing into the vertex buffer.

[Obsolete("Use DrawIndexedPrimitives(PrimitiveType primitiveType, int baseVertex, int startIndex, int primitiveCount) instead. In future versions this method can be removed.")]
public void DrawIndexedPrimitives(PrimitiveType primitiveType, int baseVertex, int minVertexIndex, int numVertices, int startIndex, int primitiveCount)

Parameters

primitiveType PrimitiveType

The type of primitives in the index buffer.

baseVertex int

Used to offset the vertex range indexed from the vertex buffer.

minVertexIndex int

This is unused and remains here only for XNA API compatibility.

numVertices int

This is unused and remains here only for XNA API compatibility.

startIndex int

The index within the index buffer to start drawing from.

primitiveCount int

The number of primitives to render from the index buffer.

Remarks

Note that minVertexIndex and numVertices are unused in MonoGame and will be ignored.

DrawInstancedPrimitives(PrimitiveType, int, int, int, int)

Draw instanced geometry from the bound vertex buffers and index buffer.

public void DrawInstancedPrimitives(PrimitiveType primitiveType, int baseVertex, int startIndex, int primitiveCount, int instanceCount)

Parameters

primitiveType PrimitiveType

The type of primitives in the index buffer.

baseVertex int

Used to offset the vertex range indexed from the vertex buffer.

startIndex int

The index within the index buffer to start drawing from.

primitiveCount int

The number of primitives in a single instance.

instanceCount int

The number of instances to render.

Remarks

Draw geometry with data from multiple bound vertex streams at different frequencies.

DrawInstancedPrimitives(PrimitiveType, int, int, int, int, int)

Draw instanced geometry from the bound vertex buffers and index buffer.

public void DrawInstancedPrimitives(PrimitiveType primitiveType, int baseVertex, int startIndex, int primitiveCount, int baseInstance, int instanceCount)

Parameters

primitiveType PrimitiveType

The type of primitives in the index buffer.

baseVertex int

Used to offset the vertex range indexed from the vertex buffer.

startIndex int

The index within the index buffer to start drawing from.

primitiveCount int

The number of primitives in a single instance.

baseInstance int

Used to offset the instance range indexed from the instance buffer.

instanceCount int

The number of instances to render.

Remarks

Draw geometry with data from multiple bound vertex streams at different frequencies.

DrawInstancedPrimitives(PrimitiveType, int, int, int, int, int, int)

Draw instanced geometry from the bound vertex buffers and index buffer.

[Obsolete("Use DrawInstancedPrimitives(PrimitiveType primitiveType, int baseVertex, int startIndex, int primitiveCount, int instanceCount) instead. In future versions this method can be removed.")]
public void DrawInstancedPrimitives(PrimitiveType primitiveType, int baseVertex, int minVertexIndex, int numVertices, int startIndex, int primitiveCount, int instanceCount)

Parameters

primitiveType PrimitiveType

The type of primitives in the index buffer.

baseVertex int

Used to offset the vertex range indexed from the vertex buffer.

minVertexIndex int

This is unused and remains here only for XNA API compatibility.

numVertices int

This is unused and remains here only for XNA API compatibility.

startIndex int

The index within the index buffer to start drawing from.

primitiveCount int

The number of primitives in a single instance.

instanceCount int

The number of instances to render.

Remarks

Note that minVertexIndex and numVertices are unused in MonoGame and will be ignored.

DrawPrimitives(PrimitiveType, int, int)

Draw primitives of the specified type from the currently bound vertexbuffers without indexing.

public void DrawPrimitives(PrimitiveType primitiveType, int vertexStart, int primitiveCount)

Parameters

primitiveType PrimitiveType

The type of primitives to draw.

vertexStart int

Index of the vertex to start at.

primitiveCount int

The number of primitives to draw.

DrawUserIndexedPrimitives<T>(PrimitiveType, T[], int, int, short[], int, int)

Draw primitives of the specified type by indexing into the given array of vertices with 16-bit indices.

public void DrawUserIndexedPrimitives<T>(PrimitiveType primitiveType, T[] vertexData, int vertexOffset, int numVertices, short[] indexData, int indexOffset, int primitiveCount) where T : struct, IVertexType

Parameters

primitiveType PrimitiveType

The type of primitives to draw with the vertices.

vertexData T[]

An array of vertices to draw.

vertexOffset int

The index in the array of the first vertex to draw.

numVertices int

The number of vertices to draw.

indexData short[]

The index data.

indexOffset int

The index in the array of indices of the first index to use

primitiveCount int

The number of primitives to draw.

Type Parameters

T

The type of the vertices.

Remarks

The VertexDeclaration will be found by getting VertexDeclaration from an instance of T and cached for subsequent calls.

DrawUserIndexedPrimitives<T>(PrimitiveType, T[], int, int, short[], int, int, VertexDeclaration)

Draw primitives of the specified type by indexing into the given array of vertices with 16-bit indices.

public void DrawUserIndexedPrimitives<T>(PrimitiveType primitiveType, T[] vertexData, int vertexOffset, int numVertices, short[] indexData, int indexOffset, int primitiveCount, VertexDeclaration vertexDeclaration) where T : struct

Parameters

primitiveType PrimitiveType

The type of primitives to draw with the vertices.

vertexData T[]

An array of vertices to draw.

vertexOffset int

The index in the array of the first vertex to draw.

numVertices int

The number of vertices to draw.

indexData short[]

The index data.

indexOffset int

The index in the array of indices of the first index to use

primitiveCount int

The number of primitives to draw.

vertexDeclaration VertexDeclaration

The layout of the vertices.

Type Parameters

T

The type of the vertices.

Remarks

All indices in the vertex buffer are interpreted relative to the specified vertexOffset. For example a value of zero in the array of indices points to the vertex at index vertexOffset in the array of vertices.

DrawUserIndexedPrimitives<T>(PrimitiveType, T[], int, int, int[], int, int)

Draw primitives of the specified type by indexing into the given array of vertices with 32-bit indices.

public void DrawUserIndexedPrimitives<T>(PrimitiveType primitiveType, T[] vertexData, int vertexOffset, int numVertices, int[] indexData, int indexOffset, int primitiveCount) where T : struct, IVertexType

Parameters

primitiveType PrimitiveType

The type of primitives to draw with the vertices.

vertexData T[]

An array of vertices to draw.

vertexOffset int

The index in the array of the first vertex to draw.

numVertices int

The number of vertices to draw.

indexData int[]

The index data.

indexOffset int

The index in the array of indices of the first index to use

primitiveCount int

The number of primitives to draw.

Type Parameters

T

The type of the vertices.

Remarks

The VertexDeclaration will be found by getting VertexDeclaration from an instance of T and cached for subsequent calls.

DrawUserIndexedPrimitives<T>(PrimitiveType, T[], int, int, int[], int, int, VertexDeclaration)

Draw primitives of the specified type by indexing into the given array of vertices with 32-bit indices.

public void DrawUserIndexedPrimitives<T>(PrimitiveType primitiveType, T[] vertexData, int vertexOffset, int numVertices, int[] indexData, int indexOffset, int primitiveCount, VertexDeclaration vertexDeclaration) where T : struct

Parameters

primitiveType PrimitiveType

The type of primitives to draw with the vertices.

vertexData T[]

An array of vertices to draw.

vertexOffset int

The index in the array of the first vertex to draw.

numVertices int

The number of vertices to draw.

indexData int[]

The index data.

indexOffset int

The index in the array of indices of the first index to use

primitiveCount int

The number of primitives to draw.

vertexDeclaration VertexDeclaration

The layout of the vertices.

Type Parameters

T

The type of the vertices.

Remarks

All indices in the vertex buffer are interpreted relative to the specified vertexOffset. For example value of zero in the array of indices points to the vertex at index vertexOffset in the array of vertices.

DrawUserPrimitives<T>(PrimitiveType, T[], int, int)

Draw primitives of the specified type from the data in an array of vertices without indexing.

public void DrawUserPrimitives<T>(PrimitiveType primitiveType, T[] vertexData, int vertexOffset, int primitiveCount) where T : struct, IVertexType

Parameters

primitiveType PrimitiveType

The type of primitives to draw with the vertices.

vertexData T[]

An array of vertices to draw.

vertexOffset int

The index in the array of the first vertex that should be rendered.

primitiveCount int

The number of primitives to draw.

Type Parameters

T

The type of the vertices.

Remarks

The VertexDeclaration will be found by getting VertexDeclaration from an instance of T and cached for subsequent calls.

DrawUserPrimitives<T>(PrimitiveType, T[], int, int, VertexDeclaration)

Draw primitives of the specified type from the data in the given array of vertices without indexing.

public void DrawUserPrimitives<T>(PrimitiveType primitiveType, T[] vertexData, int vertexOffset, int primitiveCount, VertexDeclaration vertexDeclaration) where T : struct

Parameters

primitiveType PrimitiveType

The type of primitives to draw with the vertices.

vertexData T[]

An array of vertices to draw.

vertexOffset int

The index in the array of the first vertex that should be rendered.

primitiveCount int

The number of primitives to draw.

vertexDeclaration VertexDeclaration

The layout of the vertices.

Type Parameters

T

The type of the vertices.

~GraphicsDevice() 

protected ~GraphicsDevice()

GetBackBufferData<T>(Rectangle?, T[], int, int)

Gets the Pixel data of what is currently drawn on screen. The format is whatever the current format of the backbuffer is.

public void GetBackBufferData<T>(Rectangle? rect, T[] data, int startIndex, int elementCount) where T : struct

Parameters

rect Rectangle?

The section of the back buffer to copy. null indicates the data will be copied from the entire back buffer.

data T[]

Array of data.

startIndex int

The first element to use.

elementCount int

The number of elements to use.

Type Parameters

T

A byte[] of size (ViewPort.Width * ViewPort.Height * 4)

Exceptions

ArgumentNullException

data is null

ArgumentException

GetBackBufferData<T>(T[])

Gets the Pixel data of what is currently drawn on screen. The format is whatever the current format of the backbuffer is.

public void GetBackBufferData<T>(T[] data) where T : struct

Parameters

data T[]

Array of data.

Type Parameters

T

A byte[] of size (ViewPort.Width * ViewPort.Height * 4)

GetBackBufferData<T>(T[], int, int)

Gets the Pixel data of what is currently drawn on screen. The format is whatever the current format of the backbuffer is.

public void GetBackBufferData<T>(T[] data, int startIndex, int elementCount) where T : struct

Parameters

data T[]

Array of data.

startIndex int

The first element to use.

elementCount int

The number of elements to use.

Type Parameters

T

A byte[] of size (ViewPort.Width * ViewPort.Height * 4)

GetRenderTargets()

Gets render target surfaces.

public RenderTargetBinding[] GetRenderTargets()

Returns

RenderTargetBinding[]

An array of bound render targets.

GetRenderTargets(RenderTargetBinding[])

Gets render target surfaces.

public void GetRenderTargets(RenderTargetBinding[] outTargets)

Parameters

outTargets RenderTargetBinding[]

When this method returns, contains an array of that description of bound render targets. This parameter is treated as uninitialized.

Present()

Presents the display with the contents of the next buffer in the sequence of back buffers owned by the GraphicsDevice.

public void Present()

Exceptions

InvalidOperationException

A render target is active.

Reset()

Resets the presentation parameters for the current GraphicsDevice.

public void Reset()

Reset(PresentationParameters)

Resets the current GraphicsDevice with the specified PresentationParameters.

public void Reset(PresentationParameters presentationParameters)

Parameters

presentationParameters PresentationParameters

Presentation parameters to set.

Exceptions

ArgumentNullException

presentationParameters is null

SetRenderTarget(RenderTarget2D)

Sets a new render target for this GraphicsDevice.

public void SetRenderTarget(RenderTarget2D renderTarget)

Parameters

renderTarget RenderTarget2D

A new render target for the device, or null to set the device render target to the back buffer of the device.

SetRenderTarget(RenderTargetCube, CubeMapFace)

Sets a new render target for this GraphicsDevice.

public void SetRenderTarget(RenderTargetCube renderTarget, CubeMapFace cubeMapFace)

Parameters

renderTarget RenderTargetCube

A new render target for the device, or null to set the device render target to the back buffer of the device.

cubeMapFace CubeMapFace

The cube map face type.

SetRenderTargets(params RenderTargetBinding[])

Sets an array of render targets.

public void SetRenderTargets(params RenderTargetBinding[] renderTargets)

Parameters

renderTargets RenderTargetBinding[]

An array of render targets.

SetVertexBuffer(VertexBuffer)

Sets or binds a vertex buffer to a device.

public void SetVertexBuffer(VertexBuffer vertexBuffer)

Parameters

vertexBuffer VertexBuffer

A vertex buffer.

SetVertexBuffer(VertexBuffer, int)

Sets or binds a vertex buffer to a device.

public void SetVertexBuffer(VertexBuffer vertexBuffer, int vertexOffset)

Parameters

vertexBuffer VertexBuffer

A vertex buffer.

vertexOffset int

The offset (in bytes) from the beginning of the buffer.

Exceptions

ArgumentOutOfRangeException

vertexOffset is less than 0 OR is greater than or equal to vertexBuffer.VertexCount.

SetVertexBuffers(params VertexBufferBinding[])

Sets the vertex buffers.

public void SetVertexBuffers(params VertexBufferBinding[] vertexBuffers)

Parameters

vertexBuffers VertexBufferBinding[]

An array of vertex buffers.

Exceptions

ArgumentOutOfRangeException

Length of vertexBuffers is more than max allowed number of vertex buffers.

Events

DeviceLost

Occurs when a GraphicsDevice is about to be lost (for example, immediately before a reset).

public event EventHandler<EventArgs> DeviceLost

Event Type

EventHandler<EventArgs>

DeviceReset

Occurs after a GraphicsDevice is reset, allowing an application to recreate all resources.

public event EventHandler<EventArgs> DeviceReset

Event Type

EventHandler<EventArgs>

DeviceResetting

Occurs when a GraphicsDevice is resetting, allowing the application to cancel the default handling of the reset.

public event EventHandler<EventArgs> DeviceResetting

Event Type

EventHandler<EventArgs>

Disposing

Occurs when Dispose() is called or when this object is finalized and collected by the garbage collector.

public event EventHandler<EventArgs> Disposing

Event Type

EventHandler<EventArgs>

ResourceCreated

Occurs when a resource is created.

public event EventHandler<ResourceCreatedEventArgs> ResourceCreated

Event Type

EventHandler<ResourceCreatedEventArgs>

ResourceDestroyed

Occurs when a resource is destroyed.

public event EventHandler<ResourceDestroyedEventArgs> ResourceDestroyed

Event Type

EventHandler<ResourceDestroyedEventArgs>
Edit this page