[PATCH] protocol: Add a request to disable queuing of buffer release events

[Neil Roberts]

Adds a request called wl_surface.set_release which provides a way for
a client to explicitly disable the queuing mechanism for buffer
release events so that it can get them as soon as the buffer is no
longer being used. This is useful for example when doing
eglSwapInterval(0) because in that case the client is not likely to be
installing a frame complete callback so nothing will cause the event
queue to be flushed. However the EGL driver is likely to be using a
finite number of buffers and it may be blocking until a release event
is received. Without this request the driver may end up blocking
forever.

There was some discussion for this patch on whether the request should
be on the wl_buffer interface rather than wl_surface. However it would
be difficult for the compositor to use if it was on the wl_buffer
interface because the implementation for that is in Mesa and
wayland-shm. That means that we would have to have some extra EGL API
to query the release mode in order for the compositor to see it.
---
 protocol/wayland.xml | 51 ++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 48 insertions(+), 3 deletions(-)

diff --git a/protocol/wayland.xml b/protocol/wayland.xml
index a1df007..77d098a 100644
--- a/protocol/wayland.xml
+++ b/protocol/wayland.xml
@@ -173,7 +173,7 @@
     </event>
   </interface>
 
-  <interface name="wl_compositor" version="3">
+  <interface name="wl_compositor" version="4">
     <description summary="the compositor singleton">
       A compositor.  This object is a singleton global.  The
       compositor is in charge of combining the contents of multiple
@@ -959,7 +959,7 @@
     </event>
   </interface>
 
-  <interface name="wl_surface" version="3">
+  <interface name="wl_surface" version="4">
     <description summary="an onscreen surface">
       A surface is a rectangular area that is displayed on the screen.
       It has a location, size and pixel contents.
@@ -1233,7 +1233,52 @@
       </description>
       <arg name="scale" type="int"/>
     </request>
-   </interface>
+
+    <!-- Version 4 additions -->
+
+    <enum name="release" since="4">
+      <description summary="options for when to send a buffer release event">
+        These values are used for the wl_surface.set_release request to
+        specify when to send buffer release events.
+        WL_SURFACE_RELEASE_IMMEDIATE means the release event will be
+        sent as soon as the buffer is no longer used by the
+        compositor. WL_SURFACE_RELEASE_DELAYED means that the
+        compositor may choose to put the release event into a queue
+        and only flush it once some other events are ready to send as
+        well. Typically a client will want the latter because it
+        doesn't usually need to know about the release events until it
+        is about to render something so it can avoid being woken up
+        unnecessarily. The default value is WL_SURFACE_RELEASE_DELAYED.
+      </description>
+      <entry name="delayed" value="0"/>
+      <entry name="immediate" value="1"/>
+    </enum>
+
+    <request name="set_release" since="4">
+      <description summary="sets whether the release event for the buffer being attached will be delayed">
+        By default the compositor will typically delay sending release
+        events for a buffer until some other event is also being sent
+        in order to avoid waking up the clients more often than
+        necessary. Usually the buffer release will end up being sent
+        along with the frame complete callback. However some clients
+        will want to be able to reuse the buffers earlier than that
+        for example if they are not using the frame complete callback.
+        This can be used to give a hint to the compositor that the
+        client wants the release event for the given buffer as soon as
+        possible.
+
+        The release mode is double-buffered state, see
+        wl_surface.commit.
+
+        The default value is WL_SURFACE_RELEASE_DELAYED meaning that
+        the release events will be delayed. Setting the value to
+        WL_SURFACE_RELEASE_IMMEDIATE only effects the buffer currently
+        being attached and subsequent attaches will continue to default
+        to WL_SURFACE_RELEASE_DELAYED.
+      </description>
+      <arg name="value" type="uint" summary="The new value"/>
+    </request>
+  </interface>
 
   <interface name="wl_seat" version="3">
     <description summary="group of input devices">
-- 
1.8.3.1