IDirect3DDevice9::Clear method (d3d9helper.h)

Clears one or more surfaces such as a render target, multiple render targets, a stencil buffer, and a depth buffer.

Syntax

HRESULT Clear(
  [in] DWORD         Count,
  [in] const D3DRECT *pRects,
  [in] DWORD         Flags,
  [in] D3DCOLOR      Color,
  [in] float         Z,
  [in] DWORD         Stencil
);

Parameters

[in] Count

Type: DWORD

Number of rectangles in the array at pRects. Must be set to 0 if pRects is NULL. May not be 0 if pRects is a valid pointer.

[in] pRects

Type: const D3DRECT*

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. Coordinates are clipped to the bounds of the viewport rectangle. To indicate that the entire viewport rectangle is to be cleared, set this parameter to NULL and Count to 0.

[in] Flags

Type: DWORD

Combination of one or more D3DCLEAR flags that specify the surface(s) that will be cleared.

[in] Color

Type: D3DCOLOR

Clear a render target to this ARGB color.

[in] Z

Type: float

Clear the depth buffer to this new z value which ranges from 0 to 1. See remarks.

[in] Stencil

Type: DWORD

Clear the stencil buffer to this new value which ranges from 0 to 2ⁿ-1 (n is the bit depth of the stencil buffer). See remarks.

Return value

Type: HRESULT

If the method succeeds, the return value is D3D_OK. If the method fails, the return value can be: D3DERR_INVALIDCALL.

Remarks

Use this method to clear a surface including: a render target, all render targets in an MRT, a stencil buffer, or a depth buffer. Flags determines how many surfaces are cleared. Use pRects to clear a subset of a surface defined by an array of rectangles.

IDirect3DDevice9::Clear will fail if you:

• Try to clear either the depth buffer or the stencil buffer of a render target that does not have an attached depth buffer.
• Try to clear the stencil buffer when the depth buffer does not contain stencil data.

Requirements

See also

IDirect3DDevice9