[sleepyeyedjoe]

Fixes #1969. Built on #2022: its two commits come first, and only the last commit is this change.

In short

• What it fixes: a patch of distant scenery went dark for exactly one frame when the game switched it to a sharper texture. The traced case is the cliff beside the Castle Town wall in Hyrule Field.
• How: until a shader reads such a texture for the first time, its pool table entry now holds a tiny copy of the texture's own content instead of the dummy. The first frame is a little soft instead of black.
• Cost: about 6 µs per registration and 16 MB in all on an M4 Pro. Memory and frame times stay within the run-to-run range.
• Off switch: DM_NVN_POOL_STANDIN=0.

What and why

Cause.

• The surface's shader reads its textures through the bindless pool table. Once pool_budget() is spent, a walk makes only the textures a shader has read (pool_seen). An ID no shader has read holds the dummy, which reads 0.
• The first read sets the ID's bit, and pool_seen_scan makes the texture for the next frame. So the first frame is dark and the next is right.
• In this game the budget is always spent (909 MB against 15–18 GB of currentAllocatedSize on a 24 GB Mac; see Ocarina of Time (0400486024DEC000 v131072, Mac): parts of the scenery flash dark for a split second when the game loads a sharper version of them #1969).
• The textures that hit this are not ordinary mipped material textures. Each piece of distant scenery has a set of its own per resolution, all with one level:
  • a BC5 texture, for example 1048x1088;
  • two three-layer arrays of half that size, BC6H and BC7.
• The game registers a new set 12 to 969 frames before the material names it.
• Which registrations a shader will read is not known ahead. In 58 s of play the game registered 14,455 textures that stayed unread (9.8 GB), against 10 first reads. Making textures ahead by age and size cost 0.7–1.9 GB for one hit in three (Ocarina of Time (0400486024DEC000 v131072, Mac): parts of the scenery flash dark for a split second when the game loads a sharper version of them #1969).

Pictures. Three presents in a row at the cliff's first read, from the replays: stand-ins off in the top row (the middle frame is dark), stand-ins on in the bottom row.

The same three frames with stand-ins on, enlarged: in the middle one the cliff samples its stand-in and is a little soft.

Fix. A texture the walk leaves out for good holds a stand-in in the tables until its first read (pool_stand).

• What the stand-in holds:
  • the texture's own smallest levels, from the first of at most 1 KB on;
  • or, when it has no level that small, its last level cut down to at most 4 KB a layer: every n-th block of every n-th block row (nvn_deswizzle_pick). The blocks stay as they are, so compressed formats need no decoder.
• How it is made: the host reads those bytes from the storage on the CPU into a small shared texture cut from a heap that is resident from the start. That takes no upload batch and no residency commit, and a table may name it at once.
• Which textures get one: 2D textures and 2D arrays of up to 8 layers, with the type, layers, format and channel swizzle of the view tex_by_id makes for the ID. The swizzle rule moves to treg_swizzle, which both use.
• Unchanged (the dummy): other types, textures in sparse pools, depth formats, and render targets no pass has written.
• Only once the budget is full. Below it a later walk makes the texture. A table walked while the budget had room is walked once more when the budget has filled.
• At most 512 a frame. An area load registers thousands at once (Hyrule Field: 5,152, which took 82 ms in one frame without the limit). The rest wait and are written into the tables in place, as a newly read ID's texture is.
• DM_NVN_POOL_FIRST=1 logs each first read of a texture not made yet and what it found. The totals go to the log every 300 frames.

Evidence

Windowless replays of a player's recorded route past the cliff (DM_KEYS, DM_FRAME_DELTA=0, M4 Pro, macOS 27.0.1): 10 with DM_NVN_POOL_STANDIN=0 and 8 without. The replays are not deterministic (the cliff's set streams in about half of them), so the comparison is per event.

	Stand-ins off (10 runs)	Stand-ins on (8 runs)
First reads after the area load that found the dummy	31 of 31	0 of 49
The cliff's first read, connected dark cells on a 32x18 luminance grid	9, 10, 10, 12 (4 runs)	0–2 (5 runs)
First reads at the area load that found the dummy, per run	39	5–11

• The grid's noise: over 17,994 presents without a first read, a connected group of 4 or more cells appears in 7.
• By picture: with stand-ins off the cliff is dark for one frame; with them on it is a little soft for that frame.
• Stale stand-ins: none of the 49 was made from storage the game wrote afterwards.
• The frames left at the area load are the limit of 512 a frame at work: those reads come in the first frames, before every stand-in is made.

Cost

Medians over the runs, stand-ins off and on:

	Off	On	Run-to-run range
Resident memory	10,830 MB	10,883 MB	10,725–11,536
GPU allocated	16,376 MB	15,965 MB	15,739–17,064
Residency set	6,465 objects	6,491 objects
Frame time p50	16.67 ms	16.66 ms
Frame time p95	16.85 ms	17.19 ms	16.8–19.4 in both
Submit+present p50	6.38 ms	6.51 ms	6.2–9.6

• A run makes about 57,000 stand-ins in 355 ms (6 µs each) and holds about 6,000 at a time, in four 4 MB heaps.
• The p95 medians differ by 0.34 ms, but runs of both kinds fall in two groups (near 16.8 ms and 17.5–19.4 ms; 3 of 10 and 4 of 8 in the upper one), so the replays show no difference.
• No new red lines. The known texture type mismatch … texture ID 850 appears in 6 of the 10 runs and 2 of the 8.

Tests

• New: t_pool_standin (51 checks; 31 with the switch off). It reads the stand-ins back from the GPU and covers:
  • levels as they are, a level cut down, and a compressed texture;
  • an sRGB view with a swizzle, a 2D array, and a layer of it;
  • the first read, another registration, and an emptied ID;
  • a frame's share, and the rest written in place.
• New: t_tex P checks the picked blocks against the level decoded whole, in both GOB orders.
• Changed: t_pool_notes and t_pool_chunks. Where they checked that an unread texture past the budget is the dummy, they now check that it is not made (its stand-in, or the dummy with the switch off).
• Passing: those, t_pool_seen_replace, t_cpu_tex, t_bc_alias, t_defer_chain, t_image_usage, t_image_type, t_view_swizzle, t_stencil_view, t_pfv, t_int_float_view, t_readback; docs_symptoms.py --check, test_docs.py, test_env_switches.py.

Not done

• Other games: scripts/regress.py was not run, as this Mac has no other game's build. The stand-ins act only once pool_budget() is spent.
• Live play (one short session): on the installed build the player walked Hyrule Field toward the wall for about two minutes (M4 Pro, fullscreen) and saw no dark frame on the cliffs. The log's totals for that session: 46 first reads found a stand-in and 8 the dummy. All 8 came within 300 frames of the area load, while stand-ins were still waiting; after that, 39 of 39 found a stand-in. Frame time p95 was 17.35 ms and submit+present p50 7.35 ms (medians of the session's 300-frame windows), against 17.75 and 8.04 ms in the first 9,000 frames of the previous session on the old host, which was not the same route. No red lines.
• The diagnostics behind the pictures and the luminance grid are not part of this PR.

🤖 Generated with Claude Code

[Itsjonaathan]

I tested this PR (with #2022, which it includes) on a MacBook Air M5 (10-core GPU, 16 GB, macOS 27.2). It was applied to 04811a63, with the host rebuilt and the shader chain unchanged (39eb2f781d07). The game renders at 1280x720.

• Before: in one session of about 8 minutes, surfaces went black for a moment three times, twice in Kakariko Village and once in the Kakariko Graveyard.
• After: no black flashes in about 4 minutes in the same areas. The frame rate is unchanged at 60 fps, GPU p50 12–14 ms, with 0–4 frames dropped per 300.
• Stand-ins: the log shows them working: pool stand-ins up to frame 1448: 4492 made in 56.5 ms (1249 of them a level cut down), 1322 gave way to their texture, 3140 held now in 3 heaps of 4 MB (0 not made: the heaps were full).
• Tests: t_pool_standin (51), t_pool_seen_replace (38), t_pool_chunks (148) and t_pool_notes (81) pass, 0 failed.

The check was by eye, and the session after was short; it was not a frame-by-frame comparison.

[seedds]

Landed on main as 6c67644, with you credited as co-author. Thank you: the per-event replay numbers and the before/after pictures made the case clear. Thanks also to Itsjonaathan for the MacBook Air M5 test.

What changed on the way in:

• Rebased onto 6d9edb0. That is Ocarina of Time: large models no longer go black for one frame twice, 4–5 frames apart, when the game streams new textures into them (a texture ID a shader has read keeps its read mark when it gets another texture) #2022 as it landed: the read mark stays while the ID holds a texture and is cleared only when it is emptied, and there is no DM_NVN_POOL_SEEN_KEEP. The conflicts were only on those lines. The stand-in code is otherwise yours, unchanged.
• t_pool_standin: the readback buffer is checked for nil, because the C lint ratchet flagged it.
• Ocarina's game note has a line under "Found on this game".
• DM_NVN_POOL_STANDIN=0 stays as an A/B switch. Other games haven't been checked for stand-ins made from storage written afterwards, and DM_NVN_POOL_FIRST=1 reports those.

Checked here (M-series Mac, macOS 27.2):

• t_pool_standin: 51/51 with each encoder setting, 31/31 with stand-ins off.
• t_pool_chunks: 151, and t_pool_notes: 81, both with stand-ins on and off.
• t_pool_seen_replace: 44, and t_view_swizzle: 554.
• t_tex: 5,382, also under ASan/UBSan.
• The host builds, the C lint stays at its baseline, and the docs and env-switch tests pass.

Not run here: no game. Only games that read through the pool table reach this, and none of the local builds has libraries on the current chain. A short session on main would confirm it.

This closes #1969.