IDirect3DDevice9::SetRenderTarget Method

Sets a new color buffer for the device.

Syntax

HRESULT SetRenderTarget(      

    DWORD RenderTargetIndex,
    IDirect3DSurface9 *pRenderTarget
);

Parameters

RenderTargetIndex

[in] Index of the render target. See Remarks.

pRenderTarget

[in] Pointer to a new color buffer. If NULL, the color buffer for the corresponding RenderTargetIndex is disabled. If this parameter is other than NULL, the reference count on the new render target is incremented. Devices always must be associated with a color buffer.

The new render target surface must have at least D3DUSAGE_RENDERTARGET specified.

Return Value

If the method succeeds, the return value is D3D_OK.

This method will return D3DERR_INVALIDCALL if either:

• pRenderTarget = NULL and RenderTargetIndex = 0
• pRenderTarget is != NULL and the render target is invalid.

Remarks

The device can now support multiple render targets. The number of render targets supported by a device is contained in the NumSimultaneousRTs member of D3DCAPS9. See Multiple Render Target.

Some hardware tests the compatibility of the depth stencil buffer with the color buffer. If this is done, it is only done in a debug build.

Restrictions for using this method include the following:

• 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. See IDirect3D9::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 IDirect3DDevice9?I>Draw methods are called.

Cube textures differ from other surfaces in that they are collections of surfaces. To call IDirect3DDevice9::SetRenderTarget with a cube texture, you must select an individual face using IDirect3DCubeTexture9::GetCubeMapSurface and pass the resulting surface to IDirect3DDevice9::SetRenderTarget.