[PATCH wayland v3] protocol: try to clarify frame callback semantics
pekka.paalanen at collabora.co.uk
Tue Mar 11 06:53:13 PDT 2014
On Mon, 24 Feb 2014 10:00:33 +0200
Pekka Paalanen <ppaalanen at gmail.com> wrote:
> From: Pekka Paalanen <pekka.paalanen at collabora.co.uk>
> "the callback event will arrive after the next output refresh" is wrong,
> if you interpret "output refresh" as framebuffer flip or the moment when
> the new pixels turn into light the first time. Weston has probably never
> worked this way.
> Weston triggers the frame callbacks when it submits repainting commands
> to the GPU, which is before the framebuffer flip.
> Strike the incorrect claim, and the rest of the paragraph which no
> longer offers useful information.
> As a replacement, expand on the "throttling and driving animations"
> characteristic. The main purpose is to let clients animate at the
> display refresh rate, while avoiding drawing frames that will never be
> The new claim is that the server should give some time between
> triggering frame callbacks and repainting itself, for clients to draw
> and commit. This is somewhat intimate with the repaint scheduling
> algorithm a compositor uses, but hopefully the right intention.
> Another point of this update is to imply, that frame callbacks should
> not be used to count compositor repaint cycles nor monitor refresh
> cycles. It has never been guaranteed to work. Removing the mention of
> frame callback without an attach hopefully discourages such use.
> v2: Don't just remove a paragraph, but add useful information about the
> request's intent.
> v3: Specify the order of posting frame callbacks.
> Signed-off-by: Pekka Paalanen <pekka.paalanen at collabora.co.uk>
> Cc: Axel Davy <axel.davy at ens.fr>
> Cc: Jason Ekstrand <jason at jlekstrand.net>
> protocol/wayland.xml | 29 ++++++++++++++++++++---------
> 1 file changed, 20 insertions(+), 9 deletions(-)
> diff --git a/protocol/wayland.xml b/protocol/wayland.xml
> index e1edbe5..3aa89af 100644
> --- a/protocol/wayland.xml
> +++ b/protocol/wayland.xml
> @@ -1059,22 +1059,33 @@
> <request name="frame">
> - <description summary="request repaint feedback">
> - Request notification when the next frame is displayed. Useful
> - for throttling redrawing operations, and driving animations.
> + <description summary="request a frame throttling hint">
> + Request a notification when it is a good time start drawing a new
> + frame, by creating a frame callback. This is useful for throttling
> + redrawing operations, and driving animations.
> + When a client is animating on a wl_surface, it can use the 'frame'
> + request to get notified when it is a good time to draw and commit the
> + next frame of animation. If the client commits an update earlier than
> + that, it is likely that some updates will not make it to the display,
> + and the client is wasting resources by drawing too often.
> The frame request will take effect on the next wl_surface.commit.
> The notification will only be posted for one frame unless
> - requested again.
> + requested again. For a wl_surface, the notifications are posted in
> + the order the frame requests were committed.
> + The server must send the notifications so that a client
> + will not send excessive updates, while still allowing
> + the highest possible update rate for clients that wait for the reply
> + before drawing again. The server should give some time for the client
> + to draw and commit after sending the frame callback events to let them
> + hit the next output refresh.
> A server should avoid signalling the frame callbacks if the
> surface is not visible in any way, e.g. the surface is off-screen,
> or completely obscured by other opaque surfaces.
> - A client can request a frame callback even without an attach,
> - damage, or any other state changes. wl_surface.commit triggers a
> - display update, so the callback event will arrive after the next
> - output refresh where the surface is visible.
> The object returned by this request will be destroyed by the
> compositor after the callback is fired and as such the client must not
> attempt to use it after that point.
More information about the wayland-devel