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 2ⁿ–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:

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.
  Windows CE: Unsupported.
  Version: Requires DirectX 7.0.
  Header: Declared in d3d.h.