Skip to main content

gpui/
present_feedback.rs

1//! vue-native fork: when each window present reached the screen, for an embedder that times its
2//! own frames against the display.
3//!
4//! A platform that reports it calls [`PresentListener::queued`] on the presenting thread for each
5//! present while feedback is wanted, then [`PresentListener::resolved`] once for that present, in
6//! present order per window. Times are the platform's monotonic clock in nanoseconds: QPC on
7//! Windows, `mach_absolute_time` on macOS.
8
9use std::sync::atomic::{AtomicBool, Ordering};
10use std::sync::{Mutex, OnceLock};
11
12/// What became of a window present.
13#[derive(Clone, Copy, Debug, PartialEq, Eq)]
14pub enum PresentOutcome {
15    /// First shown on a refresh.
16    Displayed {
17        /// When that refresh began.
18        at_ns: u64,
19        /// Its distance from the refresh before; the nominal period where that was not seen.
20        refresh_ns: u64,
21        /// False when `at_ns` was estimated.
22        exact: bool,
23    },
24    /// Replaced by a later present, or dropped with its swap chain, before any refresh showed it.
25    Discarded,
26}
27
28/// Hears window presents; see the module docs.
29pub trait PresentListener: Send + Sync {
30    /// On the presenting thread, after the present was queued and before it can be resolved.
31    /// `window` is the native handle: the HWND on Windows, the view's `CAMetalLayer` on macOS.
32    fn queued(&self, window: u64, present: u64);
33    /// Once per queued present, in present order per window.
34    fn resolved(&self, window: u64, present: u64, outcome: PresentOutcome);
35    /// On Windows, once per refresh while feedback is wanted, after that refresh's
36    /// [`Self::resolved`] calls: from the vsync thread, after it asked the windows to paint, or
37    /// with [`set_feedback_after_composition`] from a thread of its own.
38    fn refresh(&self) {}
39}
40
41static LISTENER: OnceLock<Box<dyn PresentListener>> = OnceLock::new();
42static WANTED: AtomicBool = AtomicBool::new(false);
43static AFTER_COMPOSITION: AtomicBool = AtomicBool::new(false);
44
45/// On Windows, reads each refresh's feedback once the compositor has finished that refresh: every
46/// outcome is exact, and no present misses its refresh to another application's update, but every
47/// present is shown a refresh later. Off by default.
48pub fn set_feedback_after_composition(on: bool) {
49    AFTER_COMPOSITION.store(on, Ordering::Release);
50}
51
52/// Whether [`set_feedback_after_composition`] is on.
53pub fn feedback_after_composition() -> bool {
54    AFTER_COMPOSITION.load(Ordering::Acquire)
55}
56static WAKER: OnceLock<fn()> = OnceLock::new();
57
58/// Installs the listener, once per process.
59pub fn set_present_listener(listener: Box<dyn PresentListener>) -> Result<(), &'static str> {
60    LISTENER
61        .set(listener)
62        .map_err(|_| "a present listener is already installed")
63}
64
65/// The installed listener.
66pub fn present_listener() -> Option<&'static dyn PresentListener> {
67    LISTENER.get().map(|l| &**l)
68}
69
70/// Whether presents are tracked and, on Windows, the vsync thread polls every refresh. Keep it
71/// off while nothing waits for an outcome, so an idle window costs nothing.
72pub fn want_present_feedback(on: bool) {
73    if WANTED.swap(on, Ordering::AcqRel) != on && on {
74        if let Some(wake) = WAKER.get() {
75            wake();
76        }
77    }
78}
79
80/// Whether a listener is installed and wants feedback.
81pub fn present_feedback_wanted() -> bool {
82    WANTED.load(Ordering::Acquire) && LISTENER.get().is_some()
83}
84
85/// For a platform: called when feedback becomes wanted, to wake a sleeping vsync thread.
86pub fn set_present_feedback_waker(wake: fn()) {
87    let _ = WAKER.set(wake);
88}
89
90/// The refresh grid of the display the platform's vsync thread waits on, measured from its waits:
91/// a vblank and the period, in the platform's monotonic clock in nanoseconds.
92#[derive(Clone, Copy, Debug, PartialEq, Eq)]
93pub struct VBlankClock {
94    /// A vblank, not necessarily the latest.
95    pub vblank_ns: u64,
96    /// The measured distance between vblanks.
97    pub period_ns: u64,
98}
99
100static CLOCK: Mutex<Option<VBlankClock>> = Mutex::new(None);
101
102/// For a platform: the vsync thread's latest measure of its display's vblanks.
103pub fn set_vblank_clock(clock: Option<VBlankClock>) {
104    *CLOCK.lock().unwrap_or_else(|e| e.into_inner()) = clock;
105}
106
107/// The vsync thread's display's vblanks, where the platform measures them (Windows).
108pub fn vblank_clock() -> Option<VBlankClock> {
109    *CLOCK.lock().unwrap_or_else(|e| e.into_inner())
110}