Frame synchronisation

[Pekka Paalanen]

On Sat, 3 Feb 2018 21:52:54 +0100
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?

When you have both of:
- something actually new to draw, and
- the Wayland server has signalled that it has processed your previous
  frame (usually this is when the callback from wl_surface.frame is
  called).

If you draw more often than you get wl_surface.frame callbacks, then
quite likely some of your drawn frames will end up never showing on the
screen as they get superseded by a later frame. However, it is not an
error to draw at arbitary times. The frame callback is just for
throttling.

> If frame callback is the only sensible way,
> when should I fetch it and attach a listener?

You must send wl_surface.frame request before the wl_surface.commit
request that finalizes your frame submission. It is not fetching, the
request creates a new wl_callback object, and you should set up the
listener for it before returning to your event loop.

> What does that actually do?

The wl_surface.frame request creates a new object of type wl_callback,
which will deliver an event when the server is sure to use the
associated frame (buffer) you committed.

> Do I really have to do it after every draw cycle?

Yes. The wl_callback object is single-shot.

> Is there any way to
> ensure the frame will not change between wl_surface_frame() and
> wl_callback_add_listener() calls?

What do you mean by "change"? No, I cannot imagine any way of "change"
that might happen.

> Right now it seems to simply not work at all, no matter what I try. Is it
> even supported anymore?

Yes, it is still the way.

Mind, you have to have a visible wl_surface before you can get a frame
callback. IOW, you must do your very first buffer attach and commit on
your own initiative.

> The most up-to-date Wayland documentation is a
> tutorial from 2014.
> 
> 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.

The event handler functions you set up into listeners will be called
from inside a libwayland-client dispatching function, e.g.
wl_display_dispatch_pending(). There is no threading. When your event
loop calls any of the wl_display_dispatch*() functions, these will call
your handler functions as appropriate.

You have complete control over the time and context where your handler
functions may be called: it is when and where you call an event
dispatching function of libwayland-client. There are no limitations or
restrictions other that what you create yourself, except you should not
attempt to dispatch from inside a dispatch call.

wl_display_roundtrip() will dispatch events as well, because part of
its implementation is to call a wl_display_dispatch*() function.

IOW, everything goes as long as you don't, for instance, call
wl_display_roundtrip() from within an even handler function.

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

Have you seen https://wayland.freedesktop.org/ ?
You found the mailing list and there is an official IRC channel.

The documentation indeed is spotty. It can be improved by sending
patches: the website has its own git repository, and main documentation
lives in the wayland repository.


Thanks,
pq
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 833 bytes
Desc: OpenPGP digital signature
URL: <https://lists.freedesktop.org/archives/wayland-devel/attachments/20180205/b3b992a9/attachment.sig>