- set function and reference value for stencil testing



C SPECIFICATION


PARAMETERS

       _param1  Specifies  the  test  function.  Eight tokens are
                valid: GL_NEVER, GL_LESS, GL_LEQUAL,  GL_GREATER,
                GL_GEQUAL,  GL_EQUAL, GL_NOTEQUAL, and GL_ALWAYS.
                The initial value is GL_ALWAYS.

       _param2  Specifies the reference  value  for  the  stencil
                test.   _param2 is clamped to the range [0,2n-1],
                where n is the number of bitplanes in the stencil
                buffer. The initial value is 0.

       _param3  Specifies a mask that is ANDed with both the ref-
                erence value and the stored  stencil  value  when
                the test is done. The initial value is all 1's.


DESCRIPTION

       Stenciling,  like  depth-buffering,  enables  and disables
       drawing on a per-pixel basis.  You draw into  the  stencil
       planes  using  GL drawing primitives, then render geometry
       and images, using the stencil planes to mask out  portions
       of  the screen.  Stenciling is typically used in multipass
       rendering algorithms to achieve special effects,  such  as
       decals, outlining, and constructive solid geometry render-
       ing.

       The stencil test conditionally eliminates a pixel based on
       the  outcome  of  a comparison between the reference value
       and the value in the stencil buffer.  To enable  and  dis-
       able  the  test, call glEnable and glDisable with argument
       GL_STENCIL_TEST.  To specify actions based on the  outcome
       of the stencil test, call glStencilOp.

       _param1 is a symbolic constant that determines the stencil
       comparison function.  It  accepts  one  of  eight  values,
       shown in the following list.  _param2 is an integer refer-
       ence value that is used in the stencil comparison.  It  is
       clamped  to  the  range [0,2n-1], where n is the number of
       bitplanes in the stencil buffer.  _param3 is bitwise ANDed
       with  both  the  reference  value  and  the stored stencil
       value, with the ANDed values participating in the compari-
       son.

       If  stencil represents the value stored in the correspond-
       ing stencil buffer location, the following list shows  the
       effect  of  each comparison function that can be specified
       by _param1.  Only if the comparison succeeds is the  pixel
       passed through to the next stage in the rasterization pro-
       cess (see glStencilOp).  All tests treat stencil values as
                         stencil & _param3 ).

       GL_GEQUAL         Passes  if  (  _param2  & _param3 ) >= (
                         stencil & _param3 ).

       GL_EQUAL          Passes if ( _param2  &  _param3  )  =  (
                         stencil & _param3 ).

       GL_NOTEQUAL       Passes  if  (  _param2 & _param3 ) !=  (
                         stencil & _param3 ).

       GL_ALWAYS         Always passes.


NOTES

       Initially, the stencil test is disabled.  If there  is  no
       stencil  buffer,  no stencil modification can occur and it
       is as if the stencil test always passes.


ERRORS

       GL_INVALID_ENUM is generated if _param1 is not one of  the
       eight accepted values.

       GL_INVALID_OPERATION is generated if glStencilFunc is exe-
       cuted between the execution of glBegin and the correspond-
       ing execution of glEnd.


ASSOCIATED GETS

       glGet with argument GL_STENCIL_FUNC
       glGet with argument GL_STENCIL_VALUE_MASK
       glGet with argument GL_STENCIL_REF
       glGet with argument GL_STENCIL_BITS
       glIsEnabled with argument GL_STENCIL_TEST


SEE ALSO

       glAlphaFunc,     glBlendFunc,    glDepthFunc,    glEnable,
       glIsEnabled, glLogicOp, glStencilOp



                                                                1