From b60b57c4071c393d01bcf61c612686fc89d20fb0 Mon Sep 17 00:00:00 2001 From: Julian Orth Date: Sun, 26 Oct 2025 00:26:36 +0200 Subject: [PATCH] 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 --- protocol/wayland.xml | 26 ++++++++++++++++++++++++-- 1 file changed, 24 insertions(+), 2 deletions(-) diff --git a/protocol/wayland.xml b/protocol/wayland.xml index bee74a1..37895dd 100644 --- a/protocol/wayland.xml +++ b/protocol/wayland.xml @@ -190,7 +190,7 @@ - + A compositor. This object is a singleton global. The compositor is in charge of combining the contents of multiple @@ -1395,7 +1395,7 @@ - + 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 @@ + + + + + + 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. + +