'\" t
.\"     Title: glStencilFuncSeparate
.\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
.\"      Date: 05/21/2015
.\"    Manual: [FIXME: manual]
.\"    Source: [FIXME: source]
.\"  Language: English
.\"
.TH "GLSTENCILFUNCSEPARAT" "3G" "05/21/2015" "[FIXME: source]" "[FIXME: manual]"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
glStencilFuncSeparate \- set front and/or back function and reference value for stencil testing
.SH "C SPECIFICATION"
.HP \w'void\ glStencilFuncSeparate('u
.BI "void glStencilFuncSeparate(GLenum\ " "face" ", GLenum\ " "func" ", GLint\ " "ref" ", GLuint\ " "mask" ");"
.SH "PARAMETERS"
.PP
\fIface\fR
.RS 4
Specifies whether front and/or back stencil state is updated\&. Three symbolic constants are valid:
\fBGL_FRONT\fR,
\fBGL_BACK\fR, and
\fBGL_FRONT_AND_BACK\fR\&.
.RE
.PP
\fIfunc\fR
.RS 4
Specifies the test function\&. Eight symbolic constants are valid:
\fBGL_NEVER\fR,
\fBGL_LESS\fR,
\fBGL_LEQUAL\fR,
\fBGL_GREATER\fR,
\fBGL_GEQUAL\fR,
\fBGL_EQUAL\fR,
\fBGL_NOTEQUAL\fR, and
\fBGL_ALWAYS\fR\&. The initial value is
\fBGL_ALWAYS\fR\&.
.RE
.PP
\fIref\fR
.RS 4
Specifies the reference value for the stencil test\&.
\fIref\fR
is clamped to the range
0 2 n \- 1, where
n
is the number of bitplanes in the stencil buffer\&. The initial value is 0\&.
.RE
.PP
\fImask\fR
.RS 4
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\*(Aqs\&.
.RE
.SH "DESCRIPTION"
.PP
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\&.
.PP
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
\fBglEnable\fR()
and
\fBglDisable\fR()
with argument
\fBGL_STENCIL_TEST\fR\&. To specify actions based on the outcome of the stencil test, call
\fBglStencilOp\fR()
or
\fBglStencilOpSeparate\fR()\&.
.PP
There can be two separate sets of
\fIfunc\fR,
\fIref\fR, and
\fImask\fR
parameters; one affects back\-facing polygons, and the other affects front\-facing polygons as well as other non\-polygon primitives\&.
\fBglStencilFunc\fR()
sets both front and back stencil state to the same values, as if
\fBglStencilFuncSeparate\fR()
were called with
\fIface\fR
set to
\fBGL_FRONT_AND_BACK\fR\&.
.PP
\fIfunc\fR
is a symbolic constant that determines the stencil comparison function\&. It accepts one of eight values, shown in the following list\&.
\fIref\fR
is an integer reference value that is used in the stencil comparison\&. It is clamped to the range
0 2 n \- 1, where
n
is the number of bitplanes in the stencil buffer\&.
\fImask\fR
is bitwise ANDed with both the reference value and the stored stencil value, with the ANDed values participating in the comparison\&.
.PP
If
\fIstencil\fR
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
\fIfunc\fR\&. Only if the comparison succeeds is the pixel passed through to the next stage in the rasterization process (see
\fBglStencilOp\fR())\&. All tests treat
\fIstencil\fR
values as unsigned integers in the range
0 2 n \- 1, where
n
is the number of bitplanes in the stencil buffer\&.
.PP
The following values are accepted by
\fIfunc\fR:
.PP
\fBGL_NEVER\fR
.RS 4
Always fails\&.
.RE
.PP
\fBGL_LESS\fR
.RS 4
Passes if (
\fIref\fR
&
\fImask\fR
) < (
\fIstencil\fR
&
\fImask\fR
)\&.
.RE
.PP
\fBGL_LEQUAL\fR
.RS 4
Passes if (
\fIref\fR
&
\fImask\fR
) <= (
\fIstencil\fR
&
\fImask\fR
)\&.
.RE
.PP
\fBGL_GREATER\fR
.RS 4
Passes if (
\fIref\fR
&
\fImask\fR
) > (
\fIstencil\fR
&
\fImask\fR
)\&.
.RE
.PP
\fBGL_GEQUAL\fR
.RS 4
Passes if (
\fIref\fR
&
\fImask\fR
) >= (
\fIstencil\fR
&
\fImask\fR
)\&.
.RE
.PP
\fBGL_EQUAL\fR
.RS 4
Passes if (
\fIref\fR
&
\fImask\fR
) = (
\fIstencil\fR
&
\fImask\fR
)\&.
.RE
.PP
\fBGL_NOTEQUAL\fR
.RS 4
Passes if (
\fIref\fR
&
\fImask\fR
) != (
\fIstencil\fR
&
\fImask\fR
)\&.
.RE
.PP
\fBGL_ALWAYS\fR
.RS 4
Always passes\&.
.RE
.SH "NOTES"
.PP
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"
.PP
\fBGL_INVALID_ENUM\fR
is generated if
\fIfunc\fR
is not one of the eight accepted values\&.
.SH "ASSOCIATED GETS"
.PP
\fBglGet\fR()
with argument
\fBGL_STENCIL_FUNC\fR,
\fBGL_STENCIL_VALUE_MASK\fR,
\fBGL_STENCIL_REF\fR,
\fBGL_STENCIL_BACK_FUNC\fR,
\fBGL_STENCIL_BACK_VALUE_MASK\fR,
\fBGL_STENCIL_BACK_REF\fR, or
\fBGL_STENCIL_BITS\fR
.PP
\fBglIsEnabled\fR()
with argument
\fBGL_STENCIL_TEST\fR
.SH "VERSION SUPPORT"
.TS
allbox tab(:);
lB cB s s s s s s s s s s s
lB cB cB cB cB cB cB cB cB cB cB cB cB.
T{

T}:T{
\fBOpenGL Version\fR
T}
T{
\fBFunction / Feature Name\fR
T}:T{
\fB2\&.0\fR
T}:T{
\fB2\&.1\fR
T}:T{
\fB3\&.0\fR
T}:T{
\fB3\&.1\fR
T}:T{
\fB3\&.2\fR
T}:T{
\fB3\&.3\fR
T}:T{
\fB4\&.0\fR
T}:T{
\fB4\&.1\fR
T}:T{
\fB4\&.2\fR
T}:T{
\fB4\&.3\fR
T}:T{
\fB4\&.4\fR
T}:T{
\fB4\&.5\fR
T}
.T&
l c c c c c c c c c c c c.
T{
\fBglStencilFuncSeparate\fR
T}:T{
✔
T}:T{
✔
T}:T{
✔
T}:T{
✔
T}:T{
✔
T}:T{
✔
T}:T{
✔
T}:T{
✔
T}:T{
✔
T}:T{
✔
T}:T{
✔
T}:T{
✔
T}
.TE
.sp
.SH "SEE ALSO"
.PP
\fBglBlendFunc\fR(),
\fBglDepthFunc\fR(),
\fBglEnable\fR(),
\fBglLogicOp\fR(),
\fBglStencilFunc\fR(),
\fBglStencilMask\fR(),
\fBglStencilMaskSeparate\fR(),
\fBglStencilOp\fR(),
\fBglStencilOpSeparate\fR()
.SH "COPYRIGHT"
.PP
Copyright
\(co
2006 Khronos Group\&. This material may be distributed subject to the terms and conditions set forth in the Open Publication License, v 1\&.0, 8 June 1999\&.
\m[blue]\fBhttp://opencontent\&.org/openpub/\fR\m[]\&.
.SH "COPYRIGHT"
.br
Copyright \(co 1991-2006 Silicon Graphics, Inc.
.br