<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook MathML Module V1.0//EN" "DTD/dbmathml.dtd">
<!--
License Applicability. Except to the extent portions of this file are
made subject to an alternative license as permitted in the SGI Free
Software License B, Version 1.1 (the "License"), the contents of this
file are subject only to the provisions of the License. You may not use
this file except in compliance with the License. You may obtain a copy
of the License at Silicon Graphics, Inc., attn: Legal Services, 1600
Amphitheatre Parkway, Mountain View, CA 94043-1351, or at:
http://oss.sgi.com/projects/FreeB
Note that, as provided in the License, the Software is distributed on an
"AS IS" basis, with ALL EXPRESS AND IMPLIED WARRANTIES AND CONDITIONS
DISCLAIMED, INCLUDING, WITHOUT LIMITATION, ANY IMPLIED WARRANTIES AND
CONDITIONS OF MERCHANTABILITY, SATISFACTORY QUALITY, FITNESS FOR A
PARTICULAR PURPOSE, AND NON-INFRINGEMENT.
Original Code. The Original Code is: OpenGL ES Reference Manual,
Version 1.0, released September 2003, developed by Silicon Graphics,
Inc. The Original Code is Copyright (c) 2003 Silicon Graphics, Inc.
Copyright in any portions created by third parties is as indicated
elsewhere herein. All Rights Reserved.
-->
<refentry id="glStencilFunc">
<refmeta>
<refentrytitle>glStencilFunc</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glStencilFunc</refname>
<refpurpose>set function and reference value for stencil
testing</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glStencilFunc</function></funcdef>
<paramdef>GLenum <parameter>func</parameter></paramdef>
<paramdef>GLint <parameter>ref</parameter></paramdef>
<paramdef>GLuint <parameter>mask</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Parameters</title>
<variablelist>
<varlistentry>
<term>
<parameter>func</parameter>
</term>
<listitem>
<para>Specifies the test function. Eight tokens are valid:
<constant>GL_NEVER</constant>,
<constant>GL_LESS</constant>,
<constant>GL_LEQUAL</constant>,
<constant>GL_GREATER</constant>,
<constant>GL_GEQUAL</constant>,
<constant>GL_EQUAL</constant>,
<constant>GL_NOTEQUAL</constant>, and
<constant>GL_ALWAYS</constant>. The initial value is
<constant>GL_ALWAYS</constant>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<parameter>ref</parameter>
</term>
<listitem>
<para>Specifies the reference value for the stencil test.
<parameter>ref</parameter>
is clamped to the range
<inlineequation><math>
<mo>[</mo>
<mn>0</mn>
<mo>,</mo>
<msup><mn>2</mn><mrow><mi>n</mi><mo>-</mo><mn>1</mn></mrow></msup>
<mo>]</mo>
</math></inlineequation>,
where <replaceable>n</replaceable> is
the number of bitplanes in the stencil buffer. The
initial value is 0.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<parameter>mask</parameter>
</term>
<listitem>
<para>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.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>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.</para>
<para>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 stencil
test, call
<citerefentry><refentrytitle>glEnable</refentrytitle></citerefentry> and
<citerefentry><refentrytitle>glDisable</refentrytitle></citerefentry>
with argument
<constant>GL_STENCIL_TEST</constant>.
Stencil test is initially disabled.
To specify actions based on the outcome of the stencil test, call
<citerefentry><refentrytitle>glStencilOp</refentrytitle></citerefentry>.
</para>
<para>
<parameter>func</parameter>
is a symbolic constant that determines the stencil comparison
function. It accepts one of eight values, shown in the
following list. <parameter>ref</parameter>
is an integer reference value that is used in the stencil
comparison. It is clamped to the range
<inlineequation><math>
<mo>[</mo>
<mn>0</mn>
<mo>,</mo>
<msup><mn>2</mn><mrow><mi>n</mi><mo>-</mo><mn>1</mn></mrow></msup>
<mo>]</mo>
</math></inlineequation>, where <replaceable>n</replaceable>
is the number of bitplanes in the stencil buffer.
<parameter>mask</parameter>
is bitwise ANDed with both the reference value and the stored
stencil value, with the ANDed values participating in the
comparison.</para>
<para>If <parameter>stencil</parameter>
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
<parameter>func</parameter>.
Only if the comparison succeeds is the pixel passed through
to the next stage in the rasterization process (see
<citerefentry><refentrytitle>glStencilOp</refentrytitle></citerefentry>).
All tests treat <parameter>stencil</parameter>
values as unsigned integers in the range
<inlineequation><math>
<mo>[</mo>
<mn>0</mn>
<mo>,</mo>
<msup><mn>2</mn><mrow><mi>n</mi><mo>-</mo><mn>1</mn></mrow></msup>
<mo>]</mo>
</math></inlineequation>, where <replaceable>n</replaceable>
is the number of bitplanes in the stencil buffer.</para>
<para>The following values are accepted by
<parameter>func</parameter>:</para>
<variablelist>
<varlistentry>
<term>
<constant>GL_NEVER</constant>
</term>
<listitem>
<para>Always fails.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<constant>GL_LESS</constant>
</term>
<listitem>
<para>Passes if
<inlineequation><math>
<mfenced><mrow>
<mi>ref</mi>
<mo>&</mo>
<mi>mask</mi>
</mrow></mfenced>
<mo><</mo>
<mfenced><mrow>
<mi>stencil</mi>
<mo>&</mo>
<mi>mask</mi>
</mrow></mfenced>
</math></inlineequation>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<constant>GL_LEQUAL</constant>
</term>
<listitem>
<para>Passes if
<inlineequation><math>
<mfenced><mrow>
<mi>ref</mi>
<mo>&</mo>
<mi>mask</mi>
</mrow></mfenced>
<mo><=</mo>
<mfenced><mrow>
<mi>stencil</mi>
<mo>&</mo>
<mi>mask</mi>
</mrow></mfenced>
</math></inlineequation>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<constant>GL_GREATER</constant>
</term>
<listitem>
<para>Passes if
<inlineequation><math>
<mfenced><mrow>
<mi>ref</mi>
<mo>&</mo>
<mi>mask</mi>
</mrow></mfenced>
<mo>></mo>
<mfenced><mrow>
<mi>stencil</mi>
<mo>&</mo>
<mi>mask</mi>
</mrow></mfenced>
</math></inlineequation>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<constant>GL_GEQUAL</constant>
</term>
<listitem>
<para>Passes if
<inlineequation><math>
<mfenced><mrow>
<mi>ref</mi>
<mo>&</mo>
<mi>mask</mi>
</mrow></mfenced>
<mo>>=</mo>
<mfenced><mrow>
<mi>stencil</mi>
<mo>&</mo>
<mi>mask</mi>
</mrow></mfenced>
</math></inlineequation>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<constant>GL_EQUAL</constant>
</term>
<listitem>
<para>Passes if
<inlineequation><math>
<mfenced><mrow>
<mi>ref</mi>
<mo>&</mo>
<mi>mask</mi>
</mrow></mfenced>
<mo>=</mo>
<mfenced><mrow>
<mi>stencil</mi>
<mo>&</mo>
<mi>mask</mi>
</mrow></mfenced>
</math></inlineequation>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<constant>GL_NOTEQUAL</constant>
</term>
<listitem>
<para>Passes if
<inlineequation><math>
<mfenced><mrow>
<mi>ref</mi>
<mo>&</mo>
<mi>mask</mi>
</mrow></mfenced>
<mo>≠</mo>
<mfenced><mrow>
<mi>stencil</mi>
<mo>&</mo>
<mi>mask</mi>
</mrow></mfenced>
</math></inlineequation>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<constant>GL_ALWAYS</constant>
</term>
<listitem>
<para>Always passes.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Notes</title>
<para>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.</para>
</refsect1>
<refsect1>
<title>Errors</title>
<para> <constant>GL_INVALID_ENUM</constant> is generated if
<parameter>func</parameter> is not one of the eight accepted values.</para>
</refsect1>
<refsect1>
<title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glGetInteger</refentrytitle></citerefentry>
with argument <constant>GL_STENCIL_BITS</constant>
</para>
</refsect1>
<refsect1>
<title>See Also</title>
<para>
<citerefentry><refentrytitle>glAlphaFunc</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glBlendFunc</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDepthFunc</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glEnable</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glGetInteger</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glLogicOp</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glStencilOp</refentrytitle></citerefentry>
</para>
</refsect1>
</refentry>
![[BACK]](/icons/back.gif){kind=icon}
Return to glStencilFunc.xml CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [Development] / projects / ogl-sample / main / doc / gles / xml