IDirect3DDevice8::SetRenderTarget

Sets a new color buffer, depth buffer, or both for the device.

HRESULT SetRenderTarget(
  IDirect3DSurface8* pRenderTarget,
  IDirect3DSurface8* pNewZStencil
);

Parameters

pRenderTarget

[in] Pointer to a new color buffer. If NULL, the existing color buffer is retained. If this parameter is not NULL, the reference count on the new render target is incremented. Devices always have to be associated with a color buffer.

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

pNewZStencil

[in] Pointer to a new depth-stencil buffer. If there is an existing depth-stencil buffer, it is released. If this parameter is not NULL, the reference count on the new depth-stencil buffer surface is incremented. Applications can change the render target without changing the depth buffer by passing in the ppZStencilSurface parameter of IDirect3DDevice8::GetDepthStencilSurface.

The new depth-stencil surface must have at least D3DUSAGE_DEPTHSTENCIL and D3DPOOL_DEFAULT specified.

Return Values

If the method succeeds, the return value is D3D_OK.

D3DERR_INVALIDCALL is returned if pRenderTarget or pNewZStencil are not NULL and invalid, or if the new depth buffer is smaller than the new or retained color buffer.

Remarks

Once a color buffer and a depth-stencil surface have been associated with the same device by this method, they are said to be paired.

The device will call AddRef on each non-NULL surface passed to SetRenderTarget. After that the device calls Release on the previously set color buffer.

The previous depth-stencil surface's contents persist after a call to SetRenderTarget to disassociate the previous depth-stencil surface from the device. If the surface is re-associated with the device, then the contents of the surface will be unchanged, providing the color buffer to which the new depth-stencil surface is being paired is the same size and format as the color buffer to which the depth-stencil surface was most recently paired.

Calling this method resets the current viewport of the device to the size of the current render target. This is done regardless of whether the z-buffer is the only one that is being changed.

Requirements

  Header: Declared in D3d8.h.
  Import Library: Use D3d8.lib.

See Also

IDirect3DDevice8::CreateDepthStencilSurface, IDirect3DDevice8::GetDepthStencilSurface