1Name 2 3 EXT_shader_pixel_local_storage 4 5Name Strings 6 7 GL_EXT_shader_pixel_local_storage 8 9Contributors 10 11 Jan-Harald Fredriksen, ARM 12 Sandeep Kakarlapudi, ARM 13 Marius Bjorge, ARM 14 Alexander Galazin, ARM 15 Tobias Hector, Imagination Technologies 16 Ilya Zaytsev, ARM 17 18Contact 19 20 Jan-Harald Fredriksen (jan-harald.fredriksen 'at' arm.com) 21 22Status 23 24 Shipping. 25 26Version 27 28 Revision 6 29 Last Modified Date: Mar 12, 2014 30 31Number 32 33 OpenGL ES Extension #167 34 35Dependencies 36 37 OpenGL ES 3.0 is required. 38 39 This extension is written against the OpenGL ES Shading Language 40 specification, Language Version 3.00, Document Revision 3 and revision 41 OpenGL ES 3.0 of the API specification. 42 43Overview 44 45 Techniques such as deferred shading and deferred lighting are often 46 implemented by attaching multiple color render targets to a framebuffer 47 object, rendering the required intermediate data, and then sampling from 48 this data as textures. While flexible, this approach consumes a large 49 amount of external memory bandwidth, which is at a premium on mobile 50 devices. 51 52 Observing that the intermediate or "G-buffer" data is often only written to 53 and read by shaders executing for the same pixel position, tile-based 54 renderers can offer a more efficient alternative by keeping the data on-GPU. 55 This allows large amounts of data to be kept per-pixel, with zero external 56 memory bandwidth impact. 57 58 This extension provides a way for applications to pass information between 59 fragment shader invocations covering the same pixel by introducing the 60 concept of pixel local storage. Pixel local storage is an on-chip memory 61 storage that can be efficiently accessed by fragments being processed by 62 the GL. The format of data stored in the pixel local storage is independent 63 of the format of the currently attached framebuffer. The data in pixel local 64 storage is not written back to main memory. Access to pixel local storage 65 is controlled via glEnable and glDisable. If commands that implicitly or 66 explicitly flush the GL command stream are issued when pixel local storage 67 is enabled then the contents of the pixel local storage becomes undefined 68 for subsequent commands. 69 70New Procedures and Functions 71 72 None 73 74New Tokens 75 76 Accepted by the <pname> parameters of GetBooleanv, GetIntegerv, 77 GetInteger64v, or GetFloatv: 78 79 MAX_SHADER_PIXEL_LOCAL_STORAGE_FAST_SIZE_EXT 0x8F63 80 MAX_SHADER_PIXEL_LOCAL_STORAGE_SIZE_EXT 0x8F67 81 82 Accepted by the <pname> parameters of IsEnabled, GetBooleanv, GetIntegerv, 83 GetInteger64v, or GetFloatv: 84 85 SHADER_PIXEL_LOCAL_STORAGE_EXT 0x8F64 86 87New Macro Definitions 88 89 #define GL_EXT_shader_pixel_local_storage 1 90 91Additions to Chapter 4 of the OpenGL ES Shading Language Specification 92 93 In Section 4.3 (Storage Qualifiers), add a qualifiers to the table: 94 95 "Qualifier Meaning 96 -------- ------- 97 __pixel_localEXT fragment shader only; storage can be read and written 98 and is persistent across shader invocations covering 99 the same pixel 100 101 __pixel_local_inEXT fragment shader only; storage can be read and is 102 persistent across shader invocations covering the same 103 pixel; storage can be written in another shader 104 invocation declaring __pixel_localEXT or __pixel_- 105 local_outEXT storage. 106 107 __pixel_local_outEXT fragment shader only; storage can be written and is 108 persistent across shader invocations covering the same 109 pixel; storage is read in another shader invocation 110 declaring __pixel_localEXT or __pixel_local_inEXT 111 storage. 112 " 113 114 Then add a new paragraph at the end of the section: 115 "The __pixel_localEXT, __pixel_local_inEXT, and __pixel_local_outEXT 116 qualifiers are optional and must be enabled by calling 117 118 #extension GL_EXT_shader_pixel_local_storage : <behavior> 119 120 before use, where <behavior> is as specified in section 3.4." 121 122 After Section 4.3.6 (Output Variables), add a new paragraph: 123 124 "4.3.7 Pixel Local Variables 125 126 The __pixel_localEXT, __pixel_local_inEXT, and __pixel_local_outEXT 127 qualifiers are used to declare variables whose values are persistent across 128 fragment shader invocations covering the same pixel, collectively referred 129 to as pixel storage variables. Pixel local storage variables do not have any 130 backing store allocated through the OpenGL API and are not accessible to the 131 API. 132 133 Variables declared with the __pixel_localEXT qualifier can be read and 134 written from the same fragment shader invocation. Variables declared with 135 the __pixel_local_inEXT and __pixel_local_outEXT qualifiers can only be read 136 and written, respectively. 137 138 Pixel local storage variable reads and writes within a single shader 139 invocation are processed in order. 140 141 It is a compile-time error for a shader to statically write to both regular 142 user-defined fragment outputs and to pixel local storage variables. Reading 143 from pixel local storage variables and writing to user-defined fragment 144 outputs is, however, legal. 145 146 Pixel local storage variables may not have initializers and their contents 147 are undefined until written to from a shader. 148 149 Pixel local storage variables may be qualified with layout qualifiers 150 affecting how the values are stored in and retrieved from the underlying 151 storage, as described in section 4.3.8.4 "Pixel Local Block Layout 152 Qualifiers". 153 154 When reading from a pixel local storage variable, the in-storage value is 155 implicitly converted from the storage format specified by the layout 156 qualifier to the variable type. Similarly, when writing to a pixel local 157 storage variable, the value of the member is implicitly converted to the 158 storage format specified by the layout qualifier. 159 160 Pixel local storage variables may only be declared inside interface blocks 161 (section 4.3.7, "Interface Blocks"), which are then referred to as shader 162 pixel local storage blocks. It is a compile-time error to declare pixel 163 local storage variables at global scope (outside a block). 164 165 Pixel local storage blocks must be declared at global scope. 166 167 Pixel local storage variables declared inside pixel local storage 168 blocks will be laid out in local storage in monotonically increasing order 169 based on their location in the declaration. All pixel local storage 170 variables consume exactly 4 bytes of storage. 171 172 A shader may only declare a single input and a single output pixel local 173 storage block. A pixel local storage block declared using the __pixel_- 174 localEXT qualifier is counted as both an input and an output block. Thus, 175 it is a compile-time error for a shader to declare more than one pixel 176 storage block, with the exception that it is legal to declare one pixel 177 local storage block using the __pixel_local_inEXT qualifier and one with 178 the __pixel_local_outEXT qualifier. 179 180 Modify the start of Section 4.3.7 (Interface Blocks) to read: 181 182 "Uniform and pixel local storage variable declarations can be grouped into 183 named interface blocks to provide coarser granularity backing than is 184 achievable with individual declarations. They can have an optional instance 185 name, used in the shader to reference their members. A uniform block is 186 backed by the application with a buffer object. A block of pixel local 187 storage variables is not backed by any object. 188 189 GLSL ES 3.0 does not support interface blocks for shader inputs or outputs. 190 191 An interface block is started by a uniform or pixel local keyword, followed 192 by a block name, followed by an open curly brace ( { ) as follows: 193 194 interface-block: 195 layout-qualifieropt interface-qualifier block-name { member-list } instance-nameopt; 196 197 interface-qualifier: 198 in 199 out 200 uniform 201 __pixel_localEXT 202 __pixel_local_inEXT 203 __pixel_local_outEXT 204 " 205 206 Modify the sentence: 207 "Repeating the uniform interface qualifier for a member's storage qualifier 208 is optional." 209 To read: 210 "Repeating the uniform, __pixel_localEXT, __pixel_local_inEXT, or 211 __pixel_local_outEXT interface qualifier for a member's storage qualifier 212 is optional." 213 214 Add a new paragraph after the one starting with: 215 "For uniform blocks, the application uses the block name to identify the 216 block." 217 That reads: 218 "For __pixel_localEXT, __pixel_local_inEXT, and __pixel_local_outEXT storage 219 blocks, the block name is not used." 220 221 Modify the first paragraph of 4.3.8 (Layout Qualifiers) to read: 222 223 "Layout qualifiers can appear in several forms of declaration. They can 224 appear as part of an interface block definition or block member, as shown 225 in the grammar in the previous section. They can also appear with just an 226 interface qualifier (a storage qualifier that is in, out, uniform, 227 __pixel_localEXT, __pixel_local_inEXT, or __pixel_local_outEXT) to 228 establish layouts of other declarations made with that interface qualifier: 229 230 layout-qualifier interface-qualifier ; 231 " 232 233 Then remove paragraph starting with "Interface qualifiers are a subset of 234 storage qualifiers:" and the subsequent grammar for the interface-qualifier. 235 This is now described in section 4.3.7. 236 237 Add a new paragraph: 238 " 239 4.3.8.4 Pixel Local Block Layout Qualifiers 240 241 Layout qualifiers can be used for pixel local storage variables. The layout 242 qualifier identifiers for pixel local storage variables are: 243 244 layout-qualifier-id 245 float-pixel-local-format-qualifier 246 int-pixel-local-format-qualifier 247 uint-pixel-local-format-qualifier 248 249 float-pixel-local-format-qualifier 250 r11f_g11f_b10f 251 r32f 252 rg16f 253 rgb10_a2 254 rgba8 255 rg16 256 int-pixel-local-format-qualifier 257 rgba8i 258 rg16i 259 uint-pixel-local-format-qualifier 260 rgb10_a2ui 261 rgba8ui 262 rg16ui 263 r32ui 264 265 None of these have any semantic affect at all on the usage of the variables 266 being declared; they only describe how data is laid out in the underlying 267 storage. 268 269 The component format must match the base type and the number of components 270 of member declarations. It is a compile-time error to declare a pixel local 271 member where the format qualifier does not match the member type and the 272 number of components. 273 274 Pixel local storage layout qualifiers can be declared for global scope, on 275 a single pixel local storage block, or on a single pixel local storage block 276 member declaration. 277 278 Default layouts are established at global scope for pixel local storage 279 blocks as 280 281 layout(layout-qualifier-id-list) __pixel_localEXT; 282 layout(layout-qualifier-id-list) __pixel_local_inEXT; 283 layout(layout-qualifier-id-list) __pixel_local_outEXT; 284 285 The initial state of compilation is as if the following were declared: 286 287 layout(r32ui) __pixel_localEXT; 288 layout(r32ui) __pixel_local_inEXT; 289 layout(r32ui) __pixel_local_outEXT; 290 291 Pixel local storage blocks can be declared with optional layout qualifiers, 292 and so can their individual member declarations. Such block layout 293 qualification is scoped only to the content of the block. As with global 294 layout declarations, block layout qualification first inherits from 295 the current default qualification and then overrides it. Similarly, 296 individual member layout qualification is scoped just to the member 297 declaration, and inherits from and overrides the block's qualification. 298 299 The float-pixel-local-format-qualifier, the int-pixel-local-format- 300 qualifier, and the uint-pixel-local-format-qualifier overrides any previous 301 any previous use of any of these qualifiers; other qualifiers are inherited. 302 303 When multiple arguments are listed in a layout declaration, the effect will 304 be the same as if they were declared one at a time, in order from left to 305 right, each in turn inheriting from and overriding the result from the 306 previous qualification. 307 308 Example with per-member qualifiers: 309 310 __pixel_localEXT FragDataLocal { 311 layout(r11f_g11f_b10f) mediump vec3 normal; 312 layout(rgb10_a2ui) mediump uvec4 color; 313 layout(r32ui) highp uint flags; 314 }; 315 316 Example with inherited qualifiers: 317 318 layout(rgba8ui) __pixel_localEXT FragDataLocal { 319 layout(rgb10_a2, r11f_g11f_b10f) mediump vec3 normal; // storage is r11f_g11f_b10f 320 layout(rgb10_a2ui) mediump uvec4 color; 321 mediump uvec4 flags; // storage is rgba8ui 322 }; 323 324 Example of invalid local block declaration: 325 326 layout(rgba8ui) __pixel_localEXT FragDataLocal { 327 layout(r11f_g11f_b10f) mediump float normal; // error, component counts must match 328 layout(rgb10_a2ui) mediump vec4 color; // error, base types must match 329 }; 330 " 331 332Additions to Chapter 7 of the OpenGL ES Shading Language Specification 333 334 In Section 7.3 (Built-In Constants), add a new entry: 335 336 const mediump int gl_MaxShaderPixelLocalStorageFastSizeEXT = 16 337 const mediump int gl_MaxShaderPixelLocalStorageSizeEXT = 16 338 339Changes to the OpenGL ES 3.0 Specification, Chapter 3 340 341 In Section 3.9, at the end of the last sub-section ("Shader Outputs") add: 342 343 "Fragment data values may also be written to pixel local storage blocks. 344 These values are available for reading in subsequent shader invocations 345 covering the same pixel. Data values written to pixel local storage block 346 members are converted to the storage format specified in the shader. 347 348 If a shader writes to any user-defined fragment output, the pixel local 349 storage values for that fragment are lost, and their values in subsequent 350 shader invocations are undefined. 351 352 Similarly, if a shader writes to pixel local storage blocks, the value of 353 the framebuffer pixel covered by that fragment becomes undefined." 354 355Changes to the OpenGL ES 3.0 Specification, Chapter 4 356 357 In Section 4.1.7 ("Blending"), add after the fourth paragraph ("Blending 358 applies only if ..."): 359 360 "Blending only applies for user-defined fragment outputs. If the fragment 361 shader outputs to pixel local storage blocks, proceed to the next 362 operation." 363 364 In Section 4.1.9 ("Dithering), add after the second paragraph ("Many 365 dithering selection ..."): 366 367 "If the fragment shader outputs to pixel local storage blocks, no dithering 368 is performed." 369 370 In Section 4.4 ("Framebuffer Objects") modify the sentence: 371 372 "In particular, a framebuffer object encapsulates state necessary to 373 describe a collection of color, depth, and stencil logical buffers (other 374 types of buffers are not allowed)." 375 376 to read: 377 "In particular, a framebuffer object encapsulates state necessary to 378 describe a collection of color, depth, and stencil logical buffers (other 379 types of buffers cannot be attached)." 380 381 Then add the following paragraph to the end of the Section (before 4.4.1): 382 383 "A set of pixel local storage values may also be associated with the 384 framebuffer. These values are not backed by any framebuffer-attachable 385 image. This allows the GL to pass information between fragment shader 386 invocations covering the same pixel without requiring an attached object 387 to provide the underlying storage backing. The pixel local storage is only 388 valid while it is enabled as described in section 4.4.3." 389 390 Add a new section after 4.4.2 "Attaching Images to Framebuffer Objects" and 391 increase the section number for the the following subsections: 392 393 "4.4.3 Enabling pixel local storage 394 395 Fragment shaders have access to pixel local storage blocks, but this access 396 must be enabled prior to use and disabled after use. 397 398 Pixel local storage for the current draw framebuffer is enabled by calling 399 Enable with SHADER_PIXEL_LOCAL_STORAGE_EXT. 400 401 The contents of the pixel local storage for a pixel are initially an 402 implementation-defined function of the current value of the pixel in the 403 framebuffer. All pixel local storage variables are guaranteed to be zero if 404 all color components of the framebuffer are set to zero. 405 406 The contents of the pixel local storage persist until color data is flushed 407 to the framebuffer. After such an event, data in the pixel local storage 408 is lost and the contents are undefined. Events that cause a flush include: 409 * calling the GL commands Flush, Finish, and ClientWaitSync 410 * calling commands such as TexSubImage2D, CopyTexSubImage2D, and 411 BlitFramebuffer to update a texture that is also attached to the current 412 draw framebuffer while pixel local storage is enabled 413 * disabling pixel local storage by calling Disable with SHADER_PIXEL_- 414 LOCAL_STORAGE_EXT. 415 416 If pixel local storage is not enabled, an INVALID_OPERATION error will be 417 generated if any rendering command is issued while a program object that 418 accesses pixel local storage is bound. 419 420 While pixel local storage is enabled, an INVALID_OPERATION error will be 421 generated if any of the current draw framebuffer's attachment points are 422 modified, including changes to the underlying storage backing of objects 423 attached to these attachment points. An INVALID_OPERATION error will also be 424 generated on attempts to bind a different framebuffer object, to delete the 425 currently bound draw framebuffer, or change color buffer selection via 426 DrawBuffers while pixel local storage is enabled. 427 428 Pixel local storage is not supported in combination with multisample 429 rasterization. Attempting to enable pixel local storage while the value of 430 SAMPLE_BUFFERS is one will generate an INVALID_OPERATION error. 431 432 Pixel local storage is not supported when rendering to multiple draw 433 buffers. Attempting to enable pixel local storage while the current draw 434 framebuffer is a user-defined framebuffer and has an image attached to any 435 color attachment other than color attachment zero will generate an INVALID_- 436 OPERATION error. Similarly, attempting to enable pixel local storage while 437 the draw buffer for any color output other than color output zero is not 438 NONE will generate an INVALID_OPERATION error. 439 440 An INVALID_FRAMEBUFFER_OPERATION error will be generated when attempting to 441 enable pixel local storage while the current draw framebuffer is incomplete. 442 443 The total number of bytes of pixel local storage available to a shader is 444 specified by the value of the implementation-dependent constant MAX_SHADER_- 445 PIXEL_LOCAL_STORAGE_SIZE_EXT. A compile-time error will be generated if an 446 attempt is made to utilize more than the space available for pixel local 447 storage variables. An implementation may choose to subdivide the amount 448 of pixel local storage into a region for fast access and a region for normal 449 access. As many pixel local storage variables as possible will be stored, 450 in order of declaration, in the fast region before any variables will be 451 allocated in the normal region. The number of bytes available for fast 452 access is specified by the value of the implementation-dependent constant 453 MAX_SHADER_PIXEL_LOCAL_STORAGE_FAST_SIZE_EXT. This value will always be less 454 than or equal to the total amount of pixel local storage. 455 456 Pixel local storage is disabled by calling Disable with SHADER_PIXEL_- 457 LOCAL_STORAGE_EXT. 458 459 In the initial state, SHADER_PIXEL_LOCAL_STORAGE_EXT is disabled. 460 " 461 462Errors 463 464 INVALID_OPERATION is generated if the application attempts enable pixel 465 local storage while the value of SAMPLE_BUFFERS is one. 466 467 468 INVALID_OPERATION is generated if the application attempts to enable pixel 469 local storage while the current draw framebuffer is a user-defined frame- 470 buffer object and has an image attached to any color attachment other than 471 color attachment zero. 472 473 INVALID_OPERATION is generated if the application attempts to enable pixel 474 local storage while the current draw framebuffer is a user-defined frame- 475 buffer and the draw buffer for any color output other than color 476 output zero is not NONE. 477 478 INVALID_FRAMEBUFFER_OPERATION is generated if the application attempts to 479 enable pixel local storage while the current draw framebuffer is incomplete. 480 481 INVALID_OPERATION is generated if pixel local storage is disabled and the 482 application attempts to issue a rendering command while a program object 483 that accesses pixel local storage is bound. 484 485 INVALID_OPERATION is generated if pixel local storage is enabled and the 486 application attempts to bind a new draw framebuffer, delete the currently 487 bound draw framebuffer, change color buffer selection via DrawBuffers, or 488 modify any attachment of the currently bound draw framebuffer including 489 their underlying storage. 490 491New State 492 493 Add to Table 6.12 Framebuffer Control 494 495 Get Value Type Get Command Initial Value Description Sec. 496 --------------- ---- ------------ ------------- ----------- ----- 497 SHADER_PIXEL_LOCAL- B IsEnabled FALSE Pixel local 4.4.3 498 STORAGE_EXT storage. 499 500New Implementation Dependent State 501 502 Add to Table 6.32 Implementation Dependent Fragment Shader Limits 503 504 State Type Get Command Minimum Value Description Sec. 505 --------------- ---- ------------ ------------- ----------- ----- 506 MAX_SHADER_PIXEL- Z+ GetIntegerv 16 Amount of fast 4.4.3 507 LOCAL_STORAGE_FAST- storage in units 508 _SIZE_EXT of bytes available 509 for pixel local 510 storage variables. 511 512 MAX_SHADER_- Z+ GetIntegerv 16 Amount of total 4.4.3 513 PIXEL_LOCAL_STORAGE- storage in units 514 _SIZE_EXT of bytes available 515 for pixel local 516 storage variables. 517 518Examples 519 520 (1) Use the extension to write data. 521 522 #version 300 es 523 #extension GL_EXT_shader_pixel_local_storage : enable 524 525 __pixel_localEXT FragDataLocal { 526 layout(r11f_g11f_b10f) mediump vec3 normal; 527 layout(rgb10_a2) highp vec4 color; 528 layout(rgba8ui) mediump uvec4 flags; 529 } gbuf; 530 531 void main() 532 { 533 /* .... */ 534 gbuf.normal = v; 535 gbuf.color = texture(sampler, coord); 536 gbuf.flags = material_id; 537 } 538 539 (2) Use the extension to resolve the data. 540 541 #version 300 es 542 #extension GL_EXT_shader_pixel_local_storage : enable 543 544 __pixel_localEXT FragDataLocal { 545 layout(r11f_g11f_b10f) mediump vec3 normal; 546 layout(rgb10_a2) highp vec4 color; 547 layout(rgba8ui) mediump uvec4 flags; 548 } gbuf; 549 550 out highp vec4 fragColor; 551 552 void main() 553 { 554 fragColor = do_lighting(gbuf.normal, gbuf.color, gbuf.flags, light_pos); 555 } 556 557Issues 558 559 (1) Should errors be raised when this extension is used in combination with 560 blending and dithering? 561 562 RESOLVED. 563 564 No. Blending and dithering should be ignored when the shader outputs raw 565 values. 566 567 (2) Should errors be raised when this extension is used in combination with 568 multisampling? 569 570 RESOLVED. 571 572 Yes. This can be trivially detected when the pixel local storage is 573 enabled. 574 575 The alternative is that it results in undefined results. As long as the 576 shader is only run once per fragment, this should sort of work except 577 the coverage mask could mask out some bits. 578 579 (3) Should explicit packing functions be supported? 580 581 RESOLVED. 582 583 No. 584 585 Early versions of this extensions required explicit packing functions 586 to be used when writing to and reading from the pixel local storage. 587 This version of the extension does implicit conversions in of these 588 cases so packing functions are not required. 589 590 (4) What is the initial values of local variables? 591 592 RESOLVED. 593 594 On a cleared framebuffer, the values of pixel local variables will be 595 some function of the clear color value. But the function may be 596 different depending on the format of the framebuffer. This makes the 597 value effectively undefined unless the framebuffer has been cleared to 598 zero. 599 600 See also Issue 5. 601 602 (5) Do we need an API to initialize the pixel local variables? 603 604 RESOLVED. 605 606 No. This is deferred to a future extension. 607 608 Given Issue 4, there is no convenient way to initialize these variables 609 to anything other than zero. 610 611 Applications can initialize it by drawing a fullscreen quad that writes 612 to the local outputs, but that may not be the most efficient way. 613 614 An alternative solution is to define a new API to clear the framebuffer 615 along the lines of: 616 ClearLocaluiEXT(enum buffer, uint n, const T *values); 617 618 (6) Should the raw storage alias the fragment color? 619 620 RESOLVED. 621 622 Applications may want to mix shaders using pixel local storage and user- 623 defined outputs. This could be supported if we reserve a number of bits 624 (where the number depends on the framebuffer format) for the user- 625 defined outputs. 626 627 This approach may make it possible to support this functionality on 628 non-tile based renderers by directing raw values to a separate buffer 629 in memory. 630 631 This extension currently aliases the storage. Applications can manually 632 preserve the framebuffer value by using ARM_shader_framebuffer_fetch, 633 EXT_shader_framebuffer_fetch, or similar extensions to retrieve the 634 color value and then store this as a local value. 635 636 (7) Is there a way to salvage some aspect of multisampling? 637 638 RESOLVED. 639 640 Multisampling is clearly a desirable feature. The most likely 641 implementation of this extension, however, is to reuse the pixel local 642 storage normally used for multisample data to store application-specific 643 data, thus making this extension incompatible with multisampled 644 rasterization. 645 646 Support for multisampling is left to a future extension. 647 648 (8) Should pixel local variables be allowed declared outside interface 649 blocks? 650 651 RESOLVED. 652 653 No. This makes the pixel local storage much more difficult to manage. 654 The ESSL compiler would have to enforce ordering rules shaders to make 655 sure that all shaders see the pixel local storage declarations in the 656 same order. This seems to add implementation complexity for no obvious 657 benefit. 658 659 (9) Should packUnitVector3 be added in a separate extension? 660 661 RESOLVED. 662 663 Extended packing functions is only indirectly related to the core 664 feature exposed by this extension. They could potentially have other 665 use-cases. This could be added in the future if needed. See Issue 15. 666 667 (10) What happens to the local storage after eglSwapBuffers? 668 669 RESOLVED. 670 671 The contents of the pixel local storage are lost after a call to 672 eglSwapBuffers. In this respect, pixel local storage acts as an 673 ancillary buffer than cannot be preserved. 674 675 (11) Can pixel local storage variables be arrays? 676 677 RESOLVED. 678 679 Yes. There's no reason not to support this. 680 681 (12) Are variables declared with the pixel local qualifiers preserved? 682 683 RESOLVED. 684 685 There are two options: A) the implementation implicitly preserves all 686 unwritten pixel local variables, and B) the shader must explicitly 687 preserve unwritten pixel local variables. 688 689 Consider the following local storage block: 690 __pixel_localEXT FragDataLocal { 691 layout(r11f_g11f_b10f) mediump vec3 normal; 692 layout(rgb10_a2) highp vec4 color; 693 layout(rgba8ui) mediump uvec4 flags; 694 } gbuf; 695 If a shader only writes to 'color', option B would make 'normal and 696 'flags' undefined unless the shader also manually assigned these 697 variables to themselves. This would certainly be unexpected. If a 698 shader wants to reduce the data, e.g., by only preserving the 'normal' 699 variable, it can do so by declaring separate __pixel_local_inEXT and 700 __pixel_local_outEXT blocks. 701 702 Option A is chosen. 703 704 (13) Can CopyTex[Sub]Image, ReadPixels, and BlitFramebuffer be called 705 while pixel local storage is enabled? 706 707 RESOLVED. 708 709 These calls are all supported, but may not be very useful. 710 711 For CopyTex[Sub]Image and ReadPixels, the contents of the color buffer 712 will have undefined contents if the pixel local storage variables have 713 not yet been resolved. 714 715 BlitFramebuffer implicitly writes to the color buffer of the draw 716 framebuffer and will thus make all pixel local storage variables 717 associated with it undefined. 718 719 (14) What does 'undefined' mean for a pixel local storage variable 720 or a color value? 721 722 RESOLVED. 723 724 It simply means that the value has no well-defined meaning to an 725 application. It does _not_ mean that the value is random nor that it 726 could have been leaked from other contexts or processes. 727 728 (15) Do we need a built-in function to pack unit vectors? 729 730 RESOLVED. 731 732 No, there is no need for this. 733 734 Earlier drafts of this extensions added ESSL built-in functions to pack 735 and unpack unit vectors (packUnitVector3EXT, unpackUnitVector3EXT). 736 These would, however, only be useful if they gave performance 737 improvements over plain ESSL code, which they do not. 738 739 The following packing functions have been found to generate equivalent 740 code to the proposed built-in functions: 741 742 highp uint packUnitVector3(mediump vec3 n) 743 { 744 highp float p = sqrt(2.0) * sqrt(n.z + 1.0); 745 return packHalf2x16(n.xy / p); 746 } 747 748 mediump vec3 unpackUnitVector3(highp uint p) 749 { 750 highp vec2 fenc = unpackHalf2x16(p); 751 highp float f = dot(fenc, fenc); 752 highp float g = sqrt(1.0 - f); 753 highp vec3 n; 754 n.xy = 2.0*fenc*g; 755 n.z = 1.0 - 2.0*f; 756 return n; 757 } 758 759 (16) When writing to a single output value in a shader, do all local 760 storage values become invalid immediately? And vice versa? 761 762 E.g: 763 fragmentOutputValue = localstorage.value; 764 // Does a further access return an undefined value? 765 fragmentOutputValue += localstorage.value; 766 767 RESOLVED: No, these variables retain their values for the life of the 768 shader. 769 770 Fragment outputs and local storage variables are treated as temporary 771 variables during execution of a shader, rather than accessing the 772 underlying storage directly. Final values are only written to underlying 773 storage at the end of a shader's execution. Within a shader instance, 774 these variables can be read or written safely in any order. 775 776Revision History 777 778 Revision 6, 12/03/2014 (Jan-Harald Fredriksen) 779 Added Issue 16. 780 781 Revision 5, 18/02/2014 (Jan-Harald Fredriksen) 782 Clarified that pixel local storage is undefined after flush commands. 783 Updated error conditions for MRT to cover the default framebuffer. 784 Minor wording changes. 785 Resolved Issue 7. 786 Expanded Issue 15. 787 Updated resolution of Issue 3. 788 789 Revision 4, 22/12/2013 (Jan-Harald Fredriksen) 790 Changed name to EXT_shader_pixel_local_storage. 791 Added MAX_SHADER_PIXEL_LOCAL_STORAGE_FAST_SIZE_EXT. 792 Clarified memory layouts within local storage blocks. 793 794 Revision 3, 14/10/2013 (Jan-Harald Fredriksen) 795 Fixed a typo. 796 Modified error conditions with multiple draw buffers. 797 798 Revision 2, 27/09/2013 (Jan-Harald Fredriksen) 799 Increased minimum maximum storage to 16 bytes. 800 Fixed a couple of typos. 801 Added Issues 13 and 14. 802 Added an error condition when enabling pixel local storage on an 803 incomplete FBO. 804 Restricted local storage to color attachment zero. 805 Disallowed changing buffer selection DrawBuffers while pixel local 806 storage is enabled. 807 Removed packUnitVector3/unpackUnitVector3 and added Issue 15. 808 809 Revision 1, 29/07/2013 (Jan-Harald Fredriksen) 810 First external draft. 811