144 lines
4.4 KiB
Plaintext
144 lines
4.4 KiB
Plaintext
|
'\" te
|
||
|
|
'\"! tbl|eqn | mmdoc
|
||
|
|
'\"macro stdmacro
|
||
|
|
.ds Vn Version 1.2
|
||
|
|
.ds Dt 24 September 1999
|
||
|
|
.ds Re Release 1.2.1
|
||
|
|
.ds Dp Jan 14 18:30
|
||
|
|
.ds Dm 01 stencilop
|
||
|
|
.ds Xs 3015 6 stencilop.gl
|
||
|
|
.TH GLSTENCILOP 3G
|
||
|
|
.SH NAME
|
||
|
|
.B "glStencilOp
|
||
|
|
\- set stencil test actions
|
||
|
|
|
||
|
|
.EQ
|
||
|
|
delim $$
|
||
|
|
.EN
|
||
|
|
.SH C SPECIFICATION
|
||
|
|
void \f3glStencilOp\fP(
|
||
|
|
GLenum \fIfail\fP,
|
||
|
|
.nf
|
||
|
|
.ta \w'\f3void \fPglStencilOp( 'u
|
||
|
|
GLenum \fIzfail\fP,
|
||
|
|
GLenum \fIzpass\fP )
|
||
|
|
.fi
|
||
|
|
|
||
|
|
.SH PARAMETERS
|
||
|
|
.TP \w'\fIzfail\fP\ \ 'u
|
||
|
|
\f2fail\fP
|
||
|
|
Specifies the action to take when the stencil test fails.
|
||
|
|
Six symbolic constants are accepted:
|
||
|
|
\%\f3GL_KEEP\fP,
|
||
|
|
\%\f3GL_ZERO\fP,
|
||
|
|
\%\f3GL_REPLACE\fP,
|
||
|
|
\%\f3GL_INCR\fP,
|
||
|
|
\%\f3GL_DECR\fP, and
|
||
|
|
\%\f3GL_INVERT\fP. The initial value is \%\f3GL_KEEP\fP.
|
||
|
|
.TP
|
||
|
|
\f2zfail\fP
|
||
|
|
Specifies the stencil action when the stencil test passes,
|
||
|
|
but the depth test fails.
|
||
|
|
\f2zfail\fP accepts the same symbolic constants as \f2fail\fP. The initial value
|
||
|
|
is \%\f3GL_KEEP\fP.
|
||
|
|
.TP
|
||
|
|
\f2zpass\fP
|
||
|
|
Specifies the stencil action when both the stencil 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.
|
||
|
|
\f2zpass\fP accepts the same symbolic constants as \f2fail\fP. The initial value
|
||
|
|
is \%\f3GL_KEEP\fP.
|
||
|
|
.SH 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 rendering.
|
||
|
|
.P
|
||
|
|
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 \%\f3glEnable\fP
|
||
|
|
and \%\f3glDisable\fP with argument
|
||
|
|
\%\f3GL_STENCIL_TEST\fP; to control it, call \%\f3glStencilFunc\fP.
|
||
|
|
.P
|
||
|
|
\%\f3glStencilOp\fP 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 \f2fail\fP specifies what happens to the stencil buffer contents.
|
||
|
|
The following six actions are possible.
|
||
|
|
.TP 16
|
||
|
|
\%\f3GL_KEEP\fP
|
||
|
|
Keeps the current value.
|
||
|
|
.TP
|
||
|
|
\%\f3GL_ZERO\fP
|
||
|
|
Sets the stencil buffer value to 0.
|
||
|
|
.TP
|
||
|
|
\%\f3GL_REPLACE\fP
|
||
|
|
Sets the stencil buffer value to \f2ref\fP,
|
||
|
|
as specified by \%\f3glStencilFunc\fP.
|
||
|
|
.TP
|
||
|
|
\%\f3GL_INCR\fP
|
||
|
|
Increments the current stencil buffer value.
|
||
|
|
Clamps to the maximum representable unsigned value.
|
||
|
|
.TP
|
||
|
|
\%\f3GL_DECR\fP
|
||
|
|
Decrements the current stencil buffer value.
|
||
|
|
Clamps to 0.
|
||
|
|
.TP
|
||
|
|
\%\f3GL_INVERT\fP
|
||
|
|
Bitwise inverts the current stencil buffer value.
|
||
|
|
.P
|
||
|
|
Stencil buffer values are treated as unsigned integers.
|
||
|
|
When incremented and decremented,
|
||
|
|
values are clamped to 0 and $2 sup n - 1$,
|
||
|
|
where $n$ is the value returned by querying \%\f3GL_STENCIL_BITS\fP.
|
||
|
|
.P
|
||
|
|
The other two arguments to \%\f3glStencilOp\fP specify stencil buffer actions
|
||
|
|
that depend on whether subsequent depth buffer tests succeed (\f2zpass\fP)
|
||
|
|
or fail (\f2zfail\fP) (see
|
||
|
|
.br
|
||
|
|
\%\f3glDepthFunc\fP).
|
||
|
|
The actions are specified using the same six symbolic constants as \f2fail\fP.
|
||
|
|
Note that \f2zfail\fP is ignored when there is no depth buffer,
|
||
|
|
or when the depth buffer is not enabled.
|
||
|
|
In these cases, \f2fail\fP and \f2zpass\fP specify stencil action when the
|
||
|
|
stencil test fails and passes,
|
||
|
|
respectively.
|
||
|
|
.SH 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 \%\f3glStencilOp\fP.
|
||
|
|
.SH ERRORS
|
||
|
|
\%\f3GL_INVALID_ENUM\fP is generated if \f2fail\fP,
|
||
|
|
\f2zfail\fP, or \f2zpass\fP is any value other than the six defined constant values.
|
||
|
|
.P
|
||
|
|
\%\f3GL_INVALID_OPERATION\fP is generated if \%\f3glStencilOp\fP
|
||
|
|
is executed between the execution of \%\f3glBegin\fP
|
||
|
|
and the corresponding execution of \%\f3glEnd\fP.
|
||
|
|
.SH ASSOCIATED GETS
|
||
|
|
\%\f3glGet\fP with argument \%\f3GL_STENCIL_FAIL\fP
|
||
|
|
.br
|
||
|
|
\%\f3glGet\fP with argument \%\f3GL_STENCIL_PASS_DEPTH_PASS\fP
|
||
|
|
.br
|
||
|
|
\%\f3glGet\fP with argument \%\f3GL_STENCIL_PASS_DEPTH_FAIL\fP
|
||
|
|
.br
|
||
|
|
\%\f3glGet\fP with argument \%\f3GL_STENCIL_BITS\fP
|
||
|
|
.br
|
||
|
|
\%\f3glIsEnabled\fP with argument \%\f3GL_STENCIL_TEST\fP
|
||
|
|
.SH SEE ALSO
|
||
|
|
\%\f3glAlphaFunc(3G)\fP,
|
||
|
|
\%\f3glBlendFunc(3G)\fP,
|
||
|
|
\%\f3glDepthFunc(3G)\fP,
|
||
|
|
\%\f3glEnable(3G)\fP,
|
||
|
|
\%\f3glLogicOp(3G)\fP,
|
||
|
|
\%\f3glStencilFunc(3G)\fP
|