[PATCH wayland-protocols v2] unstable/linux-dmabuf: add wp_linux_dmabuf_hints

Tue Nov 20 21:20:52 UTC 2018

On multi-GPU setups, multiple devices can be used for rendering. Clients need
hints about the device in use by the compositor. For instance, if they render
on another GPU, then they need to make sure the memory is accessible between
devices and that their buffers are not placed in hidden memory.

This commit introduces a new wp_linux_dmabuf_hints object. This object
advertises a preferred device via a file descriptor and a set of preferred
formats/modifiers.

Each object is bound to a wl_surface and can dynamically update its hints. This
enables fine-grained per-surface optimizations. For instance, when a surface is
scanned out on a GPU the compositor isn't compositing with, the preferred
device can be set to this GPU to avoid unnecessary roundtrips.

A hint object can also be standalone for clients that don't support per-surface
hints.

Signed-off-by: Simon Ser <contact at emersion.fr>
---

This new version includes changes suggested by Philipp.

In the meantime, I also sent a very simple mesa patch as an RFC [1]. I also
have a wlroots patch [2]. These two have been tested and work well together.

Changes from v1 to v2:
- Explain that the primary device needs to be able to read buffers provided by
  the client.
- Suggest clients to use the primary device for rendering for power savings

[1]: https://lists.freedesktop.org/archives/mesa-dev/2018-November/209804.html
[2]: https://github.com/swaywm/wlroots/pull/1376

 .../linux-dmabuf/linux-dmabuf-unstable-v1.xml | 105 +++++++++++++++++-
 1 file changed, 103 insertions(+), 2 deletions(-)

diff --git a/unstable/linux-dmabuf/linux-dmabuf-unstable-v1.xml b/unstable/linux-dmabuf/linux-dmabuf-unstable-v1.xml
index 154afe2..b49520a 100644
--- a/unstable/linux-dmabuf/linux-dmabuf-unstable-v1.xml
+++ b/unstable/linux-dmabuf/linux-dmabuf-unstable-v1.xml
@@ -24,7 +24,7 @@
     DEALINGS IN THE SOFTWARE.
   </copyright>
 
-  <interface name="zwp_linux_dmabuf_v1" version="3">
+  <interface name="zwp_linux_dmabuf_v1" version="4">
     <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
@@ -35,6 +35,9 @@
       the set of supported formats and format modifiers is sent with
       'format' and 'modifier' events.
 
+      Clients can use the get_surface_hints request to get dmabuf hints for a
+      particular surface.
+
       The following are required from clients:
 
       - Clients must ensure that either all data in the dma-buf is
@@ -138,9 +141,29 @@
       <arg name="modifier_lo" type="uint"
            summary="low 32 bits of layout modifier"/>
     </event>
+
+    <request name="get_default_hints" since="4">
+      <description summary="get default hints">
+        This request creates a new wp_linux_dmabuf_hints object not bound
+        to a particular surface. This object will deliver hints about dmabuf
+        parameters to use if the client doesn't support per-surface hints
+        (see get_surface_hints).
+      </description>
+      <arg name="id" type="new_id" interface="zwp_linux_dmabuf_hints_v1"/>
+    </request>
+
+    <request name="get_surface_hints" since="4">
+      <description summary="get hints for a surface">
+        This request creates a new wp_linux_dmabuf_hints object for the
+        specified wl_surface. This object will deliver hints about dmabuf
+        parameters to use for buffers attached to this surface.
+      </description>
+      <arg name="id" type="new_id" interface="zwp_linux_dmabuf_hints_v1"/>
+      <arg name="surface" type="object" interface="wl_surface"/>
+    </request>
   </interface>
 
-  <interface name="zwp_linux_buffer_params_v1" version="3">
+  <interface name="zwp_linux_buffer_params_v1" version="4">
     <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
@@ -342,7 +365,85 @@
       <arg name="format" type="uint" summary="DRM_FORMAT code"/>
       <arg name="flags" type="uint" summary="see enum flags"/>
     </request>
+  </interface>
+
+  <interface name="zwp_linux_dmabuf_hints_v1" version="4">
+    <description summary="dmabuf hints">
+      This object advertises dmabuf parameters hints. Such hints include the
+      primary device and the formats/modifiers that are preferred.
+
+      These hints are sent once when this object is created and whenever they
+      change. The done event is always sent once after all hints have been sent.
+
+      All hints are optional. The compositor can send the done event without any
+      hint.
+
+      The client is allowed to ignore hints and pick a format/modifier
+      advertised as supported by the wp_linux_dmabuf interface.
+
+      The formats and modifiers are groupped by tranches of preference. For each
+      tranch, some modifier events are sent and then a tranch event finishes
+      the list. The tranches are sent in descending order of preference. All
+      formats and modifiers in the same tranch have the same preference.
+    </description>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy the hints object">
+        Using this request a client can tell the server that it is not going to
+        use the wp_linux_dmabuf_hints object anymore.
+      </description>
+    </request>
 
+    <event name="primary_device">
+      <description summary="preferred primary device">
+        This event advertises the primary device that the server prefers. There
+        is no more than one primary device.
+
+        Clients need to create buffers that the primary device can import and
+        sample a texture from (ideally directly), otherwise creating the dmabuf
+        wl_buffer will fail. The primary device will also likely be kept active
+        by the compositor, so clients can use it for rendering for power savings
+        instead of waking up another device.
+      </description>
+      <arg name="fd" type="fd" summary="device file descriptor"/>
+    </event>
+
+    <event name="modifier">
+      <description summary="preferred buffer format modifier">
+        This event advertises the formats that the server prefers, along with
+        the modifiers preferred for each format. The preferred formats must
+        have been advertised as supported formats by the wp_linux_dmabuf
+        interface.
+
+        These events are split in preference tranches by the tranch event.
+
+        For the definition of the format and modifier codes, see the
+        wp_linux_buffer_params::create request.
+      </description>
+      <arg name="format" type="uint" summary="DRM_FORMAT code"/>
+      <arg name="modifier_hi" type="uint"
+           summary="high 32 bits of layout modifier"/>
+      <arg name="modifier_lo" type="uint"
+           summary="low 32 bits of layout modifier"/>
+    </event>
+
+    <event name="tranch">
+      <description summary="preference tranch">
+        This event splits modifier events in preference tranches. It is sent
+        after a set of modifiers/formats and represents the end of a tranch. The
+        next tranch will have a lower preference.
+      </description>
+    </event>
+
+    <event name="done">
+      <description summary="all hints have been sent">
+        This event is sent after all properties of a wp_linux_dmabuf_hints
+        object have been sent.
+
+        This allows changes to the wp_linux_dmabuf_hints properties to be
+        seen as atomic, even if they happen via multiple events.
+      </description>
+    </event>
   </interface>
 
 </protocol>
-- 
2.19.1


