GraphicsDevice.SetRenderTarget Method (Int32, RenderTarget2D)

Article
12/10/2010

Sets a new render target for this GraphicsDevice.

Namespace: Microsoft.Xna.Framework.Graphics
Assembly: Microsoft.Xna.Framework (in microsoft.xna.framework.dll)

Syntax

public void SetRenderTarget (
         int renderTargetIndex,
         RenderTarget2D renderTarget
)

Parameters

renderTargetIndex
Index of the render target. The number of render targets supported by a GraphicsDevice is contained in NumberSimultaneousRenderTargets.
renderTarget
A new render target for the device, or null to set the device render target to the back buffer of the device.

Exceptions

Exception type	Condition
ArgumentException	An invalid render target index was requested. On Xbox 360, there is only one render target available and renderTargetIndex must be zero.
ObjectDisposedException	SetRenderTarget was called after this renderTarget was disposed.

Remarks

Warning

On Xbox 360, all render targets (including the back buffer) share the same memory. Because of this, the previous content of any render target is lost when the render target is changed with SetRenderTarget or when Present is called, which has the same effect as swapping the render target.

To preserve the data in a render target, it is necessary to resolve it, either with ResolveRenderTarget or ResolveBackBuffer. Just remember to resolve the render target before switching the render target to avoid losing data that you want to preserve.

The following restrictions apply when using this method.

The multisample type must be the same for the render target and the depth stencil surface.
The formats must be compatible for the render target and the depth stencil surface. For more information, see CheckDepthStencilMatch.
The size of the depth stencil surface must be greater than or equal to the size of the render target.

These restrictions are validated only when using the debug runtime when any of the GraphicsDevice drawing methods are called.

Example

Before calling ResolveRenderTarget, set the render target on the device using SetRenderTarget, complete any drawing code, and then call to resolve the data from the draw call to the currently set render target.

// Create a new render target to receive the drawn data.
renderTarget = new RenderTarget2D(
    graphics.GraphicsDevice,
    // In this case, we are creating
    // a render target to match half of a split screen:
    leftViewPort.Width,
    leftViewPort.Height,
    // Number of levels in the render target:
    1,
    // Use the same surface format as the back buffer.
    graphics.GraphicsDevice.PresentationParameters.BackBufferFormat );

// Set the render target on the device.
graphics.GraphicsDevice.SetRenderTarget( 0, renderTarget );

// TODO: Add your code to draw to the render target here.
// For example, this could be a call to Mesh.Draw, 
// a SpriteBatch Begin-End sequence, or a call to
// DrawIndexedPrimitives, as you would have called them
// in the Draw method of your application.

// Resolve the data from the draw call to the currently set render target.
graphics.GraphicsDevice.ResolveRenderTarget( 0 );

// Call GetTexture to retrieve the render target data and save it to a texture.
capturedTexture = renderTarget.GetTexture();

// Set the device render target back to the back buffer.
graphics.GraphicsDevice.SetRenderTarget( 0, null );

Platforms

Xbox 360, Windows XP SP2, Windows Vista

Share via