diff --git a/docs/OUTPUT-INTEGRATION.md b/docs/OUTPUT-INTEGRATION.md index bac610f..af02e9e 100644 --- a/docs/OUTPUT-INTEGRATION.md +++ b/docs/OUTPUT-INTEGRATION.md @@ -80,32 +80,66 @@ lamp per 25 ms** (~40/s). Practical consequences: ## The plasma display model -The plasma/VFD is a **112 × 32 pixel** text display on its own serial port -(so text updates never contend with the input link). Two glyph sizes exist: +The plasma is a **128 × 32 dot-matrix panel** on its own serial port at 9600 +8N1 (so display updates never contend with the input link). It is fully +dot-addressable: it has a text mode (cursor + fonts + attributes) **and a raw +bitmap mode** (`ESC P` graphics write — see +[Bitmap graphics](#bitmap-graphics-esc-p)). The command set is documented in +vRIO's `VPlasma.Core/Protocol/PlasmaProtocol.cs`, recovered from the Tesla +4.10 sources and the display firmware dump. + +Text mode has two glyph sizes: | Font | Cell | Fits per line | Auto-selected when | |---|---|---|---| -| large (font 5) | 10×14 px | ~11 chars | text ≤ 9 chars | -| small (font 2) | 5×7 px | ~22 chars | text 10–20 chars (longer is truncated to 20) | +| large (font 5) | 10×14 px | ~12 chars | text ≤ 9 chars | +| small (font 2) | 5×7 px | ~25 chars | text 10–20 chars (longer is truncated to 20) | What the endpoint exposes (v1): - **`plasma text `** — auto-fit: short text renders large, longer text small, centered on the display (the `PlasmaPosText` behavior the original - games used). This is the right default for callsigns, scores, and status - words. -- **`plasma text `** — explicit cursor position in **pixels** - (top-left origin). You choose the position; the font still auto-fits by - length. Use this to keep two fields on screen at once (e.g. callsign top - line, score bottom line: `plasma text 2 2 "VIPER 1-1"` + - `plasma text 2 18 "SCORE 4200"`). + games used; its pivot is x=56, faithfully a touch left of the true 128-px + center). This is the right default for callsigns, scores, and status words. +- **`plasma text `** — explicit cursor position in **pixels**, + top-left origin; the firmware accepts x 0–127, y 0–31. You choose the + position; the font still auto-fits by length. Use this to keep two fields on + screen at once (e.g. callsign top line, score bottom line: + `plasma text 2 2 "VIPER 1-1"` + `plasma text 2 18 "SCORE 4200"`). - **`plasma clear`** — blank the display. Text is **Latin-1** (one byte per char) — don't send UTF-8. -Not exposed through the endpoint yet (the underlying `PlasmaCommands` port has -them, so they're a small extension when needed): explicit font/attribute -selection and box draw/fill. +Not exposed through the endpoint yet (small extensions when needed): explicit +font/attribute selection, box draw/fill, and the bitmap mode below. + +### Bitmap graphics (`ESC P`) + +The display accepts **raw bitmap rows** — this is how the native Red Planet +game draws everything (it renders into a local 1-bpp buffer and streams the +*changed* rows). The wire command: + +``` +ESC P s y x w h data… +``` + +`s` = screen (single-screen hardware, ignored), `y` = top row (0–31), +`x` = left **byte column** (0–15), `w` = bytes per row, `h` = rows, followed +by `w×h` data bytes, **MSB = leftmost pixel**. The native game always sends +whole rows: `x=0, w=16, h=1` — 16 bytes covering one full 128-px row. + +Budget the bandwidth: a full-frame repaint is 32 rows × (7-byte header + +16 data bytes) ≈ 740 bytes ≈ **0.77 s** at 9600 baud. That's why the native +game diffs and streams only changed rows — an animation that touches a few +rows per tick is smooth; full-frame repaints are ~1 fps. Text mode is far +cheaper for text; reserve bitmaps for logos, custom gauges, and icons. + +Status: the hardware and the vPlasma emulator fully support `ESC P`, but +RIOJoy's `PlasmaCommands` port and the feedback endpoint don't expose it yet. +The natural extension is a line command (e.g. +`plasma row <32-hex-digit row>` or a base64 block form) — if an +integration needs it, that plus a `PlasmaCommands.GraphicsWrite` builder is a +small, self-contained addition. ### Update semantics