Best practices for client side buffer management

Pekka Paalanen ppaalanen at
Wed Jun 24 14:44:23 UTC 2020

On Wed, 24 Jun 2020 23:45:56 +1000
Brad Robinson <brobinson at> wrote:

> Hi Pekka,
> > The problem is, the compositor might not release the buffer until
> > you have already submitted a new one.
> >  
> OK... good to know that approach won't work.
> I guess what I'm trying to figure out (and probably won't solve completely
> till I actually sit down and code it) is how to avoid the software
> rendering part of it as much as possible.  My app can have a complex and
> deep tree of UI elements so I think it's worth trying to avoid additional
> render calls into that tree as much as possible - or at least clip it down
> to just the dirty rectangles.  But this requires the rest of the current
> buffer be kept up to date.  Presumably if there's a cycle of buffers being
> used this would mean either re-rendering certain UI  elements multiple
> times, or copying dirty rectangles from previously rendered frame buffers
> to the one about to be updated.

Hi Brad,

if you limit your render call rate to wl_surface.frame callbacks, then
that should be quite optimal. IOW, don't render when your scene state
changes. Render when you want to submit an update to display.

Your damage regions can be arbitrary, right? Not just one or few
rectangles? Arbitrary regions can be unioned before doing the one
render call for the whole frame. E.g. Weston uses Pixman library for
region computations, the same library that Xorg uses.

Since the Wayland client is in full control of buffer management (while
it should also honour the compositor's reading), you can guarantee that
the buffers keep their old contents the way you want it. In
steady-state, a client will usually be flipping between two buffers, or
re-using a single buffer if the compositor allows. You should be able
to reach a very good content re-use percentage even by rendering the UI
tree straight into Wayland buffers.

You can choose whether you copy the "historical" damage from the latest
buffer or just render it from the UI tree. You would have to go way out
of your way to manage creating buffers where the copying would hurt

> I'm not sure if this is a valid or even useful question but: once I've
> submitted a buffer to the compositor can I assume the previously submitted
> buffer will be returned imminently?

You can't assume that in the way that your program would freeze or
malfunction if the assumption is violated. There are various reasons
why a compositor might keep more than one buffer busy. Transiently it
can happen for reasons you should not care about, indefinitely it can
happen by client request (e.g. sub-surfaces in sync mode, no commit on
parent surface).

However, there are also reasonable expectations, like the maximum of 4
buffers you might need to allocate for one surface and allocating more
than that should not be necessary in practise. It's hard to imagine a
compositor scenario where it would keep all 4 buffers busy indefinitely.

> The rest of this discussion got a bit beyond me (although I will need to
> support OpenGL eventually).

Ok. When you do go with OpenGL, you will be using EGL. Make note of the
EGL extensions I linked to previously, they should help get the
equivalent buffer re-use going as talked about here. The thing about
EGL is that you will never see the wl_buffer objects, all buffer
management is hidden inside the Wayland-client-side EGL implementation.
That's why you need e.g. EXT_buffer_age extension if you mean to
efficiently re-use buffers.

Luckily, continuously allocating and destroying buffers is expensive,
so you can expect a reasonable EGL implementation to re-use existing
buffers on the EGLSurface allowing EXT_buffer_age to be useful.

There is a way to get a buffer out of EGL and then manually shovel it
through Wayland, but for a normal application I wouldn't recommend it.
It's a bunch of special code to write for no benefit.

> Thanks everyone for insights... much appreciated.

You're welcome. All this should really have been written in the Wayland
documentation, but there's always something else to do...

-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 833 bytes
Desc: OpenPGP digital signature
URL: <>

More information about the wayland-devel mailing list