Stencil Buffer State

Applications use the stencil buffer to determine whether or not a pixel is written to the rendering target surface. For details, see Stencil Buffers.

[C++]

Applications written in C++ enable or disable stenciling by calling the IDirect3DDevice7::SetRenderState method. Pass D3DRENDERSTATE_STENCILENABLE as the value of the first parameter. Set the value of the second parameter to TRUE or FALSE to enable or disable it respectively.

Set the comparison function that Direct3D uses to perform the stencil test by invoking the IDirect3DDevice7::SetRenderState method. Set the value of the first parameter to D3DRENDERSTATE_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 it by calling the IDirect3DDevice7::SetRenderState method. Pass D3DRENDERSTATE_STENCILREF as the value of the first parameter. Set the value of the second parameter to the new reference value.

Before Direct3D module performs the stencil test for any pixel, it does a bitwise AND of the stencil reference value and a stencil mask value. The result is then compared against the contents of the stencil buffer using the stencil comparison function. Your application can set the stencil mask. Use the IDirect3DDevice7::SetRenderState method, and pass D3DRENDERSTATE_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, invoke the IDirect3DDevice7::SetRenderState method and pass D3DRENDERSTATE_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 the IDirect3DDevice7::SetRenderState method and pass D3DRENDERSTATE_STENCILZFAIL as the first parameter and use a member of the D3DSTENCILOP enumerated type for the second parameter.

In addition, your program can control what Direct3D does when both the stencil test and the z-buffer test pass. Use the IDirect3DDevice7::SetRenderState method and pass D3DRENDERSTATE_STENCILPASS as the first parameter. Again, the second parameter must be a member of the D3DSTENCILOP enumerated type.

[Visual Basic]

You enable or disable stenciling in Visual Basic by calling the Direct3DDevice7.SetRenderState method. Pass D3DRENDERSTATE_STENCILENABLE as the value of the first parameter. Set the value of the second parameter to True or False to enable or disable it respectively.

Set the comparison function that Direct3D uses to perform the stencil test by invoking the Direct3DDevice7.SetRenderState method. Set the value of the first parameter to D3DRENDERSTATE_STENCILFUNC. Pass a member of the CONST_D3DCMPFUNC enumeration 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 it by calling the Direct3DDevice7.SetRenderState method. Pass D3DRENDERSTATE_STENCILREF as the value of the first parameter. Set the value of the second parameter to the new reference value.

Before 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 then compared against the contents of the stencil buffer using the stencil comparison function. Your application can set the stencil mask by using the D3DRENDERSTATE_STENCILMASK render state. Set the render state value to the new stencil mask.

To set the action that Direct3D takes when the stencil test fails, invoke the Direct3DDevice7.SetRenderState method and pass D3DRENDERSTATE_STENCILFAIL as the first parameter. The second parameter must be a member of the CONST_D3DSTENCILOP enumeration.

Your application can also control how Direct3D responds when the stencil test passes but the z-buffer test fails. Call the Direct3DDevice7.SetRenderState method and pass D3DRENDERSTATE_STENCILZFAIL as the first parameter and use a member of the D3DSTENCILOP enumeration for the second parameter.

In addition, your program can control what Direct3D does when both the stencil test and the z-buffer test pass. Use the Direct3DDevice7.SetRenderState method and pass D3DRENDERSTATE_STENCILPASS as the first parameter. Again, the second parameter must be a member of the D3DSTENCILOP enumeration.