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

[Simon Ser]

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>
---

Changes from RFC to v1:
- Added get_default_hints for clients that don't support per-surface hints
- Added preference tranches for formats and modifiers
- Made all hints optional for e.g. nested compositors that don't know the DRM
  device they're rendering with
- Clarified that clients can ignore hints

 .../linux-dmabuf/linux-dmabuf-unstable-v1.xml | 99 ++++++++++++++++++-
 1 file changed, 97 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..2751d37 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,79 @@
       <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.
+      </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