forked from BSVino/docs.gl
-
Notifications
You must be signed in to change notification settings - Fork 0
/
glStencilFunc.xhtml
199 lines (199 loc) · 12.5 KB
/
glStencilFunc.xhtml
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
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
<div class="refentry" title="glStencilFunc"><a id="glStencilFunc"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>glStencilFunc — set function and reference value for stencil
testing</p></div><div class="refsynopsisdiv" title="C Specification"><h2>C Specification</h2><div class="funcsynopsis"><table class="funcprototype-table"><tr><td><code class="funcdef">void <b class="fsfunc">glStencilFunc</b>(</code></td><td>GLenum <var class="pdparam">func</var>, </td></tr><tr><td> </td><td>GLint <var class="pdparam">ref</var>, </td></tr><tr><td> </td><td>GLuint <var class="pdparam">mask</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div></div><div class="refsect1" title="Parameters"><a id="parameters"></a><h2>Parameters</h2><div class="variablelist"><dl><dt><span class="term">
<em class="parameter"><code>func</code></em>
</span></dt><dd><p>Specifies the test function. Eight tokens are valid:
<code class="constant">GL_NEVER</code>,
<code class="constant">GL_LESS</code>,
<code class="constant">GL_LEQUAL</code>,
<code class="constant">GL_GREATER</code>,
<code class="constant">GL_GEQUAL</code>,
<code class="constant">GL_EQUAL</code>,
<code class="constant">GL_NOTEQUAL</code>, and
<code class="constant">GL_ALWAYS</code>. The initial value is
<code class="constant">GL_ALWAYS</code>.</p></dd><dt><span class="term">
<em class="parameter"><code>ref</code></em>
</span></dt><dd><p>Specifies the reference value for the stencil test.
<em class="parameter"><code>ref</code></em>
is clamped to the range
<math overflow="scroll">
<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>,
where <em class="replaceable"><code>n</code></em> is
the number of bitplanes in the stencil buffer. The
initial value is 0.</p></dd><dt><span class="term">
<em class="parameter"><code>mask</code></em>
</span></dt><dd><p>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.</p></dd></dl></div></div><div class="refsect1" title="Description"><a id="description"></a><h2>Description</h2><p>Stenciling, like depth-buffering, enables and disables
drawing on a per-pixel basis.
Stencil planes are first drawn into using GL drawing primitives, then
geometry and images are rendered 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 stencil
test, call
<a class="citerefentry" href="glEnable"><span class="citerefentry"><span class="refentrytitle">glEnable</span></span></a> and
<a class="citerefentry" href="glDisable"><span class="citerefentry"><span class="refentrytitle">glDisable</span></span></a>
with argument
<code class="constant">GL_STENCIL_TEST</code>.
Stencil test is initially disabled.
To specify actions based on the outcome of the stencil test, call
<a class="citerefentry" href="glStencilOp"><span class="citerefentry"><span class="refentrytitle">glStencilOp</span></span></a>.
</p><p>
<em class="parameter"><code>func</code></em>
is a symbolic constant that determines the stencil comparison
function. It accepts one of eight values, shown in the
following list. <em class="parameter"><code>ref</code></em>
is an integer reference value that is used in the stencil
comparison. It is clamped to the range
<math overflow="scroll">
<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>, where <em class="replaceable"><code>n</code></em>
is the number of bitplanes in the stencil buffer.
<em class="parameter"><code>mask</code></em>
is bitwise ANDed with both the reference value and the stored
stencil value, with the ANDed values participating in the
comparison.</p><p>If <em class="parameter"><code>stencil</code></em>
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
<em class="parameter"><code>func</code></em>.
Only if the comparison succeeds is the pixel passed through
to the next stage in the rasterization process (see
<a class="citerefentry" href="glStencilOp"><span class="citerefentry"><span class="refentrytitle">glStencilOp</span></span></a>).
All tests treat <em class="parameter"><code>stencil</code></em>
values as unsigned integers in the range
<math overflow="scroll">
<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>, where <em class="replaceable"><code>n</code></em>
is the number of bitplanes in the stencil buffer.</p><p>The following values are accepted by
<em class="parameter"><code>func</code></em>:</p><div class="variablelist"><dl><dt><span class="term">
<code class="constant">GL_NEVER</code>
</span></dt><dd><p>Always fails.</p></dd><dt><span class="term">
<code class="constant">GL_LESS</code>
</span></dt><dd><p>Passes if
<math overflow="scroll">
<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>.</p></dd><dt><span class="term">
<code class="constant">GL_LEQUAL</code>
</span></dt><dd><p>Passes if
<math overflow="scroll">
<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>.</p></dd><dt><span class="term">
<code class="constant">GL_GREATER</code>
</span></dt><dd><p>Passes if
<math overflow="scroll">
<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>.</p></dd><dt><span class="term">
<code class="constant">GL_GEQUAL</code>
</span></dt><dd><p>Passes if
<math overflow="scroll">
<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>.</p></dd><dt><span class="term">
<code class="constant">GL_EQUAL</code>
</span></dt><dd><p>Passes if
<math overflow="scroll">
<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>.</p></dd><dt><span class="term">
<code class="constant">GL_NOTEQUAL</code>
</span></dt><dd><p>Passes if
<math overflow="scroll">
<mfenced><mrow>
<mi>ref</mi>
<mo>&</mo>
<mi>mask</mi>
</mrow></mfenced>
<mo><</mo>
<mo>></mo>
<mfenced><mrow>
<mi>stencil</mi>
<mo>&</mo>
<mi>mask</mi>
</mrow></mfenced>
</math>.</p></dd><dt><span class="term">
<code class="constant">GL_ALWAYS</code>
</span></dt><dd><p>Always passes.</p></dd></dl></div></div><div class="refsect1" title="Notes"><a id="notes"></a><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" title="Errors"><a id="errors"></a><h2>Errors</h2><p> <code class="constant">GL_INVALID_ENUM</code> is generated if
<em class="parameter"><code>func</code></em> is not one of the eight accepted values.</p></div><div class="refsect1" title="Associated Gets"><a id="associatedgets"></a><h2>Associated Gets</h2><p>
<a class="citerefentry" href="glGet"><span class="citerefentry"><span class="refentrytitle">glGet</span></span></a>
with argument <code class="constant">GL_STENCIL_BITS</code>
</p></div><div class="refsect1" title="See Also"><a id="seealso"></a><h2>See Also</h2><p>
<a class="citerefentry" href="glAlphaFunc"><span class="citerefentry"><span class="refentrytitle">glAlphaFunc</span></span></a>,
<a class="citerefentry" href="glBlendFunc"><span class="citerefentry"><span class="refentrytitle">glBlendFunc</span></span></a>,
<a class="citerefentry" href="glDepthFunc"><span class="citerefentry"><span class="refentrytitle">glDepthFunc</span></span></a>,
<a class="citerefentry" href="glEnable"><span class="citerefentry"><span class="refentrytitle">glEnable</span></span></a>,
<a class="citerefentry" href="glGet"><span class="citerefentry"><span class="refentrytitle">glGet</span></span></a>,
<a class="citerefentry" href="glLogicOp"><span class="citerefentry"><span class="refentrytitle">glLogicOp</span></span></a>,
<a class="citerefentry" href="glStencilOp"><span class="citerefentry"><span class="refentrytitle">glStencilOp</span></span></a>
</p></div><div class="refsect1" title="Copyright"><a id="copyright"></a><h2>Copyright</h2><p>
Copyright © 2003-2004
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
<a class="ulink" href="https://web.archive.org/web/20171022161616/http://oss.sgi.com/projects/FreeB/" target="_top">https://web.archive.org/web/20171022161616/http://oss.sgi.com/projects/FreeB/</a>.
</p></div></div>