1package ports
2
3import (
4 "errors"
5 "fmt"
6 "image"
7 "os"
8 "time"
9)
10
11// MaxCaptureInflight bounds the capture requests admitted but not yet
12// answered, across outputs. The reply channel of the production app has
13// at least this capacity, so an output never blocks on a reply.
14const MaxCaptureInflight = 32
15
16// ErrCaptureTransient marks a capture failure that may clear on its own (the
17// renderer busy, the indicator or an exclusion not shown yet): a protocol
18// frame tries again shortly instead of failing. Test with errors.Is.
19var ErrCaptureTransient = errors.New("capture: transient")
20
21// ErrCaptureBusy: every capture slot of the renderer is leased.
22var ErrCaptureBusy = fmt.Errorf("%w: no free slot", ErrCaptureTransient)
23
24// CaptureFrame is a lease on one renderer readback slot holding a GPU
25// copy of a rendered frame. Done and Read make no Vulkan call: a worker
26// goroutine waits on Done, then reads. EndCapture returns the lease.
27type CaptureFrame interface {
28 // Done is the sync file signalled when the copy finished; nil means it
29 // had finished when BeginCapture returned. The frame owns it: it stays
30 // valid until EndCapture, and the reader must not close it.
31 Done() *os.File
32 // Read copies region (output pixels) as opaque sRGB8 BGRA rows into
33 // dst, stride bytes per row. Valid after Done signalled and before
34 // EndCapture.
35 Read(region image.Rectangle, dst []byte, stride int) error
36}
37
38// Renderer draws scenes for an output. One goroutine owns it. Frames go
39// to its own image until ExportTargets gives it scanout images; then each
40// Render draws into the target chosen by UseTarget (ADR 014: no CPU pass).
41type Renderer interface {
42 // SetHDR selects the HDR10 output transform (0 disables it).
43 // The DRM output calls this before ExportTargets.
44 SetHDR(sdrNits float64)
45 // Render draws the scene. done is a sync file signalled when the GPU
46 // finished the frame (nil: already finished); the caller closes it.
47 Render(Scene, map[WindowID]SurfaceContent) (done *os.File, err error)
48 // ExportTargets allocates n images of the renderer's size that the
49 // display can scan out, with one of the given XRGB8888 (SDR) or
50 // XRGB2101010 (HDR) modifiers (none: any the device exports),
51 // and returns them as dmabufs; a modifier may have several memory
52 // planes (DCC metadata), each plane owning its file. singlePlane
53 // restricts the choice to one-plane modifiers.
54 // n = 0 drops the targets.
55 ExportTargets(n int, modifiers []uint64, singlePlane bool) ([]DMABuf, error)
56 // UseTarget selects the exported image the next Render draws into.
57 UseTarget(i int)
58 // CursorBuffers allocates two linear ARGB8888 images of size×size the
59 // display can show on its cursor plane, and returns them as dmabufs.
60 CursorBuffers(size int) ([2]DMABuf, error)
61 // WriteCursor fills cursor image i with premultiplied ARGB8888 pixels
62 // (w×h, w*4 per row), cropped to the image and cleared around it.
63 WriteCursor(i int, pixels []byte, w, h int) error
64 // Pixels reads the last frame back (headless screenshots, tests). It
65 // waits for the GPU: debug only. Nil when it cannot (every capture
66 // slot leased, or the copy failed).
67 Pixels() *image.RGBA
68 // HDRPixels reads the last HDR frame's XRGB2101010 target back, each
69 // 10-bit code scaled to 16 bits (c<<6 | c>>4), A = 0xffff. It waits for
70 // the GPU: debug only. Nil when the output is SDR, the target is not
71 // readable, a slot is busy or the copy failed.
72 HDRPixels() *image.RGBA64
73 // BeginCapture submits a GPU copy of the last rendered frame into a
74 // free slot and returns without waiting. ErrCaptureBusy when every
75 // slot is leased; another error when the copy cannot be tracked (no
76 // sync file): the caller fails the request.
77 BeginCapture() (CaptureFrame, error)
78 // EndCapture returns a lease. It never waits: a slot whose copy may
79 // still run is reused only once the renderer sees it finished.
80 EndCapture(CaptureFrame)
81 // Trim frees client buffer caches left undrawn for a while and what
82 // finished frames held, without rendering. Outputs call it
83 // periodically: an idle output renders no frame to free them.
84 Trim(now time.Time) error
85 // TakeRedrawn returns the target pixels drawn since the last call
86 // (damage-limited frames count their damage only) and starts over.
87 TakeRedrawn() int
88 Close()
89}
90
91// Seat is the device broker (libseat) input devices are opened through.
92type Seat interface {
93 OpenDevice(path string) (int, error)
94 CloseDevice(fd int)
95 SwitchVT(vt int)
96}