stenci(3G)

NAME
     stenci - 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.

DESCRIPTION
     stenci 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.

     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.
     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.