Skip to content

perf(ui): contrast table and per-pane base-layer cache - #75

Merged
bsommers merged 8 commits into
mainfrom
perf/render-caches
Nov 11, 2026
Merged

bsommers merged 8 commits into
mainfrom
perf/render-caches

Conversation

@bsommers

Copy link
Copy Markdown
Owner

What

Step 3b of the responsiveness work: make an unchanged pane cheap to draw.

  • Contrast table (src/ui/contrast.rs): a 256-entry sRGB linearisation table replaces per-cell powf. Asserted bit-identical for every channel value.
  • Base-layer cache (src/ui/canvas_layer.rs, src/ui/canvas_cache.rs): each pane's base layer (fill, VT cells, URL and trigger highlights, scanlines) is cached, keyed by VT generation, scrollback offset, grid size, canvas rect, theme, palette, font options, triggers and scanlines. The key destructures its inputs exhaustively, so a new input does not compile until it is keyed. A pane that changes every frame is painted directly and never stored.
  • Derived-data slot on VtParser (src/vt/derived.rs): the cache lives with the parser and dies with the pane.
  • BILTERM_RENDER_CACHE=on|off|verify. Verify paints both ways and panics on any difference; debug builds default to it.

Measurements

Release, 6 panes, 200x60, median of 200 (tests/perf_render_frame.rs, #[ignore]):

frame before after
idle 1233 µs 184 µs
idle + help overlay 1295 µs 256 µs
idle + 3 triggers 1580 µs 185 µs
one busy pane 1139 µs 422 µs

Verification

  • tests/render_cache_equivalence.rs: cache-on, cache-off and verify compared across about 25 workspace states (output, scroll, theme, triggers, scanlines, per-window colours, search, copy mode, hints, help, palette, quick terminal, stacked, zoom, resize).
  • Mutation check: removing the scrollback offset from the key fails 2 of 3 equivalence tests.
  • Local gate after merging main: 179 of 181 pass; the two failures are phase68_69_surface_parity and swarm_wiring, which fail on main and are fixed by ci: six-cell OS/arch matrix, coverage gate, VT fuzz test, fix two stale swarm tests #71. GOLDENS OK 11; no snapshot changes.
  • Independent read-only review traced every grid mutator to the cache key and found no staleness path.

Known gaps

  • Debug builds are slower by default because of verify (about 14.8 ms per idle frame; 1.9 ms with BILTERM_RENDER_CACHE=on). Release is unaffected.
  • Cache memory is bounded per pane (two layers, each at most 200k cells) but not globally.
  • The key relies on every visible grid mutation bumping generation or the scroll offset. A future mutator that skips the bump would show a stale pane.
  • Prompt, status bar, frames, shadows, glass, cursors and overlays are still redrawn every frame.
  • A pane being moved misses the cache each frame (same cost as before).
  • The ghostty-vt feature build was not compiled or tested.

🤖 Generated with Claude Code

bsommers and others added 8 commits November 10, 2026 06:38
Renders a 6-pane 200x60 headless workspace with coloured output and reports
median frame time plus a per-claim breakdown (contrast, URL/trigger scans,
config clone). No wall-clock assertions; run with --ignored --nocapture.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
rgb_luminance called powf three times per colour and the canvas calls it
several times per cell. A 256-entry table built at first use from the same
expression gives bit-identical results (asserted for every channel value).
Adds CellStyleKey, the cell attributes the canvas style depends on.

Measured (release, 6 panes 200x60, tests/perf_render_frame.rs): idle frame
1233 us -> 792 us.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
A type-erased, interior-mutable slot where the renderer parks data derived
from the grid, so it lives and dies with the parser. The parser never reads
it; readers key their data on generation() and their other inputs.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
An unchanged pane is no longer recomposed every frame. The base layer of the
OutputCanvas (fill, VT cells with contrast, URL and trigger highlights, CRT
scanlines) moves to ui/canvas_layer.rs as a pure function of the grid and an
explicit CanvasLayerInputs struct; ui/canvas_cache.rs stores it in the pane's
VtParser and replays it while the key matches (generation, scrollback offset,
grid size, canvas rect, theme, palette, font options, triggers, scanlines).
At most two layers per pane, none above 200k cells; a pane that changes every
frame is painted directly and never stored. Runs of equal cell attributes
reuse the previous style.

BILTERM_RENDER_CACHE=on|off|verify selects the mode. Debug builds default to
verify, which paints both ways and panics on any difference, so every existing
render test checks the cache. tests/render_cache_equivalence.rs compares
cache-on, cache-off and verify frames across workspace state changes.

Measured (release, 6 panes 200x60): idle frame 792 us -> 183 us (1233 us
before this series); one busy pane 1139 us -> 416 us. Snapshots and classic
goldens unchanged.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Debug builds default the render cache to Verify, which paints every canvas
twice and compares. The 100-frame budget loop therefore measured the
self-check, which pushed the instrumented coverage build past 16 ms and cut
the test short before its config section (config coverage 94.2% -> 90.8%).
Run the timed loop with the cache On, as release builds do.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@bsommers
bsommers merged commit 604af1b into main Nov 11, 2026
15 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant