Name EXT_EGL_image_storage Name Strings GL_EXT_EGL_image_storage Contact Krzysztof Kosinski (krzysio 'at' google.com) Contributors Krzysztof Kosinski, Google Craig Donner, Google Jesse Hall, Google Jan-Harald Fredriksen, ARM Daniel Koch, Nvidia Gurchetan Singh, Google Status Complete Version August 22, 2019 (version 8) Number #522 OpenGL ES Extension #301 Dependencies Requires OpenGL 4.2, OpenGL ES 3.0, or ARB_texture_storage. Requires EGL 1.4 and either the EGL_KHR_image or EGL_KHR_image_base extensions. The EGL_KHR_gl_texture_2D_image, EGL_KHR_gl_texture_cubemap_image, EGL_KHR_gl_texture_3D_image, EGL_KHR_gl_renderbuffer_image, EGL_KHR_vg_parent_image, EGL_ANDROID_get_native_client_buffer, EGL_EXT_image_dma_buf_import and EGL_EXT_image_gl_colorspace extensions provide additional functionality layered on EGL_KHR_image_base and related to this extension. EXT_direct_state_access, ARB_direct_state_access, and OpenGL 4.5 affect the definition of this extension. This extension interacts with GL_OES_EGL_image, GL_OES_EGL_image_external, GL_OES_EGL_image_external_essl3, and GL_EXT_EGL_image_array. This extension is written based on the wording of the OpenGL ES 3.2 Specification. Overview The OpenGL ES extension OES_EGL_image provides a mechanism for creating GL textures sharing storage with EGLImage objects (in other words, creating GL texture EGLImage targets). The extension was written against the OpenGL ES 2.0 specification, which does not have the concept of immutable textures. As a result, it specifies that respecification of a texture by calling TexImage* on a texture that is an EGLImage target causes it to be implicitly orphaned. In most cases, this is not the desired behavior, but rather a result of an application error. This extension provides a mechanism for creating texture objects that are both EGLImage targets and immutable. Since immutable textures cannot be respecified, they also cannot accidentally be orphaned, and attempts to do so generate errors instead of resulting in well-defined, but often undesirable and surprising behavior. It provides a strong guarantee that texture data that is intended to be shared will remain shared. EGL extension specifications are located in the EGL Registry at http://www.khronos.org/registry/egl/ Glossary Please see the EGL_KHR_image specification for a list of terms used by this specification. New Types /* * GLeglImageOES is an opaque handle to an EGLImage * Note: GLeglImageOES is also defined in GL_OES_EGL_image */ typedef void* GLeglImageOES; New Procedures and Functions void EGLImageTargetTexStorageEXT(enum target, eglImageOES image, const int* attrib_list) void EGLImageTargetTextureStorageEXT(uint texture, eglImageOES image, const int* attrib_list) New Tokens None. Additions to Chapter 8 of the OpenGL ES 3.2 Specification (Textures and Samplers) - (8.18, p. 210) Insert the following text before the paragraph starting with "After a successful call to any TexStorage* command": The command void EGLImageTargetTexStorageEXT(enum target, eglImageOES image, const int* attrib_list); specifies all levels and properties of a texture (including dimensionality, width, height, format, mipmap levels of detail, and image data) by taking them from the specified eglImageOES . Images specified this way will be EGLImage siblings with the original EGLImage source and any other EGLImage targets. must be one of GL_TEXTURE_2D, GL_TEXTURE_2D_ARRAY, GL_TEXTURE_3D, GL_TEXTURE_CUBE_MAP, GL_TEXTURE_CUBE_MAP_ARRAY. On OpenGL implementations (non-ES), can also be GL_TEXTURE_1D or GL_TEXTURE_1D_ARRAY. If the implementation supports OES_EGL_image_external, can be GL_TEXTURE_EXTERNAL_OES. must match the type of image data stored in . For instance, if the was created from a GL texture, must match the texture target of the source texture. must be the handle of a valid EGLImage resource, cast into the type eglImageOES. Assuming no errors are generated in EGLImageTargetTexStorageEXT, the newly specified texture object will be an EGLImage target of the specified eglImageOES. must be NULL or a pointer to the value GL_NONE. If is NULL, the error INVALID_VALUE is generated. If is neither NULL nor a valid value, the behavior is undefined, up to and including program termination. If the GL is unable to specify a texture object using the supplied eglImageOES (if, for example, refers to a multisampled eglImageOES, or is GL_TEXTURE_2D but contains a cube map), the error INVALID_OPERATION is generated. If the EGL image was created using EGL_EXT_image_dma_buf_import, then the following applies: - must be GL_TEXTURE_2D or GL_TEXTURE_EXTERNAL_OES. Otherwise, the error INVALID_OPERATION is generated. - if is GL_TEXTURE_2D, then the resultant texture must have a sized internal format which is colorspace and size compatible with the dma-buf. If the GL is unable to determine such a format, the error INVALID_OPERATION is generated. - if is GL_TEXTURE_EXTERNAL_OES, the internal format of the texture is implementation defined. If is neither NULL nor a pointer to the value GL_NONE, the error INVALID_VALUE is generated. The command void EGLImageTargetTextureStorageEXT(uint texture, eglImageOES image, const int* attrib_list); is equivalent to EGLImageTargetTexStorageEXT, but the target texture object is directly specified using the parameter instead of being taken from the active texture unit. - (8.18, p. 210) Replace "After a successful call to any TexStorage* command" with "After a successful call to any TexStorage* or EGLImageTarget*StorageEXT command" - (8.18, p. 210) Add the following to the list following the sentence "Using any of the following commands with the same texture will result in an INVALID_OPERATION error being generated, even if it does not affect the dimensions or format:" EGLImageTarget*StorageEXT Issues 1. Should this extension provide support for renderbuffers? RESOLVED: This seems of limited use, and renderbuffer support specified by OES_EGL_image already uses the immutable storage model, so that would be redundant. 2. Should OES_EGL_image be a prerequisite? RESOLVED: Supporting both OES_EGL_image and this extension requires more complexity than supporting only this extension and we did not want to rule out such implementations. Therefore, this extension does not require OES_EGL_image. 3. Should multisampled texture targets be supported? RESOLVED: We are not aware of any EGLImage implementations that support multisampling, so this is omitted. 4. What is the interaction with GenerateMipmap? RESOLVED: Since immutable textures do not allow respecification, calling GenerateMipmap on a texture created with EGLImageTarget*StorageEXT never causes orphaning. 5. What is the purpose of the attrib_list parameter? RESOLVED: It allows layered extensions to pass additional data. It is intended to be used similarly to the attrib_list parameter on the EGL functions eglCreateContext and eglCreateImageKHR. Since the new entry points define immutable textures, setting additional values through texture parameters would require more complex validation. Revision History #8 (August 22, 2019) - Clarify interaction with EGL_EXT_image_dma_buf_import. #7 (February 7, 2018) - Amend the explanation of the attrib_list parameter. #6 (February 2, 2018) - Add attrib_list parameter to both entry points. #5 (January 10, 2018) - Minor wording changes and clean-ups. Moved the discussion of interaction with GenerateMipmap to an issue. #4 (December 6, 2017) - Rewritten against the OpenGL ES 3.2 specification. Renamed from KHR to EXT. #3 (November 20, 2017) - Added direct state access entry point and corrected references to the OpenGL ES 3.0 specification. #2 (November 13, 2017) - Specified the allowed texture targets. Clarified requirements. Clarified interactions with mipmaps. #1 (November 1, 2017) - Initial version.