[PATCH wayland] protocol: strike the note of frame callback triggering time

[Pekka Paalanen]

On Tue, 18 Feb 2014 16:43:15 +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.
> 
> "wl_surface.commit triggers a display update" is ambiguous and does not
> give useful information when the incorrect claim is removed, so it is
> removed also.
> 
> After these removals, leaving a single sentence "A client can request a
> frame callback even without an attach..." is obvious and uninformative:
> nothing forbids doing this, so it is implicitly allowed. Furthermore, if
> there is no damage nor a new buffer for the surface, it is not obvious
> when the frame callback should trigger.
> 
> "The next compositor repaint" is meaningless to a client, if the client
> did not submit damage. The above paragraph in the spec says compositors
> can choose to delay frame callbacks if full-speed animation is not
> needed. Therefore the frame callbacks do not always tell the very next
> compositor repaint, and even less the next output refresh (in the
> scanout hardware sense).
> 
> Do not specify anything about this until a clear definition of the frame
> callback is agreed on.
> 
> Signed-off-by: Pekka Paalanen <pekka.paalanen at collabora.co.uk>
> 
> ---
> 
> Hi,
> 
> this is continuation to
> http://lists.freedesktop.org/archives/wayland-devel/2014-February/013310.html
> and call to agree on what does the frame callback actually mean.
> 
> The current situation is that Weston triggers frame callbacks when it
> repaints, which is before the new image hits the screen. This sort of
> implies that "the client's content update is now definitely going to the
> screen", which we further interpret as "this is a good time to start
> drawing the next frame".
> 
> All the three definitions have been fairly equivalent up till now.
> Queueing changes this, and to decide proper semantics for frame
> callbacks in the presence of queueing, we need a clear definition of
> what the frame callback really means.
> 
> The definition should answer questions like can clients count scanout
> cycles with frame callbacks, and what does a frame+commit without attach
> do.
> 
> I suppose we already agree, that the frame callback can be used by EGL
> to implement swap_interval = 1. That is an easy case, as eglSwapBuffers
> always posts new content.
> 
> "Request notification when the next frame is displayed." is far too
> ambiguous, and even suggests the incorrect claim that this patch
> removes.
> 
> Thanks,
> pq
> ---
>  protocol/wayland.xml | 5 -----
>  1 file changed, 5 deletions(-)
> 
> diff --git a/protocol/wayland.xml b/protocol/wayland.xml
> index e1edbe5..fd51587 100644
> --- a/protocol/wayland.xml
> +++ b/protocol/wayland.xml
> @@ -1070,11 +1070,6 @@
>  	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.


On Tue, 18 Feb 2014 18:34:24 +0100
Axel Davy <axel.davy at ens.fr> wrote:

> I've seen you proposed the change:
> 
> -	A client can request a frame callback even without an attach,
> -	damage, or any other state changes. wl_surface.commit triggers
> -	display update, so the callback event will arrive after the next
> -	output refresh where the surface is visible.
> -
> 
> Why not replace that by:
> 
> A client can request a frame callback even without an attach,
> damage, or any other state changes. The frequency at which the frame
> callbacks are called by the compositor is not defined,
> but the client can expect it to be similar to the refresh rate if the 
> surface is focused and visible on the screen.

I see a few problems with that. What does "focused" mean? "Similar to
refresh rate" is so vague that at least you cannot implement EGL
swap_interval > 1 with it, IMO, if that is your intention. With the
added "if", it doesn't really specify anything. Most importantly, I
don't see this clarifying what the frame callback means, or how it
should be used. This is just a vague statement of the underlying
mechanism, not the request's intent.

I also do not understand how that would clarify how it interacts with
queued commits?

I believe the key is "Useful for throttling redrawing operations, and
driving animations." like it says in the spec. Maybe we should simply
expand on that:

	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 fast. Compositors must send the
	replies to frame callbacks so that the client will not do
	useless work while animating, while still allowing the highest
	possible update rate for clients that wait for the reply
	before drawing again.

Would this sound better?

This concentrates on the throttling aspect, but does not claim that you
could actually use this reliably to count scanout cycles on any output.

But it's also indifferent to queueing, which I guess is natural,
because when you queue, you are not using the frame callbacks to drive
an animation. It doesn't answer to any questions I am seeking answers
for, other than clarifying the "used for driving animations" case.

When I think about "throttling redrawing operations", it could make
sense to queue the frame callbacks. I intend to write a demo app, that
queues a bunch of frames in a burst, and then sleeps for a long time,
just to get woken up by the compositor just in time to send the next
burst. The animation should keep running without jerks. There are two
ways to do that: have a frame callback queued on the last commit in a
burst, or have presentation.feedback on the second last commit in a
burst. Either one could trigger the next burst.

But when I think that more, the client probably needs the feedback in
any case, so it won't have any use for the queued frame callback. Maybe
you are right and there is no use for queueing frame callbacks. :-)


Thanks,
pq