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 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 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 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 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 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 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 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 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 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 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 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 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}