[The-Inceptions]

What and why

On a MacBook Pro's ProMotion screen, a 60 fps game in fullscreen ran at 40 fps with its GPU at 10 ms of the 16.7 ms budget. In a window the same route held a locked 60.

The cause shows in the DM_NVN_TSV rows:

• Every present is late: with the 60 Hz display link at frame latency 2 (the variable-refresh fullscreen workaround from Mac: on a ProMotion built-in display the frame step drops to 30 / 20 fps on frames that are not expensive; at a fixed 60 Hz it does not #347), the system showed every present one 120 Hz refresh after the link's target (@pres_at_ms − @link_target_ms = 8.33 ms on every frame).
• Every other tick is skipped: the link then skipped its next tick after every second present. @link_gap_ms ran 16.7, 33.3, 16.7, 33.3 ms, which is 40 callbacks a second.
• The game follows the link: the host paces the game by the link's ticks, so the game ran at 40 fps. Frames alternated 16.7 and 33.3 ms, and each on-screen line counted half its frames as held long.
• The title screen is the same: 40 fps in fullscreen.
• Lower latency is worse: at latency 1 (DM_PRESENT_LATENCY=1) the misses of Mac: on a ProMotion built-in display the frame step drops to 30 / 20 fps on frames that are not expensive; at a fixed 60 Hz it does not #347 came back and the frame step went to 4 vsyncs (15 fps).

The change, link_vrr_120 in nvn_mtl.m:

• What it does: at 60 fps in fullscreen on a variable-refresh screen whose rate is a multiple of 120 Hz, link_sync runs the existing 120 Hz link of DM_PRESENT_LINK=2 (a frame every other tick) instead of the 60 Hz link. Frame latency stays at 2.
• How it paces: the acquire waits two ticks per vsync, and the vsync event follows every other tick. A frame that misses its tick goes up on the next 120 Hz refresh instead of a whole 60 Hz period later.
• Unchanged: a window, a fixed-rate screen, a screen at another rate, a 30 fps target (the 30 Hz link), and an explicit DM_PRESENT_LINK all keep their link. DM_PRESENT_LINK=1 keeps the 60 Hz link in fullscreen.
• Live switching: the link follows fullscreen in and out, as the latency policy already does. It logs display link: 120 Hz in fullscreen on a variable-refresh screen … when it switches.

Docs:

• New entry: docs/reference/frame-rate.md, The 60 Hz link at 40 fps in fullscreen on a ProMotion screen.
• A "Later" line on Frame latency 2 for the display link in fullscreen.
• The DM_PRESENT_LINK row in docs/env_switches.tsv.
• Ocarina of Time's note: its frame rate on this Mac, and a Found on this game line.

Checked

• Tests:

  • make -C dm/gfx/tests GAME=0400486024DEC000 check_t_present_rescue (with --metal, MTL_DEBUG_LAYER=1): 100 checks, 0 failed. This includes a new vrr120 group:
    • window vs. fullscreen
    • fixed-rate screens, 144 Hz, unknown and 240 Hz screens
    • DM_PRESENT_LINK=1
    • a 30 fps target
    • leaving fullscreen, and DM_PRESENT_LINK=2 in a window
  • make -C dm/gfx/tests GAME=0400486024DEC000 run, on this change before its rebase onto 7974118: 148 result lines, 72,183 checks, 0 failed, and 30 Python tests OK.
    • It needs Python 3.12 or newer first on PATH. The system Python 3.9 stops check_t_alpha at dmsh_side.py's str | None, which is unrelated to this change.
    • After the rebase, check_t_present_rescue ran again (100 checks, 0 failed) and the host rebuilt.
  • python3 -m unittest dm/tools/tests/test_docs.py: 11 tests OK. python3 dm/tools/docs_symptoms.py was run, and its output is unchanged after the rebase.

• Game run: The Legend of Zelda: Ocarina of Time (Switch 2), 0400486024DEC000, v131072, full shader library of chain dedc9391c30b, the bundled pipeline archive. scripts/bench.py on the kokiri-deck route (from a deck autosave; one extra Load press for a save list with two autosaves), with host= variants of main (7a7acfe) and this branch, two runs each:

  variant	fps	frame p50	frame p95	frame p99	frames > 1.5 vsyncs	GPU p50
  main, fullscreen	39.7 (39.6–39.8)	33.19	33.46	33.53	914	10.16
  this change, fullscreen	59.2 (58.8–59.6)	16.66	17.98	25.27	62	9.96
  main, window	59.9 (59.8–60.0)	16.67	16.81	18.14	4.5	10.19
  this change, window	59.95 (59.9–60.0)	16.66	16.79	16.97	1.5	10.19

  • The title screen in fullscreen on main:
    • 40.5 fps on the 60 Hz link at latency 2
    • 15 fps at latency 1
    • 59.3 fps with DM_PRESENT_LINK=0 (p99 25.2 ms)
    • 59.7 fps with DM_PRESENT_LINK=2 (p99 19.2 ms)
  • MetalFX present upscaling in fullscreen on the 120 Hz link: 59.4–59.7 fps, with no measurable GPU cost.
  • What remains on the 120 Hz link: the system still shows each present one refresh after its target, which is harmless. About 2% of the link's callbacks come two refreshes apart, so about 2% of frames stay up 25 ms. At frame latency 1 the 120 Hz link did a little worse (59.3 fps, frame p99 29.2 ms, 48 frames over 1.5 vsyncs, against 59.55 fps, 25.2 ms and 35 at latency 2, two runs each), so frame latency stays 2.

• For comparison, a fixed 60 Hz screen: with the screen held at its fixed 60 Hz mode for one app (as front_screen_match switches a 144 Hz screen), fullscreen held 60.0 fps, frame p99 16.9 ms, with 2 frames over 1.5 vsyncs in two runs. That was the 60 Hz link at latency 1, "fixed refresh". The GPU took 14.0 ms against 10.0, at the lower clock the system chose. Switching variable-refresh screens to their 60 Hz mode in fullscreen would remove the last 25 ms frames, but it changes the whole screen's mode, so it's only noted in the reference entry (second commit). Say if you'd rather go that way.

• Devices and OS: MacBook Pro 16-inch, M5 Pro (20-core GPU), 24 GB, macOS 27.2, built-in ProMotion screen.

• regress.py: this Mac has only this one game built, and its profile has no smoke.tsv, so regress.py check has nothing to boot. regress.py impact main..HEAD names Breath of the Wild, Pokémon Scarlet and Tears of the Kingdom through the present path (link_sync runs on every present). None of them is built on this Mac, so they're unchecked. The change is limited to Mac fullscreen on variable-refresh screens at multiples of 120 Hz. iOS doesn't change, because front_fullscreen is 0 there.

• Not checked:

  • external variable-refresh screens
  • other ProMotion Macs and macOS versions (the M4 Pro and M5 Max of Mac: on a ProMotion built-in display the frame step drops to 30 / 20 fps on frames that are not expensive; at a fixed 60 Hz it does not #347 held their frame rate at latency 2 on the 60 Hz link)
  • input latency against the 60 Hz link
  • other games

Docs

• The finding is in docs/reference/frame-rate.md and in the game note, and python3 dm/tools/docs_symptoms.py was run (the symptom index)
• No chain tool changed
• No game files, keys or data extracted from a game in the change or the attachments

🤖 Generated with Claude Code

[seedds]

Landed as a2cfd40, with you credited as co-author. Thank you for the diagnosis and the measurements.

One change from your version: your fixed 60 Hz measurement (60.0 fps, frame p99 16.9 ms, 2 frames over 1.5 vsyncs, latency 1) was clearly better than the 120 Hz link (59.2 fps, p99 25.3 ms, 62 frames). The host also already switches the screen mode in fullscreen, for this app only, on 144 Hz screens (front_screen_match). So the landed version does the same for a variable-refresh screen in fullscreen: it switches to a fixed-rate mode of the same size at a multiple of the game's rate. That means 120 → 60 Hz on a ProMotion screen at 60 and 30 fps, then the 60 Hz link at latency 1. Your link_vrr_120 is kept as the fallback for a variable-refresh screen that keeps its mode (no fixed mode at a multiple, or DM_SCREEN_MATCH=0). link_sync now asks the screen for the game's rate (60) rather than the link's, or the switch would never be asked for.

The host's own switch hasn't run on a ProMotion screen: the only screen here is a fixed 120 Hz external one, where the code takes main's path. Could you rerun bench.py on kokiri-deck in fullscreen on your M5 Pro with current main? The log should show front end: variable-refresh screen at 120 Hz switched to fixed 60 Hz for 60 fps in fullscreen and display link: frame latency 1 (fullscreen, fixed refresh), with about 60.0 fps. It should also show the screen going back to 120 Hz when you leave fullscreen. If it doesn't switch, the log line says why, and the 120 Hz link takes over.

[The-Inceptions]

The lint-c failure comes from main, not from this change.

• The finding: dm/gfx/tests/t_pso_archive.m: clang-analyzer-nullability.NullablePassedToNonnull: 3 findings, the baseline has 2. Two other open pull requests fail lint-c with the same line (run, run).
• Where it came from: I ran clang-tidy from LLVM 23.1.4 (the release CI downloads) on t_pso_archive.m and bisected over main.
  • d8b2b64 has 2 findings.
  • The first commit with 3 is 4a81561 (PR Timer flushes wait during any prewarm, so the start after a cold start does not compact (Ocarina of Time 762 s → 3.3 s) #1879). It added the --cold-quit-seed marker write at line 544, where the analyzer takes @(argv[2]) as nullable.
  • Main at 1d37720 still has 3.
• A fix: argv[2] is the temporary folder test_pso_archive.py makes, so this is a false positive. A NOLINT with its reason on that line:

  if (quit) [arch_compact_stamp() writeToFile:[@(argv[2]) stringByAppendingPathComponent:@"compacting"] atomically:YES encoding:NSUTF8StringEncoding error:nil];   // NOLINT(clang-analyzer-nullability.NullablePassedToNonnull): argv[2] is the temporary folder test_pso_archive.py makes, a UTF-8 path, so @(argv[2]) is never nil

  With that line, lint_c.py tidy --against origin/main passes:
  • on main: 223 findings, the baseline's 223, with 0 file/check pairs above or below it
  • on main merged with this branch: the same result

The other checks here are still queued.

[The-Inceptions]

I reran it on the M5 Pro's built-in ProMotion screen. The switch works, and fullscreen holds 60.0.

Host: a2cfd40's change applied to 7974118, the base of this PR. Main's chain has moved since (26062f9 and e121931, now d7576061facd), and this Mac's shader library is at dedc9391c30b, so a host built from main itself would have needed a full library rebuild first. Say if you'd like it repeated on main after that rebuild.

kokiri-deck in fullscreen, two runs:

	fps	frame p50	p95	p99	max	frames > 1.5 vsyncs	dropped	GPU p50
a2cfd40	60.0 (60.0–60.0)	16.66	16.78	16.87	28.8	1 (1–1)	0.5 (0–1)	14.05

Both runs logged:

display link: 120 Hz in fullscreen on a variable-refresh screen, a frame every other tick (DM_PRESENT_LINK=1 keeps 60 Hz) (frame 0)
display link: frame latency 2 (fullscreen, variable refresh)
front end: variable-refresh screen at 120 Hz switched to fixed 60 Hz for 60 fps in fullscreen (DM_SCREEN_MATCH=0 keeps it)
display link: 60 Hz again (window, fixed-rate screen or another frame rate) (frame 11)
display link: frame latency 1 (fullscreen, fixed refresh; frame 11)

After the runs, the screen was back in its 120 Hz mode.

Leaving fullscreen: a third run left fullscreen at 70 s, entered it again at 90 s and left it again at 110 s. The toggles came from a local test hook, a DM_CTL line that calls toggleFullScreen: on the main thread as ⌃⌘F does. It isn't meant for merging.

• Each exit: logged front end: screen back at 120 Hz. The window then ran at 60.0 on the 60 Hz link at latency 1.
• The re-entry: switched to fixed 60 Hz again and held 60.
• A brief link flip on exit: the screen goes back to 120 Hz before the window has left fullscreen. So for 2–3 frames, link_sync takes the 120 Hz link at latency 2 (frames 3241–3243 and 5326–5329), then logs 60 Hz again (window, …). That was harmless here.
• The present rescue: each mode change silenced the display link for 508–567 ms while active, so the present rescue took over each time (pacing mode 0). Its retry doubled each time: 3, 6, then 12 s. The game was back at 60 fps while the 12 s rescue still ran.
• Without the switch: the same toggles with DM_SCREEN_MATCH=0 silenced the link for at most 282 ms, and no rescue started.

The cost of each toggle (one run each; fps on @pres_at_ms in 2.5 s bins):

toggle	with the switch	DM_SCREEN_MATCH=0
leave at 70 s	44.4 fps over the next 10 s, 56 frames over 25 ms, 60 again after ~5 s	49.2 fps, 60 frames, ~5 s
enter at 90 s	39.3 fps, 84 frames, ~7.5 s	49.0 fps, 67 frames, ~5 s
leave at 110 s	44.7 fps, 58 frames, ~5 s	48.5 fps, 64 frames, ~5 s

So entering fullscreen with the switch took about 2.5 s longer to settle. Between toggles, the fixed 60 Hz fullscreen had at most 2 frames over 25 ms, and the 120 Hz link had its usual few at 25.3 ms.

Same Mac as before: MacBook Pro 16-inch, M5 Pro (20-core GPU), macOS 27.2.

The lint-c note above still holds at a2cfd40. clang-tidy 23.1.4 finds 3 NullablePassedToNonnull in t_pso_archive.m, against the baseline's 2.

[lucasmartin042009-sudo]

Also on an M3 Pro, another game, two-player split screen: the switch runs, 30 → 58.8 fps.

Mario Kart World (0400C3F00006E000, v0), two-player split screen, Grand Prix 50cc, Mario Bros. Circuit, handheld mode (1080p render, output 1440p, no MetalFX / SMAA), host 7f50222 + the two code hunks of a2cfd40 applied (front_mac.m, nvn_mtl.m; same shader chain), on a 14-inch MacBook Pro M3 Pro (18 GB), macOS 27.2 (26B123), built-in 1512x982 @ 120 Hz ProMotion screen, on AC power.

• Before (7f50222, fullscreen on the built-in screen, same route): 30 fps, frame p50 33.3 ms, the GPU held at about 430 MHz by the system while 99 % busy. In a window, or fullscreen on an external fixed 60 Hz screen, the same route held 60 fps.
• With a2cfd40: the log shows front end: variable-refresh screen at 120 Hz switched to fixed 60 Hz for 60 fps in fullscreen (DM_SCREEN_MATCH=0 keeps it), then display link: frame latency 1 (fullscreen, fixed refresh); CGDisplayCopyDisplayMode on the built-in screen reads 60.00 Hz during the game and 120 Hz again after it quits. Race: 58.8 fps median over 13,200 frames, frame p50 / p95 17.0 / 19.9 ms, GPU p50 13.9 ms, the GPU clock at 1,000-1,230 MHz after a 40 s ramp (an IOReport sampler), 91 frames held too long of 13,200.
• The remaining slow windows (5 of the 44 race windows of 300 frames, p50 22-34 ms, GPU busy down to 67-75 %) came with the Mac paging (11.6 of 12 GB of swap in use, the host at a 9.5 GB footprint); not the display.

Note for others testing: the window opens on the screen that holds the key window, so with an external screen attached the game went fullscreen there first (fixed-rate path, nothing to see); the built-in screen was tested by starting in a window, moving it there and entering fullscreen.