- 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