From 039023104442ff2a8a1710fdf0e11b696b91d518 Mon Sep 17 00:00:00 2001
From: Kenny Levinsen <kl@kl.wtf>
Date: Thu, 17 Apr 2025 20:01:41 +0200
Subject: [PATCH] ext-image-copy-capture: Introduce preferred_done event

ext_image_copy_capture_session_v1 sends all supported buffer constraints
which the client combines with its own internal constraints to allocate
an appropriate buffer for use with capture frames. The buffer
constraints have no order.

The compositor should include a wide set of buffer constraints for
compatibility and to enable various use-cases. The client should work
with a wide set of buffer constraints to work in different environments.

When both compositor and client supports a wide set of buffer
constraints for compatibility and the client does not have a strong
preference of its own, a suboptimal or in some cases outright
nonsensical format may end up being selected simply because it was the
first result of an unordered intersection, which could negatively impact
performance or color resolution.

In this case, the client would benefit from including compositor
preference in the consideration. Compositor preference could for example
be the format of its current scanout or composition buffer.

Introduce proferred_done to delimit preferred buffer formats from
remaining compatible buffer formats.

Signed-off-by: Kenny Levinsen <kl@kl.wtf>
---
 .../ext-image-copy-capture-v1.xml             | 23 +++++++++++++++++--
 1 file changed, 21 insertions(+), 2 deletions(-)

diff --git a/staging/ext-image-copy-capture/ext-image-copy-capture-v1.xml b/staging/ext-image-copy-capture/ext-image-copy-capture-v1.xml
index 1ac4369..f372418 100644
--- a/staging/ext-image-copy-capture/ext-image-copy-capture-v1.xml
+++ b/staging/ext-image-copy-capture/ext-image-copy-capture-v1.xml
@@ -34,7 +34,7 @@
     only be done by creating a new major version of the extension.
   </description>
 
-  <interface name="ext_image_copy_capture_manager_v1" version="1">
+  <interface name="ext_image_copy_capture_manager_v1" version="2">
     <description summary="manager to inform clients and begin capturing">
       This object is a manager which offers requests to start capturing from a
       source.
@@ -83,7 +83,7 @@
     </request>
   </interface>
 
-  <interface name="ext_image_copy_capture_session_v1" version="1">
+  <interface name="ext_image_copy_capture_session_v1" version="2">
     <description summary="image copy capture session">
       This object represents an active image copy capture session.
 
@@ -197,6 +197,25 @@
         this object.
       </description>
     </request>
+
+    <!-- Version 2 additions -->
+
+    <event name="preferred_done" since="2">
+      <description summary="all preferred formats have been sent">
+        The event is sent once when all events for buffer formats that the
+        compositor would prefer were adhered to have been sent, and will be
+        followed by any remaining supported buffer formats.
+
+        A client should aim to adhere to preferred buffer formats when
+        possible, as these may be more efficient for the compositor and should
+        have sufficient color resolution for the captured content according to
+        compositor policy.
+
+        Preferred and remaining buffer formats may overlap. If a compositor
+        does not have any preferred formats, it should omit the preferred_done
+        event when sending buffer constraints.
+      </description>
+    </event>
   </interface>
 
   <interface name="ext_image_copy_capture_frame_v1" version="1">