Display Performance

Systematic diagnosis for frame rate issues on variable refresh rate displays (ProMotion, iPad Pro, future devices). Covers render loop configuration, frame pacing, hitch mechanics, and production telemetry.

Key insight: "ProMotion available" does NOT mean your app automatically runs at 120Hz. You must configure it correctly, account for system caps, and ensure proper frame pacing.

Part 1: Why You're Stuck at 60fps

Diagnostic Order

Check these in order when stuck at 60fps on ProMotion:

1. Info.plist key missing? (iPhone only) → Part 2
2. Render loop configured for 60? (MTKView defaults, CADisplayLink) → Part 3
3. System caps enabled? (Low Power Mode, Limit Frame Rate, Thermal) → Part 5
4. Frame time > 8.33ms? (Can't sustain 120fps) → Part 6
5. Frame pacing issues? (Micro-stuttering despite good FPS) → Part 7
6. Measuring wrong thing? (UIScreen vs actual presentation) → Part 9

Part 2: Enabling ProMotion on iPhone

Critical: Core Animation won't access frame rates above 60Hz on iPhone unless you add this key.

<!-- Info.plist -->
<key>CADisableMinimumFrameDurationOnPhone</key>
<true/>

Without this key:

• Your preferredFrameRateRange hints are ignored above 60Hz
• Other animations may affect your CADisplayLink callback rate
• iPad Pro does NOT require this key

When to add: Any iPhone app that needs >60Hz for games, animations, or smooth scrolling.

Part 3: Render Loop Configuration

MTKView Defaults to 60fps

This is the most common cause. MTKView's preferredFramesPerSecond defaults to 60.

// ❌ WRONG: Implicit 60fps (default)
let mtkView = MTKView(frame: frame, device: device)
mtkView.delegate = self
// Running at 60fps even on ProMotion!

// ✅ CORRECT: Explicit 120fps request
let mtkView = MTKView(frame: frame, device: device)
mtkView.preferredFramesPerSecond = 120
mtkView.isPaused = false
mtkView.enableSetNeedsDisplay = false  // Continuous, not on-demand
mtkView.delegate = self

Critical settings for continuous high-rate rendering:

CADisplayLink Configuration (iOS 15+)

Apple explicitly recommends CADisplayLink (not timers) for custom render loops.

// ❌ WRONG: Timer-based render loop (drifts, wastes frame time)
Timer.scheduledTimer(withTimeInterval: 1.0/120.0, repeats: true) { _ in
    self.render()
}

// ❌ WRONG: Default CADisplayLink (may hint 60)
let displayLink = CADisplayLink(target: self, selector: #selector(render))
displayLink.add(to: .main, forMode: .common)

// ✅ CORRECT: Explicit frame rate range
let displayLink = CADisplayLink(target: self, selector: #selector(render))
displayLink.preferredFrameRateRange = CAFrameRateRange(
    minimum: 80,      // Minimum acceptable
    maximum: 120,     // Preferred maximum
    preferred: 120    // What you want
)
displayLink.add(to: .main, forMode: .common)

Special priority for games: iOS 15+ gives 30Hz and 60Hz special priority. If targeting these rates:

// 30Hz and 60Hz get priority scheduling
let prioritizedRange = CAFrameRateRange(
    minimum: 30,
    maximum: 60,
    preferred: 60
)
displayLink.preferredFrameRateRange = prioritizedRange

Suggested Frame Rates by Content Type

Part 4: CAMetalDisplayLink (iOS 17+)

For Metal apps needing precise timing control, CAMetalDisplayLink provides more control than CADisplayLink.

class MetalRenderer: NSObject, CAMetalDisplayLinkDelegate {
    var displayLink: CAMetalDisplayLink?
    var metalLayer: CAMetalLayer!

    func setupDisplayLink() {
        displayLink = CAMetalDisplayLink(metalLayer: metalLayer)
        displayLink?.delegate = self
        displayLink?.preferredFrameRateRange = CAFrameRateRange(
            minimum: 60,
            maximum: 120,
            preferred: 120
        )
        // Control render latency (in frames)
        displayLink?.preferredFrameLatency = 2
        displayLink?.add(to: .main, forMode: .common)
    }

    func metalDisplayLink(_ link: CAMetalDisplayLink, needsUpdate update: CAMetalDisplayLink.Update) {
        // update.drawable - The drawable to render to
        // update.targetTimestamp - Deadline to finish rendering
        // update.targetPresentationTimestamp - When frame will display

        guard let drawable = update.drawable else { return }

        let workingTime = update.targetTimestamp - CACurrentMediaTime()
        // workingTime = seconds available before deadline

        // Render to drawable...
        renderFrame(to: drawable)
    }
}

Key differences from CADisplayLink:

When to use CAMetalDisplayLink:

• Need precise control over render timing window
• Want to minimize input latency
• Building games or intensive Metal apps
• iOS 17+ only deployment

Part 5: System Caps

System states can force 60fps even when your code requests 120:

Low Power Mode

Caps ProMotion devices to 60fps.

// Check programmatically
if ProcessInfo.processInfo.isLowPowerModeEnabled {
    // System caps display to 60Hz
}

// Observe changes
NotificationCenter.default.addObserver(
    forName: .NSProcessInfoPowerStateDidChange,
    object: nil,
    queue: .main
) { _ in
    let isLowPower = ProcessInfo.processInfo.isLowPowerModeEnabled
    self.adjustRenderingForPowerState(isLowPower)
}

Limit Frame Rate (Accessibility)

Settings → Accessibility → Motion → Limit Frame Rate caps to 60fps.

No API to detect. If user reports 60fps despite configuration, have them check this setting.

Thermal Throttling

System restricts 120Hz when device overheats.

// Check thermal state
switch ProcessInfo.processInfo.thermalState {
case .nominal, .fair:
    preferredFramesPerSecond = 120
case .serious, .critical:
    preferredFramesPerSecond = 60  // Reduce proactively
@unknown default:
    break
}

// Observe thermal changes
NotificationCenter.default.addObserver(
    forName: ProcessInfo.thermalStateDidChangeNotification,
    object: nil,
    queue: .main
) { _