Skip to content

Run Windows games on Apple Silicon — free, open source, with an open compatibility database that tells you what actually works.

The Frame rate cap also paces presents at the Metal layer (HB_PRESENT_PACE_FPS) for the DXVK and vkd3d renderers when the cap divides the display's refresh rate. A limiter alone reaches the panel unevenly: it sleeps to the period but nothing aligns the present to vsync, so a frame that finishes past a boundary shows after 3 vsyncs and the next after 1. Measured with a ScreenCaptureKit recorder on the M4 (Forza Horizon 6 on the arm64 line, 1080p, GPU-bound at 31 ms a frame, 60 Hz panel): uncapped ~36 fps, the interval between displayed frames changed 69% of the time; VKD3D_FRAME_RATE=30, 74% of the intervals at 2 vsyncs and 36% changes; with Metal holding each frame for 1/30 s, 98.3% at exactly 2 vsyncs and 1.5% changes over 8 minutes of driving (2026-10-31, private/notes/fh6-arm64-current.md). The variable is read by highball-engine PR #25 (MoltenVK patch 0017) on the arm64 line and by the private KosmicKrisp build it was measured on; other engines ignore it. Only a cap that divides the refresh rate gets it, since Metal rounds the minimum up to the next vsync and 45 on 60 Hz would become 30; CoreGraphics gives the main display's rate (0 for some built-in panels, taken as 60), tests replace it. 21 environment tests pass.

Gauthier Piarrettedd7173a6537d
diff --git a/Sources/HighballKit/Bottle.swift b/Sources/HighballKit/Bottle.swift
index 52f763b..1100219 100644
--- a/Sources/HighballKit/Bottle.swift
+++ b/Sources/HighballKit/Bottle.swift
@@ -1,4 +1,5 @@
import Foundation
+import CoreGraphics
/// Graphics backend applied to a bottle (or overridden per program).
public enum Renderer: String, Codable, CaseIterable, Sendable {
@@ -808,6 +809,16 @@ public struct Bottle: Sendable {
env["D3DM_MAX_FPS"] = String(settings.fpsCap)
default: break
}
+ // A limiter alone reaches the panel unevenly: it sleeps to the period but nothing aligns
+ // the present to vsync, so a frame that finishes past a boundary shows after 3 vsyncs and
+ // the next after 1. Measured on a GPU-bound game capped at 30 on a 60 Hz panel: 74% of the
+ // displayed intervals were 2 vsyncs and the interval changed 36% of the time; with Metal
+ // holding each frame for the cap's slot (the arm64 engines' MoltenVK patch 0017, the same
+ // change in Mesa's Metal WSI) it is 98% and 1.5%. Only a cap that divides the refresh rate
+ // has a slot: Metal rounds the minimum up to the next vsync, so 45 on 60 Hz would become 30.
+ if r == .dxvk || r == .vkd3d, Self.displayRefreshRate() % settings.fpsCap == 0 {
+ env["HB_PRESENT_PACE_FPS"] = String(settings.fpsCap)
+ }
}
// Wine's menu builder writes .lnk shortcuts and app bundles onto the macOS Desktop and
// into ~/Applications for every installer that asks. Sikarugir's engines leave the
@@ -965,6 +976,12 @@ public struct Bottle: Sendable {
try? fm.removeItem(at: vkd3dCacheRoot.appending(path: old))
}
}
+ /// Frames per second of the main display, for the frame cap's pacing; CoreGraphics reports 0 for
+ /// some built-in panels, taken as 60. Tests replace it.
+ nonisolated(unsafe) public static var displayRefreshRate: () -> Int = {
+ let rate = CGDisplayCopyDisplayMode(CGMainDisplayID())?.refreshRate ?? 0
+ return rate > 0 ? Int(rate.rounded()) : 60
+ }
/// Windows path DXVK writes its per-process logs to, and its Unix location.
public static let dxvkLogWindowsPath = #"C:\highball\logs"#
public var dxvkLogURL: URL { driveC.appending(path: "highball/logs") }
diff --git a/Tests/HighballKitTests/EnvironmentTests.swift b/Tests/HighballKitTests/EnvironmentTests.swift
index b525f5a..48544bb 100644
--- a/Tests/HighballKitTests/EnvironmentTests.swift
+++ b/Tests/HighballKitTests/EnvironmentTests.swift
@@ -142,8 +142,23 @@ final class EnvironmentTests: XCTestCase {
try FileManager.default.createDirectory(at: d9vkWine, withIntermediateDirectories: true)
try FileManager.default.createDirectory(at: dxvkWine, withIntermediateDirectories: true)
defer { try? FileManager.default.removeItem(at: engine.root) }
+ let refreshRate = Bottle.displayRefreshRate
+ defer { Bottle.displayRefreshRate = refreshRate }
+ Bottle.displayRefreshRate = { 60 }
env = try bottle.environment(engine: engine, renderer: .dxvk)
XCTAssertEqual(env["DXVK_FRAME_RATE"], "60")
+ XCTAssertEqual(env["HB_PRESENT_PACE_FPS"], "60", "a cap that divides the refresh rate paces at the Metal layer")
+ bottle.settings.fpsCap = 45
+ env = try bottle.environment(engine: engine, renderer: .dxvk)
+ XCTAssertEqual(env["DXVK_FRAME_RATE"], "45")
+ XCTAssertNil(env["HB_PRESENT_PACE_FPS"], "45 has no slot on 60 Hz: Metal would round it to 30")
+ Bottle.displayRefreshRate = { 120 }
+ bottle.settings.fpsCap = 40
+ env = try bottle.environment(engine: engine, renderer: .dxvk)
+ XCTAssertEqual(env["HB_PRESENT_PACE_FPS"], "40", "40 is three vsyncs of a 120 Hz panel")
+ bottle.settings.fpsCap = 60
+ Bottle.displayRefreshRate = { 60 }
+ env = try bottle.environment(engine: engine, renderer: .dxvk)
// The async toggle travels via the generated conf, never DXVK_ASYNC: the async fork
// reads `env == "1" || config.enableAsync`, so an env 1 would defeat the per-game
// [csgo.exe] override that issue #21 requires.