1Name 2 3 EXT_shader_pixel_local_storage2 4 5Name Strings 6 7 GL_EXT_shader_pixel_local_storage2 8 9Contributors 10 11 Jan-Harald Fredriksen, ARM 12 Sandeep Kakarlapudi, ARM 13 James Glanville, Imagination Technologies 14 Tobias Hector, Imagination Technologies 15 16Contact 17 18 Tobias Hector (tobias.hector 'at' imgtec.com) 19 20Status 21 22 Complete 23 24Version 25 26 Revision 0.13 27 Last Modified Date: October 28, 2015 28 29Number 30 31 OpenGL ES Extension #253 32 33Dependencies 34 35 OpenGL ES 3.0 and GLSL ES 3.0 are required. 36 37 EXT_shader_pixel_local_storage is required. 38 39 This extension has interactions with EXT_color_buffer_float and 40 EXT_color_buffer_half_float 41 42 This extension is written against the OpenGL ES Shading Language 43 specification, Language Version 3.00, Document Revision 4 and revision 44 OpenGL ES 3.0.2 of the API specification. 45 46Overview 47 48 This extension builds on EXT_shader_pixel_local_storage by lifting the 49 restriction that pixel local storage is not supported when rendering to 50 multiple draw buffers. 51 52 Moreover, pixel local storage values are no longer lost when writing to 53 user-defined fragment outputs, and, correspondingly, framebuffer pixel 54 values do not always become undefined when the shader writes to pixel local 55 storage. 56 57 This extension adds the following capabilities: 58 - support for pixel local storage in combination with multiple user- 59 defined fragment outputs 60 - support for clearing pixel local storage variables 61 - support for multi-word pixel local storage variables 62 63New Procedures and Functions 64 65 void FramebufferPixelLocalStorageSizeEXT(uint target, sizei size); 66 sizei GetFramebufferPixelLocalStorageSizeEXT(uint target); 67 void ClearPixelLocalStorageuiEXT(sizei offset, sizei n, const uint *values); 68 69New Tokens 70 71 Accepted by the <pname> parameters of GetBooleanv, GetIntegerv, 72 GetInteger64v, or GetFloatv: 73 74 MAX_SHADER_COMBINED_LOCAL_STORAGE_FAST_SIZE_EXT 0x9650 75 MAX_SHADER_COMBINED_LOCAL_STORAGE_SIZE_EXT 0x9651 76 77 Returned by CheckFramebufferStatus: 78 79 FRAMEBUFFER_INCOMPLETE_INSUFFICIENT_SHADER_COMBINED_LOCAL_STORAGE_EXT 0x9652 80 81New Macro Definitions 82 83 #define GL_EXT_shader_pixel_local_storage2 1 84 85New Built-in Variables 86 87 None 88 89Changes to the OpenGL ES 3.0 Specification, Chapter 3 90 91 In Section 3.9.2, at the end of the last sub-section ("Shader Outputs"), 92 modify the three paragraphs added by GL_EXT_shader_pixel_local_storage, 93 such that it reads: 94 95 "Fragment data values may also be written to pixel local storage blocks. 96 These values are available for reading in subsequent shader invocations 97 covering the same pixel. Data values written to pixel local storage block 98 members are converted to the storage format specified in the shader. 99 100 If GL_EXT_shader_pixel_local_storage2 is supported a shader may write 101 to both user-defined fragment outputs and to pixel local storage blocks. 102 103 If GL_EXT_shader_pixel_local_storage2 is not supported and a shader 104 writes to any user-defined fragment output, the pixel local storage values 105 for that fragment are lost, and their values in subsequent shader 106 invocations are undefined. Similarly, if a shader writes to pixel local 107 storage blocks, the value of the framebuffer pixel covered by that fragment 108 becomes undefined." 109 110Changes to the OpenGL ES 3.0 Specification, Chapter 4 111 112 In Section 4.1.7 ("Blending"), modify the paragraph added by GL_EXT_shader- 113 _pixel_local_storage to read: 114 115 "Blending only applies to user-defined fragment outputs. No blending is 116 performed for outputs to pixel local storage blocks. If the fragment 117 shader outputs only to pixel local storage blocks, proceed to the next 118 operation." 119 120 In Section 4.1.9 ("Dithering), modify the paragraph added by GL_EXT_shader- 121 _pixel_local_storage to read: 122 123 "Dithering only applies to user-defined fragment outputs. No dithering 124 is performed on outputs to pixel local storage blocks." 125 126 In Section 4.2.3 ("Clearing the Buffers") add the following: 127 128 "The command 129 130 void ClearPixelLocalStorageuiEXT(sizei offset, sizei n, const uint *values); 131 132 clears a consecutive region of the pixel local storage to a specified set 133 of values. <offset> is the start offset of the region in 32-bit words. <n> 134 is the number of 32-bit words to clear. <values> is an array of <n> 32-bit 135 words that specifies the values the pixel local storage should be cleared 136 to. The words in <n> are packed with the first component in the least 137 significant bits of the word. The most significant bit of each component is 138 packed in the most significant bit location of its location in the word. If 139 <values> is NULL, all pixel local storage in the supplied range has every 140 bit set to 0. 141 142 Clearing the pixel local storage will clear all values stored in the 143 specified range. This will have the effect of making the value of any user- 144 defined fragment output in this range undefined. Applications can determine 145 the fragment output or pixel local storage variables the range 146 corresponds to by the locations declared in the shader and by the storage 147 sizes described in section 4.3.8.2 ("Output Layout Qualifiers") of the 148 OpenGL ES Shading Language Specification. Further, an implementation is 149 required to allocate variables in storage the following order: pixel local 150 variables first, then fragment outputs. 151 152 When ClearPixelLocalStorageuiEXT is called, no per-fragment operations or 153 mask operations are applied. 154 155 An INVALID_VALUE error will be generated if the sum of <offset> and <n> 156 exceeds the total amount pixel local storage available to a shader. An 157 INVALID_OPERATION error will be generated if ClearPixelLocalStorageuiEXT is 158 called while pixel local storage is disabled." 159 160 Replace Section 4.4.3 ("Enabling pixel local storage") with the following: 161 162 "4.4.3 Enabling pixel local storage 163 164 Fragment shaders have access to pixel local storage blocks, but this access 165 must be enabled prior to use and disabled after use. 166 167 Pixel local storage for the current draw framebuffer is enabled by calling 168 Enable with SHADER_PIXEL_LOCAL_STORAGE_EXT. 169 170 The content of the pixel local storage for a pixel is initially undefined. 171 172 The contents of the pixel local storage persist until color data is flushed 173 to the framebuffer. After such an event, data in the pixel local storage 174 is lost and the contents are undefined. Events that cause a flush include: 175 * calling the GL commands Flush, Finish, and ClientWaitSync 176 * calling commands such as TexSubImage2D, CopyTexSubImage2D, and 177 BlitFramebuffer to update a texture that is also attached to the current 178 draw framebuffer while pixel local storage is enabled 179 * disabling pixel local storage by calling Disable with SHADER_PIXEL_- 180 LOCAL_STORAGE_EXT. 181 182 If pixel local storage is not enabled, an INVALID_OPERATION error will be 183 generated if any rendering command is issued while a program object that 184 accesses pixel local storage is bound. 185 186 While pixel local storage is enabled, an INVALID_OPERATION error will be 187 generated if any of the current draw framebuffer's attachment points are 188 modified, including changes to the underlying storage backing of objects 189 attached to these attachment points. An INVALID_OPERATION error will also 190 be generated on attempts to bind a different framebuffer object, to delete 191 the currently bound draw framebuffer, or change color buffer selection via 192 DrawBuffers while pixel local storage is enabled. 193 194 Pixel local storage is not supported in combination with multisample 195 rasterization. Attempting to enable pixel local storage while the value of 196 SAMPLE_BUFFERS is one will generate an INVALID_OPERATION error. 197 198 An INVALID_FRAMEBUFFER_OPERATION error will be generated when attempting to 199 enable pixel local storage while the current draw framebuffer is incomplete. 200 201 The maximum number of bytes of pixel local storage available to a shader is 202 specified by the value of the implementation-dependent constant MAX_- 203 SHADER_PIXEL_LOCAL_STORAGE_SIZE_EXT. A compile-time error will be generated 204 if an attempt is made to utilize more than the space available for pixel 205 local storage variables. An implementation may choose to subdivide the 206 amount of pixel local storage into a region for fast access and a region 207 for normal access. As many pixel local storage variables as possible will 208 be stored, in order of declaration, in the fast region before any variables 209 will be allocated in the normal region. The number of bytes available for 210 fast access is specified by the value of the implementation-dependent 211 constant MAX_SHADER_PIXEL_LOCAL_STORAGE_FAST_SIZE_EXT. This value will 212 always be less than or equal to the total amount of pixel local storage. 213 214 The maximum number of bytes of combined storage per pixel available to a 215 shader is specified by the value of the implementation-dependent constant 216 MAX_SHADER_COMBINED_LOCAL_STORAGE_SIZE_EXT. This value is the combined 217 storage of color attachments and pixel local storage. A compile-time error 218 will be generated if an attempt is made to utilize more than the combined 219 space for local storage. An INVALID_OPERATION error is generated by any 220 command that draws geometry if the combined storage required for the 221 current draw framebuffer and the pixel local storage of the current program 222 is greater than this value. As for the total amount of pixel local storage, 223 an implementation may choose to subdivide the amount of combined storage 224 into a region for fast access and a region for normal access. The number of 225 bytes available for fast access is specified by the value of the 226 implementation-dependent constant MAX_SHADER_COMBINED_LOCAL_STORAGE_FAST_- 227 SIZE_EXT. This value will always be less than or equal to the total amount 228 of combined storage." 229 230 Pixel local storage is disabled by calling Disable with SHADER_PIXEL_- 231 LOCAL_STORAGE_EXT. 232 233 In the initial state, SHADER_PIXEL_LOCAL_STORAGE_EXT is disabled. 234 235 If EXT_shader_pixel_local_storage2 is to be used, then the amount of pixel 236 local storage must be known to the framebuffer before pixel local storage 237 is enabled, similar to a framebuffer attachment. 238 239 The command 240 241 void FramebufferPixelLocalStorageSizeEXT(uint target, sizei size); 242 243 specifies the amount of storage required for pixel local variables whilst 244 SHADER_PIXEL_LOCAL_STORAGE_EXT is enabled. <target> specifies the 245 framebuffer that is modified by this function. <size> determines the size, 246 in bytes, required for pixel local storage. An INVALID_VALUE error is 247 generated if <size> is greater than MAX_SHADER_PIXEL_LOCAL_STORAGE_SIZE_- 248 EXT, or if it is not a multiple of 4. An INVALID_OPERATION error is 249 generated if an application tries to call this function whilst SHADER_- 250 PIXEL_LOCAL_STORAGE_EXT is enabled. 251 252 The amount of storage required for pixel local variables can be 253 determined by the storage sizes described in section 4.3.8.2 ("Output 254 Layout Qualifiers") of the OpenGL ES Shading Language Specification. 255 256 If the default framebuffer is bound to <target>, then calling this 257 function does not affect framebuffer completeness. 258 259 The command 260 261 sizei GetFramebufferPixelLocalStorageSizeEXT(uint target); 262 263 returns the size of pixel local storage previously set on the framebuffer 264 bound to <target> by FramebufferPixelLocalStorageSizeEXT." 265 266 Add the following to the list of framebuffer complete conditions in 267 sub-section "Whole Framebuffer Completeness" in section 4.4.4: 268 269 " - The amount of pixel local storage specified by 270 FramebufferPixelLocalStorageSizeEXT is zero, or the combined size of 271 pixel local storage and fragment outputs is less than MAX_SHADER_- 272 COMBINED_LOCAL_STORAGE_SIZE_EXT. 273 274 { FRAMEBUFFER_INCOMPLETE_INSUFFICIENT_SHADER_COMBINED_LOCAL_STORAGE_EXT }" 275 276 Add the following to the list of functions that can affect framebuffer 277 completeness sub-section "Whole Framebuffer Completeness" in section 4.4.4: 278 279 " - Changing the size of shader pixel local storage with 280 FramebufferPixelLocalStorageSizeEXT." 281 282Errors 283 284 Remove the following error added in EXT_shader_pixel_local_storage: 285 286 INVALID_OPERATION is generated if the application attempts to enable pixel 287 local storage while the current draw framebuffer is a user-defined frame- 288 buffer object and has an image attached to any color attachment other than 289 color attachment zero. 290 291 Add the following errors: 292 293 INVALID_VALUE is generated by ClearPixelLocalStorageuiEXT if the sum of 294 <offset> and <n> exceeds the total amount pixel local storage available to a 295 shader. 296 297 INVALID_OPERATION is generated if ClearPixelLocalStorageuiEXT is called while 298 pixel local storage is disabled. 299 300 INVALID_OPERATION is generated by any command that draws geometry if the 301 combined storage required for the current draw framebuffer and the pixel 302 local storage of the current program is is greater than the value of MAX_- 303 SHADER_COMBINED_LOCAL_STORAGE_SIZE_EXT. 304 305New State 306 307 Add to Table 6.13 Framebuffer (state per framebuffer object) 308 309 State Type Get Command Initial Value Description Sec. 310 --------------- ---- ------------ ------------- ----------- ----- 311 Z+ GetFramebuffer- 0 Amount of pixel 4.4.3 312 PixelLocal- local storage 313 StorageSizeEXT specified for 314 the framebuffer. 315 316New Implementation Dependent State 317 318 Add to Table 6.32 Implementation Dependent Fragment Shader Limits 319 320 State Type Get Command Minimum Value Description Sec. 321 --------------- ---- ------------ ------------- ----------- ----- 322 MAX_SHADER_COMBINED- Z+ GetIntegerv 16 Amount of fast 4.4.3 323 LOCAL_STORAGE_FAST- storage in units 324 _SIZE_EXT of bytes available 325 for per-pixel 326 storage. 327 328 MAX_SHADER_COMBINED- Z+ GetIntegerv 16 Amount of total 4.4.3 329 LOCAL_STORAGE_SIZE- storage in units 330 _EXT of bytes available 331 for per-pixel 332 storage. 333 334Additions to Chapter 4 ("Variables and Types") of the OpenGL ES Shading Language Specification 335 336 Replace section "4.3.7 Pixel Local Variables" with the following: 337 338 "4.3.7 Pixel Local Variables 339 340 The __pixel_localEXT, __pixel_local_inEXT, and __pixel_local_outEXT, 341 qualifiers are used to declare variables whose values are persistent across 342 fragment shader invocations covering the same pixel, collectively referred 343 to as pixel local variables. Pixel local variables do not have any backing 344 store allocated through the OpenGL API and are not accessible to the API. 345 346 Variables declared with the __pixel_localEXT qualifier can be read and 347 written from the same fragment shader invocation. Variables declared with 348 the __pixel_local_inEXT qualifier can only be read. Variables declared 349 with the __pixel_local_outEXT qualifier can only be written. 350 351 Pixel local storage variable reads and writes within a single shader 352 invocation are processed in order. 353 354 It is legal for a shader to write to both user-defined fragment outputs and 355 pixel local storage variables. 356 357 Pixel local storage variables may not have initializers and their contents 358 are undefined until written to from a shader or initialized via the API. If 359 a pixel local storage variable is not written to in a fragment shader, the 360 value of that variable is undefined unless it was declared as part of a 361 __pixel_localEXT block. 362 363 Pixel local storage variables may be qualified with layout qualifiers 364 affecting how the values are stored in and retrieved from the underlying 365 storage, as described in section 4.3.8.4 "Pixel Local Block Layout 366 Qualifiers". 367 368 When reading from a pixel local storage variable, the in-storage value is 369 implicitly converted from the storage format specified by the layout 370 qualifier to the variable type. Similarly, when writing to a pixel local 371 storage variable, the value of the member is implicitly converted to the 372 storage format specified by the layout qualifier. 373 374 Pixel local storage variables may only be declared inside interface blocks 375 (section 4.3.7, "Interface Blocks"), which are then referred to as shader 376 pixel local storage blocks. It is a compile-time error to declare pixel 377 local storage variables at global scope (outside a block). 378 379 Pixel local storage blocks must be declared at global scope. 380 381 Pixel local storage variables declared inside pixel local storage 382 blocks will be laid out in local storage in monotonically increasing order 383 based on their location in the declaration. All pixel local variables 384 consume integer multiples of 4 bytes, as specified in section 4.3.8.4. 385 386 Pixel local storage blocks may be allocated from the same storage as any 387 user-defined color outputs, but do not alias. Writing to pixel local 388 variables has no effect on any user-defined outputs, and pixel local 389 variables are not affected by writes to any user-defined outputs. 390 391 A shader may only declare a single input and a single output pixel local 392 storage block. A pixel local storage block declared using the __pixel_- 393 localEXT qualifier is counted as both an input and an output block. Thus, 394 it is a compile-time error for a shader to declare more than one pixel 395 storage block, with the exception that it is legal to declare one pixel 396 local storage block using the __pixel_local_inEXT qualifier and one with 397 the __pixel_local_outEXT qualifier. 398 399 Modify the start of Section 4.3.7 (Interface Blocks) to read: 400 401 "Uniform and pixel local storage variable declarations can be grouped into 402 named interface blocks to provide coarser granularity backing than is 403 achievable with individual declarations. They can have an optional instance 404 name, used in the shader to reference their members. A uniform block is 405 backed by the application with a buffer object. A block of pixel local 406 storage variables is not backed by any object. 407 408 GLSL ES 3.0 does not support interface blocks for shader inputs or outputs. 409 410 An interface block is started by a uniform or pixel local keyword, followed 411 by a block name, followed by an open curly brace ( { ) as follows: 412 413 interface-block: 414 layout-qualifieropt interface-qualifier block-name { member-list } instance-nameopt; 415 416 interface-qualifier: 417 in 418 out 419 uniform 420 __pixel_localEXT 421 __pixel_local_inEXT 422 __pixel_local_outEXT 423 " 424 425 Modify the sentence: 426 "Repeating the uniform interface qualifier for a member's storage qualifier 427 is optional." 428 To read: 429 "Repeating the uniform, __pixel_localEXT, __pixel_local_inEXT, or 430 __pixel_local_outEXT interface qualifier for a member's storage qualifier 431 is optional." 432 433 Add a new paragraph after the one starting with: 434 "For uniform blocks, the application uses the block name to identify the 435 block." 436 That reads: 437 "For __pixel_localEXT, __pixel_local_inEXT, and __pixel_local_outEXT storage 438 blocks, the block name is not used." 439 440 In section 4.3.8.2, "Output Layout Qualifiers", add the following to the 441 list of layout qualifiers applicable to fragment outputs only: 442 443 layout-qualifier-id 444 float-output-format-qualifier 445 int-output-format-qualifier 446 uint-output-format-qualifier 447 generic-output-format-qualifier 448 449 float-pixel-local-format-qualifier 450 rgb565 451 r8 452 rg8 453 rgb8 454 rgba8 455 srgb8_a8 456 rgb5_a1 457 rgba4 458 rgb10_a2 459 460 [[ Only if EXT_color_buffer_float is supported ]] 461 r32f 462 rg32f 463 r11f_g11f_b10f 464 rgba32f 465 466 [[ Only if EXT_color_buffer_half_float or EXT_color_buffer_float is supported ]] 467 r16f 468 rg16f 469 rgba16f 470 471 [[ Only if EXT_color_buffer_half_float is supported ]] 472 rgb16f 473 474 int-pixel-local-format-qualifier 475 r8i 476 r16i 477 r32i 478 rg8i 479 rg16i 480 rg32i 481 rgba8i 482 rgba16i 483 rgba32i 484 485 uint-pixel-local-format-qualifier 486 r8ui 487 r16ui 488 r32ui 489 rg8ui 490 rg16ui 491 rg32ui 492 rgba8ui 493 rgb10_a2ui 494 rgba16ui 495 rgba32ui 496 497 generic-output-format-qualifier 498 implementation_defined 499 500 Add the following paragraphs to the end of this section: 501 502 "The output format qualifiers are optional and must be enabled by calling 503 504 #extension GL_EXT_shader_pixel_local_storage2: <behavior> 505 506 before use, where <behavior> is as specified in section 3.4. 507 508 Each output-format-qualifier specifies the format which each of the 509 user-defined fragment outputs is stored at the end of shader execution. 510 The values are packed to the specified format and stored as raw bits in 511 fragment output storage. 512 513 By default, the format for each output is set to "implementation_defined", 514 and the underlying implementation will make a decision about how to 515 store it. If any output is set to a format other than implementation_- 516 defined, all formats must be specified. 517 518 The output-format-qualifier format must match the base type and the 519 number of components of the variable declaration. It is a compile-time 520 error to declare a user-defined output variable where the format qualifier 521 does not match the variable type and the number of components. 522 523 If EXT_shader_pixel_local_storage2 is enabled, the format of every 524 user-defined fragment output variable should be specified in order to use 525 pixel local storage blocks. Any outputs set as implementation_defined 526 (the default) behave as if consuming all available local storage, leaving 527 no space for pixel local variables, causing a compile time error if pixel 528 local storage blocks also exist in the shader. 529 530 The specified output-format-qualifier does not need to be constant 531 between shader invocations, but any resolves to the final framebuffer will 532 treat the data as being of the format specified on the active frame- 533 buffer's color attachment rather than the shader defined format. This 534 implies that color attachment values are undefined if the format of the 535 color attachment does not match the format specified in the shader. The 536 number of user-defined outputs and the size specified by their format 537 qualifier must remain consistent between shader invocations, or the values 538 will be undefined. 539 540 Each user-defined fragment output variable uses memory local to the 541 shading processor. Each format takes up a predetermined number of bytes 542 of storage, as specified in the table below. 543 544 |----------------|-------| 545 | Format | Bytes | 546 |----------------|-------| 547 | r8 | 4 | 548 | r8ui | 4 | 549 | r8i | 4 | 550 | r16ui | 4 | 551 | r16i | 4 | 552 | r32ui | 4 | 553 | r32i | 4 | 554 | rg8 | 4 | 555 | rg8ui | 4 | 556 | rg8i | 4 | 557 | rg16ui | 4 | 558 | rg16i | 4 | 559 | rg32ui | 8 | 560 | rg32i | 8 | 561 | rgb8 | 4 | 562 | rgb565 | 4 | 563 | rgba8 | 4 | 564 | srgb8_a8 | 4 | 565 | rgb5_a1 | 4 | 566 | rgba4 | 4 | 567 | rgb10_a2 | 4 | 568 | rgba8ui | 4 | 569 | rgba8i | 4 | 570 | rgb10_a2ui | 4 | 571 | rgba16ui | 8 | 572 | rgba16i | 8 | 573 | rgba32ui | 16 | 574 | rgba32i | 16 | 575 | r32f | 4 | 576 | rg32f | 8 | 577 | r11f_g11f_b10f | 4 | 578 | rgba32f | 16 | 579 | r16f | 4 | 580 | rg16f | 4 | 581 | rgb16f | 8 | 582 | rgba16f | 8 | 583 |----------------|-------| 584 585 The total amount of memory used by a pixel local storage block or a user- 586 defined fragment output can be determined by the size of each variable's 587 format as in the equation below. n is the number of pixel local storage 588 members or output variables in each case. 589 590 n 591 \¯ 592 /_ i = sizeof(format-qualifier) 593 i=0 594 595 The total combined amount of memory used by fragment outputs and pixel 596 local storage can be worked out simply via the following: 597 598 total memory = sizeof(pixel local storage) + sizeof(fragment outputs)" 599 600 The total number of bytes of fragment output local storage available is 601 specified by the value of the implementation-dependent constant 602 gl_MaxShaderCombinedLocalStorageSizeEXT. A compile-time error will be 603 generated if the declared outputs use more storage than this value. 604 605 An implementation may choose to subdivide the amount of local storage into 606 a region for fast access and a region for normal access. As many local 607 variables as possible are allocated into the fast access region before any 608 are allocated into the normal access. Pixel local variables are 609 prioritized and are fully allocated into combined local storage before any 610 fragment output variables are allocated. The number of total bytes 611 available for fast access is specified by the value of the implementation- 612 dependent constant gl_MaxShaderCombinedLocalStorageFastSizeEXT. This value 613 will always be less than or equal to the total amount of combined local 614 storage." 615 616 In Section 4.3.8.4 ("Pixel Local Block Layout Qualifiers"), add the following 617 618 (add the following to the list of layout qualifiers for pixel local storage 619 variables) 620 float-pixel-local-format-qualifier 621 rg32f 622 rgba32f 623 rgba16f 624 625 int-pixel-local-format-qualifier 626 rgba16i 627 r32i 628 rg32i 629 rgba32i 630 631 uint-pixel-local-format-qualifier 632 rg32ui 633 rgba16ui 634 rgba32ui 635 636 (add to the end of the description of the pixel local block layout qualifiers) 637 638 "The size of each pixel local format qualifier is equivalent to that 639 specified for the output format qualifiers in section 4.3.8.2." 640 641Additions to Chapter 6 of the OpenGL ES Shading Language Specification 642 643 In Section 6.4 (Jumps), change the sentence about the discard keyword that 644 currently reads: 645 646 'This keyword causes the fragment to be discarded and no updates to the 647 framebuffer will occur.' 648 649 to: 650 651 'This keyword causes the fragment to be discarded and no updates to the 652 framebuffer or any pixel local storage variables will occur.' 653 654Additions to Chapter 7 of the OpenGL ES Shading Language Specification 655 656 In Section 7.3 (Built-In Constants), add new entries: 657 658 const mediump int gl_MaxShaderCombinedLocalStorageFastSizeEXT = 16 659 const mediump int gl_MaxShaderCombinedLocalStorageSizeEXT = 16 660 661Examples 662 (1) G-buffer creation pass 663 664 #version 300 es 665 #extension GL_EXT_shader_pixel_local_storage2 : enable 666 667 varying vec2 coord; 668 varying vec3 normal; 669 uniform sampler2D albedo_metallicness_texture; 670 uniform sampler2D roughness_texture; 671 672 uniform float roughness; 673 uniform float albedo; 674 uniform vec3 metallicness; 675 676 __pixel_localEXT FragDataLocal { 677 layout (r32f) highp float depth; 678 layout (rgba8ui) highp vec4 normal_roughness; 679 layout (rgba8ui) highp vec4 albedo_metallicness; 680 } gbuf; 681 682 void main() 683 { 684 // Write to pls values 685 gbuf.depth = gl_FragCoord.z; 686 gbuf.normal_roughness = vec4(normal, texture2d(roughness_texture).r); 687 gbuf.albedo_metallicness = texture2d(albedo_metallicness_texture, coord); 688 } 689 690 (2) Light accumulation step (multiple lights can hit the same pixel) 691 692 #version 300 es 693 #extension GL_EXT_shader_pixel_local_storage2 : enable 694 695 uniform vec4 light_position; 696 697 __pixel_localEXT FragDataLocal { 698 layout (r32f) highp float depth; 699 layout (rgba8ui) highp vec4 normal_roughness; 700 layout (rgba8ui) highp vec4 albedo_metallicness; 701 } gbuf; 702 703 layout(location = 0, rgba10_a2) out highp vec4 accumulationBuffer; 704 705 void main() 706 { 707 // Accumulate to the accumulationBuffer, without invalidating the pls data 708 accumulationBuffer = do_lighting(gbuf.depth, gbuf.normal_roughness, gbuf.albedo_metallicness, light_position); 709 } 710 711Issues 712 713 (1) Should there be a way to dumping the PLS contents to memory for 714 debugging purposes? 715 716 RESOLVED: Not in this extension. 717 718 A couple of ways this could be supported: 719 A) Reuse ReadPixels. Allow a new combination of <format> and <type> 720 parameters, say, "SHADER_PIXEL_LOCAL_STORAGE" and UNSIGNED_INT. 721 B) Add a new function, say glReadPixelLocalStorage. This would be 722 as the above, except that the <format> and <type> parameters 723 would be implicit. 724 725 Either approach would probably need a query function to determine 726 the amount of storage used, or a way to specify the amount of storage 727 to retrieve. 728 729 (2) How are local storage values initialized? 730 731 RESOLVED: Using ClearPixelLocalStorageuiEXT. 732 733 EXT_shader_pixel_local_storage stated: 734 "All pixel local storage variables are guaranteed to be zero if 735 all color components of the framebuffer are set to zero." 736 737 But with this extension, color data and pixel local storage are 738 distinct, so while this guarantee could be made, it may not be the 739 most efficient approach. 740 741 This is solved by adding an explicit API: ClearPixelLocalStorageuiEXT. 742 743 (3) Is the proposed resolution to (2) a compatibility break with EXT_- 744 shader_pixel_local_storage? 745 746 RESOLVED: No. 747 748 EXT_shader_pixel_local_storage guaranteed that the pixel local 749 storage was initialized to zero if all color components of the 750 framebuffer were set to zero. Given that this only applied to the 751 aliased pixel local storage in the original extension, and aliasing 752 is no longer present, the resolution is not a compatibility break, 753 as the spec itself is a compatibility break. 754 755 (4) Do we need to know the render target count at compile time? 756 757 RESOLVED. 758 759 Yes. Implementations will need to know the render target count and 760 the storage size of each render target in order to allocate and 761 partition the pixel local storage. 762 763 (5) Do we want to explicitly alias some pixel local storage variables onto 764 color rendertargets? 765 766 RESOLVED. 767 768 See Issue 7. 769 770 (6) Should the maximum PLS storage queries be per framebuffer? 771 772 RESOLVED: No - glGetInteger with a MAX_COMBINED_LOCAL_STORAGE_SIZE. 773 774 Dynamic, per framebuffer, queries will have all necessary information, 775 but applications can not access this information until the framebuffer 776 object has been created, which seems undesirable. 777 778 EXT_shader_pixel_local_storage specified static queries for the 779 amount of available pixel local storage. With this extension, the 780 semantics of that query changes since color and pixel local storage 781 no longer alias. Given that change, we need a query for the 782 total amount of storage available for pixel local storage and color 783 attachments. 784 785 (7) Do we want to keep the aliasing of pixel local storage variables onto 786 color rendertargets? 787 788 RESOLVED: No 789 790 The main benefit of aliasing was that it potentially allows more (fast) 791 local storage. Instead of sharing the local storage between color 792 render targets and pixel local storage variables, all local storage can 793 be allocated to pixel local storage initially. In this case, we expect 794 all pixel local storage to be resolved (and become undefined) when any 795 user-defined color output is written to (and vice versa). 796 797 However, given the existance (and support) of framebuffer fetch, it 798 seems unnecessary to continue using this - the same effect can be 799 achieved with side-by-side framebuffer fetch and pixel local storage, 800 without the drawback of requiring explicit resolves. 801 802 (8) Do we want the full range of framebuffer formats to work with this 803 extension? If so, how do we define the sizes of, say rgb565? Does it 804 take up 16bits or is it assumed to be padded to 32 bits? 805 806 RESOLVED: Add all formats, but storage for all formats is padded 807 to multiples of 32-bits. 808 809 (9) Do the usual per-fragment operations apply to color outputs in this 810 extension? 811 812 RESOLVED: Yes. All values written to user-defined color outputs pass 813 through per-fragment operations (including blending, alpha to coverage, 814 etc.) as normal. 815 816Revision History 817 818 Revision 0.13, 28/10/2015 (Tobias Hector) 819 Added enumerant values 820 821 Revision 0.12, 08/10/2015 (Tobias Hector) 822 Added PLS interactions with the discard keyword. 823 824 Revision 0.11, 07/10/2015 (Tobias Hector) 825 Specified that PLS variables are undefined if they're not written to, 826 unless they were defined as both input and output (in which case they 827 are preserved). 828 829 Revision 0.10, 13/07/2015 (Tobias Hector) 830 Re-added error about multisampled rendering 831 832 Revision 0.9, 10/07/2015 (Tobias Hector) 833 Corrected ClearPixelLocalStorageuiEXT to accept a uint value, instead of int 834 Changed language about combined local storage to be clearer. 835 836 Revision 0.8, 03/07/2015 (Tobias Hector) 837 Added wording that disallows the default framebuffer becoming incomplete. 838 Added language allowing NULL to be passed into ClearPixelLocalStorageuiEXT 839 Added word alignment to size parameter of FramebufferPixelLocalStorageSizeEXT 840 841 Revision 0.7, 02/07/2015 (Tobias Hector) 842 Folded in updates from external review. 843 Added interactions with EXT_color_buffer_float and half_float 844 Added multi-word pixel local storage formats 845 Added framebuffer pixel local storage size specification 846 Added framebuffer completeness checks 847 Updated issues list to match updated spec. 848 849 Revision 0.6, 03/10/2014 (Jan-Harald Fredriksen) 850 Extended padding for all color outputs to 4 bytes. 851 Resolved and updated proposed resolutions for several issues. 852 Added Issue 10 and Issue 11. 853 854 Revision 0.5, 25/09/2014 (Jan-Harald Fredriksen) 855 Integrated a subset of IMG_fragment_output_format. 856 857 Revision 0.4, 20/06/2014 (Jan-Harald Fredriksen) 858 Minor wording changes. 859 860 Revision 0.3, 27/05/2014 (Jan-Harald Fredriksen) 861 Adding Issue 7. 862 863 Revision 0.2, 18/05/2014 (Jan-Harald Fredriksen) 864 Adding some issues and a new query. 865 866 Revision 0.1, 21/03/2014 (Jan-Harald Fredriksen) 867 Second internal draft. 868 Adding missing changes compared to EXT_shader_pixel_local_storage. 869 Added proposed resolution of Issue 1. 870 Added Issue 2, Issue 3, and Issue 4. 871 872 Revision 0, 19/11/2013 (Jan-Harald Fredriksen) 873 First internal draft. 874