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

[Pekka Paalanen]

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