76 lines
4.3 KiB
Markdown
76 lines
4.3 KiB
Markdown
# Architecture
|
|
|
|
```
|
|
┌──────────────────────────────────────────┐
|
|
│ hyprland-headless.service │
|
|
│ Hyprland 0.56.2, no physical monitor │
|
|
│ private XDG_RUNTIME_DIR, as `user` │
|
|
│ outputs come from `outputs[]` │
|
|
└───────────────┬──────────────────────────┘
|
|
│ Wayland session
|
|
▼
|
|
┌──────────────────────────────────────────┐
|
|
│ hyprland-headless-stream.service │
|
|
│ hhstream-server │
|
|
│ capture ──▶ one "latest frame" slot │
|
|
│ accept ──▶ a thread per client │
|
|
└───────────────┬──────────────────────────┘
|
|
│ AF_UNIX, mode 0660
|
|
▼
|
|
many clients ── hhstream-client / any socket reader
|
|
```
|
|
|
|
Three pieces, deliberately separate:
|
|
|
|
1. **The compositor** (`Hyprland`, unchanged upstream) renders into virtual
|
|
outputs. It knows nothing about frames on a socket.
|
|
2. **The frame server** (`hhstream`) captures, holds exactly one frame, and
|
|
publishes it. It owns the socket, the framing and the drop policy.
|
|
3. **The client** is any process that can open a Unix socket and read the
|
|
contract's byte format. The shipped `hhstream-client` is a convenience, not a
|
|
requirement.
|
|
|
|
## Why one frame, not a queue
|
|
|
|
The server keeps a single slot holding the most recent frame. Each client thread
|
|
sends whatever is in that slot when it is ready. A client that cannot keep up
|
|
therefore misses frames instead of forcing the server to buffer them: memory use
|
|
does not grow with the number of stalled clients, and a stalled client cannot
|
|
delay the others. See `docs/CONTRACT.md` for exactly what a client observes.
|
|
|
|
## Capture
|
|
|
|
Capturing is a separate program (by default `grim`, a wlr-screencopy client) run
|
|
inside the compositor's session and pointed at stdout. That choice is what keeps
|
|
`hhstream` free of Wayland and GPU code — the awkward part lives in a tool that
|
|
already exists and is already tested — and it is why the capture command is a
|
|
module option: tests inject a fake, and a future backend (a native screencopy
|
|
client, a hardware encoder) is a command-line swap rather than a rewrite.
|
|
|
|
## The hardware requirement, stated plainly
|
|
|
|
`Hyprland` 0.56.2 asks aquamarine for its **headless backend as mandatory**
|
|
(`src/Compositor.cpp`) and does not accept the DRM backend if it is
|
|
unavailable. Aquamarine's headless backend still needs an EGL/GBM **render
|
|
node**; there is no software-only path that works without one. Consequently a
|
|
host with no graphics device at all (`/dev/dri` missing) cannot run this, and
|
|
Pyprland fails with `CBackend::create() failed!` before any of its managers come
|
|
up.
|
|
|
|
So the requirements are:
|
|
|
|
- a render node, i.e. `/dev/dri/renderD*` — from a real GPU, a virtual GPU
|
|
(`virtio-gpu`, `virtio-gpu-gl`, QXL) or a NixOS test VM's own QEMU display;
|
|
- the `video`/`render` groups for whichever user runs it (the module sets them).
|
|
|
|
## Testing, and what each layer proves
|
|
|
|
| Layer | Proves |
|
|
|---|---|
|
|
| `tests/unit` | the framing, the capture wrapper and the server's client handling, with no compositor and no GPU |
|
|
| `checks.vm-basic` | the module actually starts both units, the socket appears with the right owner/mode, the Hello parses and two frames arrive — with a fake capture program |
|
|
| `checks.vm-hyprland` | the real thing: headless Hyprland comes up in the VM and `grim` captures a frame of the configured size |
|
|
|
|
`vm-hyprland` is the only check that can fail for reasons outside this repo, so
|
|
it is kept separate from `vm-basic` on purpose: when it fails, the compositor's
|
|
log is the answer and the other two layers are already known good. |