Platform SDK: DirectX

Direct3DDevice7.Clear

The Direct3DDevice7.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.

object.Clear( _ 
    count As Long, _ 
    recs() As D3DRECT, _ 
    flags As CONST_D3DCLEARFLAGS, _ 
    color As Long, _ 
    z As Single, _ 
    stencil As Long)

Parameters

object
Object expression that resolves to a Direct3DDevice7 object.
count
Number of rectangles in the array at recs.
recs()
Array of D3DRECT types 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.
flags
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 color parameter.
D3DCLEAR_STENCIL
Clear the stencil buffer to the value in the stencil parameter.
D3DCLEAR_ZBUFFER
Clear the depth-buffer to the value in the z parameter.
color
RGBA color value to which the render target surface will be cleared. You can construct an appropriate value by calling the DirectX7.CreateColorRGBA method.
z
New z-value that this method stores in the depth-buffer. This parameter can range from 0.0 to 1.0, inclusive (for z-based or w-based depth buffers). The value of 0.0 represents the nearest distance to the viewer, and 1.0 the farthest distance.
stencil
Integer value to store in each stencil buffer entry. This parameter can range from 0 to 2n-1 inclusive, where n is the bit depth of the stencil buffer.

Error Codes

If the method fails, an error is raised and Err.Number may be set to one of the following error codes:

D3DERR_STENCILBUFFER_NOTPRESENT
D3DERR_VIEWPORTHASNODEVICE
D3DERR_ZBUFFER_NOTPRESENT
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

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 doesn't contain stencil buffer information, this method fails.