doc.go RawHistoryFolder

1// Package neferclient is a Wayland client toolkit library for Go: connection,
2// outputs, surface roles, seat and DMA-BUF presentation. It does not render
3// and holds no application policy.
4//
5// # Rebuilding after a dmabuf feedback change
6//
7// The compositor may change its linux-dmabuf preference at any time (another
8// main device or format table, for example when a surface moves to a GPU on
9// another output). Every complete round calls [Handler.FeedbackDone], also when
10// nothing changed. A renderer built from the first feedback must then be
11// rebuilt from the new one. On the owner goroutine:
12//
13//  1. Keep a [Feedback.Clone] of the feedback each renderer was built from. In
14//     FeedbackDone, return when [Feedback.Equal] says the preference is the
15//     one in use.
16//  2. Stop watching the renderer's descriptors, call [Surface.DestroyImports]
17//     (a frame may be pending: that is allowed), then close the old renderer.
18//  3. Build the new renderer from [Surface.Feedback] and import its buffers and
19//     timelines on demand, as for the first one. Ids may be reused.
20//  4. Present again when [Handler.Frame] reports the pending frame; Present
21//     refuses until then, with the old renderer or the new one.
22//
23// Destroying the wl_buffer and timeline objects never withdraws a commit the
24// compositor already holds, and the duplicated descriptors are owned by the
25// requests, so rebuilding cannot touch a destroyed object or close a
26// descriptor twice. The compositor holds its own references to the DMA-BUFs
27// and timelines it received, so closing the old renderer at once is safe; what
28// the explicit-sync rule forbids is writing to or recycling storage before its
29// release point signals.
30package neferclient