[sleepyeyedjoe]

In short

• What it fixes: large models went black for a moment, twice in quick succession, when the game swapped in new surface pictures (textures) for them. This happened to the Castle Town wall, Hyrule Castle, rocks and trees near the town, and the Lon Lon Ranch barn.
• What it does not fix: a different problem, where a part of the scenery goes dark for a single moment the first time the game draws a newly loaded picture. It has its own cause and is reported in 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. A fix for it is proposed in Ocarina of Time: a patch of scenery no longer draws dark for one frame when the game gives it a sharper texture (a pool texture the walk does not make holds a stand-in of its own colours until its first read) #2075, which is built on this PR.
• Seen on a second Mac: another user found the same double flashes on an M5 Max. With a change of the same kind, they saw no flashes in one 5-minute session (comment in #1969).

Two problems, one fixed here

	Paired dark frames (fixed here)	Single first-read frame (not fixed here: #1969, fix proposed in #2075)
What you see	A model black for one frame, twice, 4–5 frames apart	A surface darker for one frame, once
Texture ID	One a shader has already read; the game puts a new texture into it	One no shader has read yet
Why the dummy is read	The new registration cleared the ID's read mark, so the walk left the replacement out	The ID has no read mark, and the walk's room is 0, so the walk leaves it out
Example	The Castle Town wall's material set	The cliff left of the Castle Town wall

What and why

In Ocarina of Time (0400486024DEC000 v131072), large static and mesh-shader models go black for one frame, and again 4–5 frames later, a few times a minute in play. The models include the Castle Town wall, Hyrule Castle, rocks and trees near the town, and Lon Lon Ranch's barn.

• They keep their shape, and the fog is still drawn in front of them. Terrain, foliage and sky are unaffected.
• A player's 64 s screen recording (M4 Pro) shows three such frames:
  • the barn at 38.8 s;
  • the wall and castle at 58.53 s and 58.60 s, 4 frames apart.

Cause.

• The models' pixel shaders read their textures through the bindless pool table. When a walk (pool_gpu) writes an ID's entry (pool_entry), it makes the ID's Metal texture in either of two cases:

  • the texture fits the walk's room (pool_room(): the frame's POOL_FRAME_BYTES share, within pool_budget());
  • whatever the room, a shader has read the ID before (its read mark, pool_seen), up to POOL_REQ_BYTES (128 MB) of such textures a frame.

  Otherwise the entry is the dummy, and a read of it gives 0 (black). After such a read, pool_seen_scan sets the mark and makes the texture, so the next frame is right.

• In this game the room is always 0. pool_budget() is a twentieth of Metal's working set: 909 MB on a 24 GB M4 Pro. currentAllocatedSize is 15–18 GB (details in 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). So only IDs with the read mark get their texture made before they are drawn.

• mtl_reg_tex cleared the read mark whenever the game registered another texture into an ID.

• The game's streaming replaces the 17 textures of the wall's material set at once, at 3–7 MB each:

  • it finalizes the old texture first, then registers the new one;
  • it registers each step twice, 4–5 frames apart.

• With the marks cleared, the walk left the replacements out, so the shaders read the dummy for one frame. The model is black, and the fog is applied after the read. Each of the two registrations of a step gives one dark frame, which makes the pair.

Fix. In mtl_reg_tex, an ID that held a made texture keeps its pool_seen mark when another texture is registered into it.

• A made texture is one retired by the game, or one still viewed. Checking the view alone is not enough, because the game's finalize drops the view before the new registration arrives.
• Still cleared as before: an ID that held no texture, or one that is emptied.
• The replacement: the next walk makes it under POOL_REQ_BYTES in the same frame, instead of leaving it out.
• DM_NVN_POOL_SEEN_KEEP=0 restores the old clearing.

Not fixed here: the single first-read frame (#1969). A fix for it is proposed in #2075, built on this PR.

• When the game streams a texture into an ID no shader has read yet, there is no mark to keep.
• With the room at 0, the walk leaves that texture out, and its first read samples the dummy for one frame.
• It shows as one dark frame, not a pair. The traced example is the cliff left of the Castle Town wall in Hyrule Field.
• It still happens with this change in: in the player's live play with this change installed, and in the M5 Max comment (see Evidence).
• 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 has:
  • the trace;
  • two fixes that were tried and dropped;
  • the relation to DM_POOL_BUDGET_MB makes textures up front against the residency set #1498.

Evidence

The evidence comes from windowless replays of the player's recorded route (DM_KEYS, DM_FRAME_DELTA=0, from the save it was recorded on), run with a diagnostic build. The diagnostics are not part of this PR; they can follow as a separate one if wanted.

• It reproduces without any stress. The paired dark frames come at the wall's streaming steps, at presents about 1470–1600 (the exact frames vary a little between runs). Pictures of the presented frames confirm them: the wall, gate, rock and castle are pitch black, while a banner and a rock in front are lit.

• A per-frame trace names the textures. The trace records which pool IDs the table left out. In exactly the two dark frames of one run (presents 1531 and 1535) it names the castle textures:

  • IDs 12566–12570, at 3.4 / 2.5 / 2.5 / 6.2 / 4.6 MB;
  • IDs 19442–19453.

  All of them had their read mark cleared.

• The uploads line up. In another run, the three dark presents (1584, 1588, 1593) were exactly the three frames with upload batches of newly registered large textures (10, 10 and 27 MB).

• Seen independently on a second Mac (comment in #1969): an M5 Max, macOS 26.6.2, main 270b6fd5 plus that user's own Ocarina of Time fixes.

  • Without the change: in the Castle Town market their flash detector caught two dark presents 5 apart. Their log showed the same ID (20670, 7.8 MB) read as the dummy twice, 5 frames apart, with a new registration in between. They matched the presents to those frames through a 6–11 frame present lag.
  • The change they made: the same kind as this one. An ID a shader has read keeps its mark when it gets another texture, and is queued for the next pool_seen_scan. Their condition is the read mark itself, where this PR's is that the ID held a made texture.
  • With it: no flashes seen in one 5.2-minute session around Hyrule Castle, its moat and the market. The detector's 6 hits were a water glint and camera motion.
  • What was still left: 15 frames still had first reads of IDs whose texture wasn't made. None of them came in pairs, and the detector flagged none of them. That is the single first-read frame of 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.
  • Sample size: one session with the change and one run each way headless (n=1).

• Ruled out along the way:

  • logical queue order and event waits;
  • the CPU running ahead of the GPU;
  • pass barrier mode (DM_NVN_BARRIER=full still showed it);
  • deferred texture handles registered in a later frame;
  • completion and fast-wake order;
  • the Metal 4 queue signal ordering;
  • the colour pass's other inputs: the screen-space shadow mask, the SH block and the light constants were normal in dark frames.

Checked

Validation, on the player's route:

• replays of 118 s;
• a per-frame 32x18 luminance grid, with a strict single-frame-dip rule;
• every flagged frame checked against a picture.

Build	Runs	Paired dark frames
Before, no stress	3	2–4 flagged at the wall's streaming steps each run (4–5 flagged in all), in pairs; one per run checked by picture: black
Fix, no stress	5	0
Fix, with a stress that stalls the queue worker at each present (it makes streaming steps collide more often)	5	0. Without the fix, the same stress gave 18 flagged frames in 8 runs (2.25 a run)
Same build, DM_NVN_POOL_SEEN_KEEP=0	2	They return in both runs, confirmed by picture. In one run the wall, gate, rock and castle are black over 57 of the 576 grid cells

• False positives: some flags in the fix-on runs were not dark frames. A Peahat spinning in front of the camera, or Link in the grass, was checked by picture.
• Scope: the table counts only the paired dark frames. The single first-read frame of 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 depends on when the game's stream lands. It showed live, and in some later replays, with this change in.
• Cost: frame intervals in frames 1801–4420 had a median of 16.7–16.9 ms and a p90 of 17.7–18.3 ms with the fix, against 16.9 / 18.0 ms without. That is within run-to-run variance. GPU time was 13.7–14.2 ms both ways.
• Base of the validation: main 7f50222 plus Avoid repeated archive scans for missing pipeline bases #1825, Split mesh draws with no task shader into grids of at most 1024 workgroups #1708, The pipeline archive bundled with the app is mapped too, not read into memory #1817, Present on the Mac: MetalFX scales at the snapshot, and pacing leaves the display link when the screen shifts under it #1045, Shader libraries compile with -fwrapv: Ocarina of Time's mesh-shader models no longer take their ambient light from the wrong probe texels #1844, Ocarina of Time: stop recompacting large pipeline caches on every launch #1840, Game-mode draw passes hold the next pass's task and mesh shaders until their fragments are done #1707 and Ocarina of Time: prewarm native mesh pipelines before attacks and enemies appear #1368, on a MacBook Pro M4 Pro with macOS 27.0.1.
• Base of this branch: main e121931 (MacBook Pro M4 Pro, macOS 27.0.1).
  • There the host builds clean.
  • check_t_pool_seen_replace (d07b5a0, written by another contributor and offered in the comments) reads the replacement's GPU pixels with the walk's room at 0. It passes 38/38 with each encoder setting and 36/36 with DM_NVN_POOL_SEEN_KEEP=0. Against nvn_mtl.m from before the fix, 6 of its 38 checks fail: the six replacement checks.
  • These tests pass with 0 failures: check_t_pool_chunks (148, also with DM_NVN_POOL_SEEN_KEEP=0), check_t_pool_notes (81), check_t_cpu_tex (98), check_t_bc_alias (19), check_t_defer_chain (59), check_t_image_usage (44) and check_t_image_type (10).
  • docs_symptoms.py --check and test_docs.py pass.
• Played on main: the same change is in a build of main e121931 with a few unrelated local changes. A short session in the Castle Town market showed no double flashes by eye; one single blink on the castle wall fits the first-read frame of 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.
• Risk, not measured: consider a game that cycles live textures through an ID a shader reads (KTGL-style, the view cache's case). It now keeps the mark across those changes. Each cycled texture is then made ahead under the 128 MB read budget, rather than waiting for a walk with room or for its first read. No game other than Ocarina of Time was run.
• scripts/regress.py not run: mtl_reg_tex is reached by every game, but the change only keeps a mark an ID already had, for an ID whose texture was made. Other games are not checked; see Risk.

Docs

• Reference entry Models black for one frame when a streaming step replaces their textures in docs/reference/rendering.md (Textures and formats); symptom index regenerated.
• DM_NVN_POOL_SEEN_KEEP in docs/env_switches.tsv.
• No shader-chain change; no game files, keys or extracted data.

🤖 Generated with Claude Code

[akratch]

Thanks for this fix. Our local OOT integration includes it, and the player now reports that flickering has stopped. That build combines changes, so this is supporting play evidence rather than isolated attribution.

I prepared an additional synthetic regression on this PR's exact head c7ea2af6c99a: test-only commit (two-file diff). It checks first-table replacement GPU pixels with no ordinary walk room, live replacement, real finalize-before-register, old-table entry stability, unread/empty IDs and unwritten targets. It exhausts the budget counter rather than allocating a large working set; storage is 1 MiB.

make -C dm/gfx/tests GAME=0400486024DEC000 check_t_pool_seen_replace passes 38/38 with each encoder flag setting, and 36/36 with DM_NVN_POOL_SEEN_KEEP=0, under Metal validation on M4 Max / macOS 27.2. These are direct-backend configurations, not independent replay-worker concurrency stress. C ratchet: no new findings. The earlier unmodified-clearing control in our integrated tree failed six replacement checks. No game assets are required or included.

This is test coverage offered for this existing fix; no duplicate production PR. Happy for it to be folded into your work.

[sleepyeyedjoe]

Thanks, this is a good addition. It checks the replacement's GPU pixels, which t_pool_chunks does not.

It is now in this PR as d07b5a0, with you as its author. Your commit's author was set to another name and address, so I used the noreply address from your Co-authored-by line.

Rerun here on an M4 Pro with macOS 27.0.1:

• 38/38 with each encoder setting;
• 36/36 with DM_NVN_POOL_SEEN_KEEP=0.

Control: against nvn_mtl.m from before the fix, it fails 6 of 38, the six replacement checks.

Thanks also for the play report.

— Claude (AI agent)

[seedds]

Landed on main as 6d9edb0, with you and akratch credited as co-authors. Thank you both: the trace, the A/B runs and the GPU-pixel test made this easy to check.

One change from the PR. The read mark now belongs to the ID. It stays while the ID holds any texture and is cleared only when the ID is emptied (if (!t) pool_seen_clear(id_)).

• The PR kept it only when the ID "held a made texture" (retired || view). But retired says the game finalized the old texture, not that its Metal texture was ever made.
• That condition also left out two cases where shaders still read the ID:
  • a read ID whose texture was still waiting for the read budget;
  • an ID whose memory pool was finalized while its texture was live.
• Unwritten render targets still stay the dummy through pool_unwritten_target, which is what kept transient targets from being made ahead.
• DM_NVN_POOL_SEEN_KEEP is gone. A switch that brings the bug back isn't worth keeping.

Tests. t_pool_seen_replace has one more case: the waiting read ID, whose replacement keeps the mark and is made in the first table.

• t_pool_seen_replace: 44/44 with each encoder setting, and 7 failures against the old nvn_mtl.m.
• t_pool_chunks: 151/151.

Not run. No game ran on this form. Only pool-table games reach it, and none of the local builds has libraries on the current chain. Your 118 s Ocarina replays are the game evidence. If you can, a short session on main around the Castle Town wall would confirm it.

The single dark frame at a texture's first read is still #1969, open, and #2075 is still to be reviewed.