[PATCH wayland v3] protocol: try to clarify frame callback semantics

[Pekka Paalanen]

Ping?

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
> presented.
> 
> 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>
>  
>      <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.