fps: Cap the headline by asking the platform what the panel runs at

Nothing about a window's own frames can establish its display's refresh rate.
The gaps between presents are whole multiples of the panel's period, so they
bound it from below and never from above — 41.7ms is six refreshes at 144Hz
and one at 24Hz — and every estimate tried read a real window wrong: 169 and
149 from the shortest and the densest gaps, 75 from a window drawing every
other refresh, and 24 from an application whose own timer fired every 41.7ms.

So the platform is asked. GPUI hands out its display handle through
`DisplayId`: a `CGDirectDisplayID` on macOS, an `HMONITOR` on Windows. Wayland
gives out per-connection object ids that mean nothing to a second connection,
so the outputs are enumerated again there and matched to GPUI's displays by
the identity it derives from their names. X11 and everything else have no
query and stay uncapped, as does a panel that reports no fixed rate — which is
what a ProMotion display honestly is.

The answer is re-asked when the window moves to another display, and not
otherwise: it is a property of the panel, and on some platforms asking is a
round trip.

Measured on Wayland against two panels: 143.998Hz and 59.997Hz discovered,
against 143.999 and 59.997 from the compositor, and a window whose frames cost
4.3ms — 232 uncapped — reading MAX 144 on the faster one.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01USSMRpQ5W58YP3UKUCzrri

Author: huacnlee

Cargo.lock

@@ -29,6 +29,7 @@ sysinfo = "0.37"
 # counter the platform's own activity monitor attributes per process with, so no
 # vendor SDK or elevated privilege is involved.
 [target.'cfg(target_os = "macos")'.dependencies]
+core-graphics = "0.24"
 libc = "0.2"
 objc2-core-foundation = { version = "0.3", default-features = false, features = [
     "std",
@@ -42,8 +43,13 @@ objc2-io-kit = { version = "0.3", default-features = false, features = [
     "libc",
 ] }
 
+[target.'cfg(target_os = "linux")'.dependencies]
+uuid = { version = "1", features = ["v5"] }
+wayland-client = "0.31"
+
 [target.'cfg(target_os = "windows")'.dependencies]
 windows = { workspace = true, features = [
+    "Win32_Graphics_Gdi",
     "Win32_System_Performance",
     "Win32_System_ProcessStatus",
     "Win32_System_Threading",

crates/fps/Cargo.toml

@@ -40,6 +40,7 @@ mod gpu;
 mod memory;
 mod monitor;
 mod overlay;
+mod refresh;
 mod sampler;
 mod style;
 

crates/fps/src/lib.rs

@@ -3,15 +3,16 @@ use std::time::Duration;
 use web_time::Instant;
 
 use gpui::{
-    Bounds, Context, Div, Hsla, InteractiveElement as _, IntoElement, MouseButton, ParentElement,
-    PathBuilder, Pixels, Point, Render, StatefulInteractiveElement as _, Styled, Window, canvas,
-    div, point, prelude::FluentBuilder as _, px, relative,
+    App, Bounds, Context, DisplayId, Div, Hsla, InteractiveElement as _, IntoElement, MouseButton,
+    ParentElement, PathBuilder, Pixels, Point, Render, StatefulInteractiveElement as _, Styled,
+    Window, canvas, div, point, prelude::FluentBuilder as _, px, relative,
 };
 
 use gpui::Task;
 
 use crate::{
     FrameTraceGuard,
+    refresh::display_refresh_rate,
     sampler::{FrameSampler, ResourceSample, minimum_resource_interval},
     style::FpsStyle,
 };
@@ -141,23 +142,25 @@ struct Readout {
     invalidations: f32,
 }
 
-/// The rate a full redraw could sustain: what a frame's cost implies.
+/// The rate a full redraw could sustain: what a frame's cost implies, held to
+/// what the panel can scan out.
 ///
-/// Not held to the display's refresh rate, which GPUI does not expose and
-/// which cannot be recovered from the frames this window happened to present.
-/// Gaps between presents are whole multiples of the panel's period, so they
-/// put a *lower* bound on it and never an upper one: 41.7ms is six refreshes
-/// at 144Hz and one at 24Hz, and nothing in the timing says which. Every
-/// estimate tried here read a real window wrong — 169 and 149 from the
-/// shortest and the densest gaps, 75 from a window drawing every other
-/// refresh, 24 from an application whose own timer fired every 41.7ms — and a
-/// ceiling under the truth hides the figure the reader came for.
-fn sustainable_rate(mean_draw: Duration) -> f32 {
+/// The cap is the half the derivation loses. Counting presents could never
+/// exceed the refresh rate — frames go to the compositor on vsync, so the
+/// bound came for free — while a frame drawn in 3ms reads as 333, a rate
+/// nobody could ever see. `display` is `None` where the platform would not say
+/// what the panel runs at, and an uncapped reading is better than one held to
+/// a guess: see [`crate::refresh`] for why guessing was tried and abandoned.
+fn sustainable_rate(mean_draw: Duration, display: Option<Duration>) -> f32 {
     let mean_draw = mean_draw.as_secs_f32();
     if mean_draw <= 0. {
         return 0.;
     }
-    1. / mean_draw
+    let rate = 1. / mean_draw;
+    match display.map(|period| period.as_secs_f32()) {
+        Some(period) if period > 0. => rate.min(1. / period),
+        _ => rate,
+    }
 }
 
 /// Which question the headline answers.
@@ -181,6 +184,10 @@ pub struct FpsMonitor {
     style: FpsStyle,
     frame_budget: Duration,
     headline: Headline,
+    /// The panel's refresh period, and which display it was asked about, so
+    /// that moving the window to another monitor re-asks and staying on one
+    /// does not ask again every frame.
+    display: Option<(DisplayId, Option<Duration>)>,
     show_resources: bool,
     resource_interval: Duration,
     resources: Option<ResourceSample>,
@@ -201,6 +208,7 @@ impl FpsMonitor {
             style: FpsStyle::default(),
             frame_budget,
             headline: Headline::Max,
+            display: None,
             show_resources: true,
             resource_interval: DEFAULT_RESOURCE_INTERVAL,
             resources: None,
@@ -333,6 +341,19 @@ impl FpsMonitor {
         }));
     }
 
+    /// Re-asks the platform for the refresh rate when the window has moved to
+    /// another display, and not otherwise: the answer is a property of the
+    /// panel, and on some platforms asking is a round trip.
+    fn update_display(&mut self, window: &Window, cx: &App) {
+        let Some(display) = window.display(cx) else {
+            return;
+        };
+        let id = display.id();
+        if self.display.map(|(asked, _)| asked) != Some(id) {
+            self.display = Some((id, display_refresh_rate(display.as_ref())));
+        }
+    }
+
     /// Republishes the readings if [`READOUT_INTERVAL`] has passed.
     fn update_readout(&mut self) {
         let now = Instant::now();
@@ -344,7 +365,10 @@ impl FpsMonitor {
         }
 
         self.readout = Readout {
-            max_fps: sustainable_rate(self.sampler.mean_draw()),
+            max_fps: sustainable_rate(
+                self.sampler.mean_draw(),
+                self.display.and_then(|(_, refresh_rate)| refresh_rate),
+            ),
             fps: self.sampler.fps(),
             interval_millis: self.sampler.present_interval().as_secs_f32() * 1000.,
             // The mean over the interval rather than the latest frame, which
@@ -494,8 +518,9 @@ impl FpsMonitor {
 }
 
 impl Render for FpsMonitor {
-    fn render(&mut self, _: &mut Window, cx: &mut Context<Self>) -> impl IntoElement {
+    fn render(&mut self, window: &mut Window, cx: &mut Context<Self>) -> impl IntoElement {
         self.sampler.tick();
+        self.update_display(window, cx);
         self.update_readout();
         self.update_axis();
         self.start_clock(cx);
@@ -736,11 +761,19 @@ mod tests {
     use super::*;
 
     #[test]
-    fn the_headline_rate_is_what_a_frame_costs() {
-        assert!((sustainable_rate(Duration::from_millis(3)) - 333.33).abs() < 0.1);
-        assert_eq!(sustainable_rate(Duration::from_millis(20)), 50.);
+    fn the_headline_rate_is_what_a_frame_costs_and_the_panel_allows() {
+        let sixty = Duration::from_micros(16_667);
+        // A cheap frame on a 60Hz panel is not 333 frames anyone could see.
+        assert!((sustainable_rate(Duration::from_millis(3), Some(sixty)) - 60.).abs() < 0.01);
+        // A frame that costs more than a refresh sets the rate itself.
+        assert_eq!(
+            sustainable_rate(Duration::from_millis(20), Some(sixty)),
+            50.
+        );
+        // Where the platform will not say, an uncapped reading beats a guess.
+        assert!((sustainable_rate(Duration::from_millis(3), None) - 333.33).abs() < 0.1);
         // No frames drawn yet is no rate, not an infinite one.
-        assert_eq!(sustainable_rate(Duration::ZERO), 0.);
+        assert_eq!(sustainable_rate(Duration::ZERO, Some(sixty)), 0.);
     }
 
     #[gpui::test]

crates/fps/src/monitor.rs

@@ -0,0 +1,203 @@
+//! The refresh rate of the display a window is on, read from the platform.
+//!
+//! GPUI does not report it, and it cannot be recovered from the frames a
+//! window presented: those gaps are whole multiples of the panel's period, so
+//! they bound it from below and never from above — 41.7ms is six refreshes at
+//! 144Hz and one at 24Hz, and nothing in the timing says which. Every estimate
+//! tried before this read a real window wrong.
+//!
+//! So it is asked for. GPUI does hand out the platform's own display handle
+//! through [`gpui::DisplayId`], which is a `CGDirectDisplayID` on macOS and an
+//! `HMONITOR` on Windows, and on Wayland the outputs can be enumerated again
+//! and matched by the identity GPUI derives from their names.
+//!
+//! `None` means nobody could say — a platform without a query here, a virtual
+//! display, or a panel with no fixed rate — and the caller shows an uncapped
+//! reading rather than one held to a guess.
+
+use std::time::Duration;
+
+use gpui::PlatformDisplay;
+
+/// The period between refreshes of `display`, when the platform reports one.
+pub(crate) fn display_refresh_rate(display: &dyn PlatformDisplay) -> Option<Duration> {
+    platform::refresh_rate(display)
+}
+
+/// Turns a rate in hertz into the period the rest of the crate works in,
+/// rejecting the zeroes platforms use to mean "no fixed rate".
+#[cfg(any(target_os = "macos", target_os = "windows"))]
+fn period_from_hertz(hertz: f64) -> Option<Duration> {
+    (hertz > 1.).then(|| Duration::from_secs_f64(1. / hertz))
+}
+
+#[cfg(target_os = "macos")]
+mod platform {
+    use super::*;
+    use core_graphics::display::{CGDirectDisplayID, CGDisplay};
+
+    pub(super) fn refresh_rate(display: &dyn PlatformDisplay) -> Option<Duration> {
+        let id: u64 = display.id().into();
+        // Zero rather than an error is how CoreGraphics says this display has
+        // no fixed rate, which is what a built-in panel reports: on ProMotion
+        // there genuinely is not one, and the nominal period would have to come
+        // from CoreVideo instead.
+        let mode = CGDisplay::new(id as CGDirectDisplayID).display_mode()?;
+        period_from_hertz(mode.refresh_rate())
+    }
+}
+
+#[cfg(target_os = "windows")]
+mod platform {
+    use super::*;
+    use windows::{
+        Win32::{Foundation::*, Graphics::Gdi::*},
+        core::*,
+    };
+
+    pub(super) fn refresh_rate(display: &dyn PlatformDisplay) -> Option<Duration> {
+        let id: u64 = display.id().into();
+        let monitor = HMONITOR(id as _);
+
+        let mut info = MONITORINFOEXW {
+            monitorInfo: MONITORINFO {
+                cbSize: std::mem::size_of::<MONITORINFOEXW>() as u32,
+                ..Default::default()
+            },
+            ..Default::default()
+        };
+        if !unsafe { GetMonitorInfoW(monitor, &mut info as *mut _ as *mut MONITORINFO) }.as_bool() {
+            return None;
+        }
+
+        let mut mode = DEVMODEW {
+            dmSize: std::mem::size_of::<DEVMODEW>() as u16,
+            ..Default::default()
+        };
+        let device = PCWSTR(info.szDevice.as_ptr());
+        if !unsafe { EnumDisplaySettingsW(device, ENUM_CURRENT_SETTINGS, &mut mode) }.as_bool() {
+            return None;
+        }
+        // Zero and one both mean "whatever the hardware defaults to" rather
+        // than a rate, which is what a driver reports when it has none to give.
+        period_from_hertz(mode.dmDisplayFrequency as f64)
+    }
+}
+
+#[cfg(target_os = "linux")]
+mod platform {
+    use super::*;
+    use std::{collections::HashMap, sync::OnceLock};
+    use uuid::Uuid;
+    use wayland_client::{
+        Connection, Dispatch, Proxy as _, QueueHandle, WEnum,
+        protocol::{wl_output, wl_registry},
+    };
+
+    /// Wayland hands each client its own object ids, so the id GPUI reports for
+    /// an output means nothing on a second connection. What both sides can
+    /// agree on is the output's name, which GPUI folds into the display's uuid
+    /// — so the outputs are enumerated again and matched by that.
+    pub(super) fn refresh_rate(display: &dyn PlatformDisplay) -> Option<Duration> {
+        let uuid = display.uuid().ok()?;
+        outputs().get(&uuid).copied()
+    }
+
+    /// Asked once. Outputs change when a monitor is plugged in or its mode is
+    /// changed, and neither happens in the middle of reading a frame counter.
+    fn outputs() -> &'static HashMap<Uuid, Duration> {
+        static OUTPUTS: OnceLock<HashMap<Uuid, Duration>> = OnceLock::new();
+        OUTPUTS.get_or_init(|| query_outputs().unwrap_or_default())
+    }
+
+    fn query_outputs() -> Option<HashMap<Uuid, Duration>> {
+        let connection = Connection::connect_to_env().ok()?;
+        let mut queue = connection.new_event_queue();
+        let handle = queue.handle();
+        let _registry = connection.display().get_registry(&handle, ());
+
+        let mut state = State::default();
+        // Once for the globals, once for the events the outputs send back.
+        queue.roundtrip(&mut state).ok()?;
+        queue.roundtrip(&mut state).ok()?;
+        Some(state.rates)
+    }
+
+    #[derive(Default)]
+    struct State {
+        /// Name and current mode, per output object, until its `Done`.
+        pending: HashMap<u32, (Option<String>, Option<Duration>)>,
+        rates: HashMap<Uuid, Duration>,
+    }
+
+    impl Dispatch<wl_registry::WlRegistry, ()> for State {
+        fn event(
+            _: &mut Self,
+            registry: &wl_registry::WlRegistry,
+            event: wl_registry::Event,
+            _: &(),
+            _: &Connection,
+            handle: &QueueHandle<Self>,
+        ) {
+            if let wl_registry::Event::Global {
+                name,
+                interface,
+                version,
+            } = event
+                && interface == wl_output::WlOutput::interface().name
+            {
+                // Version 4 is where an output started naming itself, which is
+                // the only thing this connection and GPUI's can match on.
+                if version >= 4 {
+                    registry.bind::<wl_output::WlOutput, _, _>(name, 4, handle, ());
+                }
+            }
+        }
+    }
+
+    impl Dispatch<wl_output::WlOutput, ()> for State {
+        fn event(
+            state: &mut Self,
+            output: &wl_output::WlOutput,
+            event: wl_output::Event,
+            _: &(),
+            _: &Connection,
+            _: &QueueHandle<Self>,
+        ) {
+            let id = output.id().protocol_id();
+            match event {
+                wl_output::Event::Name { name } => {
+                    state.pending.entry(id).or_default().0 = Some(name);
+                }
+                wl_output::Event::Mode { flags, refresh, .. } => {
+                    // Outputs advertise every mode they support; only one of
+                    // them is the one being scanned out.
+                    let current = matches!(flags, WEnum::Value(mode) if mode.contains(wl_output::Mode::Current));
+                    if current && refresh > 0 {
+                        state.pending.entry(id).or_default().1 =
+                            Some(Duration::from_nanos(1_000_000_000_000 / refresh as u64));
+                    }
+                }
+                wl_output::Event::Done => {
+                    if let Some((Some(name), Some(rate))) = state.pending.remove(&id) {
+                        // The same derivation GPUI uses for a Wayland display's
+                        // uuid, which is what makes the two sides comparable.
+                        state
+                            .rates
+                            .insert(Uuid::new_v5(&Uuid::NAMESPACE_DNS, name.as_bytes()), rate);
+                    }
+                }
+                _ => {}
+            }
+        }
+    }
+}
+
+#[cfg(not(any(target_os = "macos", target_os = "windows", target_os = "linux")))]
+mod platform {
+    use super::*;
+
+    pub(super) fn refresh_rate(_display: &dyn PlatformDisplay) -> Option<Duration> {
+        None
+    }
+}