Clearing a Stencil Buffer

[Previous] [Next]

The IDirect3DDevice7 interface includes the Clear method, which you can use to simultaneously clear the render target's color buffer, depth buffer, and stencil buffer. Here's the declaration for the IDirect3DDevice7::Clear method:

 HRESULT IDirect3DDevice7::Clear(     DWORD dwCount,     LPD3DRECT lpRects,     DWORD dwFlags,     D3DVALUE dvZ,     DWORD dwStencil ); 

Parameter	Description
dwCount	The number of rectangles in the array at lpRects.
lpRects	An array of D3DRECT structures defining the rectangles to be cleared. You can set a rectangle to the dimensions of the render-target surface to clear the entire surface. Each of these rectangles uses screen coordinates that correspond to points on the render-target surface. The coordinates are clipped to the bounds of the viewport rectangle.
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 render-target surface 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 will be cleared.
dvZ	The new z value that this method stores in the depth buffer. This parameter can range from 0.0 to 1.0, inclusive. The value of 0.0 represents the nearest distance to the viewer, and 1.0 represents the farthest distance.
dwStencil	The integer value to store in each stencil-buffer entry. This parameter can range from 0 to 2n-1 inclusive, in which n is the bit depth of the stencil buffer.

The IDirect3DDevice7::Clear method still accepts the older D3DCLEAR_TARGET flag, which clears the render target using an RGBA color you provide in the dwColor parameter. This method also still accepts the D3DCLEAR_ZBUFFER flag, which clears the depth buffer to a depth you specify in dvZ (in which 0.0 is the closest distance and 1.0 is the farthest). DirectX 6 introduced the D3DCLEAR_STENCIL flag, which you can use to reset the stencil bits to the value you specify in the dwStencil parameter. This value can be an integer ranging from 0 to 2ⁿ-1, in which n is the bit depth of the stencil buffer.