<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE html
  PUBLIC "-//W3C//DTD XHTML 1.1 plus MathML 2.0//EN" "http://www.w3.org/TR/MathML2/dtd/xhtml-math11-f.dtd">
<html
	xmlns="http://www.w3.org/1999/xhtml"
	xmlns:mml="http://www.w3.org/1998/Math/MathML"
><head><title>glStencilFunc</title><link rel="stylesheet" href="style.css" type="text/css"/><meta name="generator" content="DocBook XSL Stylesheets V1.59.1"/><link rel="home" href="index.xml" title="PyOpenGL 2.0.1.07 Man Pages"/><link rel="up" href="reference-GL.xml" title="GL"/><link rel="previous" href="glShadeModel.3G.xml" title="glShadeModel"/><link rel="next" href="glStencilMask.3G.xml" title="glStencilMask"/></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">glStencilFunc</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="glShadeModel.3G.xml">Prev</a> </td><th width="60%" align="center">GL</th><td width="20%" align="right"> <a accesskey="n" href="glStencilMask.3G.xml">Next</a></td></tr></table><hr/></div><div class="refentry" lang="en"><a name="glStencilFunc.3G"/><div class="titlepage"/><div class="refnamediv"><a name="glStencilFunc.3G-name"/><h2>Name</h2><p>glStencilFunc &#8212; set function and reference value for stencil testing</p></div><div class="refsynopsisdiv"><a name="glStencilFunc.3G-c_spec"/><h2>C Specification</h2><table class="funcprototype" border="0" cellpadding="0" cellspacing="0"><tr><td valign="top"><code>void <tt>glStencilFunc</tt></code></td><td valign="top"><code>(</code></td><td valign="top"><code>GLenum <i><tt>func</tt></i>, GLint <i><tt>ref</tt></i>, GLuint <i><tt>mask</tt></i>);</code></td></tr></table></div><div class="refsynopsisdiv"><a name="glStencilFunc.3G-python_spec"/><h2>Python Specification</h2><table class="funcprototype" border="0" cellpadding="0" cellspacing="0"><tr><td valign="top"><code><tt>glStencilFunc</tt></code></td><td valign="top"><code>(</code></td><td valign="top"><code><i><tt>func</tt></i>, <i><tt>ref</tt></i>, <i><tt>mask</tt></i>) &#8594; <tt>None</tt></code></td></tr></table></div><div class="refsect1" lang="en"><a name="glStencilFunc.3G-parameters"/><h2>Parameters</h2><div class="variablelist"><dl><dt><span class="term"><i><tt>func</tt></i></span></dt><dd>
						Specifies the test function. Eight tokens are valid: <tt>GL_NEVER</tt>,
						<tt>GL_LESS</tt>, <tt>GL_LEQUAL</tt>, <tt>GL_GREATER</tt>,
						<tt>GL_GEQUAL</tt>, <tt>GL_EQUAL</tt>, <tt>GL_NOTEQUAL</tt>, and
						<tt>GL_ALWAYS</tt>. The initial value is <tt>GL_ALWAYS</tt>.
					</dd><dt><span class="term"><i><tt>ref</tt></i></span></dt><dd>
						Specifies the reference value for the stencil test. <i><tt>ref</tt></i> is clamped to the range
						[0,<mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
								<mml:mrow>
									<mml:msup>
										<mml:mn>2</mml:mn>
										<mml:mi>n</mml:mi>
									</mml:msup>
									<mml:mo>-</mml:mo>
									<mml:mn>1</mml:mn>
								</mml:mrow>
							</mml:math>], where <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
								<mml:mi>n</mml:mi>
							</mml:math> is the number of bitplanes in the stencil buffer. The initial value is 0.
					</dd><dt><span class="term"><i><tt>mask</tt></i></span></dt><dd>
						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.
					</dd></dl></div></div><div class="refsect1" lang="en"><a name="glStencilFunc.3G-description"/><h2>Description</h2><p>
			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><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 <a href="glEnable.3G.xml"><tt>glEnable</tt></a>
			and <a href="glEnable.3G.xml"><tt>glDisable</tt></a> with argument <tt>GL_STENCIL_TEST</tt>. To specify
			actions based on the outcome of the stencil test, call <a href="glStencilOp.3G.xml"><tt>glStencilOp</tt></a>.
		</p><p>
			<i><tt>func</tt></i> is a symbolic constant that determines the stencil comparison function. It accepts one of
			eight values, shown in the following list. <i><tt>ref</tt></i> is an integer reference value that is used in the
			stencil comparison. It is clamped to the range [0,<mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
					<mml:mrow>
						<mml:msup>
							<mml:mn>2</mml:mn>
							<mml:mi>n</mml:mi>
						</mml:msup>
						<mml:mo>-</mml:mo>
						<mml:mn>1</mml:mn>
					</mml:mrow>
				</mml:math>], where <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
					<mml:mi>n</mml:mi>
				</mml:math> is the number of bitplanes in the stencil buffer. <i><tt>mask</tt></i> is bitwise ANDed with
			both the reference value and the stored stencil value, with the ANDed values participating in the comparison.
		</p><p>
			If <i><tt>stencil</tt></i> 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 <i><tt>func</tt></i>. Only
			if the comparison succeeds is the pixel passed through to the next stage in the rasterization process (see
			<a href="glStencilOp.3G.xml">glStencilOp</a>). All tests treat <i><tt>stencil</tt></i> values as unsigned integers in the range
			[0,<mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
					<mml:mrow>
						<mml:msup>
							<mml:mn>2</mml:mn>
							<mml:mi>n</mml:mi>
						</mml:msup>
						<mml:mo>-</mml:mo>
						<mml:mn>1</mml:mn>
					</mml:mrow>
				</mml:math>], where <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
					<mml:mi>n</mml:mi>
				</mml:math> is the number of bitplanes in the stencil buffer.
		</p><p>
			The following values are accepted by <i><tt>func</tt></i>:
		</p><div class="variablelist"><dl><dt><span class="term"><tt>GL_NEVER</tt></span></dt><dd>
						Always fails.
					</dd><dt><span class="term"><tt>GL_LESS</tt></span></dt><dd>
						Passes if ( <i><tt>ref</tt></i> &amp; <i><tt>mask</tt></i> ) &lt; (
						<i><tt>stencil</tt></i> &amp; <i><tt>mask</tt></i> ).
					</dd><dt><span class="term"><tt>GL_LEQUAL</tt></span></dt><dd>
						Passes if ( <i><tt>ref</tt></i> &amp; <i><tt>mask</tt></i> ) &#8804; (
						<i><tt>stencil</tt></i> &amp; <i><tt>mask</tt></i> ).
					</dd><dt><span class="term"><tt>GL_GREATER</tt></span></dt><dd>
						Passes if ( <i><tt>ref</tt></i> &amp; <i><tt>mask</tt></i> ) &gt; (
						<i><tt>stencil</tt></i> &amp; <i><tt>mask</tt></i> ).
					</dd><dt><span class="term"><tt>GL_GEQUAL</tt></span></dt><dd>
						Passes if ( <i><tt>ref</tt></i> &amp; <i><tt>mask</tt></i> ) &#8805; (
						<i><tt>stencil</tt></i> &amp; <i><tt>mask</tt></i> ).
					</dd><dt><span class="term"><tt>GL_EQUAL</tt></span></dt><dd>
						Passes if ( <i><tt>ref</tt></i> &amp; <i><tt>mask</tt></i> ) = (
						<i><tt>stencil</tt></i> &amp; <i><tt>mask</tt></i> ).
					</dd><dt><span class="term"><tt>GL_NOTEQUAL</tt></span></dt><dd>
						Passes if ( <i><tt>ref</tt></i> &amp; <i><tt>mask</tt></i> ) &#8800; (
						<i><tt>stencil</tt></i> &amp; <i><tt>mask</tt></i> ).
					</dd><dt><span class="term"><tt>GL_ALWAYS</tt></span></dt><dd>
						Always passes.
					</dd></dl></div></div><div class="refsect1" lang="en"><a name="glStencilFunc.3G-notes"/><h2>Notes</h2><p>
			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.
		</p></div><div class="refsect1" lang="en"><a name="glStencilFunc.3G-errors"/><h2>Errors</h2><p>
			<tt>GL_INVALID_ENUM</tt> is generated if <i><tt>func</tt></i> is not one of the eight accepted
			values.
		</p><p>
			<tt>GL_INVALID_OPERATION</tt> is generated if <tt>glStencilFunc</tt> is executed between the
			execution of <a href="glBegin.3G.xml"><tt>glBegin</tt></a> and the corresponding execution of <a href="glBegin.3G.xml"><tt>glEnd</tt></a>.
		</p></div><div class="refsect1" lang="en"><a name="glStencilFunc.3G-associated_gets"/><h2>Associated Gets</h2><p>
			<tt>glGet</tt> with argument <tt>GL_STENCIL_FUNC</tt>
		</p><p>
			<tt>glGet</tt> with argument <tt>GL_STENCIL_VALUE_MASK</tt>
		</p><p>
			<tt>glGet</tt> with argument <tt>GL_STENCIL_REF</tt>
		</p><p>
			<tt>glGet</tt> with argument <tt>GL_STENCIL_BITS</tt>
		</p><p>
			<a href="glIsEnabled.3G.xml"><tt>glIsEnabled</tt></a> with argument <tt>GL_STENCIL_TEST</tt>
		</p></div><div class="refsect1" lang="en"><a name="glStencilFunc.3G-see_also"/><h2>See Also</h2><p>
			<span class="simplelist"><a href="glAlphaFunc.3G.xml">glAlphaFunc</a>, <a href="glBlendFunc.3G.xml">glBlendFunc</a>, <a href="glDepthFunc.3G.xml">glDepthFunc</a>, <a href="glEnable.3G.xml">glEnable</a>, <a href="glIsEnabled.3G.xml">glIsEnabled</a>, <a href="glLogicOp.3G.xml">glLogicOp</a>, <a href="glStencilOp.3G.xml">glStencilOp</a></span>
		</p></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="glShadeModel.3G.xml">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="reference-GL.xml">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="glStencilMask.3G.xml">Next</a></td></tr><tr><td width="40%" align="left" valign="top">glShadeModel </td><td width="20%" align="center"><a accesskey="h" href="index.xml">Home</a></td><td width="40%" align="right" valign="top"> glStencilMask</td></tr></table></div></body></html>
