Stencil Planes

Stencil planes enable and disable drawing on a per-pixel basis. They are typically used in multipass algorithms to achieve special effects, such as decals, outlining, shadows, and constructive solid geometry rendering.

Some hardware designed to accelerate Direct3D implements stencil planes. The special effects enabled by stencil planes are useful for entertainment applications.

Stencil planes are assumed to be embedded in the z-buffer data.

In DirectX 5.0, applications found the available z-buffer bit depths using the DDBD_Xx flags set in the dwDeviceZBufferBitDepth member of the D3DDEVICEDESC_V1 structure. To support z-buffers with stencil and z-buffer bit depths that cannot be represented using the existing DDBD_Xx flags, DirectX 6.0 and later versions have a new API entry point, IDirect3D7::EnumZBufferFormats (described in the Direct3D SDK documentation), which returns an array of DDPIXELFORMAT structures describing the possible z-buffer/stencil pixel formats. The DDPIXELFORMAT structure includes the following new z-buffer-related members:

dwStencilBitDepth
Specifies the number of stencil bits (as an integer, not as a DDBD_Xx flag value).

dwZBitMask
Specifies which bits the z-value occupies. If nonzero, this mask means that the z-buffer is a standardized unsigned integer z-buffer format.

dwStencilBitMask
Specifies which bits the stencil value occupies.

A new flag, DDPF_STENCILBUFFER, indicates the presence of stencil bits within the z-buffer. The dwZBufferBitDepth member, which existed previously, gives the total number of z-buffer bits including the stencil bits.

DirectX 6.0 and later versions drivers should still set the appropriate DDBD_Xx flags in dwDeviceZBufferBitDepth for the z-only z-buffer formats they support. If stencil planes are not supported and the DDBD_Xx flags can represent all available z-buffer formats, then setting these flags is sufficient, because they are translated into DDPIXELFORMAT by IDirect3D7::EnumZBufferFormats. Otherwise, the Direct3D driver must respond to a DdGetDriverInfo query that uses the GUID_ZPixelFormats GUID by returning a buffer in which the first DWORD indicates the number of valid z-buffer DDPIXELFORMAT structures, followed by the DDPIXELFORMAT structures themselves.

New render states associated with stencil planes are shown in the following table, which lists the render state, the type associated with the render state's value, and a description. For more details on these render states, see the DirectX SDK documentation.

Render State	Type	Description
D3DRENDERSTATE_STENCILFUNC	D3DCMPFUNC	Comparison function. The test passes if the following expression is true: (ref & mask) OPERATION (stencil & mask) where ref is the reference value, stencil is the value in the stencil buffer, and mask is the value of D3DRENDERSTATE_STENCILMASK.
D3DRENDERSTATE_STENCILREF	DWORD	Reference value used in the stencil test.
D3DRENDERSTATE_STENCILMASK	DWORD	Mask value used in the stencil test.
D3DRENDERSTATE_STENCILWRITEMASK	DWORD	Write mask applied to any values written to the stencil buffer.
D3DRENDERSTATE_STENCILFAIL D3DRENDERSTATE_STENCILZFAIL D3DRENDERSTATE_STENCILPASS	D3DSTENCILOP	These new render states are defined, respectively, to inform the hardware about what to do when the stencil test fails, when the stencil test passes but the z-test fails, and when both the stencil and z-tests pass. The values of these new render states can be set to enumerators of the D3DSTENCILOP enumerated type, which specify the desired stencil operation to be performed. For more information about D3DSTENCILOP, see the DirectX SDK documentation.