Frame synchronisation

[Daniel Stone]

Hi Andrzej,

On 3 February 2018 at 20:52, Andrzej Korwin-Mikke
<andrzej.kmikke at gmail.com> wrote:
> Greetings, there is virtually no documentation on frame synchronisation on
> the Internet, it's mentioned on four blogs with no explanation whatsoever.
> How do I know when to draw? If frame callback is the only sensible way, when
> should I fetch it and attach a listener? What does that actually do? Do I
> really have to do it after every draw cycle? Is there any way to ensure the
> frame will not change between wl_surface_frame() and
> wl_callback_add_listener() calls?

In short: yes, you have to do it after every draw cycle. Surface
frames are part of the commit cycle, e.g. you do:
wl_surface_attach(surface, next_buffer);
wl_surface_damage(surface, { 0, 0, width, height });
frame = wl_surface_frame(surface);
wl_callback_add_listener(frame, &frame_listener, frame_data);
wl_surface_commit(surface);

This will request that next_buffer is displayed on surface, and call
frame_listener when the compositor thinks you should begin drawing the
next frame.

I don't understand 'ensure the frame will not change'?

You can find much more detail here:
http://ppaalanen.blogspot.co.uk/2015/02/weston-repaint-scheduling.html

> Right now it seems to simply not work at all, no matter what I try. Is it
> even supported anymore? The most up-to-date Wayland documentation is a
> tutorial from 2014.

Yes, it's certainly supported. It's used by GTK+, Qt, EGL
implementations, GStreamer, etc etc. We'd know very quickly if it was
broken.

> And while we're at it, how are the listener methods actually executed? In a
> new thread using the address space of the program? I don't even know what
> can I and what can I not use when dealing with them.

No, not in a new thread. The callbacks are not invoked by the server
reaching across into Wayland's process space. They are invoked by the
client itself, at a time of its choosing.

Each Wayland object (e.g. wl_registry, wl_compositor, wl_surface,
wl_callback, and so on) can be on an event queue (cf. documentation
for wl_proxy_set_queue). When objects are created, by default they
inherit the event queue of their parent; there is a default event
queue for the display also.

The listener functions you set are called when you dispatch the event
queue the object is assigned to, using wl_display_dispatch_queue().
wl_display_dispatch() will dispatch the default event queue for the
display. Dispatching is also performed when you do a roundtrip with
wl_display_roundtrip_queue() on a particular queue, or
wl_display_roundtrip() on the default event queue.

There is some documentation on this here:
https://wayland.freedesktop.org/docs/html/apb.html#Client-classwl__display

> It simply baffles me how at the age of information there's virtually no
> up-to-date development documentation of the biggest advancement in Linux
> GUIs since the 80's. Could we at least set up a p2p information sharing
> medium less annoying than a mailing list? An official wiki, forum, even an
> IRC channel?

We know our documentation isn't great, and we're working on it. In the
meantime, we do have #wayland on Freenode.

Cheers,
Daniel