Name ARB_ES3_1_compatibility Name Strings GL_ARB_ES3_1_compatibility Contact Piers Daniell, NVIDIA Corporation (pdaniell 'at' nvidia.com) Contributors Daniel Koch, NVIDIA Corporation (dkoch 'at' nvidia.com) and contributors to the OpenGL ES 3.1 specification Notice Copyright (c) 2014 The Khronos Group Inc. Copyright terms at http://www.khronos.org/registry/speccopyright.html Specification Update Policy Khronos-approved extension specifications are updated in response to issues and bugs prioritized by the Khronos OpenGL Working Group. For extensions which have been promoted to a core Specification, fixes will first appear in the latest version of that core Specification, and will eventually be backported to the extension document. This policy is described in more detail at https://www.khronos.org/registry/OpenGL/docs/update_policy.php Status Complete. Approved by the ARB on June 26, 2014. Ratified by the Khronos Board of Promoters on August 7, 2014. Version Last Modified Date: September 19, 2014 Revision: 15 Number ARB Extension #159 Dependencies OpenGL 4.4, ARB_ES2_compatibility, ARB_ES3_compatibility are required. This extension is written against The OpenGL 4.4 (Compatibility Profile) specification. Overview This extension adds support for features of OpenGL ES 3.1 that are missing from OpenGL 4.4. Enabling these features will ease the process of porting applications from OpenGL ES 3.1 to OpenGL. In particular this adds the following features: - a new MemoryBarrierByRegion API which is potentially more efficient for specific localized memory access patterns. - increases the minimum required size of SSBOs to 2^27 (128 MB). - support for GLSL ES version 310 (ie #version 310 es). - a new GLSL built-in function, imageAtomicExchange, which performs atomic exchanges on r32f floating point images. - a new GLSL built-in fragment shader input, gl_HelperInvocation, that identifies whether the current fragment shader input is a helper invocation. Fragment shader code can use this variable to skip performing operations that are useless or potentially dangerous for helper invocations. - a new GLSL built-in constant for the maximum supported samples: gl_MaxSamples. - a number of new GLSL built-in constants mirroring the API limits for image uniforms: gl_Max*ImageUniforms, gl_MaxCombinedShaderOutputResources. - new GLSL built-in functions which extend mix() to select between int, uint, and bool components. - add the "coherent" qualifier to all memory variables taken by the GLSL built-in atomic* and imageAtomic* functions. New Procedures and Functions void MemoryBarrierByRegion(bitfield barriers); New Tokens None Additions to Chapter 1 of the OpenGL 4.4 (Compatibility Profile) Specification (Introduction) Modify section 1.3.2 (OpenGL ES) to include mention of OpenGL ES 3.1: OpenGL ES is a ... well-defined subsets of OpenGL. OpenGL ES version 1.1 implements a subset of the OpenGL 1.5 fixed-function API, OpenGL ES 2.0 implements a subset of the OpenGL 2.0 shader-based API, OpenGL ES 3.0 implements a subset of OpenGL 3.3, and OpenGL ES 3.1 implements a subset of OpenGL 4.3. OpenGL ES versions also include ... OpenGL and OpenGL ES are developed ... OpenGL implementations supporting this extension include functionality initially defined in OpenGL ES 3.1, for increased compatibility between OpenGL and OpenGL ES implementations. Modify section 1.3.3 (OpenGL ES Shading Language) to include mention of version 3.10: The Specification should also be read together with companion documents titled "The OpenGL ES Shading Language". Versions 1.00, 3.00 and 3.10 should be read. These documents define versions of the OpenGL ES Shading Language designed for implementations of OpenGL ES 2.0, 3.0 and 3.1, respectively, but also supported by OpenGL implementations. References ... OpenGL implementations supporting this extensions are guaranteed to support versions 1.00, 3.00 and 3.10 of the OpenGL ES Shading Language. Additions to Chapter 7 of the OpenGL 4.4 (Compatibility Profile) Specification (Programs and Shaders) Modify Section 7.12.2, "Shader Memory Access Synchronization", (p. 148) (Append to the end of the section) "The command void MemoryBarrierByRegion(bitfield barriers) behaves as described above for MemoryBarrier, with two differences: First, it narrows the region under consideration so that only reads/writes of prior fragment shaders that are invoked for a smaller region of the framebuffer will be completed/reflected prior to subsequent reads/write of following fragment shaders. The size of the region is implementation dependent and may be as small as one framebuffer pixel. Second, it only applies to memory transactions that may be read by or written by a fragment shader. Therefore, only the barrier bits - ATOMIC_COUNTER_BARRIER_BIT - FRAMEBUFFER_BARRIER_BIT - SHADER_IMAGE_ACCESS_BARRIER_BIT - SHADER_STORAGE_BARRIER_BIT - TEXTURE_FETCH_BARRIER_BIT - UNIFORM_BARRIER_BIT are supported. When barriers is ALL_BARRIER_BITS, shader memory accesses will be synchronized relative to all these barrier bits, but not to other barrier bits specific to MemoryBarrier. This implies that reads/writes for scatter/gather-like algorithms may or may not be completed/reflected after a MemoryBarrierByRegion command. However, for uses such as deferred shading, where a linked list of visible surfaces with the head at a framebuffer address may be constructed, and the entirety of the list is only dependent on previous executions at that framebuffer address, MemoryBarrierByRegion may be significantly more efficient than MemoryBarrier." Additions to Chapter 9 of the OpenGL 4.4 (Compatibility Profile) Specification (Framebuffers and Framebuffer Objects) Modify Section 9.2.3 (Framebuffer Object Queries) in the second paragraph describing GetFramebufferAttachmentParameteriv to add BACK as a valid : "If the default framebuffer is bound to , then must be one of FRONT_LEFT, FRONT_RIGHT, BACK, BACK_LEFT, or BACK_RIGHT, identifying a color buffer; ... identifying the stencil buffer. Since this command can only query a single framebuffer attachment, BACK is equivalent to BACK_LEFT." Modify the first paragraph of Section 9.4.5 (Effects of Framebuffer State on Framebuffer Dependent Values) "The values of the state variables listed in table 23.85 may change when a change is made to the current framebuffer binding, to the state of the currently bound framebuffer object, or to an image attached to that framebuffer object. Most such state is dependent on the draw framebuffer (DRAW_FRAMEBUFFER_BINDING), but IMPLEMENTATION_COLOR_READ_TYPE and IMPLEMENTATION_COLOR_READ_FORMAT are dependent on the read framebuffer (READ_FRAMEBUFFER_BINDING)." Additions to Chapter 15 of the OpenGL 4.4 (Compatibility Profile) Specification (Programmable Fragment Processing) Modify Section 15.2.2 (Shader Inputs), (p. 530, 5th paragraph) "The built-in variable gl_SampleMaskIn is an integer array... The number of elements in the array is ceil(gl_MaxSamples/32), where gl_MaxSamples is the value of MAX_SAMPLES, the maximum number of color samples supported by the implementation. Bit ... " Modify Section 15.2.3 (Shader Outputs), (p. 532, 2nd paragraph) "The built-in integer array gl_SampleMask can be used ... The number of elements in the arrays is ceil(gl_MaxSamples/32), where gl_MaxSamples is the value of MAX_SAMPLES, the maximum number of color samples supported by the implementation. If bit ... " Additions to Chapter 17 of the OpenGL 4.4 (Compatibility Profile) Specification (Writing Fragments and Samples to the Framebuffer) Modify Section 17.4.1 (Selecting Buffers for Writing), (p. 572, 2nd paragraph) "If the GL is bound to the default framebuffer, then each of the constants must be one of the values listed in table 17.6 or the special value BACK. When the value BACK is used then must be 1 and color values are written into the left buffer for single-buffered contexts, or into the back left buffer for double- buffered contexts. An INVALID_OPERATION error is generated if contains the value BACK and does not equal 1." Additions to Chapter 18 of the OpenGL 4.4 (Compatibility Profile) Specification (Drawing, Reading, and Copying Pixels) Modify Section 18.2.1 (Selecting Buffers for Reading), (p. 589) Remove the last paragraph that describes the IMPLEMENTATION_COLOR_READ_FORMAT and IMPLEMENTATION_COLOR_READ_TYPE queries and errors. Modify Section 18.2.2 (ReadPixels), (p. 589) Add the following paragraph at the end of the section: "The preferred parameters for and may be determined by calling GetIntegerv with the symbolic constants IMPLEMENTATION_COLOR_READ_FORMAT and IMPLEMENTATION_COLOR_READ_TYPE, respectively. The implementation chosen format may vary depending on the format of the selected read buffer of the currently bound read framebuffer. An INVALID_OPERATION error is generated by GetIntegerv if pname is IMPLEMENTATION_COLOR_READ_FORMAT or IMPLEMENTATION_COLOR_READ_TYPE and any of: - the read framebuffer is not framebuffer complete - the read framebuffer is a framebuffer object, and the selected read buffer (see section 18.2.1) has no image attached - the selected read buffer is NONE " Additions to Chapter 22 of the OpenGL 4.4 (Compatibility Profile) Specification (Context State Queries) Modify Section 22.2 (Pointer and String Queries), (p. 648) "If is SHADING_LANGUAGE_VERSION, ... Version strings "100", "300 es" and "310 es" correspond to the OpenGL ES Shading Language versions 100, 300 and 310, respectively." Additions to the OpenGL Shading Language Including the following line in a shader can be used to control the language features described in this extension: #extension GL_ARB_ES3_1_compatibility : where is as specified in section 3.3. New preprocessor #defines are added to the OpenGL Shading Language: #define GL_ARB_ES3_1_compatibility 1 Additions to Chapter 3 of the OpenGL Shading Language 4.40.8 Specification (Basics) Modify the paragraph at the bottom of page 16 in Section 3.3 (Preprocessor) as follows: "... Shaders that specify #version 100 will be treated as targeting version 1.00 of the OpenGL ES Shading Language. Shaders that specify #version 300 will be treated as targeting version 3.00 of the OpenGL ES Shading Language. Shaders that specify #version 310 will be treated as targeting version 3.10 of the OpenGL ES Shading Language. ..." Modify the 3rd paragraph at the top of p16 as follows: A argument ... If version 300 or 310 is specified, the profile argument is not optional and must be "es", or a compile-time error results. The Language Specification ... Additions to Chapter 4 of the OpenGL Shading Language 4.40.8 Specification (Variables and Types) Modify Section 4.7.2 (Precision Qualifiers) (Replace the first sentence to reference all opaque types instead of just samplers) "Any floating point, integer, or opaque-type declaration can have the type preceded by one of these precision qualifiers: ..." Modify Section 4.7.3 (Default Precision Qualifiers) (Replace the second sentence to reference all opaque types and not just samples) "The type field can be either int or float, any of the opaque types, and the precision-qualifier can be lowp, mediump, or highp. ..." Additions to Chapter 7 of the OpenGL Shading Language 4.40.8 Specification (Built-in Variables) Modify Section 7.1, Built-In Language Variables (p. 122) (Add to list of fragment language built-in variables on page 122) in bool gl_HelperInvocation; (Add after the description of gl_SamplePosition on page 127) "The value gl_HelperInvocation is true if the fragment shader invocation is considered a "helper invocation" and is false otherwise. A "helper invocation" is a fragment-shader invocation that is created solely for the purposes of evaluating derivatives for use in non-helper fragment-shader invocations. Such derivatives are computed implicitly in the built-in function texture() (see section 8.9 "Texture Functions"), and explicitly in the derivative functions in section 8.13.1 "Derivative Functions", for example dFdx() and dFdy(). Fragment shader helper invocations execute the same shader code as non-helper invocations, but will not have side effects that modify the framebuffer or other shader-accessible memory. In particular: * Fragments corresponding to helper invocations are discarded when shader execution is complete, without updating the framebuffer. * Stores to image and buffer variables performed by helper invocations have no effect on the underlying image or buffer memory. * Atomic operations to image, buffer, or atomic counter variables performed by helper invocations have no effect on the underlying image or buffer memory. The values returned by such atomic operations are undefined. Helper invocations may be generated for pixels not covered by a primitive being rendered. While fragment shader inputs qualified with "centroid" are normally required to be sampled in the intersection of the pixel and the primitive, the requirement is ignored for such pixels since there is no intersection between the pixel and primitive. Helper invocations may also be generated for fragments that are covered by a primitive being rendered when the fragment is killed by early fragment tests (using the "early_fragment_tests" qualifier) or where the implementation is able to determine that executing the fragment shader would have no effect other than assisting in computing derivatives for other fragment shader invocations. The set of helper invocations generated when processing any set of primitives is implementation-dependent." Add to section 7.3 Built-in Constants const int gl_MaxSamples = 4; const int gl_MaxVertexImageUniforms = 0; const int gl_MaxFragmentImageUniforms = 8; const int gl_MaxComputeImageUniforms = 8; const int gl_MaxCombinedImageUniforms = 48; const int gl_MaxCombinedShaderOutputResources = 16; Additions to Chapter 8 of the OpenGL Shading Language 4.40.8 Specification (Built-in Functions) Modify Section 8.3, Common Functions (Additions to the table listing common built-in functions) Syntax Description --------------------------- -------------------------------------------------- genIType mix(genIType x, Selects which vector each returned component comes genIType y, from. For a component of a that is false, the genBType a) corresponding component of x is returned. For a genUType mix(genUType x, component of a that is true, the corresponding genUType y, component of y is returned. genBType a) genBType mix(genBType x, genBType y, genBType a) Modify Section 8.11, Atomic Memory Functions (Modify the table on page 173 by adding "coherent" qualifier to all memory variables.) Syntax Description ---------------------------------------- --------------------------------------------------- uint atomicAdd(coherent inout uint mem, Computes a new value by adding the value of data to uint data) the contents mem. int atomicAdd(coherent inout int mem, int data) uint atomicMin(coherent inout uint mem, Computes a new value by taking the minimum of the uint data) value of data and the contents of mem. int atomicMin(coherent inout int mem, int data) uint atomicMax(coherent inout uint mem, Computes a new value by taking the maximum of the uint data) value of data and the contents of mem. int atomicMax(coherent inout int mem, int data) uint atomicAnd(coherent inout uint mem, Computes a new value by performing a bit-wise uint data) AND of the value of data and the contents of mem. int atomicAnd(coherent inout int mem, int data) uint atomicOr(coherent inout uint mem, Computes a new value by performing a bit-wise OR uint data) of the value of data and the contents of mem. int atomicOr(coherent inout int mem, int data) uint atomicXor(coherent inout uint mem, Computes a new value by performing a bit-wise uint data) EXCLUSIVE OR of the value of data and the int atomicXor(coherent inout int mem, contents of mem. int data) uint atomicExchange( Computes a new value by simply copying the value coherent inout uint mem, of data. uint data) int atomicExchange( coherent inout int mem, int data) uint atomicCompSwap( Compares the value of compare and the contents of coherent inout uint mem, mem. If the values are equal, the new value is given uint compare, by data; otherwise, it is taken from the original uint data) contents of mem. int atomicCompSwap( coherent inout int mem, int compare, int data) Modify Section 8.12, Image Functions (Modify the table section listing imageAtomic* on page 175 by adding the "coherent" qualifier to the image parameter and adding a new imageAtomicExchange function for float data.) Syntax Description ------------------------------ --------------------------------------------------- uint imageAtomicAdd( Computes a new value by adding the value of data coherent IMAGE_PARAMS, to the contents of the selected texel. uint data) int imageAtomicAdd( coherent IMAGE_PARAMS, int data) uint imageAtomicMin( Computes a new value by taking the minimum of the coherent IMAGE_PARAMS, value of data and the contents of the selected texel. uint data) int imageAtomicMin( coherent IMAGE_PARAMS, int data) uint imageAtomicMax( Computes a new value by taking the maximum of the coherent IMAGE_PARAMS, value data and the contents of the selected texel. uint data) int imageAtomicMax( coherent IMAGE_PARAMS, int data) uint imageAtomicAnd( Computes a new value by performing a bit-wise coherent IMAGE_PARAMS, AND of the value of data and the contents of the uint data) selected texel. int imageAtomicAnd( coherent IMAGE_PARAMS, int data) uint imageAtomicOr( Computes a new value by performing a bit-wise OR coherent IMAGE_PARAMS, of the value of data and the contents of the selected uint data) texel. int imageAtomicOr( coherent IMAGE_PARAMS, int data) uint imageAtomicXor( Computes a new value by performing a bit-wise coherent IMAGE_PARAMS, EXCLUSIVE OR of the value of data and the uint data) contents of the selected texel. int imageAtomicXor( coherent IMAGE_PARAMS, int data) uint imageAtomicExchange( Computes a new value by simply copying the value of coherent IMAGE_PARAMS, . These functions support 32-bit signed and uint data); unsigned integer operands, and 32-bit float operands. int imageAtomicExchange( coherent IMAGE_PARAMS, int data); float imageAtomicExchange( coherent IMAGE_PARAMS, float data); uint imageAtomicCompSwap( Compares the value of compare and the contents of coherent IMAGE_PARAMS, the selected texel. If the values are equal, the new uint compare, value is given by data; otherwise, it is taken from the uint data) original value loaded from the texel. int imageAtomicCompSwap( coherent IMAGE_PARAMS, int compare, int data) Additions to the AGL/GLX/WGL Specifications None Errors An INVALID_VALUE is generated by MemoryBarrier or MemoryBarrierByRegion if barriers is not the special value ALL_BARRIER_BITS and any of the unsupported bits are set. New State (Modify Table 23.64 - Implementation Dependent Values) Remove IMPLEMENTATION_COLOR_READ_FORMAT and IMPLEMENTATION_COLOR_READ_TYPE. (Modify Table 23.76 - Implementation Dependent Aggregate Shader Limits) Increase the minimum required value of MAX_SHADER_STORAGE_BLOCK_SIZE to 2^27. (Modify Table 23.85 - Framebuffer Dependent Values) Add the following entries: Get Value Type Get Command Minimum Value Description Sec -------------------------------- ---- ----------- ------------- ------------------------------ ---- IMPLEMENTATION_COLOR_READ_TYPE E GetIntegerv - Implementation preferred pixel 18.2 type* IMPLEMENTATION_COLOR_READ_FORMAT E GetIntegerv - Implementation preferred pixel 18.2 format* "* Unlike most framebuffer-dependent state which is queried from the currently bound draw framebuffer, this state is queried from the currently bound read framebuffer." Issues 1) With this extension, is OpenGL 4.4 a complete superset of OpenGL ES 3.1? RESOLVED: No, there are things in OpenGL ES 3.1 that were once in OpenGL but have since been deprecated and removed. There is no plan to bring these back into core OpenGL. Here is a list of those things: - Application-generated object names. - Client vertex and index arrays. - Default vertex array object. - ALPHA, LUMINANCE and LUMINANCE_ALPHA pixel formats. - RED_BITS, GREEN_BITS, BLUE_BITS, DEPTH_BITS and STENCIL_BITS. - GENERATE_MIPMAP_HINT and automatic mipmap generation. - ALIASED_POINT_SIZE_RANGE query. - Line widths greater than 1. - Query of EXTENSIONS with GetString. In addition the error FRAMEBUFFER_INCOMPLETE_DIMENSIONS was in ES2 and the token remains in ES3 and above, but ES3 and above cannot generate this error. This has not been added to OpenGL core. Revision History Rev. Date Author Changes ---- -------- -------- ----------------------------------------------- 15 09/19/14 Jon Leech Remove FRONT as valid . 14 09/18/14 Jon Leech Add FRONT and BACK as valid s for GetFramebufferAttachmentParameteriv (Bug 12695). 13 05/08/14 pdaniell Allow precision qualifiers to be used with any opaque type, and not just samplers. 12 05/01/14 pdaniell Add #extension support. 11 04/17/14 pdaniell Improve support for the IMPLEMENTATION_COLOR_READ_FORMAT and IMPLEMENTATION_COLOR_READ_TYPE queries to match the OpenGL ES 3.1 spec. 10 04/16/14 pdaniell Add ES compatibility for calling DrawBuffers with BACK. 9 03/20/14 pdaniell Update glMemoryBarrierByRegion language to match latest OpenGL ES 3.1 spec. 8 03/15/14 dkoch Update overview to specifically itemize the additions. 7 03/13/14 pdaniell Remove fixes for ARB_vertex_attrib_binding which have now gone into an OpenGL 4.4 update. 6 03/07/14 pdaniell Update language for glMemoryBarrierByRegion to the latest ES 3.1 spec. 5 03/04/14 pdaniell Add some more built-in constants for shader image load store. 4 03/04/14 dkoch Remove unnecessary edits (Bug 11802). 3 03/02/14 dkoch More complete first draft. 2 02/27/14 pdaniell Complete the first draft. 1 12/20/13 pdaniell Initial draft with overview only.