Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

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.

Syntax

HRESULT Clear(
  DWORD 
Count,
  CONST RECT* 
pRects,
  DWORD 
Flags,
  D3DMCOLOR 
Color,
  float 
Z,
  DWORD 
Stencil
);

Parameters

Count

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

pRects

[in] Pointer to an array of RECTstructures 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 D3DMCLEAR Values.

Flag Description

D3DMCLEAR_STENCIL

Clear the stencil buffer to the value in the Stencilparameter.

D3DMCLEAR_TARGET

Clear the render target to the color in the Colorparameter.

D3DMCLEAR_ZBUFFER

Clear the depth buffer to the value in the Zparameter.

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 nis the bit depth of the stencil buffer.

Return Value

If the method succeeds, the return value is D3DM_OK (see D3DM Values).

If the method fails, the return value can be D3DERR_INVALIDCALL (see D3DMERR Values).

Remarks

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

Requirements

Header d3dm.h
Library D3dm.lib, D3dmguid.lib
Windows Embedded CE Windows CE 5.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also

Reference

IDirect3DMobileDevice
D3DMCLEAR Values

Other Resources

RECT