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