Platform SDK: DirectX

IDirect3DDevice7::Clear

The IDirect3DDevice7::Clear method clears the viewport (or a set of rectangles in the viewport) to a specified RGBA color, clears the depth buffer, and erases the stencil buffer. This method supersedes the clearing methods exposed by the legacy IDirect3DViewport3 interface.

HRESULT Clear(
  DWORD     dwCount,   
  LPD3DRECT lpRects,   
  DWORD     dwFlags,   
  DWORD     dwColor,   
  D3DVALUE  dvZ,       
  DWORD     dwStencil  
);

Parameters

dwCount
Number of rectangles in the array at lpRects. If you set lpRects to NULL, this parameter must be set to 0.
lpRects
Array of D3DRECT structures that describe the rectangles to be cleared. Set a rectangle to the dimensions of the rendering target to clear the entire surface. Each rectangle uses screen coordinates that correspond to points on the render target surface. Coordinates are clipped to the bounds of the viewport rectangle. This parameter can be set to NULL to indicate that the entire viewport rectangle is to be cleared.
dwFlags
Flags indicating which surfaces should be cleared. This parameter can be any combination of the following flags, but at least one flag must be used:
D3DCLEAR_TARGET
Clear the rendering target to the color in the dwColor parameter.
D3DCLEAR_STENCIL
Clear the stencil buffer to the value in the dwStencil parameter.
D3DCLEAR_ZBUFFER
Clear the depth buffer to the value in the dvZ parameter.
dwColor
A 32-bit RGBA color value to which the render target surface is cleared.
dvZ
New z value that this method stores in the depth buffer. This parameter can be in the range from 0.0 through 1.0 (for z-based or w-based depth buffers). A value of 0.0 represents the nearest distance to the viewer, and 1.0 the farthest distance.
dwStencil
Integer value to store in each stencil-buffer entry. This parameter can be in the range from 0 through 2n–1, where n is the bit depth of the stencil buffer.

Return Values

If the method succeeds, the return value is D3D_OK.

If the method fails, the return value can be one of the following values:

D3DERR_STENCILBUFFER_NOTPRESENT
D3DERR_VIEWPORTHASNODEVICE
D3DERR_ZBUFFER_NOTPRESENT
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

Remarks

This method was introduced with the IDirect3DDevice7 interface.

This method fails if you specify the D3DCLEAR_ZBUFFER or D3DCLEAR_STENCIL flags when the render target does not have an attached depth buffer. Similarly, if you specify the D3DCLEAR_STENCIL flag when the depth-buffer format does not contain stencil buffer information, this method fails.

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.