Skip to main content

sui_platform/
headless.rs

1use std::{collections::VecDeque, time::Instant};
2
3use sui_core::{AsyncWakeToken, Error, Event, Result, Size, WindowEvent, WindowId};
4use sui_render_wgpu::{
5    DebugCaptureArtifact, DebugCaptureRequest, DisplayCapabilities, RgbaImage,
6    WgpuExternalTextureRegistry, WgpuRenderer,
7};
8use sui_runtime::{PresentationLatencyDiagnostics, Runtime};
9
10use crate::{AccessibilityBridge, AccessibilitySnapshot, PresentedFrame, present_window_frame};
11
12#[derive(Debug, Clone)]
13pub struct PlatformWindow {
14    pub id: WindowId,
15    pub title: String,
16    pub accessibility: Option<AccessibilitySnapshot>,
17}
18
19#[derive(Debug, Default)]
20pub struct HeadlessPlatform {
21    renderer: WgpuRenderer,
22    windows: Vec<WindowState>,
23    pending_events: VecDeque<QueuedEvent>,
24    frame_clock: f64,
25    /// The display windows render for; see
26    /// [`with_display_capabilities`](Self::with_display_capabilities).
27    display_capabilities: Option<DisplayCapabilities>,
28}
29
30impl HeadlessPlatform {
31    const DEFAULT_WINDOW_SIZE: Size = Size::new(1280.0, 720.0);
32
33    pub fn new() -> Self {
34        Self::default()
35    }
36
37    pub fn with_feather_width(mut self, feather_width: f32) -> Self {
38        self.set_feather_width(feather_width);
39        self
40    }
41
42    /// Render windows as if they were on a display with `capabilities`.
43    /// Output strategies, diagnostics, final-output captures, and HDR theme
44    /// styling all follow it. Without it, windows render for an SDR display.
45    pub fn with_display_capabilities(mut self, capabilities: DisplayCapabilities) -> Self {
46        self.display_capabilities = Some(capabilities);
47        self
48    }
49
50    fn display_capabilities(&self) -> DisplayCapabilities {
51        self.display_capabilities
52            .clone()
53            .unwrap_or_else(|| DisplayCapabilities {
54                notes: "Headless offscreen renderer.".to_string(),
55                ..DisplayCapabilities::default()
56            })
57    }
58
59    pub fn with_feathering_enabled(mut self, enabled: bool) -> Self {
60        self.set_feathering_enabled(enabled);
61        self
62    }
63
64    pub fn run(&mut self, runtime: &mut Runtime) -> Result<Vec<PlatformWindow>> {
65        loop {
66            if self.pump(runtime)? {
67                continue;
68            }
69            if !self.advance_to_next_wakeup(runtime)? {
70                break;
71            }
72        }
73
74        Ok(self
75            .windows
76            .iter()
77            .filter(|window| window.open)
78            .map(WindowState::snapshot)
79            .collect())
80    }
81
82    pub fn pump(&mut self, runtime: &mut Runtime) -> Result<bool> {
83        self.sync_windows(runtime)?;
84        let mut did_work = runtime.has_pending_commands();
85        runtime.process_commands();
86        runtime.tick(self.frame_clock);
87        self.queue_ready_events(runtime);
88        self.queue_redraw_requests(runtime)?;
89
90        while let Some(queued_event) = self.pending_events.pop_front() {
91            did_work = true;
92            self.process_event(runtime, queued_event)?;
93        }
94
95        Ok(did_work)
96    }
97
98    pub fn advance_time(&mut self, delta: f64) {
99        self.frame_clock += delta;
100    }
101
102    pub fn wake_async(
103        &mut self,
104        runtime: &mut Runtime,
105        window_id: WindowId,
106        token: AsyncWakeToken,
107    ) -> Result<bool> {
108        self.sync_windows(runtime)?;
109        runtime.wake_async(window_id, token)
110    }
111
112    pub fn current_time(&self) -> f64 {
113        self.frame_clock
114    }
115
116    fn advance_to_next_wakeup(&mut self, runtime: &Runtime) -> Result<bool> {
117        let mut next: Option<f64> = None;
118        for window_id in runtime.window_ids() {
119            let candidate = runtime.next_wakeup_time(window_id)?;
120            next = match (next, candidate) {
121                (Some(current), Some(candidate)) => Some(current.min(candidate)),
122                (None, Some(candidate)) => Some(candidate),
123                (current, None) => current,
124            };
125        }
126
127        let Some(next) = next else {
128            return Ok(false);
129        };
130        if next <= self.frame_clock {
131            return Ok(false);
132        }
133
134        self.frame_clock = next;
135        Ok(true)
136    }
137
138    pub fn pending_event_count(&self) -> usize {
139        self.pending_events.len()
140    }
141
142    pub fn has_pending_events(&self) -> bool {
143        !self.pending_events.is_empty()
144    }
145
146    pub fn dispatch_event(
147        &mut self,
148        runtime: &Runtime,
149        window_id: WindowId,
150        event: Event,
151    ) -> Result<()> {
152        self.sync_windows(runtime)?;
153
154        if !self
155            .windows
156            .iter()
157            .any(|window| window.id == window_id && window.open)
158        {
159            return Err(Error::new(format!(
160                "window {} is not registered with the headless platform",
161                window_id.get()
162            )));
163        }
164
165        self.pending_events
166            .push_back(QueuedEvent { window_id, event });
167        Ok(())
168    }
169
170    pub fn renderer(&self) -> &WgpuRenderer {
171        &self.renderer
172    }
173
174    pub fn feather_width(&self) -> f32 {
175        self.renderer.feather_width()
176    }
177
178    pub fn feathering_enabled(&self) -> bool {
179        self.renderer.feathering_enabled()
180    }
181
182    pub fn set_feather_width(&mut self, feather_width: f32) {
183        self.renderer.set_feather_width(feather_width);
184    }
185
186    pub fn set_feathering_enabled(&mut self, enabled: bool) {
187        self.renderer.set_feathering_enabled(enabled);
188    }
189
190    /// Attach the registry used to resolve app-owned WGPU textures.
191    pub fn set_external_texture_registry(&mut self, registry: WgpuExternalTextureRegistry) {
192        self.renderer.set_external_texture_registry(registry);
193    }
194
195    pub fn renderer_mut(&mut self) -> &mut WgpuRenderer {
196        &mut self.renderer
197    }
198
199    pub fn capture_rgba(&self, window_id: WindowId) -> Result<RgbaImage> {
200        self.renderer.capture_rgba(window_id)
201    }
202
203    pub fn capture_debug_frame(
204        &mut self,
205        window_id: WindowId,
206        request: DebugCaptureRequest,
207    ) -> Result<DebugCaptureArtifact> {
208        self.renderer.capture_last_frame_debug(window_id, request)
209    }
210
211    pub fn accessibility_snapshot(&self, window_id: WindowId) -> Option<&AccessibilitySnapshot> {
212        self.windows
213            .iter()
214            .find(|window| window.id == window_id && window.open)
215            .and_then(|window| window.accessibility.snapshot())
216    }
217
218    fn queue_ready_events(&mut self, runtime: &mut Runtime) {
219        self.pending_events.extend(
220            runtime
221                .drain_ready_events()
222                .into_iter()
223                .map(|(window_id, event)| QueuedEvent { window_id, event }),
224        );
225    }
226
227    fn sync_windows(&mut self, runtime: &Runtime) -> Result<()> {
228        let runtime_window_ids = runtime.window_ids();
229
230        let removed_ids: Vec<_> = self
231            .windows
232            .iter()
233            .map(|window| window.id)
234            .filter(|window_id| !runtime_window_ids.contains(window_id))
235            .collect();
236
237        for window_id in removed_ids {
238            self.renderer.remove_window(window_id);
239            crate::clear_window_performance(window_id);
240        }
241
242        self.windows
243            .retain(|window| runtime_window_ids.contains(&window.id));
244        self.pending_events
245            .retain(|queued_event| runtime_window_ids.contains(&queued_event.window_id));
246
247        for window_id in runtime_window_ids {
248            if self.windows.iter().any(|window| window.id == window_id) {
249                continue;
250            }
251
252            self.windows.push(WindowState {
253                id: window_id,
254                title: runtime.window_title(window_id)?.to_string(),
255                open: true,
256                awaiting_performance_bootstrap: true,
257                redraw_requested: false,
258                redraw_requested_at_ms: None,
259                frame_index: 0,
260                pending_event_time_ms: 0.0,
261                last_non_redraw_event_at_ms: None,
262                accessibility: AccessibilityBridge::default(),
263            });
264            self.pending_events.push_back(QueuedEvent {
265                window_id,
266                event: Event::Window(WindowEvent::Resized(Self::DEFAULT_WINDOW_SIZE)),
267            });
268        }
269
270        Ok(())
271    }
272
273    fn queue_redraw_requests(&mut self, runtime: &Runtime) -> Result<()> {
274        let now_ms = self.current_time() * 1000.0;
275
276        for window in &mut self.windows {
277            let capturing = crate::has_pending_window_debug_captures(window.id);
278            if !window.open
279                || window.redraw_requested
280                || (!runtime.needs_render(window.id)? && !capturing)
281            {
282                continue;
283            }
284
285            window.redraw_requested = true;
286            window.redraw_requested_at_ms = Some(now_ms);
287            self.pending_events.push_back(QueuedEvent {
288                window_id: window.id,
289                event: Event::Window(WindowEvent::RedrawRequested),
290            });
291        }
292
293        Ok(())
294    }
295
296    fn process_event(&mut self, runtime: &mut Runtime, queued_event: QueuedEvent) -> Result<()> {
297        let Some(window_index) = self
298            .windows
299            .iter()
300            .position(|window| window.id == queued_event.window_id && window.open)
301        else {
302            return Ok(());
303        };
304
305        let is_redraw = matches!(
306            queued_event.event,
307            Event::Window(WindowEvent::RedrawRequested)
308        );
309        let is_close = matches!(
310            queued_event.event,
311            Event::Window(WindowEvent::CloseRequested)
312        );
313        let window_id = queued_event.window_id;
314        let event_arrived_at_ms = self.current_time() * 1000.0;
315
316        let event_started = Instant::now();
317        runtime.handle_event(window_id, queued_event.event)?;
318        let event_time_ms = event_started.elapsed().as_secs_f64() * 1000.0;
319        // Match the desktop host: input with no pending redraw belongs to idle
320        // processing, not to the timing or latency of a future frame.
321        if !is_redraw && !is_close && runtime.needs_render(window_id)? {
322            self.windows[window_index].pending_event_time_ms += event_time_ms;
323            self.windows[window_index].last_non_redraw_event_at_ms = Some(event_arrived_at_ms);
324        }
325
326        if is_redraw {
327            self.windows[window_index].redraw_requested = false;
328
329            if runtime.needs_render(window_id)? {
330                runtime.tick(self.frame_clock);
331
332                let render_started_at_ms = self.current_time() * 1000.0;
333                let mut presentation_latency = PresentationLatencyDiagnostics::new(
334                    self.windows[window_index]
335                        .last_non_redraw_event_at_ms
336                        .map(|timestamp| (render_started_at_ms - timestamp).max(0.0))
337                        .unwrap_or(0.0),
338                    0.0,
339                    self.windows[window_index]
340                        .redraw_requested_at_ms
341                        .map(|timestamp| (render_started_at_ms - timestamp).max(0.0))
342                        .unwrap_or(0.0),
343                );
344
345                self.renderer
346                    .set_window_display_capabilities(window_id, self.display_capabilities())?;
347                let PresentedFrame {
348                    output,
349                    runtime_time_ms,
350                    renderer_time_ms,
351                    ..
352                } = present_window_frame(runtime, &mut self.renderer, window_id)?;
353                let presented_at_ms = self.current_time() * 1000.0;
354                presentation_latency.event_to_present_ms = self.windows[window_index]
355                    .last_non_redraw_event_at_ms
356                    .map(|timestamp| (presented_at_ms - timestamp).max(0.0))
357                    .unwrap_or(0.0);
358
359                self.windows[window_index].frame_index += 1;
360                let frame_index = self.windows[window_index].frame_index;
361                let pending_event_time_ms =
362                    std::mem::take(&mut self.windows[window_index].pending_event_time_ms);
363                self.windows[window_index].last_non_redraw_event_at_ms = None;
364                self.windows[window_index].redraw_requested_at_ms = None;
365
366                crate::publish_frame_performance(
367                    window_id,
368                    frame_index,
369                    pending_event_time_ms,
370                    event_time_ms,
371                    runtime_time_ms,
372                    presentation_latency,
373                    &output,
374                    &self.renderer,
375                    renderer_time_ms,
376                );
377
378                if self.windows[window_index].awaiting_performance_bootstrap {
379                    self.windows[window_index].awaiting_performance_bootstrap = false;
380                    if !self.windows[window_index].redraw_requested {
381                        self.windows[window_index].redraw_requested = true;
382                        self.windows[window_index].redraw_requested_at_ms =
383                            Some(self.current_time() * 1000.0);
384                        self.pending_events.push_back(QueuedEvent {
385                            window_id,
386                            event: Event::Window(WindowEvent::RedrawRequested),
387                        });
388                    }
389                }
390
391                self.windows[window_index].title = output.title;
392                self.windows[window_index]
393                    .accessibility
394                    .update(window_id, output.semantics);
395            }
396
397            for token in crate::service_window_debug_captures(&mut self.renderer, window_id) {
398                runtime.wake_async(window_id, token)?;
399            }
400        }
401
402        if is_close {
403            runtime.remove_window(window_id)?;
404            self.renderer.remove_window(window_id);
405            crate::clear_window_performance(window_id);
406            self.pending_events
407                .retain(|pending_event| pending_event.window_id != window_id);
408            self.windows.swap_remove(window_index);
409        }
410
411        Ok(())
412    }
413}
414
415#[derive(Debug, Clone)]
416struct WindowState {
417    id: WindowId,
418    title: String,
419    open: bool,
420    awaiting_performance_bootstrap: bool,
421    redraw_requested: bool,
422    redraw_requested_at_ms: Option<f64>,
423    frame_index: u64,
424    pending_event_time_ms: f64,
425    last_non_redraw_event_at_ms: Option<f64>,
426    accessibility: AccessibilityBridge,
427}
428
429impl WindowState {
430    fn snapshot(&self) -> PlatformWindow {
431        PlatformWindow {
432            id: self.id,
433            title: self.title.clone(),
434            accessibility: self.accessibility.snapshot().cloned(),
435        }
436    }
437}
438
439#[derive(Debug, Clone)]
440struct QueuedEvent {
441    window_id: WindowId,
442    event: Event,
443}
444
445#[cfg(test)]
446mod tests {
447    use std::{cell::RefCell, f32::consts::TAU, rc::Rc};
448
449    use super::HeadlessPlatform;
450    use sui_core::{
451        AsyncWakeToken, Color, CustomEvent, Event, Rect, Result, SemanticsNode, SemanticsRole,
452        Size, TimerToken, WakeEvent, WindowEvent,
453    };
454    use sui_layout::Constraints;
455    use sui_runtime::{
456        Application, ArrangeCtx, EventCtx, MeasureCtx, PaintCtx, Runtime,
457        SceneStatisticsDetailMode, SemanticsCtx, Widget, WindowBuilder, WindowColorManagementMode,
458        WindowDynamicRangeMode, WindowOutputColorPrimaries, WindowRenderOptions,
459        WindowToneMappingMode, set_window_render_options, set_window_scene_statistics_detail_mode,
460        window_performance_snapshot,
461    };
462
463    #[derive(Default)]
464    struct Counters {
465        events: usize,
466        paints: usize,
467        timer_wakes: usize,
468        async_wakes: usize,
469        animation_wakes: usize,
470        pending_animation_frames: usize,
471        last_animation_delta: Option<f64>,
472        timer_token: Option<TimerToken>,
473        async_token: Option<AsyncWakeToken>,
474    }
475
476    struct TestRoot {
477        counters: Rc<RefCell<Counters>>,
478    }
479
480    impl Widget for TestRoot {
481        fn event(&mut self, ctx: &mut EventCtx, event: &Event) {
482            match event {
483                Event::Custom(custom) if custom.kind == "repaint" => {
484                    self.counters.borrow_mut().events += 1;
485                    ctx.request_paint();
486                }
487                Event::Custom(custom) if custom.kind == "arm-wakeups" => {
488                    let mut counters = self.counters.borrow_mut();
489                    counters.timer_token = Some(ctx.schedule_timer_after(3.0));
490                    counters.async_token = Some(ctx.register_async_wakeup());
491                }
492                Event::Custom(custom) if custom.kind == "arm-animation" => {
493                    let mut counters = self.counters.borrow_mut();
494                    counters.pending_animation_frames = 3;
495                    counters.last_animation_delta = None;
496                    ctx.request_animation_frame();
497                }
498                Event::Wake(WakeEvent::Timer { token, .. }) => {
499                    let mut counters = self.counters.borrow_mut();
500                    if counters.timer_token == Some(*token) {
501                        counters.timer_wakes += 1;
502                        ctx.request_paint();
503                        ctx.set_handled();
504                    }
505                }
506                Event::Wake(WakeEvent::Async { token, .. }) => {
507                    let mut counters = self.counters.borrow_mut();
508                    if counters.async_token == Some(*token) {
509                        counters.async_wakes += 1;
510                        ctx.request_paint();
511                        ctx.set_handled();
512                    }
513                }
514                Event::Wake(WakeEvent::AnimationFrame { delta, .. }) => {
515                    let mut counters = self.counters.borrow_mut();
516                    if counters.pending_animation_frames > 0 {
517                        counters.pending_animation_frames -= 1;
518                        counters.animation_wakes += 1;
519                        counters.last_animation_delta = Some(*delta);
520                        ctx.request_paint();
521                        if counters.pending_animation_frames > 0 {
522                            ctx.request_animation_frame();
523                        }
524                        ctx.set_handled();
525                    }
526                }
527                _ => {}
528            }
529        }
530
531        fn paint(&self, ctx: &mut PaintCtx) {
532            self.counters.borrow_mut().paints += 1;
533            ctx.clear(Color::rgba(0.08, 0.09, 0.11, 1.0));
534            ctx.fill_rect(
535                Rect::new(24.0, 24.0, 120.0, 48.0),
536                Color::rgba(0.16, 0.19, 0.25, 1.0),
537            );
538        }
539
540        fn semantics(&self, ctx: &mut SemanticsCtx) {
541            ctx.push(SemanticsNode::new(
542                ctx.widget_id(),
543                SemanticsRole::Window,
544                ctx.bounds(),
545            ));
546        }
547    }
548
549    fn build_runtime(counters: Rc<RefCell<Counters>>) -> (Runtime, sui_core::WindowId) {
550        let runtime = Application::new()
551            .window(
552                WindowBuilder::new()
553                    .title("Test")
554                    .root(TestRoot { counters }),
555            )
556            .build()
557            .unwrap();
558        let window_id = runtime.window_ids()[0];
559        (runtime, window_id)
560    }
561
562    #[test]
563    fn input_without_a_redraw_does_not_accumulate_in_the_next_frames_timing() -> Result<()> {
564        let counters = Rc::new(RefCell::new(Counters::default()));
565        let (mut runtime, window_id) = build_runtime(counters);
566        set_window_scene_statistics_detail_mode(window_id, SceneStatisticsDetailMode::Detailed);
567        let mut platform = HeadlessPlatform::new();
568        platform.run(&mut runtime)?;
569        let original_frame = platform.renderer().frames_rendered();
570
571        for _ in 0..1000 {
572            platform.dispatch_event(
573                &runtime,
574                window_id,
575                Event::Custom(CustomEvent::new("idle-input")),
576            )?;
577        }
578        platform.run(&mut runtime)?;
579        assert_eq!(platform.renderer().frames_rendered(), original_frame);
580        assert_eq!(
581            platform.windows[0].pending_event_time_ms, 0.0,
582            "input processed while no frame is pending must not be charged to a later frame"
583        );
584        assert_eq!(platform.windows[0].last_non_redraw_event_at_ms, None);
585
586        // A real repaint still includes the event that requested it, plus any
587        // other events processed before that frame is rendered.
588        platform.advance_time(1.0);
589        platform.process_event(
590            &mut runtime,
591            super::QueuedEvent {
592                window_id,
593                event: Event::Custom(CustomEvent::new("repaint")),
594            },
595        )?;
596        let repaint_cost = platform.windows[0].pending_event_time_ms;
597        assert!(repaint_cost > 0.0);
598        assert_eq!(
599            platform.windows[0].last_non_redraw_event_at_ms,
600            Some(1000.0)
601        );
602        platform.process_event(
603            &mut runtime,
604            super::QueuedEvent {
605                window_id,
606                event: Event::Custom(CustomEvent::new("more-input")),
607            },
608        )?;
609        assert!(platform.windows[0].pending_event_time_ms >= repaint_cost);
610        let expected_event_cost = platform.windows[0].pending_event_time_ms;
611        platform.run(&mut runtime)?;
612        let snapshot = window_performance_snapshot(window_id).expect("repaint timing");
613        let reported_event_cost = snapshot
614            .phase_timings
615            .iter()
616            .find(|sample| sample.phase == sui_runtime::FramePhase::Event)
617            .expect("events that contribute to a frame must still be reported")
618            .duration_ms;
619        assert_eq!(reported_event_cost, expected_event_cost);
620        assert_eq!(platform.windows[0].pending_event_time_ms, 0.0);
621        assert_eq!(platform.windows[0].last_non_redraw_event_at_ms, None);
622        Ok(())
623    }
624
625    #[test]
626    fn queued_events_reenter_the_platform_render_loop() -> Result<()> {
627        let counters = Rc::new(RefCell::new(Counters::default()));
628        let (mut runtime, window_id) = build_runtime(Rc::clone(&counters));
629        let mut platform = HeadlessPlatform::new();
630
631        let windows = platform.run(&mut runtime)?;
632        let accessibility = platform.accessibility_snapshot(window_id).unwrap();
633
634        assert_eq!(windows.len(), 1);
635        assert_eq!(windows[0].title, "Test");
636        assert_eq!(windows[0].accessibility.as_ref(), Some(accessibility));
637        assert_eq!(accessibility.nodes.len(), 1);
638        assert_eq!(accessibility.nodes[0].role, SemanticsRole::Window);
639        assert_eq!(platform.renderer().frames_rendered(), 2);
640        assert_eq!(counters.borrow().paints, 1);
641        assert!(!platform.has_pending_events());
642
643        platform.dispatch_event(
644            &runtime,
645            window_id,
646            Event::Custom(CustomEvent::new("repaint")),
647        )?;
648        let _ = platform.run(&mut runtime)?;
649
650        assert_eq!(counters.borrow().events, 1);
651        assert_eq!(counters.borrow().paints, 2);
652        assert_eq!(platform.renderer().frames_rendered(), 3);
653        assert!(!platform.has_pending_events());
654        assert!(!runtime.needs_render(window_id)?);
655
656        Ok(())
657    }
658
659    #[test]
660    fn close_requested_removes_window_from_platform_and_runtime() -> Result<()> {
661        let counters = Rc::new(RefCell::new(Counters::default()));
662        let (mut runtime, window_id) = build_runtime(counters);
663        let mut platform = HeadlessPlatform::new();
664
665        let _ = platform.run(&mut runtime)?;
666
667        platform.dispatch_event(
668            &runtime,
669            window_id,
670            Event::Window(WindowEvent::CloseRequested),
671        )?;
672        let windows = platform.run(&mut runtime)?;
673
674        assert!(windows.is_empty());
675        assert!(runtime.window_ids().is_empty());
676        assert!(runtime.needs_render(window_id).is_err());
677
678        Ok(())
679    }
680
681    #[test]
682    fn wakeups_reenter_the_platform_pump_and_trigger_repaint() -> Result<()> {
683        let counters = Rc::new(RefCell::new(Counters::default()));
684        let (mut runtime, window_id) = build_runtime(Rc::clone(&counters));
685        let mut platform = HeadlessPlatform::new();
686
687        let _ = platform.run(&mut runtime)?;
688
689        platform.dispatch_event(
690            &runtime,
691            window_id,
692            Event::Custom(CustomEvent::new("arm-wakeups")),
693        )?;
694        assert!(platform.pump(&mut runtime)?);
695
696        let async_token = counters.borrow().async_token.unwrap();
697        assert_eq!(counters.borrow().paints, 1);
698        assert_eq!(counters.borrow().timer_wakes, 0);
699
700        assert!(platform.wake_async(&mut runtime, window_id, async_token)?);
701        assert!(platform.pump(&mut runtime)?);
702
703        assert_eq!(counters.borrow().async_wakes, 1);
704        assert_eq!(counters.borrow().paints, 1);
705        assert!(platform.pump(&mut runtime)?);
706        assert_eq!(counters.borrow().paints, 2);
707
708        platform.advance_time(3.0);
709        assert!(platform.pump(&mut runtime)?);
710
711        assert_eq!(counters.borrow().timer_wakes, 1);
712        assert_eq!(counters.borrow().paints, 2);
713        assert!(platform.pump(&mut runtime)?);
714        assert_eq!(counters.borrow().paints, 3);
715
716        Ok(())
717    }
718
719    /// Paints an overbright orange and, on request, captures its window.
720    struct CaptureProbe {
721        ticket: Rc<RefCell<Option<crate::DebugCaptureTicket>>>,
722        artifact: Rc<RefCell<Option<Result<sui_render_wgpu::DebugCaptureArtifact>>>>,
723    }
724
725    impl Widget for CaptureProbe {
726        fn event(&mut self, ctx: &mut EventCtx, event: &Event) {
727            match event {
728                Event::Custom(custom) if custom.kind == "capture" => {
729                    let wake = ctx.register_async_wakeup();
730                    let request = sui_render_wgpu::DebugCaptureRequest {
731                        stage: sui_render_wgpu::DebugCaptureStage::HdrIntermediate,
732                        encoding: sui_render_wgpu::DebugCaptureEncoding::Exr,
733                        ..Default::default()
734                    };
735                    *self.ticket.borrow_mut() = Some(crate::request_window_debug_capture(
736                        ctx.window_id(),
737                        request,
738                        Some(wake),
739                    ));
740                }
741                Event::Wake(WakeEvent::Async { .. }) => {
742                    if let Some(ticket) = *self.ticket.borrow() {
743                        *self.artifact.borrow_mut() = crate::take_window_debug_capture(ticket);
744                    }
745                }
746                _ => {}
747            }
748        }
749
750        fn measure(&mut self, _ctx: &mut MeasureCtx, constraints: Constraints) -> Size {
751            constraints.clamp(Size::new(64.0, 32.0))
752        }
753
754        fn paint(&self, ctx: &mut PaintCtx) {
755            ctx.fill_bounds(Color::linear_rgba(4.0, 2.0, 0.5, 1.0));
756        }
757    }
758
759    /// Records the tone mapping in the output diagnostics each time it is
760    /// measured, observing them.
761    struct DiagnosticsProbe {
762        seen: Rc<RefCell<Vec<Option<WindowToneMappingMode>>>>,
763    }
764
765    impl Widget for DiagnosticsProbe {
766        fn measure(&mut self, ctx: &mut MeasureCtx, constraints: Constraints) -> Size {
767            let diagnostics =
768                ctx.observe(&crate::window_output_diagnostics_signal(ctx.window_id()));
769            self.seen
770                .borrow_mut()
771                .push(diagnostics.map(|diagnostics| diagnostics.requested_tone_mapping_mode));
772            constraints.clamp(Size::new(32.0, 16.0))
773        }
774    }
775
776    #[test]
777    fn widgets_observing_output_diagnostics_follow_presented_frames() -> Result<()> {
778        let seen = Rc::new(RefCell::new(Vec::new()));
779        let mut runtime = Application::new()
780            .window(
781                WindowBuilder::new()
782                    .title("Diagnostics")
783                    .root(DiagnosticsProbe {
784                        seen: Rc::clone(&seen),
785                    }),
786            )
787            .build()?;
788        let window_id = runtime.window_ids()[0];
789        set_window_render_options(
790            window_id,
791            WindowRenderOptions::new(false, 0.0)
792                .with_tone_mapping_mode(WindowToneMappingMode::Clamp),
793        );
794        let mut platform = HeadlessPlatform::new();
795        let _ = platform.run(&mut runtime)?;
796
797        // Measured before the first frame, then again once it was presented.
798        assert_eq!(
799            *seen.borrow(),
800            vec![None, Some(WindowToneMappingMode::Clamp)]
801        );
802        assert!(
803            !runtime.needs_render(window_id)?,
804            "unchanged diagnostics do not invalidate again"
805        );
806
807        set_window_render_options(
808            window_id,
809            WindowRenderOptions::new(false, 0.0)
810                .with_tone_mapping_mode(WindowToneMappingMode::Reinhard),
811        );
812        platform.dispatch_event(
813            &runtime,
814            window_id,
815            Event::Window(WindowEvent::RedrawRequested),
816        )?;
817        let _ = platform.run(&mut runtime)?;
818        assert_eq!(
819            seen.borrow().last().copied().flatten(),
820            Some(WindowToneMappingMode::Reinhard)
821        );
822        Ok(())
823    }
824
825    /// Paints its bounds SDR white.
826    struct White;
827
828    impl Widget for White {
829        fn measure(&mut self, _ctx: &mut MeasureCtx, constraints: Constraints) -> Size {
830            constraints.clamp(Size::new(32.0, 16.0))
831        }
832
833        fn paint(&self, ctx: &mut PaintCtx) {
834            ctx.fill_bounds(Color::WHITE);
835        }
836    }
837
838    fn white_window() -> Result<(Runtime, sui_core::WindowId)> {
839        let runtime = Application::new()
840            .window(WindowBuilder::new().title("Display").root(White))
841            .build()?;
842        let window_id = runtime.window_ids()[0];
843        Ok((runtime, window_id))
844    }
845
846    #[test]
847    fn headless_windows_render_for_the_display_they_are_given() -> Result<()> {
848        use sui_render_wgpu::{
849            DebugCaptureArtifact, DebugCaptureEncoding, DebugCaptureRequest, DebugCaptureStage,
850            DisplayCapabilities, OutputGamut, OutputStrategy,
851        };
852        use sui_runtime::{OutputColorRange, window_output_color_range};
853
854        // Without a display, windows render for SDR.
855        let (mut runtime, window_id) = white_window()?;
856        let _ = HeadlessPlatform::new().run(&mut runtime)?;
857        let diagnostics = crate::window_output_diagnostics(window_id).expect("diagnostics");
858        assert!(matches!(
859            diagnostics.active_output_strategy,
860            OutputStrategy::SdrSurface { .. }
861        ));
862        assert_eq!(diagnostics.output_gamut, OutputGamut::Srgb);
863        assert_eq!(
864            window_output_color_range(window_id),
865            Some(OutputColorRange::Standard)
866        );
867
868        // On an HDR display they present extended range, report it, and
869        // capture the final output as scRGB with SDR white at its brightness.
870        let (mut runtime, window_id) = white_window()?;
871        let mut platform = HeadlessPlatform::new()
872            .with_display_capabilities(DisplayCapabilities::hdr(1000.0, 250.0));
873        let _ = platform.run(&mut runtime)?;
874        let diagnostics = crate::window_output_diagnostics(window_id).expect("diagnostics");
875        assert!(
876            matches!(
877                diagnostics.active_output_strategy,
878                OutputStrategy::HdrNativeSurface { .. }
879            ),
880            "{:?}",
881            diagnostics.active_output_strategy
882        );
883        assert_eq!(
884            diagnostics.display_capabilities.max_luminance_nits,
885            Some(1000.0)
886        );
887        // Encoded in sRGB primaries, scRGB still shows the display's colors.
888        assert_eq!(
889            diagnostics.display_capabilities.preferred_primaries,
890            sui_render_wgpu::DisplayColorPrimaries::Srgb
891        );
892        assert_eq!(diagnostics.output_gamut, OutputGamut::Display);
893        assert_eq!(
894            window_output_color_range(window_id),
895            Some(OutputColorRange::HighDynamicRange)
896        );
897        let DebugCaptureArtifact::HdrLinearRgbaF32(image) = platform.capture_debug_frame(
898            window_id,
899            DebugCaptureRequest {
900                stage: DebugCaptureStage::FinalComposed,
901                encoding: DebugCaptureEncoding::Exr,
902                ..Default::default()
903            },
904        )?
905        else {
906            panic!("an HDR final output is linear floating point");
907        };
908        let white = diagnostics.requested_sdr_content_brightness_nits / 80.0;
909        assert!(
910            (image.pixels()[0] - white).abs() < 0.01,
911            "SDR white is {white} in scRGB, got {}",
912            image.pixels()[0]
913        );
914        Ok(())
915    }
916
917    #[test]
918    fn apps_can_capture_their_window_after_a_redraw() -> Result<()> {
919        let ticket = Rc::new(RefCell::new(None));
920        let artifact = Rc::new(RefCell::new(None));
921        let mut runtime = Application::new()
922            .window(WindowBuilder::new().title("Capture").root(CaptureProbe {
923                ticket: Rc::clone(&ticket),
924                artifact: Rc::clone(&artifact),
925            }))
926            .build()?;
927        let window_id = runtime.window_ids()[0];
928        let mut platform = HeadlessPlatform::new();
929        let _ = platform.run(&mut runtime)?;
930
931        platform.dispatch_event(
932            &runtime,
933            window_id,
934            Event::Custom(CustomEvent::new("capture")),
935        )?;
936        let _ = platform.run(&mut runtime)?;
937
938        let result = artifact
939            .borrow_mut()
940            .take()
941            .expect("the capture was delivered");
942        let sui_render_wgpu::DebugCaptureArtifact::HdrLinearRgbaF32(image) = result? else {
943            panic!("an HDR intermediate capture is linear floating point");
944        };
945        let brightest = image.pixels().iter().copied().fold(0.0_f32, f32::max);
946        assert!(
947            brightest > 3.9,
948            "the capture keeps extended range: {brightest}"
949        );
950        Ok(())
951    }
952
953    #[test]
954    fn animation_frame_request_keeps_headless_pumping_until_completion() -> Result<()> {
955        let counters = Rc::new(RefCell::new(Counters::default()));
956        let (mut runtime, window_id) = build_runtime(Rc::clone(&counters));
957        let mut platform = HeadlessPlatform::new();
958
959        let _ = platform.run(&mut runtime)?;
960        assert_eq!(counters.borrow().paints, 1);
961
962        platform.dispatch_event(
963            &runtime,
964            window_id,
965            Event::Custom(CustomEvent::new("arm-animation")),
966        )?;
967        let _ = platform.run(&mut runtime)?;
968
969        let counters = counters.borrow();
970        assert_eq!(counters.animation_wakes, 3);
971        assert_eq!(counters.pending_animation_frames, 0);
972        assert_eq!(counters.paints, 4);
973        assert_eq!(counters.last_animation_delta, Some(1.0 / 120.0));
974        assert!((platform.current_time() - (2.0 / 120.0)).abs() < 1e-9);
975
976        Ok(())
977    }
978
979    #[test]
980    fn feather_width_is_configurable_without_renderer_access() {
981        let mut platform = HeadlessPlatform::new()
982            .with_feathering_enabled(false)
983            .with_feather_width(2.5);
984
985        assert!(!platform.feathering_enabled());
986        assert_eq!(platform.feather_width(), 2.5);
987
988        platform.set_feather_width(-4.0);
989        platform.set_feathering_enabled(true);
990
991        assert!(platform.feathering_enabled());
992        assert_eq!(platform.feather_width(), 0.0);
993    }
994
995    const HDR_BENCH_STEP_S: f64 = 1.0 / 120.0;
996    const HDR_BENCH_FRAMES: usize = 120;
997    const HDR_BENCH_WIDTH: f32 = 1280.0;
998    const HDR_BENCH_HEIGHT: f32 = 720.0;
999    const HDR_BENCH_COLS: usize = 48;
1000    const HDR_BENCH_ROWS: usize = 27;
1001
1002    struct AnimatedHdrGrid {
1003        phase: f32,
1004        timer: Option<TimerToken>,
1005    }
1006
1007    impl AnimatedHdrGrid {
1008        fn new() -> Self {
1009            Self {
1010                phase: 0.0,
1011                timer: None,
1012            }
1013        }
1014
1015        fn arm(&mut self, ctx: &mut EventCtx) {
1016            if self.timer.is_none() {
1017                self.timer = Some(ctx.schedule_timer_after(HDR_BENCH_STEP_S));
1018            }
1019        }
1020    }
1021
1022    impl Widget for AnimatedHdrGrid {
1023        fn event(&mut self, ctx: &mut EventCtx, event: &Event) {
1024            match event {
1025                Event::Window(WindowEvent::Resized(_)) => {
1026                    self.arm(ctx);
1027                    ctx.request_paint();
1028                }
1029                Event::Wake(WakeEvent::Timer { token, .. }) if self.timer == Some(*token) => {
1030                    self.phase = (self.phase + 0.035) % TAU;
1031                    self.timer = Some(ctx.schedule_timer_after(HDR_BENCH_STEP_S));
1032                    ctx.request_paint();
1033                    ctx.set_handled();
1034                }
1035                _ => {}
1036            }
1037        }
1038
1039        fn measure(&mut self, _ctx: &mut MeasureCtx, constraints: Constraints) -> Size {
1040            constraints.clamp(Size::new(HDR_BENCH_WIDTH, HDR_BENCH_HEIGHT))
1041        }
1042
1043        fn arrange(&mut self, _ctx: &mut ArrangeCtx, _bounds: Rect) {}
1044
1045        fn paint(&self, ctx: &mut PaintCtx) {
1046            ctx.clear(Color::linear_rgba(0.08, 0.09, 0.11, 1.0));
1047            let cell_w = HDR_BENCH_WIDTH / HDR_BENCH_COLS as f32;
1048            let cell_h = HDR_BENCH_HEIGHT / HDR_BENCH_ROWS as f32;
1049            for row in 0..HDR_BENCH_ROWS {
1050                for col in 0..HDR_BENCH_COLS {
1051                    let x = col as f32 * cell_w;
1052                    let y = row as f32 * cell_h;
1053                    let t = self.phase + row as f32 * 0.19 + col as f32 * 0.11;
1054                    let r = 0.5 + 3.5 * (0.5 + 0.5 * t.sin());
1055                    let g = 0.25 + 2.25 * (0.5 + 0.5 * (t * 1.3).cos());
1056                    let b = 0.15 + 1.85 * (0.5 + 0.5 * (t * 0.7 + 1.2).sin());
1057                    ctx.fill_rect(
1058                        Rect::new(x, y, cell_w + 1.0, cell_h + 1.0),
1059                        Color::linear_rgba(r, g, b, 1.0),
1060                    );
1061                }
1062            }
1063        }
1064
1065        fn semantics(&self, ctx: &mut SemanticsCtx) {
1066            let mut node = SemanticsNode::new(ctx.widget_id(), SemanticsRole::Window, ctx.bounds());
1067            node.name = Some("Animated HDR Grid".to_string());
1068            ctx.push(node);
1069        }
1070    }
1071
1072    fn mean(values: &[f64]) -> f64 {
1073        if values.is_empty() {
1074            0.0
1075        } else {
1076            values.iter().sum::<f64>() / values.len() as f64
1077        }
1078    }
1079
1080    fn percentile(sorted: &[f64], p: f64) -> f64 {
1081        if sorted.is_empty() {
1082            return 0.0;
1083        }
1084        let rank = ((sorted.len() - 1) as f64 * p).round() as usize;
1085        sorted[rank]
1086    }
1087
1088    #[test]
1089    #[ignore = "hardware Vulkan benchmark; run explicitly on a machine with a working headless GPU path"]
1090    fn steady_state_headless_hdr_grid_benchmark_emits_advancing_frames() -> Result<()> {
1091        let options = WindowRenderOptions::new(true, 1.0)
1092            .with_color_management_mode(WindowColorManagementMode::PreferHdr)
1093            .with_output_color_primaries(WindowOutputColorPrimaries::DisplayP3)
1094            .with_dynamic_range_mode(WindowDynamicRangeMode::HighDynamicRange)
1095            .with_tone_mapping_mode(WindowToneMappingMode::Automatic);
1096
1097        let runtime = Application::new()
1098            .window(
1099                WindowBuilder::new()
1100                    .title("Animated HDR Grid")
1101                    .root(AnimatedHdrGrid::new()),
1102            )
1103            .build()
1104            .unwrap();
1105        let window_id = runtime.window_ids()[0];
1106        set_window_render_options(window_id, options);
1107        set_window_scene_statistics_detail_mode(window_id, SceneStatisticsDetailMode::Detailed);
1108
1109        let mut runtime = runtime;
1110        let mut platform = HeadlessPlatform::new();
1111        let mut totals = Vec::with_capacity(HDR_BENCH_FRAMES);
1112        let mut commands = Vec::with_capacity(HDR_BENCH_FRAMES);
1113        let mut dirty = Vec::with_capacity(HDR_BENCH_FRAMES);
1114        let mut last_frame = 0u64;
1115        let mut iterations = 0usize;
1116        let max_iterations = 20_000usize;
1117
1118        while totals.len() < HDR_BENCH_FRAMES && iterations < max_iterations {
1119            let _ = platform.pump(&mut runtime)?;
1120            if let Some(snapshot) = window_performance_snapshot(window_id)
1121                && snapshot.frame_index != last_frame
1122            {
1123                last_frame = snapshot.frame_index;
1124                totals.push(snapshot.total_time_ms);
1125                commands.push(snapshot.scene.command_count as f64);
1126                dirty.push(snapshot.scene.dirty_coverage as f64);
1127            }
1128            platform.advance_time(HDR_BENCH_STEP_S);
1129            iterations += 1;
1130        }
1131
1132        let mut totals_sorted = totals.clone();
1133        totals_sorted.sort_by(|a, b| a.total_cmp(b));
1134
1135        println!("benchmark=steady-state-headless-hdr-grid");
1136        println!("iterations={iterations}");
1137        println!("frames={}", totals.len());
1138        println!("nominal_fps={:.2}", 1.0 / HDR_BENCH_STEP_S);
1139        println!("frame_total_ms_avg={:.3}", mean(&totals));
1140        println!("frame_total_ms_p50={:.3}", percentile(&totals_sorted, 0.50));
1141        println!("frame_total_ms_p95={:.3}", percentile(&totals_sorted, 0.95));
1142        println!(
1143            "frame_total_ms_max={:.3}",
1144            totals_sorted.last().copied().unwrap_or(0.0)
1145        );
1146        println!("command_count_avg={:.1}", mean(&commands));
1147        println!("dirty_coverage_avg={:.2}", mean(&dirty));
1148
1149        assert_eq!(
1150            totals.len(),
1151            HDR_BENCH_FRAMES,
1152            "expected {} benchmark frames, got {} after {} iterations",
1153            HDR_BENCH_FRAMES,
1154            totals.len(),
1155            iterations
1156        );
1157        assert!(mean(&totals) > 0.0, "expected positive frame timings");
1158
1159        Ok(())
1160    }
1161}