[dpadr]

What and why

Two diagnostic tools for measuring what a translation choice costs in one hot pixel shader, offline and then in game. Both are off by default; nothing changes for a player.

DM_NVN_SHADER_ALT=<dir> (host, nvn_mtl.m):

• A shader whose <key>_b.metallib is in that folder draws with that library instead of the game's. The library is a variant built the way dmsh_build.py builds the game's, with the same side libraries.
• How it works. The variant gets its own shader object and its own program twin (prog_alt), so its pipelines and archive entries are separate: pso_key holds the shader objects, and lib_name tags the library alt/<file>. Variant pipelines are never written to the prewarm lists or the user's record.
• Refusals. A variant whose side-library set (_bx, _bf, _bp, _bv), entry points or argument-buffer layout differ from the game's is refused with one [RED] line, and the key keeps the game's library.
• A/B. DM_NVN_SHADER_ALT_AB=ab with DM_AB=<frames> draws the variants only in the odd phases, so one run compares them with the game's library in the neighbouring phases. The [ab] line of each phase is read as for any other DM_AB switch.
• Switch unset: prog_get is prog_alt(prog_get_base(cp)), and prog_alt returns its argument after a dispatch_once check.

fsbench (dm/gfx/tools/fsbench/, a tool only):

• It times one translated fragment shader and source variants of it on a full-screen draw, rebuilt from a DM_NVN_PASSDUMP_ALL pass dump and DM_NVN_CBDUMP uniform dumps.
• For each variant it checks the output against the first library and prints Apple's compiler statistics (registers, spill, instruction mix).
• The source variants are regex transforms of the translated MSL: border emulation off (nobs), no NaN scrub of coordinates, read-only storage buffers through constant, the pool read mark off, and others.
• The scene format is in its README, because scenes are made from a game's dumps and stay out of the repository.

The method these tools were made for, used on Ocarina of Time (0400486024DEC000, v131072):

1. Map which shaders cover the picture: DM_NVN_HILITE stills.
2. Rank them by GPU time: DM_NVN_GPUPROF joined with DM_NVN_PASSDUMP.
3. Bench the top ones offline with fsbench.
4. Confirm in game with DM_NVN_SHADER_ALT and DM_AB.

The first result, on a MacBook Air M2 (16 GB):

• The four heaviest main-pass shaders were rebuilt without the border-emulation second sample. The unchanged source rebuilt to the image's libraries byte for byte, so the variant was the only difference.
• In-run, three runs of 20 phase pairs each: GPU p50 −0.49 / −1.06 / −0.85 ms, and frame mean −0.52 / −1.06 / −0.91 ms.
• This is the evidence posted on Unused border corrections are compiled out of pipelines that bind no sampler with a twin (function constant DMSH_BORDER_FC) #1929; that change, for every shader, has since landed as 511a0a2. The findings are in Ocarina of Time (0400486024DEC000): hot pixel shaders on Metal run at the 128-register cap; border emulation cost ~0.85 ms a frame on an M2 Air #2316.

The coverage and ranking scripts used for steps 1 and 2 are not in this PR: they are tied to one game's scripted route and saves.

Checked

• Tests (job log in the work folder):
  • make -C dm/gfx/tests GAME=0400486024DEC000 check_t_shader_alt: the variant is drawn in its phases only; the twin is made once; archive tags; the pipeline key differs; nothing is recorded for the prewarm; a missing side library, a missing entry point, or no variant leaves the game's library.
  • check_t_pso_archive: OK. check_t_pso_bundle: 71 checks, 0 failed. check_t_pso_warm: 123 checks, 0 failed. check_t_nvn: 298 checks, 0 failed.
  • t_shader_alt: 15 checks, 0 failed (with the twin's reference count, with it and after it).
  • dmhost builds for 0400486024DEC000 with no warning on any line this branch changes.
  • python3 -m unittest dm/tools/tests/test_docs.py: OK.
  • dm/tools/env_switches.py --check reports only what it reports on main: 4 removed switches still quoted, DM_NVN_VCONV_KEEP without a row.
  • fsbench.py tool builds the binary on main, and fsbench.py compile compiles a fixture. The same source ran fsbench run and stats on five of Ocarina of Time's shaders (below).
• Games run, with title ID and version: Ocarina of Time 0400486024DEC000 v131072.
  • The switch was used on cut6 (chain cd098f1631bd): 4 runs of 12,000 frames on a scripted route, the variants loaded in every run, and no [RED] line from the switch.
  • fsbench was used on five of its shaders, with every variant bit-exact. One scene bug was found on the way and fixed: the dump's target= is Metal's numbering, so a 2D array was read as a cube, and compare samplers had no compare function.
  • The branch on current main was compiled and tested, not played.
• Devices and OS: MacBook Air M2 (10-core GPU, 16 GB), macOS 27.0.
• Not run: scripts/regress.py check --games. Both switches are off by default, and with them unset the only change on the draw path is the prog_alt check, which returns at once. Not checked on an iPhone (it is a Mac diagnostic, but nothing in it is Mac-only).

Docs

• docs/env_switches.tsv: rows for DM_NVN_SHADER_ALT and DM_NVN_SHADER_ALT_AB.
• docs/development.md, GPU measurement: a paragraph on the in-run A/B of one shader, with a link to fsbench.
• dm/gfx/tools/fsbench/README.md: commands, inputs, the scene format, and how to read the numbers.
• No game files, keys or data extracted from a game in the change or the attachments
• A chain tool changed: not applicable (the chain is unchanged; fsbench only reads its flags)

🤖 Generated with Claude Code

[dpadr]

Four commits added (24b9391):

• fsbench:
  • compute and mesh modes;
  • cstats and mstats;
  • function-constant specialization (needed for libraries that declare constants, such as dm_border_off);
  • crun's multiset compare, so kernels whose outputs vary run to run (atomics) can still be checked.
• Two reference entries, both open findings, not chain rules:
  • uninitialized locals in translated MSL: a goto flag read before it's set, with zero-initialization proposed;
  • constant buffers that overflow the uniform registers.

Checked: t_shader_alt 22/22, t_pso_archive, t_nvn 298/298, test_docs, and the fsbench tool builds (M2 Air, macOS 27.0).