1GLSTENCILFUNC(3G) [FIXME: manual] GLSTENCILFUNC(3G)
2
6 glStencilFunc - set front and back function and reference value for
7 stencil testing
8
10 void glStencilFunc(GLenum func, GLint ref, GLuint mask);
11
13 func
14 Specifies the test function. Eight symbolic constants are valid:
15 GL_NEVER, GL_LESS, GL_LEQUAL, GL_GREATER, GL_GEQUAL, GL_EQUAL,
16 GL_NOTEQUAL, and GL_ALWAYS. The initial value is GL_ALWAYS.
17 ref
19 Specifies the reference value for the stencil test. ref is clamped
20 to the range 0 2 n - 1, where n is the number of bitplanes in the
21 stencil buffer. The initial value is 0.
22 mask
24 Specifies a mask that is ANDed with both the reference value and
25 the stored stencil value when the test is done. The initial value
26 is all 1's.
27
29 Stenciling, like depth-buffering, enables and disables drawing on a
30 per-pixel basis. Stencil planes are first drawn into using GL drawing
31 primitives, then geometry and images are rendered using the stencil
32 planes to mask out portions of the screen. Stenciling is typically used
33 in multipass rendering algorithms to achieve special effects, such as
34 decals, outlining, and constructive solid geometry rendering.
35 The stencil test conditionally eliminates a pixel based on the outcome
37 of a comparison between the reference value and the value in the
38 stencil buffer. To enable and disable the test, call glEnable() and
39 glDisable with argument GL_STENCIL_TEST. To specify actions based on
41 the outcome of the stencil test, call glStencilOp() or
42 glStencilOpSeparate().
43 There can be two separate sets of func, ref, and mask parameters; one
45 affects back-facing polygons, and the other affects front-facing
46 polygons as well as other non-polygon primitives. glStencilFunc() sets
47 both front and back stencil state to the same values. Use
48 glStencilFuncSeparate() to set front and back stencil state to
49 different values.
50 func is a symbolic constant that determines the stencil comparison
52 function. It accepts one of eight values, shown in the following list.
53 ref is an integer reference value that is used in the stencil
54 comparison. It is clamped to the range 0 2 n - 1, where n is the number
55 of bitplanes in the stencil buffer. mask is bitwise ANDed with both
56 the reference value and the stored stencil value, with the ANDed values
57 participating in the comparison.
58 If stencil represents the value stored in the corresponding stencil
60 buffer location, the following list shows the effect of each comparison
61 function that can be specified by func. Only if the comparison succeeds
62 is the pixel passed through to the next stage in the rasterization
63 process (see glStencilOp()). All tests treat stencil values as unsigned
64 integers in the range 0 2 n - 1, where n is the number of bitplanes in
65 the stencil buffer.
66 The following values are accepted by func:
68 GL_NEVER
70 Always fails.
71 GL_LESS
73 Passes if ( ref & mask ) < ( stencil & mask ).
74 GL_LEQUAL
76 Passes if ( ref & mask ) <= ( stencil & mask ).
77 GL_GREATER
79 Passes if ( ref & mask ) > ( stencil & mask ).
80 GL_GEQUAL
82 Passes if ( ref & mask ) >= ( stencil & mask ).
83 GL_EQUAL
85 Passes if ( ref & mask ) = ( stencil & mask ).
86 GL_NOTEQUAL
88 Passes if ( ref & mask ) != ( stencil & mask ).
89 GL_ALWAYS
91 Always passes.
92
94 Initially, the stencil test is disabled. If there is no stencil buffer,
95 no stencil modification can occur and it is as if the stencil test
96 always passes.
97 glStencilFunc() is the same as calling glStencilFuncSeparate() with
99 face set to GL_FRONT_AND_BACK.
100
102 GL_INVALID_ENUM is generated if func is not one of the eight accepted
103 values.
104
106 glGet() with argument GL_STENCIL_FUNC, GL_STENCIL_VALUE_MASK,
107 GL_STENCIL_REF, GL_STENCIL_BACK_FUNC, GL_STENCIL_BACK_VALUE_MASK,
108 GL_STENCIL_BACK_REF, or GL_STENCIL_BITS
109 glIsEnabled() with argument GL_STENCIL_TEST
111
113 ┌──────────────┬───────────────────────────────────────────────────────────────────────┐
114 │ │ OpenGL Version │
115 ├──────────────┼─────┬─────┬─────┬─────┬─────┬─────┬─────┬─────┬─────┬─────┬─────┬─────┤
116 │Function │ 2.0 │ 2.1 │ 3.0 │ 3.1 │ 3.2 │ 3.3 │ 4.0 │ 4.1 │ 4.2 │ 4.3 │ 4.4 │ 4.5 │
117 │/ │ │ │ │ │ │ │ │ │ │ │ │ │
118 │Feature │ │ │ │ │ │ │ │ │ │ │ │ │
119 │Name │ │ │ │ │ │ │ │ │ │ │ │ │
120 ├──────────────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┤
121 │glStencilFunc │ ✔ │ ✔ │ ✔ │ ✔ │ ✔ │ ✔ │ ✔ │ ✔ │ ✔ │ ✔ │ ✔ │ ✔ │
122 └──────────────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┘
123
125 glBlendFunc(), glDepthFunc(), glEnable(), glLogicOp(),
126 glStencilFuncSeparate(), glStencilMask(), glStencilMaskSeparate(),
127 glStencilOp(), glStencilOpSeparate()
128
130 Copyright © 1991-2006 Silicon Graphics, Inc. Copyright © 2010-2014
131 Khronos Group. This document is licensed under the SGI Free Software B
132 License. For details, see http://oss.sgi.com/projects/FreeB/.
133
135 Copyright © 1991-2006 Silicon Graphics, Inc.
136 Copyright © 2010-2014 Khronos Group
137[FIXME: source] 07/13/2018 GLSTENCILFUNC(3G)