xref: /third_party/EGL/extensions/KHR/EGL_KHR_image_base.txt

Name

    KHR_image_base

Name Strings

    EGL_KHR_image_base

Contributors

    Jeff Juliano
    Gary King
    Jon Leech
    Jonathan Grant
    Barthold Lichtenbelt
    Aaftab Munshi
    Acorn Pooley
    Chris Wynn

Contacts

    Jon Leech (jon 'at' alumni.caltech.edu)
    Gary King, NVIDIA Corporation (gking 'at' nvidia.com)

Notice

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

Status

    Complete. Functionality approved (as part of KHR_image) by the
    Khronos Board of Promoters on February 11, 2008.

    Split into KHR_image_base and KHR_image_pixmap approved by the
    Khronos Technical Working Group on November 19, 2008. Update to
    version 5 approved on December 10, 2008.

Version

    Version 8, August 27, 2014

Number

    EGL Extension #8

Dependencies

    EGL 1.2 is required.

    An EGL client API, such as OpenGL ES or OpenVG, is required.

    This extension is written against the wording of the EGL 1.2
    Specification.

Overview

    This extension defines a new EGL resource type that is suitable for
    sharing 2D arrays of image data between client APIs, the EGLImage.
    Although the intended purpose is sharing 2D image data, the
    underlying interface makes no assumptions about the format or
    purpose of the resource being shared, leaving those decisions to
    the application and associated client APIs.

Glossary

    EGLImage:  An opaque handle to a shared resource created by EGL
               client APIs, presumably a 2D array of image data

    EGLImage source:  An object or sub-object originally created in
               a client API (such as a mipmap level of a texture object
               in OpenGL-ES, or a VGImage in OpenVG) which is used as
               the <buffer> parameter in a call to eglCreateImageKHR.

    EGLImage target:  An object created in a client API (such as a
               texture object in OpenGL-ES or a VGImage in OpenVG)
               from a previously-created EGLImage

    EGLImage sibling: The set of all EGLImage targets (in all
               client API contexts) which are created from the
               same EGLImage object, and the EGLImage source resouce
               which was used to create that EGLImage.

    Orphaning:  The process of respecifying and/or deleting an EGLImage
               sibling resource (inside a client API context) which
               does not result in deallocation of the memory associated
               with the EGLImage or affect rendering results using other
               EGLImage siblings.

    Referencing:  The process of creating an EGLImage target resource
               (inside a client API context) from an EGLImage.

    Respecification: When the size, format, or other attributes of an
               EGLImage sibling are changed via client API calls such as
               gl*TexImage*. Respecification usually will result in
               orphaning the sibling. Note that changing the pixel values of
               the sibling (e.g. by rendering to it or by calling
               gl*TexSubImage*) does not constitute respecification.

New Types

    /*
     * EGLImageKHR is an object which can be used to create EGLImage
     * target resources (inside client APIs).
     */
    typedef void* EGLImageKHR;

New Procedures and Functions

    EGLImageKHR eglCreateImageKHR(
                            EGLDisplay dpy,
                            EGLContext ctx,
                            EGLenum target,
                            EGLClientBuffer buffer,
                            const EGLint *attrib_list)

    EGLBoolean eglDestroyImageKHR(
                            EGLDisplay dpy,
                            EGLImageKHR image)

New Tokens

    Returned by eglCreateImageKHR:

        EGL_NO_IMAGE_KHR                                     ((EGLImageKHR)0)

    Accepted as an attribute in the <attrib_list> parameter of
    eglCreateImageKHR:

        EGL_IMAGE_PRESERVED_KHR                              0x30D2

Additions to Chapter 2 of the EGL 1.2 Specification (EGL Operation)

    Add a new section "EGLImages" after section 2.4:

    "2.5 EGLImages

    As described in section 2.4, EGL allows contexts of the same client
    API type to share significant amounts of state (such as OpenGL-ES
    texture objects and OpenVG paths); however, in some cases it may
    be desirable to share state between client APIs - an example would be
    using a previously-rendered OpenVG image as an OpenGL-ES texture
    object.

    In order to facilitate these more complicated use-cases, EGL is capable
    of creating EGL resources that can be shared between contexts of
    different client APIs (called "EGLImages") from client API resources
    such as texel arrays in OpenGL-ES texture objects or OpenVG VGImages
    (collectively, the resources that are used to create EGLImages are
    referred to as "EGLImage sources").

    The EGL client APIs each provide mechanisms for creating appropriate
    resource types (such as complete texture arrays or OpenVG VGImages) from
    EGLImages through a API-specific mechanisms.  Collectively, resources
    which are created from EGLImages within client APIs are referred to as
    "EGLImage targets."  Each EGLImage may have multiple associated EGLImage
    targets.  Collectively, the EGLImage source and EGLImage targets
    associated with an EGLImage object are referred to as "EGLImage
    siblings."

    2.5.1  EGLImage Specification

    The command

        EGLImageKHR eglCreateImageKHR(
                                EGLDisplay dpy,
                                EGLContext ctx,
                                EGLenum target,
                                EGLClientBuffer buffer,
                                const EGLint *attrib_list)

    is used to create an EGLImage from an existing image resource <buffer>.
    <dpy> specifies the EGL display used for this operation.
    <ctx> specifies the EGL client API context
    used for this operation, or EGL_NO_CONTEXT if a client API context is not
    required.  <target> specifies the type of resource being used as the
    EGLImage source (examples include two-dimensional textures in OpenGL ES
    contexts and VGImage objects in OpenVG contexts).  <buffer> is the name
    (or handle) of a resource to be used as the EGLImage source, cast into the
    type EGLClientBuffer.  <attrib_list> is an list of attribute-value pairs
    which is used to select sub-sections of <buffer> for use as the EGLImage
    source, such as mipmap levels for OpenGL ES texture map resources, as well as
    behavioral options, such as whether to preserve pixel data during creation. If
    <attrib_list> is non-NULL, the last attribute specified in the list must
    be EGL_NONE.

    The resource specified by <dpy>, <ctx>, <target>, <buffer>, and
    <attrib_list> must not itself be an EGLImage sibling, or bound to an EGL
    PBuffer resource (eglBindTexImage, eglCreatePbufferFromClientBuffer).

    Values accepted for <target> are listed in Table aaa, below(fn1).
        (fn1) No values are defined by this extension. All functionality
        to create EGLImages from other types of resources, such as
        native pixmaps, GL textures, and VGImages, is layered in other
        extensions.

      +-------------------------+--------------------------------------------+
      |  <target>               |  Notes                                     |
      +-------------------------+--------------------------------------------+
      +-------------------------+--------------------------------------------+
       Table aaa.  Legal values for eglCreateImageKHR <target> parameter

    Attribute names accepted in <attrib_list> are shown in Table bbb,
    together with the <target> for which each attribute name is valid, and
    the default value used for each attribute if it is not included in
    <attrib_list>.

      +-------------------------+----------------------+-----------+---------------+
      | Attribute               | Description          | Valid     | Default Value |
      |                         |                      | <target>s |               |
      +-------------------------+----------------------+-----------+---------------+
      | EGL_NONE                | Marks the end of the | All       | N/A           |
      |                         | attribute-value list |           |               |
      | EGL_IMAGE_PRESERVED_KHR | Whether to preserve  | All       | EGL_FALSE     |
      |                         | pixel data           |           |               |
      +-------------------------+----------------------+-----------+---------------+
       Table bbb.  Legal attributes for eglCreateImageKHR <attrib_list> parameter

    This command returns an EGLImageKHR object corresponding to the image
    data specified by <dpy>, <ctx>, <target>, <buffer> and <attrib_list> which
    may be referenced by client API operations, or EGL_NO_IMAGE_KHR in the
    event of an error.

    If the value of attribute EGL_IMAGE_PRESERVED_KHR is EGL_FALSE (the
    default), then all pixel data values associated with <buffer> will be
    undefined after eglCreateImageKHR returns.

    If the value of attribute EGL_IMAGE_PRESERVED_KHR is EGL_TRUE, then all
    pixel data values associated with <buffer> are preserved.

    Errors

        If eglCreateImageKHR fails, EGL_NO_IMAGE_KHR will be returned, the
        contents of <buffer> will be unaffected, and one of the following
        errors will be generated:

       * If <dpy> is not the handle of a valid EGLDisplay object, the error
         EGL_BAD_DISPLAY is generated.

       * If <ctx> is neither the handle of a valid EGLContext object on
         <dpy> nor EGL_NO_CONTEXT, the error EGL_BAD_CONTEXT is
         generated.

       * If <target> is not one of the values in Table aaa, the error
         EGL_BAD_PARAMETER is generated.

       * If an attribute specified in <attrib_list> is not one of the
         attributes listed in Table bbb, the error EGL_BAD_PARAMETER is
         generated.

       * If an attribute specified in <attrib_list> is not a valid attribute
         for <target>, as shown in Table bbb, the error EGL_BAD_MATCH is
         generated.

       * If the resource specified by <dpy>, <ctx>, <target>, <buffer> and
         <attrib_list> has an off-screen buffer bound to it (e.g., by a
         previous call to eglBindTexImage), the error EGL_BAD_ACCESS is
         generated.

       * If the resource specified by <dpy>, <ctx>, <target>, <buffer> and
         <attrib_list> is bound to an off-screen buffer (e.g., by a previous
         call to eglCreatePbufferFromClientBuffer), the error
         EGL_BAD_ACCESS is generated.

       * If the resource specified by <dpy>, <ctx>, <target>, <buffer> and
         <attrib_list> is itself an EGLImage sibling, the error
         EGL_BAD_ACCESS is generated.

       * If insufficient memory is available to complete the specified
         operation, the error EGL_BAD_ALLOC is generated.

       * If the call to eglCreateImageKHR fails for multiple reasons, the
         generated error must be appropriate for one of the reasons,
         although the specific error returned is undefined.

       * If the value specified in <attrib_list> for EGL_IMAGE_PRESERVED_KHR
         is EGL_TRUE, and an EGLImageKHR handle cannot be created from the
         specified resource such that the pixel data values in <buffer> are
         preserved, the error EGL_BAD_ACCESS is generated.

    Note that the success or failure of eglCreateImageKHR should not affect
    the ability to use <buffer> in its original API context (or context
    share group) (although the pixel data values will be undefined if
    EGL_IMAGE_PRESERVED_KHR is not EGL_TRUE).

    2.5.2  Lifetime and Usage of EGLImages

    Once an EGLImage is created from an EGLImage source, the memory associated
    with the EGLImage source will remain allocated (and all EGLImage siblings
    in all client API contexts will be useable) as long as either of the
    following conditions is true:
      A)  Any EGLImage siblings exist in any client API context
      B)  The EGLImage object exists inside EGL

    The semantics for specifying, deleting and using EGLImage siblings are
    client API-specific, and are described in the appropriate API
    specifications.

    If an application specifies an EGLImage sibling as the destination for
    rendering and/or pixel download operations (e.g., as an OpenGL-ES
    framebuffer object, glTexSubImage2D, etc.), the modified image results
    will be observed by all EGLImage siblings in all client API contexts.
    If multiple client API contexts access EGLImage sibling resources
    simultaneously, with one or more context modifying the image data,
    rendering results in all contexts accessing EGLImage siblings are
    undefined.

    Respecification and/or deletion of any EGLImage sibling (i.e., both
    EGLImage source and EGLImage target resources) inside a client API
    context (e.g., by issuing a subsequent call to
    gl{Copy,Compressed}TexImage, glDeleteTextures, with the EGLImage
    sibling resource as the target of the operation) affects only that
    client API context and other contexts within its share group.  The
    specific semantics for this behavior are defined by each client API,
    and generally results in orphaning of the EGLImage, and may also
    include allocation of additional memory for the respecified resource
    and/or copying of the EGLImage pixel data.

    Operations inside EGL or any client API context which may affect the
    lifetime of an EGLImage (or the memory allocated for the EGLImage),
    such as respecifying and/or deleting an EGLImage sibling inside a
    client API context, must be atomic.

    Applications may create client API resources from an EGLImageKHR using
    client API extensions outside the scope of this document (such as
    GL_OES_EGL_image, which creates OpenGL ES texture and renderbuffer
    objects). If the EGLImageKHR used to create the client resource was
    created with the EGL_IMAGE_PRESERVED_KHR attribute set to EGL_TRUE, then
    the pixel data values associated with the image will be preserved after
    creating the client resource; otherwise, the pixel data values will be
    undefined. If the EGLImageKHR was created with the
    EGL_IMAGE_PRESERVED_KHR attribute set to EGL_TRUE, and EGL is unable to
    create the client resource without modifying the pixel values, then
    creation will fail and the pixel data values will be preserved.

    The command

        EGLBoolean eglDestroyImageKHR(
                            EGLDisplay dpy,
                            EGLImageKHR image)

    is used to destroy the specified EGLImageKHR object <image>.  Once
    destroyed, <image> may not be used to create any additional EGLImage
    target resources within any client API contexts, although existing
    EGLImage siblings may continue to be used.  EGL_TRUE is returned
    if DestroyImageKHR succeeds, EGL_FALSE indicates failure.

       * If <dpy> is not the handle of a valid EGLDisplay object, the error
         EGL_BAD_DISPLAY is generated.

       * If <image> is not a valid EGLImageKHR object created with respect
         to <dpy>, the error EGL_BAD_PARAMETER is generated."

    Add a new error to the list at the bottom of Section 3.5.3 (Binding
    Off-Screen Rendering Surfaces to Client Buffers):

       "* If the buffers contained in <buffer> consist of any EGLImage
          siblings, an EGL_BAD_ACCESS error is generated."

Issues

    1.  What resource types should be supported by this extension?

        RESOLVED:  This specification is designed to support the
        sharing of two-dimensional image resources between client APIs,
        as these resources are a fundamental component of all modern
        graphics APIs.

        Other resources types (e.g., buffer objects) will not be directly
        supported by this specification, due to a variety of reasons:

            a.  An absense of use cases for this functionality
            b.  Handling the semantics for some of these resources
                (e.g., glMapBuffer) would significantly complicate
                and delay this specification.
            c.  A desire to address the image-sharing use cases
                as quickly as possible.

        Should additional resource-sharing functionality be desired
        in the future, the framework provided by this specification
        should be extendable to handle more general resource
        sharing.

    2.  Should this specification address client API-specific resources
        (OpenGL texture maps, OpenVG VGImages), or should that
        functionality be provided by layered extensions?

        SUGGESTION: Use layered extensions, even for for sharing image
        data with native rendering APIs (the EGL_KHR_image_pixmap
        extension).

        There are two major arguments for using layered extensions:

          1.  The two client APIs which are defined at the time of this
              specification (OpenVG, OpenGL ES) may not always be
              deployed on a device; many devices may choose to implement
              just one of these two APIs.  However, even single-API
              devices may benefit from the ability to share image data
              with native rendering APIs (provided in this specification)
              or with the OpenMAX API.

          2.  OpenGL ES defines a number of optional resource types
              (cubemaps, renderbuffers, volumetric textures) which this
              framework should support; however, implementations may not.
              By layering each of these resource types in individual
              extensions, implementations which are limited to just the
              core OpenGL ES 1.1 (or OpenGL ES 2.0) features will not
              need to add EGLImage enumerant support for unsupported
              resource types.

        The original EGL_KHR_image extension included native pixmap
        functionality. We have now split the abstract base functionality
        (the egl{Create,Destroy}ImageKHR APIs) from the native pixmap
        functionality, and redefined EGL_KHR_image as the combination of
        EGL_KHR_image_base and EGL_KHR_image_pixmap.

    3.  Should attributes (width, height, format, etc.) for EGLImages
        be queriable?

        SUGGESTION:  No.  Given the wealth of attributes that we would
        need to specify all possible EGLImages (and possible
        memory layout optimizations performed by implementations), we
        can dramatically simplify the API without loss of key
        functionality by making EGLImages opaque and allowing
        implementations to make the correct decisions internally.

    4.  Should this specification allow the creation of EGLImages from
        client API resources which are themselves EGLImage targets?

        RESOLVED:  No.  This can make memory garbage collection and
        reference counting more difficult, with no practical benefit.
        Instead, generate an error if an application attempts to
        create an EGLImage from an EGLImage target resource.

    5.  Should this specification allow multiple EGLImages to be created
        from the same EGLImage source resource?

        RESOLVED:  No.  The resource <buffer> specified to
        eglCreateImageKHR may include multiple sub-objects; examples are
        mipmapped images and cubemaps in the OpenGL-ES API.  However, the
        EGLImage source is defined as the specific sub-object that is defined
        by: <ctx>, <target>, <buffer>, and <attrib_list>.  This sub-object must
        not be an EGLImage sibling (either EGLImage source or EGLImage target)
        when eglCreateImageKHR is called; however, other sub-objects in
        <buffer> may be EGLImage siblings.  This allows applications to share
        individual cubemap faces, or individual mipmap levels of detail across
        all of the supported APIs.

        Note that the EGLImage source and any EGLImage target resources
        will still be EGLImage siblings, even if the EGLImage object
        is destroyed by a call to DestroyImageKHR.

    6.  If an EGLImage sibling is respecified (or deleted), what
        should happen to the EGLImage and any other EGLImage
        siblings?

        RESOLVED:  The principle of least surprise would dictate that
        respecification and/or deletion of a resource in one client API
        should not adversely affect operation in other client APIs
        (such as introducing errors).

        Applying this to EGLImages, respecification and/or deletion
        of one EGLImage sibling should not respecify/delete other
        EGLImage siblings.  Each client API will be responsible for
        defining appropriate semantics to meet this restriction;
        however, example behaviors may include one or more of:
        allocating additional memory for the respecified resource,
        deleting the EGLImage sibling resource without deallocating
        the associated memory ("orphaning") and/or copying the
        existing EGLImage pixel data to an alternate memory location.

        The memory associated with EGLImage objects should remain
        allocated as long as any EGLImage sibling resources exist
        in any client API context.

    7.  Should this specification address synchronization issues
        when multiple client API contexts simultaneously access EGLImage
        sibling resources?

        RESOLVED:  No.  Including error-producing lock and synchronization
        semantics would introduce additional (undesirable) validation
        overhead in numerous common operations (e.g., glBindTexture,
        glDrawArrays, etc.).  Rather than burdening implementations (and
        applications) with this overhead, a separate synchronization
        mechanism should be exposed to applications.

    8.  Should eglCreatePbufferFromClientBuffer accept buffer parameters
        which are EGLImage siblings?

        RESOLVED:  No.  Allowing this behavior creates very complex
        circular dependency possibilities (CreateImage / DeriveImage /
        CreatePbufferFromClientBuffer / BindTexImage /
        CreateImage / ...) with no practical benefit.  Therefore,
        attempting to create a Pbuffer from a client buffer which
        is an EGLImage sibling should generate an error.

    9.  Should CreateImage accept client buffers which are bound to
        Pbuffers (through eglBindTexImage)?

        RESOLVED:  No, for the same reasons listed in Issue 8.

    10. Should implementations be allowed to modify the pixel data in the
        EGLImage source buffers specified to eglCreateImageKHR?

        SUGGESTION:  By allowing previously-existing image data to become
        undefined after calls to eglCreateImageKHR, implementations are able
        to perform any necessary reallocations required for cross-API
        buffer compatibility (and/or performance), without requiring
        copy-aside functionality.  Because applications are able to
        respecify the pixel data through mechanisms such as vgSubImage
        and glTexSubImage, no use-cases are restricted by this.

        Therefore, the current suggestion is to allow implementations
        to leave pixel data undefined after calls to eglCreateImageKHR
        functions.  The current spec revision has been written in
        this way.

    11. What is the correct mechanism for specifying the EGLImage source
        resources used to create an EGLImage object?

        RESOLVED:  Three different mechanisms were discussed while
        defining this extension:

            A)  Providing resource-specific creation functions, such as
                eglCreateImage2DKHR, eglCreateImage3DKHR, etc.

            B)  Providing a single creation function which returns a
                "NULL" EGLImage object, and requiring client APIs to
                define additional functions which would allow client API
                resources to be "bound" to the EGLImage object.

            C)  Provide a single resource creation function, and use
                an attribute-value list with attributes specific to the
                "target" image resource.

        Initial specifications were written using Option (A); however,
        it was believed that this structure would result in an increase
        in the number of entry points over time as additional client APIs
        and client API resource targets were added.  Furthermore, reuse
        of these functions was resulting in cases where parameters were
        required to have modal behavior: a 2D image creation function
        was required to have a mipmap level of detail parameter for
        OpenGL ES texture maps, but this same parameter would need to be
        0 for OpenVG.

        Option (B) provided some nice characteristics: as client APIs
        continue to evolve, any extensions needed to allow EGLImage
        creation could be isolated in the individual client API, rather
        than necessitating an EGL extension.  However, the creation of
        "NULL" images created additional semantic complexity and error
        conditions (e.g., attempting to derive an EGLImage target from a
        "NULL" image), and every client API would need to provide a
        function for every unique resource type; instead of one common
        API function for pixmap, OpenGL 2D textures, and OpenVG VGImages,
        three would be required.

        This specification is written using Option (C).  There is a
        single CreateImage function, with a <target> parameter defining
        the EGLImage source type, and an attribute-value list allowing
        for additional selection of resource sub-sections.  This
        maximizes entry-point reuse, and minimizes the number of
        redundant parameters an application may be required to send.
        This framework allows for layered extensions to be easily
        written, so little churn is expected as client APIs evolve.

    12. Should a context be explicitly provided to eglCreateImageKHR,
        or should the context be deduced from the current thread's
        bound API?

        SUGGESTION:  For clarity (both in usage and spec language), the
        context containing the EGLImage source should be provided by the
        application, rather than inferring the context from EGL state.

    13. Why does this extension define a new EGL object type, rather
        than using the existing EGLSurface objects?

        RESOLVED:  Although controversial, the creation of a new,
        opaque image object type removes several fundamental problems
        with the EGLSurface (and Pbuffer) API:

            1)  The tight compatibility requirements of EGLSurfaces
                and EGLConfigs necessitated applications creating
                (and calling MakeCurrent) for every unique pixel
                format used during rendering.  This has already caused
                noticeable performance problems in OpenGL-ES (and
                desktop OpenGL), and is the primary reason that
                framebuffer objects were created.

            2)  Application use-cases are centered around sharing of
                color image data, although unique "sundry" buffers
                (such as depth, stencil and alpha mask) may be used
                in each client API.

            3)  Extending the CreatePbuffer interface to support fully-
                specifying all possible buffer attributes in all client
                APIs will become unwieldy, particularly as new EGL
                client APIs and pixel formats are introduced.

        The EGLImage proposal addresses all three of these restrictions:

        1) is addressed by placing the burden of framebuffer management
        inside the client API, and allowing EGLImages to be accessed
        inside client APIs using an appropriate resource type (such
        as OpenGL-ES renderbuffers).  This follows the example provided
        by the GL_OES_framebuffer_object specification.

        2) is addressed by defining EGLImages to be "trivial" two-
        dimensional arrays of pixel data.  Implementations may choose
        to support creation of EGLImages from any type of pixel data,
        and the association of multiple EGLImages and/or sundry
        buffers into a single framebuffer is the responsibility of the
        application and client API, using a mechanism such as
        GL_OES_framebuffer_object.

        3) is addressed by defining EGLImages as opaque and
        non-queriable.  Although this introduces potential portability
        problems (addressed separately in issue 15), it avoids the
        ever-expanding problem of defining buffer compatibility as the
        cartesian product of all possible buffer attributes.

    14. Since referencing EGLImages is the responsibility of the client
        API, and may fail for implementation-dependent reasons,
        doesn't this result in a potential portability problem?

        UNRESOLVED:  Yes, this portability problem (where referencing
        succeeds on one platform but generates errors on a different
        one) is very similar to the implementation-dependent
        failure introduced in the EXT_framebuffer_object specification,
        discussed (at length) in Issues (12), (37), (46), (48) and (61)
        of that specification.  Similar to that specification, this
        specification should include some "minimum requirements"
        language for EGLImage creation and referencing.

        Since there are numerous references to an upcoming
        "format restriction" API in the EXT_framebuffer_object
        specification, it may be valuable to wait until that API is
        defined before attempting to define a similar API for
        EGLImages.

    15. Should creation of an EGLImage from an EGLImage source
        introduce the possibility for errors in the EGLImage source's
        owning context?

        RESOLVED:  No; although image data may be undefined (issue 11),
        the (successful or unsuccessful) creation of an EGLImage should
        not introduce additional error conditions in the EGLImage
        source's owning context.  Text added to the end of section
        2.5.1 describing this.

    16. Is it reasonable to require that when a preserved EGLImage is
        used by layered extensions to create client API siblings of that
        image, pixel data values are preserved?

        UNRESOLVED: There are at least two extensions that reference
        EGLImages to create EGLImage targets, VG_KHR_EGL_image and
        GL_OES_EGL_image.

        Each of these extensions makes provision for failing the creation of
        the EGLImage target due to "an implementation-dependent reason".
        This could include that the pixel data has been marked as preserved,
        and that the implementation is not able to create the EGLImage
        target without causing the pixel data of the original EGLImage
        source <buffer> to become undefined.

        Issue 14 of EGL_KHR_image also discusses the consequences of failure
        for implementation-dependent reasons. This implies that all
        extensions for referencing an EGLImage need to make provision for
        implementation-dependent failure.

        PROPOSED: Yes, this is reasonable. We should add "EGL_KHR_image_base
        affects the behavior of this extension" sections to the ES and VG
        extensions. Implementations can continue to export EGL_KHR_image if
        they are unable to support preserved image functionality.

    17. Do EGLImage Target creation extensions such as VG_KHR_EGL_image and
        GL_OES_EGL_image also need to be extended?

        UNRESOLVED: The problem here is that both these extensions
        explicitly state that pixel data becomes undefined when they
        reference an EGLImage to create an EGLImage target.

        One solution would be to allow this extension to do the defining on
        behalf of these extensions. For example, the VG_KHR_EGL_image
        extension on its own leaves the status of the pixel data undefined,
        but when VG_KHR_EGL_image is combined with this extension, then the
        status becomes defined (by this extension).

        When combined with the reasons given in Issue 1, this means it is
        possible to leave EGLImage Target creation extensions unchanged.

        PROPOSED: Yes, augment these extensions as described in issue 16.

    18. Is it reasonable for developers to want to preserve pixel data upon
        creation of EGLImage and EGLImage targets?

        RESOLVED: Yes. This is necessary for composition implementations
        using EGLImages as an encapsulation mechanism for moving data
        between producer application, composition API, and composition
        implementation(s).

    19. Should we really change the default value of EGL_IMAGE_PRESERVED_KHR
        when EGL_KHR_image is supported?

        RESOLVED: No. This is a subtle and hard to diagnose source of
        errors, and the only way to write a portable app would still be
        to explicitly specify the attribute value. By making the default
        value FALSE no matter which of the two extension(s) are
        supported, compatibility with EGL_KHR_image is preserved, and
        apps must explicitly ask for preservation if they need it.

    20. Why is EGL_NO_DISPLAY not supported as the <dpy> argument for
        creating and destroying images, unlike the original version of the
        EGL_KHR_image specification?

        RESOLVED: There are no defined use cases for this at present, so
        there is no way to legally pass in EGL_NO_DISPLAY. If in the future,
        a layered extension allows creation of images not associated with
        any display, this behavior can be reintroduced.


Revision History

#8  (Jon Leech, August 27, 2014)
    - Remove leftover comment saying that inapplicable attributes are
      ignored (Bug 12585).

#7  (Jon Leech, June 12, 2013)
    - Add a column to table bbb specifying which <target>s attributes are
      valid for, and a generic error if an attribute doesn't match <target>
      (Bug 10151).

#6  (Jon Leech, December 1, 2010)
    - Clarify wording of EGL_BAD_CONTEXT error.

#5  (Jon Leech, December 10, 2008)
    - Change definition of EGL_NO_IMAGE_KHR to 0 (appropriately cast)
      instead of a reference to an extern implementation-defined
      variable.

#4  (Jon Leech, November 25, 2008)
    - Simplify error conditions for eglDestroyImage.

#3  (Jon Leech, November 12, 2008)
    - Added glossary entry for Respecification, updated description of
      behavior with preserved images per suggestions from Acorn, and added
      issue 20 regarding removal of EGL_NO_DISPLAY as a valid <dpy>.

#2  (Jon Leech, October 22, 2008)
    - Change default value of EGL_IMAGE_PRESERVED_KHR to EGL_FALSE.
      Update issue 19.

#1  (Jon Leech, October 21, 2008)
    - Split abstract functionality from EGL_KHR_image into this extension,
      and merged preserved image functionality from
      EGL_SYMBIAN_image_preserved.