IMG_image_plane_attribs

EGL_IMG_image_plane_attribs

Ben Bowman
Alistair Strachan

Tobias Hector, Imagination Technologies (tobias 'dot' hector 'at'
imgtec 'dot' com)

Complete

Version 0.4, October 18, 2015

EGL Extension #95

EGL_KHR_image_base is required.

One of EGL_KHR_image, EGL_KHR_image_pixmap or
EGL_ANDROID_image_native_buffer is required.

This extension is written against the wording of the EGL 1.2
Specification as modified by EGL_KHR_image_base,
EGL_ANDROID_image_native_buffer and EGL_KHR_image_pixmap.
This extension interacts with GL_OES_EGL_image and GL_EXT_texture_rg.

This extension allows creating an EGLImage from a single plane of a
multi-planar Android native image buffer (ANativeWindowBuffer) or
a native pixmap (EGLNativePixmap).

None

None

Accepted by the <attrib_list> parameter of eglCreateImageKHR:

    EGL_NATIVE_BUFFER_MULTIPLANE_SEPARATE_IMG        0x3105
    EGL_NATIVE_BUFFER_PLANE_OFFSET_IMG               0x3106

Add to section 2.5.1 "EGLImage Specification" (as defined by the
EGL_KHR_image_base specification), in the description of
eglCreateImageKHR:

Add the following to Table bbb (Legal attributes for eglCreateImageKHR
<attr_list> parameter), Section 2.5.1 (EGLImage Specification)

  +-----------------------------+-------------------------+---------------------------+---------------+
  | Attribute                   | Description             | Valid <target>s           | Default Value |
  +-----------------------------+-------------------------+---------------------------+---------------+
  | EGL_NATIVE_BUFFER_MULTI     | Whether a multiplane    | EGL_NATIVE_BUFFER_ANDROID | EGL_FALSE     |
  | PLANE_SEPARATE_IMG          | native buffer should be | EGL_NATIVE_PIXMAP_KHR     |               |
  |                             | treated as separate     |                           |               |
  |                             | buffers                 |                           |               |
  |                             |                         |                           |               |
  | EGL_NATIVE_BUFFER_          | Which plane of a multi- | EGL_NATIVE_BUFFER_ANDROID | 0             |
  | PLANE_OFFSET_IMG            | plane native buffer is  | EGL_NATIVE_PIXMAP_KHR     |               |
  |                             | used as the EGLImage    |                           |               |
  |                             | source                  |                           |               |
  +-----------------------------+-------------------------+---------------------------+---------------+
  Table bbb. Legal attributes for eglCreateImageKHR <attrib_list> parameter

...

If <target> is EGL_NATIVE_BUFFER_ANDROID or EGL_NATIVE_PIXMAP_KHR, and
<buffer> is a handle to a valid multi-planar surface, such as a YUV420 2 or
3 planar video surface, an EGLImage will be created from only one of the
planes, as opposed to a single image representing all of the planes as is
normally the case. The intention of this extension is that a call to
glEGLImageTargetTexture2DOES or EGLImageTargetRenderbufferStorageOES with an
EGLImage created from a single plane of a multiplanar buffer will result in
a GL_RED or GL_RG  texture or renderbuffer, depending on the format of the
multiplanar buffer. This allows an application to work directly in the YUV
colorspace, rather than forcing a conversion to the linear RGB colorspace,
potentially losing precision.

The size of each image will represent the actual size of the data buffer
for that plane which may mean that the size of an EGLImage created from
plane 0 of a multi-planar buffer may not be the same as that of one
created from plane 1, which is determined by the YUV's sampling ratio (e.g.
a 420 will have planes 1 and 2, if present, represented by an image of half
the width).

Add to the list of error conditions for eglCreateImageKHR:

  "* If EGL_NATIVE_BUFFER_MULTIPLANE_SEPARATE_IMG is EGL_TRUE, and <target>
     is not EGL_NATIVE_BUFFER_ANDROID or EGL_NATIVE_PIXMAP_KHR, the error
     EGL_BAD_PARAMETER is generated.

   * If EGL_NATIVE_BUFFER_MULTIPLANE_SEPARATE_IMG is EGL_TRUE, and
     EGL_NATIVE_BUFFER_PLANE_OFFSET_IMG is greater than or equal to the
     number of planes in <buffer>, the error EGL_BAD_MATCH is generated.

   * If EGL_NATIVE_BUFFER_MULTIPLANE_SEPARATE_IMG is EGL_FALSE, and
     EGL_NATIVE_BUFFER_PLANE_OFFSET_IMG is greater than 0, the error
     EGL_BAD_PARAMETER is generated.

   * If EGL_NATIVE_BUFFER_MULTIPLANE_SEPARATE_IMG is EGL_TRUE, and the
     format of <buffer> is not supported by the implementation,
     EGL_BAD_PARAMETER is generated."

If neither of these extensions are supported, remove all references to
native pixmaps and EGL_NATIVE_PIXMAP_KHR.

If this extension is not supported, remove all references to
ANativeWindowBuffer and EGL_NATIVE_BUFFER_ANDROID.

None