Direct3DDevice8.Clear

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, _ 
    ClearD3DRect As Any,
    Flags As CONST_D3DCLEARFLAGS, _ 
    Color As Long, _ 
    Z As Single, _ 
    Stencil As Long)

Parts

object

Object expression that resolves to a Direct3DDevice8 object.

Count

Number of rectangles in the array at ClearD3DRect. If you set ClearD3DRect to ByVal 0, this parameter must be set to 0.

ClearD3DRect

First element of an array of D3DRECT types 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 ByVal 0 to indicate that the entire viewport rectangle is to be cleared.

Flags

A combination of the flags defined by the CONST_D3DCLEARFLAGS enumeration that indicate which surfaces should be cleared. Note that at least one flag must be used.

Color

A 32-bit ARGB color value to which the render target surface is cleared.

Z

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

Integer value to store in each stencil-buffer entry. This parameter can be in the range from 0 through 2ⁿ–1, where n is the bit depth of the stencil buffer.

Error Codes

If the method fails, an error is raised and Err.Number can be set to D3DERR_INVALIDCALL.

For information on trapping errors, see the Microsoft® Visual Basic® Error Handling topic.

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.

The following code fragment shows how to call the default case for Clear.

Dim Device As Direct3DDevice8

' The following assumes that Flags, Color, Z, and Stencil
' have been set to valid values.
Device.Clear 0, ByVal 0, Flags, Color, Z, Stencil

The following code fragment show how to call Clear when specifying an array of rectangles to clear.

Dim clearD3dRects(10)
device.Clear 10, clearD3dRects(0), Flags, Color, Z, Stencil

Note that you pass in only the first element of the array of rectangles to clear.