| Microsoft DirectX 8.1 (C++) |
Applications use the stencil buffer to determine whether a pixel is written to the rendering target surface.
For details, see Stencil Buffer Techniques.
Applications written in C++ enable or disable stenciling by calling the IDirect3DDevice8::SetRenderState method. Pass D3DRS_STENCILENABLE as the value of the first parameter. Set the value of the second parameter to TRUE or FALSE to enable or disable stenciling, respectively.
Set the comparison function that Microsoft® Direct3D® uses to perform the stencil test by calling SetRenderState. Set the value of the first parameter to D3DRS_STENCILFUNC. Pass a member of the D3DCMPFUNC enumerated type as the value of the second parameter.
The stencil reference value is the value in the stencil buffer that the stencil function uses for its test. By default, the stencil reference value is zero. Your application can set the value by calling SetRenderState. Pass D3DRS_STENCILREF as the value of the first parameter. Set the value of the second parameter to the new reference value.
Before the Direct3D module performs the stencil test for any pixel, it performs a bitwise AND operation of the stencil reference value and a stencil mask value. The result is compared against the contents of the stencil buffer using the stencil comparison function. Your application can set the stencil mask by calling SetRenderState. Pass D3DRS_STENCILMASK as the value of the first parameter. Set the value of the second parameter to the new stencil mask.
To set the action that Direct3D takes when the stencil test fails, call SetRenderState and pass D3DRS_STENCILFAIL as the first parameter. The second parameter must be a member of the D3DSTENCILOP enumerated type.
Your application can also control how Direct3D responds when the stencil test passes but the z-buffer test fails. Call SetRenderState and pass D3DRS_STENCILZFAIL as the first parameter and use a member of the D3DSTENCILOP enumerated type for the second parameter.
In addition, your application can control what Direct3D does when both the stencil test and the z-buffer test pass. Call SetRenderState and pass D3DRS_STENCILPASS as the first parameter. Again, the second parameter must be a member of the D3DSTENCILOP enumerated type.
A write mask can be applied to the values written into the stencil buffer. To set a stencil buffer write mask, call SetRenderState and pass D3DRS_STENCILWRITEMASK as the first parameter. Pass the value of the write mask as the second parameter.