IDirect3DViewport3::Clear2

The IDirect3DViewport3::Clear2 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.

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

Parameters

dwCount

Number of rectangles in the array at lpRects.

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.

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

32-bit RGBA color value to which the render target surface will be cleared.

dvZ

New z value that this method stores in the depth-buffer. This parameter can range from 0.0 to 1.0, inclusive. The 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 range from 0 to 2ⁿ-1 inclusive, 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 may be one of the following values:

Remarks

This method fails if you specify the D3DCLEAR_ZBUFFER or D3DCLEAR_STENCIL flags when the render target does not have an attached depth-buffer. This behavior differs from the IDirect3DViewport3::Clear method, which will succeed if under these circumstances.

If you specify the D3DCLEAR_STENCIL flag when the depth-buffer format doesn't contain stencil buffer information, this method fails.

This method ignores the current background material for the viewport; to clear a viewport using the background material, use the IDirect3DViewport3::Clear method.

QuickInfo

  Windows NT/2000: Requires Windows 2000.
  Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
  Header: Declared in d3d.h.
  Import Library: Use ddraw.lib.

See Also

IDirect3DViewport3::Clear