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

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