[keanu-stitch8]

What

NVN clears every layer of the render target view that is bound (the whole texture when the view sets no layer range). The host folds a clear into the next Metal pass's load action, and a pass that is not layered (renderTargetArrayLength unset) clears only its one attached layer. Layers above the first of an array, cube or 3D target kept their old or zero content.

rp_begin_ex_ already clears an attachment that is larger than the pass in a pass of its own (Clears of attachments larger than the render pass, Bayonetta 2). This PR does the same for layers. A cleared attachment whose view covers more than one layer, in a pass that is not layered, is cleared in a pass of its own with renderTargetArrayLength set to the view's layers (att_layers), then loaded in the real pass. A view limited to some layers clears only those. Layered passes and single-layer targets are unchanged.

Found on

Little Nightmares (01002FC00412C000, 1.0.4, Unreal Engine 4, SDK 3.5.1, provisional profile):

• Each point light's one-pass cube shadow (geometry shader ffc21034b958840b, emitting every triangle into six faces) clears the 512x512 D32F_S8 cube in the pass that captures the vertex shader's output. That pass is not layered.
• Only face 0 (+X) was cleared. Faces 1-5 kept the zero depth tex_zero_fill gives a new texture, so every fragment of the layered pass failed the depth test there.
• The projection's comparison sampler then read those faces as fully shadowed. The lantern and the lighter lit only one side of the room, with straight edges at the face boundaries.
• With the fix, all six faces hold depth (0.986–0.999 against a light radius of 450), the static and final cubes differ only by the moving character, and the room is lit all around with Six's shadow on the floor.

Diagnostics (first commit)

DM_CTL texraw saved slice 0 only, which hid the bug (face 0 looked plausible). It now saves level 0 of every slice, one after another, with the slice count after the header's four fields when there is more than one. A single-slice file is unchanged.

Tests

• New t_clear_layers (production replay, MTL_DEBUG_LAYER=1) covers:
  • a depth clear of a cube with no view (all six faces) and through a one-face view (that face only);
  • colour clears of a 2D array with no view, from layer 1 on, and through a two-layer view;
  • a plain 2D target, which stays one layer.
• Without the fix, 4 of the 6 cases fail, exactly on the layers above the first. With it: 30 checks, 0 failed.
• make -C dm/gfx/tests GAME=010015100B514000 run: all pass (on the fork's tree, which carries this change).
• t_clear_ds, t_clear_tex, t_clear_layers and dm/tools/tests/test_docs.py pass on this branch.
• Regression harness: scripts/regress.py check --games was not run. This Mac has no NSP folders laid out for the harness (<name> [<id>] with <id>_build) for the other local games. The change only acts when a cleared attachment has more than one layer in a pass that is not layered, and the pass dump prints C … cleared in a pass of its own (… N layers …) whenever it does.

🤖 Generated with Claude Code

[seedds]

Landed on main as ffdf67de. Thank you, @keanu-stitch8, for the diagnosis, implementation and GPU coverage. Your clear implementation, texraw improvement and tests are retained, and you are credited as co-author.

This is good general graphics design: NVN clears the complete bound view, so the Metal load-action path must cover that view. High confidence in the original bug and fix; this is a generalized root-cause correction with no game-specific rule or renderer workaround.

The rebase onto #730 exposed one integration issue. A clear already completed in a standalone pass was still counted as a tile write in the following pass, retaining a stale store over shader image writes. Store tracking now uses the following pass's actual clear load action. The added literal GPU case failed four assertions before the correction and passes afterward.

Validation:

• Before rebase: full Metal graphics suite, LLVM 23 lint and all 11 documentation tests passed. Breath of the Wild's full 110-second route passed: 58.4 → 58.0 fps, p99 33.56 → 33.52 ms, matching screenshots and zero red diagnostics.
• After rebase: image-store GPU test 120/120, layered-clear GPU test 30/30, focused LLVM lint with no new findings, and all 11 documentation tests passed.
• Regression risk was moderate because this is a shared path with a narrow trigger. The impact report selected Breath of the Wild, Tears of the Kingdom and Pokemon Scarlet. The remaining game checks were stopped at the maintainer's request: Tears of the Kingdom's candidate paused after focus loss with all GPU fences completed, its foreground-controlled repeat was canceled, and Scarlet's runtime comparison was not completed. Those two games are not claimed as validated.
• The earlier runtime comparison used the documented Xcode 27.2 compiler override against the old compiler lock. Fresh main now pins Xcode 27.2. Validation notes and the completed BotW record are committed.

Closing after landing the reviewed change on main.