1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
|
<?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 — 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>) →<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> & <i><tt>mask</tt></i> ) < (
<i><tt>stencil</tt></i> & <i><tt>mask</tt></i> ).
</dd><dt><span class="term"><tt>GL_LEQUAL</tt></span></dt><dd>
Passes if ( <i><tt>ref</tt></i> & <i><tt>mask</tt></i> ) ≤ (
<i><tt>stencil</tt></i> & <i><tt>mask</tt></i> ).
</dd><dt><span class="term"><tt>GL_GREATER</tt></span></dt><dd>
Passes if ( <i><tt>ref</tt></i> & <i><tt>mask</tt></i> ) > (
<i><tt>stencil</tt></i> & <i><tt>mask</tt></i> ).
</dd><dt><span class="term"><tt>GL_GEQUAL</tt></span></dt><dd>
Passes if ( <i><tt>ref</tt></i> & <i><tt>mask</tt></i> ) ≥ (
<i><tt>stencil</tt></i> & <i><tt>mask</tt></i> ).
</dd><dt><span class="term"><tt>GL_EQUAL</tt></span></dt><dd>
Passes if ( <i><tt>ref</tt></i> & <i><tt>mask</tt></i> ) = (
<i><tt>stencil</tt></i> & <i><tt>mask</tt></i> ).
</dd><dt><span class="term"><tt>GL_NOTEQUAL</tt></span></dt><dd>
Passes if ( <i><tt>ref</tt></i> & <i><tt>mask</tt></i> ) ≠ (
<i><tt>stencil</tt></i> & <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>
|
