xref: /third_party/openGLES/extensions/OES/OES_EGL_image.txt

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