Class RenderTarget2D

Namespace

Microsoft.Xna.Framework.Graphics

Assembly

MonoGame.Framework.dll

Represents a 2D texture resource that will be written to at the end of a render pass.

public class RenderTarget2D : Texture2D, IDisposable

Inheritance

object

GraphicsResource

Texture

Texture2D

RenderTarget2D

Implements

IDisposable

Inherited Members

Texture2D.Bounds

Texture2D.Width

Texture2D.Height

Texture2D.SetData<T>(int, int, Rectangle?, T[], int, int)

Texture2D.SetData<T>(int, Rectangle?, T[], int, int)

Texture2D.SetData<T>(T[], int, int)

Texture2D.SetData<T>(T[])

Texture2D.GetData<T>(int, int, Rectangle?, T[], int, int)

Texture2D.GetData<T>(int, Rectangle?, T[], int, int)

Texture2D.GetData<T>(T[], int, int)

Texture2D.GetData<T>(T[])

Texture2D.FromFile(GraphicsDevice, string, Action<byte[]>)

Texture2D.FromFile(GraphicsDevice, string)

Texture2D.FromStream(GraphicsDevice, Stream, Action<byte[]>)

Texture2D.FromStream(GraphicsDevice, Stream)

Texture2D.SaveAsJpeg(Stream, int, int)

Texture2D.SaveAsPng(Stream, int, int)

Texture2D.Reload(Stream)

Texture.Format

Texture.LevelCount

GraphicsResource.Dispose()

GraphicsResource.Disposing

GraphicsResource.GraphicsDevice

GraphicsResource.IsDisposed

GraphicsResource.Name

GraphicsResource.Tag

GraphicsResource.ToString()

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

Remarks

After a render pass the render target contains the color information of a rendered image.

Render targets represent a linear area of display memory and usually resides in the display memory of the display card. Because of this, objects must be recreated when the device is reset.

Constructors

RenderTarget2D(GraphicsDevice, int, int)

Creates a new RenderTarget2D instance with the specified parameters.

public RenderTarget2D(GraphicsDevice graphicsDevice, int width, int height)

Parameters

graphicsDevice GraphicsDevice

The graphics device to associate with this render target resource.

width int

Width, in pixels, of the render target.

height int

Height, in pixels, of the render target.

Exceptions

ArgumentNullException

The graphicsDevice parameter is null.

ArgumentOutOfRangeException

The width and/or height parameters less than or equal to zero.

RenderTarget2D(GraphicsDevice, int, int, bool, SurfaceFormat, DepthFormat)

Creates a new RenderTarget2D instance with the specified parameters.

public RenderTarget2D(GraphicsDevice graphicsDevice, int width, int height, bool mipMap, SurfaceFormat preferredFormat, DepthFormat preferredDepthFormat)

Parameters

graphicsDevice GraphicsDevice

The graphics device to associate with this render target resource.

width int

Width, in pixels, of the render target.

height int

Height, in pixels, of the render target.

mipMap bool

true if mipmapping is enabled; otherwise, false.

preferredFormat SurfaceFormat

The preferred surface format of the render target.

preferredDepthFormat DepthFormat

The preferred depth format of the render target.

Exceptions

ArgumentNullException

The graphicsDevice parameter is null.

ArgumentOutOfRangeException

The width and/or height parameters less than or equal to zero.

RenderTarget2D(GraphicsDevice, int, int, bool, SurfaceFormat, DepthFormat, int, RenderTargetUsage)

Creates a new RenderTarget2D instance with the specified parameters.

public RenderTarget2D(GraphicsDevice graphicsDevice, int width, int height, bool mipMap, SurfaceFormat preferredFormat, DepthFormat preferredDepthFormat, int preferredMultiSampleCount, RenderTargetUsage usage)

Parameters

graphicsDevice GraphicsDevice

The graphics device to associate with this render target resource.

width int

Width, in pixels, of the render target.

height int

Height, in pixels, of the render target.

mipMap bool

true if mipmapping is enabled; otherwise, false.

preferredFormat SurfaceFormat

The preferred surface format of the render target.

preferredDepthFormat DepthFormat

The preferred depth format of the render target.

preferredMultiSampleCount int

The preferred number of samples per pixel when multisampling.

usage RenderTargetUsage

The behavior to use when binding the render target to the graphics device.

Exceptions

ArgumentNullException

The graphicsDevice parameter is null.

ArgumentOutOfRangeException

The width and/or height parameters less than or equal to zero.

RenderTarget2D(GraphicsDevice, int, int, bool, SurfaceFormat, DepthFormat, int, RenderTargetUsage, SurfaceType)

Allows child class to specify the surface type, eg: a swap chain.

protected RenderTarget2D(GraphicsDevice graphicsDevice, int width, int height, bool mipMap, SurfaceFormat format, DepthFormat depthFormat, int preferredMultiSampleCount, RenderTargetUsage usage, Texture2D.SurfaceType surfaceType)

Parameters

graphicsDevice GraphicsDevice

width int

height int

mipMap bool

format SurfaceFormat

depthFormat DepthFormat

preferredMultiSampleCount int

usage RenderTargetUsage

surfaceType Texture2D.SurfaceType

RenderTarget2D(GraphicsDevice, int, int, bool, SurfaceFormat, DepthFormat, int, RenderTargetUsage, bool)

Creates a new RenderTarget2D instance with the specified parameters.

public RenderTarget2D(GraphicsDevice graphicsDevice, int width, int height, bool mipMap, SurfaceFormat preferredFormat, DepthFormat preferredDepthFormat, int preferredMultiSampleCount, RenderTargetUsage usage, bool shared)

Parameters

graphicsDevice GraphicsDevice

The graphics device to associate with this render target resource.

width int

Width, in pixels, of the render target.

height int

Height, in pixels, of the render target.

mipMap bool

true if mipmapping is enabled; otherwise, false.

preferredFormat SurfaceFormat

The preferred surface format of the render target.

preferredDepthFormat DepthFormat

The preferred depth format of the render target.

preferredMultiSampleCount int

The preferred number of samples per pixel when multisampling.

usage RenderTargetUsage

The behavior to use when binding the render target to the graphics device.

shared bool

Whether this render target resource should be a shared resource accessible on another device. This property is only valid for DirectX targets.

Exceptions

ArgumentNullException

The graphicsDevice parameter is null.

ArgumentOutOfRangeException

The width and/or height parameters less than or equal to zero.

RenderTarget2D(GraphicsDevice, int, int, bool, SurfaceFormat, DepthFormat, int, RenderTargetUsage, bool, int)

Creates a new RenderTarget2D instance with the specified parameters.

public RenderTarget2D(GraphicsDevice graphicsDevice, int width, int height, bool mipMap, SurfaceFormat preferredFormat, DepthFormat preferredDepthFormat, int preferredMultiSampleCount, RenderTargetUsage usage, bool shared, int arraySize)

Parameters

graphicsDevice GraphicsDevice

The graphics device to associate with this render target resource.

width int

Width, in pixels, of the render target.

height int

Height, in pixels, of the render target.

mipMap bool

true if mipmapping is enabled; otherwise, false.

preferredFormat SurfaceFormat

The preferred surface format of the render target.

preferredDepthFormat DepthFormat

The preferred depth format of the render target.

preferredMultiSampleCount int

The preferred number of samples per pixel when multisampling.

usage RenderTargetUsage

The behavior to use when binding the render target to the graphics device.

shared bool

Whether this render target resource should be a shared resource accessible on another device. This property is only valid for DirectX targets.

arraySize int

The size of the texture array.

Exceptions

ArgumentNullException

The graphicsDevice parameter is null.

ArgumentOutOfRangeException

The width and/or height parameters less than or equal to zero.

ArgumentException

arraySize is greater than 0 and the graphics device does not support texture arrays.

Properties

DepthStencilFormat

Gets the depth format used by this RenderTarget2D

public DepthFormat DepthStencilFormat { get; }

Property Value

DepthFormat

IsContentLost

Gets a value that indicates whether the contents of this RenderTarget2D has been lost due to a lost device event.

[Obsolete("This is provided for XNA compatibility only and will always return false")]
public bool IsContentLost { get; }

Property Value

bool

Remarks

This property will always return false. It is included for XNA compatibility.

MultiSampleCount

Gets the number of samples taken per pixel

public int MultiSampleCount { get; }

Property Value

int

RenderTargetUsage

Gets or Sets the usage type used by this RenderTarget2D

public RenderTargetUsage RenderTargetUsage { get; }

Property Value

RenderTargetUsage

Methods

Dispose(bool)

protected override void Dispose(bool disposing)

Parameters

disposing bool

FromNativeHandle(GraphicsDevice, nint, int, int, SurfaceFormat, DepthFormat, int, bool)

Creates a RenderTarget2D that wraps an externally-owned native graphics handle.

public static RenderTarget2D FromNativeHandle(GraphicsDevice graphicsDevice, nint handle, int width, int height, SurfaceFormat format = SurfaceFormat.Color, DepthFormat preferredDepthFormat = DepthFormat.None, int preferredMultiSampleCount = 0, bool externalPresentation = false)

Parameters

graphicsDevice GraphicsDevice

The graphics device.

handle nint

The native image or texture handle.

This should be a handle to an image or texture such as VkImage, GLuint, ID3D12Resource* or ID3D11Texture2D* depending on the platform.

width int

Image width in pixels.

height int

Image height in pixels.

format SurfaceFormat

The surface format of the native image or texture.

preferredDepthFormat DepthFormat

The preferred depth format of the render target.

None by default.

preferredMultiSampleCount int

The preferred number of samples per pixel when multisampling.

0 by default.

externalPresentation bool

true if the wrapped native resource is an external swapchain, such as an OpenXR swapchain. false if the render target will be used for sampling in shaders, such as for use as input with SpriteBatch.

false by default.

Returns

RenderTarget2D

A non-owning RenderTarget2D backed by the native resource handle.

Remarks

The returned render target does not own the underlying native image or texture memory. The external caller/runtime is responsible for its lifetime.

GraphicsDeviceResetting()

Called before the device is reset. Allows graphics resources to invalidate their state so they can be recreated after the device reset. Warning: This may be called after a call to Dispose() up until the resource is garbage collected.

protected override void GraphicsDeviceResetting()

QuerySelectedFormat(GraphicsDevice, SurfaceFormat)

protected static SurfaceFormat QuerySelectedFormat(GraphicsDevice graphicsDevice, SurfaceFormat preferredFormat)

Parameters

graphicsDevice GraphicsDevice

preferredFormat SurfaceFormat

Returns

SurfaceFormat

Events

ContentLost

Occurs when a graphics device lost event is triggered.

[Obsolete("This is provided for XNA compatibility is never called by MonoGame")]
public event EventHandler<EventArgs> ContentLost

Event Type

EventHandler<EventArgs>

Remarks

This event is never called. It is included for XNA compatibility.