Stencil Buffer State
A version of this page is also available for
4/8/2010
Applications use the stencil buffer to determine whether a pixel is written to the rendering target surface. For more information, see Stencil Buffers.
Applications enable or disable stenciling by calling the IDirect3DMobileDevice::SetRenderState method. Pass D3MDRS_STENCILENABLE (see D3DMRENDERSTATETYPE) 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® Mobile uses to perform the stencil test by calling IDirect3DMobileDevice::SetRenderState. Set the value of the first parameter to D3DMRS_STENCILFUNC. Pass a member of the D3DMCMPFUNC 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 IDirect3DMobileDevice::SetRenderState. Pass D3DMRS_STENCILREF as the value of the first parameter. Set the value of the second parameter to the new reference value.
Before Direct3D Mobile 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 IDirect3DMobileDevice::SetRenderState. Pass D3DMRS_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 Mobile takes when the stencil test fails, call IDirect3DMobileDevice::SetRenderState and pass D3DMRS_STENCILFAIL as the first parameter. The second parameter must be a member of the D3DMSTENCILOP enumerated type.
Your application can also control how Direct3D Mobile responds when the stencil test passes but the z-buffer test fails. Call IDirect3DMobileDevice::SetRenderState and pass D3DMRS_STENCILZFAIL as the first parameter and use a member of the D3DMSTENCILOP enumerated type for the second parameter.
In addition, your application can control what Direct3D Mobile does when both the stencil test and the z-buffer test pass. Call IDirect3DMobileDevice::SetRenderState and pass D3DMRS_STENCILPASS as the first parameter. Again, the second parameter must be a member of the D3DMSTENCILOP enumerated type.