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 2n–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.
Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Version: Requires DirectX 7.0.
Header: Declared in d3d.h.