From 94ef7579304298563312ca167aa57be795d1ec65 Mon Sep 17 00:00:00 2001
From: Simon Ser <contact@emersion.fr>
Date: Thu, 14 Apr 2022 10:17:22 +0200
Subject: [PATCH] protocol: introduce wl_surface.configure

This event atomically applies a group of events configuring a
surface.

For instance, if a surface jumps from one wl_output to another, the
compositor will send the following sequence:

- wl_surface.leave(wl_output@1)
- wl_surface.enter(wl_output@2)
- wl_surface.configure()

The client can use the configure event to avoid painting intermediate
frames based on partially outdated state.

Signed-off-by: Simon Ser <contact@emersion.fr>
---
 protocol/wayland.xml | 33 +++++++++++++++++++++++++++++++--
 1 file changed, 31 insertions(+), 2 deletions(-)

diff --git a/protocol/wayland.xml b/protocol/wayland.xml
index 1da3db9d..187bac11 100644
--- a/protocol/wayland.xml
+++ b/protocol/wayland.xml
@@ -187,7 +187,7 @@
     </event>
   </interface>
 
-  <interface name="wl_compositor" version="5">
+  <interface name="wl_compositor" version="6">
     <description summary="the compositor singleton">
       A compositor.  This object is a singleton global.  The
       compositor is in charge of combining the contents of multiple
@@ -1352,7 +1352,7 @@
     </event>
   </interface>
 
-  <interface name="wl_surface" version="5">
+  <interface name="wl_surface" version="6">
     <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
@@ -1635,6 +1635,9 @@
 	output.
 
 	Note that a surface may be overlapping with zero or more outputs.
+
+	This event is a part of a wl_surface configuration sequence, see
+	wl_surface.configure.
       </description>
       <arg name="output" type="object" interface="wl_output" summary="output entered by the surface"/>
     </event>
@@ -1650,6 +1653,9 @@
 	has been sent, and the compositor might expect new surface content
 	updates even if no enter event has been sent. The frame event should be
 	used instead.
+
+	This event is a part of a wl_surface configuration sequence, see
+	wl_surface.configure.
       </description>
       <arg name="output" type="object" interface="wl_output" summary="output left by the surface"/>
     </event>
@@ -1786,6 +1792,26 @@
       <arg name="x" type="int" summary="surface-local x coordinate"/>
       <arg name="y" type="int" summary="surface-local y coordinate"/>
     </request>
+
+    <!-- Version 6 additions -->
+
+    <event name="configure" since="6">
+      <description summary="end of a surface configuration sequence">
+	The configure event marks the end of a wl_surface configuration
+	sequence. A wl_surface configuration sequence is a set of zero or more
+	events configuring the state of the surface. A wl_surface configuration
+	sequence is started by any event (of any interface) specified to be a
+	part of a wl_surface configuration sequence, and includes any other
+	events specified similarly until the end of the sequence. Clients should
+	wait to receive the whole sequence before they start applying changes to
+	their surfaces.
+
+	Any event that is specified to be a part of wl_surface configuration
+	sequence guarantees that a wl_surface.configure event will follow after
+	all state events for the same sequence have been sent, provided that the
+	negotiated wl_surface interface version is 6 or greater.
+      </description>
+    </event>
    </interface>
 
   <interface name="wl_seat" version="8">
@@ -2921,6 +2947,9 @@
       wl_surface state is applied, regardless of the sub-surface's mode.
       As the exception, set_sync and set_desync are effective immediately.
 
+      Compositors must always send a wl_surface.configure event on the parent
+      after sending a wl_surface.configure event on the sub-surface.
+
       The main surface can be thought to be always in desynchronized mode,
       since it does not have a parent in the sub-surfaces sense.