render: repaint and upload only the rows a frame changed #424

Merged

natsukium merged 6 commits from render/incremental-instances into main 2026-09-25 10:31:45 +09:00

Conversation 0 Commits 6 Files changed 16 +971 -153

natsukium commented 2026-09-25 08:38:28 +09:00

Owner

Copy link

Closes #403

Per keystroke the client rebuilt every cell instance and re-uploaded the whole bg/fg/deco instance buffers, so one echoed character cost a full-grid walk plus a full-buffer copy.

The renderer now keeps cell instances across frames in fixed-stride row slots (crates/felis-render-wgpu/src/row_cache.rs), repaints only the rows the client's shadow ScreenBuffer marked dirty plus the cursor's old/new rows, and uploads only the changed byte ranges:

• staged path (discrete GPU): Queue::write_buffer per changed run;
• unified-memory mapped ring (#396): ranged mapped views into the ring slot, no blit. Each ring slot tracks the (epoch, version) it last took.

Every input that reaches all rows falls back to a full repaint (geometry, cell metrics, viewport, selection, chrome rows, pre-edit, DECSCNM, shape frame, glyph atlas recycle, theme/palette, font reload, atlas thrash, slot overflow). If padded slots would exceed half the device buffer limit, rows stay packed and every frame repaints them all, the same as before. The property test incremental_frames_match_a_full_rebuild drives random shadow writes, scrolls, resizes, cursor/paint-state changes, sized cells, and both padded and packed limits, and after every frame it compares the result with a from-scratch walk. ring_slots_track_the_source_through_ranged_writes covers the ring.

Measurements

Linux, niri 60 Hz, NVIDIA (adapter confirmed), release builds, interleaved with base a53cd63e, wl-latency harness, 154x61:

run	frame build+upload CPU per keystroke, median (p95)	wl-latency p50 / mean / p95 ms	load start/end
base 1	272 (391) us	5.09 / 5.29 / 6.78	6.39 / 5.42
this 1	51 (106) us	5.11 / 5.21 / 6.56	4.59 / 1.98
base 2	387 (1156) us	7.17 / 7.50 / 11.63	5.09 / 8.17
this 2	52 (141) us	5.10 / 5.28 / 6.84	6.29 / 2.49
base 3	372 (548) us	6.01 / 6.39 / 8.49	2.07 / 3.83
this 3	51 (82) us	5.12 / 5.18 / 6.54	3.23 / 3.09

(foot control ~2.2 ms p50.) End-to-end p50 does not move because vsync and compositor time dominate it. A 212x93 scroll flood, where every row repaints, costs ~5% more per frame (601/604 -> 628/647 us). That cost and the whole-grid glyph populate walk are split into #422.

macOS (M4 Max): the felis-render-wgpu suite passes with the mapped upload mode. A GUI check could not run because the screen was locked.

Closes #403 Per keystroke the client rebuilt every cell instance and re-uploaded the whole bg/fg/deco instance buffers, so one echoed character cost a full-grid walk plus a full-buffer copy. The renderer now keeps cell instances across frames in fixed-stride row slots (`crates/felis-render-wgpu/src/row_cache.rs`), repaints only the rows the client's shadow `ScreenBuffer` marked dirty plus the cursor's old/new rows, and uploads only the changed byte ranges: - staged path (discrete GPU): `Queue::write_buffer` per changed run; - unified-memory mapped ring (#396): ranged mapped views into the ring slot, no blit. Each ring slot tracks the `(epoch, version)` it last took. Every input that reaches all rows falls back to a full repaint (geometry, cell metrics, viewport, selection, chrome rows, pre-edit, DECSCNM, shape frame, glyph atlas recycle, theme/palette, font reload, atlas thrash, slot overflow). If padded slots would exceed half the device buffer limit, rows stay packed and every frame repaints them all, the same as before. The property test `incremental_frames_match_a_full_rebuild` drives random shadow writes, scrolls, resizes, cursor/paint-state changes, sized cells, and both padded and packed limits, and after every frame it compares the result with a from-scratch walk. `ring_slots_track_the_source_through_ranged_writes` covers the ring. ## Measurements Linux, niri 60 Hz, NVIDIA (adapter confirmed), release builds, interleaved with base a53cd63e, wl-latency harness, 154x61: | run | frame build+upload CPU per keystroke, median (p95) | wl-latency p50 / mean / p95 ms | load start/end | |---|---|---|---| | base 1 | 272 (391) us | 5.09 / 5.29 / 6.78 | 6.39 / 5.42 | | this 1 | 51 (106) us | 5.11 / 5.21 / 6.56 | 4.59 / 1.98 | | base 2 | 387 (1156) us | 7.17 / 7.50 / 11.63 | 5.09 / 8.17 | | this 2 | 52 (141) us | 5.10 / 5.28 / 6.84 | 6.29 / 2.49 | | base 3 | 372 (548) us | 6.01 / 6.39 / 8.49 | 2.07 / 3.83 | | this 3 | 51 (82) us | 5.12 / 5.18 / 6.54 | 3.23 / 3.09 | (foot control ~2.2 ms p50.) End-to-end p50 does not move because vsync and compositor time dominate it. A 212x93 scroll flood, where every row repaints, costs ~5% more per frame (601/604 -> 628/647 us). That cost and the whole-grid glyph populate walk are split into #422. macOS (M4 Max): the felis-render-wgpu suite passes with the mapped upload mode. A GUI check could not run because the screen was locked.

natsukium added 4 commits 2026-09-25 08:38:28 +09:00

render: repaint and upload only the rows a frame changed ... 897f7e0b05

Every keystroke rebuilt the instances of every cell and re-uploaded
the whole instance buffer, so one echoed character cost a full-grid
walk plus a full-buffer copy, scaling with window area rather than
with the change.

The client's shadow already marks the rows each apply writes (it shares
the daemon's ScreenBuffer), and nothing read those marks. The renderer
now keeps its cell instances across frames in fixed-stride row slots,
repaints the rows the shadow marked plus the rows the cursor left and
entered, and the client clears the marks after each paint. Unused slot
entries are zero-sized quads, which rasterize nothing, so the draw
calls and passes are unchanged. Packed rows were rejected: an echoed
glyph changes its row's instance count, which would shift and
re-upload every later row. Every input that reaches all rows repaints
them all: geometry, cell metrics, viewport, selection, chrome rows,
pre-edit span, DECSCNM, the shape frame being built, a glyph atlas
recycle (a new counter), a theme or palette change and a font reload
(explicit invalidation), a frame that ran out of atlas, and a row
outgrowing its slot (which doubles that slot, so a line being typed
does not relayout every few keys). A property test drives random
shadow writes, scrolls, resizes, cursor moves and paint-state changes
and requires the cached instances to equal a from-scratch walk after
every frame.

Uploads follow the rows: the staged path writes each changed run with
`Queue::write_buffer` at its offset, and the unified-memory ring writes
the changed runs into its mapped slot, so no blit returns on that path.
Each ring slot remembers the version it last took, since it misses the
frames written into the other two slots.

Measured on Linux (niri 60 Hz, NVIDIA, release builds, interleaved
with the base a53cd63e, wl-latency harness, 154x61 grid), CPU time of
the frame's instance build and upload per keystroke frame, median
(p95):

  base: 272 (391), 387 (1156), 372 (548) us  load 6.4/5.1/2.1
  this:  51 (106),  52 (141),  51 (82)  us   load 4.6/6.3/3.2

wl-latency p50 stays at 5.1 ms (base 5.09/7.17/6.01, this
5.11/5.10/5.12; the slower base runs had the higher load): the saved
0.2-0.3 ms sits below the vsync and compositor time that dominates the
figure. A scroll flood at 212x93, where every frame repaints every row,
costs 628/647 us against the base's 601/604 us per frame, the price of
the per-row copy and the slot padding.

Assisted-by: Claude Code

render: keep padded row slots within the buffer limit ... 1397ef8bcb

A slot is as wide as the widest row, so one wide row pads every other
row to its width, and the first layout also doubled every slot. At the
largest admitted grid (2048x1025) filled with glyphs the foreground
layer then needed more than wgpu's default 256 MiB buffer limit, which
the packed layout stays under, and the buffer allocation fails.

The first layout now sizes slots at the widest row plus an eighth plus
eight, and only a slot a row outgrew doubles. When a padded layer
would exceed half the device's buffer limit (the ring rounds capacity
up to a power of two), or four times its packed size past a 16 MiB
allowance, the frame keeps the rows packed and repaints them all, as
every frame did before, until the rows even out. The property test now
runs under a limit that forces packed rows as well as one that does
not, and adds OSC 66 sized cells.

Assisted-by: Claude Code

docs: state the packed-row fallback and the property test's reach ... bb6a6db371

The rendering pages said a frame always uploads only the rows it
rebuilt, but when padded row slots would not fit the buffer limit the
cell layers stay packed and every frame rebuilds and uploads all rows,
so the claim held only for the slotted layout. The testing reference
also claimed the row-cache property test covers every frame-wide paint
input, while it never builds a non-empty shape frame (that needs a real
font stack and shaper); it does cover both slotted and packed rows.

Assisted-by: Claude Code

Merge remote-tracking branch 'origin/main' into render/incremental-instances 7202896267

natsukium added 1 commit 2026-09-25 08:47:22 +09:00

Merge remote-tracking branch 'origin/main' into render/incremental-instances ... b355f4e3e8

# Conflicts:
#	CHANGELOG.md

natsukium added 1 commit 2026-09-25 09:29:43 +09:00

Merge remote-tracking branch 'origin/main' into render/incremental-instances a5ce909f48

natsukium merged commit 43ac9b1454 into main 2026-09-25 10:31:45 +09:00

natsukium deleted branch render/incremental-instances 2026-09-25 10:31:46 +09:00

natsukium referenced this pull request from a commit 2026-09-25 10:31:47 +09:00

render: repaint and upload only the rows a frame changed (#424)

natsukium referenced this pull request 2026-09-25 10:47:31 +09:00

grid: cache recent pens in front of the style dedup index #429

natsukium referenced this pull request 2026-09-25 11:02:19 +09:00

render: walk only the marked rows to prime and shape glyphs #431

natsukium referenced this pull request 2026-09-25 11:04:36 +09:00

grid: let TableGc force a sweep, and sweep the row-cache test through it #432

natsukium referenced this pull request from a commit 2026-09-25 11:04:36 +09:00

grid: let TableGc force a sweep, and sweep the row-cache test through it

natsukium referenced this pull request from a commit 2026-09-25 11:08:55 +09:00

grid: let TableGc force a sweep, and sweep the row-cache test through it (#432)

natsukium referenced this pull request from a commit 2026-09-25 12:29:28 +09:00

render: walk only the marked rows to prime and shape glyphs (#431)

natsukium referenced this pull request 2026-09-25 12:52:03 +09:00

grid: a scroll over a dirty region, and DL/IL, ship rows instead of a Scrolled directive #447

natsukium referenced this pull request 2026-09-25 13:15:57 +09:00

bench: follow up the 9d1d842f cross-terminal run #405

Commenting is not possible because the repository is archived.

Reviewers

No reviewers

Labels

Clear labels   

priority/P0

Must be resolved before the v0.1.0 tag

  

priority/P1

Must be settled before the first public contract freezes

  

priority/P2

Explicitly deferred until after v0.1.0

  

release/v0.1.0

Work tracked for the first tagged release

  

status/blocked

Cannot start now: waits on an upstream release, another issue, or a recorded revisit trigger

  

status/planned

Triaged with a source-grounded plan and a passed pi review; ready to implement

  

type/bug

Shipped behavior that contradicts the docs or the code's own intent; needs a product code change

  

type/design

An open scope or trade-off question; needs a recorded decision in the owning explanation doc before code

  

type/test-gap

Documented or reviewed behavior that no test pins; usually split from a review finding, needs no product code change

  

type/tracker

Parent issue that tracks child work

No labels

priority/P0

priority/P1

priority/P2

release/v0.1.0

status/blocked

status/planned

type/bug

type/design

type/test-gap

type/tracker

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

natsukium/felis!424

No description provided.