IDirect3DDevice7::SetRenderTarget

The IDirect3DDevice7::SetRenderTarget method permits the application to easily route rendering output to a new DirectDraw surface as a render target.

HRESULT SetRenderTarget(
  LPDIRECTDRAWSURFACE7 lpNewRenderTarget,  
  DWORD dwFlags                            
);

Parameters

lpNewRenderTarget

Address of a IDirectDrawSurface7 interface for the surface object that is the new rendering target. This surface must be created with the DDSCAPS_3DDEVICE capability.

dwFlags

Not currently used; set to 0.

Return Values

If the method succeeds, the return value is D3D_OK.

If the method fails, the return value is an error. The error can be one of the following values:

Remarks

Do not use this method to set a new render target surface with a depth buffer if the current render target does not have a depth buffer. Likewise, you cannot use this method to switch from a nondepth-buffered render target to a depth-buffered render target. Attempts to do this fail in debug builds and can exhibit unreliable behavior in retail builds. Since both the new and the old render targets use depth buffers, the depth buffer attached to the new render target replaces the previous depth buffer for the context.

Unlike this method's implementation in previous interfaces, IDirect3DDevice7::SetRenderTarget does not invalidate the current material or viewport for the device.

Capabilities do not change with changes in the properties of the render target surface. Both the Direct3D hardware abstraction layer (HAL) and the software rasterizers have only one opportunity to expose capabilities to the application. The system cannot expose different sets of capabilities, depending on the format of the destination surface.

If more than one depth buffer is attached to the render target, this function fails.

In the IDirect3DDevice3 interface, this method accepted a pointer to the legacy IDirectDrawSurface4 interface.

Requirements

  Windows NT/2000: Requires Windows 2000.
  Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
  Version: Requires DirectX 7.0.
  Header: Declared in d3d.h.

See Also

IDirect3DDevice7::GetRenderTarget