Name
KHR_gl_texture_2D_image
KHR_gl_texture_cubemap_image
KHR_gl_texture_3D_image
KHR_gl_renderbuffer_image
Name Strings
EGL_KHR_gl_texture_2D_image
EGL_KHR_gl_texture_cubemap_image
EGL_KHR_gl_texture_3D_image
EGL_KHR_gl_renderbuffer_image
Contributors
Aaftab Munshi
Barthold Lichtenbelt
Gary King
Jeff Juliano
Jon Leech
Jonathan Grant
Acorn Pooley
Contacts
Gary King, NVIDIA Corporation (gking 'at' nvidia.com)
Notice
Copyright (c) 2006-2013 The Khronos Group Inc. Copyright terms at
http://www.khronos.org/registry/speccopyright.html
Status
Complete.
Approved by the Khronos Board of Promoters on February 11, 2008.
Version
Version 13, October 9, 2013
Number
EGL Extension #5
Dependencies
All extensions require EGL 1.2 and the EGL_KHR_image extension
These extensions are written against the wording of the EGL 1.2
Specification.
KHR_gl_texture_2D_image requires an OpenGL or OpenGL ES client API (any
version of either API).
KHR_gl_texture_cubemap_image requires an OpenGL or OpenGL ES client API
supporting texture cube maps, either in the core API or via extensions.
KHR_gl_texture_3D_image requires KHR_gl_texture_2D_image to be supported
by the EGL implementation. It also requires an OpenGL or OpenGL ES
client API supporting three-dimensional textures, either in the core API
or via extensions.
KHR_gl_renderbuffer_image requires KHR_gl_texture_2D_image to be
supported by the EGL implementation. It also requires an OpenGL or
OpenGL ES client API supporting renderbuffers, either in the core API or
via extensions.
Overview
The extensions specified in this document provide a mechanism for
creating EGLImage objects from OpenGL and OpenGL ES (henceforth referred
to collectively as 'GL') API resources, including two- and three-
dimensional textures, cube maps and render buffers. For an overview of
EGLImage operation, please see the EGL_KHR_image specification.
Due to the number of available extensions for the OpenGL ES 1.1 and
OpenGL ES 2.0 APIs, this document is organized as 4 separate extensions,
described collectively. These extensions are separated based on the
required underlying GL functionality (described in the dependencies
section).
New Types
None
New Procedures and Functions
None
New Tokens
Accepted in the <target> parameter of eglCreateImageKHR:
EGL_GL_TEXTURE_2D_KHR 0x30B1
Accepted as an attribute in the <attr_list> parameter of
eglCreateImageKHR:
EGL_GL_TEXTURE_LEVEL_KHR 0x30BC
Added by KHR_gl_texture_cubemap_image:
Accepted in the <target> parameter of eglCreateImageKHR:
EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_X_KHR 0x30B3
EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_X_KHR 0x30B4
EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_Y_KHR 0x30B5
EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_Y_KHR 0x30B6
EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_Z_KHR 0x30B7
EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_Z_KHR 0x30B8
Added by KHR_gl_texture_3D_image:
Accepted in the <target> parameter of eglCreateImageKHR:
EGL_GL_TEXTURE_3D_KHR 0x30B2
Accepted as an attribute in the <attr_list> parameter of
eglCreateImageKHR:
EGL_GL_TEXTURE_ZOFFSET_KHR 0x30BD
Added by KHR_gl_renderbuffer_image:
Accepted in the <target> parameter of eglCreateImageKHR:
EGL_GL_RENDERBUFFER_KHR 0x30B9
Additions to the EGL Image (EGL_KHR_image) Specification:
Add the following to Table aaa (Legal values for eglCreateImageKHR
<target> parameter), Section 2.5.1 (EGLImage Specification)
+-------------------------------------+---------------------------------+
| <target> | Notes |
+-------------------------------------+---------------------------------+
| EGL_GL_TEXTURE_2D_KHR | Used for GL 2D texture images |
+-------------------------------------+---------------------------------+
If KHR_gl_texture_cubemap_image is supported:
+-----------------------------------------+-----------------------------+
| <target> | Notes |
+-----------------------------------------+-----------------------------+
| EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_X_KHR | Used for the +X face of |
| | GL cubemap texture images |
+-----------------------------------------+-----------------------------+
| EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_X_KHR | Used for the -X face of |
| | GL cubemap texture images |
+-----------------------------------------+-----------------------------+
| EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_Y_KHR | Used for the +Y face of |
| | GL cubemap texture images |
+-----------------------------------------+-----------------------------+
| EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_Y_KHR | Used for the -Y face of |
| | GL cubemap texture images |
+-----------------------------------------+-----------------------------+
| EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_Z_KHR | Used for the +Z face of |
| | GL cubemap texture images |
+-----------------------------------------+-----------------------------+
| EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_Z_KHR | Used for the -Z face of |
| | GL cubemap texture images |
+-----------------------------------------+-----------------------------+
If KHR_gl_texture_3D_image is supported:
+-------------------------------------+---------------------------------+
| <target> | Notes |
+-------------------------------------+---------------------------------+
| EGL_GL_TEXTURE_3D_KHR | Used for GL 3D texture images |
+-------------------------------------+---------------------------------+
If KHR_gl_renderbuffer_image is supported:
+-------------------------------------+---------------------------------+
| <target> | Notes |
+-------------------------------------+---------------------------------+
| EGL_GL_RENDERBUFFER_KHR | Used for GL renderbuffer images|
+-------------------------------------+---------------------------------+
Add the following to Table bbb (Legal attributes for eglCreateImageKHR
<attr_list> parameter), Section 2.5.1 (EGLImage Specification)
+---------------------------+-------------------------------+----------------------------+---------+
| | | Valid | Default |
| Attribute | Description | <target>s | Value |
+---------------------------+-------------------------------+----------------------------+---------+
| EGL_GL_TEXTURE_LEVEL_KHR | Specifies the mipmap level | EGL_GL_TEXTURE_2D_KHR, | 0 |
| | used as the EGLImage source. | EGL_GL_TEXTURE_CUBE_MAP_*, | |
| | Must be part of the complete | EGL_GL_TEXTURE_3D_KHR | |
| | texture object <buffer> | | |
+---------------------------+-------------------------------+----------------------------+---------+
If KHR_gl_texture_3D_image is supported:
+----------------------------+------------------------------+----------------------------+---------+
| | | Valid | Default |
| Attribute | Description | <target>s | Value |
+----------------------------+------------------------------+----------------------------+---------+
| EGL_GL_TEXTURE_ZOFFSET_KHR | Specifies the depth offset | EGL_GL_TEXTURE_3D_KHR | 0 |
| | of the image to use as the | | |
| | EGLImage source. Must be | | |
| | part of the complete texture| | |
| | object <buffer> | | |
+----------------------------+------------------------------+----------------------------+---------+
Insert the following text after paragraph 3 ("If <target> is
NATIVE_PIXMAP_KHR...") of Section 2.5.1 (EGLImage Specification)
"If <target> is EGL_GL_TEXTURE_2D_KHR, EGL_GL_TEXTURE_3D_KHR,
EGL_GL_RENDERBUFFER_KHR,
EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_X_KHR,
EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_X_KHR,
EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_Y_KHR,
EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_Y_KHR,
EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_Z_KHR, or
EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_Z_KHR,
<dpy> must be a valid EGLDisplay,
and <ctx> must be a valid GL API context on that display.
If <target> is EGL_GL_TEXTURE_2D_KHR, <buffer> must be the name of a
nonzero, GL_TEXTURE_2D target texture object, cast into
the type EGLClientBuffer. <attr_list> should specify the mipmap level
which will be used as the EGLImage source (EGL_GL_TEXTURE_LEVEL_KHR); the
specified mipmap level must be part of <buffer>. If not specified, the
default value listed in Table bbb will be used, instead. Additional
values specified in <attr_list> are ignored. The texture must be complete
unless the mipmap level to be used is 0, the texture has mipmap level 0
specified, and no other mipmap levels are specified.
If <target> is one of the EGL_GL_TEXTURE_CUBE_MAP_* enumerants, <buffer>
must be the name of a cube-complete, nonzero, GL_TEXTURE_CUBE_MAP (or
equivalent in GL extensions) target texture object, cast into the type
EGLClientBuffer. <attr_list> should specify the mipmap level which will
be used as the EGLImage source (EGL_GL_TEXTURE_LEVEL_KHR); the specified
mipmap level must be part of <buffer>. If not specified, the default
value listed in Table bbb will be used, instead. Additional values
specified in <attr_list> are ignored. The texture must be cube-complete
unless the mipmap level to be used is 0, the texture has mipmap level 0
specified for all faces, and no other mipmap levels are specified for any
faces.
If <target> is EGL_GL_TEXTURE_3D_KHR, <buffer> must be the name of a
complete, nonzero, GL_TEXTURE_3D (or equivalent in GL extensions) target
texture object, cast
into the type EGLClientBuffer. <attr_list> should specify the mipmap
level (EGL_GL_TEXTURE_LEVEL_KHR) and z-offset (EGL_GL_TEXTURE_ZOFFSET_KHR)
which will be used as the EGLImage source; the specified mipmap level must
be part of <buffer>, and the specified z-offset must be smaller than the
depth of the specified mipmap level. If a value is not specified, the
default value listed in Table bbb will be used, instead. Additional
values specified in <attr_list> are ignored. The texture must be
complete unless the mipmap level to be used is 0, the texture has mipmap
level 0 specified, and no other mipmap levels are specified.
If <target> is EGL_GL_RENDERBUFFER_KHR, <buffer> must be the name of a
complete, nonzero, non-multisampled GL_RENDERBUFFER (or equivalent in
extensions) target object, cast into the type EGLClientBuffer. Values
specified in <attr_list> are ignored."
Add the following errors to the end of the list in Section 2.5.1 (EGLImage
Specification):
" * If <target> is EGL_GL_TEXTURE_2D_KHR, EGL_GL_TEXTURE_CUBE_MAP_*_KHR,
EGL_GL_RENDERBUFFER_KHR or EGL_GL_TEXTURE_3D_KHR, and <dpy> is not a
valid EGLDisplay, the error EGL_BAD_DISPLAY is generated.
* If <target> is EGL_GL_TEXTURE_2D_KHR, EGL_GL_TEXTURE_CUBE_MAP_*_KHR,
EGL_GL_RENDERBUFFER_KHR or EGL_GL_TEXTURE_3D_KHR, and <ctx> is not a
valid EGLContext, the error EGL_BAD_CONTEXT is generated.
* If <target> is EGL_GL_TEXTURE_2D_KHR, EGL_GL_TEXTURE_CUBE_MAP_*_KHR,
EGL_GL_RENDERBUFFER_KHR or EGL_GL_TEXTURE_3D_KHR, and <ctx> is not a
valid GL context, or does not match the <dpy>, the error
EGL_BAD_MATCH is generated.
* If <target> is EGL_GL_TEXTURE_2D_KHR, EGL_GL_TEXTURE_CUBE_MAP_*_KHR
or EGL_GL_TEXTURE_3D_KHR and <buffer> is not the name of a
texture object of type <target>, the error EGL_BAD_PARAMETER
is generated.
* If <target> is EGL_GL_RENDERBUFFER_KHR and <buffer> is not the
name of a renderbuffer object, or if <buffer> is the name of a
multisampled renderbuffer object, the error EGL_BAD_PARAMETER is
generated.
* If EGL_GL_TEXTURE_LEVEL_KHR is nonzero, <target> is
EGL_GL_TEXTURE_2D_KHR, EGL_GL_TEXTURE_CUBE_MAP_*_KHR or
EGL_GL_TEXTURE_3D_KHR, and <buffer> is not the name of a complete
GL texture object, the error EGL_BAD_PARAMETER is generated.
* If EGL_GL_TEXTURE_LEVEL_KHR is 0, <target> is
EGL_GL_TEXTURE_2D_KHR, EGL_GL_TEXTURE_CUBE_MAP_*_KHR or
EGL_GL_TEXTURE_3D_KHR, <buffer> is the name of an incomplete GL
texture object, and any mipmap levels other than mipmap level 0
are specified, the error EGL_BAD_PARAMETER is generated.
* If EGL_GL_TEXTURE_LEVEL_KHR is 0, <target> is
EGL_GL_TEXTURE_2D_KHR or EGL_GL_TEXTURE_3D_KHR, <buffer> is not
the name of a complete GL texture object, and mipmap level 0 is
not specified, the error EGL_BAD_PARAMETER is generated.
* If EGL_GL_TEXTURE_LEVEL_KHR is 0, <target> is
EGL_GL_TEXTURE_CUBE_MAP_*_KHR, <buffer> is not the name of a
complete GL texture object, and one or more faces do not have
mipmap level 0 specified, the error EGL_BAD_PARAMETER is
generated.
* If <target> is EGL_GL_TEXTURE_2D_KHR,
EGL_GL_TEXTURE_CUBE_MAP_*_KHR, EGL_GL_RENDERBUFFER_KHR or
EGL_GL_TEXTURE_3D_KHR and <buffer> refers to the default GL
texture object (0) for the corresponding GL target, the error
EGL_BAD_PARAMETER is generated.
* If <target> is EGL_GL_TEXTURE_2D_KHR, EGL_GL_TEXTURE_CUBE_MAP_*_KHR,
or EGL_GL_TEXTURE_3D_KHR, and the value specified in <attr_list>
for EGL_GL_TEXTURE_LEVEL_KHR is not a valid mipmap level for the
specified GL texture object <buffer>, the error EGL_BAD_MATCH is
generated.
* If <target> is EGL_GL_TEXTURE_3D_KHR, and the value specified in
<attr_list> for EGL_GL_TEXTURE_ZOFFSET_KHR exceeds the depth
of the specified mipmap level-of-detail in <buffer>, the error
EGL_BAD_PARAMETER is generated."
Issues
1. What should happen if an application attempts to create an
EGLImage from a default OpenGL object (i.e., objects with
a name of 0)?
SUGGESTION: Disallow this operation, and generate an error.
2. What happens when one of
glTexImage2D
glCopyTexImage2D
glCompressedTexImage2D
glTexImage3D
glCopyTexImage3D
glCompressedTexImage3D
is called on a texture which has a mipmap level which is an EGLImage
sibling?
RESOLVED: the EGLImage sibling is orphaned. The mipmap level and the
EGLImage no longer have any connection.
3. What happens when one of
glTexSubImage2D
glCopyTexSubImage2D
glCompressedTexSubImage2D
glTexSubImage3D
glCopyTexSubImage3D
glCompressedTexSubImage3D
is called on a texture which has a mipmap level which is an EGLImage
sibling?
RESOLVED: the EGLImage sibling is NOT orphaned. The mipmap level
remains an EGLImage sibling.
4. What happens when glGenerateMipmaps is called on a texture which has a
mipmap level which is an EGLImage sibling?
RESOLVED: If the texture is already complete, then the EGLImage
sibling is not orphaned, and the mipmap level remains an EGLImage
sibling. However, if the texture was not complete then the
EGLImage sibling IS orphaned. This is because the implementation
will implicitly alter the structure of the mipmap levels.
5. What happens when the GL_GENERATE_MIPMAP bit causes a texture to be
respecified.
RESOLVED: If the texture is already complete, then the EGLImage
sibling is not orphaned, and the mipmap level remains an EGLImage
sibling. However, if the texture was not complete then the
EGLImage sibling IS orphaned. This is because the implementation
will implicitly alter the structure of the mipmap levels.
6. Can an EGLImage be created from a multisampled GL image?
RESOLVED: NO. Attempting to create an EGLImage from a multisampled
GL renderbuffer is now an error. Attempting to create from a
multisampled OpenGL texture image is not possible because none of
the multisampled <target>s are supported.
7. Are all types of two-dimensional GL images which might
be associated with EGLImages allowed?
Not yet. We could add new variants of these extensions to support
other image types such as rectangular and 2D array slice textures,
but haven't yet seen a need to do so.
Revision History
#13 (Jon Leech, October 9, 2013) - Define interactions with and support for
OpenGL and OpenGL ES 3.0, in addition to OpenGL ES 1/2. Add issue 7 (Bug
10728).
#12 (Jon Leech, September 16, 2013) - Add error when specifying a
renderbuffer <target> and passing a multisampled renderbuffer object.
Add issue 6 describing lack of support for multisampled EGLImages (Bug
10728).
#11 (Jon Leech, June 26, 2013) - Add error when specifying a renderbuffer
<target> and not passing a renderbuffer object (Bug 10384).
#10 (Jon Leech, June 13, 2013) - Add a "Valid Targets" column to table bbb
for new attributes, matching proposed changes in EGL_KHR_image_base (Bug
10151).
#9 (Jon Leech, March 28, 2012)
- Fix spelling of *CUBE_MAP* tokens (from CUBEMAP) to agree with
eglext.h.
#8 (Jon Leech, February 4, 2009)
- Change "non-default ... texture object" to "nonzero".
#7 (Bruce Merry, January 20, 2009)
- Minor wording improvements on issues 4 and 5.
#6 (Acorn Pooley, January 13, 2009)
- Modify completion requirement so textures with only mipmap level 0 can
be EGLImage source siblings. Add issues 2-5.
#5 (Jon Leech, October 8, 2008)
- Updated status (approved as part of OpenKODE 1.0)
#4 (Jon Leech, April 7, 2007)
- Assigned enumerant values
- Added OpenKODE 1.0 Provisional disclaimer
#3 (December 14, 2006)
- Changed requirement to egl 1.2 to include EGLClientBuffer type.
- formatting to keep within 80 columns
- added error condition descriptions for <dpy> and <ctx>
- changed error condition for EGL_GL_TEXTURE_ZOFFSET_KHR too big to
be EGL_BAD_PARAMETER
#2 (November 27, 2006)
- Changed OES token to KHR
