stenci(3G)stenci(3G)NAMEstenci - alter the operating parameters of the stencil
FORTRAN SPECIFICATION
subroutine stenci(enable, ref, func, mask, fail, pass, zpass)
integer*4 enable, ref, func, mask, 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 SFNEVE, SFLESS, SFEQUA, SFLEQU,
SFGREA, SFNOTE, SFGEQU, and SFALWA.
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, STREPL, STINCR, STDECR, and STINVE.
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, STREPL, STINCR, STDECR, and STINVE.
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, STREPL, STINCR, STDECR, and
STINVE.
DESCRIPTIONstenci operates as a superior z-buffer test with a different algorithm.
When stenci 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.
stenci operation can be enabled only if stencil bitplanes are present
(see stensi). Stencil bitplanes are present only in the normal
framebuffer, so stenci should be called only while draw mode is NORMAL.
When the z-buffer is enabled, three test cases are distinguished:
fail Stencil test fails.
Page 1
stenci(3G)stenci(3G)
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.
STREPL Replace with the reference value.
STINCR Increment by one (clamp to max).
STDECR Decrement by one (clamp to zero).
STINVE Invert all bits.
Arguments fail, pass, and zpass are each specified as one of STKEEP,
STZERO, STREPL, STINCR, STDECR, and STINVE.
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:
SFNEVE Never pass.
SFLESS Pass if ref is less than stencil.
SFLEQU Pass if ref is less than or equal to stencil.
SFEQUA Pass if ref is equal to stencil.
SFGREA Pass if ref is greater than stencil.
SFGEQU Pass if ref is greater than or equal to stencil.
SFNOTE Pass if ref is not equal to stencil.
SFALWA Always pass.
The stencil bitplanes are treated as an unsigned integer of planes bits,
where planes is the value passed to stensi to allocate the stencil
buffer.
mask is a field that specifies which stencil bitplanes are to be
considered by the test. It does not affect which bitplanes are updated.
Page 2
stenci(3G)stenci(3G)
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
drawmo, polymo, sclear, stensi, swrite, zbuffe
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 stenci. Use getgde to
determine whether stenci is supported.
stenci is supported only in the normal framebuffer, and is therefore
effective only while draw mode is NORMALW.
BUGS
IRIS-4D VGX models do not support stencil operation when afunct is
enabled.
Page 3
