[FifteenPen]

What and why

In The Legend of Zelda: Ocarina of Time (0400486024DEC000, v131072), the dark rock above the cave arch at Death Mountain Trail's cave entrance shows short screen-aligned light-blue dashes, the sky behind it, changing from frame to frame and staying on the same surfaces as the camera moves. A player also reported blocks on Death Mountain Trail's cliffs on an iPhone.

Per-pass snapshots (DM_NVN_TEXDUMP with DM_NVN_TEXSNAP, taken on a tree where the marks were larger blocks) show the rock drawn whole, then a later full-screen pass painting the marks over it; a pass dump of main's build shows the same draws in the same pass with the same bindings. That pass, 25a8adc977ff813d, samples the scene's depth attachment (1536x864 Depth32Float) through a texture slot and writes the same attachment (depth test LEQUAL, depth writes on); five decal draws after it do the same. On the console each fragment reads the depth stored before the draw. On Apple's GPUs a depth attachment sampled by the pass that renders into it reads whole compressed blocks of undefined content, so the shader's comparison against the sample fails or passes block by block.

fb_prepare marks the depth attachment as read for such a binding and ends the pass before the next draw that writes depth (the depth half of the snapshot rule), which cannot help a single draw that does both. It is the case PR #1430's assumption leaves out (Pool shaders taken as depth readers): a shader that reads the depth it writes.

The change, fb_depth_snap in nvn_mtl.m, called by fb_prepare, for every game:

• A draw that writes depth or stencil and samples its own depth attachment through a texture slot ends the open pass; the attachment's level and layer are copied into a snapshot (fb_snap, the colour snapshots' cache), and the draw's binding reads the copy.
• The copy is reused, without ending the pass, until the game's next barrier, as the colour snapshots are: NVN makes rendering visible to texture reads only through a barrier. At the cave entrance the game issues no barrier between the six draws; a copy for each and a copy reused gave the same picture.
• Only a single-level 2D view of the attachment's level and layer, bound in a texture slot, is copied. Reads through pools, TEXU handles or dynamic tables are left as they were, and so is a depth-only pass (fb_prepare returns early without a colour attachment, as for the colour rule; noted in the entry).
• DM_NVN_FB_DSNAP=0 reads the attachment directly, as before. The first copy logs same-pass depth sampling: copy #1.

#1866 is complementary: it ends the pass before a draw that samples depth an earlier draw of the pass wrote, and leaves alone a draw that writes depth itself. Both touch the same line in fb_prepare, so whichever lands second needs a one-line rebase.

Docs: a new reference entry, Depth sampled by the draw that writes it, the switch's row in docs/env_switches.tsv, and a line under the game note's "Found on this game".

Checked

• Tests, on this branch (main 7a7acfe + this change), Apple silicon, Metal debug layer:
  • make -C dm/gfx/tests GAME=0400486024DEC000 check_t_feedback: 218 checks, 0 failed. The new depth_snap_case covers a copy for a draw that writes depth and samples it (pass ended), reuse by the next such draw without ending the pass, a fresh copy after a game barrier, a direct read by a draw that leaves depth alone, the switch off, and the copy's content. In one earlier run the existing timestamp check "two reports in one command buffer read two times" failed; it is flaky on unchanged main too (1 failure in 4 runs of d8b2b64 here; A draw that samples the depth attachment its render pass already wrote ends the pass first (Red Dead Redemption's sky blocks) #1866 reports 2 in 6), and the next four runs passed.
  • make -C dm/gfx/tests GAME=0400486024DEC000 run: every test passes.
  • python3 -m unittest dm/tools/tests/test_docs.py dm/tools/tests/test_env_switches.py, python3 dm/tools/docs_symptoms.py.
  • dm/tools/lint_c.py tidy (LLVM 23.1.4) on the changed files: 0 file/check pairs above the baseline.
• Games run: The Legend of Zelda: Ocarina of Time (0400486024DEC000, v131072), a player's save at Death Mountain Trail's cave entrance.

  • In play, on main d8b2b64's Mac app (docked, in a window): the light-blue dashes over the rock above the arch. With this change's host in the same app: gone. That app also carried The game's compute dispatches with no game barrier between them run side by side (profile key dispatch_overlap, on for Ocarina of Time): Kokiri Forest GPU p50 15.63 → 14.76 ms #1901 and Ocarina of Time takes the launcher's Render scale: the 3D views at that fraction of the game's own size, the dynamic resolution held at its top level (Kokiri Forest docked at 0.75: GPU p50 15.77 → 14.31 ms, 60 fps held) #1903, which do not touch this path. Headless captures of the spot at 1440x810 and 1536x864 did not show the dashes, so this check is by eye.

  • Cost, this change's host on a --platform mac build of main d8b2b64, scripts/bench.py headless, docked, 45 s standing at the cave entrance, every pipeline from a warmed archive, two runs a side, same binary:

    	fps	frame p50 / p99	GPU p50
    default	60	16.665 / 16.855 ms	12.17 ms (12.11–12.23)
    DM_NVN_FB_DSNAP=0	60	16.67 / 16.86 ms	12.225 ms (12.17–12.28)

    1,000 copies and 3,611–4,696 reuses by frame 3,600–3,800: no measurable cost.

• Devices and OS: Apple M4 Pro (20-core GPU, 24 GB), macOS 27.2.
• regress.py impact: every NVN game, through nvn_mtl.m (Breath of the Wild, Pokémon Scarlet and Tears of the Kingdom have usage manifests). The rule acts only on a draw that writes depth and samples its own depth attachment through a texture slot, and logs its first copy. regress.py check was not run: of this Mac's NVN games only Mario Kart World has a smoke route, and none has a build for the current chain.
• Not checked: iOS (the player's report is the same symptom), other games, depth-only passes (not covered, see above).

Docs

• The finding is in its game note or its docs/reference/<subsystem>.md entry, and python3 dm/tools/docs_symptoms.py was run (the symptom index)
• A chain tool changed: not applicable (host only)
• No game files, keys or data extracted from a game in the change or the attachments

[akratch]

Independent test coverage from an M4 Max, macOS 27.2 / Xcode 27.2. The submitted RGBA stand-in is useful for substitution and reuse, but cannot exercise an actual depth format or the depth attachment's store/copy path.

I added a second case that clears a private Depth32Float attachment to 0.375 through the production render-pass path, calls fb_prepare, checks that the replacement is a distinct depth snapshot, and reads back all 16 floats with Metal validation enabled. It also checks allocation and submission completion. The existing RGBA/reuse/off-switch cases remain unchanged. On our OOT integration based on 7238bfd18c86, all 225 feedback checks pass, and the full Metal graphics/host suites and lint ratchets pass. This is integration-level synthetic GPU validation; the newly rebuilt game's long-session behavior and other games/iOS remain unchecked.

The test-only diff below is against this PR's a671ec7674a1 test file. No game data or shader-chain change is involved.

Additional real-depth regression

diff --git a/dm/gfx/tests/t_feedback.m b/dm/gfx/tests/t_feedback.m
index 5b151b8a..215ec54f 100644
--- a/dm/gfx/tests/t_feedback.m
+++ b/dm/gfx/tests/t_feedback.m
@@ -597,6 +597,43 @@ static void depth_snap_case(NvProg *pr) {
     mtl_tex_release(&output); mtl_tex_release(&depth);
     printf("depth copy: %s\n", before == failed ? "PASS" : "FAIL");
 }
+// Exercise the depth snapshot with an actual private Depth32Float attachment.
+// The RGBA fixture above checks substitution and reuse; it cannot catch a depth
+// format, render-pass store or depth-to-buffer copy error.
+static void real_depth_snap_case(NvProg *pr) {
+    tex_t colour, depth;
+    target(&colour, 99930);
+    depth = (tex_t){.magic=MAGIC('T','E','X',0), .serial=99931};
+    depth.d = (nvn_texdesc){.target=NVN_TEXTURE_TARGET_2D, .format=NVN_FORMAT_DEPTH32F,
+        .width=4, .height=4, .depth=1, .levels=1, .samples=1};
+    id<MTLTexture> dt = [g_dev newTextureWithDescriptor:tex_desc(&depth, 0)];
+    CHECK(dt != nil, "real depth attachment allocates");
+    if (!dt) { mtl_tex_release(&colour); return; }
+    res_add(dt); mtl_tex_init(&depth); serial_put(depth.serial, dt);
+    mtl_reg_tex(653, &depth, NULL);
+    id<MTLBuffer> result = [g_dev newBufferWithLength:1024 options:MTLResourceStorageModeShared];
+    CHECK(result != nil, "real depth readback allocates");
+    if (!result) { mtl_tex_release(&colour); mtl_tex_release(&depth); return; }
+    res_add(result);
+    state_reset(); memset(&R, 0, sizeof R); mtl_sub_begin();
+    R.has_rt = 1; R.rt.n = 1; R.rt.color[0] = &colour; R.rt.depth = &depth;
+    S.ds.dt = S.ds.dw = 1; S.tex[1][0] = 653; pr->sh[1]->rf.b[0].reg = 0;
+    R.clear_d = 1; R.cd = 0.375;
+    clear(MTLClearColorMake(0, 0, 0, 1));
+    fb_prepare(pr);
+    id<MTLTexture> snap = g_fb_n == 1 ? g_fb_use[0] : nil;
+    CHECK(snap && snap != dt && snap.pixelFormat == MTLPixelFormatDepth32Float,
+          "real depth feedback substitutes a Depth32Float snapshot");
+    if (snap) { blit_barrier(); readback(snap, result, 0); }
+    R.rt.depth = NULL; S.ds.dt = S.ds.dw = 0; S.tex[1][0] = 0; rp_end();
+    CHECK(mtl_wait(mtl_sub_commit(), 5000000000ull) && !mtl_last_commit_error(),
+          "real depth copy and readback complete under Metal validation");
+    int valid = snap != nil;
+    for (int y = 0; y < 4; y++) for (int x = 0; x < 4; x++)
+        valid &= *(const float *)((const uint8_t *)result.contents + y * 256 + x * 4) == 0.375f;
+    CHECK(valid, "every real depth sample retains the completed attachment clear");
+    mtl_tex_release(&colour); mtl_tex_release(&depth);
+}
 int main(int argc, char **argv) { @autoreleasepool {
     setenv("DM_NVN_TBDR", "0", 1); setenv("DM_NVN_GPU_TS", "segment", 1);
     mtl_init(); NSError *error = nil;
@@ -623,6 +660,7 @@ int main(int argc, char **argv) { @autoreleasepool {
     for (int i = 0; i < 3; i++) slot_case(pr, pipeline, slots[i], i);
     reuse_case(pr);
     depth_snap_case(pr);
+    real_depth_snap_case(pr);
     shape_case();
     mip_chain_case(pr);
     fs->fn = [lib newFunctionWithName:@"mask"];

[seedds]

Landed in 8190693, folded together with #1866 into one depth rule (fb_depth_rule): a draw that writes depth and samples it reads your copy (fb_depth_snap, unchanged apart from the RED key), and a draw that samples depth an earlier draw of its pass wrote ends the pass first (#1866). The rule now also runs in depth-only passes, so the limit you noted is gone, and one switch, DM_NVN_FB_DEPTH, replaces DM_NVN_FB_DSNAP. akratch's real-depth test is in, extended to Depth32Float_Stencil8 and a depth-only pass. regress on Octopath Traveler II, which takes the copy on its Depth32Float_Stencil8 depth: PASS, no new red line, the same frame times. You are credited as co-author. Thanks for the careful diagnosis and measurements.