• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1Name
2
3    EXT_EGL_image_storage
4
5Name Strings
6
7    GL_EXT_EGL_image_storage
8
9Contact
10
11    Krzysztof Kosinski (krzysio 'at' google.com)
12
13Contributors
14
15    Krzysztof Kosinski, Google
16    Craig Donner, Google
17    Jesse Hall, Google
18    Jan-Harald Fredriksen, ARM
19    Daniel Koch, Nvidia
20    Gurchetan Singh, Google
21
22Status
23
24    Complete
25
26Version
27
28    August 22, 2019 (version 8)
29
30Number
31
32    #522
33    OpenGL ES Extension #301
34
35Dependencies
36
37    Requires OpenGL 4.2, OpenGL ES 3.0, or ARB_texture_storage.
38
39    Requires EGL 1.4 and either the EGL_KHR_image or EGL_KHR_image_base
40    extensions.
41
42    The EGL_KHR_gl_texture_2D_image, EGL_KHR_gl_texture_cubemap_image,
43    EGL_KHR_gl_texture_3D_image, EGL_KHR_gl_renderbuffer_image,
44    EGL_KHR_vg_parent_image, EGL_ANDROID_get_native_client_buffer,
45    EGL_EXT_image_dma_buf_import and EGL_EXT_image_gl_colorspace extensions
46    provide additional functionality layered on EGL_KHR_image_base and
47    related to this extension.
48
49    EXT_direct_state_access, ARB_direct_state_access, and OpenGL 4.5 affect
50    the definition of this extension.
51
52    This extension interacts with GL_OES_EGL_image, GL_OES_EGL_image_external,
53    GL_OES_EGL_image_external_essl3, and GL_EXT_EGL_image_array.
54
55    This extension is written based on the wording of the OpenGL ES 3.2
56    Specification.
57
58Overview
59
60    The OpenGL ES extension OES_EGL_image provides a mechanism for creating
61    GL textures sharing storage with EGLImage objects (in other words, creating
62    GL texture EGLImage targets).  The extension was written against the
63    OpenGL ES 2.0 specification, which does not have the concept of immutable
64    textures.  As a result, it specifies that respecification of a texture by
65    calling TexImage* on a texture that is an EGLImage target causes it to be
66    implicitly orphaned.  In most cases, this is not the desired behavior, but
67    rather a result of an application error.
68
69    This extension provides a mechanism for creating texture objects that are
70    both EGLImage targets and immutable.  Since immutable textures cannot be
71    respecified, they also cannot accidentally be orphaned, and attempts to do
72    so generate errors instead of resulting in well-defined, but often
73    undesirable and surprising behavior.  It provides a strong guarantee that
74    texture data that is intended to be shared will remain shared.
75
76    EGL extension specifications are located in the EGL Registry at
77
78        http://www.khronos.org/registry/egl/
79
80Glossary
81
82    Please see the EGL_KHR_image specification for a list of terms
83    used by this specification.
84
85New Types
86
87    /*
88     * GLeglImageOES is an opaque handle to an EGLImage
89     * Note: GLeglImageOES is also defined in GL_OES_EGL_image
90     */
91    typedef void* GLeglImageOES;
92
93New Procedures and Functions
94
95    void EGLImageTargetTexStorageEXT(enum target, eglImageOES image,
96                                     const int* attrib_list)
97
98    <If EXT_direct_state_access or an equivalent mechanism is supported:>
99
100    void EGLImageTargetTextureStorageEXT(uint texture, eglImageOES image,
101                                         const int* attrib_list)
102
103New Tokens
104
105     None.
106
107Additions to Chapter 8 of the OpenGL ES 3.2 Specification (Textures and
108Samplers)
109
110    - (8.18, p. 210)  Insert the following text before the paragraph starting
111    with "After a successful call to any TexStorage* command":
112
113    The command
114
115        void EGLImageTargetTexStorageEXT(enum target, eglImageOES image,
116                                         const int* attrib_list);
117
118    specifies all levels and properties of a texture (including dimensionality,
119    width, height, format, mipmap levels of detail, and image data) by taking
120    them from the specified eglImageOES <image>.  Images specified this way
121    will be EGLImage siblings with the original EGLImage source and any other
122    EGLImage targets.
123
124    <target> must be one of GL_TEXTURE_2D, GL_TEXTURE_2D_ARRAY, GL_TEXTURE_3D,
125    GL_TEXTURE_CUBE_MAP, GL_TEXTURE_CUBE_MAP_ARRAY.  On OpenGL implementations
126    (non-ES), <target> can also be GL_TEXTURE_1D or GL_TEXTURE_1D_ARRAY.
127    If the implementation supports OES_EGL_image_external, <target> can be
128    GL_TEXTURE_EXTERNAL_OES.  <target> must match the type of image data stored
129    in <image>.  For instance, if the <image> was created from a GL texture,
130    <target> must match the texture target of the source texture. <image> must
131    be the handle of a valid EGLImage resource, cast into the type eglImageOES.
132    Assuming no errors are generated in EGLImageTargetTexStorageEXT, the newly
133    specified texture object will be an EGLImage target of the specified
134    eglImageOES. <attrib_list> must be NULL or a pointer to the value GL_NONE.
135
136    If <image> is NULL, the error INVALID_VALUE is generated.  If <image> is
137    neither NULL nor a valid value, the behavior is undefined, up to and
138    including program termination.
139
140    If the GL is unable to specify a texture object using the supplied
141    eglImageOES <image> (if, for example, <image> refers to a multisampled
142    eglImageOES, or <target> is GL_TEXTURE_2D but <image> contains a cube map),
143    the error INVALID_OPERATION is generated.
144
145    If the EGL image was created using EGL_EXT_image_dma_buf_import, then the
146    following applies:
147
148        - <target> must be GL_TEXTURE_2D or GL_TEXTURE_EXTERNAL_OES. Otherwise,
149          the error INVALID_OPERATION is generated.
150        - if <target> is GL_TEXTURE_2D, then the resultant texture must have a
151          sized internal format which is colorspace and size compatible with the
152          dma-buf. If the GL is unable to determine such a format, the error
153          INVALID_OPERATION is generated.
154        - if <target> is GL_TEXTURE_EXTERNAL_OES, the internal format of the
155          texture is implementation defined.
156
157    If <attrib_list> is neither NULL nor a pointer to the value GL_NONE, the
158    error INVALID_VALUE is generated.
159
160    <If EXT_direct_state_access or an equivalent mechanism is supported:>
161
162    The command
163
164        void EGLImageTargetTextureStorageEXT(uint texture, eglImageOES image,
165                                             const int* attrib_list);
166
167    is equivalent to EGLImageTargetTexStorageEXT, but the target texture object
168    is directly specified using the <texture> parameter instead of being taken
169    from the active texture unit.
170
171    - (8.18, p. 210)  Replace "After a successful call to any TexStorage*
172    command" with "After a successful call to any TexStorage* or
173    EGLImageTarget*StorageEXT command"
174
175    - (8.18, p. 210)  Add the following to the list following the sentence
176    "Using any of the following commands with the same texture will result in
177    an INVALID_OPERATION error being generated, even if it does not affect the
178    dimensions or format:"
179
180    EGLImageTarget*StorageEXT
181
182Issues
183
184    1.  Should this extension provide support for renderbuffers?
185
186        RESOLVED:  This seems of limited use, and renderbuffer support specified
187        by OES_EGL_image already uses the immutable storage model, so that would
188        be redundant.
189
190    2.  Should OES_EGL_image be a prerequisite?
191
192        RESOLVED:  Supporting both OES_EGL_image and this extension requires
193        more complexity than supporting only this extension and we did not want
194        to rule out such implementations.  Therefore, this extension does not
195        require OES_EGL_image.
196
197    3.  Should multisampled texture targets be supported?
198
199        RESOLVED:  We are not aware of any EGLImage implementations that support
200        multisampling, so this is omitted.
201
202    4.  What is the interaction with GenerateMipmap?
203
204        RESOLVED:  Since immutable textures do not allow respecification,
205        calling GenerateMipmap on a texture created with
206        EGLImageTarget*StorageEXT never causes orphaning.
207
208    5.  What is the purpose of the attrib_list parameter?
209
210        RESOLVED:  It allows layered extensions to pass additional data.  It is
211        intended to be used similarly to the attrib_list parameter on the
212        EGL functions eglCreateContext and eglCreateImageKHR.  Since the new
213        entry points define immutable textures, setting additional values
214        through texture parameters would require more complex validation.
215
216Revision History
217
218    #8 (August 22, 2019) - Clarify interaction with EGL_EXT_image_dma_buf_import.
219
220    #7 (February 7, 2018) - Amend the explanation of the attrib_list parameter.
221
222    #6 (February 2, 2018) - Add attrib_list parameter to both entry points.
223
224    #5 (January 10, 2018) - Minor wording changes and clean-ups.  Moved the
225        discussion of interaction with GenerateMipmap to an issue.
226
227    #4 (December 6, 2017) - Rewritten against the OpenGL ES 3.2 specification.
228        Renamed from KHR to EXT.
229
230    #3 (November 20, 2017) - Added direct state access entry point and corrected
231        references to the OpenGL ES 3.0 specification.
232
233    #2 (November 13, 2017) - Specified the allowed texture targets.  Clarified
234        requirements.  Clarified interactions with mipmaps.
235
236    #1 (November 1, 2017) - Initial version.
237
238