148 lines
4.4 KiB
Plaintext
148 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 stencilfu
|
|
.ds Xs 21383 6 stencilfunc.gl
|
|
.TH GLSTENCILFUNC 3G
|
|
.SH NAME
|
|
.B "glStencilFunc
|
|
\- set function and reference value for stencil testing
|
|
|
|
.EQ
|
|
delim $$
|
|
.EN
|
|
.SH C SPECIFICATION
|
|
void \f3glStencilFunc\fP(
|
|
GLenum \fIfunc\fP,
|
|
.nf
|
|
.ta \w'\f3void \fPglStencilFunc( 'u
|
|
GLint \fIref\fP,
|
|
GLuint \fImask\fP )
|
|
.fi
|
|
|
|
.SH PARAMETERS
|
|
.TP \w'\f2func\fP\ \ 'u
|
|
\f2func\fP
|
|
Specifies the test function.
|
|
Eight tokens are valid:
|
|
\%\f3GL_NEVER\fP,
|
|
\%\f3GL_LESS\fP,
|
|
\%\f3GL_LEQUAL\fP,
|
|
\%\f3GL_GREATER\fP,
|
|
\%\f3GL_GEQUAL\fP,
|
|
\%\f3GL_EQUAL\fP,
|
|
\%\f3GL_NOTEQUAL\fP, and
|
|
\%\f3GL_ALWAYS\fP. The initial value is \%\f3GL_ALWAYS\fP.
|
|
.TP
|
|
\f2ref\fP
|
|
Specifies the reference value for the stencil test.
|
|
\f2ref\fP is clamped to the range [0,$2 sup n - 1$],
|
|
where $n$ is the number of bitplanes in the stencil buffer. The
|
|
initial value is 0.
|
|
.TP
|
|
\f2mask\fP
|
|
Specifies a mask that is ANDed with both the reference value
|
|
and the stored stencil value when the test is done. The initial value
|
|
is all 1's.
|
|
.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 reference value
|
|
and the value in the stencil buffer.
|
|
To enable and disable the test, call \%\f3glEnable\fP and \%\f3glDisable\fP
|
|
with argument \%\f3GL_STENCIL_TEST\fP.
|
|
To specify actions based on the outcome of the stencil test, call
|
|
\%\f3glStencilOp\fP.
|
|
.P
|
|
\f2func\fP is a symbolic constant that determines the stencil comparison function.
|
|
It accepts one of eight values,
|
|
shown in the following list.
|
|
\f2ref\fP is an integer reference value that is used in the stencil comparison.
|
|
It is clamped to the range [0,$2 sup n - 1$],
|
|
where $n$ is the number of bitplanes in the stencil buffer.
|
|
\f2mask\fP is bitwise ANDed with both the reference value
|
|
and the stored stencil value,
|
|
with the ANDed values participating in the comparison.
|
|
.P
|
|
If \f2stencil\fP represents the value stored in the corresponding
|
|
stencil buffer location,
|
|
the following list shows the effect of each comparison function
|
|
that can be specified by \f2func\fP.
|
|
Only if the comparison succeeds is the pixel passed through
|
|
to the next stage in the rasterization process
|
|
(see \%\f3glStencilOp\fP).
|
|
All tests treat \f2stencil\fP values as unsigned integers in the range
|
|
[0,$2 sup n - 1$],
|
|
where $n$ is the number of bitplanes in the stencil buffer.
|
|
.P
|
|
The following values are accepted by \f2func\fP:
|
|
.TP 18
|
|
\%\f3GL_NEVER\fP
|
|
Always fails.
|
|
.TP
|
|
\%\f3GL_LESS\fP
|
|
Passes if ( \f2ref\fP & \f2mask\fP ) < ( \f2stencil\fP & \f2mask\fP ).
|
|
.TP
|
|
\%\f3GL_LEQUAL\fP
|
|
Passes if ( \f2ref\fP & \f2mask\fP ) \(<= ( \f2stencil\fP & \f2mask\fP ).
|
|
.TP
|
|
\%\f3GL_GREATER\fP
|
|
Passes if ( \f2ref\fP & \f2mask\fP ) > ( \f2stencil\fP & \f2mask\fP ).
|
|
.TP
|
|
\%\f3GL_GEQUAL\fP
|
|
Passes if ( \f2ref\fP & \f2mask\fP ) \(>= ( \f2stencil\fP & \f2mask\fP ).
|
|
.TP
|
|
\%\f3GL_EQUAL\fP
|
|
Passes if ( \f2ref\fP & \f2mask\fP ) = ( \f2stencil\fP & \f2mask\fP ).
|
|
.TP
|
|
\%\f3GL_NOTEQUAL\fP
|
|
Passes if ( \f2ref\fP & \f2mask\fP ) \(!= ( \f2stencil\fP & \f2mask\fP ).
|
|
.TP
|
|
\%\f3GL_ALWAYS\fP
|
|
Always passes.
|
|
.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 test always passes.
|
|
.SH ERRORS
|
|
\%\f3GL_INVALID_ENUM\fP is generated if \f2func\fP is not one of the eight
|
|
accepted values.
|
|
.P
|
|
\%\f3GL_INVALID_OPERATION\fP is generated if \%\f3glStencilFunc\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_FUNC\fP
|
|
.br
|
|
\%\f3glGet\fP with argument \%\f3GL_STENCIL_VALUE_MASK\fP
|
|
.br
|
|
\%\f3glGet\fP with argument \%\f3GL_STENCIL_REF\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,
|
|
\%\f3glIsEnabled(3G)\fP,
|
|
\%\f3glLogicOp(3G)\fP,
|
|
\%\f3glStencilOp(3G)\fP
|