Commit 2c319d34 authored by Pekka Paalanen's avatar Pekka Paalanen Committed by Kristian Høgsberg
Browse files

protocol: try to clarify frame callback semantics

"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's avatarPekka Paalanen <>
Cc: Axel Davy <>
Cc: Jason Ekstrand <>
parent 9cfffffe
......@@ -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.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment