[moretti]

Split out of #930 (4 of 4). This one has two commits. The display-link commit is built on the MetalFX one (both change the present path in nvn_mtl.m), so they go together.

Summary

1. MetalFX scales the picture at the snapshot. The MetalFX scaler ran on the game's queue at each display-link tick, between or right after the frame's segments, and cost about 2.6 ms of every frame. With present snapshots it now runs in the snapshot's command buffer, right after the frame's last segment, and the present only draws the result 1:1.

 snap_take (after the frame's last segment)
   copy the game's texture into the ring slot
+  MetalFX: scale the presented rectangle into the slot's `up` texture
 present_now (display-link tick, game's queue)
-  MetalFX scaler -> drawable
+  draw `up` 1:1 (any mismatch: the old path for that frame)

On by default on the Mac and off on iOS, where it hasn't been measured (DM_PRESENT_FX_AT_SNAP=1 turns it on). DM_PRESENT_FX_AT_SNAP=0 restores the old placement, and ab compares the two. @present_gpu_ms and @snap_gpu_ms give each command buffer's GPU time.

2. Pacing leaves the display link when the screen shifts under it. At some point in a fullscreen session on a ProMotion Mac, macOS starts showing every frame 1/240 s after the display link's target. From then on the link calls back a tick late about every 12 frames (56 fps). Presenting without the link (mode 0) holds 60.

each presented frame
  late = presentedTime - link target
  if 3/4 of 120 presents were >= 2 ms late          # the 1/240 s shift
     and fullscreen, variable-refresh screen, 60 fps game, pacing mode 1 (default)
       request: leave the link
each frame (link_sync, the game's present thread)
  if requested: pacing mode 1 -> 0 and invalidate the link, in one step
  if those conditions stop holding: back to the link

Also in this commit: @link_* timing rows for the link callback, and a hold fix. A 60 fps frame on the 120 Hz link (DM_PRESENT_LINK=2) is now held for two ticks; before, the game ran at 87 fps and 1.16× speed there. DM_PRESENT_RESYNC=0 keeps the link.

Related: #603 (Mario Kart 8 Deluxe: DM_PRESENT_LINK=0 removes the same late presents on an M3 Max), #347 / #348, #822.

Evidence

Breath of the Wild 1.9.0, MacBook Pro M5 Pro, macOS 27.2, built-in ProMotion screen, fullscreen.

• MetalFX. Before: the present cost 2.58–2.66 ms of GPU time on the game's queue (48–56 fps in busy scenes).
  After: 0.34–0.52 ms, measured in the same run with the placement switched every 30 s.

• Display link. The shift started at 87, 251, 342 and 355 s in four sessions.

  Run	Pacing	Before the shift	After the shift
  7	60 Hz link	60.00 fps	56 fps
  8	120 Hz link, latency 1	60.00 fps	58.63 fps
  10	no link (mode 0)	60.03 fps for 15 min, game time 1.000
  11	this PR, no settings	60 fps	60 fps for the rest of a 27-minute session

  In run 11 the host switched about 2 s after the shift, with no freeze. Timing rows on 200 late frames: our callback ran 0.16 ms (max 0.5) with no waits, and the link thread sat idle 20.7 ms before each late callback instead of 8.33 ms. So the lateness comes from macOS, not from our code.

• Tests: t_link_ticks 48, t_present_rescue --metal 86, check_t_present_snap 23 checks.

• Builds and tests on its own on current main: host and CPU gfx tests, sanitizers, tool tests, clang-tidy and ruff/pyright pass locally.

Merge Danger

Door: two-way. DM_PRESENT_FX_AT_SNAP=0 and DM_PRESENT_RESYNC=0 turn each part off.

Blast Radius: Mac presentation.

• Leaving the link happens only in fullscreen on variable-refresh screens, and only after the shift is seen. Windows, fixed-rate screens and DM_PRESENT_LINK=2 keep the current behaviour.
• When the canvas changes (a resize, fullscreen), remaking the scaler can block the game's present thread once, for up to 200 ms.
• iOS gets only the hold fix, and only with DM_PRESENT_LINK=2.
• Not checked yet: external monitors, other games, and why macOS shifts the screen at all (open in docs/reference/frame-rate.md).

regress.py impact: Breath of the Wild, Pokémon Scarlet and Tears of the Kingdom are reached, and Hades through the present rule. None of them is on this machine, so regress.py check --games was not run.

Update: rebased on main, and the shift at 30 fps

This branch is rebased on today's main. The conflicts with the probe-ramp change (now on main) are resolved, so queued and fxsnap both run in t_present_snap.

A new commit makes pacing leave the shifted display link at 30 fps too. Before, the leave condition required mtl_fps_target() == 60. Donkey Kong Bananza shifted during an interval-2 scene on the 30 Hz link and showed 33 and 58 ms frames, 26-27 fps for 33 s. Mode 0 now presents each frame for its period at 60 and at 30 fps alike, and a change of rate no longer brings pacing back to the link.

• t_present_rescue: the hand-off now runs at 60 and at 30 fps. Without the fix 6 checks fail; with it, 100 pass.
• t_present_snap: 166 checks pass in both encode modes, with Metal validation.

[sleepyeyedjoe]

Independent data point for the display-link shift, on another game and chip: Ocarina of Time (0400486024DEC000 v131072), MacBook Pro M4 Pro (Mac16,8), built-in ProMotion screen, macOS 27.0.1, fullscreen (display link: frame latency 2 (fullscreen, variable refresh)), present_snap 1. Host: main 1794a35 with #1245, #1707, #1742 and #1752.

In a 38-minute session, long stretches had every 11th frame at 25 ms (three 120 Hz ticks), frame p95 about 24.7 ms and 27–30 frames dropped per 300 on screen: about 56 fps. During those stretches the CPU was near idle (106–148 % of one core, CPU energy 1.5–3 W) and GPU p50 was 9–12 ms, so as you describe, the lateness isn't ours. The stretches came and went through the session.

Same build	Session	Dropped on screen
ProMotion, default pacing	38 min	27–30 per 300 in the stretches
Display fixed at 60 Hz in System Settings (frame latency 1, fixed refresh)	about 2 min (8,100 frames)	62 in all, 0–12 per 300
ProMotion with DM_PRESENT_LINK=0	about 3 min (10,200 frames)	16 in all, 0–4 per 300

The two short sessions include area loads. I'll add a longer DM_PRESENT_LINK=0 session. I haven't run this PR itself; mode 0 is the state it switches to.