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

Name

    KHR_image_pixmap

Name Strings

    EGL_KHR_image_pixmap

Contributors

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

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.

Version

    Version 5, November 13, 2013

Number

    EGL Extension #9

Dependencies

    EGL 1.2 is required.

    EGL_KHR_image_base is required.

    The EGL implementation must define an EGLNativePixmapType (although it
    is not required either to export any EGLConfigs supporting rendering to
    native pixmaps, or to support eglCreatePixmapSurface).

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

Overview

    This extension allows creating an EGLImage from a native pixmap
    image.

New Types

    None

New Procedures and Functions

    None

New Tokens

    Accepted by the <target> parameter of eglCreateImageKHR:

        EGL_NATIVE_PIXMAP_KHR                          0x30B0

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

    Rename section 2.2.2.1 "Native Surface Coordinate Systems" to "Native
    Surface and EGLImage Pixmap Coordinate Systems" and add to the end of
    the section:

   "EGLImages created with target EGL_NATIVE_PIXMAP_KHR share the same
    coordinate system as native pixmap surfaces. When that coordinate system
    is inverted, client APIs must invert their <y> coordinate when accessing
    such images as described above."
    
    Add to section 2.5.1 "EGLImage Specification" (as defined by the
    EGL_KHR_image_base specification), in the description of
    eglCreateImageKHR:

   "Values accepted for <target> are listed in Table aaa, below.

      +-------------------------+--------------------------------------------+
      |  <target>               |  Notes                                     |
      +-------------------------+--------------------------------------------+
      |  EGL_NATIVE_PIXMAP_KHR  |   Used for EGLNativePixmapType objects     |
      +-------------------------+--------------------------------------------+
       Table aaa.  Legal values for eglCreateImageKHR <target> parameter

    ...

    If <target> is EGL_NATIVE_PIXMAP_KHR, <dpy> must be a valid display, <ctx>
    must be EGL_NO_CONTEXT; <buffer> must be a handle to a valid
    NativePixmapType object, cast into the type EGLClientBuffer; and
    attributes other than EGL_IMAGE_PRESERVED_KHR are ignored."

    Add to the list of error conditions for eglCreateImageKHR:

      "* If <target> is EGL_NATIVE_PIXMAP_KHR and <buffer> is not a
         valid native pixmap handle, or if <buffer> is a native pixmap
         whose color buffer format is incompatible with the system's
         EGLImage implementation, the error EGL_BAD_PARAMETER is
         generated.

       * If <target> is EGL_NATIVE_PIXMAP_KHR, and <dpy> is not a valid
         EGLDisplay object the error EGL_BAD_DISPLAY is generated.

       * If <target> is EGL_NATIVE_PIXMAP_KHR, and <ctx> is not EGL_NO_CONTEXT,
         the error EGL_BAD_PARAMETER is generated.

       * If <target> is EGL_NATIVE_PIXMAP_KHR, and <buffer> is not a handle
         to a valid NativePixmapType object, the error EGL_BAD_PARAMETER
         is generated."

Issues

    1) Should this specification allow EGLImages to be created from native
       pixmaps which already have a pixmap surface associated with them, and
       vice versa?

       RESOLVED: Yes. There are practical usecases for this, and it is
       already the application's responsibility to handle any format
       mismatch or synchronization issues that this may allow.

Revision History

#5  (Jon Leech, November 13, 2013)
    - Add Issue #1 regarding use cases for multiple EGL consumer/producers
      of a native pixmap (Bug 7779).

#4  (Jon Leech, October 16, 2013)
    - Add language allowing native pixmap and client API image y coordinate
      convention to differ. Re-base extension against EGL 1.4 (Bug 9701).

#3  (Jon Leech, November 25, 2008)
    - Remove dependency on EGLConfig in error conditions.

#2  (Jon Leech, November 12, 2008)
    - Clarified dependency on EGLNativePixmapType such that pixmap configs
      and surfaces are not required.

#1  (Jon Leech, October 21, 2008)
    - Split native pixmap functionality from EGL_KHR_image into a layered
      extension on EGL_KHR_image_base, and note interaction with the new
      EGL_IMAGE_PRESERVED_KHR attribute.