X-Git-Url: https://git.libre-soc.org/?a=blobdiff_plain;f=docs%2FWL_bind_wayland_display.spec;h=02bd6ea21129341b3b89e497bef416cc993f915a;hb=7e14293556bf8b4248728d2952752c13f70647f3;hp=e2fde3c507b7c0e900c2648a164db3ee064c1c5c;hpb=fa31b1095eeea97695125ad5770239805bed37da;p=mesa.git

diff --git a/docs/WL_bind_wayland_display.spec b/docs/WL_bind_wayland_display.spec
index e2fde3c507b..02bd6ea2112 100644
--- a/docs/WL_bind_wayland_display.spec
+++ b/docs/WL_bind_wayland_display.spec
@@ -56,12 +56,27 @@ 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
+
+    Possible values for EGL_TEXTURE_FORMAT:
+
+        EGL_TEXTURE_Y_U_V_WL                    0x31D7
+        EGL_TEXTURE_Y_UV_WL                     0x31D8
+        EGL_TEXTURE_Y_XUXV_WL                   0x31D9
+
+
 Additions to the EGL 1.4 Specification:
 
     To bind a server side wl_display to an EGLDisplay, call
@@ -80,9 +95,67 @@ 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 texture format using
+    EGL_TEXTURE_FORMAT 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 of different types), 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_TEXTURE_RGB, EGL_TEXTURE_RGBA, EGL_TEXTURE_Y_U_V_WL,
+    EGL_TEXTURE_Y_UV_WL, EGL_TEXTURE_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_TEXTURE_RGB
+                One plane, samples RGB from the texture to rgb in the
+                shader.  Alpha channel is not valid.
+
+        EGL_TEXTURE_RGBA
+                One plane, samples RGBA from the texture to rgba in the
+                shader.
+
+    YUV buffer types:
+
+        EGL_TEXTURE_Y_U_V_WL
+                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_TEXTURE_Y_UV_WL
+                Two planes, samples Y from the first plane to r in
+                the shader, U and V from the second plane to rg.
+
+        EGL_TEXTURE_Y_XUXV_WL
+                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.
+
+    Further, eglQueryWaylandBufferWL accepts attributes EGL_WIDTH and
+    EGL_HEIGHT to query the width and height of the wl_buffer.
 
 Issues
 
@@ -90,3 +163,13 @@ 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)
+    Version 4, July 19, 2012
+        Use EGL_TEXTURE_FORMAT, EGL_TEXTURE_RGB, and EGL_TEXTURE_RGBA,
+        and just define the new YUV texture formats.  Add support for
+        EGL_WIDTH and EGL_HEIGHT in the query attributes (Kristian Høgsberg)