1// Package buffers models buffer ownership between the renderer and the
2// compositor without GPU dependencies. The caller serializes all events.
3package buffers
4
5import (
6 "errors"
7 "fmt"
8)
9
10var ErrNoBuffer = errors.New("no available buffer")
11var ErrTransition = errors.New("invalid buffer transition")
12
13type State string
14
15const (
16 Available State = "available"
17 Rendering State = "rendering"
18 Acquired State = "acquire_exported"
19 Committed State = "committed"
20 CompositorOwned State = "compositor_owned"
21 Released State = "release_point_signaled"
22)
23
24// Buffer is an immutable identity and mutable ownership record. On an explicit
25// sync surface wl_buffer.release is optional; only the latest release point of
26// this buffer's own timeline authorizes reuse.
27type Buffer struct {
28 ID, Generation uint64
29 State State
30 AcquirePoint, ReleasePoint uint64
31 WlReleased, PointSignaled bool
32}
33
34type Pool struct {
35 Generation uint64
36 NextPoint uint64
37 Buffers []*Buffer
38}
39
40func New(count int) (*Pool, error) {
41 if count < 1 {
42 return nil, fmt.Errorf("buffer count must be positive")
43 }
44 p := &Pool{Generation: 1}
45 for i := 0; i < count; i++ {
46 p.Buffers = append(p.Buffers, &Buffer{ID: uint64(i + 1), Generation: 1, State: Available})
47 }
48 return p, nil
49}
50
51// Begin skips rendering when every buffer is busy. Retired generations are
52// never selected, even if their release events complete later.
53func (p *Pool) Begin() (*Buffer, error) {
54 for _, b := range p.Buffers {
55 if b.Generation == p.Generation && b.State == Available {
56 b.State = Rendering
57 b.WlReleased, b.PointSignaled = false, false
58 return b, nil
59 }
60 }
61 return nil, ErrNoBuffer
62}
63
64func (p *Pool) Acquire(b *Buffer) (uint64, error) {
65 if !p.owns(b) || b.State != Rendering || b.Generation != p.Generation {
66 return 0, ErrTransition
67 }
68 p.NextPoint++
69 b.AcquirePoint = p.NextPoint
70 b.State = Acquired
71 return b.AcquirePoint, nil
72}
73
74func (p *Pool) Commit(b *Buffer) (uint64, error) {
75 if !p.owns(b) || b.State != Acquired || b.Generation != p.Generation {
76 return 0, ErrTransition
77 }
78 p.NextPoint++
79 b.ReleasePoint = p.NextPoint
80 b.PointSignaled = false
81 b.WlReleased = false
82 b.State = Committed
83 return b.ReleasePoint, nil
84}
85
86func (p *Pool) Own(b *Buffer) error {
87 if !p.owns(b) || b.State != Committed {
88 return ErrTransition
89 }
90 b.State = CompositorOwned
91 return nil
92}
93
94// Release records an optional wl_buffer.release event. It never authorizes
95// reuse, and a late event from a prior commit must not modify the new commit.
96func (p *Pool) Release(b *Buffer) error {
97 if !p.owns(b) {
98 return ErrTransition
99 }
100 if b.State == Committed || b.State == CompositorOwned {
101 b.WlReleased = true
102 }
103 return nil
104}
105
106func (p *Pool) Signal(b *Buffer, point uint64) error {
107 if !p.owns(b) || (b.State != Committed && b.State != CompositorOwned) || b.PointSignaled || point != b.ReleasePoint {
108 return ErrTransition
109 }
110 b.PointSignaled = true
111 b.State = Released
112 return nil
113}
114
115// Reuse requires the caller to have arranged a GPU wait on the exported
116// release-point sync_file before submitting new writes to this image.
117func (p *Pool) Reuse(b *Buffer, gpuWaitInstalled bool) error {
118 if !p.owns(b) || b.Generation != p.Generation || b.State != Released || !gpuWaitInstalled {
119 return ErrTransition
120 }
121 b.State = Available
122 return nil
123}
124
125// Resize installs an entirely new generation. Old images remain tracked until
126// their latest release point signals; even Available old images are retired.
127func (p *Pool) Resize(count int) error {
128 if count < 1 {
129 return fmt.Errorf("buffer count must be positive")
130 }
131 p.Generation++
132 var next uint64
133 for _, b := range p.Buffers {
134 if b.ID > next {
135 next = b.ID
136 }
137 }
138 for i := 0; i < count; i++ {
139 next++
140 p.Buffers = append(p.Buffers, &Buffer{ID: next, Generation: p.Generation, State: Available})
141 }
142 return nil
143}
144
145// Retirable reports when the compositor and GPU no longer own a retired image.
146// An abandoned Rendering or Acquired image still needs the caller to finish or
147// wait for its Vulkan submission before destroying the GPU allocation.
148func (p *Pool) Retirable(b *Buffer) bool {
149 return p.owns(b) && b.Generation < p.Generation && (b.State == Available || b.State == Released)
150}
151
152func (p *Pool) Remove(b *Buffer) error {
153 if !p.Retirable(b) {
154 return ErrTransition
155 }
156 for i, other := range p.Buffers {
157 if other == b {
158 p.Buffers = append(p.Buffers[:i], p.Buffers[i+1:]...)
159 return nil
160 }
161 }
162 return ErrTransition
163}
164
165func (p *Pool) owns(b *Buffer) bool {
166 if b == nil {
167 return false
168 }
169 for _, other := range p.Buffers {
170 if other == b {
171 return true
172 }
173 }
174 return false
175}