protocol: add wl_surface.discard_constraints request

This commit defines a new discard_constraints request. This request is
intended to be used by clients that use the wp-fifo and wp-commit-timing
protocols for frame pacing but want to be able to respond immediately to
resize requests.

Consider a client using wp-fifo presenting to a display with refresh
rate 1 (unitless). The client has allocated 3 buffers O1, O2, and O3.
The client receives a resize request at time T+2. The client allocates
new buffers N1, N2, and N3 with the new size.

The following sequence of requests and events can be observed in
WAYLAND_DEBUG output:

    T+0: release(O1)
    T+0: -> attach(O1)
    T+1: release(O2)
    T+1: -> attach(O2)
    T+2: release(O3)
    T+2: -> attach(O3)
    T+2: resize request
    T+2: -> attach(N1)
    T+2: -> attach(N2)
    T+2: -> attach(N3)
    T+3: release(O1)
    T+4: release(O2)
    T+5: release(O3)
    T+6: release(N1)
    T+6: -> attach(N1)

Due to the lack of backpressure, all newly created buffers are attached
immediately at T+2. Since O1, O2, and O3 are still equeued, the content
update containing N1 will only be applied at T+5 and therefore cannot be
released any earlier than T+6, creating a presentation bubble between
T+3 and T+6.

Furthermore, even if the client did not attach N2 immediately at T+2, N1
would not become visible until T+5, which means that the client
effectively does not respond to the resize request until T+5.

This effect can be observed with the following command:

    vkcube --present_mode 2

Resizing the application window causes easily visible stutters on
displays with low refresh rates.

Note that the queue can grow unbounded if the client receives an
unbounded number of resize requests between refresh cycles.

To remedy this, this commit allows the client to hint to the compositor
that it should discard all existing constraints, if able. Since
compositor architectures might impose limitations on which constraints
the compositor is able to discard, this is left to compositor policy. It
is expected that most compositors should be able to discard wp-fifo and
wp-commit-timing constraints. Some compositors might be able to discard
buffer constraints if the buffer in question is superseded by another
buffer in a later content update.

I had considered creating per-interface requests, such as
wp_fifo_v1.discard_constraints, however, such constraints are often
created by WSI layers and an update of the WSI layer could introduce new
constraints that the client would not be aware of. To discard all
constraints, the WSI layer would have to invoke these requests and there
are no APIs for the client to communicate to the WSI layer which
behavior is desired.

Signed-off-by: Julian Orth <ju.orth@gmail.com>

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
@@ -1395,7 +1395,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
@@ -1884,6 +1884,28 @@
       <arg name="transform" type="uint" enum="wl_output.transform"
 	   summary="preferred transform"/>
     </event>
+
+    <!-- Version 7 additions -->
+
+    <request name="discard_constraints" since="7">
+      <description summary="hint that existing constraints should be discarded">
+	This request hints to the compositor that the constraints of content
+	updates (CUs) that are currently enqueued in the surface queue should be
+	discarded. See the description of wl_surface.commit for the definition
+	of CUs and per-surface queues.
+
+	This hint is double-buffered state, see wl_surface.commit. It applies to
+	all CUs that are enqueued at the time of the wl_surface.commit request
+	and to their dependencies, excluding the CU created by the
+	wl_surface.commit request itself.
+
+	Clients may use this request to hint that they prioritize the
+	application of the following CUs over previously committed pacing and
+	timing constraints.
+
+	It is compositor policy which constraints are discarded.
+      </description>
+    </request>
    </interface>
 
   <interface name="wl_seat" version="10">