[PATCH wayland-protocols v2] linux-dmabuf: add immediate dmabuf import path

[Varad Gautam]

From: Varad Gautam <varad.gautam at collabora.com>

provide a mechanism that allows clients to import the added dmabufs
and immediately receive the newly created wl_buffer handle. this is
useful to clients that are sure of their import request succeeding,
and wish to avoid the wl_buffer communication roundtrip.

bump zwp_linux_dmabuf_v1, zwp_linux_buffer_params_v1 interface
versions.

v2: specify using incorrectly imported dmabufs as undefined behavior
instead of sending success/failure events. (pq, daniels)

Signed-off-by: Varad Gautam <varad.gautam at collabora.com>
---
 unstable/linux-dmabuf/linux-dmabuf-unstable-v1.xml | 39 ++++++++++++++++++----
 1 file changed, 33 insertions(+), 6 deletions(-)

diff --git a/unstable/linux-dmabuf/linux-dmabuf-unstable-v1.xml b/unstable/linux-dmabuf/linux-dmabuf-unstable-v1.xml
index 60240f9..22e7af9 100644
--- a/unstable/linux-dmabuf/linux-dmabuf-unstable-v1.xml
+++ b/unstable/linux-dmabuf/linux-dmabuf-unstable-v1.xml
@@ -26,13 +26,13 @@
     THIS SOFTWARE.
   </copyright>
 
-  <interface name="zwp_linux_dmabuf_v1" version="1">
+  <interface name="zwp_linux_dmabuf_v1" version="2">
     <description summary="factory for creating dmabuf-based wl_buffers">
       Following the interfaces from:
       https://www.khronos.org/registry/egl/extensions/EXT/EGL_EXT_image_dma_buf_import.txt
       and the Linux DRM sub-system's AddFb2 ioctl.
 
-      This interface offers a way to create generic dmabuf-based
+      This interface offers ways to create generic dmabuf-based
       wl_buffers. Immediately after a client binds to this interface,
       the set of supported formats is sent with 'format' events.
 
@@ -58,10 +58,15 @@
       To create a wl_buffer from one or more dmabufs, a client creates a
       zwp_linux_dmabuf_params_v1 object with a zwp_linux_dmabuf_v1.create_params
       request. All planes required by the intended format are added with
-      the 'add' request. Finally, a 'create' request is issued. The server
-      will reply with either a 'created' event which provides the final
+      the 'add' request. Finally, a 'create' or 'create_immed' request is
+      issued. Depending on the request, the server will:
+
+      - reply with either a 'created' event which provides the final
       wl_buffer or a 'failed' event saying that it cannot use the dmabufs
-      provided.
+      provided, in case of a 'create' request.
+
+      - return a newly created wl_buffer from the imported dmabufs, in case
+      of a 'create_immed' request.
 
       Warning! The protocol described in this file is experimental and
       backward incompatible changes may be made. Backward compatible changes
@@ -107,7 +112,7 @@
     </event>
   </interface>
 
-  <interface name="zwp_linux_buffer_params_v1" version="1">
+  <interface name="zwp_linux_buffer_params_v1" version="2">
     <description summary="parameters for creating a dmabuf-based wl_buffer">
       This temporary object is a collection of dmabufs and other
       parameters that together form a single logical buffer. The temporary
@@ -140,6 +145,8 @@
              summary="invalid width or height"/>
       <entry name="out_of_bounds" value="6"
              summary="offset + stride * height goes out of dmabuf bounds"/>
+      <entry name="invalid_wl_buffer" value="7"
+             summary="invalid wl_buffer resulted from importing given buffer_params"/>
     </enum>
 
     <request name="destroy" type="destructor">
@@ -271,6 +278,26 @@
         zlinux_buffer_params object.
       </description>
     </event>
+
+    <request name="create_immed" since="2">
+      <description summary="create and return a wl_buffer from the given dmabufs">
+        This asks for immediate creation of a wl_buffer from the added dmabufs
+        and returns the newly created wl_buffer. The result of using a
+        wl_buffer handle returned by this request is undefined in the case
+        when the server fails to import the supplied dmabufs, and the server
+        may raise an optional fatal invalid_wl_buffer error.
+
+        This takes the same arguments as a 'create' request, and obeys the
+        same restrictions.
+      </description>
+      <arg name="buffer_id" type="new_id" interface="wl_buffer"
+           summary="id for the newly created wl_buffer"/>
+      <arg name="width" type="int" summary="base plane width in pixels"/>
+      <arg name="height" type="int" summary="base plane height in pixels"/>
+      <arg name="format" type="uint" summary="DRM_FORMAT code"/>
+      <arg name="flags" type="uint" summary="see enum flags"/>
+    </request>
+
   </interface>
 
 </protocol>
-- 
2.6.2