Name OES_EGL_image_external_essl3 Name Strings GL_OES_EGL_image_external_essl3 Contributors Jan-Harald Fredriksen, ARM (jan-harald.fredriksen 'at' arm.com) James Helferty, NVIDIA (jhelferty 'at' nvidia.com) Mark Callow, ArtSpark Holdings Inc (callow.mark 'a' artspark.co.jp) Contributors to GL_OES_EGL_image_external. Contacts Jan-Harald Fredriksen, ARM (jan-harald.fredriksen 'at' arm.com) Notice Copyright (c) 2014-2024 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 ES 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 OpenGL ES Working Group. Ratified by the Khronos Board of Promoters on January 23, 2015. Version January 3, 2024 (version 11) Number OpenGL ES Extension #220 Dependencies Requires OpenGL ES 3.0 and ESSL 3.0. Requires EGL 1.2 Requires either the EGL_KHR_image_base or the EGL_KHR_image extension. Requires OES_EGL_image_external. This extension is written based on the wording of the OpenGL ES 3.0.3 specification, the OpenGL ES Shading Language version 3.0 rev4, and the OES_EGL_image_external extension. This extension interacts with OpenGL ES 3.1. This extension interacts with GL_EXT_gpu_shader5 and GL_OES_gpu_shader5. This extension borrows concepts and function names from the GL_OES_EGL_image and OES_EGL_image_external extensions. This extension is compatible with GL_OES_EGL_image but does not require it. Overview OES_EGL_image_external provides a mechanism for creating EGLImage texture targets from EGLImages, but only specified language interactions for the OpenGL ES Shading Language version 1.0. This extension adds support for versions 3.x of the OpenGL ES Shading Language. Glossary Please see the EGL_OES_image_base specification for a list of terms used by this specification. New Types * New sampler type allowed by the OpenGL ES Shading Language when * #extension GL_OES_EGL_image_external_essl3 * is used. */ samplerExternalOES New Procedures and Functions None. New Tokens None. Changes to section 3.8.2 ("Sampler Objects") of the OpenGL ES 3.0.3 specification - Add to the description BindSampler: "If state is present in a sampler object bound to a texture unit that would have been rejected by a call to TexParameter* for the texture bound to that unit, the behavior of the implementation is as if the texture were incomplete. For example, if TEXTURE_WRAP_S or TEXTURE_WRAP_T is set to anything but CLAMP_TO_EDGE on the sampler object bound to a texture unit and the texture bound to that unit is an external texture, the texture will be considered incomplete. Sampler object state which does not affect sampling for the type of texture bound to a texture unit, such as TEXTURE_WRAP_R for an external texture, does not affect completeness." Changes to section 3.7.14 ("External Textures") of the OES_EGL_image_external specification "It is an INVALID_OPERATION error to set the TEXTURE_BASE_LEVEL to a value other than zero." [[Only if OpenGL ES 3.1 is supported]] Changes to section 8.22 ("Texture Image Loads and Stores") of the OpenGL ES 3.1 specification On p. 196 in the errors section for BindImageTexture, replace the last error with the following: "An INVALID_OPERATION error is generated if is neither the name of an immutable texture object, nor the name of an external texture object. Add to table 8.26 "Mapping of image load, store..." Texture target face/ i j k layer -------------------------- -- -- -- ----- TEXTURE_EXTERNAL_OES x y - - Changes to section 3.7 ("Keywords") of the OpenGL ES Shading Language specification - Add to the list of keywords: "samplerExternalOES" Changes to section 4.1 ("Basic Types") of the OpenGL ES Shading Language specification - Add to the list of Floating Point Sampler Types (opaque): "samplerExternalOES a handle for accessing an external 2D texture" - Add a paragraph at the end of the section: "The samplerExternalOES type is optional and must be enabled by #extension GL_OES_EGL_image_external_essl3 : enable" Changes to section 4.5.4 ("Default Precision Qualifiers") of the OpenGL ES Shading Language specification - Add the following paragraph: "All languages have the following predeclared globally scoped default precision statements: precision lowp samplerExternalOES;" Changes to section 8.8 ("Texture Lookup Functions") of the OpenGL ES Shading Language specification - Add to the table the following sampler functions: "highp ivec2 textureSize(samplerExternalOES sampler, int lod) vec4 texture(samplerExternalOES sampler, vec2 P [, float bias] ) vec4 textureProj(samplerExternalOES sampler, vec3 P [, float bias] ) vec4 textureProj(samplerExternalOES sampler, vec4 P [, float bias]) vec4 texelFetch(samplerExternalOES sampler, ivec2 P, int lod)" Changes to section 9 ("Shading Language Grammar") of the OpenGL ES Shading Language specification - Add to token list: "SAMPLEREXTERNAL" - Add following "type_specifier_no_array:" "SAMPLEREXTERNAL" Changes to section 11 ("Counting of Inputs and Outputs") of the OpenGL ES Shading Language specification - Add a paragraph at the end "Part of the storage may be reserved by an implementation for its own use e.g. for conversion of external textures. This reduces the number of uniforms available to the shader. The size of this reduction is undefined but should be minimized. Dependencies on OpenGL ES 3.1 and ESSL 3.10 All texture built-in functions added in ESSL 3.10 are excluded from this extension per Issue 4. This extension is expected to work without modification for ESSL 3.10. If OpenGL ES 3.1 is not supported, ignore changes to section 8.22 since image load store is not supported. Interactions with EXT_gpu_shader5 and OES_gpu_shader5 If either of these extensions is supported, add the following paragraph to the end of section 4.1.7.1 ("Samplers") of the ESSL 3.10 specification: "When aggregated into arrays within a shader, external samplers can only be indexed with a constant integral expression. All other sampler types can only be indexed with a dynamically uniform integral expression, otherwise results are undefined." Issues 1. Why is this functionality not added as an interaction to the OES_EGL_image_external extension as in interaction with ESSL 3.x? RESOLVED. Since the built-in texture functions in ESSL were modified going from ESSL 1.0 to 3.x, the original extension does not trivially apply to ESSL 3.x. There are also many shipping implementations of OES_EGL_image_external extension that have chosen to not extend support to ESSL 3.x. If we were to amend the original extension, there would be no way for applications to determine whether a particular implementation supported the language extension for ESSL 3.x or not. 2. Should this extension require OES_EGL_image_external? RESOLVED: Yes. This extension currently depends on OES_EGL_image_external to define the API extensions. This also implies that an implementation cannot choose to support this extension for ESSL 3.x only. 3. What should this extension be called? RESOLVED: OES_EGL_image_external_essl3 4. Should built-in functions beyond ESSL1 compatibility be supported in ESSL 3.x shaders? RESOLVED: Yes. It seems useful to add some of these. The ESSL 3.x built-ins that are only useful for mipmapped textures are excluded since external textures cannot be mipmapped. The ESSL 3.x built-ins that require offsets are excluded since it is not clear how these should work with sub-sampled YUV formats. Required for ESSL1 feature compatibility: - texture - textureProj (two versions) Also included in this extension: - textureSize - texelFetch Excluded from this extension: - textureLod - textureLodOffset - textureProjLod - textureProjLodOffset - textureGrad - textureGradOffset - textureProjGrad - textureProjGradOffset - textureOffset - texelFetchOffset - textureProjOffset - textureGather [for ESSL 3.10] - textureGatherOffset [for ESSL 3.10] 5. Should external integer textures be supported in ESSL 3.x shaders? RESOLVED: No. The built-in functions added for ESSL1 always return floating point values, but that's in part because OpenGL ES 2.0 did not support integer textures. For ESSL 3.x, we could allow the same return values for external textures as for regular 2D textures. This would require adding new sampler types, such as samplerExternaliOES and samplerExternaluOES. Since there is no obvious use-case for external integer textures these are not added by this extension. 6. What token should be used to enable this extension in ESSL 3.x? RESOLVED: GL_OES_EGL_image_external_essl3 The alternatives are a) reuse the GL_OES_image_external token (this should not cause problems since the original extension did not apply to ESSL 3.x), b) use the name of this extension. Option b) is chosen since there is no clear benefit to reusing the old name. 7. What is the interaction with separate sampler objects? RESOLVED: The texture is incomplete if the sampler object state is not compatible with the sampler state. The general rule for separate sampler objects is that if state is present in a sampler object bound to a texture unit that would have been rejected by a call to TexParameter* for the texture bound to that unit, the behavior of the implementation is as if the texture was incomplete. This rule also applies to external textures. A specific constraint is that the OES_EGL_image_external extension specifies that the only supported min filter modes for external textures is LINEAR or NEAREST and that the only valid s and t wrap mode is CLAMP_TO_EDGE. TexParameter* will generate errors if these are called while an external texture is bound. In ES3.x it is possible to attach a sampler object that has any wrap mode and min filter. In this case, the external texture will be treated as incomplete if the sampler object state is incompatible with such textures. 8. What is the interaction with the texture base level? RESOLVED: The base level must be zero for external textures. External textures do not support mipmap filtering. It is consistent with the behavior for 2D multisampled textures in ES3.1 to make it an error to specify a base level other than zero for external textures. This error is not specified in GL_OES_EGL_image_external so adding an error may break existing applications using that extension (in ESSL 1.x) in combination with OpenGL ES 3.x if they set the base level to any other value. 9. What formats are supported? This is implementation defined. GL_OES_EGL_image_external does not require any specific formats, and this extension does not change that. On a given implementation, it is expected that the same set of formats is supported in all shader stages. 10. Should image / load store be supported? And, if so, how? RESOLVED: Yes, in a limited form. Allowing image / load store on external textures enables compute shaders to write to these textures. A limited set of use-cases is enabled by making glBindImageTexture accept external textures. Shaders can access such external textures using the existing sampler type. Since the image format must be specified by the shader, no additional format conversion is done for external textures accessed via image load/store. This implies that the shader author must know the format of the external texture in order to do useful work. Also, only the image formats already supported by image load store are available (i.e, there is no automatic conversion to, for example, YUV formats.) Revision History #11 - (Jan 3, 2024) Clarified wording of issue 7. #10 - (Jan 29, 2016) Fixed typo in issue 10. #9 - (Apr 10, 2015) Clarified issue 10. Specified default precision for samplerExternalOES as lowp for all shader stages. #8 - (Feb 6, 2015) Fixed typo in return value of textureSize (vec2->ivec2) #7 - (Oct 15, 2014) Resolved issue 10. Added interaction with EXT_gpu_shader5. #6 - (Oct 10, 2014) Added issue 10 and its tentative resolution. #5 - (Sep 25, 2014) Updated resolution of issue 7. Added issues 8 and 9. Converted to OES. #4 - (Sep 24, 2014) Added issue 7 with proposed resolution. #3 - (Jul 30, 2014) Excluded textureGather from this extension. #2 - (Jul 30, 2014) Updated based feedback. Tentatively resolved issues. Added issue 6. #1 - (Jul 15, 2014) Original draft.