# Sauna

Sauna turns the Bigscreen Beyond into a self-tracked wearable spatial display — head-tracked,
no lighthouses, ideally no SteamVR — without changing the hardware. This glossary fixes the
language so plans, code, and docs say the same thing. It is a glossary only: no implementation
details, no decisions (those live in `docs/adr/`).

## Language

### The product

**Sauna**:
This project. The host-side system that makes a Beyond track its own orientation and display
content as a spatial display. Named after the predecessor's `libsurvive-sauna` lineage.

**Spatial display**:
The thing Sauna delivers: head-tracked imagery presented in the headset so content appears fixed
in space (or head-locked by choice) rather than as a flat 2D framebuffer. The deliverable mode of use.
_Avoid_: "VR mode" (implies a full runtime/game platform we are not committing to), "AR".

**3DOF / 6DOF**:
Degrees of freedom of head tracking. **3DOF** = orientation only (yaw/pitch/roll), no position —
Sauna's committed target. **6DOF** = orientation + position — a stretch goal, currently without a
no-hardware path (the only cameras face inward).

**Virtual screen**:
The v1 deliverable experience: a 2D content surface (desktop, window, or video) presented by the
**compositor** so it appears as a screen floating fixed in space, head-tracked in **3DOF**. The v1
embodiment of **spatial display**. Multiple virtual screens may coexist (one per captured
display), arranged **curved** or **flat**.
_Avoid_: "virtual monitor" — confusable with **monitor mode**, which is about how the OS enumerates
the panels, not what the wearer sees.

**Curved / flat arrangement**:
The two multi-screen layouts. **Curved** (the default): screens sit on a cylinder around the
wearer's head at the set distance, each facing the wearer, adjacent edges touching, in OS
left-to-right order — every screen equidistant. **Flat**: all screens coplanar on one plane,
OS monitor coordinates reproduced faithfully (gaps included). The **anchor** is the screen
dead ahead in curved mode — the OS primary monitor.

**Streaming bridge**:
A stretch mode where the **compositor** presents frames rendered on another machine and streamed
over the network (à la Virtual Desktop on Quest), instead of locally rendered content.

### The hardware

**Beyond**:
The Bigscreen Beyond HMD. A tethered PC-VR microOLED headset. Comes in generations **BS1**, **BS2**,
**BS2E** (E = with eye tracking), distinguished by HMD-serial prefix.
_Avoid_: "the HMD" when the generation matters.

**Tundra**:
The Tundra TL448K6D "Watchman" system-in-package inside the Beyond — Valve's lighthouse tracking
module. For Sauna it matters as the home of the **IMU** and the per-unit **calibration** flash, not
as a lighthouse receiver. Enumerates as a Valve USB device, separate from the **MCU**.
_Avoid_: "the tracker", "Watchman" (use Tundra), "the SiP".

**MCU**:
The ATSAMG55G19 microcontroller on the display board — the Beyond's housekeeping brain. Owns the
Bigscreen control interface (display, brightness, EDID, persistence, proximity, LEDs, fan).
Distinct from the **Tundra**.

**Prox**:
The proximity sensor stream from the **MCU** that says whether the headset is on a head.
**Don** = put the headset on; **doff** = take it off; **worn** = the averaged prox reading says
on-head. The don is Sauna's canonical wake signal (see **asleep**). Every supported unit has a
prox sensor.
_Avoid_: "presence sensor", "wear detection" — say prox / worn / don / doff.

**Emission gating**:
The **MCU** firmware holding the OLEDs dark while the **prox** says away, even with a fully
healthy video link (scanout + vsync alive, host presenting normally). Distinct from the doff-kill,
where a worn→away *transition* takes the video signal and vsync down. Consequence: at an unworn
cold start there is no vsync symptom for "user sees nothing" — the ground truth is the telemetry
**DISPLAYS_ON** bit, not free-run detection. Bench rigs can disable gating with the firmware debug
command `'p'` (restore `'['`; persists until restored or power-cycled — `McuProx::setProxBypass`).
See docs/photon-latency-bench.md.

**DISPLAYS_ON**:
Bit 0 of the MCU telemetry display-status word (bytes 24-25, `video_get_display_status`): panels
are actually emitting. Camera-validated to within one video frame. Host accessor
`McuProx::displaysOn()`. The instrument for "are there photons", as opposed to "is the host
presenting" (which can be true for seconds before photons exist).

**VXR7200**:
The DisplayPort-to-MIPI bridge chip that drives the panels from the incoming video. Configured by
the **MCU**; boots autonomously from its own flash.
_Flagged ambiguity_: vendor naming. The `beyond_synaptics` repo and its Synaptics-generated firmware
blobs say Synaptics; one sibling doc said Analogix. **Resolution: call the part "VXR7200"**; treat
vendor as unconfirmed until a datasheet says otherwise.

**Linkbox**:
The inline box between PC DisplayPort and the headset's USB-C cable. Converts/relays the video link.
"Linkbox-less" is the stretch goal of removing it from the chain.

**IMU**:
The gyroscope + accelerometer stream originating in the **Tundra**. The raw sensor source for 3DOF.
Whether a magnetometer is present is unconfirmed (see _yaw drift_).

### Display modes

**Monitor mode**:
The Beyond enumerating to the OS as an ordinary desktop monitor (an EDID policy, not a hardware
change). The umbrella term for using the panels without a VR runtime.

**Extended mode** vs **Direct mode**:
Two ways the OS can drive the panels in **monitor mode**. **Extended mode** = the Beyond is a normal
extended desktop at 3840×1920. **Direct mode** = a VR-style exclusive surface at native 5088×2544,
bypassing the desktop. Keep these distinct; they are not synonyms for **monitor mode**.

**Persistence**:
The fraction of each frame the panels are lit (duty cycle). Low persistence reduces motion blur and
limits OLED burn-in; controlled over the Bigscreen interface.

### Optics / correction

**Distortion correction**:
The pre-warp applied to rendered images so the lenses present a rectilinear view. In SteamVR this is
the driver's `ComputeDistortion`; Sauna must reproduce it if SteamVR is bypassed.
_Avoid_: "warp mesh" as a synonym — that's one *implementation* of distortion correction, not the concept.

**Calibration**:
The per-unit optical + tracking data measured at the factory and stored in **Tundra** flash:
distortion polynomials, eye-to-head canting, IPD, IMU bias/scale. Read once per headset.
_Avoid_: "config" (overloaded), "profile".

**Yaw drift**:
The unbounded heading error of a **3DOF** orientation estimate that lacks an absolute reference
(no magnetometer / no optical fix). The defining accuracy problem of 3DOF; addressed by recenter UX
or a heading source.

### Runtime

**Overlay cursor / in-image cursor**:
Two ways a mouse cursor reaches a **virtual screen**. The **overlay cursor** is composited by
Sauna's capture onto the captured frame (position from the OS at composite time). An **in-image
cursor** is one Windows already drew into the desktop image (software-cursor states: accessibility
pointer customization, some HDR/remote situations) — Sauna cannot remove it, only avoid doubling
it (`cursor_overlay` knob). Remote-control software (Parsec) adds a third, client-side cursor that
is not in the capture at all — name which cursor is meant when reporting bugs.

**Compositor**:
Sauna's host-side render core: takes content frames plus the head pose, renders the per-eye
views from the per-unit **calibration** (eye-to-head canting, IPD), applies **distortion
correction**, and presents stereo imagery to the panels. Unqualified "compositor" means Sauna's
own; say "SteamVR compositor" (or "DWM") when meaning someone else's.

**SteamVR-free**:
Operating with no SteamVR runtime in the loop. Distinct from **lighthouse-free** (no base stations).
Sauna is committed to lighthouse-free; SteamVR-free is a goal, not yet a commitment. Independent of
**SteamVR coexistence**, which is committed.
_Avoid_: conflating "no SteamVR" with "no lighthouses" — they are independent.

**SteamVR coexistence**:
Sauna and SteamVR sharing one machine and one Beyond without fighting: Sauna **releases** the
headset the moment SteamVR starts and **reclaims** it after SteamVR exits (prox-gated — see
ADR 0002). "Release/reclaim" refer to the whole display acquisition; **asleep** refers only to
panel power. A release is not sleep and sleep is not a release.

**Photon latency**:
The time from software feeding video (first Present) to the panels actually emitting
(**DISPLAYS_ON** + camera). On a cold DirectMode bringup: 3.1-4.8 s, dominated by firmware/VXR
video-mode detect + DSC settle, not the host stack. If scanout is already running and only
**emission gating** holds the panels dark, prox-don lights them in ~50 ms. Measured by
`panel_bench` + the camera rig (docs/photon-latency-bench.md).
_Avoid_: "wake latency" without saying which path — gated-emission wake (~50 ms) and full
re-acquire wake (3-5 s) differ by two orders of magnitude.

**Asleep**:
The user-facing umbrella for "headset idle, tracking alive, not showing content." Has two depths
that differ in wake speed and idle cost — **doze** and **parked**. "Asleep" the word does not say
which depth; name the depth when it matters.
**Wake** is prox-don by default; head-motion wake exists behind a flag (see ADR 0003).
_Avoid_: "standby", "screensaver"; calling a SteamVR **release** "asleep".

**Doze / dozing**:
The shallow sleep depth: the video pipeline stays warm (scanout alive, `video_enabled` true,
VXR locked) but emission is swept off, the fan idles, and the LED breathes — so the headset
*looks and sounds* asleep while waking near-instantly (the **emission gating** path, not a
re-acquire). The firmware owns the doze choreography behind a `display-sleep` / `display-wake`
HID command pair (`'H'` / `'h'`); the host keeps the link warm by presenting black. Costs idle
power (link + VXR + scanout stay up) — the trade against instant wake.
Implemented + validated on hardware (beyond_synaptics ≥ 0.4.x, ADR 0005): wake is **~95 ms to
display-on, ~400 ms to full brightness** (measured) — the link/DSC never de-locks, so the wake
skips the retrain bounce entirely. The brightness sweep is gamma-eased so the fade/wake look
perceptually even. See docs/photon-latency-bench.md.
_Avoid_: calling doze "off" — the panels are driven, just dark.

**Parked**:
The deep sleep depth: panels off, content capture paused, **and** the video pipeline torn down
(host `POWER_OFF` → `video_enabled` false → VXR de-locks, fan off, OLED reset). Minimum footprint,
but wake pays the full cold-bringup **photon latency** — **~4-6 s, measured** (the DSC/link retrain
bounce dominates; same cost as a cold start because `POWER_OFF` de-locks the link). Entered when
minimum power matters more than instant wake. "Parked" is the code/console word.
_Avoid_: using "parked" for **doze** — they differ by ~50× in wake time (~95 ms vs ~4-6 s).

## Flagged ambiguities

- **VXR7200 vendor** — Synaptics vs Analogix. Use the part number; vendor unconfirmed.
- **"Extended mode"** — means the desktop-extension display mode here; do not let it drift into meaning
  "the whole monitor-mode feature." Use **monitor mode** for the umbrella.
- **"SteamVR" vs "lighthouses"** — independent. State which one is meant.