gl.StencilOp(fail, zfail, zpass)
The stencil test conditionally eliminates a pixel based on the outcome of a comparison between the value in the stencil
buffer and a reference value. To enable and disable the test, call gl.Enable() and gl.Disable()
with argument #GL_STENCIL_TEST
; to control it, call gl.StencilFunc().
gl.StencilOp()
takes three arguments that indicate what happens 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 fail
specifies what happens to
the stencil buffer contents. The following eight actions are possible.
#GL_KEEP
#GL_ZERO
#GL_REPLACE
#GL_INCR
#GL_DECR
#GL_INVERT
Stencil buffer values are treated as unsigned integers. When incremented and decremented, values are clamped to 0 and 2^n - 1,
where n is the value returned by querying #GL_STENCIL_BITS
.
The other two arguments to gl.StencilOp()
specify stencil buffer actions that depend on whether subsequent depth buffer tests
succeed (zpass
) or fail (zfail
) (See gl.DepthFunc for details.). The actions are specified using the same eight symbolic
constants as fail
. Note that zfail
is ignored when there is no depth buffer, or when the depth buffer is not enabled. In
these cases, fail
and zpass
specify stencil action when the stencil test fails and passes, respectively.
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 gl.StencilOp()
.
Please consult an OpenGL reference manual for more information.
#GL_KEEP
(see above)zfail
accepts the same symbolic constants as fail
; the initial value is #GL_KEEP
zpass
accepts the same symbolic constants as fail
; the initial value is #GL_KEEP
#GL_INVALID_ENUM
is generated if fail
, zfail
, or zpass
is any value other than the eight defined constant values.
#GL_INVALID_OPERATION
is generated if gl.StencilOp()
is executed between the execution of gl.Begin() and the corresponding execution of gl.End().
#GL_STENCIL_FAIL
, #GL_STENCIL_PASS_DEPTH_PASS
, #GL_STENCIL_PASS_DEPTH_FAIL
, #GL_STENCIL_BACK_FAIL
, or #GL_STENCIL_BITS
gl.IsEnabled() with argument #GL_STENCIL_TEST