[FeReuss]

What and why

The translator's border colour corrections (the dm_bs twin samplers) are in every shader that samples, though a game binds a sampler with a twin to few draws: Ocarina of Time binds none. They cost registers and instructions in every pipeline; its 1080p material passes spilled 300-400 bytes a thread with them.

The chain now gives every stage and every kernel a bool function constant, dm_border_off (DMSH_BORDER_FC, index 216), and the host specializes a pipeline with it on when its draw or dispatch binds no twinned sampler (border_need): bd_off for the stages, cs_fn for the kernels, and the mesh and task pipelines' keys and descriptors (mtk_desc4, mtk_pso: k.border). The specialized function is a distinct identity (FnVariant), because Metal returns one MTLFunction per function content. pso_offline.py bakes the specialization into the app's pipeline archive (HOST_CONSTANTS), and cps_new looks up and captures a compute pipeline by that descriptor only for a function that declares dm_border_off; any other function with constants is built from fn_dev's specialization and not captured, as before (t_pso_bundle checks it). DM_NVN_BORDER_KEEP=1 keeps the corrections in every pipeline; =ab alternates the two in the DM_AB phases.

The picture does not change where no twinned sampler is bound (t_border covers both sides). It is a chain change: dmsh_chain.h is regenerated and every game's shaders are built again.

Rebased onto the native mesh pipeline prewarm and the mesh-without-task code that main took since (mtk_desc4, mtk_build, mtk_pso): the specialization is in the descriptor and the key there.

Checked

• Tests: dm/gfx/tests test_dmsh_border.py (10 tests, 1 skipped, OK) and dm/tools/tests test_pso_offline, test_nsp_chain, test_docs (48 + 28 tests OK); make -C dm/gfx/tests GAME=0400486024DEC000 check_t_... for t_border (107 checks), t_pso_bundle (69), t_pso_archive (222), t_pso_warm (123, MTLDevice and Metal 4), t_pso_depth_stencil (286 + 286), t_pso_stall (43), t_geometry (1,929), t_geometry_feedback (110), t_geometry_hazards (61), t_geometry_mesh (44), t_mesh_first_use (53), t_upscaler_mfx (91 + 12), t_feedback (203), t_pool_chunks (146): all 0 failed, on this branch; t_pso_skey OK. The host builds (make -C dm/host GAME=0400486024DEC000). The whole make -C dm/gfx/tests GAME=0400486024DEC000 run on the tree with every PR of the series: 150 suites, 72,812 checks, 0 failed; 525 read-back cases, 0 failed.
• Games run: Ocarina of Time 0400486024DEC000 v131072, the Hyrule Field view (still_shots route, the heaviest), 1920x1080 docked, 210 s, window, 60 fps cap, DM_NVN_BORDER_KEEP=ab with DM_AB=600 (phases of 600 frames, the first quarter of each left out), in one process: with the specialization (this PR) span p50 23.10 ms, frame p50 22.61 ms (43.9 fps); with the corrections kept in every pipeline 24.37 ms, 23.98 ms (41.7 fps): -1.27 ms of GPU span, -1.37 ms of frame, +2.2 fps. The kernels (the upscaler's among them) were about 0.3 ms of it. 0 [RED] lines. Measured on a tree built on main 7f502220 (the series), not on 7a7acfee: the specialization code is the same, the mesh/task parts were re-applied by hand on the new prewarm, and the shaders of this tree were not built.
• Devices and OS: MacBook Air M4 (10-core GPU, 16 GB, no fan), macOS 27.2.
• For a change to the shader chain: scripts/regress.py check --games is not run. Only Ocarina of Time is built on this Mac, and a chain rebuild of it needs about 10 GB of free disk (4 GB here). The other games that sample with a twinned sampler bound are where it matters, and they are unchecked; with no twinned sampler bound the pipeline is the same as before, with the correction code removed.

Front ends

None.

Docs

• The finding is in the game note (Shaders / Frame rate), docs/reference/rendering.md (the border corrections entry) and the symptom index (python3 dm/tools/docs_symptoms.py was run).
• A chain tool changed: dmsh_chain.py --header was run and dm/gfx/nvn/dmsh_chain.h is part of the change.
• No game files, keys or data extracted from a game in the change or the attachments

Series: what these PRs add up to

This PR is one of a set from one effort to make Ocarina of Time (0400486024DEC000 v131072) hold its frame rate on a MacBook Air M4. The set, and how its parts combine into the last measured result:

The result (the Hyrule Field view, the heaviest of the game: 1920x1080 docked, 60 fps cap, window, 120 s runs, M4 with 10 GPU cores, 16 GB, macOS 27.2):

Tree	fps	frame p50	GPU p50
main 7f502220 + #1304, fps_hold at its default	30.1	33.31 ms	27.56 ms
+ fps_hold off (#1927)	33.7	29.38 ms	27.28 ms
build 3: + #1833 with the M4 window fix, border-FC (#1929), the barrier set and cut_draws 128 below, and the PRs listed as "also in the tree"	40.2	24.48 ms	22.09 ms
+ enc_thread on (#1928)	41.6	23.46 ms	21.39 ms
+ native float add (#1930) = build 4	44.6	22.39 ms	20.45 ms

(The step from 33.7 to 40.2 changes the shader chain, so it has no in-process A/B; #1833 is most of it. Kokiri Forest, walking, is at 60 fps on build 4; the Hyrule view is the worst case.)

Each part switched in one process on build 4 (DM_AB, 210 s, 600-frame phases, frame p50 with the part active against without; the noise between phases is about 0.3 ms): border-FC (#1929) 22.61 vs 23.98 ms; the barrier set (FRAG_ORDER, PASS_OVERLAP and HEAP_RELAX alternating together) 22.41 vs 22.58 ms; CUT_IDLE 22.74 vs 22.85 ms; DISPATCH_CHAIN 22.32 vs 22.48 ms.

Which PRs make that tree:

Part	Where
fps_hold off	#1927
enc_thread on	#1928
border-FC	#1929
native float add	#1930
launcher's Render scale / GPU share (no frame-time effect)	#1931 (draft, on #1304)
M4 address window of shader_raw_direct (without it every raw store is dropped on an M4 and the foliage is not drawn: the 48-50 fps of a build without it are false)	the branch FeReuss:pr1833-m4-window, one commit on #1833's head (not yet offered on #1833 itself)
Base, other authors, open, in the measured tree	#1304 (tier 0), #1714 (gpu_ts_hz), #1833 (shader_raw_direct), #1720, #1377, #1840
Base, in the measured tree, already in main or withdrawn	#1844 (-fwrapv, now e4e5ff64), #1368 / #1708 (native mesh prewarm and mesh without task: main's own versions), #1707 (withdrawn)
Measured, not submitted (the net is within the noise): barrier set (FRAG_ORDER + PASS_OVERLAP + HEAP_RELAX), CUT_IDLE	branches pr/pass-overlap and pr/cut-idle in FeReuss/nxnative-oot
Not ported: dispatch chain (the same idea as #1901), cut_draws 128 (64 and 128 tie on this tree)

All of it was measured on main 7f502220 plus the above; these PRs are rebased on main 8d5d4f1b; the tool and docs tests that touch them were run again there (test_env_switches, test_docs, test_nsp_chain, and each PR's own), while the host build and the graphics suite are those of 7a7acfee, and none of it has been run in the game on the newer main (a shader rebuild of the new chain takes about an hour and 10 GB of disk). This PR is #1929.

🤖 Generated with Claude Code

[seedds]

Landed on main as 511a0a2, with you as co-author: the function constant dm_border_off (DMSH_BORDER_FC), the host's specialization by border_need and the offline archives' constants are yours. Changes on the way in:

• A draw now compares its stages' need with the bound pipeline's (prog_border): a sampler with a twin bound after the pipeline was picked kept the pipeline without the corrections.
• The transform-feedback capture pipeline was built with the unspecialized function; it goes through pso_build_dev with the key's flag.
• The proxy object standing in for a function is gone: pipeline builders take an explicit off flag from the draw's key (fn_off, fn4_of_b, fn_dev_b, cps_new_b), so descriptors hold only real Metal functions.

Measured here: Ocarina of Time on the forest deck, in-process A/B on an M6, GPU p50 10.66-10.88 ms without the corrections against 11.01-11.26 ms with them; compiled for the M1's GPU, 300 of its pixel shaders have 10% less code and 77 of them less per-thread scratch. Not run: Tears of the Kingdom (the one known game that binds a twin), an iPhone, an M1. Thank you.

[dpadr]

Independent measurements of this change on another game and device.

MacBook Air M2 (10-core GPU, 16 GB), macOS 27.0, The Legend of Zelda: Ocarina of Time 0400486024DEC000 v131072, handheld 1440x810, chain cd098f1631bd.

Where dm_bs costs. The game's three heaviest main-pass pixel shaders are 1e4d2630d24846d0, 19f99e925937b038 and bd75f2962d28d424. Their Metal compiler statistics (main0, RG11B10Float target):

shader	Switch 2 registers / instructions	Metal registers	spill	Metal instructions	texture instructions
1e4d2630	91 / 1,760	128 (cap)	256 B	3,112	29
19f99e92	90 / 1,704	128 (cap)	160 B	2,862	33
bd75f296	90 / 1,696	128 (cap)	144 B	2,839	33

The dm_bs sites are 11 of the 29 texture instructions in 1e4d2630 and 16 of the 33 in the other two. With the second sample removed, 1e4d2630 goes to 208 B of spill, 2,912 instructions and 18 texture instructions; it stays at 128 registers.

Why it costs with mask 0. The second sample is guarded by a uniform test of the mask, but a sample has no side effects, so the compiler if-converts it. Both samples always issue, and a select picks one. The guarded sample is paid on every pixel, whatever the mask, and it also holds registers and adds waits.

Offline, per shader. A full-screen 1440x810 pass of each shader alone, with the uniform blocks dumped from the game, the same chain flags, and 20 rounds; times are net of a null shader. Base against the second sample removed:

shader	base	without the second sample	change	output
1e4d2630d24846d0	6.87 ms	5.23 ms	−23.9 %	bit-exact
19f99e925937b038	4.72 ms	2.80 ms	−40.7 %	bit-exact
bd75f2962d28d424	4.68 ms	2.71 ms	−42.0 %	bit-exact
087ef21b3a72ad3a (foliage)	2.06 ms	1.41 ms	−31.6 %	bit-exact
9aa7f545bb5abcae (shadow resolve)	0.100 ms	0.079 ms	−20.9 %	bit-exact

In game. The libraries of those four shaders were replaced with copies built without the second sample. The rest of the build is otherwise identical: the unchanged source rebuilt to the image's own libraries byte for byte. A host switch (diagnostic only) drew them in alternate 240-frame phases of one run, against the original libraries in the neighbouring phases, over a scripted 12,000-frame route, with pipelines warmed beforehand. Three runs, each with 20 B phases compared against their two A neighbours (median, bootstrap 95 %):

run	GPU p50	frame mean
1	−0.49 ms [−0.67, −0.22]	−0.52 ms [−0.90, −0.38]
2	−1.06 ms [−1.15, −0.97]	−1.06 ms [−1.33, −0.86]
3	−0.85 ms [−0.95, −0.79]	−0.91 ms [−1.12, −0.75]

That is about 0.85 ms a frame from four shaders. Pass count and CPU submit work did not change.

No twinned sampler on these routes. The host logs a draw's border mask in its pass dump whenever a bit is set. Full-frame dumps of the route (frames 2400–2402) and of six places (49–50 dumped frames each, 10 camera directions) have no such line. This game's samplers use opaque white (1,1,1,1) or opaque black (0,0,0,1), which Metal provides itself, so the mask is 0 at every draw that was dumped and the second sample never changes a result.

🤖 Generated with Claude Code

[dpadr]

A whole-game measurement of this change, following the per-shader one above.

MacBook Air M2 (10-core GPU, 16 GB), macOS 27.0, The Legend of Zelda: Ocarina of Time 0400486024DEC000 v131072, handheld 1440x810. The build carries this change as it landed on main (511a0a2), on chain bf6035002b98.

Method. DM_AB=240 DM_NVN_BORDER_KEEP=ab: within one run, 240-frame phases alternate between this change (A) and every pipeline keeping its border corrections (B, as before the change). Pipelines were warmed beforehand. The route is scripted and runs to frame 12,000. There were three runs, and in each, 20 B phases are compared with their two A neighbours (median, bootstrap 95 %). CPU clocks were low in these runs (1.5–2.65 GHz), but each comparison is between neighbouring phases, so both sides ran at the same clock.

Without the change (B − A):

run	GPU p50	main pass (1440x810)	compute and copy	frame p50
1	+2.87 ms [2.81, 2.99]	+3.12 ms [2.92, 3.28]	+0.34 ms	+2.76 ms
2	+2.92 ms [2.74, 3.07]	+2.69 ms [2.52, 2.81]	+0.34 ms	+2.89 ms
3	+2.62 ms [1.43, 3.34]	+2.05 ms [1.29, 3.46]	+0.23 ms	+2.23 ms

On this route, the change saves about 2.8 ms of GPU time a frame on the M2, about 10 %, almost all of it in the main pass. CPU instructions a frame did not change.

Frame times, three runs pooled (each phase's first quarter dropped):

	frame p50	frame p95	frames over 33.4 ms
with the change	27.8 ms	35.7 ms	8.5 %
without	30.6 ms	37.3 ms	15.4 %