Skip to content

Mac: match the screen's refresh rate to the game's frame rate while it runs (144 Hz → 120 Hz) - #79

Closed
v0lumehi wants to merge 1 commit into
seedds:mainfrom
v0lumehi:screen-match
Closed

v0lumehi wants to merge 1 commit into
seedds:mainfrom
v0lumehi:screen-match

Conversation

@v0lumehi

Copy link
Copy Markdown
Contributor

On a 144 Hz screen, 60 fps can't be paced evenly. link_range's virtual ticks (from #27) keep the average at 60, but each frame still stays up two or three refreshes in turn (13.9 / 20.8 ms). Apple's Metal HUD shows the frame-interval line jumping between those two values. On a 120 Hz screen the same game's line is flat.

Change

  • link_sync tells the front end the link's rate: 60, 30, or 120 with DM_PRESENT_LINK=2 (front_screen_match).
  • When the screen's mode isn't a multiple of that rate, front_mac.m switches it to the mode of the same size with the highest rate that is, e.g. 144 → 120 Hz for 60 and 30 fps. This uses kCGConfigureForAppOnly, so macOS switches the screen back when the host quits, crashes included.
  • After the switch the link sets its range again for the new rate, so there are no virtual ticks anymore.
  • A window moved to another screen matches that screen too. A screen with no suitable mode keeps the virtual ticks as before.
  • DM_SCREEN_MATCH=0 keeps the screen's rate.

This is unlike the mode switch in #62, which only served BotW's variable step. This one applies to every game on a 144 / 165 Hz screen and is independent of #76 and #77.

Tested

Hades on a 144 Hz XB273U at 2560x1440 (M2 Max):

  • Log: screen at 144 Hz switched to 120 Hz for 60 fps, then present pacing mode -1 → 1 with no virtual ticks.
  • The HUD's frame-interval line is steady at 16.7 ms, where it jumped before.
  • After quitting, the screen is back at 144 Hz.

The 165 Hz case hasn't been run, but the mode choice is the same (165 → 120 or 60, whichever modes the screen offers).

…e rate switches to one that is while the game runs

60 fps on a 144 Hz screen cannot be paced evenly: the display link counts a tick on the refresh nearest each
1/60 s slot (link_range's virtual ticks), so frames stay up two and three refreshes in turn (13.9 / 20.8 ms) and
Apple's HUD shows the frame interval jumping between them. link_sync now tells the front end the link's rate
(60, 30, or 120 with DM_PRESENT_LINK=2; front_screen_match), and front_mac.m switches a screen whose mode is not a
multiple of it to the mode of the same size with the highest rate that is, with kCGConfigureForAppOnly, so macOS
switches it back when the host quits. The link then sets its range again for the new rate. A window moved to
another screen matches that screen too; a screen with no such mode keeps the virtual ticks. DM_SCREEN_MATCH=0
keeps the screen's rate.

Hades on a 144 Hz XB273U (2560x1440): switched to 120 Hz, the HUD's frame interval line steady at 16.7 ms where
it jumped before; 144 Hz again after quitting.
seedds added a commit that referenced this pull request Oct 23, 2026
…the game's frame rate switches to one that is (144 → 120 Hz), from PR #79

60 fps on a 144 Hz screen cannot be paced evenly: the display link counts a tick on the refresh nearest each 1/60 s
slot (link_range's virtual ticks), so frames stay up two and three refreshes in turn (13.9 / 20.8 ms) and Apple's HUD
shows the frame interval jumping between them. link_sync now tells the front end the link's rate (60, 30, or 120
with DM_PRESENT_LINK=2; front_screen_match), and in fullscreen front_mac.m switches a screen whose mode is not a
multiple of it to the mode of the same size with the highest rate that is, with kCGConfigureForAppOnly, so macOS
switches it back when the host quits; leaving fullscreen or that screen switches it back at once. A window keeps
the screen's rate and the virtual ticks: the switch changes the whole screen for every app and most external
screens go black for a second or more. DM_SCREEN_MATCH=0 keeps the rate in fullscreen too.

Changes to the PR: the switch only in fullscreen, with the way back on leaving it (the PR switched in a window
too); no switch without a window (the windowless host's main thread runs the guest); the rate to match is
atomic; the link takes a rate change only once its object exists, so one made while its thread starts is not lost,
and sets the range directly instead of logging a pacing mode -1; the screen this host switched takes its rate
from its mode, which maximumFramesPerSecond may not show yet. The link now also sets its range again when the
window moves to another screen, which kept the first screen's range before.

Checked on this Mac's built-in 120 Hz screen (a multiple of every link rate) with a harness that drives
front_mac.m asked for 50 fps: no switch in the window, 120 → 50 Hz in fullscreen, 120 Hz again on leaving it, and
120 Hz after quitting in fullscreen; at 60 fps and with DM_SCREEN_MATCH=0 nothing switched. Hades windowed and
fullscreen (DM_FULLSCREEN=1) paced at 60 as before, the unchanged host alike. nvn_mtl.m passes an iOS SDK
syntax check. The link's new range after a switch has not run here (it needs a 144 or 165 Hz screen); the PR's
author measured the windowed switch on a 144 Hz XB273U at 2560x1440: 120 Hz, the HUD's frame interval steady at
16.7 ms, 144 Hz again after quitting.

Co-authored-by: v0lumehi <[email protected]>
@seedds

seedds commented Oct 23, 2026

Copy link
Copy Markdown
Owner

Thanks! This is ported onto main as a678703, with you as co-author, and with these changes:

  • Fullscreen only. The screen switches when the window enters fullscreen, and switches back as soon as it leaves fullscreen or that screen. In a window the screen keeps its rate and the virtual ticks, because the switch changes the whole screen for every app and most external screens go black for a second or more. DM_SCREEN_MATCH=0 keeps the rate in fullscreen too.
  • No window, no switch. link_sync also runs in the windowless host, whose main thread runs the guest. front_screen_match now returns there instead of queuing a switch of the main screen.
  • g_match_want is atomic. The present thread writes it, and the main thread reads it.
  • Rate changes aren't lost. The link takes a rate change only once its object exists, so a change made while its thread starts isn't lost. It sets the range directly, so there's no present pacing mode -1 → 1 line. It now also sets the range again when the window moves to another screen, which it never did before.
  • Rate read from the mode. A screen the host switched takes its rate from the mode it set, since maximumFramesPerSecond may not have caught up yet when the screen observer fires.

Checked here on a built-in 120 Hz screen, using a harness that drives front_mac.m and asks for 50 fps:

  • no switch in a window;
  • 120 → 50 Hz in fullscreen;
  • 120 Hz again on leaving fullscreen, and after quitting while in fullscreen;
  • nothing switched at 60 fps or with DM_SCREEN_MATCH=0.

Hades paced at 60 fps, windowed and fullscreen, as before. The new link range after a switch hasn't run here, because that needs a 144 or 165 Hz screen. If you can, a fullscreen run on your XB273U (⌃⌘F or DM_FULLSCREEN=1) would confirm it. The log should show screen at 144 Hz switched to 120 Hz, then display link: the screen runs at 120 Hz now, range set again, and 144 Hz again after you leave fullscreen.

@seedds seedds closed this Oct 23, 2026
@v0lumehi
v0lumehi deleted the screen-match branch October 24, 2026 07:53
Know-It-All-Brother pushed a commit to Know-It-All-Brother/nxnative that referenced this pull request Nov 9, 2026
…the game's frame rate switches to one that is (144 → 120 Hz), from PR seedds#79

60 fps on a 144 Hz screen cannot be paced evenly: the display link counts a tick on the refresh nearest each 1/60 s
slot (link_range's virtual ticks), so frames stay up two and three refreshes in turn (13.9 / 20.8 ms) and Apple's HUD
shows the frame interval jumping between them. link_sync now tells the front end the link's rate (60, 30, or 120
with DM_PRESENT_LINK=2; front_screen_match), and in fullscreen front_mac.m switches a screen whose mode is not a
multiple of it to the mode of the same size with the highest rate that is, with kCGConfigureForAppOnly, so macOS
switches it back when the host quits; leaving fullscreen or that screen switches it back at once. A window keeps
the screen's rate and the virtual ticks: the switch changes the whole screen for every app and most external
screens go black for a second or more. DM_SCREEN_MATCH=0 keeps the rate in fullscreen too.

Changes to the PR: the switch only in fullscreen, with the way back on leaving it (the PR switched in a window
too); no switch without a window (the windowless host's main thread runs the guest); the rate to match is
atomic; the link takes a rate change only once its object exists, so one made while its thread starts is not lost,
and sets the range directly instead of logging a pacing mode -1; the screen this host switched takes its rate
from its mode, which maximumFramesPerSecond may not show yet. The link now also sets its range again when the
window moves to another screen, which kept the first screen's range before.

Checked on this Mac's built-in 120 Hz screen (a multiple of every link rate) with a harness that drives
front_mac.m asked for 50 fps: no switch in the window, 120 → 50 Hz in fullscreen, 120 Hz again on leaving it, and
120 Hz after quitting in fullscreen; at 60 fps and with DM_SCREEN_MATCH=0 nothing switched. Hades windowed and
fullscreen (DM_FULLSCREEN=1) paced at 60 as before, the unchanged host alike. nvn_mtl.m passes an iOS SDK
syntax check. The link's new range after a switch has not run here (it needs a 144 or 165 Hz screen); the PR's
author measured the windowed switch on a 144 Hz XB273U at 2560x1440: 120 Hz, the HUD's frame interval steady at
16.7 ms, 144 Hz again after quitting.

Co-authored-by: v0lumehi <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants