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

Varad Gautam varadgautam at gmail.com
Fri Nov 11 11:40:44 UTC 2016

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

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 @@
-  <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:
       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 @@
-  <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 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.
+    <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>

More information about the wayland-devel mailing list