From 0c32d70d30a4a4bfc1b1f919df4101b9fe9a2a2d Mon Sep 17 00:00:00 2001
From: Simon Ser <contact@emersion.fr>
Date: Wed, 12 May 2021 16:27:14 +0200
Subject: [PATCH] protocol: introduce wl_surface.get_release

This new request allows clients to get per-surface-commit buffer
release events. It supersedes wl_buffer.release.

This functionality is also available via the linux-explicit-synchronization
protocol, but requires the compositor to also support Linux
synchronization fences. Adding this new request to the core protocol
allows any compositor to implement the functionality.

Signed-off-by: Simon Ser <contact@emersion.fr>
Closes: https://gitlab.freedesktop.org/wayland/wayland/-/issues/203
References: https://gitlab.freedesktop.org/wayland/wayland/-/issues/46
---
 protocol/wayland.xml | 36 ++++++++++++++++++++++++++++++++----
 1 file changed, 32 insertions(+), 4 deletions(-)

diff --git a/protocol/wayland.xml b/protocol/wayland.xml
index 5c2a8030..7e52cb4b 100644
--- a/protocol/wayland.xml
+++ b/protocol/wayland.xml
@@ -190,7 +190,7 @@
     </event>
   </interface>
 
-  <interface name="wl_compositor" version="6">
+  <interface name="wl_compositor" version="7">
     <description summary="the compositor singleton">
       A compositor.  This object is a singleton global.  The
       compositor is in charge of combining the contents of multiple
@@ -1380,7 +1380,7 @@
     </event>
   </interface>
 
-  <interface name="wl_surface" version="6">
+  <interface name="wl_surface" version="7">
     <description summary="an onscreen surface">
       A surface is a rectangular area that may be displayed on zero
       or more outputs, and shown any number of times at the compositor's
@@ -1436,6 +1436,7 @@
       <entry name="invalid_offset" value="3" summary="buffer offset is invalid"/>
       <entry name="defunct_role_object" value="4"
 	     summary="surface was destroyed before its role object"/>
+      <entry name="no_attach" value="5" summary="missing attach request"/>
     </enum>
 
     <request name="destroy" type="destructor">
@@ -1490,8 +1491,9 @@
 	If a pending wl_buffer has been committed to more than one wl_surface,
 	the delivery of wl_buffer.release events becomes undefined. A well
 	behaved client should not rely on wl_buffer.release events in this
-	case. Alternatively, a client could create multiple wl_buffer objects
-	from the same backing storage or use wp_linux_buffer_release.
+	case. Instead, clients hitting this case should use
+	wl_surface.get_release (if unavailable, a fallback can be implemented
+	by creating multiple wl_buffer objects from the same backing storage).
 
 	Destroying the wl_buffer after wl_buffer.release does not change
 	the surface contents. Destroying the wl_buffer before wl_buffer.release
@@ -1852,6 +1854,32 @@
       <arg name="transform" type="uint" enum="wl_output.transform"
 	   summary="preferred transform"/>
     </event>
+
+    <!-- Version 7 additions -->
+
+    <request name="get_release" since="7">
+      <description summary="get a release callback">
+	Create a callback for the release of the buffer attached by the client
+	with wl_surface.attach.
+
+	The compositor will release the buffer when it has finished its usage of
+	the underlying storage for the relevant commit. Once the client receives
+	this event, and assuming the associated buffer is not pending release
+	from other wl_surface.commit requests, the client can safely re-use the
+	buffer.
+
+	Release callbacks are double-buffered state, and will be associated
+	with the pending buffer at wl_surface.commit time.
+
+	The callback_data passed in the wl_callback.done event is unused and
+	is always zero.
+
+	Sending this request without a wl_surface.attach request in the same
+	commit is a protocol error. The compositor will send the no_attach error
+	in this case.
+      </description>
+      <arg name="callback" type="new_id" interface="wl_callback" summary="callback object for the release"/>
+    </request>
    </interface>
 
   <interface name="wl_seat" version="9">