Share via

IDirect3DDevice8::Clear

  • Article

This 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 Clear(
  DWORD Count,
  CONST D3DRECT* pRects,
  DWORD Flags,
  D3DCOLOR Color,
  float Z,
  DWORD Stencil
);

Parameters

  • Count
    [in] Number of rectangles in the array at pRects. If you set pRects to NULL, this parameter must be set to 0.

  • pRects
    [in] Pointer to an array of D3DRECT structures that describe the rectangles to clear. 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.

  • Flags
    [in] Flags that indicate which surfaces should be cleared. This parameter can be any combination of the following flags, but at least one flag must be used.

    Flag Description
    D3DCLEAR_STENCIL Clear the stencil buffer to the value in the Stencil parameter.
    D3DCLEAR_TARGET Clear the render target to the color in the Color parameter.
    D3DCLEAR_ZBUFFER Clear the depth buffer to the value in the Z parameter.

  • Color
    [in] A 32-bit ARGB color value to which the render target surface is cleared.

  • Z
    [in] 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.

  • Stencil
    [in] Integer value to store in each stencil-buffer entry. This parameter can be in the range from 0 through 2n1, 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 D3DERR_INVALIDCALL.

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. Similarly, if you specify the D3DCLEAR_STENCIL flag when the depth-buffer format does not contain stencil buffer information, this method fails.

Requirements

OS Versions: Windows CE .NET 4.0 and later.
Header: D3d8.h.
Link Library: D3d8.lib.

See Also

D3DRECT | IDirect3DDevice8

 Last updated on Thursday, April 08, 2004

© 1992-2003 Microsoft Corporation. All rights reserved.