1Name 2 3 ANGLE_shader_pixel_local_storage 4 5Name Strings 6 7 GL_ANGLE_shader_pixel_local_storage 8 GL_ANGLE_shader_pixel_local_storage_coherent 9 10Contact 11 12 Chris Dalton (chris 'at' rive.app) 13 14Contributors 15 16 Chris Dalton, Rive 17 Kenneth Russell, Google Inc. 18 Shahbaz Youssefi, Google Inc. 19 Kelsey Gilbert, Mozilla Corp. 20 Geoff Lang, Google Inc. 21 Kimmo Kinnunen, Apple Inc. 22 Contributors to the EXT_shader_pixel_local_storage specification 23 Contributors to the ARB_fragment_shader_interlock specification 24 Contributors to the INTEL_fragment_shader_ordering specification 25 Contributors to the EXT_shader_framebuffer_fetch specification 26 Contributors to the ARB_shader_image_load_store specification 27 Contributors to the QCOM_tiled_rendering specification 28 Contributors to the KHR_blend_equation_advanced specification 29 Contributors to the NV_texture_barrier specification 30 Contributors to the (Vulkan) EXT_fragment_shader_interlock specification 31 Contributors to the (Vulkan) ARM_rasterization_order_attachment_access specification 32 33Status 34 35 Incomplete 36 37Version 38 39 Last Modified Date: Aug 18, 2022 40 Author Revision: 1 41 42Number 43 44 OpenGL ES Extension XX 45 46Dependencies 47 48 OpenGL ES 3.0 and GLSL ES 3.00 are required. 49 50 This extension is written against the OpenGL ES 3.0 specification and the 51 OpenGL ES Shading Language 3.00 specification. 52 53 This extension interacts with ANGLE_robust_client_memory. 54 55 This extension interacts with ANGLE_request_extension. 56 57 This extension interacts with ANGLE_polygon_mode. 58 59 This extension interacts with ANGLE_provoking_vertex. 60 61 This extension interacts with EXT_blend_func_extended. 62 63 This extension interacts with EXT_clip_control. 64 65 This extension interacts with EXT_clip_cull_distance. 66 67 This extension interacts with EXT_depth_clamp. 68 69 This extension interacts with EXT_draw_buffers_indexed. 70 71 This extension interacts with EXT_polygon_offset_clamp. 72 73 This extension interacts with KHR_blend_equation_advanced. 74 75 This extension interacts with KHR_debug. 76 77 This extension interacts with NV_polygon_mode. 78 79 This extension interacts with NV_scissor_exclusive. 80 81 This extension interacts with OES_draw_buffers_indexed. 82 83 This extension interacts with OES_sample_variables. 84 85 This extension interacts with OpenGL ES 3.1. 86 87 This extension interacts with GLSL ES 3.10. 88 89Overview 90 91 A major feature missing from WebGL is the ability to access rendering 92 results from fragment shaders and perform tasks like programmable blending. 93 This is especially desirable on Tile-Based Deferred Rendering (TBDR) 94 architectures, as it can be implemented entirely on-chip to achieve maximum 95 performance. 96 97 Capabilities in this area vary widely, but it is the case that all major GPU 98 vendors, on all major APIs, have some mechanism, direct or indirect, whereby 99 a fragment shader can access prior rendering results. The intent of this 100 extension is to condense this myriad of hardware and API features into a 101 simple interface with straightforward implementation(s) on every graphics 102 API. 103 104 Similar to EXT_shader_pixel_local_storage, this extension provides a means 105 for fragment shaders to load and store user-defined data associated with the 106 pixel being covered. The data is accessed via GLSL built-in functions 107 pixelLocalLoadANGLE() and pixelLocalStoreANGLE(). Only the current pixel's 108 data can be accessed; data associated with other pixels is not accessible to 109 the fragment shader. Pixel local storage persists across all fragment 110 invocations and across all draws issued between OpenGL ES API calls 111 BeginPixelLocalStorageANGLE() and EndPixelLocalStorageANGLE(), even if the 112 application binds different shader programs. 113 114 Applications define custom, formatted planes of pixel local storage data, up 115 to an implementation-dependent maximum, using the OpenGL ES API functions 116 FramebufferMemorylessPixelLocalStorageANGLE() and 117 FramebufferTexturePixelLocalStorageANGLE(). These methods behave similarly 118 to FramebufferTextureLayer(). Fragment shaders access a specific local 119 storage plane using one of the opaque GLSL types {pixelLocalANGLE, 120 ipixelLocalANGLE, upixelLocalANGLE}, which are analogous to samplers or 121 images. 122 123 This extension provides two different extension string entries: 124 125 - GL_ANGLE_shader_pixel_local_storage: Provides the new pixel local 126 storage functionality, but each pixel may only be touched once in any 127 single rendering pass. The command PixelLocalStorageBarrierANGLE() is 128 provided to indicate a boundary between passes. Rendering the same 129 pixel twice without a barrier can yield incorrect results. However, 130 "incorrect" does _not_ mean they can be random, uninitialized, or 131 leaked from outside the current draw framebuffer; any artifacts are 132 strictly a result of race conditions between overlapping fragment 133 invocations involved in the current rendering pass. 134 135 - GL_ANGLE_shader_pixel_local_storage_coherent: Guarantees that pixel 136 local storage operations touching the same pixel are invoked 137 synchronously and in API primitive order. No barriers are required and 138 render passes can emit overlapping fragments. 139 140 Some implementations may support GL_ANGLE_shader_pixel_local_storage without 141 supporting GL_ANGLE_shader_pixel_local_storage_coherent. 142 143 A note on performance: On some platforms, this feature will be polyfilled 144 with shader images. While every implementation can be expected to run 145 reasonably fast, certain platforms may see some performance degradation at 146 times from using pixel local storage instead of the normal raster pipeline. 147 As always, benchmark and consider other options before using pixel local 148 storage. 149 150IP Status 151 152 No known IP claims. 153 154New Procedures and Functions 155 156 void FramebufferMemorylessPixelLocalStorageANGLE(int plane, 157 enum internalformat) 158 159 void FramebufferTexturePixelLocalStorageANGLE(int plane, 160 uint backingtexture, 161 int level, 162 int layer) 163 164 void FramebufferPixelLocalClearValue{f,i,ui}vANGLE(int plane, 165 const T value[]) 166 167 void BeginPixelLocalStorageANGLE(sizei n, const enum loadops[]) 168 169 void EndPixelLocalStorageANGLE(sizei n, const enum storeops[]) 170 171 void PixelLocalStorageBarrierANGLE() 172 173 void FramebufferPixelLocalStorageInterruptANGLE() 174 175 void FramebufferPixelLocalStorageRestoreANGLE() 176 177 void GetFramebufferPixelLocalStorageParameter{f,i}vANGLE(int plane, 178 enum pname, 179 T *params) 180 181 (the following commands are supported only if ANGLE_robust_client_memory is 182 supported) 183 184 void GetFramebufferPixelLocalStorageParameter{f,i}vRobustANGLE(int plane, 185 enum pname, 186 GLsizei bufSize, 187 GLsizei *length, 188 T *params) 189 190New Tokens 191 192 Accepted by the <pname> parameter of GetIntegerv(): 193 194 MAX_PIXEL_LOCAL_STORAGE_PLANES_ANGLE 0x96E0 195 MAX_COLOR_ATTACHMENTS_WITH_ACTIVE_PIXEL_LOCAL_STORAGE_ANGLE 0x96E1 196 MAX_COMBINED_DRAW_BUFFERS_AND_PIXEL_LOCAL_STORAGE_PLANES_ANGLE 0x96E2 197 PIXEL_LOCAL_STORAGE_ACTIVE_PLANES_ANGLE 0x96E3 198 199 Accepted as array elements in the <loadops> parameter of 200 BeginPixelLocalStorageANGLE(): 201 202 LOAD_OP_ZERO_ANGLE 0x96E4 203 LOAD_OP_CLEAR_ANGLE 0x96E5 204 LOAD_OP_LOAD_ANGLE 0x96E6 205 206 Accepted as array elements in the <storeops> parameter of 207 EndPixelLocalStorageANGLE(): 208 209 STORE_OP_STORE_ANGLE 0x96E7 210 211 Accepted by the <pname> parameter of 212 GetFramebufferPixelLocalStorageParameterivANGLE() and 213 GetFramebufferPixelLocalStorageParameterivRobustANGLE(): 214 215 PIXEL_LOCAL_FORMAT_ANGLE 0x96E8 216 PIXEL_LOCAL_TEXTURE_NAME_ANGLE 0x96E9 217 PIXEL_LOCAL_TEXTURE_LEVEL_ANGLE 0x96EA 218 PIXEL_LOCAL_TEXTURE_LAYER_ANGLE 0x96EB 219 220 Accepted by the <pname> parameter of 221 GetFramebufferPixelLocalStorageParameterfvANGLE() and 222 GetFramebufferPixelLocalStorageParameterfvRobustANGLE(): 223 224 PIXEL_LOCAL_CLEAR_VALUE_FLOAT_ANGLE 0x96EC 225 226 Accepted by the <pname> parameter of 227 GetFramebufferPixelLocalStorageParameterivANGLE() and 228 GetFramebufferPixelLocalStorageParameterivRobustANGLE(): 229 230 PIXEL_LOCAL_CLEAR_VALUE_INT_ANGLE 0x96ED 231 PIXEL_LOCAL_CLEAR_VALUE_UNSIGNED_INT_ANGLE 0x96EE 232 233New GLSL Opaque Types 234 235 pixelLocalANGLE 236 ipixelLocalANGLE 237 upixelLocalANGLE 238 239New GLSL Built-in Functions 240 241 gvec4 pixelLocalLoadANGLE(gpixelLocalANGLE) 242 void pixelLocalStoreANGLE(gpixelLocalANGLE, gvec4 value) 243 244Additions to the OpenGL ES Specification, Version 3.0.6 245 246 Modify Chapter 2 "OpenGL ES Operation" 247 248 (Insert a new numbered section before 2.14 "Asynchronous Queries".) 249 250 Section 2.X "Pixel Local Storage" 251 252 Pixel local storage provides a means for fragment shaders to load and store 253 user-defined data associated with the pixel being covered. Pixel local 254 storage is configured on a framebuffer as described in Section 4.4.2.X 255 "Configuring Pixel Local Storage on a Framebuffer". Fragment shaders may 256 access pixel local storage data as described in OpenGL ES Shading Language 257 Specification. 258 259 Pixel local storage is activated and deactivated for the current draw 260 framebuffer using the commands: 261 262 void BeginPixelLocalStorageANGLE(sizei n, const enum loadops[]) 263 264 void EndPixelLocalStorageANGLE(sizei n, const enum storeops[]) 265 266 Parameters: 267 268 * <n> specifies the length of the <loadops> or <storeops> array. 269 270 * <loadops> specifies an array of <n> pixel local storage "Load 271 Operations", whose ith element describes the Load Operation to 272 perform on the ith pixel local storage plane. Supported Load 273 Operations are listed in Table X.1. Load Operations are 274 performed on the entire area of each plane, irrespective of 275 scissor or viewport state. 276 277 Load Operation Description 278 ----------------------------------------------------------------------- 279 LOAD_OP_ZERO_ANGLE Clear all components of the pixel local storage 280 plane to 0. This is recommended over 281 LOAD_OP_CLEAR_ANGLE, as it is more likely to be 282 performant on all implementations. 283 284 LOAD_OP_CLEAR_ANGLE Clear the pixel local storage plane to its 285 framebuffer's ith clear value of corresponding 286 type. Pixel local clear values are specified 287 with 288 FramebufferPixelLocalClearValue{f,i,ui}vANGLE(), 289 as described in section 4.4.2.Y "Pixel Local 290 Clear State". If the magnitude of any component 291 of the clear value is too large to be 292 represented in the plane's internalformat, it 293 is clamped. 294 295 LOAD_OP_LOAD_ANGLE Load the contents of the bound texture image 296 into pixel local storage. This Load Operation 297 is only valid for pixel local storage planes 298 that have a texture binding. Texture bindings 299 are established with 300 FramebufferTexturePixelLocalStorageANGLE() as 301 described in section 4.4.2.X "Configuring Pixel 302 Local Storage on a Framebuffer". 303 304 DONT_CARE Leave the initial contents of the pixel local 305 storage plane undefined, favoring speed, and 306 with the caveat that they are _not_ leaked from 307 outside the current draw framebuffer. 308 309 Table X.1: Pixel local storage Load Operations. 310 311 * <storeops> specifies an array of <n> pixel local storage "Store 312 Operations", whose ith element describes the Store Operation 313 to perform on the backing texture of the ith pixel local 314 storage plane. The store operation is ignored if its plane is 315 memoryless. Supported Store Operations are listed in Table 316 X.2. 317 318 Store Operation Description 319 ----------------------------------------------------------------------- 320 STORE_OP_STORE_ANGLE Update the the bound texture image to reflect 321 the pixel local storage contents. 322 323 DONT_CARE Leave the bound texture image contents 324 undefined, with the caveat that they are either 325 unchanged, or not leaked from outside the 326 current draw framebuffer. 327 328 Table X.2: Pixel local storage Store Operations. 329 330 Errors generated by BeginPixelLocalStorageANGLE(): 331 332 * INVALID_FRAMEBUFFER_OPERATION is generated if the default framebuffer 333 object name 0 is bound to DRAW_FRAMEBUFFER. 334 335 * INVALID_FRAMEBUFFER_OPERATION is generated if pixel local storage on the 336 draw framebuffer is in an interrupted state. (See section 2.X.2 337 "Interrupting Pixel Local Storage") 338 339 * INVALID_OPERATION is generated if 340 PIXEL_LOCAL_STORAGE_ACTIVE_PLANES_ANGLE is nonzero. 341 342 * INVALID_OPERATION is generated if the value of SAMPLE_BUFFERS is 1 343 (i.e., if rendering to a multisampled framebuffer). 344 345 * INVALID_OPERATION is generated if DITHER is enabled. 346 347 * INVALID_OPERATION is generated if RASTERIZER_DISCARD is enabled. 348 349 * INVALID_OPERATION is generated if TRANSFORM_FEEDBACK_ACTIVE is TRUE. 350 351 * INVALID_OPERATION is generated if BLEND_DST_ALPHA, BLEND_DST_RGB, 352 BLEND_SRC_ALPHA, or BLEND_SRC_RGB, for any draw buffer, is a blend 353 function requiring the secondary color input, as specified in 354 EXT_blend_func_extended (SRC1_COLOR_EXT, ONE_MINUS_SRC1_COLOR_EXT, 355 SRC1_ALPHA_EXT, ONE_MINUS_SRC1_ALPHA_EXT). 356 357 * INVALID_OPERATION is generated if BLEND_EQUATION_RGB and/or 358 BLEND_EQUATION_ALPHA is an advanced blend equation defined in 359 KHR_blend_equation_advanced. 360 361 * INVALID_VALUE is generated if 362 <n> < 1 or <n> > MAX_PIXEL_LOCAL_STORAGE_PLANES_ANGLE. 363 364 * INVALID_FRAMEBUFFER_OPERATION is generated if the draw framebuffer has 365 an image attached to any color attachment point on or after: 366 367 COLOR_ATTACHMENT0 + 368 MAX_COLOR_ATTACHMENTS_WITH_ACTIVE_PIXEL_LOCAL_STORAGE_ANGLE 369 370 * INVALID_FRAMEBUFFER_OPERATION is generated if the draw framebuffer has 371 an image attached to any color attachment point on or after: 372 373 COLOR_ATTACHMENT0 + 374 MAX_COMBINED_DRAW_BUFFERS_AND_PIXEL_LOCAL_STORAGE_PLANES_ANGLE - <n> 375 376 * INVALID_VALUE is generated if <loadops> is NULL. 377 378 * INVALID_ENUM is generated if <loadops>[0..<n>-1] is not one of the Load 379 Operations enumerated in Table X.1. 380 381 * INVALID_OPERATION is generated if a pixel local storage plane at index 382 [0..<n>-1] is in a deinitialized state. 383 384 * INVALID_OPERATION is generated if <loadops>[0..<n>-1] is 385 LOAD_OP_LOAD_ANGLE and the pixel local storage plane at that same index 386 is memoryless. 387 388 * INVALID_OPERATION is generated if all enabled, texture-backed pixel 389 local storage planes do not have the same width and height. 390 391 * INVALID_OPERATION is generated if the draw framebuffer has other 392 attachments, and its enabled, texture-backed pixel local storage planes 393 do not have identical dimensions with the rendering area. 394 395 (The rendering area is defined in section 4.4.1 "Binding and Managing 396 Framebuffer Objects" as the intersection of rectangles having a lower 397 left of [0, 0] and an upper right of [width, height] for each 398 attachment.) 399 400 * INVALID_OPERATION is generated if the draw framebuffer has no 401 attachments and no enabled, texture-backed pixel local storage planes. 402 403 * INVALID_OPERATION is generated if a single texture image is bound to 404 more than one active pixel local storage plane. 405 406 * INVALID_OPERATION is generated if a single texture image is 407 simultaneously bound to a pixel local storage plane and attached to the 408 draw framebuffer. 409 410 Errors generated by EndPixelLocalStorageANGLE(): 411 412 * INVALID_FRAMEBUFFER_OPERATION is generated if pixel local storage on the 413 draw framebuffer is in an interrupted state. (See section 2.X.2 414 "Interrupting Pixel Local Storage") 415 416 * INVALID_OPERATION is generated if 417 PIXEL_LOCAL_STORAGE_ACTIVE_PLANES_ANGLE is zero. 418 419 * INVALID_VALUE is generated if 420 <n> != PIXEL_LOCAL_STORAGE_ACTIVE_PLANES_ANGLE. 421 422 * INVALID_ENUM is generated if 423 <storeops>[0..PIXEL_LOCAL_STORAGE_ACTIVE_PLANES_ANGLE-1] is not one of 424 the Store Operations enumerated in Table X.2. 425 426 A successful call to BeginPixelLocalStorageANGLE() has the following side 427 effects: 428 429 * Pixel local storage planes indexed in the range [0..<n>-1] are fully 430 activated, initialized and available for fragment shaders to read and 431 write. 432 433 * PIXEL_LOCAL_STORAGE_ACTIVE_PLANES_ANGLE is updated to equal <n>. 434 435 * BLEND is disabled and COLOR_WRITEMASK is updated to {TRUE, TRUE, TRUE, 436 TRUE} for all draw buffers whose index is >= <i>, where: 437 438 <i> = min( 439 MAX_COLOR_ATTACHMENTS_WITH_ACTIVE_PIXEL_LOCAL_STORAGE_ANGLE, 440 MAX_COMBINED_DRAW_BUFFERS_AND_PIXEL_LOCAL_STORAGE_PLANES_ANGLE - <n>) 441 442 Pixel local storage data will persist across all fragment invocations and 443 across all draws issued until the application calls 444 EndPixelLocalStorageANGLE(), even if the application binds different shader 445 programs. In order to make this guarantee, the the OpenGL ES API only allows 446 a limited set of commands while PIXEL_LOCAL_STORAGE_ACTIVE_PLANES_ANGLE is 447 nonzero. All other commands generate INVALID_OPERATION. Valid commands while 448 pixel local storage is active are listed in Table X.3. 449 450 ActiveTexture 451 BindBuffer 452 BindBufferBase 453 BindBufferRange 454 BindFramebuffer 455 BindSampler 456 BindTexture 457 BindVertexArray 458 BlendEquationSeparatei* 459 BlendEquationi* 460 BlendFuncSeparatei* 461 BlendFunci* 462 BufferData 463 BufferSubData 464 CheckFramebufferStatus 465 ClearBuffer* 466 ClipControlEXT 467 ColorMaski* 468 CullFace 469 DebugMessageCallback* 470 DebugMessageControl* 471 DebugMessageInsert* 472 Delete* 473 DepthFunc 474 DepthMask 475 DepthRangef 476 Disable 477 DisableVertexAttribArray 478 Disablei* 479 DispatchComputeIndirect 480 DrawArrays* 481 DrawBuffers 482 DrawElements* 483 DrawRangeElements* 484 Enable 485 EnableClientState 486 EnableVertexAttribArray 487 Enablei* 488 EndPixelLocalStorageANGLE 489 FlushMappedBufferRange 490 FramebufferMemorylessPixelLocalStorageANGLE 491 FramebufferParameter* 492 FramebufferPixelLocalStorageInterruptANGLE 493 FramebufferRenderbuffer 494 FramebufferTexture* 495 FrontFace 496 Gen* 497 Get* 498 Is* 499 MapBufferRange 500 ObjectLabel* 501 ObjectPtrLabel* 502 PixelLocalStorageBarrierANGLE 503 PolygonMode* 504 PolygonOffset* 505 PopDebugGroup* 506 ProvokingVertexANGLE 507 PushDebugGroup* 508 SamplerParameter* 509 Scissor 510 StencilFunc 511 StencilFuncSeparate 512 StencilMask 513 StencilMaskSeparate 514 StencilOp 515 StencilOpSeparate 516 TexParameter* 517 Uniform* 518 UnmapBuffer 519 UseProgram 520 ValidateProgram 521 VertexAttrib* 522 Viewport 523 524 Table X.3: Valid commands while PIXEL_LOCAL_STORAGE_ACTIVE_PLANES_ANGLE 525 is nonzero. 526 527 Additional restrictions also go into effect while 528 PIXEL_LOCAL_STORAGE_ACTIVE_PLANES_ANGLE is nonzero: 529 530 * Calls that modify the current draw framebuffer, or change the 531 DRAW_FRAMEBUFFER_BINDING, end pixel local storage implicitly with 532 <storeops> of STORE_OP_STORE_ANGLE. 533 534 e.g., BindFramebuffer, DrawBuffers, FramebufferTexture2D, 535 FramebufferTextureLayer, FramebufferRenderbuffer, 536 FramebufferParameteri, FramebufferTexturePixelLocalStorageANGLE, 537 FramebufferMemorylessPixelLocalStorageANGLE, etc. (When <target> is 538 FRAMEBUFFER or DRAW_FRAMEBUFFER, or when the framebuffer object being 539 modified is the draw framebuffer whose pixel local storage is currently 540 active). 541 542 * INVALID_OPERATION is generated by Enable(), Disable() if <cap> is not 543 one of: BLEND, CULL_FACE, DEBUG_OUTPUT, DEBUG_OUTPUT_SYNCHRONOUS, 544 DEPTH_CLAMP_EXT, DEPTH_TEST, POLYGON_OFFSET_POINT_NV, 545 POLYGON_OFFSET_LINE_NV, POLYGON_OFFSET_LINE_ANGLE, POLYGON_OFFSET_FILL, 546 PRIMITIVE_RESTART_FIXED_INDEX, SCISSOR_TEST, SCISSOR_TEST_EXCLUSIVE_NV, 547 STENCIL_TEST, CLIP_DISTANCE[0..7]_EXT 548 549 * Calls to ClearBuffer{f,i,ui}v() are ignored if <buffer> is COLOR and any 550 of the following are true: 551 552 <buffer> >= MAX_COLOR_ATTACHMENTS_WITH_ACTIVE_PIXEL_LOCAL_STORAGE_ANGLE 553 <buffer> >= 554 (MAX_COMBINED_DRAW_BUFFERS_AND_PIXEL_LOCAL_STORAGE_PLANES_ANGLE - 555 ACTIVE_PIXEL_LOCAL_STORAGE_PLANES_ANGLE) 556 557 * Calls to EnableiOES(BLEND, <i>) and ColorMaskiOES(<i>, ...) are ignored 558 if any of the following are true: 559 560 <i> >= MAX_COLOR_ATTACHMENTS_WITH_ACTIVE_PIXEL_LOCAL_STORAGE_ANGLE 561 <i> >= (MAX_COMBINED_DRAW_BUFFERS_AND_PIXEL_LOCAL_STORAGE_PLANES_ANGLE - 562 ACTIVE_PIXEL_LOCAL_STORAGE_PLANES_ANGLE) 563 564 * Calls to Enable(BLEND) and ColorMask() only update state on draw buffers 565 whose index is less than <n>, where: 566 567 <n> = min( 568 MAX_COLOR_ATTACHMENTS_WITH_ACTIVE_PIXEL_LOCAL_STORAGE_ANGLE, 569 MAX_COMBINED_DRAW_BUFFERS_AND_PIXEL_LOCAL_STORAGE_PLANES_ANGLE - 570 ACTIVE_PIXEL_LOCAL_STORAGE_PLANES_ANGLE); 571 572 i.e., their behavior is overridden to the equivalence of: 573 574 for (int i = 0; i < <n>; ++i) 575 EnableiOES(BLEND, i) 576 577 for (int i = 0; i < <n>; ++i) 578 ColorMaskiOES(i, ...) 579 580 * INVALID_OPERATION is generated by Enablei*(), Disablei*() if <cap> is 581 not one of: BLEND, SCISSOR_TEST, SCISSOR_TEST_EXCLUSIVE_NV 582 583 * INVALID_OPERATION is generated by BlendFunc*() if <srcRGB>, <dstRGB>, 584 <srcAlpha>, or <dstAlpha> is a blend function requiring the secondary 585 color input, as specified in EXT_blend_func_extended (SRC1_COLOR_EXT, 586 ONE_MINUS_SRC1_COLOR_EXT, SRC1_ALPHA_EXT, ONE_MINUS_SRC1_ALPHA_EXT). 587 588 * INVALID_OPERATION is generated by BlendEquation*() if <mode> is one of 589 the advanced blend equations defined in KHR_blend_equation_advanced. 590 591 * INVALID_OPERATION is generated if a draw is issued with a fragment 592 shader that accesses a texture bound to pixel local storage. 593 594 * INVALID_OPERATION is generated if a draw is issued with a fragment 595 shader that has a pixel local uniform bound to an inactive pixel local 596 storage plane. 597 598 * INVALID_OPERATION is generated if a draw is issued with a fragment 599 shader that does _not_ have a pixel local uniform bound to an _active_ 600 pixel local storage plane (i.e., the fragment shader must declare 601 uniforms bound to every single active pixel local storage plane). 602 603 This is because many backend implementations need to account for every 604 active pixel local storage plane, even if the application code does not 605 access it during a particular shader invocation. 606 607 * INVALID_OPERATION is generated if a draw is issued with a fragment 608 shader that has a pixel local storage uniform whose format layout 609 qualifier does not identically match the internalformat of its 610 associated pixel local storage plane on the current draw framebuffer, as 611 enumerated in Table X.4. 612 613 Because of the "implementation-dependent" clause of the framebuffer 614 completeness test, and because a pixel local storage implementation may add 615 additional attachments to the underlying framebuffer object, it is strongly 616 advised that an application also check to see if the framebuffer is complete 617 after BeginPixelLocalStorageANGLE() and prior to rendering. (See section 618 4.4.4.2 "Whole Framebuffer Completeness".) 619 620 If BeginPixelLocalStorageANGLE() generates an error, 621 PIXEL_LOCAL_STORAGE_ACTIVE_PLANES_ANGLE is not modified, and a balancing 622 call to EndPixelLocalStorageANGLE() may therefore also generate an error. 623 624 When PIXEL_LOCAL_STORAGE_ACTIVE_PLANES_ANGLE is zero, any draw issued with a 625 fragment shader that declares pixel local storage uniforms generates an 626 INVALID_FRAMEBUFFER_OPERATION error. 627 628 Section 2.X.1 "Non-coherent Pixel Local Storage" 629 630 When GL_ANGLE_shader_pixel_local_storage_coherent is _not_ supported, and 631 pixel local storage is active, applications must also split their rendering 632 of pixel local storage into separate passes, none of which touch an 633 individual pixel more than once. The command: 634 635 void PixelLocalStorageBarrierANGLE() 636 637 Errors: 638 639 * INVALID_FRAMEBUFFER_OPERATION is generated if pixel local storage on the 640 draw framebuffer is in an interrupted state. (See section 2.X.2 641 "Interrupting Pixel Local Storage") 642 643 * INVALID_OPERATION is generated if 644 PIXEL_LOCAL_STORAGE_ACTIVE_PLANES_ANGLE is zero. 645 646 delimits a boundary between distinct, non-self-overlapping rendering passes. 647 Pixel local storage loads issued after the barrier will reflect stores 648 issued prior to the barrier, and stores issued after the barrier will not 649 execute until all accesses initiated prior to the barrier are complete. 650 651 Rendering to the same pixel more than once without a barrier in between can 652 yield incorrect results in pixel local storage, however, "incorrect" does 653 _not_ mean they can be random, uninitialized, or leaked from outside the 654 current draw framebuffer. Any artifacts are strictly a result of race 655 conditions between overlapping fragment invocations involved in the current 656 rendering pass. 657 658 Section 2.X.2 "Interrupting Pixel Local Storage" 659 660 An application may need to interrupt a pixel local storage rendering pass. 661 One example of this may be a browser implementing WebGL. The command: 662 663 void FramebufferPixelLocalStorageInterruptANGLE() 664 665 Errors: 666 667 * INVALID_FRAMEBUFFER_OPERATION is generated if the current interrupt 668 count on the draw framebuffer is equal to 255. 669 670 Increments an interrupt counter on the current draw framebuffer. When the 671 counter increments from 0 to 1, and PIXEL_LOCAL_STORAGE_ACTIVE_PLANES_ANGLE 672 is nonzero, this command also ends pixel local storage using 673 STORE_OP_STORE_ANGLE for every plane. The contents of any memoryless planes 674 are lost. The counter value cannot be incremented greater than 255. This 675 command is ignored when the default framebuffer object name 0 is bound. When 676 a framebuffer's pixel local storage interupt counter is nonzero, it is 677 considered to be in an "interrupted" state. 678 679 The command: 680 681 void FramebufferPixelLocalStorageRestoreANGLE() 682 683 Errors: 684 685 * INVALID_FRAMEBUFFER_OPERATION is generated if pixel local storage on the 686 draw framebuffer is not in an interrupted state. 687 688 Decrements the pixel local storage interrupt counter on the current draw 689 framebuffer. When the counter decrements from 1 to 0, and 690 PIXEL_LOCAL_STORAGE_ACTIVE_PLANES_ANGLE was nonzero at the time this 691 framebuffer entered an interrupted state, the command also begins pixel 692 local storage using LOAD_OP_LOAD_ANGLE for texture backed planes and 693 DONT_CARE for memoryless planes. The number of planes activated is equal to 694 the value of PIXEL_LOCAL_STORAGE_ACTIVE_PLANES_ANGLE at the time this 695 framebuffer entered an interrupted state. This command is ignored when the 696 default framebuffer object name 0 is bound. 697 698 Modify Section 4.4.2 "Attaching Images to Framebuffer Objects" 699 700 (Add a new paragraph to 4.4.2.3 "Attaching Renderbuffer Images to a 701 Framebuffer".) 702 703 If a renderbuffer object is deleted while its image is attached to the 704 currently bound draw framebuffer, and pixel local storage is active, then it 705 is as if EndPixelLocalStorageANGLE() had been called with 706 <n>=PIXEL_LOCAL_STORAGE_ACTIVE_PLANES_ANGLE and <storeops> of 707 STORE_OP_STORE_ANGLE. 708 709 (Add a new paragraph to 4.4.2.4 "Attaching Texture Images to a Framebuffer".) 710 711 If a texture object is deleted while its image is attached to the currently 712 bound draw framebuffer, and pixel local storage is active, then it is as if 713 EndPixelLocalStorageANGLE() had been called with 714 <n>=PIXEL_LOCAL_STORAGE_ACTIVE_PLANES_ANGLE and <storeops> of 715 STORE_OP_STORE_ANGLE. 716 717 (Insert two new numbered section after 4.4.2.4 "Attaching Texture Images to a 718 Framebuffer".) 719 720 Section 4.4.2.X "Configuring Pixel Local Storage on a Framebuffer" 721 722 The GL provides an array of configurable pixel local storage planes on 723 framebuffer objects. These planes are numbered beginning with zero, with the 724 total number of pixel local storage planes provided given by the 725 implementation-dependent constant MAX_PIXEL_LOCAL_STORAGE_PLANES_ANGLE. 726 Fragment shaders may access pixel local storage data as described in OpenGL 727 ES Shading Language Specification. Initially, pixel local storage planes are 728 in a deinitialized state and are unusable. 729 730 A memoryless pixel local storage plane may be established on the current 731 draw framebuffer by calling: 732 733 void FramebufferMemorylessPixelLocalStorageANGLE(int plane, 734 enum internalformat) 735 736 Parameters: 737 738 * <plane> identifies the pixel local storage plane index. 739 740 * <internalformat> selects the data format, as enumerated in Table X.4. 741 742 internalformat Clear Value Type Pixel Local Type format qualifier 743 ----------------------------------------------------------------------- 744 RGBA8 FLOAT pixelLocalANGLE rgba8 745 RGBA8I INT ipixelLocalANGLE rgba8i 746 RGBA8UI UNSIGNED_INT upixelLocalANGLE rgba8ui 747 R32F FLOAT pixelLocalANGLE r32f 748 R32UI UNSIGNED_INT upixelLocalANGLE r32ui 749 750 Table X.4: Supported pixel local storage internalformats, with the Clear 751 Value Type used by BeginPixelLocalStorageANGLE(), and their required 752 corresponding GLSL Pixel Local Type and format layout qualifier. 753 754 Note that all pixel local storage formats consume exactly 4 bytes of 755 storage. 756 757 Note that r32i is excluded from this table because it is not supported 758 by EXT_shader_pixel_local_storage. 759 760 Errors: 761 762 * INVALID_FRAMEBUFFER_OPERATION is generated if the default framebuffer 763 object name 0 is bound to DRAW_FRAMEBUFFER. 764 765 * INVALID_FRAMEBUFFER_OPERATION is generated if pixel local storage on the 766 draw framebuffer is in an interrupted state. (See section 2.X.2 767 "Interrupting Pixel Local Storage") 768 769 * INVALID_OPERATION is generated if 770 PIXEL_LOCAL_STORAGE_ACTIVE_PLANES_ANGLE is nonzero. 771 772 * INVALID_VALUE is generated if 773 <plane> < 0 or <plane> >= MAX_PIXEL_LOCAL_STORAGE_PLANES_ANGLE. 774 775 * INVALID_ENUM is generated if <internalformat> is not one of the 776 acceptable values in Table X.4, or NONE. 777 778 If <internalformat> is NONE, the pixel local storage plane at index <plane> 779 is deinitialized and any internal storage is released. 780 781 Otherwise, this call establishes a formatted plane of pixel local storage 782 data at index <plane>, accessible exclusively to fragment shaders, whose 783 liftetime will be scoped between calls to BeginPixelLocalStorageANGLE() and 784 EndPixelLocalStorageANGLE(). The pixel local storage plane is "memoryless" 785 from the application's perspective; its contents are cleared upon calling 786 BeginPixelLocalStorageANGLE(), and its contents are lost after the 787 application calls EndPixelLocalStorageANGLE(). The implementation will make 788 a best effort to store this data exclusively in high performance local 789 caches, e.g., tiled memory, but accessing the data may still result in 790 memory transactions on some platforms. 791 792 Additionally, the GL supports binding a layer of an immutable texture object 793 to pixel local storage. In this scenario, the pixel local storage data is 794 not lost upon calling EndPixelLocalStorageANGLE(), but rather, will be 795 stored in the given texture image. Such behavior is useful for applications 796 such as blending in the fragment shader, where the application renders to 797 pixel local storage instead of a color attachment. 798 799 When a texture image is bound to pixel local storage, the application may 800 also choose to initialize the pixel local storage plane using its bound 801 texture image contents during BeginPixelLocalStorageANGLE(), by passing Load 802 Operation LOAD_OP_LOAD_ANGLE. 803 804 An immutable texture layer image may be bound to a pixel local storage plane 805 on the current draw framebuffer by calling: 806 807 void FramebufferTexturePixelLocalStorageANGLE(int plane, 808 uint backingtexture, 809 int level, 810 int layer) 811 812 Parameters: 813 814 * <plane> identifies the pixel local storage plane index. 815 816 * <backingtexture> specifies the name of an existing immutable texture 817 object to bind. 818 819 * <level> selectes the mipmap level to bind. 820 821 * <layer> specifies the texture layer to bind: 822 823 - Zero if <backingtexture> is a TEXTURE_2D 824 - The array index to bind if <backingtexture> is a TEXTURE_2D_ARRAY 825 826 Errors: 827 828 * INVALID_FRAMEBUFFER_OPERATION is generated if the default framebuffer 829 object name 0 is bound to DRAW_FRAMEBUFFER. 830 831 * INVALID_FRAMEBUFFER_OPERATION is generated if pixel local storage on the 832 draw framebuffer is in an interrupted state. (See section 2.X.2 833 "Interrupting Pixel Local Storage") 834 835 * INVALID_OPERATION is generated if 836 PIXEL_LOCAL_STORAGE_ACTIVE_PLANES_ANGLE is nonzero. 837 838 * INVALID_VALUE is generated if 839 <plane> < 0 or <plane> >= MAX_PIXEL_LOCAL_STORAGE_PLANES_ANGLE. 840 841 * INVALID_OPERATION is generated if <backingtexture> is not the name of an 842 existing immutable texture object, or zero. 843 844 * INVALID_OPERATION is generated if <backingtexture> is nonzero and not of 845 type TEXTURE_2D or TEXTURE_2D_ARRAY. 846 847 * INVALID_VALUE is generated if <backingtexture> is nonzero and 848 <level> < 0. 849 850 * INVALID_VALUE is generated if <backingtexture> is nonzero and 851 <level> >= the immutable number of mipmap levels in <backingtexture>. 852 853 * INVALID_VALUE is generated if <backingtexture> is nonzero and 854 <layer> < 0. 855 856 * INVALID_VALUE is generated if <backingtexture> is nonzero and 857 <layer> >= the immutable number of texture layers in <backingtexture>. 858 859 * INVALID_ENUM is generated if <backingtexture> is nonzero and its 860 internalformat is not one of the acceptable values in Table X.4. 861 862 If <backingtexture> is 0, <level> and <layer> are ignored and the pixel 863 local storage plane <plane> is deinitialized. 864 865 Otherwise, this call establishes a formatted plane of pixel local storage 866 data at index <plane>, whose contents are bound to the given texture layer 867 image. 868 869 When a texture object is deleted, any pixel local storage plane to which it 870 is bound is automatically deinitialized. 871 872 If a texture object is deleted while its image is bound to a pixel local 873 storage plane on the currently bound draw framebuffer, and pixel local 874 storage is active, then it is as if EndPixelLocalStorageANGLE() had been 875 called with <n>=PIXEL_LOCAL_STORAGE_ACTIVE_PLANES_ANGLE and <storeops> of 876 STORE_OP_STORE_ANGLE. 877 878 Section 4.4.2.Y "Pixel Local Clear State" 879 880 Each pixel local storage plane on a framebuffer has state for three separate 881 clear values: a 4-component vector of type FLOAT, INT, and UNSIGNED_INT. 882 When the Load Operation LOAD_OP_CLEAR_ANGLE is executed, a pixel local 883 storage plane is cleared to the value whose type corresponds to its 884 internalformat. (See Table X.4.) Clear values are set with the commands: 885 886 void FramebufferPixelLocalClearValuefvANGLE(int plane, 887 const float value[]) 888 889 void FramebufferPixelLocalClearValueivANGLE(int plane, 890 const int value[]) 891 892 void FramebufferPixelLocalClearValueuivANGLE(int plane, 893 const uint value[]) 894 895 Parameters: 896 897 * <plane> identifies the pixel local storage plane index. 898 899 * <value> specifies the new 4-component clear value. 900 901 Description: 902 903 Sets the clear value state of specific type for a plane of pixel local 904 storage on the current draw framebuffer. 905 906 Errors: 907 908 * INVALID_FRAMEBUFFER_OPERATION is generated if the default framebuffer 909 object name 0 is bound to DRAW_FRAMEBUFFER. 910 911 * INVALID_FRAMEBUFFER_OPERATION is generated if pixel local storage on the 912 draw framebuffer is in an interrupted state. (See section 2.X.2 913 "Interrupting Pixel Local Storage") 914 915 * INVALID_VALUE is generated if 916 <plane> < 0 or <plane> >= MAX_PIXEL_LOCAL_STORAGE_PLANES_ANGLE. 917 918 Modify Section 6.1 "Querying GL State" 919 920 (Insert a new numbered section after 6.1.14 "Renderbuffer Object Queries".) 921 922 Section 6.1.X "Pixel Local Storage Queries" 923 924 The application may query the state of a pixel local storage plane on the 925 current draw famebuffer using the commands: 926 927 void GetFramebufferPixelLocalStorageParameterfvANGLE(int plane, 928 enum pname, 929 GLsizei bufSize, 930 GLsizei *length, 931 GLfloat *params) 932 933 void GetFramebufferPixelLocalStorageParameterivANGLE(int plane, 934 enum pname, 935 GLsizei bufSize, 936 GLsizei *length, 937 GLint *params) 938 939 Parameters: 940 941 * <plane> identifies the pixel local storage plane index. 942 943 * <pname> specifies the parameter of the plane to query. 944 945 * <params> receives the value(s) for parameter <pname> of the pixel local 946 storage plane at index <plane>. When an error is generated, nothing is 947 written to <params>. 948 949 Description: 950 951 * If <pname> is PIXEL_LOCAL_FORMAT_ANGLE, <params> will contain the 952 internalformat of the plane from Table X.4, or NONE if the selected 953 pixel local storage plane is in a deinitialized state. 954 955 * If <pname> is PIXEL_LOCAL_TEXTURE_NAME_ANGLE, <params> will contain the 956 name of the immutable texture object which contains the image bound to 957 the plane, or 0 if the plane is memoryless or deinitialized. 958 959 Note that when the texture object bound to a plane is deleted, the plane 960 is automatically converted to memoryless. See section 4.4.2.X 961 "Configuring Pixel Local Storage on a Framebuffer". 962 963 * If <pname> is PIXEL_LOCAL_TEXTURE_LEVEL_ANGLE, <params> will contain the 964 mipmap level of the bound texture object, or 0 if the plane is 965 memoryless or deinitialized. 966 967 * If <pname> is PIXEL_LOCAL_TEXTURE_LAYER_ANGLE, <params> will contain the 968 layer of the bound texture object, or 0 if the plane is memoryless or 969 deinitialized. 970 971 * If <pname> is PIXEL_LOCAL_CLEAR_VALUE_FLOAT_ANGLE, 972 PIXEL_LOCAL_CLEAR_VALUE_INT_ANGLE, or 973 PIXEL_LOCAL_CLEAR_VALUE_UNSIGNED_INT_ANGLE, <params> will contain 4 974 values: the 4 color components of the clear value of corresponding type. 975 976 Errors: 977 978 * INVALID_FRAMEBUFFER_OPERATION is generated if the default framebuffer 979 object name 0 is bound to DRAW_FRAMEBUFFER. 980 981 * INVALID_FRAMEBUFFER_OPERATION is generated if pixel local storage on the 982 draw framebuffer is in an interrupted state. (See section 2.X.2 983 "Interrupting Pixel Local Storage") 984 985 * INVALID_VALUE is generated if 986 <plane> < 0 or <plane> >= MAX_PIXEL_LOCAL_STORAGE_PLANES_ANGLE. 987 988 * INVALID_ENUM is generated if <pname> is not in Table 6.Y, or if the 989 command issued is not the associated "Get Command" for <pname> in Table 990 6.Y. 991 992 * INVALID_VALUE is generated if <params> is NULL. 993 994 If ANGLE_robust_client_memory is supported, the alternative query commands 995 may also be used: 996 997 void GetFramebufferPixelLocalStorageParameterfvRobustANGLE(int plane, 998 enum pname, 999 GLsizei bufSize, 1000 GLsizei *length, 1001 GLfloat *params) 1002 1003 void GetFramebufferPixelLocalStorageParameterivRobustANGLE(int plane, 1004 enum pname, 1005 GLsizei bufSize, 1006 GLsizei *length, 1007 GLint *params) 1008 1009 Additional Parameters: 1010 1011 * <bufSize> indicates the maximum number of values that can be written to 1012 <params>. 1013 1014 * <length> may be NULL. If not NULL, it receives the number of values 1015 written to <params>. When an error is generated, nothing is written to 1016 <length>. 1017 1018 Additional Errors: 1019 1020 * INVALID_OPERATION is generated if <bufSize> is not large enough to 1021 receive the requested parameter. 1022 1023 1024 Modify Section 6.1 "State Tables" 1025 1026 (Insert two new numbered tables.) 1027 1028 Minimum 1029 Get Value Type Get Command Value Sec. 1030 ------------------------------------------------------------------------ 1031 MAX_PIXEL_LOCAL_STORAGE- 1032 _PLANES_ANGLE Z+ GetIntegerv 4 4.4.2.X 1033 1034 MAX_COLOR_ATTACHMENTS_WITH- 1035 _ACTIVE_PIXEL_LOCAL_STORAGE_ANGLE Z+ GetIntegerv *0! 2.X 1036 1037 MAX_COMBINED_DRAW_BUFFERS_AND- 1038 _PIXEL_LOCAL_STORAGE_PLANES_ANGLE Z+ GetIntegerv 4 2.X 1039 1040 Table 6.X: Impementation Dependent Pixel Local Storage Limits 1041 1042 Note that MAX_COLOR_ATTACHMENTS_WITH_ACTIVE_PIXEL_LOCAL_STORAGE_ANGLE may be 1043 zero, in which case the application cannot render to any other color 1044 attachments while PIXEL_LOCAL_STORAGE_ACTIVE_PLANES_ANGLE is nonzero. 1045 1046 Initial 1047 Get Value Type Get Command Value Sec. 1048 -------------------------------------------------------------------------- 1049 PIXEL_LOCAL_STORAGE- 1050 _ACTIVE_PLANES_ANGLE Z+ GetIntegerv 0 2.X 1051 1052 PIXEL_LOCAL_FORMAT- GetFramebufferPixelLocal- 1053 _ANGLE Z+ StorageParameterivANGLE NONE 6.1.X 1054 1055 PIXEL_LOCAL_TEXTURE- GetFramebufferPixelLocal- 1056 _NAME_ANGLE Z+ StorageParameterivANGLE 0 6.1.X 1057 1058 PIXEL_LOCAL_TEXTURE- GetFramebufferPixelLocal- 1059 _LEVEL_ANGLE Z+ StorageParameterivANGLE 0 6.1.X 1060 1061 PIXEL_LOCAL_TEXTURE- GetFramebufferPixelLocal- 1062 _LAYER_ANGLE Z StorageParameterivANGLE 0 6.1.X 1063 1064 PIXEL_LOCAL_CLEAR- GetFramebufferPixelLocal- 1065 _VALUE_FLOAT_ANGLE 4*R StorageParameterfvANGLE 0,0,0,0 6.1.X 1066 1067 PIXEL_LOCAL_CLEAR- GetFramebufferPixelLocal- 1068 _VALUE_INT_ANGLE 4*Z StorageParameterivANGLE 0,0,0,0 6.1.X 1069 1070 PIXEL_LOCAL_CLEAR_VALUE- GetFramebufferPixelLocal- 1071 _UNSIGNED_INT_ANGLE 4*Z+ StorageParameterivANGLE 0,0,0,0 6.1.X 1072 1073 Table 6.Y: Pixel Local Storage State 1074 1075 1076Interactions with the ANGLE_request_extension specification 1077 1078 When either ANGLE_shader_pixel_local_storage or 1079 ANGLE_shader_pixel_local_storage_coherent is enabled, the following 1080 extensions are all implicitly enabled, if supported: 1081 1082 * OES_draw_buffers_indexed 1083 * EXT_draw_buffers_indexed 1084 * EXT_color_buffer_float 1085 * EXT_color_buffer_half_float 1086 * ANGLE_shader_pixel_local_storage_coherent 1087 * ANGLE_shader_pixel_local_storage 1088 1089Interactions with ANGLE_provoking_vertex, ANGLE_polygon_mode, 1090EXT_blend_func_extended, EXT_clip_control, EXT_clip_cull_distance, 1091EXT_depth_clamp, EXT_draw_buffers_indexed, EXT_polygon_offset_clamp, 1092KHR_blend_equation_advanced, KHR_debug, NV_polygon_mode, 1093NV_scissor_exclusive, OES_draw_buffers_indexed 1094 1095 If any of these extensions is not supported, ignore the applicable 1096 references to the extension itself, and to BlendEquationSeparatei*, 1097 BlendEquationi*, BlendFuncSeparatei*, BlendFunci*, ColorMaski*, 1098 DebugMessageCallback*, DebugMessageControl*, DebugMessageInsert*, Disablei*, 1099 ClipControlEXT, Enablei*, ObjectLabel*, PolygonMode*, PolygonOffsetClampEXT, 1100 ProvokingVertexANGLE, ObjectPtrLabel*, PopDebugGroup*, PushDebugGroup*, 1101 DEBUG_OUTPUT, DEBUG_OUTPUT_SYNCHRONOUS, SCISSOR_TEST_EXCLUSIVE_NV, 1102 CLIP_DISTANCE[0..7]_EXT, POLYGON_OFFSET_POINT_NV, POLYGON_OFFSET_LINE_NV, 1103 POLYGON_OFFSET_LINE_ANGLE symbols. 1104 1105Interactions with OpenGL ES 3.1 1106 1107 Modify Section 8.22 "Texture Image Loads and Stores" 1108 1109 (Modify the final paragraph.) 1110 1111 Add active pixel local storage planes to the list of resource types that count 1112 against MAX_COMBINED_SHADER_OUTPUT_RESOURCES. 1113 1114 1115Additions to the OpenGL ES Shading Language Specification, Version 3.00 1116 1117 Including the following line in a fragment shader controls the language 1118 features described in this extension: 1119 1120 #extension GL_ANGLE_shader_pixel_local_storage : <behavior> 1121 1122 Where <behavior> is as specified in section 3.5. 1123 1124 Whether or not the application relies on the "_coherent" extension string 1125 from the OpenGL ES API side, the language features described in this section 1126 are identical, and fragment shaders should only enable 1127 GL_ANGLE_shader_pixel_local_storage. 1128 1129 Modify Section 4.1 "Basic Types" 1130 1131 (Add the following new types.) 1132 1133 Pixel Local Types (opaque) 1134 1135 * pixelLocalANGLE 1136 a handle for accessing floating-point pixel local storage data 1137 1138 * ipixelLocalANGLE 1139 a handle for accessing integer pixel local storage data 1140 1141 * upixelLocalANGLE 1142 a handle for accessing unsigned integer pixel local storage data 1143 1144 Modify Section 4.1.7 "Opaque Types" 1145 1146 (Insert a new numbered section after 4.1.7.1 "Samplers".) 1147 1148 Section 4.1.7.X "Pixel Local Storage" 1149 1150 Pixel local types (e.g. pixelLocalANGLE) are opaque types. They are handles 1151 for accessing user-defined data that is associated with the pixel being 1152 covered. They are used with the built-in functions described in section 8.X 1153 "Pixel Local Storage Functions". 1154 1155 In addition to the limitations already imposed on opaque types, pixel local 1156 types are subject to additional constraints: 1157 1158 * They cannot be aggregated in arrays. 1159 1160 * As uniforms, they must be declared at global scope; they cannot be 1161 declared in structs or interface blocks. 1162 1163 * As uniforms, they are not visible to the OpenGL ES API and cannot be 1164 accessed via GetUniformLocation() or GetActiveUniform(). (This 1165 facilitates backends that are implemented entirely in-shader, e.g., 1166 EXT_shader_pixel_local_storage.) 1167 1168 * As uniforms, they must declare "binding" and "format" layout qualifiers, 1169 as described in section 4.3.8.X "Pixel Local Storage Layout Qualifiers". 1170 1171 * As function arguments, they cannot have layout qualifiers. Any function 1172 that accepts pixel local type(s) as arguments is inlined by the compiler, 1173 and the bindings and formats are determined at the call site. 1174 1175 * They cannot be aliased; it is a compile-time error to declare two pixel 1176 local uniforms with duplicate binding layout qualifiers. 1177 1178 * They can only be declared in a fragment shader. 1179 1180 Fragment shaders that declare pixel local storage uniforms are subject to 1181 additional shader-wide restrictions as well: 1182 1183 * discard is illegal 1184 1185 When polyfilled with shader images, pixel local storage requires 1186 early_fragment_tests, which causes discard to interact differently 1187 with the depth and stencil tests. 1188 1189 In order to ensure identical behavior across all backends (some of 1190 which may not have access to early_fragment_tests), we disallow 1191 discard if pixel local storage uniforms have been declared. 1192 1193 * return from main() is illegal 1194 1195 ARB_fragment_shader_interlock functions cannot be called within flow 1196 control, which includes any code that might execute after a return 1197 statement. To keep things simple, and since these "interlock" calls 1198 are automatically generated by the compiler inside of main(), we 1199 disallow return from main() if pixel local storage uniforms have been 1200 declared. 1201 1202 * assignment to gl_FragDepth(EXT) or gl_SampleMask is illegal 1203 1204 When polyfilled with shader images, pixel local storage requires 1205 early_fragment_tests, which causes assignments to gl_FragDepth(EXT) 1206 and gl_SampleMask to be ignored. 1207 1208 In order to ensure identical behavior across all backends, we disallow 1209 assignment to these values if pixel local storage uniforms have been 1210 declared. 1211 1212 * EXT_blend_func_extended: nonzero values of the <index> layout qualifier 1213 are illegal 1214 1215 Nonzero <index> values may restrict the number of draw buffers, which 1216 can invalidate a PLS implementation. 1217 1218 * EXT_blend_func_extended: multiple unassigned fragment output locations 1219 are illegal 1220 1221 Since PLS may use additional internal fragment outputs, we ban all 1222 implicit fragment output assignments while PLS is in use. 1223 1224 * KHR_blend_equation_advanced: "blend_support" layout qualifiers are 1225 illegal 1226 1227 KHR_blend_equation_advanced is incompatible with multiple draw 1228 buffers, which is a required feature for many PLS implementations. 1229 1230 Modify Section 4.3.8 "Layout Qualifiers" 1231 1232 (Insert a new numbered section after 4.3.8.3 "Uniform Block Layout 1233 Qualifiers") 1234 1235 Section 4.3.8.X "Pixel Local Storage Layout Qualifiers" 1236 1237 The layout qualifier identifiers for pixel local storage types are: 1238 1239 layout-qualifier-id 1240 binding = <integer-constant> 1241 <format> 1242 1243 Accepable identifiers for <format> are enumerated in Table X.4. 1244 1245 It is a compile-time error to declare a pixel local storage uniform that 1246 does not specify both of these layout qualifiers, or to specify a format 1247 layout qualifier on any type other than that format's corresponding "Pixel 1248 Local Type", as enumerated in Table X.4. 1249 1250 Modify Section 8 "Built-in Functions" 1251 1252 (Insert a new numbered section after 8.9 "Fragment Processing Functions".) 1253 1254 Section 8.X "Pixel Local Storage Functions" 1255 1256 The built-in functions defined in this section accept pixel local storage 1257 handles (abbreviated as "PLS handles") in order to load and store data 1258 associated with the pixel being covered. 1259 1260 A reference to a specific PLS plane is established by indexing into the 1261 current draw framebuffer's PLS planes using the PLS handle's "binding" 1262 layout qualifier. If any PLS handle references an inactive PLS plane, or a 1263 PLS plane whose internalformat does not match the handle's format, the 1264 shader does not execute and a draw-time error is generated in the OpenGL ES 1265 API instead. 1266 1267 Syntax: 1268 1269 vec4 pixelLocalLoadANGLE(pixelLocalANGLE handle) 1270 ivec4 pixelLocalLoadANGLE(ipixelLocalANGLE handle) 1271 uvec4 pixelLocalLoadANGLE(upixelLocalANGLE handle) 1272 1273 Description: 1274 1275 Reads the current pixel's data from the PLS plane referenced by <handle>. 1276 1277 Syntax: 1278 1279 void pixelLocalStoreANGLE(pixelLocalANGLE handle, vec4 value) 1280 void pixelLocalStoreANGLE(ipixelLocalANGLE handle, ivec4 value) 1281 void pixelLocalStoreANGLE(upixelLocalANGLE handle, uvec4 value) 1282 1283 Description: 1284 1285 Replaces the current pixel's data with <value> in the PLS plane referenced 1286 by <handle>. If the magnitude of <value> is too large to be represented in 1287 the PLS format, it is clamped. 1288 1289 Modify Section 9 "Shading Language Grammar" 1290 1291 (Add the following tokens to the lexical analysis.) 1292 1293 PIXELLOCALANGLE IPIXELLOCALANGLE UPIXELLOCALANGLE 1294 1295 1296Interactions with GLSL ES 3.10 1297 1298 If GLSL ES 3.10 is supported, pixel local storage and images cannot be used 1299 in the same shader; it is a compile time error for a shader to declare both 1300 image uniforms and pixel local storage uniforms. 1301 1302 1303Issues 1304 1305 (1) EXT_shader_pixel_local_storage has a clause that PLS contents become 1306 undefined if an application causes color data to be flushed to the 1307 framebuffer. Can we use this extension and still guarantee the security of 1308 WebGL? 1309 1310 RESOLVED: We have confirmation that all mobile vendors guarantee there's 1311 no data leaked from outside the render pass. There can be data leaked from 1312 normal framebuffer attachments to PLS planes, but said attachments 1313 themselves are not shared between WebGL contexts, so should not be a 1314 security concern. 1315 1316 Imagination gave the caveat that we must also initialize PLS data up front 1317 in order to not get left-over data from a previous render pass, but this 1318 is exactly what our API is designed to do via load operations. If 1319 EXT_shader_pixel_local_storage2 is supported, we can clear PLS using 1320 ClearPixelLocalStorageuiEXT(). Otherwise, we can clear or load PLS data 1321 from a texture by issuing a fullscreen draw. 1322 1323 Additionally, if the browser uses virtual contexts and wishes to interrupt 1324 a PLS render pass, it must be sure to internally call 1325 FramebufferPixelLocalStorageInterruptANGLE() before handing off control to 1326 the other virtual context, and FramebufferPixelLocalStorageRestoreANGLE() 1327 again before returning control. 1328 1329 (2) Depending on the implementation, <loadops> of LOAD_OP_ZERO_ANGLE and 1330 LOAD_OP_LOAD_ANGLE can have very different performance characteristics. 1331 Would a <loadop> of DONT_CARE, which makes the PLS contents undefined, be 1332 acceptable in WebGL? 1333 1334 RESOLVED: From a security standpoint, the crucial aspect is that the data 1335 doesn't come from another context, and that needs to be specified. Similar 1336 decisions have been made previously in performance-critical areas of the 1337 spec. 1338 1339 (3) Should we support the ability to enable/disable pixel local storage 1340 planes on an individual basis? (e.g., "LOAD_OP_DISABLE_ANGLE".) 1341 1342 RESOLVED: No. Some implementations need to reserve color attachments for 1343 internal use. Allowing any combination of planes to be enabled or disabled 1344 would make this specification unnecessarily complex. Furthermore, browsers 1345 implementing WebGL will need the ability to interrupt pixel local storage 1346 rendering passes, which would also be more complicated if we were to 1347 support enabling and disabling planes individually. 1348 1349 (4) Should we support binding cube map layers to pixel local storage? 1350 1351 RESOLVED: No. There is currently a 1:1 mapping on every implementation 1352 from pixel local storage shaders to backend shaders, but binding a cube 1353 map layer would require a texelFetch() implementation to behave 1354 differently in the shader. We can always add cube map support in the 1355 future, if the need arises. 1356 1357 (5) Can we support transform feedback? 1358 1359 RESOLVED: No. Transform feedback can lead to render pass breaks in the 1360 Vulkan backend. 1361