egl: Add EGL_WAYLAND_PLANE_WL attribute

This lets us specify the plane to create the image for for multiplanar
wl_buffers.

Signed-off-by: Kristian Høgsberg <krh@bitplanet.net>

1 files changed, 87 insertions, 3 deletions

diff --git a/docs/WL_bind_wayland_display.spec b/docs/WL_bind_wayland_display.spec
index e2fde3c507b..e1aca538003 100644
--- a/docs/WL_bind_wayland_display.spec
+++ b/docs/WL_bind_wayland_display.spec
@@ -56,12 +56,34 @@ New Procedures and Functions
     EGLBoolean eglUnbindWaylandDisplayWL(EGLDisplay dpy,
                                          struct wl_display *display);
 
+    EGLBoolean eglQueryWaylandBufferWL(EGLDisplay dpy,
+                                       struct wl_buffer *buffer,
+                                       EGLint attribute, EGLint *value);
+
 New Tokens
 
     Accepted as <target> in eglCreateImageKHR
 
         EGL_WAYLAND_BUFFER_WL                   0x31D5
 
+    Accepted in the <attrib_list> parameter of eglCreateImageKHR:
+
+        EGL_WAYLAND_PLANE_WL                    0x31D6
+
+
+    Accepted as a eglQueryWaylandBufferWL attribute:
+
+        EGL_WAYLAND_BUFFER_COMPONENTS_WL	0x31D7
+
+    Possible values for EGL_WAYLAND_BUFFER_COMPONENTS_WL:    
+
+        EGL_WAYLAND_BUFFER_RGB_WL               0x31D8
+        EGL_WAYLAND_BUFFER_RGBA_WL              0x31D9
+        EGL_WAYLAND_BUFFER_Y_U_V_WL             0x31Da
+        EGL_WAYLAND_BUFFER_Y_UV_WL              0x31Db
+        EGL_WAYLAND_BUFFER_Y_XUXV_WL            0x31Dc
+
+
 Additions to the EGL 1.4 Specification:
 
     To bind a server side wl_display to an EGLDisplay, call
@@ -80,9 +102,65 @@ Additions to the EGL 1.4 Specification:
     eglUnbindWaylandDisplayWL returns EGL_FALSE when there is no
     wl_display bound to the EGLDisplay currently otherwise EGL_TRUE.
 
-    Import a wl_buffer by calling eglCreateImageKHR with
-    wl_buffer as EGLClientBuffer, EGL_WAYLAND_BUFFER_WL as the target,
-    NULL context and an empty attribute_list.
+    A wl_buffer can have several planes, typically in case of planar
+    YUV formats.  Depending on the exact YUV format in use, the
+    compositor will have to create one or more EGLImages for the
+    various planes.  The eglQueryWaylandBufferWL function should be
+    used to first query the wl_buffer components using
+    EGL_WAYLAND_BUFFER_COMPONENTS_WL as the attribute.  If the
+    wl_buffer object is not an EGL wl_buffer (wl_shm and other wayland
+    extensions can create wl_buffer objects), this query will return
+    EGL_FALSE.  In that case the wl_buffer can not be used with EGL
+    and the compositor should have another way to get the buffer
+    contents.
+
+    If eglQueryWaylandBufferWL succeeds, the returned value will be
+    one of EGL_WAYLAND_BUFFER_RGB_WL, EGL_WAYLAND_BUFFER_RGBA_WL,
+    EGL_WAYLAND_BUFFER_Y_U_V_WL, EGL_WAYLAND_BUFFER_Y_UV_WL,
+    EGL_WAYLAND_BUFFER_Y_XUXV_WL.  The value returned describes how
+    many EGLImages must be used, which components will be sampled from
+    each EGLImage and how they map to rgba components in the shader.
+    The naming conventions separates planes by _ and within each
+    plane, the order or R, G, B, A, Y, U, and V indicates how those
+    components map to the rgba value returned by the sampler.  X
+    indicates that the corresponding component in the rgba value isn't
+    used.
+
+    RGB and RGBA buffer types:
+
+        EGL_WAYLAND_BUFFER_RGB_WL
+                One plane, samples RGB from the texture to rgb in the
+                shader.  Alpha channel is not valid.
+
+        EGL_WAYLAND_BUFFER_RGBA_WL              0x31D9
+                One plane, samples RGBA from the texture to rgba in the
+                shader.
+
+    YUV buffer types:
+
+        EGL_WAYLAND_BUFFER_Y_U_V_WL             0x31Da
+                Three planes, samples Y from the first plane to r in
+                the shader, U from the second plane to r, and V from
+                the third plane to r.
+
+        EGL_WAYLAND_BUFFER_Y_UV_WL              0x31Db
+                Two planes, samples Y from the first plane to r in
+                the shader, U and V from the second plane to rg.
+
+        EGL_WAYLAND_BUFFER_Y_XUXV_WL            0x31Dc
+                Two planes, samples Y from the first plane to r in
+                the shader, U and V from the second plane to g and a.
+
+    After querying the wl_buffer layout, create EGLImages for the
+    planes by calling eglCreateImageKHR with wl_buffer as
+    EGLClientBuffer, EGL_WAYLAND_BUFFER_WL as the target, NULL
+    context.  If no attributes are given, an EGLImage will be created
+    for the first plane.  For multi-planar buffers, specify the plane
+    to create the EGLImage for by using the EGL_WAYLAND_PLANE_WL
+    attribute.  The value of the attribute is the index of the plane,
+    as defined by the buffer format.  Writing to an EGLImage created
+    from a wl_buffer in any way (such as glTexImage2D, binding the
+    EGLImage as a renderbuffer etc) will result in undefined behavior.
 
 Issues
 
@@ -90,3 +168,9 @@ Revision History
 
     Version 1, March 1, 2011
         Initial draft (Benjamin Franzke)
+    Version 2, July 5, 2012
+        Add EGL_WAYLAND_PLANE_WL attribute to allow creating an EGLImage
+        for different planes of planar buffer. (Kristian Høgsberg)
+    Version 3, July 10, 2012
+        Add eglQueryWaylandBufferWL and the various buffer
+        formats. (Kristian Høgsberg)