Name
OES_EGL_image
Name Strings
GL_OES_EGL_image
Contributors
Gary King
Acorn Pooley
Jon Leech
Contacts
Gary King, NVIDIA Corporation (gking 'at' nvidia.com)
Notice
Copyright (c) 2006-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 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
Approved by the Khronos OpenKODE Working Group in January, 2007
as part of OpenKODE 1.0 Provisional.
Version
April 23, 2015 (version 8)
Number
OpenGL ES Extension #23
Dependencies
Requires OpenGL-ES 1.1 or OpenGL-ES 2.0.
Requires EGL 1.2 and either the EGL_OES_image or EGL_OES_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, and
EGL_KHR_vg_parent_image extensions provide additional functionality
layered on EGL_OES_image_base and related to this extension
OES_framebuffer_object affects the wording of this specification
This extension is written based on the wording of the OpenGL 2.0
Specification and the EXT_framebuffer_object extension.
Overview
This extension provides a mechanism for creating texture and
renderbuffer objects sharing storage with specified EGLImage objects
(such objects are referred to as "EGLImage targets").
The companion EGL_KHR_image_base and EGL_KHR_image extensions
provide the definition and rationale for EGLImage objects.
Other EGL extensions, such as EGL_KHR_gl_texture_2D_image,
EGL_KHR_gl_texture_cubemap_image, EGL_KHR_gl_texture_3D_image,
EGL_KHR_gl_renderbuffer_image, and EGL_KHR_vg_parent_image, define
the related functionality of creating EGLImage objects from
"EGLImage sources" such as OpenGL ES texture or renderbuffers or
OpenVG VGImage objects.
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
*/
typedef void* GLeglImageOES;
New Procedures and Functions
void EGLImageTargetTexture2DOES(enum target, eglImageOES image)
void EGLImageTargetRenderbufferStorageOES(enum target,
eglImageOES image)
New Tokens
None.
Additions to Chapter 3 of the OpenGL 2.0 Specification (Rasterization)
- (3.8.2, p. 160) Insert the following text after the end of the
first paragraph (before the discussion of {Copy}TexSubImage):
"Another way of specifying two-dimensional texture images is to
reference them from existing EGLImage objects. Images specified
this way will be EGLImage siblings with the original EGLImage
source and any other EGLImage targets.
The command
void EGLImageTargetTexture2DOES(enum target, eglImageOES image);
defines an entire two-dimensional texture array. All properties
of the texture images (including width, height, format, border, mipmap
levels of detail, and image data) are taken from the specified
eglImageOES <image>, rather than from the client or the framebuffer.
Any existing image arrays associated with any mipmap levels in the texture
object are freed (as if TexImage was called for each, with an image of
zero size). As a result of this referencing operation, all of the pixel
data in the <buffer> used as the EGLImage source resource (i.e., the
<buffer> parameter passed to the CreateImageOES command that returned
<image>) will become undefined.
Currently, <target> must be TEXTURE_2D. <image> must be the
handle of a valid EGLImage resource, cast into the type eglImageOES.
Assuming no errors are generated in EGLImageTargetTexture2DOES, the
newly specified texture object will be an EGLImage target of the
specified eglImageOES. If an application later respecifies any image
array in the texture object (through mechanisms such as calls to
TexImage2D and/or GenerateMipmapOES, or setting the
SGIS_GENERATE_MIPMAP parameter to TRUE), implementations should allocate
additional space for all specified (and respecified) image arrays,
and copy any existing image data to the newly (re)specified texture
object (as if TexImage was called for every level-of-detail in the
texture object). The respecified texture object will not be an
EGLImage target.
If the GL is unable to specify a texture object using the supplied
eglImageOES <image> (if, for example, <image> refers to a multisampled
eglImageOES), the error INVALID_OPERATION is generated.
If <image> does not refer to a valid eglImageOES object, the error
INVALID_VALUE is generated.
If <target> is not TEXTURE_2D, the error INVALID_ENUM is generated.
Additions to the EXT_framebuffer_object extension
- (4.4.2.1) Add the following text at the end of section 4.4.2.1
(Renderbuffer Objects)
The command
void EGLImageTargetRenderbufferStorageOES(enum target,
eglImageOES image)
establishes the data storage, format, and dimensions of a
renderbuffer object's image, using the parameters and storage
associated with the eglImageOES <image>. Assuming no errors
are generated in this process, the resulting renderbuffer
will be an EGLImage target of the specifed eglImageOES <image>.
The renderbuffer will remain an EGLImage target until it is
deleted or respecified by a call to
{Reference}RenderbufferStorageOES. As a result of this referencing
operation, all of the pixel data in the <buffer> used as the
EGLImage source resource (i.e., the <buffer> parameter passed to
the CreateImageOES command that returned <image>) will become
undefined.
<target> must be RENDERBUFFER_OES, and <image> must be the
handle of a valid EGLImage resource, cast into the type
eglImageOES.
If the GL is unable to create a renderbuffer using the specified
eglImageOES, the error INVALID_OPERATION is generated. If <image>
does not refer to a valid eglImageOES object, the error
INVALID_VALUE is generated.
Issues
1. What happens if an application tries to specify a new mipmap
level (or respecify an existing mipmap level) for a texture
object that was originally specified using
EGLImageTargetTexture2D (e.g., by subsequent calls to
{Copy}TexImage, GenerateMipmapOES, and/or setting the
texture's GENERATE_MIPMAP_SGIS parameter to TRUE) ?
RESOLVED: If the application respecifies any properties of
an EGLImage target texture, the GL should allocate additional
memory for the respecified object, copying any data from
previously-specified levels (including those in the EGLImage
source). The respecified texture object will not be an
EGLImage target, potentially orphaning the EGLImage.
2. What happens if multiple texture or renderbuffer objects, which
are each EGLImage siblings, are attached to multiple attachment
points of a framebuffer object?
RESOLVED: There are several possibilities for handling this
situation, listed below. The primary goal for any solution
should be minimizing the required run-time error checking &
validation, since determining that two objects refer to the same
parent resource is a complex operation.
i. Generate an error if a context share group attempts to create
two EGLImage siblings (either source or target) .
This limits error checking to just EGLImageTargetTexture /
EGLImageTargetRenderbufferStorage, which should be infrequent
calls, particularly during run-time. However, some potentially
valuable use cases are restricted with this approach, such
as referencing 2D texture objects from cube map EGLImage sources
in the same context share group.
ii. Add a new clause to the framebuffer completeness test that
disallows multiple EGLImage siblings being attached to the
same framebuffer object.
This would be in the spirit of the OES_framebuffer_object
extension and does not limit any valuable use cases; however,
it has the potential to significantly increase runtime
overhead, given the complexity of this completeness check
and the potential frequency that framebuffer completeness
may need to be checked.
iii. Leave the rendering results undefined, but require that
behavior be limited to undefined rendering results (i.e.,
the application and/or system may not crash as a result
of this operation).
This solution allows implementations the opportunity to have
virtually no additional run-time validation overhead, nor
are any valuable use cases restricted. Implementations
may consider framebuffer objects which contain multiple
EGLImage siblings as incomplete framebuffers if necessary to
ensure application & system stability.
SUGGESTION: Solution (iii). The only reasonable well-defined
behavior for this type of API usage is an error; however, given
the potential for the error check to noticeably increase validation
overhead, leaving this behavior undefined seems like the best
choice.
3. What about portability problems introduced by allowing implementation-
dependent failures?
UNRESOLVED: This is the same issue described in Issue 14 of the
EGL_KHR_image_base specification. Like the resolution for that
issue, this specification should include some minimum
requirements, but leave the larger portability problem
unresolved at the moment.
4. Should EGLImageTargetTexture2DOES and
EGLImageTargetRenderBufferStorageOES result in undefined pixel data,
as with calls to eglCreateImageOES?
UNRESOLVED: One of the problems with allowing the referencing
functions to result in undefined pixel data is that the EGLImage
source object may be part of a larger image structure (such as
an array of mipmap levels-of-detail, or cube map faces). While we
can specify that the pixel data in the EGLImage become undefined
quite easily, specifying that the pixel data in other images become
undefined is more difficult. So, with that discussion, the following
options were considered:
i. Specify that the pixel data in the EGLImage, and other image
arrays associated with the EGLImage source, become undefined
as a result of referencing.
ii. Specify that only the pixel data in the EGLImage becomes
undefined; any data in other image arrays associated with the
EGLImage source must not be affected by the referencing
operation.
iii. Specify that the pixel data in the EGLImage is unaffected as
a result of the referencing operation.
Option (i) gives the greatest flexibility (and potentially ease-
of implementation) to implementers, which should may result in
implementations exporting a larger number of compatible configurations
than the other, stricter options. Additionally, for well-behaved
applications (i.e., applications which perform all resource creation
and referencing prior to use), making the image data undefined will
not have any adverse side effects.
Option (ii) provides option (i)'s benefits if the EGLImage source
is a trivial image (i.e., no additional mipmap levels-of-detail,
3D texture slices, etc.); however, some implementations may be
required to implement potentially-expensive copy operations to support
complex EGLImage source images.
Option (iii) is the strictest, and may significantly impede
implementers' ability to expose compatible configurations.
Weighing the benefits (increased configuration compatibility and ease-
/ performance- of implementation) versus the costs (specification
ugliness), the specification has currently selected option (i),
favoring compatibility and performance.
5. What should the entry point for referencing 2D textures be named?
UNRESOLVED: Unfortunately, OpenGL is not particularly consistent
with texture naming conventions. However, most texture function
names have followed the convention of using a verb- or adjective-
specifier followed by the object type, e.g. : CopyTexImage,
CompressedTexImage, DrawPixels, etc.
Therefore, this issue can be broken into two sub-issues: naming
the verb or adjective and naming the object type.
The following options were considered for the verb or adjective:
a1) Reference / Referenced
a2) EGLImageTarget
Reference (a1) is the verb for creating EGLImage targets from
EGLImages (defined in the EGL_OES_image specification), but
"Reference<blah>" might confuse some developers, since the
direction of the verb sounds backwards.
Therefore, option (a2) has been selected, since the newly-
specified texture object will be an EGLImage target.
And the following options were considered for the object type:
b1) TexImage
b2) Texture
b3) TextureObject
(b1) follows the convention used by other texture specification
functions; however, unlike {Copy,Compressed}TexImage, which
specify only a single mipmap level-of-detail, the referencing
entry point respecifies all image arrays in the texture object.
(b2) and (b3) address the issues with (b1). The OpenGL
specification interchangeably uses "texture" and "texture object"
to refer to the entire collection of image arrays, so either
choice seems reasonable. For brevity, (b2) has been used
in this specification.
Note, though, that eglBindTexImage also respecifies all image
arrays in the texture object, but it does not change the
TexImage suffix.
Another option would be to treat the referencing function as an
attachment, rather than a specification, in which case a more
appropriate name would follow the convention used in the
OES_framebuffer_object extension, such as Texture2DeglImageOES.
6. What should the entry point for referencing renderbuffers be named?
UNRESOLVED: There are far fewer conventions for renderbuffer
function names than there are for textures, so the naming for
this function should use whichever convention is selected
to resolve Issue 5. Given the current selections in that issue,
EGLImageTargetRenderbufferStorage is being used.
Dependencies on EGL_KHR_image, EGL_KHR_image_base, and EGL 1.2
If EGL 1.2 is not supported, or if neither the EGL_OES_image nor
EGL_OES_image_base extensions is supported, all discussion of
EGLImages should be ignored, and any calls to either
EGLImageTargetTexture2DOES or EGLImageTargetRenderbufferStorageOES
should generate the error INVALID_OPERATION.
Dependencies on OES_framebuffer_object
If the OES_framebuffer_object extension is not supported, all
discussion of renderbuffers should be ignored, and all calls to
EGLImageTargetRenderbufferStorageOES should generate the error
INVALID_OPERATION.
Revision History
#8 (April 23, 2015, Jon Leech)
- Fix typo EGLImageTargetTexImage2DOES -> EGLImageTargetTexture2DOES
(Bug 8114).
#7 (April 17, 2014, Jon Leech)
- Add missing error for invalid <image> parameter to
EGLImageTargetTexture2DOES (Bug 5164).
#6 (April 1, 2009, Acorn Pooley, Jon Leech)
- Fix dependancy typo. Mention EGL_KHR_image_base. Correct
spelling of EGL_KHR_image and refer to alternate
EGL_KHR_image_base. Correct dependency on EGL from 1.1 to 1.2.
Change filename in the registry to correspond to capitalization
of the extension string. Don't update the version number
further until all internal edits are completed.
#5 (April 1, 2009, Jon Leech)
- Added more overview pointing to companion EGL extensions.
#4 (April 22, 2007, Jon Leech)
- Added updated 'Status' to reflect OpenKODE 1.0 Provisional.
#3 (December 14, 2006)
- Changed requirement to egl 1.2 to include EGLClientBuffer type.
#2 (October 20, 2006)
- Reworded phrasing describing undefined pixel data as a
result of EGLImageTarget* commands
#1 - Original Release
