OES_EGL_image

GL_OES_EGL_image

Gary King
Acorn Pooley
Jon Leech

Gary King, NVIDIA Corporation (gking 'at' nvidia.com)

Copyright (c) 2006-2014 The Khronos Group Inc. Copyright terms at
    http://www.khronos.org/registry/speccopyright.html

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

Approved by the Khronos OpenKODE Working Group in January, 2007
as part of OpenKODE 1.0 Provisional.

April 23, 2015 (version 8)

OpenGL ES Extension #23

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.

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/

Please see the EGL_KHR_image specification for a list of terms
used by this specification.

/*
 * GLeglImageOES is an opaque handle to an EGLImage
 */
typedef void* GLeglImageOES;

void EGLImageTargetTexture2DOES(enum target, eglImageOES image)

void EGLImageTargetRenderbufferStorageOES(enum target,
                                          eglImageOES image)

 None.

- (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.

- (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.

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.

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.

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.

#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