[PATCH wayland v2] protocol: try to clarify frame callback semantics

Sun Feb 23 10:56:52 PST 2014

On Feb 23, 2014 1:50 AM, "Pekka Paalanen" <ppaalanen at gmail.com> wrote:
>
> On Fri, 21 Feb 2014 21:38:15 -0600
> Jason Ekstrand <jason at jlekstrand.net> wrote:
>
> > Pekka,
> > Sorry this e-mail took so long to send.  Not much time lately.  The
first
> > time or two I read this suggested re-wording I didn't like it, but now
it's
> > starting to grow on me.  I still kind of like the idea of "the buffer
you
> > sent is now in use, go ahead and send the next one" but I don't know
that
> > it's that much better or that it actually changes anything.
>
> Hi,
>
> there is a slight difference. If the semantics were written as "the
> update you sent is now applied" which is the same as the buffer
> getting into use, just in different words, then that implies that
> we should be queueing also frame callbacks when an update is queued.

Yes, it does change that a bit.

> I still do not know if it is better to queue frame callbacks or
> not, but my current code does not queue them and it avoids the
> corner case of what to do with the callbacks when a queued update
> gets discarded.

Let's go with that for now.  We can always add frame callback queueing if
someone decides it's useful, but we can never take it away once it hits
libwayland.  Also, it's not clear what interaction other extensions may
have with the frame callback and we don't want to make it more complicated
for them if we don't have to.

--Jason Ekstrand

> Thanks,
> pq
>
> > The big thing I'd like to leave open (and I think your change does) is
the
> > following:  Suppose a client commits a buffer and then, several seconds
> > later (after the attached buffer was first used), the user does
something
> > that causes the client to refresh.  If it does a frame+commit without an
> > attach, the server should be able to respond immediately without waiting
> > for another pageflip.  This way the client may be able to render in time
> > for the next flip.  Sure, the client might be too slow and miss the
flip,
> > but that's really no worse than waiting before sending the frame
callback.
> >
> > Point is, it should be a compositor decision and I think you made that
> > clear enough.
> >
> > Looks good to me.
> > --Jason Ekstrand
> >
> > Reviewed-by: Jason Ekstrand <jason at jlekstrand.net>
> >
> > On Fri, Feb 21, 2014 at 7:46 AM, 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, 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
> > > presented.
> > >
> > > 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.
> > >
> > > Signed-off-by: Pekka Paalanen <pekka.paalanen at collabora.co.uk>
> > > Cc: Axel Davy <axel.davy at ens.fr>
> > > Cc: Jason Ekstrand <jason at jlekstrand.net>
> > > ---
> > >  protocol/wayland.xml | 26 ++++++++++++++++++--------
> > >  1 file changed, 18 insertions(+), 8 deletions(-)
> > >
> > > diff --git a/protocol/wayland.xml b/protocol/wayland.xml
> > > index e1edbe5..6e370ad 100644
> > > --- a/protocol/wayland.xml
> > > +++ b/protocol/wayland.xml
> > > @@ -1059,22 +1059,32 @@
> > >      </request>
> > >
> > >      <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.
> > >
> > > +       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.
> > > --
> > > 1.8.3.2
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.freedesktop.org/archives/wayland-devel/attachments/20140223/75e0c8d3/attachment.html>