1Name 2 3 ARB_ES3_1_compatibility 4 5Name Strings 6 7 GL_ARB_ES3_1_compatibility 8 9Contact 10 11 Piers Daniell, NVIDIA Corporation (pdaniell 'at' nvidia.com) 12 13Contributors 14 15 Daniel Koch, NVIDIA Corporation (dkoch 'at' nvidia.com) 16 17 and contributors to the OpenGL ES 3.1 specification 18 19Notice 20 21 Copyright (c) 2014 The Khronos Group Inc. Copyright terms at 22 http://www.khronos.org/registry/speccopyright.html 23 24Specification Update Policy 25 26 Khronos-approved extension specifications are updated in response to 27 issues and bugs prioritized by the Khronos OpenGL Working Group. For 28 extensions which have been promoted to a core Specification, fixes will 29 first appear in the latest version of that core Specification, and will 30 eventually be backported to the extension document. This policy is 31 described in more detail at 32 https://www.khronos.org/registry/OpenGL/docs/update_policy.php 33 34Status 35 36 Complete. 37 Approved by the ARB on June 26, 2014. 38 Ratified by the Khronos Board of Promoters on August 7, 2014. 39 40Version 41 42 Last Modified Date: September 19, 2014 43 Revision: 15 44 45Number 46 47 ARB Extension #159 48 49Dependencies 50 51 OpenGL 4.4, ARB_ES2_compatibility, ARB_ES3_compatibility are required. 52 53 This extension is written against The OpenGL 4.4 (Compatibility Profile) 54 specification. 55 56Overview 57 58 This extension adds support for features of OpenGL ES 3.1 that are 59 missing from OpenGL 4.4. Enabling these features will ease the process 60 of porting applications from OpenGL ES 3.1 to OpenGL. 61 62 In particular this adds the following features: 63 64 - a new MemoryBarrierByRegion API which is potentially more efficient 65 for specific localized memory access patterns. 66 67 - increases the minimum required size of SSBOs to 2^27 (128 MB). 68 69 - support for GLSL ES version 310 (ie #version 310 es). 70 71 - a new GLSL built-in function, imageAtomicExchange, which performs atomic 72 exchanges on r32f floating point images. 73 74 - a new GLSL built-in fragment shader input, gl_HelperInvocation, that 75 identifies whether the current fragment shader input is a helper 76 invocation. Fragment shader code can use this variable to skip performing 77 operations that are useless or potentially dangerous for helper 78 invocations. 79 80 - a new GLSL built-in constant for the maximum supported samples: 81 gl_MaxSamples. 82 83 - a number of new GLSL built-in constants mirroring the API limits for 84 image uniforms: gl_Max*ImageUniforms, gl_MaxCombinedShaderOutputResources. 85 86 - new GLSL built-in functions which extend mix() to select between int, 87 uint, and bool components. 88 89 - add the "coherent" qualifier to all memory variables taken by the GLSL 90 built-in atomic* and imageAtomic* functions. 91 92New Procedures and Functions 93 94 void MemoryBarrierByRegion(bitfield barriers); 95 96New Tokens 97 98 None 99 100Additions to Chapter 1 of the OpenGL 4.4 (Compatibility Profile) 101Specification (Introduction) 102 103 Modify section 1.3.2 (OpenGL ES) to include mention of OpenGL ES 3.1: 104 105 OpenGL ES is a ... well-defined subsets of OpenGL. OpenGL ES version 106 1.1 implements a subset of the OpenGL 1.5 fixed-function API, OpenGL 107 ES 2.0 implements a subset of the OpenGL 2.0 shader-based API, OpenGL 108 ES 3.0 implements a subset of OpenGL 3.3, and OpenGL ES 3.1 implements 109 a subset of OpenGL 4.3. OpenGL ES versions also include ... 110 111 OpenGL and OpenGL ES are developed ... 112 113 OpenGL implementations supporting this extension include functionality 114 initially defined in OpenGL ES 3.1, for increased compatibility between 115 OpenGL and OpenGL ES implementations. 116 117 118 Modify section 1.3.3 (OpenGL ES Shading Language) to include mention 119 of version 3.10: 120 121 The Specification should also be read together with companion documents 122 titled "The OpenGL ES Shading Language". Versions 1.00, 3.00 and 3.10 123 should be read. These documents define versions of the OpenGL ES Shading 124 Language designed for implementations of OpenGL ES 2.0, 3.0 and 3.1, 125 respectively, but also supported by OpenGL implementations. References ... 126 127 OpenGL implementations supporting this extensions are guaranteed to 128 support versions 1.00, 3.00 and 3.10 of the OpenGL ES Shading Language. 129 130 131Additions to Chapter 7 of the OpenGL 4.4 (Compatibility Profile) 132Specification (Programs and Shaders) 133 134 Modify Section 7.12.2, "Shader Memory Access Synchronization", (p. 148) 135 136 (Append to the end of the section) 137 138 "The command 139 140 void MemoryBarrierByRegion(bitfield barriers) 141 142 behaves as described above for MemoryBarrier, with two differences: 143 144 First, it narrows the region under consideration so that only reads/writes 145 of prior fragment shaders that are invoked for a smaller region of the 146 framebuffer will be completed/reflected prior to subsequent reads/write of 147 following fragment shaders. The size of the region is implementation 148 dependent and may be as small as one framebuffer pixel. 149 150 Second, it only applies to memory transactions that may be read by or 151 written by a fragment shader. Therefore, only the barrier bits 152 - ATOMIC_COUNTER_BARRIER_BIT 153 - FRAMEBUFFER_BARRIER_BIT 154 - SHADER_IMAGE_ACCESS_BARRIER_BIT 155 - SHADER_STORAGE_BARRIER_BIT 156 - TEXTURE_FETCH_BARRIER_BIT 157 - UNIFORM_BARRIER_BIT 158 are supported. 159 160 When barriers is ALL_BARRIER_BITS, shader memory accesses will be 161 synchronized relative to all these barrier bits, but not to other barrier 162 bits specific to MemoryBarrier. This implies that reads/writes for 163 scatter/gather-like algorithms may or may not be completed/reflected after 164 a MemoryBarrierByRegion command. However, for uses such as deferred 165 shading, where a linked list of visible surfaces with the head at a 166 framebuffer address may be constructed, and the entirety of the list is 167 only dependent on previous executions at that framebuffer address, 168 MemoryBarrierByRegion may be significantly more efficient than 169 MemoryBarrier." 170 171 172Additions to Chapter 9 of the OpenGL 4.4 (Compatibility Profile) 173Specification (Framebuffers and Framebuffer Objects) 174 175 Modify Section 9.2.3 (Framebuffer Object Queries) in the second 176 paragraph describing GetFramebufferAttachmentParameteriv to add BACK as 177 a valid <attachment>: 178 179 "If the default framebuffer is bound to <target>, then <attachment> must 180 be one of FRONT_LEFT, FRONT_RIGHT, BACK, BACK_LEFT, or BACK_RIGHT, 181 identifying a color buffer; ... identifying the stencil buffer. Since 182 this command can only query a single framebuffer attachment, BACK is 183 equivalent to BACK_LEFT." 184 185 Modify the first paragraph of Section 9.4.5 (Effects of 186 Framebuffer State on Framebuffer Dependent Values) 187 188 "The values of the state variables listed in table 23.85 may change when 189 a change is made to the current framebuffer binding, to the state of the 190 currently bound framebuffer object, or to an image attached to that 191 framebuffer object. Most such state is dependent on the draw framebuffer 192 (DRAW_FRAMEBUFFER_BINDING), but IMPLEMENTATION_COLOR_READ_TYPE and 193 IMPLEMENTATION_COLOR_READ_FORMAT are dependent on the read framebuffer 194 (READ_FRAMEBUFFER_BINDING)." 195 196 197Additions to Chapter 15 of the OpenGL 4.4 (Compatibility Profile) 198Specification (Programmable Fragment Processing) 199 200 Modify Section 15.2.2 (Shader Inputs), (p. 530, 5th paragraph) 201 202 "The built-in variable gl_SampleMaskIn is an integer array... 203 The number of elements in the array is ceil(gl_MaxSamples/32), where 204 gl_MaxSamples is the value of MAX_SAMPLES, the maximum number of 205 color samples supported by the implementation. Bit <n> ... " 206 207 Modify Section 15.2.3 (Shader Outputs), (p. 532, 2nd paragraph) 208 209 "The built-in integer array gl_SampleMask can be used ... 210 The number of elements in the arrays is ceil(gl_MaxSamples/32), where 211 gl_MaxSamples is the value of MAX_SAMPLES, the maximum number of 212 color samples supported by the implementation. If bit <n> ... " 213 214 215Additions to Chapter 17 of the OpenGL 4.4 (Compatibility Profile) 216Specification (Writing Fragments and Samples to the Framebuffer) 217 218 Modify Section 17.4.1 (Selecting Buffers for Writing), (p. 572, 219 2nd paragraph) 220 221 "If the GL is bound to the default framebuffer, then each of the 222 constants must be one of the values listed in table 17.6 or the 223 special value BACK. When the value BACK is used then <n> must 224 be 1 and color values are written into the left buffer for 225 single-buffered contexts, or into the back left buffer for double- 226 buffered contexts. An INVALID_OPERATION error is generated if 227 <bufs> contains the value BACK and <n> does not equal 1." 228 229 230Additions to Chapter 18 of the OpenGL 4.4 (Compatibility Profile) 231Specification (Drawing, Reading, and Copying Pixels) 232 233 Modify Section 18.2.1 (Selecting Buffers for Reading), (p. 589) 234 235 Remove the last paragraph that describes the 236 IMPLEMENTATION_COLOR_READ_FORMAT and IMPLEMENTATION_COLOR_READ_TYPE 237 queries and errors. 238 239 Modify Section 18.2.2 (ReadPixels), (p. 589) 240 241 Add the following paragraph at the end of the section: 242 243 "The preferred parameters for <format> and <type> may be determined by 244 calling GetIntegerv with the symbolic constants 245 IMPLEMENTATION_COLOR_READ_FORMAT and IMPLEMENTATION_COLOR_READ_TYPE, 246 respectively. The implementation chosen format may vary depending on the 247 format of the selected read buffer of the currently bound read 248 framebuffer. 249 250 An INVALID_OPERATION error is generated by GetIntegerv if pname is 251 IMPLEMENTATION_COLOR_READ_FORMAT or IMPLEMENTATION_COLOR_READ_TYPE and 252 any of: 253 - the read framebuffer is not framebuffer complete 254 - the read framebuffer is a framebuffer object, and the selected read buffer 255 (see section 18.2.1) has no image attached 256 - the selected read buffer is NONE 257 " 258 259Additions to Chapter 22 of the OpenGL 4.4 (Compatibility Profile) 260Specification (Context State Queries) 261 262 Modify Section 22.2 (Pointer and String Queries), (p. 648) 263 264 "If <name> is SHADING_LANGUAGE_VERSION, ... 265 Version strings "100", "300 es" and "310 es" correspond to the OpenGL 266 ES Shading Language versions 100, 300 and 310, respectively." 267 268 269 270Additions to the OpenGL Shading Language 271 272 Including the following line in a shader can be used to control the 273 language features described in this extension: 274 275 #extension GL_ARB_ES3_1_compatibility : <behavior> 276 277 where <behavior> is as specified in section 3.3. 278 279 New preprocessor #defines are added to the OpenGL Shading Language: 280 281 #define GL_ARB_ES3_1_compatibility 1 282 283 284Additions to Chapter 3 of the OpenGL Shading Language 4.40.8 Specification 285(Basics) 286 287 Modify the paragraph at the bottom of page 16 in Section 3.3 288 (Preprocessor) as follows: 289 290 "... Shaders that specify #version 100 will be treated as targeting 291 version 1.00 of the OpenGL ES Shading Language. Shaders that specify 292 #version 300 will be treated as targeting version 3.00 of the OpenGL 293 ES Shading Language. Shaders that specify #version 310 will be treated 294 as targeting version 3.10 of the OpenGL ES Shading Language. ..." 295 296 Modify the 3rd paragraph at the top of p16 as follows: 297 298 A <profile> argument ... 299 If version 300 or 310 is specified, the profile argument is not optional 300 and must be "es", or a compile-time error results. The Language 301 Specification ... 302 303 304Additions to Chapter 4 of the OpenGL Shading Language 4.40.8 Specification 305(Variables and Types) 306 307 Modify Section 4.7.2 (Precision Qualifiers) 308 309 (Replace the first sentence to reference all opaque types instead of just 310 samplers) 311 312 "Any floating point, integer, or opaque-type declaration can have the 313 type preceded by one of these precision qualifiers: ..." 314 315 Modify Section 4.7.3 (Default Precision Qualifiers) 316 317 (Replace the second sentence to reference all opaque types and not just 318 samples) 319 320 "The type field can be either int or float, any of the opaque types, and 321 the precision-qualifier can be lowp, mediump, or highp. ..." 322 323 324Additions to Chapter 7 of the OpenGL Shading Language 4.40.8 Specification 325(Built-in Variables) 326 327 Modify Section 7.1, Built-In Language Variables (p. 122) 328 329 (Add to list of fragment language built-in variables on page 122) 330 331 in bool gl_HelperInvocation; 332 333 (Add after the description of gl_SamplePosition on page 127) 334 335 "The value gl_HelperInvocation is true if the fragment shader invocation is 336 considered a "helper invocation" and is false otherwise. A "helper 337 invocation" is a fragment-shader invocation that is created solely for the 338 purposes of evaluating derivatives for use in non-helper fragment-shader 339 invocations. Such derivatives are computed implicitly in the built-in 340 function texture() (see section 8.9 "Texture Functions"), and explicitly in 341 the derivative functions in section 8.13.1 "Derivative Functions", for 342 example dFdx() and dFdy(). 343 344 Fragment shader helper invocations execute the same shader code as 345 non-helper invocations, but will not have side effects that modify the 346 framebuffer or other shader-accessible memory. In particular: 347 348 * Fragments corresponding to helper invocations are discarded when 349 shader execution is complete, without updating the framebuffer. 350 351 * Stores to image and buffer variables performed by helper invocations 352 have no effect on the underlying image or buffer memory. 353 354 * Atomic operations to image, buffer, or atomic counter variables 355 performed by helper invocations have no effect on the underlying image 356 or buffer memory. The values returned by such atomic operations are 357 undefined. 358 359 Helper invocations may be generated for pixels not covered by a primitive 360 being rendered. While fragment shader inputs qualified with "centroid" 361 are normally required to be sampled in the intersection of the pixel and 362 the primitive, the requirement is ignored for such pixels since there is 363 no intersection between the pixel and primitive. 364 365 Helper invocations may also be generated for fragments that are covered by 366 a primitive being rendered when the fragment is killed by early fragment 367 tests (using the "early_fragment_tests" qualifier) or where the 368 implementation is able to determine that executing the fragment shader 369 would have no effect other than assisting in computing derivatives for 370 other fragment shader invocations. 371 372 The set of helper invocations generated when processing any set of 373 primitives is implementation-dependent." 374 375 Add to section 7.3 Built-in Constants 376 377 const int gl_MaxSamples = 4; 378 379 const int gl_MaxVertexImageUniforms = 0; 380 const int gl_MaxFragmentImageUniforms = 8; 381 const int gl_MaxComputeImageUniforms = 8; 382 const int gl_MaxCombinedImageUniforms = 48; 383 const int gl_MaxCombinedShaderOutputResources = 16; 384 385Additions to Chapter 8 of the OpenGL Shading Language 4.40.8 Specification 386(Built-in Functions) 387 388 Modify Section 8.3, Common Functions 389 390 (Additions to the table listing common built-in functions) 391 392 Syntax Description 393 --------------------------- -------------------------------------------------- 394 genIType mix(genIType x, Selects which vector each returned component comes 395 genIType y, from. For a component of a that is false, the 396 genBType a) corresponding component of x is returned. For a 397 genUType mix(genUType x, component of a that is true, the corresponding 398 genUType y, component of y is returned. 399 genBType a) 400 genBType mix(genBType x, 401 genBType y, 402 genBType a) 403 404 Modify Section 8.11, Atomic Memory Functions 405 406 (Modify the table on page 173 by adding "coherent" qualifier to all memory 407 variables.) 408 409 Syntax Description 410 ---------------------------------------- --------------------------------------------------- 411 uint atomicAdd(coherent inout uint mem, Computes a new value by adding the value of data to 412 uint data) the contents mem. 413 int atomicAdd(coherent inout int mem, 414 int data) 415 416 uint atomicMin(coherent inout uint mem, Computes a new value by taking the minimum of the 417 uint data) value of data and the contents of mem. 418 int atomicMin(coherent inout int mem, 419 int data) 420 421 uint atomicMax(coherent inout uint mem, Computes a new value by taking the maximum of the 422 uint data) value of data and the contents of mem. 423 int atomicMax(coherent inout int mem, 424 int data) 425 426 uint atomicAnd(coherent inout uint mem, Computes a new value by performing a bit-wise 427 uint data) AND of the value of data and the contents of mem. 428 int atomicAnd(coherent inout int mem, 429 int data) 430 431 uint atomicOr(coherent inout uint mem, Computes a new value by performing a bit-wise OR 432 uint data) of the value of data and the contents of mem. 433 int atomicOr(coherent inout int mem, 434 int data) 435 436 uint atomicXor(coherent inout uint mem, Computes a new value by performing a bit-wise 437 uint data) EXCLUSIVE OR of the value of data and the 438 int atomicXor(coherent inout int mem, contents of mem. 439 int data) 440 441 uint atomicExchange( Computes a new value by simply copying the value 442 coherent inout uint mem, of data. 443 uint data) 444 int atomicExchange( 445 coherent inout int mem, 446 int data) 447 448 uint atomicCompSwap( Compares the value of compare and the contents of 449 coherent inout uint mem, mem. If the values are equal, the new value is given 450 uint compare, by data; otherwise, it is taken from the original 451 uint data) contents of mem. 452 int atomicCompSwap( 453 coherent inout int mem, 454 int compare, 455 int data) 456 457 Modify Section 8.12, Image Functions 458 459 (Modify the table section listing imageAtomic* on page 175 by adding 460 the "coherent" qualifier to the image parameter and adding a new 461 imageAtomicExchange function for float data.) 462 463 Syntax Description 464 ------------------------------ --------------------------------------------------- 465 uint imageAtomicAdd( Computes a new value by adding the value of data 466 coherent IMAGE_PARAMS, to the contents of the selected texel. 467 uint data) 468 int imageAtomicAdd( 469 coherent IMAGE_PARAMS, 470 int data) 471 472 uint imageAtomicMin( Computes a new value by taking the minimum of the 473 coherent IMAGE_PARAMS, value of data and the contents of the selected texel. 474 uint data) 475 int imageAtomicMin( 476 coherent IMAGE_PARAMS, 477 int data) 478 479 uint imageAtomicMax( Computes a new value by taking the maximum of the 480 coherent IMAGE_PARAMS, value data and the contents of the selected texel. 481 uint data) 482 int imageAtomicMax( 483 coherent IMAGE_PARAMS, 484 int data) 485 486 uint imageAtomicAnd( Computes a new value by performing a bit-wise 487 coherent IMAGE_PARAMS, AND of the value of data and the contents of the 488 uint data) selected texel. 489 int imageAtomicAnd( 490 coherent IMAGE_PARAMS, 491 int data) 492 493 uint imageAtomicOr( Computes a new value by performing a bit-wise OR 494 coherent IMAGE_PARAMS, of the value of data and the contents of the selected 495 uint data) texel. 496 int imageAtomicOr( 497 coherent IMAGE_PARAMS, 498 int data) 499 500 uint imageAtomicXor( Computes a new value by performing a bit-wise 501 coherent IMAGE_PARAMS, EXCLUSIVE OR of the value of data and the 502 uint data) contents of the selected texel. 503 int imageAtomicXor( 504 coherent IMAGE_PARAMS, 505 int data) 506 507 uint imageAtomicExchange( Computes a new value by simply copying the value of 508 coherent IMAGE_PARAMS, <data>. These functions support 32-bit signed and 509 uint data); unsigned integer operands, and 32-bit float operands. 510 int imageAtomicExchange( 511 coherent IMAGE_PARAMS, 512 int data); 513 float imageAtomicExchange( 514 coherent IMAGE_PARAMS, 515 float data); 516 517 uint imageAtomicCompSwap( Compares the value of compare and the contents of 518 coherent IMAGE_PARAMS, the selected texel. If the values are equal, the new 519 uint compare, value is given by data; otherwise, it is taken from the 520 uint data) original value loaded from the texel. 521 int imageAtomicCompSwap( 522 coherent IMAGE_PARAMS, 523 int compare, 524 int data) 525 526Additions to the AGL/GLX/WGL Specifications 527 528 None 529 530Errors 531 532 An INVALID_VALUE is generated by MemoryBarrier or MemoryBarrierByRegion 533 if barriers is not the special value ALL_BARRIER_BITS and any of the 534 unsupported bits are set. 535 536New State 537 538 (Modify Table 23.64 - Implementation Dependent Values) 539 540 Remove IMPLEMENTATION_COLOR_READ_FORMAT and IMPLEMENTATION_COLOR_READ_TYPE. 541 542 (Modify Table 23.76 - Implementation Dependent Aggregate Shader Limits) 543 544 Increase the minimum required value of MAX_SHADER_STORAGE_BLOCK_SIZE to 2^27. 545 546 (Modify Table 23.85 - Framebuffer Dependent Values) 547 548 Add the following entries: 549 550 Get Value Type Get Command Minimum Value Description Sec 551 -------------------------------- ---- ----------- ------------- ------------------------------ ---- 552 IMPLEMENTATION_COLOR_READ_TYPE E GetIntegerv - Implementation preferred pixel 18.2 553 type* 554 IMPLEMENTATION_COLOR_READ_FORMAT E GetIntegerv - Implementation preferred pixel 18.2 555 format* 556 557 "* Unlike most framebuffer-dependent state which is queried from the currently bound 558 draw framebuffer, this state is queried from the currently bound read framebuffer." 559 560 561Issues 562 563 1) With this extension, is OpenGL 4.4 a complete superset of OpenGL ES 3.1? 564 565 RESOLVED: No, there are things in OpenGL ES 3.1 that were once in OpenGL 566 but have since been deprecated and removed. There is no plan to bring 567 these back into core OpenGL. Here is a list of those things: 568 569 - Application-generated object names. 570 571 - Client vertex and index arrays. 572 573 - Default vertex array object. 574 575 - ALPHA, LUMINANCE and LUMINANCE_ALPHA pixel formats. 576 577 - RED_BITS, GREEN_BITS, BLUE_BITS, DEPTH_BITS and STENCIL_BITS. 578 579 - GENERATE_MIPMAP_HINT and automatic mipmap generation. 580 581 - ALIASED_POINT_SIZE_RANGE query. 582 583 - Line widths greater than 1. 584 585 - Query of EXTENSIONS with GetString. 586 587 In addition the error FRAMEBUFFER_INCOMPLETE_DIMENSIONS was in ES2 and the 588 token remains in ES3 and above, but ES3 and above cannot generate this 589 error. This has not been added to OpenGL core. 590 591Revision History 592 593 Rev. Date Author Changes 594 ---- -------- -------- ----------------------------------------------- 595 15 09/19/14 Jon Leech Remove FRONT as valid <attachment>. 596 597 14 09/18/14 Jon Leech Add FRONT and BACK as valid <attachment>s for 598 GetFramebufferAttachmentParameteriv (Bug 599 12695). 600 601 13 05/08/14 pdaniell Allow precision qualifiers to be used with any 602 opaque type, and not just samplers. 603 604 12 05/01/14 pdaniell Add #extension support. 605 606 11 04/17/14 pdaniell Improve support for the 607 IMPLEMENTATION_COLOR_READ_FORMAT and 608 IMPLEMENTATION_COLOR_READ_TYPE queries to match 609 the OpenGL ES 3.1 spec. 610 611 10 04/16/14 pdaniell Add ES compatibility for calling DrawBuffers 612 with BACK. 613 614 9 03/20/14 pdaniell Update glMemoryBarrierByRegion language to 615 match latest OpenGL ES 3.1 spec. 616 617 8 03/15/14 dkoch Update overview to specifically itemize the 618 additions. 619 620 7 03/13/14 pdaniell Remove fixes for ARB_vertex_attrib_binding 621 which have now gone into an OpenGL 4.4 update. 622 623 6 03/07/14 pdaniell Update language for glMemoryBarrierByRegion to 624 the latest ES 3.1 spec. 625 626 5 03/04/14 pdaniell Add some more built-in constants for shader 627 image load store. 628 629 4 03/04/14 dkoch Remove unnecessary edits (Bug 11802). 630 631 3 03/02/14 dkoch More complete first draft. 632 633 2 02/27/14 pdaniell Complete the first draft. 634 635 1 12/20/13 pdaniell Initial draft with overview only. 636