• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1Name
2
3    AMD_shader_stencil_export
4
5Name Strings
6
7    GL_AMD_shader_stencil_export
8
9Contributors
10
11    Graham Sellers, AMD
12    Andrew Lewycky, AMD
13    Mais Alnasser, AMD
14
15Contact
16
17    Graham Sellers, AMD (graham.sellers 'at' amd.com)
18
19Status
20
21    In Progress.
22
23Version
24
25    Last Modified Date:         04/07/2010
26    Author Revision:            5
27
28Number
29
30    382
31
32Dependencies
33
34    OpenGL 1.0 is required.
35
36    ARB_fragment_shader is required.
37
38    This extension is written against the OpenGL Shading Language Specification
39    version 1.40.05
40
41Overview
42
43    In OpenGL, the stencil test is a powerful mechanism to selectively discard
44    fragments based on the content of the stencil buffer. However, facilites
45    to update the content of the stencil buffer are limited to operations such
46    as incrementing the existing value, or overwriting with a fixed reference
47    value.
48
49    This extension provides a mechanism whereby a shader may generate the
50    stencil reference value per invocation. When stencil testing is enabled,
51    this allows the test to be performed against the value generated in the
52    shader. When the stencil operation is set to GL_REPLACE, this allows a
53    value generated in the shader to be written to the stencil buffer directly.
54
55IP Status
56
57    None.
58
59New Procedures and Functions
60
61    None.
62
63New Tokens
64
65    None.
66
67Additions to Chapter 2 of the OpenGL 2.1 Specification (OpenGL Operation)
68
69    None.
70
71Additions to Chapter 3 of the OpenGL 2.1 Specification (Rasterization)
72
73    None.
74
75Additions to Chapter 4 of the OpenGL 2.1 Specification (Per-Fragment Operations
76and the Framebuffer)
77
78    None.
79
80Additions to Chapter 5 of the OpenGL 2.1 Specification (Special
81Functions)
82
83    None.
84
85Additions to Chapter 6 of the OpenGL 2.1 Specification (State and
86State Requests)
87
88    None.
89
90Additions to the OpenGL Shading Language Version 1.40.05
91
92    Add a new Section 3.3.x, GL_AMD_shader_stencil_export Extension (p. 11)
93
94    3.3.x GL_AMD_shader_stencil_export
95
96    To use the GL_AMD_shader_stencil_export extension in a shader it must be
97    enabled using the #extension directive.
98
99    The shading language preprocessor #define GL_AMD_shader_stencil_export will
100    be defined to 1 if the GL_AMD_shader_stencil_export extension is supported.
101
102    Modify Section 7.2, "Fragment Shader Special Variables":
103
104    Add to the list of built-in special variables, p.63:
105
106        out int gl_FragStencilRefAMD;
107
108    Modify the paragraph beginning, "Fragment shaders output values to the
109    OpenGL pipeline..." to:
110
111    Fragment shaders output values to the OpenGL pipeline using the built-in
112    variables gl_FragColor, gl_FragData, gl_FragDepth, and gl_FragStencilRefAMD
113    unless the discard statement is executed. Both gl_FragColor and gl_FragData
114    are deprecated; the preferred usage is to explicitly declare these outputs
115    in the fragment shader using the out storage qualifier.
116
117    Insert a new paragraph after the paragraph describing gl_FragDepth:
118
119    Writing to gl_FragStencilRefAMD will establish the stencil reference value
120    for the fragment being processed. Only the least significant bits of the
121    integer gl_FragStencilRefAMD are considered up to the value of STENCIL_BITS
122    and higher order bits are discarded. If stencil testing is enabled and no
123    shader writes to gl_FragStencilRefAMD, then the fixed function value for
124    stencil reference will be used as the fragment's stencil reference value.
125    If a shader statically assignes a value to gl_FragStencilRefAMD, and there
126    is an execution path through the shader that does not set
127    gl_FragStencilRefAMD, then the value of the fragment's stencil reference
128    value may be undefined for executions of the shader that take that path.
129    That is, if the set of linked shaders statically contain a write to
130    gl_FragStencilRefAMD, then it is responsible for always writing it.
131
132    Modify the first paragraph on p.64:
133
134    If a shader executes the discard keyword, the fragment is discarded, and
135    the values of any user-defined fragment outputs, gl_FragDepth, gl_FragColor,
136    gl_FragData, and gl_FragStencilRefAMD become irrelevant.
137
138Additions to the AGL/GLX/WGL Specifications
139
140    None.
141
142GLX Protocol
143
144    None.
145
146Errors
147
148    None.
149
150New State
151
152    None.
153
154New Implementation Dependent State
155
156    None.
157
158Issues
159
160    1) Should gl_FragStencilRefAMD be initialized to the current stencil
161       reference value on input to the fragment shader?
162
163       RESOLVED: No. gl_FragStencilRefAMD is write-only. If the current stencil
164       reference value is required in a shader, the application should place
165       it in a uniform.
166
167    2) Is it possible to output the stencil mask from the shader?
168
169       RESOLVED: No.
170
171    3) Is the global stencil mask still applied?
172
173       RESOLVED: Yes. The mask is global as there is no way to export the
174       stencil mask from the shader.
175
176    4) How is two-sided stencil handled? How do we export front and back
177       stencil references?
178
179       RESOLVED: There is only one export from the shader. However, two sided
180       stencil reference generation may be achived as:
181
182          if (gl_FrontFacing)
183            gl_FragStencilRefAMD = foo;
184          else
185            gl_FragStencilRefAMD = bar;
186
187       If both front and back stencil reference values are needed in a single
188       shader, user defined uniforms may be used.
189
190    5) If the value written to gl_FragStencilRefAMD is outside of the range of
191       values representable by the stencil buffer, what happens?
192
193       RESOLVED: The additional bits are discarded. This is logical as the
194       stencil mask is still applied and its bit-depth is that of the stencil
195       buffer. If clamping is desired, this should be performed in the shader.
196
197Revision History
198
199    Rev.    Date      Author    Changes
200    ----  --------    --------  -----------------------------------------
201
202     5    04/07/2010  gsellers  Remove erroneous language stating that
203                                gl_FragStencilRefAMD is initialized to the fixed
204                                function reference value.
205     4    09/27/2009  gsellers  Update issues 1, 4 and 5.
206     3    07/16/2009  gsellers  Address two-sided stencil references.
207                                Add issues 3, 4 and 5.
208     2    07/14/2009  gsellers  Add AMD suffix to gl_FragStencilRef. Resolve (1)
209     1    07/10/2009  gsellers  Initial draft.