• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1Name
2
3    ARM_shader_framebuffer_fetch
4
5Name Strings
6
7    GL_ARM_shader_framebuffer_fetch
8
9Contributors
10
11    Aske Simon Christensen
12    Sandeep Kakarlapudi
13
14Contact
15
16    Jan-Harald Fredriksen (jan-harald.fredriksen 'at' arm.com)
17
18Status
19
20    Shipping.
21
22Version
23
24    Revision 12
25    Last Modified Date: November 25, 2013
26
27Number
28
29    OpenGL ES Extension #165
30
31Dependencies
32
33    OpenGL ES 2.0 or higher is required.
34
35    ESSL 1.00 or higher is required.
36
37    This extension is written against the OpenGL ES Shading Language
38    specification, Language Version 1.00, Document Revision 17 and revision
39    OpenGL ES 2.0.25 of the API specification.
40
41Overview
42
43    This extension enables fragment shaders to read existing framebuffer
44    data as input. This permits use-cases such as programmable blending,
45    and other operations that may not be possible to implement with
46    fixed-function blending.
47
48    This extension also adds the ability to indicate that a shader should
49    be run once per sample instead of once per pixel.
50
51    Reading framebuffer data as input in combination with multiple render
52    targets (MRT) may not be supported by all implementations. This
53    extension allows applications to query for this capability.
54
55New Procedures and Functions
56
57    None
58
59New Tokens
60
61    Accepted by the <cap> parameter of Enable, Disable, and IsEnabled,
62    and by the <pname> parameter of GetBooleanv, GetIntegerv, and GetFloatv:
63        FETCH_PER_SAMPLE_ARM                                0x8F65
64
65    Accepted by the <pname> parameter of GetBooleanv, GetIntegerv, and
66    GetFloatv:
67        FRAGMENT_SHADER_FRAMEBUFFER_FETCH_MRT_ARM           0x8F66
68
69New Macro Definitions
70
71    #define GL_ARM_shader_framebuffer_fetch 1
72
73New Built-in Variables
74
75    mediump vec4 gl_LastFragColorARM
76
77Changes to the OpenGL ES 2.0.25 Specification, Chapter 3
78
79    Remove the last sentence of Paragraph 2 of Chapter 3.8.1, page 86 ("These
80    built-in varying variables include [...]" and add:
81
82    "These built-in varying variables include the fragment's position, eye z
83    coordinate, and front-facing flag, as well as the current color value in the
84    framebuffer.
85
86    When reading the current color value from the framebuffer, the values
87    associated with the image attached to color attachment point 0 are returned.
88
89    Reading the current color value from the framebuffer may not be supported on
90    all hardware if more than one color attachment has an image attached. This
91    capability can be determined by calling GetBooleanv with the symbolic
92    constant FRAGMENT_SHADER_FRAMEBUFFER_FETCH_MRT_ARM. If FALSE is returned,
93    shaders that read the current value from the framebuffer when more than one
94    color attachment point has an image attached produce undefined results.
95
96    Reading the current color value from the framebuffer is only supported for
97    fixed-point color components. Undefined results are produced if a shader
98    reads from gl_LastFragColorARM while either no image is attached to color
99    attachment 0 or the image attached to color attachment point 0 has a format
100    that is not unsigned normalized fixed-point. No error is generated in this
101    case.
102
103    Add to Chapter 3.2 Multisampling:
104
105    "Per-sample fetch can be used to specify that reads of current values from
106    the framebuffer, colors and other associated data, including varying
107    interpolation, should be evaluated for each sample. Per-sample fetch
108    is controlled by by calling Enable or Disable with the symbolic constant
109    FETCH_PER_SAMPLE_ARM.
110
111    If SAMPLE_BUFFERS is not one, or the fragment shader does not statically
112    access current values from the framebuffer, per-sample fetch has no effect."
113
114Additions to Chapter 3 of the OpenGL ES Shading Language Specification
115
116    Remove Paragraph 2 of section 3.8, page 17, Identifiers ("Identifiers
117    starting with "gl_" are reserved [...]") and add:
118
119    "Identifiers starting with "gl_" are reserved for use by OpenGL ES, and
120    may not be declared in a shader as either a variable or a function.
121    However, as noted in the specification, certain predeclared "gl_" names
122    are allowed to be redeclared in a shader for the specific purpose of
123    changing their precision qualifier."
124
125Additions to Chapter 7 of the OpenGL ES Shading Language Specification
126
127    In section 7.2 (Fragment Shader Special Variables), after the
128    8th paragraph ("If the shader executes the discard keyword,") and before
129    the paragraph on about gl_FragCoord, add:
130
131        "The fragment shader has access to the read-only built-in
132        variable gl_LastFragColorARM. The value of this variable is the
133        color of the pixel to which the current fragment is destined, i.e.,
134        the color that will be used as the destination color during blending,
135        for draw buffer 0.
136
137        If the current render target is multisampled, and the destination
138        pixel thus contains more than one sample per fragment, the value of
139        gl_LastFragColorARM is an implementation-dependent combination of the
140        samples within the destination pixel that are covered by the current
141        fragment. The value will be between the minium and maximum value of the
142        samples in the pixel.
143
144        If the current GL state would cause the destination color to be
145        converted from sRGB to linear at input to blending, then the color read
146        from the framebuffer is converted from sRGB to linear before going into
147        gl_LastFragColorARM. If the destination pixel contains more than one
148        sample, this conversion is applied to each color sample prior to the
149        averaging.
150
151        If no samples within the destination pixel are covered by the current
152        fragment, the value of gl_LastFragColorARM is undefined.
153
154        If more than one color attachment has an image attached, reads from
155        gl_LastFragColorARM, may produce undefined results. This is, however,
156        not an error. See section 3.8.1 "Shader Variables" of the OpenGL ES
157        2.0.25 Graphics System Specification for more details.
158
159        gl_LastFragColorARM is declared with a default precision qualifier.
160        This can be changed by redeclaring the variable with the desired
161        precision qualifier. Redeclarations must be at global scope and must
162        not otherwise alter the declared type of the variable.
163
164        Reads from gl_LastFragColorARM must wait for the processing of all
165        previous fragments destined for the current pixel to complete. For best
166        performance, it is therefore recommended that reads from this built-in
167        variable is done as late in the execution of the fragment shader as
168        possible.
169
170        Access to gl_LastFragColorARM is optional, and must be enabled by:
171
172        #extension GL_ARM_shader_framebuffer_fetch : <behavior>
173
174        Where <behavior> is as specified in section 3.4."
175
176    In section 7.2 (Fragment Shader Special Variables), at the end of
177    the list of built-in variables, add:
178
179        "mediump vec4 gl_LastFragColorARM"
180
181Errors
182
183    None
184
185New State
186
187    Add to table 6.6 (Multisampling):
188
189    Get Value                       Get Command    Type    Initial Value    Description
190    ---------                       -----------    ----    -------------    ---------
191    FETCH_PER_SAMPLE_ARM            IsEnabled      B       FALSE            Per-sample fetch enabled
192
193New Implementation Dependent State
194
195    Add to table 6.19 (Implementation Dependent Values (cont.)):
196
197    Get Value                                  Type  Get Command  Minimum Value  Description        Section
198    ---------                                  ----  -----------  -------------  --------------     -------
199    FRAGMENT_SHADER_FRAMEBUFFER_FETCH_MRT_ARM  B     GetBooleanv  -              Reading existing   3.8.1
200                                                                                 framebuffer color data
201                                                                                 from a fragment
202                                                                                 shader when more than
203                                                                                 one color attachment
204                                                                                 point has an image attached
205                                                                                 gives defined results.
206
207Issues
208
209    (1) What should the built-in variables be called?
210
211        RESOLVED.
212
213        In the current implementation, it is called gl_FBColor, but
214        since we need to change that anyway for the public version (to
215        add the ARM suffix), we could change the name completely if we
216        come up with something better.
217
218        The current proposal is to use gl_LastFragColorARM as in
219        NV_shader_framebuffer_fetch with an added extension post-fix.
220        This could then be extended to include
221        gl_LastFragDataARM[gl_MaxDrawBuffers] as in EXT_framebuffer_fetch in a
222        future extension.
223
224    (2) What should the precision of gl_LastFragColorARM be?
225
226        RESOLVED.
227
228        Is it usually appropriate for the variable to be mediump (or
229        perhaps lowp), but that precludes the mechanism from being
230        used effectively with float32 render targets. float32 render targets
231        are not required in either OpenGL ES 2.0 or OpenGL ES 3.0.
232
233        gl_LastFragColor is currently defined as mediump by default, but the
234        precision can be redeclared in the shader in the same manner as in
235        EXT_shader_framebuffer_fetch.
236
237    (3) What should the precision of gl_LastFragDepthARM be?
238
239        RESOLVED.
240
241        No longer relevant for this extension as the depth buffer support
242        has been split out to a separate extension.
243
244    (4) Which framebuffer formats are supported?
245
246        RESOLVED.
247
248        All UNORM formats are supported. No other formats are supported.
249
250        Since gl_LastFragColor is a built-in variable, with a given
251        type, other types are not trivial to add.
252
253    (5) Should there be a query for the valid framebuffer formats?
254
255        RESOLVED.
256
257        If only some formats are supported, the application needs some
258        way to determine which formats are supported and which are not.
259
260        Alternatives:
261          A) Specify the exact set of formats in the extension.
262          B) Add a query, for example something based on the internal format
263             queries in OpenGL ES 3.0.
264
265        Given the resolution of Issue 4, alternative A is effectively
266        chosen.
267
268    (6) What performance recommendations should the extension contain?
269
270        RESOLVED.
271
272        There is currently a recommendation to place the framebuffer
273        read as late as possible in the shader.
274
275    (7) Should gl_LastFragStencil and gl_LastFragDepth be split into
276        separate extensions?
277
278        RESOLVED.
279
280        Yes. This is is now added by ARM_shader_framebuffer_fetch_depth_stencil.
281
282    (8) Should shaders that read the current fragment color, depth, or stencil
283        be run per-sample?
284
285        RESOLVED.
286
287        The EXT_framebuffer_fetch extension automatically runs the parts of the
288        shader that depend on gl_LastFragData per sample if this variable is
289        read. In some use-cases (e.g., tone-mapping), this is important to
290        avoid shader aliasing. This approach is, however, not possible to
291        implement on all hardware.
292
293        An alternative is to allow the application to control the shader
294        iteration rate. This could be done similarly to the API part of
295        ARB_sample_shading.
296
297        The latter approach is taken by this extension.
298
299    (9) Should the value read back include only the samples covered by the
300        current fragment?
301
302        RESOLVED.
303
304        Yes, only the samples covered by the current fragment will be read back.
305
306        The alternative would be to ignore the coverage mask when returning the
307        value, but this seems less desirable.
308
309        If the shader is run per sample (see Issue 8) both options would
310        give the same result.
311
312    (10)How is this different from EXT_shader_framebuffer_fetch?
313
314        RESOLVED.
315
316        The core functionality is the same, that is, fragment shaders may read
317        existing framebuffer data as input.
318
319        The two main differences are:
320         * This extension places the mechanism for running the shader per sample
321           under application control. It is not possible to run only those parts
322           of the shader that depend on the current framebuffer color per
323           sample.
324         * This extension may not be compatible with multiple render targets on
325           all hardware.
326
327    (11) What is meant by undefined results in this extension?
328
329        RESOLVED.
330
331        Reads from gl_LastFragColorARM may return undefined results in some
332        cases as described in the text. This means that there is no guarantees
333        on the exact value returned in these cases. The values will typically
334        be a GPU specific 'default' value, or correspond to the API clear value.
335        It is guaranteed that these values will never originate from other GL
336        contexts or applications.
337
338Revision History
339
340    Revision 12, 25/11/2013 (Jan-Harald Fredriksen)
341        Added and resolved issue 11.
342
343    Revision 11, 26/09/2013 (Jan-Harald Fredriksen)
344        Restricting redeclarations of built-in variables to global scope.
345
346    Revision 10, 15/07/2013 (Jan-Harald Fredriksen)
347        Minor clarification.
348
349    Revision 9, 10/07/2013 (Jan-Harald Fredriksen)
350        Renaming SAMPLE_SHADING_ARM to FETCH_PER_SAMPLE_ARM and restricting it
351        to shaders that use fetch to avoid confusion with possible per per-
352        sample shading extensions in the future.
353
354    Revision 8, 02/05/2013 (Jan-Harald Fredriksen)
355        Separated out depth and stencil functionality.
356        Changing MRT interactions to depend on the number of color attachments
357        that have images attached to them.
358        Removing error condition when reading from non-fixed-point color
359        attachments.
360
361    Revision 7, 19/04/2013 (Jan-Harald Fredriksen)
362        Language clarifications.
363
364    Revision 6, 12/04/2013 (Jan-Harald Fredriksen)
365        Removing explicit references to specific GPUs.
366        Resolved issues 4 and 5.
367
368    Revision 5, 11/04/2013 (Jan-Harald Fredriksen)
369        Allowing the new built-in variables to be redeclared for purposes of
370        redefining their precision qualifier.
371
372    Revision 4, 10/04/2013 (Jan-Harald Fredriksen)
373        Adding FRAGMENT_SHADER_FRAMEBUFFER_FETCH_DRAW_BUFFERS_ARM.
374        Clarifying ESSL language about how reads are done when multisampling is
375        enabled.
376
377    Revision 3, 09/04/2013 (Jan-Harald Fredriksen)
378        Tentatively resolved issue 8 and 9. Added issue 10.
379
380    Revision 2, 08/10/2012 (Jan-Harald Fredriksen)
381        Added issue 9.
382
383    Revision 1, 22/07/2012 (Jan-Harald Fredriksen)
384        First draft based on ARM_framebuffer_read.
385