A footgun in the wlr_buffer API is that there's no difference
between acquiring a buffer and increasing the lock count. In other
words, transitioning a buffer from the released state to the
acquired state is not explicit. This may result in hard-to-debug
failures if there is a dangling released wlr_buffer somewhere
(e.g. wlr_client_buffer.source [1]) and some piece of code calls
wlr_buffer_lock(). In that case, the buffer will be acquired and
released again. In the context of a wlr_buffer issued from a
Wayland protocol wl_buffer object, this can cause the underlying
memory to be used after wl_buffer.release has been sent to the
client, and a double wl_buffer.release event to be sent.
Make it so acquiring a buffer is an explicit operation to make sure
the caller means the state transition and is prepared for a new
release event. wlr_buffer_acquire() forbids calls on already-acquired
buffers, and wlr_buffer_lock() now forbids calls on released buffers.
[1]: https://gitlab.freedesktop.org/wlroots/wlroots/-/merge_requests/4904
We've had this struct for a while. It'd be useful for compositors
if they want to manage the swap chains themselves instead of being
forced to use wlr_output's. Some compositors might also want to use
a swapchain without an output.
The swapchain maximum capacity is set to 4, so that we have enough room
for:
- A buffer currently displayed on screen
- A buffer queued for display (e.g. to KMS)
- A pending buffer that'll be queued next commit
- An additional pending buffer in case we want to invalidate the
currently pending one
