stencil(3G)stencil(3G)NAMEstencil - alter the operating parameters of the stencilC 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 SF_NEVER, SF_LESS, SF_EQUAL,
SF_LEQUAL, SF_GREATER, SF_NOTEQUAL, SF_GEQUAL, and SF_ALWAYS.
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 ST_KEEP, ST_ZERO, ST_REPLACE, ST_INCR, ST_DECR, and
ST_INVERT.
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
ST_KEEP, ST_ZERO, ST_REPLACE, ST_INCR, ST_DECR, and ST_INVERT.
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 ST_KEEP, ST_ZERO, ST_REPLACE, ST_INCR, ST_DECR,
and ST_INVERT.
DESCRIPTIONstencil 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:
ST_KEEP Keep the current value (no change).
ST_ZERO Replace with zero.
ST_REPLACE Replace with the reference value.
ST_INCR Increment by one (clamp to max).
ST_DECR Decrement by one (clamp to zero).
ST_INVERT Invert all bits.
Arguments fail, pass, and zpass are each specified as one of ST_KEEP,
ST_ZERO, ST_REPLACE, ST_INCR, ST_DECR, and ST_INVERT.
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:
SF_NEVER Never pass.
SF_LESS Pass if ref is less than stencil.
SF_LEQUAL Pass if ref is less than or equal to stencil.
SF_EQUAL Pass if ref is equal to stencil.
SF_GREATER Pass if ref is greater than stencil.
SF_GEQUAL Pass if ref is greater than or equal to stencil.
SF_NOTEQUAL Pass if ref is not equal to stencil.
SF_ALWAYS 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
