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

[Kristian Høgsberg]

On Tue, Mar 11, 2014 at 03:53:06PM +0200, Pekka Paalanen wrote:
> Ping?

Pong, thanks.  As we discussed, I agree with the changes here.
Patch committed.

Kristian

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