stencil(3G) stencil(3G)
NAME
stencil - alter the operating parameters of the stencil
C SPECIFICATION
void stencil(enable, ref, func, mask, fail, pass, zpass)
long enable;
unsigned long ref;
long func;
unsigned long mask;
long fail, pass, zpass;
PARAMETERS
enable expects either TRUE or FALSE, enabling or disabling stencil
operation. When stencil operation is disabled (the default),
the values of the subsequent six parameters are ignored,
ref expects a reference value used by the stencil compare function.
func expects one of eight flags specifying the stencil comparison
function. These flags are SFNEVER, SFLESS, SFEQUAL,
SFLEQUAL, SFGREATER, SFNOTEQUAL, SFGEQUAL, and SFALWAYS.
mask expects a mask specifying which stencil bitplanes are
significant during the comparison operation.
fail expects one of six flags indicating which stencil operation
should be performed should the stencil test fail. The values
are STKEEP, STZERO, STREPLACE, STINCR, STDECR, and
STINVERT.
pass expects one of six flags indicating which stencil operation
should be performed should the stencil test pass, and the z-
buffer test (if z-buffering is enabled) fail. The values are
STKEEP, STZERO, STREPLACE, STINCR, STDECR, and STINVERT.
zpass expects one of six flags indicating which stencil operation
should be performed should the stencil and z-buffer tests pass.
Its value is not significant when the z-buffer is not enabled.
The values are STKEEP, STZERO, STREPLACE, STINCR, STDECR,
and STINVERT.
DESCRIPTION
stencil operates as a superior z-buffer test with a different algorithm.
When stencil is enabled, each pixel write first tests the stencil
bitplanes. Both the color and z-buffer bitplane writes, as well as the
write of the stencil bitplanes, are conditioned by the stencil test.
stencil operation can be enabled only if stencil bitplanes are present
(see stensize). Stencil bitplanes are present only in the normal
framebuffer, so stencil should be called only while draw mode is
NORMALDRAW.
Page 1
stencil(3G) stencil(3G)
When the z-buffer is enabled, three test cases are distinguished:
fail Stencil test fails.
pass Stencil test passes, but z-buffer test fails.
zpass Stencil test passes, and z-buffer test passes.
(When the z-buffer is not enabled, only cases fail and pass are
considered.) In all three cases the stencil bitplanes are updated with a
potentially new value. This value is a function of the case. The user
specifies, for each case, which of six possible values will be used:
STKEEP Keep the current value (no change).
STZERO Replace with zero.
STREPLACE Replace with the reference value.
STINCR Increment by one (clamp to max).
STDECR Decrement by one (clamp to zero).
STINVERT Invert all bits.
Arguments fail, pass, and zpass are each specified as one of STKEEP,
STZERO, STREPLACE, STINCR, STDECR, and STINVERT.
ref is the reference value used by the function that determines whether
the stencil test passes or fails. func specifies the comparison between
ref and the current stencil plane value. This comparison function is
specified with the flags:
SFNEVER Never pass.
SFLESS Pass if ref is less than stencil.
SFLEQUAL Pass if ref is less than or equal to stencil.
SFEQUAL Pass if ref is equal to stencil.
SFGREATER Pass if ref is greater than stencil.
SFGEQUAL Pass if ref is greater than or equal to stencil.
SFNOTEQUAL Pass if ref is not equal to stencil.
SFALWAYS Always pass.
The stencil bitplanes are treated as an unsigned integer of planes bits,
where planes is the value passed to stensize to allocate the stencil
buffer.
Page 2
stencil(3G) stencil(3G)
mask is a field that specifies which stencil bitplanes are to be
considered by the test. It does not affect which bitplanes are updated.
If the z-buffer is enabled, color and depth fields are drawn only in the
zpass case (both the stencil and depth tests pass). If the z-buffer is
not enabled, color is drawn only in the pass case. The zpass case is
ignored.
SEE ALSO
drawmode, polymode, sclear, stensize, swritemask, zbuffer
NOTES
IRIS-4D G, GT, and GTX models, as well as the Personal Iris, Iris Indy,
Iris Indigo Entry, and Indigo XL, do not support stencil. Use getgdesc
to determine whether stencil is supported.
stencil is supported only in the normal framebuffer, and is therefore
effective only while draw mode is NORMALDRAW.
BUGS
IRIS-4D VGX models do not support stencil operation when afunction is
enabled.
Page 3