[wayland-protocols] 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.

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

diff --git a/unstable/linux-dmabuf/linux-dmabuf-unstable-v1.xml b/unstable/linux-dmabuf/linux-dmabuf-unstable-v1.xml
index 3b4861f..a0aa42e 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,16 @@
       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.
+
+      - reply with either a 'created_immed' event or a 'failed_immed' event to
+      notify successful wl_buffer creation, in case of a 'create_immed'
+      request. The created wl_buffer is returned to the client by the request.
 
       Warning! The protocol described in this file is experimental and
       backward incompatible changes may be made. Backward compatible changes
@@ -106,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
@@ -255,6 +261,25 @@
       <arg name="flags" type="uint" summary="see enum flags"/>
     </request>
 
+    <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 added dmabufs and
+        returns the newly created wl_buffer. On successful creation, a
+        'created_immed' event is triggered that can be used to verify that the
+        wl_buffer received from this request is a valid handle. A 'failed_immed'
+        event notifies unsuccessful dmabuf import.
+
+        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>
+
     <event name="created">
       <description summary="buffer creation succeeded">
         This event indicates that the attempted buffer creation was
@@ -277,6 +302,27 @@
         zlinux_buffer_params object.
       </description>
     </event>
+
+    <event name="created_immed" since="2">
+      <description summary="immediate buffer creation succeeded">
+        This event notifies the success of 'create_immed' request.
+
+        Upon receiving this event, the client should destroy the
+        zlinux_dmabuf_params object.
+      </description>
+    </event>
+
+    <event name="failed_immed" since="2">
+      <description summary="immediate buffer creation failed">
+        This event indicates that the attempted immediate buffer creation has
+        failed. It usually means that one of the dmabuf constraints has not
+        been fulfilled.
+
+        Upon receiving this event, the client should destroy the
+        zlinux_buffer_params object.
+      </description>
+    </event>
+
   </interface>
 
 </protocol>
-- 
2.6.2