- set stencil test actions



C SPECIFICATION


PARAMETERS

       _param1  Specifies  the  action  to  take when the stencil
                test fails.  Six symbolic constants are accepted:
                GL_KEEP,  GL_ZERO,  GL_REPLACE, GL_INCR, GL_DECR,
                and GL_INVERT. The initial value is GL_KEEP.

       _param2  Specifies the stencil  action  when  the  stencil
                test  passes,  but the depth test fails.  _param2
                accepts the same symbolic constants  as  _param1.
                The initial value is GL_KEEP.

       _param3  Specifies  the stencil action when both the sten-
                cil test and the depth test  pass,  or  when  the
                stencil  test passes and either there is no depth
                buffer or depth testing is not enabled.   _param3
                accepts  the  same symbolic constants as _param1.
                The initial value is GL_KEEP.


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 value in the sten-
       cil  buffer  and  a reference value. To enable and disable
       the  test,  call  glEnable  and  glDisable  with  argument
       GL_STENCIL_TEST; to control it, call glStencilFunc.

       glStencilOp  takes three arguments that indicate what hap-
       pens to the  stored  stencil  value  while  stenciling  is
       enabled.   If the stencil test fails, no change is made to
       the pixel's color or depth buffers, and _param1  specifies
       what  happens to the stencil buffer contents.  The follow-
       ing six actions are possible.

       GL_KEEP         Keeps the current value.

       GL_ZERO         Sets the stencil buffer value to 0.

       GL_REPLACE      Sets the stencil buffer value to  ref,  as
                       specified by glStencilFunc.


       The other two arguments  to  glStencilOp  specify  stencil
       buffer  actions  that  depend  on whether subsequent depth
       buffer tests succeed (_param3) or fail (_param2) (see
       glDepthFunc).  The actions are specified  using  the  same
       six  symbolic  constants as _param1.  Note that _param2 is
       ignored when there is no depth buffer, or when  the  depth
       buffer  is  not  enabled.   In  these  cases,  _param1 and
       _param3 specify stencil action when the stencil test fails
       and passes, respectively.


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 tests always pass, regardless of any
       call to glStencilOp.


ERRORS

       GL_INVALID_ENUM  is  generated  if  _param1,  _param2,  or
       _param3  is  any value other than the six defined constant
       values.

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


ASSOCIATED GETS

       glGet with argument GL_STENCIL_FAIL
       glGet with argument GL_STENCIL_PASS_DEPTH_PASS
       glGet with argument GL_STENCIL_PASS_DEPTH_FAIL
       glGet with argument GL_STENCIL_BITS
       glIsEnabled with argument GL_STENCIL_TEST


SEE ALSO

       glAlphaFunc,    glBlendFunc,    glDepthFunc,     glEnable,
       glLogicOp, glStencilFunc



                                                                1