Best practices for client side buffer management

Carsten Haitzler (The Rasterman) raster at
Fri Jun 19 10:21:34 UTC 2020

On Fri, 19 Jun 2020 13:24:12 +1000 Brad Robinson <brobinson at>

> Hi All,
> I'm fairly new to Wayland and Linux GUI programming in general, but doing
> some experiments to figure out how to integrate it into my custom UI
> toolkit library and have a couple of questions about client side buffer
> management.
> Firstly, this is how I'm allocating the backing memory for client side
> buffer pools.  This is C# p-invoking to libc, and basically it's using
> mkstemp() to get a temp file, ftruncate() to set its length, mmap() to map
> it and then unlink() once mapped so temp files aren't left behind.  Any
> issues with this approach?
>             // Get temp file
>             var sb = new
> StringBuilder(System.IO.Path.Join(System.IO.Path.GetTempPath(),
> "mmXXXXXX"));
>             int fd = mkstemp(sb);
>             ftruncate(fd, (ulong)capacity);

i assume GetTempPath() will be looking at /tmp ... and /tmp may not be a
ramdisk. it may be a real disk... in which case your buffers may be getting
written to an actual disk. don't use /tmp.

you might wan to to loop at shm_open or memfd or libdrm for specific drivr
allocation calls like drm_intel_bo_alloc_tiled, drm_intel_bo_map/unmap etc. the
latter libdrm ones wo9uld allow your buffers to possibly be scanned out
directly to the screen or used as textures directly without copies, but will
need careful handling, so do this only as an advanced step.

>             // Map it
>             var addr = mmap(IntPtr.Zero, (ulong)capacity, Prot.Read |
> Prot.Write, Map.Shared, fd, 0);
>             // Unlink it (so temp files not left behind)
>             unlink(sb.ToString());
> Secondly I'm wondering about practical strategies for managing client side
> buffers.  The toolkit in question basically needs arbitrarily sized buffers
> to render whatever size the window happens to be.  Seems like to use a
> buffer pool for this would require some sort of heap manager to manage
> what's in each pool.  I'm wondering if there's any recommendations or best
> practices for how to deal with this.  eg: create one big pool and
> explicitly manage what's in there as a heap, use lots of little pools with
> one buffer in each, a combination of both, something else?

resizes of windows are less common (in general) than rendering to them. here
i'd go for a scheme of N buffers in a ring per window. so you have buffers A,
B, C and you first render to A then display it, then next frame B, then C, then
A, then B, then C. You could get away without C. as the buffers retain their
state you can take advantage of this and only partially render part of a
buffer for updates "since 1 or 2 frames ago" (depending if you do double or
triple buffering). as its predictable ABCABCABC you can just keep a "Sliding
window of the update regions of the past N frames" and merge those into the
"current amount to update" but always store per-frame update rectangle regions
before this merge-at-render-time. 3 buffers allows you to be rendering a 3rd
buffer while 1 buffer is queued to be displayed and one is still being
displayed. if you find you need a 4th buffer, perhaps just overdraw the 3rd on
you just did and "update it" ... or just block or don't update yet as you are
getting too far ahead of the compositor.

> Finally, the toolkit already maintains an off-screen buffer with the
> window's current contents rendered into it.  I'll probably replace that
> with a Wayland buffer, but wondering about partial updates.  eg: if the
> client only needs to redraw a part of the window what's the correct process
> to update just that part with Wayland.  Can I just update the existing
> buffer and prompt Wayland to just redraw that part?

no. never do that. always have more than 1 and update a buffer that is not
being displayed or queued to be displayed. the above sliding window allows your
partial rendering to work as you can depend on previous content still being
there where you left it from N frames ago.

> Any advice appreciated...
> Brad

------------- Codito, ergo sum - "I code, therefore I am" --------------
Carsten Haitzler - raster at

More information about the wayland-devel mailing list