Skip to content

Home: serve the parked hero backdrop from the retained region cache - #1302

Merged
GLinnik21 merged 8 commits into
mainfrom
perf/home-hero-ground-cache
Nov 16, 2026
Merged

GLinnik21 merged 8 commits into
mainfrom
perf/home-hero-ground-cache

Conversation

@GLinnik21

@GLinnik21 GLinnik21 commented Nov 9, 2026 •

Copy link
Copy Markdown
Collaborator

What

While Home is parked at the hero, its backdrop (the AmbientWash, the hero art over it and the scrims) is static, but it was re-shaded every frame. On the television (Mali HWCNT, frame.ui, before this change) the ground's grad plus image classes cost about 2.6M of the frame's 9.5M GPU_ACTIVE cycles (about 3.9 ms at 672 MHz), frames finished about 0.5 ms past the compositor's aim instead of 2.5 ms early, and grid-pong / hero-pong missed 18-50 refreshes per 60 cycles against 5-15 before. About 82% of the screen is unchanged frame to frame in grid-pong.

This paints the backdrop ONCE into the existing retained-texture region cache (gfx::region_paint) and serves it as one quad until an input changes. No damage-region renderer; no new cache.

Design

  • The shared mechanism, extended in place. Painter::cached_ground is the exact-semantics sibling of cached_region (one private body, cached_in, behind both). cached_region serves its picture as a GROUP, so a painter's alpha, gain or translate is applied to the texture; a ground's primitives take the alpha one by one (Painter::ambient mixes the wash toward the app ground), which is not the group's blend. So a ground is served only through a plain painter (Painter::is_plain: a page at rest, not dipping, not sliding) and drawn live through any other. The Under posters preview's cached_region is unchanged.
  • The key names the picture. Backdrop::ground_key holds only the screen's own state: the exact bits of the wash's twelve corner springs (AmbientWash::paint_bits), each art layer's texture id and decoded size, the dive (env.sp, from which the art's offset and the hero's own alpha follow) and main's shelf shade (WashScrim::paint_bits). The renderer folds in what only it knows: Painter::cached_ground is handed the texture ids, and gfx::region_ground_key mixes in each one's tex_ledger::revision (a texture re-specified under one name is another picture) and the two program switches the ground's paths read.
  • Motion: bypass, not a new key every frame. A key that changed on every frame of a reveal, a flip or the dive would fill the texture every frame: the live shading plus a full-screen write plus a quad, dearer than not caching. So the picture has NO name (drawn live, nothing filled) until every spring that eases it has landed (AmbientWash::at_rest, each resident art layer standing at exactly 1.0 with no velocity, the dive) and there is no slide. This needed one real fix beyond the cache: the dive was only ever stepped, and a bare Spring::step parks one ulp off its target with a velocity of ~1e-44 and stays there, so after the first Hero -> grid -> Hero trip the cache would never engage again. HomeScreen::update now lands the dive (Spring::land), as the art and wash springs already are. A regression test (the_backdrop_has_its_name_back_after_a_trip_to_the_grid) failed before that call ((3e-45, -1.8e-44)) and passes after.
  • Glass and the frozen ground are untouched by construction. The discovery walk and every blur-source pass decline the region (backdrop::discovering() / blur_source_pass()), so the ground still declares and draws its primitives there exactly as before and GLASSDIFF keys on the same arguments; the inline capture and sample_control_ground read the framebuffer, which holds the same pixels.
  • Memory. The region is a full 1928x1088 RGBA texture (8.0 MiB incl. REGION_SLACK), within the render-set ledger's 64 MiB (region_resident_bytes() was already summed there); it is one slot, one picture on screen at a time, and region_frame_end gives it back on any frame no page asked (the grid, a dipped page, another screen).
  • Sans-IO. No IO, clock or global in the machine; ci/check-deps.sh ledgers unchanged. The key is a pure function of the screen's own state; the fill and the quad are the renderer's.
  • /tmp/plxnative-nopreviewcache now also draws the Home backdrop live (same binary A/B).

Evidence

On head 0695176 (origin/main 8e8330a merged in; review fixes in the last commit):

  • Merge. Main's Home changes since the branch point (refactor(ui): complete owned presentation and replay inputs #1392, refactor(sans-io): complete machine input and effect boundaries #1358, Polish the Home hero, Continue Watching, and Detail shading #1310-RC 2 polish: Yellow reaches SRT/ASS tracks, timed skip prompts follow the countdown, hero title gap #1345, Continue Watching: a server that answers second no longer hides its newest cards behind the deck #1405) are taken as they are. The ground is now named by main's shelf shade as well: WashScrim::paint_bits sits beside AmbientWash::paint_bits, and Backdrop::draw and ground_key take the shade. Polish the Home hero, Continue Watching, and Detail shading #1310 removed the one-pass hero ground, so the key reads two renderer switches (art_wash_ok, wash_ink_ok).

  • Tests.

    • make check: exit 0, every test result: ok with 0 failed (screens 2179 passed, app 1420, hostsim app 1627, ui 1637, gfx 261, media 2136, hostsim media 2416), and the Python harness Ran 745 tests … OK.
    • make check-nodef: exit 0.
    • make ARM_PROFILE=release: exit 0.
    • the_backdrop_has_its_name_back_after_a_trip_to_the_grid fails with the Spring::land call removed (the dive parks at (3e-45, -1.8e-44)) and passes with it.
  • Replay anchor 1-boot-home-chip-grid, replaced. With the dive landed, it DIVERGED from f=154 (46 of 200 frames) in Targets and Resolve, with every other counter zero. Replaying the committed anchors against a build with only the Spring::land call removed gave all SAME, so the divergence comes from the dive landing. The fixture was a historical key-only AppFrameV4 recording (refactor(ui): complete owned presentation and replay inputs #1392), and the current recorder cannot emit that format. It was therefore re-recorded with tools/plxnative-rec rerecord as a current AppFrameV5 anchor (state_fp 13512213413816145485, 266 frames, anchor: true kept). This retires that fixture's V4 ledger. 6-settings-family stays a V4 fixture that replays SAME. The pins (recorder.rs, test_harness.py, test_replay_fixtures.py) and the README census follow the change. make check-replay ran three times, once at 960x540: SAME=6 REFUSED_EXPECTED=2 unexpected=0.

  • Simulator pixel diff (before the merge). Cached against live, on the same binary: 1 to 5 pixels of 2,073,600 differ, each by 1 LSB. Main's shade inside the cached ground has not been pixel-diffed after the merge.

  • Review fixes (0695176).

    • A resident art layer is named only at exactly full reveal, not just at zero velocity. bind leaves a spring at velocity 0 on a jump or when art arrives, and that would have cost one wasted fill. Two tests fail against the old gate.
    • The screen no longer reads renderer state (tex_ledger, program switches). The renderer mixes them in instead (gfx::region_ground_key, with its own test).
    • Gates on this head: make check (136 steps, all ok), check-nodef, check-replay (SAME=6 REFUSED_EXPECTED=2 unexpected=0) and make ARM_PROFILE=release. Re-measured on the TV: grid-pong cached, GPU_ACTIVE p50 7.20M, 1 region fill in the run.
  • Simulator pixel diff, after the merge (same binary, --cw-art-fixture mock, hero pinned; the cached legs against nopreviewcache legs, with a free-running spinner at the top right masked):

    • With the hero parked, with a Continue Watching card focused, along the CW row, into the grid and after the Hero → grid → Hero trip: 0 differing pixels in most cases.
    • Everywhere else, at most 1 LSB. Those pixels sit in boxes (the hero button row, the Play pill) that also differ live against live.
    • Exception: 7-8 card-edge pixels at 1 LSB in one cached leg each.
    • The fill log shows 1-2 fills per cached run (boot, and after the trip) and 0 in every live leg.
    • The overdraw ledger: grad falls from about 2.07M to under 45k px/s, and panel from 4.9M to 2.8M px/s.

Television

Measured 2026-11-16 on the dev set: make ARM_PROFILE=release deploy of the merged branch (verify-deploy: 47 files match), tests/run.py --fps --mock. Every pair is the SAME binary, and the control leg arms plxnative-nopreviewcache, which draws the backdrop live.

grid-pong (the hero is parked and focus walks the first shelf; this is the case the cache targets). Pacing legs ran with no profiler, panel off, four interleaved pairs. The figure is missed refreshes per 60 cycles:

pair cached live
1 11 55
2 35 51
3 0 (the scene's 0-miss budget passes) 38
4 33 49
mean ≈20 ≈48

The cached leg wins every pair. worst_ms p50 is 19.5-20.0 ms cached against 23.5-24.3 ms live.

Mali HWCNT, frame.ui (--extra-trigger plxnative-hwcnt=frame.ui, panel on, one pair; the miss counts of these legs are not quotable):

GPU_ACTIVE / frame cached live
mean 7.09M 10.05M
p50 7.18M 10.33M
p95 9.10M 10.93M
max 12.95M 14.25M

So p50 is 3.15M cycles lower, about 4.7 ms at 672 MHz, or -30 %. JS1_ACTIVE falls from 2.54M to 0.24M. L2 external write beats fall from 245k to 30k per frame. The worst cached frame, which includes the fills at each settle, is still below the worst live frame.

hero-pong (the hero flips every 600 ms, so a slide is always in motion and the cache is bypassed by design). Panel on, two pairs: cached 106 / 90, live 89 / 112. No change, as designed.

home-idle, cached: PASS, 59 loop/s, about 1 fps presented. It was not A/B'd, because the idle screen does not redraw the ground per frame.

Kernel scheduler trace (tools/tv-sched-trace.sh --app, two 6 s windows per leg in a grid-pong run armed with framecb + framering=17, analyze-sched-trace.py --latch, panel on):

cached live
frame pairs scored 394 334
waits ≥ 10 ms, GPU-late 0 22 (+1 tick ×13, +2 ticks ×8, +0 ×1)
waits ≥ 10 ms, compositor (on time) 330 0
GPU done minus aim, on-time frames, p50 / p95 / p99 -6.17 / -4.62 / -2.60 ms -6.64 / -3.52 / +1.81 ms

With the cache, the trace windows hold no GPU-late frame. That includes the windows' share of the fills at each settle, so the fill frame did not show up as a spike. The trace covers 12 s of each 120 s run, whose bench misses were 35 cached and 63 live.

Not run: home-hero and home-cw-row-walk.

🤖 Generated with Claude Code

GLinnik21 and others added 8 commits November 9, 2026 16:58
While Home is parked at the hero the backdrop (wash, art, scrim) is static, but it was
re-shaded every frame: ~2.6M of the frame's 9.5M GPU_ACTIVE cycles on the television.
Paint it once into the shared region cache (gfx::region_paint) and serve one quad until
an input changes. Painter::cached_ground is the exact-semantics sibling of cached_region
(only through a plain painter); Backdrop::ground_key names the picture by every input it
draws (wash corners, per-layer art id/revision/size/position, scroll offset, hero alpha,
the ground-mode switches) and refuses a name while anything moves, so a slide or a settling
spring draws live. Glass and the discovery/source passes decline the region and draw live,
so their recorded draw arguments and source pixels are unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…fter a trip to the grid

A bare Spring::step parks the dive one ulp off its target with a velocity of ~1e-44 and keeps it
there, so the backdrop's rest test (dive velocity exactly 0) was false for the rest of the page's life
after the first Hero -> grid -> Hero trip and the cache never engaged again. Land it like the art and
wash springs. A reveal spring with no texture behind it no longer vetoes the name, and the
cached_ground doc says what a non-plain painter does to the region ask.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… lands exactly

The dive's Spring::land (previous commit) changes the hashed state of the page from the frame the dive
to the second shelf lands (frame 198 on): present, input, result, land, effect, focus and hit counters all
stay zero. Attributed by replaying the committed anchors against a build with only that call removed
(all three SAME). Re-recorded on the unchanged shape; only the recording segment is replaced and
Targets and Resolve replay SAME, three runs at 1920x1080 and one at the CI window.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Home's backdrop draw now takes main's shared side and shelf shade (the scrim), so the cached
ground is named by it too: WashScrim::paint_bits (ink, the shader's mode and every uniform) joins
Backdrop::ground_key, and HomeScreen::backdrop_shade builds the frame's shade once for the draw
and for the name. The one-pass hero ground switch main removed leaves the key (two renderer
switches remain). The replay anchor is main's, to be re-recorded after the dive landing.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
… re-recorded

The entry (frames 198 on, 64 of 262) described a re-record of 1-boot-home-chip-grid that is not in
this tree: the anchor here is main's historical AppFrameV4 fixture, which the dive landing diverges
from frame 154 (46 of 200 frames, every other counter zero). The entry returns with the re-record.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Home's snap dive now lands exactly (Spring::land), which moves the recorded canon of the anchor from
frame 154 (46 of 200 frames, every other counter zero). The fixture was a historical key-only
AppFrameV4 recording the current recorder cannot emit, so it is re-recorded as a current
AppFrameV5/codec-6 recording (state_fp 13512213413816145485, 266 frames) with plxnative-rec rerecord,
which keeps the anchor flag. This retires this one fixture's V4 ledger; 6-settings-family stays a V4
fixture and replays SAME.

The pins follow: recorder.rs's fixture preflight row takes the current shape and 266 frames, and the
frozen-V4 manifest loop drops the fixture; test_harness.py's fingerprint table takes the current
state_fp. The README gets the census entry and no longer calls this fixture historical.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The fixture is now a current-format recording: its manifest is closed-enum structural like the
-current fixture's, so the outbound guard refuses it by the same rule, and the policy census counts
266 frames for it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…es its own state

Review findings on #1302.

- Backdrop::ground_key tested only the reveal spring's velocity, but bind leaves
  a spring at velocity 0 where it jumps (a replacement at the draw) and where
  non-resident art arrives (parked at 0.0): a resident layer at pos < 1.0 got a
  name for one frame and paid a full 1928x1088 fill wasted the next. A resident
  layer is stepped toward 1.0 and landed there, so it is settled only at exactly
  1.0 with no velocity (both layers). The reveal alpha drops out of the name: a
  named layer is always at 1.0. Two tests fail against the old gate (the spring
  states directly, and art arriving at draw_page's bind).
- The screen read renderer process state (tex_ledger::revision, art_wash_ok,
  wash_ink_ok). Painter::cached_ground now takes the texture ids the picture
  samples and gfx::region_ground_key mixes each one's revision and the two
  program switches into the key, so the screen's name holds only the screen's
  own state. The revision assertion moves to a gfx test.
- Docs: tests/README.md no longer states a stale Home frame count; region_frame_end
  names which pages ask every frame now that Home is a second caller; the ui
  CLAUDE.md bullet follows the new split.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@GLinnik21
GLinnik21 marked this pull request as ready for review November 16, 2026 16:40
@GLinnik21
GLinnik21 merged commit 8fc1b62 into main Nov 16, 2026
13 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