1#[path = "desktop/budget_recovery.rs"]
10mod budget_recovery;
11#[path = "desktop/capture.rs"]
12mod capture;
13#[path = "desktop/draw_plan.rs"]
14mod draw_plan;
15#[path = "desktop/geometry.rs"]
16mod geometry;
17#[path = "desktop/images.rs"]
18mod images;
19#[path = "desktop/keyboard.rs"]
20mod keyboard;
21#[path = "desktop/pointer.rs"]
22mod pointer;
23#[cfg(feature = "text")]
24#[path = "desktop/text.rs"]
25mod text;
26#[path = "desktop/three_d.rs"]
27mod three_d;
28#[path = "desktop/timing.rs"]
29mod timing;
30#[path = "desktop/window.rs"]
31mod window;
32use keyboard::map_key;
33#[cfg(test)]
34use winit::keyboard::KeyCode;
35
36pub use geometry::{DesktopScreenError, DesktopScreenMode, DesktopScreenUpdates};
37pub use images::DesktopImageError;
38pub use pointer::DesktopPointerError;
39pub use sim_engine::FrameCacheBudget;
40#[cfg(feature = "text")]
41pub use text::{DesktopTextError, DesktopTextUpdates};
42pub use three_d::{DesktopThreeDError, DesktopThreeDUpdates};
43pub use timing::{DesktopGpuTimingSample, DesktopGpuTimings};
44
45use std::{error::Error, fmt, sync::Arc, time::Instant};
46
47use sim_engine::{
48 FrameBudget, FrameComposerError, FramePassOptions, FrameReport, GpuTimingSource,
49 Mesh3dRenderReport, RenderStatus, RendererConfigurationError, RendererFrameError,
50 RendererInitError, RendererPresentMode, RendererSurfaceStatus, WgpuRenderer,
51 WgpuRendererOptions,
52};
53use winit::{
54 application::ApplicationHandler,
55 dpi::{LogicalSize, PhysicalPosition, PhysicalSize},
56 error::{EventLoopError, OsError},
57 event::{DeviceEvent, DeviceId, ElementState, MouseScrollDelta, WindowEvent},
58 event_loop::{ActiveEventLoop, EventLoop},
59 keyboard::PhysicalKey,
60 window::{Window, WindowId},
61};
62
63use crate::{
64 app::Application,
65 headless::{
66 BeginFrameRejection, FrameOutcome, FrameRequest, FrameTransition, HeadlessRunner,
67 LogicFrameReport, RunnerBuildError,
68 },
69 identity::{WorldFactoryId, WorldGeneration},
70 input::{
71 Action, ButtonState, InputEvent, PhysicalKeyCode, PointerCapture, RelativePointerMotion,
72 RelativePointerMotionError, SUPPORTED_PHYSICAL_KEY_COUNT, physical_key_index,
73 },
74 render::FrameLimits,
75 three_d::ThreeDRenderLimits,
76};
77
78use capture::DesktopCapture;
79use images::{DesktopImages, ScreenPresentationError};
80use pointer::DesktopPointerGeometry;
81use three_d::DesktopThreeD;
82
83const DEFAULT_TITLE: &str = "Sim;Logic";
84const DEFAULT_WIDTH: f64 = 1_280.0;
85const DEFAULT_HEIGHT: f64 = 720.0;
86const MAX_TITLE_BYTES: usize = 256;
87
88#[derive(Debug, Clone, PartialEq)]
90pub struct DesktopConfig {
91 title: String,
92 logical_width: f64,
93 logical_height: f64,
94 present_mode: RendererPresentMode,
95 frame_cache: FrameCacheBudget,
96 screen_mode: DesktopScreenMode,
97 text_batching: bool,
98 gpu_timing: bool,
99 window_mode: crate::window::WindowMode,
100}
101
102impl Default for DesktopConfig {
103 fn default() -> Self {
104 Self {
105 title: DEFAULT_TITLE.to_owned(),
106 logical_width: DEFAULT_WIDTH,
107 logical_height: DEFAULT_HEIGHT,
108 present_mode: RendererPresentMode::Vsync,
109 frame_cache: FrameCacheBudget::default(),
110 screen_mode: DesktopScreenMode::default(),
111 text_batching: true,
112 gpu_timing: false,
113 window_mode: crate::window::WindowMode::Windowed,
114 }
115 }
116}
117
118impl DesktopConfig {
119 pub fn set_text_batching(&mut self, enabled: bool) -> &mut Self {
123 self.text_batching = enabled;
124 self
125 }
126
127 pub const fn text_batching(&self) -> bool {
129 self.text_batching
130 }
131
132 pub fn set_screen_mode(&mut self, mode: DesktopScreenMode) -> &mut Self {
136 self.screen_mode = mode;
137 self
138 }
139
140 pub const fn screen_mode(&self) -> DesktopScreenMode {
142 self.screen_mode
143 }
144
145 pub fn set_window_mode(&mut self, mode: crate::window::WindowMode) -> &mut Self {
148 self.window_mode = mode;
149 self
150 }
151
152 pub const fn window_mode(&self) -> crate::window::WindowMode {
154 self.window_mode
155 }
156
157 pub fn new(
159 title: impl Into<String>,
160 logical_width: f64,
161 logical_height: f64,
162 ) -> Result<Self, DesktopConfigError> {
163 let title = title.into();
164 validate_title(&title)?;
165 validate_logical_size(logical_width, logical_height)?;
166 Ok(Self {
167 title,
168 logical_width,
169 logical_height,
170 present_mode: RendererPresentMode::Vsync,
171 frame_cache: FrameCacheBudget::default(),
172 screen_mode: DesktopScreenMode::default(),
173 text_batching: true,
174 gpu_timing: false,
175 window_mode: crate::window::WindowMode::Windowed,
176 })
177 }
178
179 pub fn set_present_mode(&mut self, present_mode: RendererPresentMode) -> &mut Self {
181 self.present_mode = present_mode;
182 self
183 }
184
185 pub fn set_frame_cache_budget(&mut self, budget: FrameCacheBudget) -> &mut Self {
191 self.frame_cache = budget;
192 self
193 }
194
195 pub const fn frame_cache_budget(&self) -> FrameCacheBudget {
197 self.frame_cache
198 }
199
200 pub fn set_gpu_timing(&mut self, enabled: bool) -> &mut Self {
207 self.gpu_timing = enabled;
208 self
209 }
210
211 pub const fn gpu_timing(&self) -> bool {
213 self.gpu_timing
214 }
215
216 pub fn title(&self) -> &str {
218 &self.title
219 }
220
221 pub const fn logical_width(&self) -> f64 {
223 self.logical_width
224 }
225
226 pub const fn logical_height(&self) -> f64 {
228 self.logical_height
229 }
230
231 pub const fn present_mode(&self) -> RendererPresentMode {
233 self.present_mode
234 }
235}
236
237#[derive(Debug, Clone, PartialEq)]
239pub enum DesktopConfigError {
240 EmptyTitle,
242 TitleTooLong {
244 limit: usize,
246 },
247 InvalidLogicalSize {
249 width: f64,
251 height: f64,
253 },
254}
255
256impl fmt::Display for DesktopConfigError {
257 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
258 match self {
259 Self::EmptyTitle => formatter.write_str("desktop window title must not be empty"),
260 Self::TitleTooLong { limit } => {
261 write!(
262 formatter,
263 "desktop window title exceeds {limit} UTF-8 bytes"
264 )
265 }
266 Self::InvalidLogicalSize { width, height } => write!(
267 formatter,
268 "desktop logical size must be finite and positive, got {width}x{height}"
269 ),
270 }
271 }
272}
273
274impl Error for DesktopConfigError {}
275
276#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
278#[non_exhaustive]
279pub enum DesktopExitReason {
280 #[default]
282 WindowClosed,
283 ApplicationRequested,
286}
287
288#[derive(Debug, Default)]
290pub struct DesktopRunReport {
291 logic_frames: u64,
292 drawn_frames: u64,
293 skipped_frames: u64,
294 committed_transitions: u64,
295 device_recoveries: u64,
296 budget_rejections: u64,
297 exit_reason: DesktopExitReason,
298 last_logic_frame: Option<LogicFrameReport>,
299 last_render_frame: Option<FrameReport>,
300 last_screen_updates: Option<DesktopScreenUpdates>,
301 last_screen_extraction: Option<crate::ScreenExtractionUpdates>,
302 #[cfg(feature = "text")]
303 last_text_updates: Option<DesktopTextUpdates>,
304 renderer_description: Option<String>,
305 last_three_d_frame: Option<Mesh3dRenderReport>,
306 last_three_d_updates: Option<DesktopThreeDUpdates>,
307 three_d_updates: DesktopThreeDUpdates,
308 gpu_timings: DesktopGpuTimings,
309}
310
311impl DesktopRunReport {
312 #[cfg(feature = "text")]
315 pub const fn last_text_updates(&self) -> Option<DesktopTextUpdates> {
316 self.last_text_updates
317 }
318
319 pub fn renderer_description(&self) -> Option<&str> {
322 self.renderer_description.as_deref()
323 }
324 pub const fn last_screen_updates(&self) -> Option<DesktopScreenUpdates> {
327 self.last_screen_updates
328 }
329
330 pub const fn last_screen_extraction(&self) -> Option<crate::ScreenExtractionUpdates> {
335 self.last_screen_extraction
336 }
337 pub const fn budget_rejections(&self) -> u64 {
339 self.budget_rejections
340 }
341 pub const fn logic_frames(&self) -> u64 {
343 self.logic_frames
344 }
345
346 pub const fn drawn_frames(&self) -> u64 {
348 self.drawn_frames
349 }
350
351 pub const fn skipped_frames(&self) -> u64 {
353 self.skipped_frames
354 }
355
356 pub const fn committed_transitions(&self) -> u64 {
358 self.committed_transitions
359 }
360
361 pub const fn device_recoveries(&self) -> u64 {
363 self.device_recoveries
364 }
365
366 pub const fn exit_reason(&self) -> DesktopExitReason {
368 self.exit_reason
369 }
370
371 pub const fn last_logic_frame(&self) -> Option<&LogicFrameReport> {
373 self.last_logic_frame.as_ref()
374 }
375
376 pub const fn last_render_frame(&self) -> Option<FrameReport> {
379 self.last_render_frame
380 }
381
382 pub const fn last_three_d_frame(&self) -> Option<Mesh3dRenderReport> {
388 self.last_three_d_frame
389 }
390
391 pub const fn last_three_d_updates(&self) -> Option<DesktopThreeDUpdates> {
395 self.last_three_d_updates
396 }
397
398 pub const fn three_d_updates(&self) -> DesktopThreeDUpdates {
402 self.three_d_updates
403 }
404
405 pub const fn gpu_timings(&self) -> &DesktopGpuTimings {
409 &self.gpu_timings
410 }
411
412 fn record_application_exit(&mut self, report: LogicFrameReport) {
413 self.exit_reason = DesktopExitReason::ApplicationRequested;
414 self.last_logic_frame = Some(report);
415 }
416}
417
418#[derive(Debug)]
420pub enum DesktopRunError {
421 Runner(RunnerBuildError),
423 EventLoop(EventLoopError),
425 Window(OsError),
427 WindowMode(crate::window::WindowModeFailure),
429 RendererConfiguration(RendererConfigurationError),
431 RendererConfigurationAfterFrame {
434 error: RendererConfigurationError,
436 logic_frame: Box<LogicFrameReport>,
438 },
439 LogicalViewport(sim_engine::LogicalViewportError),
441 Pointer(DesktopPointerError),
443 RendererInitialization(RendererInitError),
445 InputEventLimitExceeded {
447 limit: usize,
449 },
450 InputBufferAllocationFailed,
452 BeginFrame(BeginFrameRejection),
454 RuntimeInvariant,
456 LogicFrame {
460 report: Box<LogicFrameReport>,
462 diagnostic_presentation: Box<Result<FrameReport, FrameComposerError>>,
464 },
465 Presentation {
468 error: FrameComposerError,
470 logic_frame: Box<LogicFrameReport>,
472 },
473 ImagePreparation {
477 error: DesktopImageError,
479 logic_frame: Box<LogicFrameReport>,
481 },
482 #[cfg(feature = "text")]
485 TextPreparation {
486 error: DesktopTextError,
488 logic_frame: Box<LogicFrameReport>,
490 },
491 ThreeDPreparation {
495 error: DesktopThreeDError,
497 logic_frame: Box<LogicFrameReport>,
499 },
500 Recovery {
503 error: RendererInitError,
505 logic_frame: Box<LogicFrameReport>,
507 },
508}
509
510impl fmt::Display for DesktopRunError {
511 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
512 match self {
513 Self::Runner(error) => write!(formatter, "logical runner failed: {error}"),
514 Self::EventLoop(error) => write!(formatter, "desktop event loop failed: {error}"),
515 Self::Window(error) => write!(formatter, "desktop window failed: {error}"),
516 Self::WindowMode(error) => {
517 write!(formatter, "initial window mode unavailable: {error:?}")
518 }
519 Self::RendererConfiguration(error) => {
520 write!(formatter, "renderer configuration failed: {error}")
521 }
522 Self::RendererConfigurationAfterFrame { error, .. } => {
523 write!(
524 formatter,
525 "post-frame renderer configuration failed: {error}"
526 )
527 }
528 Self::LogicalViewport(error) => write!(formatter, "logical viewport failed: {error}"),
529 Self::Pointer(error) => write!(formatter, "desktop pointer conversion failed: {error}"),
530 Self::RendererInitialization(error) => {
531 write!(formatter, "renderer initialization failed: {error}")
532 }
533 Self::InputEventLimitExceeded { limit } => write!(
534 formatter,
535 "desktop input exceeded its limit of {limit} mapped events"
536 ),
537 Self::InputBufferAllocationFailed => {
538 formatter.write_str("desktop input buffer allocation failed")
539 }
540 Self::BeginFrame(error) => write!(formatter, "logical frame was rejected: {error}"),
541 Self::RuntimeInvariant => {
542 formatter.write_str("desktop adapter lost required runtime state")
543 }
544 Self::LogicFrame { report, .. } => write!(
545 formatter,
546 "logical frame {} failed after it began",
547 report.frame_index()
548 ),
549 Self::Presentation { error, .. } => {
550 write!(formatter, "frame presentation failed: {error}")
551 }
552 Self::ImagePreparation { error, .. } => {
553 write!(formatter, "desktop image preparation failed: {error}")
554 }
555 #[cfg(feature = "text")]
556 Self::TextPreparation { error, .. } => {
557 write!(formatter, "desktop text preparation failed: {error}")
558 }
559 Self::ThreeDPreparation { error, .. } => {
560 write!(formatter, "desktop 3D preparation failed: {error}")
561 }
562 Self::Recovery { error, .. } => write!(formatter, "renderer recovery failed: {error}"),
563 }
564 }
565}
566
567impl Error for DesktopRunError {
568 fn source(&self) -> Option<&(dyn Error + 'static)> {
569 match self {
570 Self::Runner(error) => Some(error),
571 Self::EventLoop(error) => Some(error),
572 Self::Window(error) => Some(error),
573 Self::WindowMode(_) => None,
574 Self::RendererConfiguration(error) => Some(error),
575 Self::RendererConfigurationAfterFrame { error, .. } => Some(error),
576 Self::LogicalViewport(error) => Some(error),
577 Self::Pointer(error) => Some(error),
578 Self::RendererInitialization(error) => Some(error),
579 Self::BeginFrame(error) => Some(error),
580 Self::Presentation { error, .. } => Some(error),
581 Self::ImagePreparation { error, .. } => Some(error),
582 #[cfg(feature = "text")]
583 Self::TextPreparation { error, .. } => Some(error),
584 Self::ThreeDPreparation { error, .. } => Some(error),
585 Self::Recovery { error, .. } => Some(error),
586 Self::InputEventLimitExceeded { .. }
587 | Self::InputBufferAllocationFailed
588 | Self::RuntimeInvariant => None,
589 Self::LogicFrame { report, .. } => report
590 .failure()
591 .map(|error| error as &(dyn Error + 'static)),
592 }
593 }
594}
595
596pub(crate) fn run<A: Action>(
597 application: Application<A>,
598 initial: WorldFactoryId,
599 config: DesktopConfig,
600) -> Result<DesktopRunReport, DesktopRunError> {
601 let input_event_limit = application.config.input_event_limit();
602 let frame_budget = frame_budget(application.config.render().frame_limits());
603 let three_d_limits = application.config.render().three_d();
604 let runner = application
605 .build_headless(initial)
606 .map_err(DesktopRunError::Runner)?;
607 let event_loop = EventLoop::new().map_err(DesktopRunError::EventLoop)?;
608 let mut desktop = DesktopHost::new(
609 runner,
610 config,
611 input_event_limit,
612 frame_budget,
613 three_d_limits,
614 );
615 event_loop
616 .run_app(&mut desktop)
617 .map_err(DesktopRunError::EventLoop)?;
618 desktop.collect_gpu_timings();
619 desktop.report.renderer_description = desktop
620 .renderer
621 .as_ref()
622 .map(|renderer| format!("{:?}", renderer.diagnostics()));
623 match desktop.fatal {
624 Some(error) => Err(error),
625 None => Ok(desktop.report),
626 }
627}
628
629struct DesktopHost<A: Action> {
630 runner: HeadlessRunner<A>,
631 config: DesktopConfig,
632 input_event_limit: usize,
633 frame_budget: FrameBudget,
634 window: Option<Arc<Window>>,
635 renderer: Option<WgpuRenderer>,
636 images: DesktopImages,
637 three_d: DesktopThreeD,
638 three_d_limits: ThreeDRenderLimits,
639 pending_events: Vec<InputEvent>,
640 input_failure: Option<InputBufferFailure>,
641 held_keys: [bool; SUPPORTED_PHYSICAL_KEY_COUNT],
642 pointer_geometry: DesktopPointerGeometry,
643 capture: DesktopCapture,
644 window_occluded: bool,
645 surface_waiting: bool,
646 last_frame: Instant,
647 report: DesktopRunReport,
648 fatal: Option<DesktopRunError>,
649}
650
651impl<A: Action> DesktopHost<A> {
652 fn new(
653 runner: HeadlessRunner<A>,
654 config: DesktopConfig,
655 input_event_limit: usize,
656 frame_budget: FrameBudget,
657 three_d_limits: ThreeDRenderLimits,
658 ) -> Self {
659 let mut images = DesktopImages::new();
660 images.screen_mode = config.screen_mode;
661 images.text_batching = config.text_batching;
662 Self {
663 runner,
664 config,
665 input_event_limit,
666 frame_budget,
667 window: None,
668 renderer: None,
669 images,
670 three_d: DesktopThreeD::new(),
671 three_d_limits,
672 pending_events: Vec::new(),
673 input_failure: None,
674 held_keys: [false; SUPPORTED_PHYSICAL_KEY_COUNT],
675 pointer_geometry: DesktopPointerGeometry::empty(),
676 capture: DesktopCapture::new(),
677 window_occluded: false,
678 surface_waiting: false,
679 last_frame: Instant::now(),
680 report: DesktopRunReport::default(),
681 fatal: None,
682 }
683 }
684
685 fn stop(&mut self, event_loop: &ActiveEventLoop, error: DesktopRunError) {
686 self.release_capture();
687 if self.fatal.is_none() {
688 self.fatal = Some(error);
689 }
690 event_loop.exit();
691 }
692
693 fn release_capture(&mut self) {
694 let status = self.capture.release();
695 self.runner.with_pointer_capture(|capture| {
696 capture.release();
697 capture.acknowledge(status);
698 });
699 }
700
701 fn synchronize_capture(&mut self) {
702 if self
703 .runner
704 .app_resource::<PointerCapture>()
705 .is_some_and(PointerCapture::pending)
706 {
707 let was_captured = self.capture.accepts_motion();
708 let backend = &mut self.capture;
709 self.runner
710 .with_pointer_capture(|capture| backend.synchronize(capture));
711 self.collect_capture_change(was_captured, self.capture.accepts_motion());
712 }
713 }
714
715 fn collect_capture_change(&mut self, was_captured: bool, captured: bool) {
716 if was_captured != captured && self.collect_input(InputEvent::PointerLeft) {
723 self.pointer_geometry.cursor_left();
724 }
725 }
726
727 fn collect_relative_motion(&mut self, delta: (f64, f64)) -> Result<(), DesktopPointerError> {
728 if !self.capture.accepts_motion() || self.input_failure.is_some() {
729 return Ok(());
730 }
731 let motion = RelativePointerMotion::new(delta.0, delta.1)
732 .map_err(DesktopPointerError::RelativeMotion)?;
733 self.collect_input(InputEvent::relative_pointer_motion(motion));
734 Ok(())
735 }
736
737 fn collect_mouse_wheel(&mut self, delta: MouseScrollDelta) -> Result<(), DesktopPointerError> {
738 if self.input_failure.is_some() {
739 return Ok(());
740 }
741 let event = self.pointer_geometry.mouse_wheel(delta)?;
744 self.collect_input(event);
745 Ok(())
746 }
747
748 fn collect_gpu_timings(&mut self) {
749 if let Some(renderer) = self.renderer.as_mut() {
750 self.report.gpu_timings.collect(renderer);
751 }
752 }
753
754 fn collect_key(
755 &mut self,
756 physical_key: PhysicalKey,
757 state: ElementState,
758 is_synthetic: bool,
759 repeat: bool,
760 ) {
761 if is_synthetic || (repeat && state == ElementState::Pressed) {
766 return;
767 }
768 let Some(key) = map_key(physical_key) else {
769 return;
770 };
771 self.collect_physical_key(key, map_button_state(state));
772 }
773
774 fn collect_physical_key(&mut self, key: PhysicalKeyCode, state: ButtonState) {
775 if self.collect_input(InputEvent::key(key, state)) {
776 self.held_keys[physical_key_index(key)] = state == ButtonState::Pressed;
777 }
778 }
779
780 fn collect_input(&mut self, event: InputEvent) -> bool {
781 if self.input_failure.is_some() {
782 return false;
783 }
784 if let InputEvent::RelativePointerMotion { motion } = event
785 && let Some(InputEvent::RelativePointerMotion { motion: previous }) =
786 self.pending_events.last_mut()
787 {
788 match previous.checked_add(motion) {
789 Ok(sum) => *previous = sum,
790 Err(error) => {
791 self.input_failure = Some(InputBufferFailure::RelativeMotion(error));
792 return false;
793 }
794 }
795 return true;
796 }
797 if matches!(event, InputEvent::PointerMoved { .. })
800 && let Some(last @ InputEvent::PointerMoved { .. }) = self.pending_events.last_mut()
801 {
802 *last = event;
803 return true;
804 }
805 if self.pending_events.len() >= self.input_event_limit {
806 self.input_failure = Some(InputBufferFailure::Limit);
807 return false;
808 }
809 if self.pending_events.try_reserve(1).is_err() {
810 self.input_failure = Some(InputBufferFailure::Allocation);
811 return false;
812 }
813 self.pending_events.push(event);
814 true
815 }
816
817 fn collect_cursor(
818 &mut self,
819 position: PhysicalPosition<f64>,
820 ) -> Result<(), DesktopPointerError> {
821 if self.input_failure.is_some() || self.capture.accepts_motion() {
822 return Ok(());
823 }
824 let mut geometry = self.pointer_geometry;
825 let event = geometry.cursor_moved(position)?;
826 if self.collect_input(event) {
827 self.pointer_geometry = geometry;
828 }
829 Ok(())
830 }
831
832 fn collect_mouse_button(&mut self, button: winit::event::MouseButton, state: ElementState) {
833 if let Some(button) = pointer::map_mouse_button(button) {
834 self.collect_input(InputEvent::mouse_button(button, map_button_state(state)));
835 }
836 }
837
838 fn collect_pointer_left(&mut self) {
839 if self.capture.accepts_motion() {
840 return;
841 }
842 if self.collect_input(InputEvent::PointerLeft) {
843 self.pointer_geometry.cursor_left();
844 }
845 }
846
847 fn collect_resize(&mut self, size: PhysicalSize<u32>) -> Result<(), DesktopPointerError> {
848 if self.input_failure.is_some() {
849 return Ok(());
850 }
851 let mut geometry = self.pointer_geometry;
852 if geometry
853 .resized(size)?
854 .is_none_or(|event| self.collect_input(event))
855 {
856 self.pointer_geometry = geometry;
857 }
858 Ok(())
859 }
860
861 fn collect_scale_factor(&mut self, scale_factor: f64) -> Result<(), DesktopPointerError> {
862 if self.input_failure.is_some() {
863 return Ok(());
864 }
865 let mut geometry = self.pointer_geometry;
866 if geometry
867 .scale_factor_changed(scale_factor)?
868 .is_none_or(|event| self.collect_input(event))
869 {
870 self.pointer_geometry = geometry;
871 }
872 Ok(())
873 }
874
875 fn collect_focus_loss(&mut self) {
876 self.capture.set_focused(false);
877 self.release_capture();
878 if self.collect_input(InputEvent::FocusLost) {
882 self.held_keys.fill(false);
883 self.pointer_geometry.cursor_left();
884 }
885 }
886
887 fn redraw(&mut self, event_loop: &ActiveEventLoop) {
888 if !callback_may_run(self.fatal.is_some(), event_loop.exiting()) {
889 return;
890 }
891 self.collect_gpu_timings();
894 if let Some(failure) = self.input_failure {
895 let error = match failure {
896 InputBufferFailure::Limit => DesktopRunError::InputEventLimitExceeded {
897 limit: self.input_event_limit,
898 },
899 InputBufferFailure::Allocation => DesktopRunError::InputBufferAllocationFailed,
900 InputBufferFailure::RelativeMotion(error) => {
901 DesktopRunError::Pointer(DesktopPointerError::RelativeMotion(error))
902 }
903 };
904 self.stop(event_loop, error);
905 return;
906 }
907
908 let Some(renderer) = self.renderer.as_ref() else {
909 return;
910 };
911 let viewport = match renderer.logical_viewport() {
912 Ok(viewport) => viewport,
913 Err(error) => {
914 self.stop(event_loop, DesktopRunError::LogicalViewport(error));
915 return;
916 }
917 };
918 let now = Instant::now();
919 let elapsed = now.saturating_duration_since(self.last_frame);
920 self.last_frame = now;
921 let outcome = advance_shared_core(
922 &mut self.runner,
923 FrameRequest::new(elapsed, &self.pending_events, viewport),
924 );
925 self.pending_events.clear();
926
927 let report = match outcome {
928 FrameOutcome::Rejected(error) => {
929 self.stop(event_loop, DesktopRunError::BeginFrame(error));
930 return;
931 }
932 FrameOutcome::Advanced(report) => report,
933 };
934 self.synchronize_capture();
935 if let Some(window) = self.window.as_deref() {
936 self.runner
937 .with_window_controls(|controls| window::synchronize(window, controls));
938 }
939 self.report.logic_frames = self.report.logic_frames.saturating_add(1);
940 if let Some(updates) = report.extracted_generation().and_then(|generation| {
941 self.runner
942 .extracted_frame()
943 .filter(|frame| frame.world_generation() == generation)
944 .map(crate::ExtractedFrame::screen_extraction_updates)
945 }) {
946 self.report.last_screen_extraction = Some(updates);
947 }
948 if matches!(report.transition(), FrameTransition::Committed { .. }) {
949 self.report.committed_transitions = self.report.committed_transitions.saturating_add(1);
950 }
951 if transition_resets_wall_clock(report.transition()) {
952 self.last_frame = Instant::now();
955 }
956 let active_generation = self.runner.world_generation();
957 if let Some(rejection) = budget_recovery::logical(&report, active_generation)
958 && self
959 .runner
960 .with_presentation_feedback(|feedback| feedback.reject(rejection))
961 .is_some()
962 {
963 self.report.budget_rejections = self.report.budget_rejections.saturating_add(1);
964 self.report.last_logic_frame = Some(report);
965 return;
966 }
967 let snapshot_generation = self
968 .runner
969 .extracted_frame()
970 .map(crate::ExtractedFrame::world_generation);
971 match presentation_decision(
972 &report,
973 snapshot_generation,
974 active_generation,
975 self.window_occluded,
976 ) {
977 PresentationDecision::DiagnosticsOnly => {
978 let diagnostic_presentation = match self.renderer.as_mut() {
979 Some(renderer) => present_diagnostics_only(renderer, self.frame_budget),
980 None => {
981 self.stop(event_loop, DesktopRunError::RuntimeInvariant);
982 return;
983 }
984 };
985 self.stop(
986 event_loop,
987 DesktopRunError::LogicFrame {
988 report: Box::new(report),
989 diagnostic_presentation: Box::new(diagnostic_presentation),
990 },
991 );
992 return;
993 }
994 PresentationDecision::ApplicationExit => {
995 self.release_capture();
996 self.report.record_application_exit(report);
997 event_loop.exit();
998 return;
999 }
1000 PresentationDecision::SkipStaleSnapshot | PresentationDecision::SkipOccludedWindow => {
1001 self.report.last_logic_frame = Some(report);
1002 return;
1003 }
1004 PresentationDecision::PresentWorld => {}
1005 }
1006
1007 let Some(extracted) = self.runner.extracted_frame() else {
1008 self.stop(event_loop, DesktopRunError::RuntimeInvariant);
1009 return;
1010 };
1011 let Some(renderer) = self.renderer.as_mut() else {
1012 self.stop(event_loop, DesktopRunError::RuntimeInvariant);
1013 return;
1014 };
1015 self.report.last_three_d_frame = None;
1016 self.report.last_three_d_updates = None;
1017 self.report.last_screen_updates = None;
1018 #[cfg(feature = "text")]
1019 {
1020 self.report.last_text_updates = None;
1021 }
1022 if extracted.three_d().is_none() {
1023 if self.three_d.color_target().is_some() {
1026 renderer.clear_frame_cache();
1027 }
1028 self.three_d.clear();
1029 }
1030 let presentation = if let Some(snapshot) = extracted.three_d() {
1031 (|| {
1032 self.images.preflight_three_d(
1033 extracted,
1034 self.runner.image_assets(),
1035 self.frame_budget,
1036 three_d::color_target_bytes(renderer)?,
1037 )?;
1038 let three_d_report =
1039 self.three_d
1040 .prepare(renderer, snapshot, self.three_d_limits)?;
1041 self.report.gpu_timings.submitted(
1042 report.frame_index(),
1043 GpuTimingSource::Scene3d,
1044 three_d_report.gpu_timing_id(),
1045 );
1046 self.report.last_three_d_frame = Some(three_d_report);
1047 let updates = self.three_d.updates();
1048 self.report.last_three_d_updates = Some(updates);
1049 self.report.three_d_updates.accumulate(updates);
1050 images::present(
1051 renderer,
1052 extracted,
1053 self.runner.image_assets(),
1054 &mut self.images,
1055 self.frame_budget,
1056 self.three_d.color_target(),
1057 )
1058 })()
1059 } else if !images::needs_managed_presentation(extracted, &self.images) {
1060 present_extracted(renderer, extracted, self.frame_budget)
1061 .map_err(ScreenPresentationError::Composition)
1062 } else {
1063 images::present(
1064 renderer,
1065 extracted,
1066 self.runner.image_assets(),
1067 &mut self.images,
1068 self.frame_budget,
1069 None,
1070 )
1071 };
1072 let presentation = match presentation {
1073 Ok(report) => Ok(report),
1074 Err(ScreenPresentationError::Composition(error)) => {
1075 if let Some(rejection) =
1076 budget_recovery::composed(&error, report.frame_index(), active_generation)
1077 && self
1078 .runner
1079 .with_presentation_feedback(|feedback| feedback.reject(rejection))
1080 .is_some()
1081 {
1082 self.report.budget_rejections = self.report.budget_rejections.saturating_add(1);
1083 self.report.last_logic_frame = Some(report);
1084 return;
1085 }
1086 Err(error)
1087 }
1088 Err(ScreenPresentationError::Images(error)) => {
1089 self.stop(
1090 event_loop,
1091 DesktopRunError::ImagePreparation {
1092 error,
1093 logic_frame: Box::new(report),
1094 },
1095 );
1096 return;
1097 }
1098 #[cfg(feature = "text")]
1099 Err(ScreenPresentationError::Text(error)) => {
1100 self.stop(
1101 event_loop,
1102 DesktopRunError::TextPreparation {
1103 error,
1104 logic_frame: Box::new(report),
1105 },
1106 );
1107 return;
1108 }
1109 Err(ScreenPresentationError::ThreeD(error)) => {
1110 self.stop(
1111 event_loop,
1112 DesktopRunError::ThreeDPreparation {
1113 error,
1114 logic_frame: Box::new(report),
1115 },
1116 );
1117 return;
1118 }
1119 };
1120 match presentation {
1121 Ok(render_report) => {
1122 self.report.last_screen_updates = Some(self.images.geometry.updates);
1123 #[cfg(feature = "text")]
1124 {
1125 self.report.last_text_updates = Some(self.images.texts.updates);
1126 }
1127 self.report.gpu_timings.submitted(
1128 report.frame_index(),
1129 GpuTimingSource::FrameComposer,
1130 render_report.gpu_timing_id(),
1131 );
1132 self.report.last_render_frame = Some(render_report);
1133 match render_report.status() {
1134 RenderStatus::Drawn => {
1135 self.runner
1136 .with_presentation_feedback(|feedback| feedback.presented());
1137 self.report.drawn_frames = self.report.drawn_frames.saturating_add(1);
1138 self.surface_waiting = false;
1139 }
1140 RenderStatus::Skipped(status) => {
1141 self.report.skipped_frames = self.report.skipped_frames.saturating_add(1);
1142 if let Err(error) = self.handle_skip(status) {
1143 let error = match error {
1144 SkipHandlingError::RendererConfiguration(error) => {
1145 DesktopRunError::RendererConfigurationAfterFrame {
1146 error,
1147 logic_frame: Box::new(report),
1148 }
1149 }
1150 SkipHandlingError::Presentation(error) => {
1151 DesktopRunError::Presentation {
1152 error,
1153 logic_frame: Box::new(report),
1154 }
1155 }
1156 };
1157 self.stop(event_loop, error);
1158 return;
1159 }
1160 }
1161 }
1162 }
1163 Err(error) => match renderer_failure_action(&error) {
1164 RendererFailureAction::RecoverDeviceAndSurface {
1165 reset_wall_clock_on_success,
1166 } => {
1167 let Some(renderer) = self.renderer.as_mut() else {
1168 return;
1169 };
1170 match pollster::block_on(renderer.recover_device_and_surface()) {
1171 Ok(()) => {
1172 self.images.clear();
1173 self.report.device_recoveries =
1174 self.report.device_recoveries.saturating_add(1);
1175 self.report.gpu_timings.reset(
1176 self.report.device_recoveries,
1177 renderer.gpu_timing_statistics(),
1178 );
1179 self.report.last_render_frame = None;
1180 self.report.last_screen_updates = None;
1181 #[cfg(feature = "text")]
1182 {
1183 self.report.last_text_updates = None;
1184 }
1185 self.report.last_three_d_frame = None;
1186 self.report.last_three_d_updates = None;
1187 if let Err(error) = self.three_d.restore(renderer) {
1188 self.stop(
1189 event_loop,
1190 DesktopRunError::ThreeDPreparation {
1191 error,
1192 logic_frame: Box::new(report),
1193 },
1194 );
1195 return;
1196 }
1197 if reset_wall_clock_on_success {
1198 self.last_frame = Instant::now();
1199 }
1200 self.surface_waiting = false;
1201 }
1202 Err(error) => {
1203 self.stop(
1204 event_loop,
1205 DesktopRunError::Recovery {
1206 error,
1207 logic_frame: Box::new(report),
1208 },
1209 );
1210 return;
1211 }
1212 }
1213 }
1214 RendererFailureAction::Fail => {
1215 self.stop(
1216 event_loop,
1217 DesktopRunError::Presentation {
1218 error,
1219 logic_frame: Box::new(report),
1220 },
1221 );
1222 return;
1223 }
1224 },
1225 }
1226 self.report.last_logic_frame = Some(report);
1227 }
1228
1229 fn handle_skip(&mut self, status: RendererSurfaceStatus) -> Result<(), SkipHandlingError> {
1230 match skipped_surface_action(status) {
1231 SkippedSurfaceAction::RetryLater => self.surface_waiting = false,
1232 SkippedSurfaceAction::WaitForWindowEvent => self.surface_waiting = true,
1233 SkippedSurfaceAction::ReconfigureThenRetry => {
1234 self.surface_waiting = false;
1235 self.resize_renderer()
1236 .map_err(SkipHandlingError::RendererConfiguration)?;
1237 }
1238 SkippedSurfaceAction::Fail => {
1239 return Err(SkipHandlingError::Presentation(FrameComposerError::Frame(
1240 RendererFrameError::Surface(status),
1241 )));
1242 }
1243 }
1244 Ok(())
1245 }
1246
1247 fn resize_renderer(&mut self) -> Result<(), RendererConfigurationError> {
1248 let Some(renderer) = self.renderer.as_mut() else {
1249 return Ok(());
1250 };
1251 let size = self.pointer_geometry.physical_size();
1252 renderer.resize_with_scale_factor(
1253 size.width,
1254 size.height,
1255 self.pointer_geometry.scale_factor(),
1256 )
1257 }
1258}
1259
1260impl<A: Action> ApplicationHandler for DesktopHost<A> {
1261 fn resumed(&mut self, event_loop: &ActiveEventLoop) {
1262 if !callback_may_run(self.fatal.is_some(), event_loop.exiting()) || self.window.is_some() {
1263 return;
1264 }
1265 let attributes = Window::default_attributes()
1266 .with_title(self.config.title.clone())
1267 .with_inner_size(LogicalSize::new(
1268 self.config.logical_width,
1269 self.config.logical_height,
1270 ));
1271 let window = match event_loop.create_window(attributes) {
1272 Ok(window) => Arc::new(window),
1273 Err(error) => {
1274 self.stop(event_loop, DesktopRunError::Window(error));
1275 return;
1276 }
1277 };
1278 let initial_mode = self
1279 .runner
1280 .app_resource::<crate::window::WindowControls>()
1281 .and_then(crate::window::WindowControls::pending_mode)
1282 .unwrap_or(self.config.window_mode);
1283 let initial_status = window::apply_mode(&window, initial_mode);
1284 self.runner
1285 .with_window_controls(|controls| controls.acknowledge_mode(initial_status));
1286 if let crate::window::WindowModeStatus::Unavailable(error) = initial_status {
1287 self.stop(event_loop, DesktopRunError::WindowMode(error));
1288 return;
1289 }
1290 let size = window.inner_size();
1291 let scale_factor = window.scale_factor();
1292 self.pointer_geometry = match DesktopPointerGeometry::new(size, scale_factor) {
1293 Ok(geometry) => geometry,
1294 Err(error) => {
1295 self.stop(event_loop, DesktopRunError::Pointer(error));
1296 return;
1297 }
1298 };
1299 let options = match WgpuRendererOptions::new(self.config.present_mode, scale_factor) {
1300 Ok(options) => options.with_gpu_timing(self.config.gpu_timing),
1301 Err(error) => {
1302 self.stop(event_loop, DesktopRunError::RendererConfiguration(error));
1303 return;
1304 }
1305 };
1306 let mut renderer = match pollster::block_on(WgpuRenderer::new_with_options(
1307 Arc::clone(&window),
1308 size.width.max(1),
1309 size.height.max(1),
1310 options,
1311 )) {
1312 Ok(renderer) => renderer,
1313 Err(error) => {
1314 self.stop(event_loop, DesktopRunError::RendererInitialization(error));
1315 return;
1316 }
1317 };
1318 let notify_window = Arc::clone(&window);
1319 renderer.set_frame_cache_budget(self.config.frame_cache);
1320 renderer.set_pre_present_notify(move || notify_window.pre_present_notify());
1321 self.report
1322 .gpu_timings
1323 .reset(0, renderer.gpu_timing_statistics());
1324 self.window_occluded = extent_is_occluded(size.width, size.height);
1325 self.last_frame = Instant::now();
1326 self.capture.attach(Arc::clone(&window));
1327 self.window = Some(window);
1328 self.images.clear();
1329 self.three_d.clear();
1330 self.renderer = Some(renderer);
1331 }
1332
1333 fn window_event(
1334 &mut self,
1335 event_loop: &ActiveEventLoop,
1336 window_id: WindowId,
1337 event: WindowEvent,
1338 ) {
1339 if !callback_may_run(self.fatal.is_some(), event_loop.exiting()) {
1342 return;
1343 }
1344 let Some(window) = self.window.as_ref() else {
1345 return;
1346 };
1347 if window.id() != window_id {
1348 return;
1349 }
1350
1351 match event {
1352 WindowEvent::CloseRequested | WindowEvent::Destroyed => {
1353 self.release_capture();
1354 event_loop.exit();
1355 }
1356 WindowEvent::KeyboardInput {
1357 event,
1358 is_synthetic,
1359 ..
1360 } => self.collect_key(event.physical_key, event.state, is_synthetic, event.repeat),
1361 WindowEvent::CursorMoved { position, .. } => {
1362 if let Err(error) = self.collect_cursor(position) {
1363 self.stop(event_loop, DesktopRunError::Pointer(error));
1364 }
1365 }
1366 WindowEvent::MouseInput { state, button, .. } => {
1367 self.collect_mouse_button(button, state)
1368 }
1369 WindowEvent::MouseWheel { delta, .. } => {
1370 if let Err(error) = self.collect_mouse_wheel(delta) {
1371 self.stop(event_loop, DesktopRunError::Pointer(error));
1372 }
1373 }
1374 WindowEvent::CursorLeft { .. } => self.collect_pointer_left(),
1375 WindowEvent::Focused(false) => self.collect_focus_loss(),
1376 WindowEvent::Focused(true) => {
1377 self.capture.set_focused(true);
1378 self.surface_waiting = false;
1379 }
1380 WindowEvent::Resized(size) => {
1381 if let Err(error) = self.collect_resize(size) {
1382 self.stop(event_loop, DesktopRunError::Pointer(error));
1383 return;
1384 }
1385 self.window_occluded = extent_is_occluded(size.width, size.height);
1386 if !self.window_occluded {
1387 self.surface_waiting = false;
1388 }
1389 if let Err(error) = self.resize_renderer() {
1390 self.stop(event_loop, DesktopRunError::RendererConfiguration(error));
1391 }
1392 }
1393 WindowEvent::ScaleFactorChanged { scale_factor, .. } => {
1394 if let Err(error) = self.collect_scale_factor(scale_factor) {
1395 self.stop(event_loop, DesktopRunError::Pointer(error));
1396 return;
1397 }
1398 if let Some(renderer) = self.renderer.as_mut()
1399 && let Err(error) = renderer.set_scale_factor(scale_factor)
1400 {
1401 self.stop(event_loop, DesktopRunError::RendererConfiguration(error));
1402 }
1403 }
1404 WindowEvent::Occluded(occluded) => {
1405 self.window_occluded = occluded;
1406 if !occluded {
1407 self.surface_waiting = false;
1408 }
1409 }
1410 WindowEvent::RedrawRequested => {
1411 self.surface_waiting = false;
1414 self.redraw(event_loop);
1415 }
1416 _ => {}
1417 }
1418 }
1419
1420 fn about_to_wait(&mut self, event_loop: &ActiveEventLoop) {
1421 if callback_may_run(self.fatal.is_some(), event_loop.exiting())
1422 && !self.window_occluded
1423 && !self.surface_waiting
1424 && let Some(window) = self.window.as_ref()
1425 {
1426 window.request_redraw();
1427 }
1428 }
1429
1430 fn device_event(&mut self, event_loop: &ActiveEventLoop, _: DeviceId, event: DeviceEvent) {
1431 if !callback_may_run(self.fatal.is_some(), event_loop.exiting()) {
1432 return;
1433 }
1434 if let DeviceEvent::MouseMotion { delta } = event
1435 && let Err(error) = self.collect_relative_motion(delta)
1436 {
1437 self.stop(event_loop, DesktopRunError::Pointer(error));
1438 }
1439 }
1440
1441 fn suspended(&mut self, event_loop: &ActiveEventLoop) {
1442 if callback_may_run(self.fatal.is_some(), event_loop.exiting()) {
1443 self.collect_focus_loss();
1444 }
1445 }
1446}
1447
1448const fn callback_may_run(failed: bool, exiting: bool) -> bool {
1451 !failed && !exiting
1452}
1453
1454#[derive(Debug, Clone, Copy, PartialEq, Eq)]
1455enum PresentationDecision {
1456 DiagnosticsOnly,
1457 ApplicationExit,
1458 SkipStaleSnapshot,
1459 SkipOccludedWindow,
1460 PresentWorld,
1461}
1462
1463#[derive(Debug, Clone, Copy, PartialEq, Eq)]
1464enum SkippedSurfaceAction {
1465 RetryLater,
1466 WaitForWindowEvent,
1467 ReconfigureThenRetry,
1468 Fail,
1469}
1470
1471#[derive(Debug, Clone, Copy, PartialEq, Eq)]
1472enum RendererFailureAction {
1473 RecoverDeviceAndSurface { reset_wall_clock_on_success: bool },
1474 Fail,
1475}
1476
1477enum SkipHandlingError {
1478 RendererConfiguration(RendererConfigurationError),
1479 Presentation(FrameComposerError),
1480}
1481
1482fn advance_shared_core<A: Action>(
1483 runner: &mut HeadlessRunner<A>,
1484 request: FrameRequest<'_>,
1485) -> FrameOutcome {
1486 runner.advance_frame(request)
1487}
1488
1489fn presentation_decision(
1490 report: &LogicFrameReport,
1491 snapshot: Option<WorldGeneration>,
1492 active: WorldGeneration,
1493 window_occluded: bool,
1494) -> PresentationDecision {
1495 if report.failure().is_some() {
1496 return PresentationDecision::DiagnosticsOnly;
1497 }
1498 if report.exit_requested() {
1499 return PresentationDecision::ApplicationExit;
1500 }
1501 if !snapshot_is_fresh(report.extracted_generation(), snapshot, active) {
1502 return PresentationDecision::SkipStaleSnapshot;
1503 }
1504 if window_occluded {
1505 return PresentationDecision::SkipOccludedWindow;
1506 }
1507 PresentationDecision::PresentWorld
1508}
1509
1510const fn skipped_surface_action(status: RendererSurfaceStatus) -> SkippedSurfaceAction {
1511 match status {
1512 RendererSurfaceStatus::Timeout => SkippedSurfaceAction::RetryLater,
1513 RendererSurfaceStatus::Occluded => SkippedSurfaceAction::WaitForWindowEvent,
1514 RendererSurfaceStatus::Outdated => SkippedSurfaceAction::ReconfigureThenRetry,
1515 RendererSurfaceStatus::Lost | RendererSurfaceStatus::Validation => {
1516 SkippedSurfaceAction::Fail
1517 }
1518 }
1519}
1520
1521const fn renderer_failure_action(error: &FrameComposerError) -> RendererFailureAction {
1522 if matches!(
1523 error,
1524 FrameComposerError::Frame(RendererFrameError::Surface(RendererSurfaceStatus::Lost))
1525 ) {
1526 RendererFailureAction::RecoverDeviceAndSurface {
1527 reset_wall_clock_on_success: true,
1528 }
1529 } else {
1530 RendererFailureAction::Fail
1531 }
1532}
1533
1534const fn transition_resets_wall_clock(transition: &FrameTransition) -> bool {
1535 matches!(
1536 transition,
1537 FrameTransition::Committed { .. } | FrameTransition::PreparationFailed { .. }
1538 )
1539}
1540
1541const fn extent_is_occluded(width: u32, height: u32) -> bool {
1542 width == 0 || height == 0
1543}
1544
1545#[derive(Debug, Clone, Copy, PartialEq, Eq)]
1546enum InputBufferFailure {
1547 Limit,
1548 Allocation,
1549 RelativeMotion(RelativePointerMotionError),
1550}
1551
1552fn present_extracted(
1553 renderer: &mut WgpuRenderer,
1554 extracted: &crate::ExtractedFrame,
1555 budget: FrameBudget,
1556) -> Result<FrameReport, FrameComposerError> {
1557 let mut frame = renderer.begin_frame(extracted.background(), budget)?;
1558 frame.draw_scene(
1559 extracted.world_scene(),
1560 extracted.camera(),
1561 FramePassOptions::new(0),
1562 )?;
1563 if let Some(options) = screen_pass_options(extracted.screen_scene().command_count()) {
1564 frame.draw_screen_scene(extracted.screen_scene(), options)?;
1565 }
1566 frame.present()
1567}
1568
1569fn screen_pass_options(command_count: usize) -> Option<FramePassOptions> {
1570 (command_count != 0).then(|| FramePassOptions::new(1))
1571}
1572
1573fn present_diagnostics_only(
1574 renderer: &mut WgpuRenderer,
1575 budget: FrameBudget,
1576) -> Result<FrameReport, FrameComposerError> {
1577 renderer
1578 .begin_frame(sim_engine::Color::BLACK, budget)?
1579 .present()
1580}
1581
1582const fn map_button_state(state: ElementState) -> ButtonState {
1583 match state {
1584 ElementState::Pressed => ButtonState::Pressed,
1585 ElementState::Released => ButtonState::Released,
1586 }
1587}
1588
1589fn snapshot_is_fresh(
1590 report: Option<crate::identity::WorldGeneration>,
1591 snapshot: Option<crate::identity::WorldGeneration>,
1592 active: crate::identity::WorldGeneration,
1593) -> bool {
1594 matches!((report, snapshot), (Some(report), Some(snapshot)) if report == active && snapshot == active)
1595}
1596
1597const fn frame_budget(limits: FrameLimits) -> FrameBudget {
1598 FrameBudget::new(
1599 limits.max_passes(),
1600 limits.max_commands(),
1601 limits.max_vertices(),
1602 limits.max_upload_bytes(),
1603 limits.max_texture_bytes(),
1604 limits.max_draw_calls(),
1605 )
1606}
1607
1608fn validate_title(title: &str) -> Result<(), DesktopConfigError> {
1609 if title.trim().is_empty() {
1610 return Err(DesktopConfigError::EmptyTitle);
1611 }
1612 if title.len() > MAX_TITLE_BYTES {
1613 return Err(DesktopConfigError::TitleTooLong {
1614 limit: MAX_TITLE_BYTES,
1615 });
1616 }
1617 Ok(())
1618}
1619
1620fn validate_logical_size(width: f64, height: f64) -> Result<(), DesktopConfigError> {
1621 if width.is_finite() && height.is_finite() && width > 0.0 && height > 0.0 {
1622 Ok(())
1623 } else {
1624 Err(DesktopConfigError::InvalidLogicalSize { width, height })
1625 }
1626}
1627
1628#[cfg(test)]
1629#[path = "desktop/pointer_tests.rs"]
1630mod pointer_tests;
1631
1632#[cfg(test)]
1633#[path = "desktop/input_tests.rs"]
1634mod input_tests;
1635
1636#[cfg(test)]
1637mod tests {
1638 use super::*;
1639 use std::{error::Error, time::Duration};
1640
1641 use sim_engine::{Camera2d, Color, LogicalViewport, Vec2};
1642
1643 use crate::{
1644 ExtractionError,
1645 app::{AppConfig, Application},
1646 commands::LogicCommands,
1647 headless::{CandidateFailure, FrameFailure},
1648 identity::{ApplicationId, WorldGeneration},
1649 input::{ALL_PHYSICAL_KEYS, FixedInput, InputEvent},
1650 query::Query,
1651 system::Stage,
1652 time::FixedTime,
1653 visual::{ActiveCamera2d, CircleVisual, Transform2d},
1654 };
1655
1656 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
1657 enum TestAction {
1658 MoveRight,
1659 }
1660
1661 fn move_circle(
1662 input: FixedInput<TestAction>,
1663 time: FixedTime,
1664 mut circles: Query<&mut Transform2d>,
1665 ) {
1666 if !input.held(TestAction::MoveRight) {
1667 return;
1668 }
1669 for mut transform in &mut circles {
1670 assert!(
1671 transform
1672 .translate_by(Vec2::new(time.seconds_f32() * 60.0, 0.0))
1673 .is_ok()
1674 );
1675 }
1676 }
1677
1678 fn spawn_second_camera(mut commands: LogicCommands) {
1679 let camera = Camera2d::new(Vec2::ZERO, 32.0);
1680 let Ok(camera) = camera else {
1681 panic!("test camera should be valid");
1682 };
1683 assert!(commands.spawn(ActiveCamera2d::new(camera)).is_ok());
1684 }
1685
1686 fn viewport(width: f32, height: f32) -> Result<LogicalViewport, Box<dyn Error>> {
1687 Ok(LogicalViewport::new(width, height)?)
1688 }
1689
1690 fn parity_runner() -> Result<HeadlessRunner<TestAction>, Box<dyn Error>> {
1691 let mut application = Application::new(AppConfig::default())?;
1692 application.bind_key(PhysicalKeyCode::KeyD, TestAction::MoveRight)?;
1693 let camera = ActiveCamera2d::new(Camera2d::new(Vec2::ZERO, 32.0)?);
1694 let circle = CircleVisual::new(1.0, Color::rgb8(68, 144, 255))?;
1695 let initial = application.register_world("desktop-parity", move |world| {
1696 world.spawn(camera)?;
1697 world.spawn((Transform2d::default(), circle))?;
1698 Ok(())
1699 })?;
1700 application.add_system(Stage::FixedUpdate, move_circle);
1701 Ok(application.build_headless(initial)?)
1702 }
1703
1704 #[test]
1705 fn desktop_configuration_rejects_unbounded_window_values() {
1706 assert!(matches!(
1707 DesktopConfig::new(" ", 800.0, 600.0),
1708 Err(DesktopConfigError::EmptyTitle)
1709 ));
1710 assert!(matches!(
1711 DesktopConfig::new("test", f64::NAN, 600.0),
1712 Err(DesktopConfigError::InvalidLogicalSize { .. })
1713 ));
1714 }
1715
1716 #[test]
1717 fn gpu_timing_is_explicitly_opt_in_without_changing_window_or_cache_settings() {
1718 let mut config = DesktopConfig::new("GPU diagnostics", 960.0, 540.0).unwrap();
1719 let before = config.clone();
1720 assert!(!DesktopConfig::default().gpu_timing());
1721 assert!(!config.gpu_timing());
1722 config.set_gpu_timing(true);
1723 assert!(config.gpu_timing());
1724 let options = WgpuRendererOptions::new(config.present_mode(), 1.25)
1725 .unwrap()
1726 .with_gpu_timing(config.gpu_timing());
1727 assert!(options.gpu_timing());
1728 config.set_gpu_timing(false);
1729 assert_eq!(config, before);
1730 let report = DesktopRunReport::default();
1731 assert!(report.gpu_timings().statistics().is_none());
1732 assert!(report.last_three_d_updates().is_none());
1733 assert_eq!(report.three_d_updates(), DesktopThreeDUpdates::default());
1734 }
1735
1736 #[test]
1737 fn screen_pass_is_optional_and_always_follows_the_world() {
1738 assert!(screen_pass_options(0).is_none());
1739 for count in [1, 256, usize::MAX] {
1740 assert_eq!(
1741 screen_pass_options(count).map(|options| options.order()),
1742 Some(1)
1743 );
1744 }
1745 }
1746
1747 #[test]
1748 fn renderer_budget_conversion_is_exact() {
1749 let source = FrameLimits::new(2, 3, 5, 7, 11, 13);
1750 let converted = frame_budget(source);
1751
1752 assert_eq!(converted.max_passes(), 2);
1753 assert_eq!(converted.max_commands(), 3);
1754 assert_eq!(converted.max_vertices(), 5);
1755 assert_eq!(converted.max_upload_bytes(), 7);
1756 assert_eq!(converted.max_texture_bytes(), 11);
1757 assert_eq!(converted.max_draw_calls(), 13);
1758 }
1759
1760 #[test]
1761 fn desktop_maps_every_supported_physical_key() {
1762 let mappings = [
1763 (KeyCode::KeyW, PhysicalKeyCode::KeyW),
1764 (KeyCode::KeyA, PhysicalKeyCode::KeyA),
1765 (KeyCode::KeyS, PhysicalKeyCode::KeyS),
1766 (KeyCode::KeyD, PhysicalKeyCode::KeyD),
1767 (KeyCode::Enter, PhysicalKeyCode::Enter),
1768 (KeyCode::Space, PhysicalKeyCode::Space),
1769 (KeyCode::ArrowLeft, PhysicalKeyCode::ArrowLeft),
1770 (KeyCode::ArrowRight, PhysicalKeyCode::ArrowRight),
1771 (KeyCode::ArrowDown, PhysicalKeyCode::ArrowDown),
1772 (KeyCode::ArrowUp, PhysicalKeyCode::ArrowUp),
1773 (KeyCode::Escape, PhysicalKeyCode::Escape),
1774 (KeyCode::KeyP, PhysicalKeyCode::KeyP),
1775 (KeyCode::KeyR, PhysicalKeyCode::KeyR),
1776 (KeyCode::KeyN, PhysicalKeyCode::KeyN),
1777 (KeyCode::Digit1, PhysicalKeyCode::Digit1),
1778 (KeyCode::Digit2, PhysicalKeyCode::Digit2),
1779 (KeyCode::Digit3, PhysicalKeyCode::Digit3),
1780 (KeyCode::Digit4, PhysicalKeyCode::Digit4),
1781 (KeyCode::Digit5, PhysicalKeyCode::Digit5),
1782 (KeyCode::F3, PhysicalKeyCode::F3),
1783 (KeyCode::F4, PhysicalKeyCode::F4),
1784 (KeyCode::F5, PhysicalKeyCode::F5),
1785 (KeyCode::F6, PhysicalKeyCode::F6),
1786 (KeyCode::F8, PhysicalKeyCode::F8),
1787 (KeyCode::F9, PhysicalKeyCode::F9),
1788 (KeyCode::KeyL, PhysicalKeyCode::KeyL),
1789 (KeyCode::KeyF, PhysicalKeyCode::KeyF),
1790 (KeyCode::KeyM, PhysicalKeyCode::KeyM),
1791 (KeyCode::KeyT, PhysicalKeyCode::KeyT),
1792 (KeyCode::KeyV, PhysicalKeyCode::KeyV),
1793 (KeyCode::Digit6, PhysicalKeyCode::Digit6),
1794 (KeyCode::Digit7, PhysicalKeyCode::Digit7),
1795 (KeyCode::Digit8, PhysicalKeyCode::Digit8),
1796 (KeyCode::Digit9, PhysicalKeyCode::Digit9),
1797 (KeyCode::F7, PhysicalKeyCode::F7),
1798 (KeyCode::KeyE, PhysicalKeyCode::KeyE),
1799 (KeyCode::ShiftLeft, PhysicalKeyCode::ShiftLeft),
1800 (KeyCode::Tab, PhysicalKeyCode::Tab),
1801 (KeyCode::Digit0, PhysicalKeyCode::Digit0),
1802 (KeyCode::F1, PhysicalKeyCode::F1),
1803 (KeyCode::F2, PhysicalKeyCode::F2),
1804 (KeyCode::F10, PhysicalKeyCode::F10),
1805 (KeyCode::F11, PhysicalKeyCode::F11),
1806 (KeyCode::F12, PhysicalKeyCode::F12),
1807 (KeyCode::ShiftRight, PhysicalKeyCode::ShiftRight),
1808 (KeyCode::ControlLeft, PhysicalKeyCode::ControlLeft),
1809 (KeyCode::ControlRight, PhysicalKeyCode::ControlRight),
1810 (KeyCode::AltLeft, PhysicalKeyCode::AltLeft),
1811 (KeyCode::AltRight, PhysicalKeyCode::AltRight),
1812 (KeyCode::SuperLeft, PhysicalKeyCode::SuperLeft),
1813 (KeyCode::SuperRight, PhysicalKeyCode::SuperRight),
1814 (KeyCode::Backspace, PhysicalKeyCode::Backspace),
1815 (KeyCode::Delete, PhysicalKeyCode::Delete),
1816 (KeyCode::Insert, PhysicalKeyCode::Insert),
1817 (KeyCode::Home, PhysicalKeyCode::Home),
1818 (KeyCode::End, PhysicalKeyCode::End),
1819 (KeyCode::PageUp, PhysicalKeyCode::PageUp),
1820 (KeyCode::PageDown, PhysicalKeyCode::PageDown),
1821 (KeyCode::CapsLock, PhysicalKeyCode::CapsLock),
1822 (KeyCode::NumLock, PhysicalKeyCode::NumLock),
1823 (KeyCode::ScrollLock, PhysicalKeyCode::ScrollLock),
1824 (KeyCode::PrintScreen, PhysicalKeyCode::PrintScreen),
1825 (KeyCode::Pause, PhysicalKeyCode::Pause),
1826 (KeyCode::ContextMenu, PhysicalKeyCode::ContextMenu),
1827 (KeyCode::Backquote, PhysicalKeyCode::Backquote),
1828 (KeyCode::Minus, PhysicalKeyCode::Minus),
1829 (KeyCode::Equal, PhysicalKeyCode::Equal),
1830 (KeyCode::BracketLeft, PhysicalKeyCode::BracketLeft),
1831 (KeyCode::BracketRight, PhysicalKeyCode::BracketRight),
1832 (KeyCode::Backslash, PhysicalKeyCode::Backslash),
1833 (KeyCode::Semicolon, PhysicalKeyCode::Semicolon),
1834 (KeyCode::Quote, PhysicalKeyCode::Quote),
1835 (KeyCode::Comma, PhysicalKeyCode::Comma),
1836 (KeyCode::Period, PhysicalKeyCode::Period),
1837 (KeyCode::Slash, PhysicalKeyCode::Slash),
1838 (KeyCode::KeyB, PhysicalKeyCode::KeyB),
1839 (KeyCode::KeyC, PhysicalKeyCode::KeyC),
1840 (KeyCode::KeyG, PhysicalKeyCode::KeyG),
1841 (KeyCode::KeyH, PhysicalKeyCode::KeyH),
1842 (KeyCode::KeyI, PhysicalKeyCode::KeyI),
1843 (KeyCode::KeyJ, PhysicalKeyCode::KeyJ),
1844 (KeyCode::KeyK, PhysicalKeyCode::KeyK),
1845 (KeyCode::KeyO, PhysicalKeyCode::KeyO),
1846 (KeyCode::KeyU, PhysicalKeyCode::KeyU),
1847 (KeyCode::KeyX, PhysicalKeyCode::KeyX),
1848 (KeyCode::KeyY, PhysicalKeyCode::KeyY),
1849 (KeyCode::KeyZ, PhysicalKeyCode::KeyZ),
1850 (KeyCode::Numpad0, PhysicalKeyCode::Numpad0),
1851 (KeyCode::Numpad1, PhysicalKeyCode::Numpad1),
1852 (KeyCode::Numpad2, PhysicalKeyCode::Numpad2),
1853 (KeyCode::Numpad3, PhysicalKeyCode::Numpad3),
1854 (KeyCode::Numpad4, PhysicalKeyCode::Numpad4),
1855 (KeyCode::Numpad5, PhysicalKeyCode::Numpad5),
1856 (KeyCode::Numpad6, PhysicalKeyCode::Numpad6),
1857 (KeyCode::Numpad7, PhysicalKeyCode::Numpad7),
1858 (KeyCode::Numpad8, PhysicalKeyCode::Numpad8),
1859 (KeyCode::Numpad9, PhysicalKeyCode::Numpad9),
1860 (KeyCode::NumpadEnter, PhysicalKeyCode::NumpadEnter),
1861 (KeyCode::NumpadAdd, PhysicalKeyCode::NumpadAdd),
1862 (KeyCode::NumpadSubtract, PhysicalKeyCode::NumpadSubtract),
1863 (KeyCode::NumpadMultiply, PhysicalKeyCode::NumpadMultiply),
1864 (KeyCode::NumpadDivide, PhysicalKeyCode::NumpadDivide),
1865 (KeyCode::NumpadDecimal, PhysicalKeyCode::NumpadDecimal),
1866 (KeyCode::NumpadEqual, PhysicalKeyCode::NumpadEqual),
1867 (KeyCode::IntlBackslash, PhysicalKeyCode::IntlBackslash),
1868 (KeyCode::IntlRo, PhysicalKeyCode::IntlRo),
1869 (KeyCode::IntlYen, PhysicalKeyCode::IntlYen),
1870 (KeyCode::KeyQ, PhysicalKeyCode::KeyQ),
1871 ];
1872
1873 assert_eq!(mappings.map(|(_, portable)| portable), ALL_PHYSICAL_KEYS);
1874 for (platform, portable) in mappings {
1875 assert_eq!(map_key(PhysicalKey::Code(platform)), Some(portable));
1876 assert_eq!(ALL_PHYSICAL_KEYS[physical_key_index(portable)], portable);
1877 }
1878 assert_eq!(map_key(PhysicalKey::Code(KeyCode::MediaPlayPause)), None);
1879 assert_eq!(
1880 map_key(PhysicalKey::Unidentified(
1881 winit::keyboard::NativeKeyCode::Unidentified
1882 )),
1883 None
1884 );
1885 }
1886
1887 #[test]
1888 fn terminal_callbacks_cannot_run_after_close_or_failure() {
1889 assert!(callback_may_run(false, false));
1890 assert!(
1891 !callback_may_run(false, true),
1892 "normal exit has no fatal error"
1893 );
1894 assert!(
1895 !callback_may_run(true, false),
1896 "failure stops before exit dispatch"
1897 );
1898 assert!(!callback_may_run(true, true));
1899 }
1900
1901 #[test]
1902 fn focus_loss_queues_one_core_owned_boundary_after_all_supported_keys()
1903 -> Result<(), Box<dyn Error>> {
1904 let mut host = DesktopHost::new(
1905 parity_runner()?,
1906 DesktopConfig::default(),
1907 ALL_PHYSICAL_KEYS.len() + 1,
1908 frame_budget(FrameLimits::default()),
1909 ThreeDRenderLimits::default(),
1910 );
1911 let new_keys = ALL_PHYSICAL_KEYS;
1912
1913 for key in new_keys.into_iter().rev() {
1914 host.collect_physical_key(key, ButtonState::Pressed);
1915 }
1916 host.collect_focus_loss();
1917
1918 assert_eq!(host.pending_events.len(), new_keys.len() + 1);
1919 for (index, key) in new_keys.into_iter().enumerate() {
1920 assert_eq!(
1921 host.pending_events[index],
1922 InputEvent::key(new_keys[new_keys.len() - index - 1], ButtonState::Pressed)
1923 );
1924 assert!(!host.held_keys[physical_key_index(key)]);
1925 }
1926 assert_eq!(host.pending_events.last(), Some(&InputEvent::FocusLost));
1927 assert_eq!(host.input_failure, None);
1928 Ok(())
1929 }
1930
1931 #[test]
1932 fn stale_or_unpublished_snapshots_are_never_fresh() {
1933 let application = ApplicationId::from_raw(9);
1934 let old = WorldGeneration::new(application, 1);
1935 let active = WorldGeneration::new(application, 2);
1936
1937 assert!(snapshot_is_fresh(Some(active), Some(active), active));
1938 assert!(!snapshot_is_fresh(Some(active), Some(old), active));
1939 assert!(!snapshot_is_fresh(Some(old), Some(active), active));
1940 assert!(!snapshot_is_fresh(None, Some(active), active));
1941 assert!(!snapshot_is_fresh(Some(active), None, active));
1942 }
1943
1944 #[test]
1945 fn desktop_adapter_and_headless_call_the_same_core_lifecycle() -> Result<(), Box<dyn Error>> {
1946 let mut desktop_core = parity_runner()?;
1947 let mut headless_core = parity_runner()?;
1948 let events = [InputEvent::key(PhysicalKeyCode::KeyD, ButtonState::Pressed)];
1949 let logical_viewport = viewport(800.0, 600.0)?;
1950
1951 let desktop_outcome = advance_shared_core(
1952 &mut desktop_core,
1953 FrameRequest::new(Duration::from_millis(25), &events, logical_viewport),
1954 );
1955 let headless_outcome = headless_core.advance_frame(FrameRequest::new(
1956 Duration::from_millis(25),
1957 &events,
1958 logical_viewport,
1959 ));
1960 let (FrameOutcome::Advanced(desktop_report), FrameOutcome::Advanced(headless_report)) =
1961 (desktop_outcome, headless_outcome)
1962 else {
1963 panic!("both bounded core frames should advance");
1964 };
1965
1966 assert_eq!(desktop_report.timing(), headless_report.timing());
1967 assert_eq!(
1968 desktop_report.fixed_ticks_attempted(),
1969 headless_report.fixed_ticks_attempted()
1970 );
1971 assert_eq!(desktop_report.spawned(), headless_report.spawned());
1972 assert_eq!(desktop_report.despawned(), headless_report.despawned());
1973 assert!(desktop_report.failure().is_none());
1974 assert!(headless_report.failure().is_none());
1975
1976 let desktop_frame = desktop_core
1977 .extracted_frame()
1978 .ok_or("desktop core should publish a frame")?;
1979 let headless_frame = headless_core
1980 .extracted_frame()
1981 .ok_or("headless core should publish a frame")?;
1982 assert_eq!(desktop_frame.background(), headless_frame.background());
1983 assert_eq!(desktop_frame.camera(), headless_frame.camera());
1984 let [desktop_circle] = desktop_frame.resolved_circles() else {
1985 panic!("desktop core should resolve one circle");
1986 };
1987 let [headless_circle] = headless_frame.resolved_circles() else {
1988 panic!("headless core should resolve one circle");
1989 };
1990 assert_eq!(desktop_circle.position(), headless_circle.position());
1991 assert_eq!(desktop_circle.radius(), headless_circle.radius());
1992 assert_eq!(desktop_circle.color(), headless_circle.color());
1993 assert_eq!(desktop_circle.layer(), headless_circle.layer());
1994 assert_eq!(
1995 desktop_circle.draw_order_depth(),
1996 headless_circle.draw_order_depth()
1997 );
1998 Ok(())
1999 }
2000
2001 #[test]
2002 fn presentation_requires_the_report_snapshot_and_active_generation_to_match()
2003 -> Result<(), Box<dyn Error>> {
2004 let mut runner = parity_runner()?;
2005 let outcome = advance_shared_core(
2006 &mut runner,
2007 FrameRequest::new(Duration::ZERO, &[], viewport(800.0, 600.0)?),
2008 );
2009 let FrameOutcome::Advanced(report) = outcome else {
2010 panic!("bounded core frame should advance");
2011 };
2012 let active = runner.world_generation();
2013 let snapshot = runner
2014 .extracted_frame()
2015 .map(crate::ExtractedFrame::world_generation);
2016 let foreign = WorldGeneration::new(ApplicationId::from_raw(900), 1);
2017
2018 assert_eq!(
2019 presentation_decision(&report, snapshot, active, false),
2020 PresentationDecision::PresentWorld
2021 );
2022 assert_eq!(
2023 presentation_decision(&report, Some(foreign), active, false),
2024 PresentationDecision::SkipStaleSnapshot
2025 );
2026 assert_eq!(
2027 presentation_decision(&report, snapshot, active, true),
2028 PresentationDecision::SkipOccludedWindow
2029 );
2030 Ok(())
2031 }
2032
2033 #[test]
2034 fn application_exit_is_recorded_without_another_presentation() -> Result<(), Box<dyn Error>> {
2035 let mut application = Application::<TestAction>::new(AppConfig::default())?;
2036 let camera = ActiveCamera2d::new(Camera2d::new(Vec2::ZERO, 32.0)?);
2037 let initial = application.register_world("desktop-exit", move |world| {
2038 world.spawn(camera)?;
2039 Ok(())
2040 })?;
2041 application.add_system(Stage::FrameUpdate, |mut commands: LogicCommands| {
2042 assert!(commands.request_exit().is_ok());
2043 });
2044 let mut runner = application.build_headless(initial)?;
2045
2046 let outcome = advance_shared_core(
2047 &mut runner,
2048 FrameRequest::new(Duration::ZERO, &[], viewport(800.0, 600.0)?),
2049 );
2050 let FrameOutcome::Advanced(report) = outcome else {
2051 panic!("bounded exit frame should advance");
2052 };
2053 assert!(report.exit_requested());
2054 assert_eq!(report.extracted_generation(), None);
2055 assert_eq!(
2056 presentation_decision(
2057 &report,
2058 runner
2059 .extracted_frame()
2060 .map(crate::ExtractedFrame::world_generation),
2061 runner.world_generation(),
2062 false,
2063 ),
2064 PresentationDecision::ApplicationExit
2065 );
2066
2067 let mut desktop = DesktopRunReport::default();
2068 assert_eq!(desktop.exit_reason(), DesktopExitReason::WindowClosed);
2069 desktop.record_application_exit(report);
2070 assert_eq!(
2071 desktop.exit_reason(),
2072 DesktopExitReason::ApplicationRequested
2073 );
2074 assert_eq!(desktop.drawn_frames(), 0);
2075 assert_eq!(desktop.skipped_frames(), 0);
2076 assert!(desktop.last_render_frame().is_none());
2077 assert!(
2078 desktop
2079 .last_logic_frame()
2080 .is_some_and(LogicFrameReport::exit_requested)
2081 );
2082 Ok(())
2083 }
2084
2085 #[test]
2086 fn extraction_and_renderer_failures_choose_separate_paths() -> Result<(), Box<dyn Error>> {
2087 let mut application = Application::<TestAction>::new(AppConfig::default())?;
2088 let camera = ActiveCamera2d::new(Camera2d::new(Vec2::ZERO, 32.0)?);
2089 let initial = application.register_world("invalid-after-frame", move |world| {
2090 world.spawn(camera)?;
2091 Ok(())
2092 })?;
2093 application.add_system(Stage::FrameUpdate, spawn_second_camera);
2094 let mut runner = application.build_headless(initial)?;
2095
2096 let outcome = advance_shared_core(
2097 &mut runner,
2098 FrameRequest::new(Duration::ZERO, &[], viewport(800.0, 600.0)?),
2099 );
2100 let FrameOutcome::Advanced(report) = outcome else {
2101 panic!("BeginFrame should succeed before extraction fails");
2102 };
2103 assert!(matches!(
2104 report.failure(),
2105 Some(FrameFailure::Extraction(
2106 ExtractionError::MultipleActiveCameras
2107 ))
2108 ));
2109 assert_eq!(
2110 presentation_decision(
2111 &report,
2112 runner
2113 .extracted_frame()
2114 .map(crate::ExtractedFrame::world_generation),
2115 runner.world_generation(),
2116 false,
2117 ),
2118 PresentationDecision::DiagnosticsOnly
2119 );
2120
2121 let renderer_validation = FrameComposerError::Frame(RendererFrameError::Surface(
2122 RendererSurfaceStatus::Validation,
2123 ));
2124 assert_eq!(
2125 renderer_failure_action(&renderer_validation),
2126 RendererFailureAction::Fail
2127 );
2128 assert_eq!(
2129 renderer_failure_action(&FrameComposerError::InvalidBackground),
2130 RendererFailureAction::Fail
2131 );
2132 Ok(())
2133 }
2134
2135 #[test]
2136 fn surface_outcomes_follow_the_desktop_retry_policy() {
2137 assert_eq!(
2138 skipped_surface_action(RendererSurfaceStatus::Timeout),
2139 SkippedSurfaceAction::RetryLater
2140 );
2141 assert_eq!(
2142 skipped_surface_action(RendererSurfaceStatus::Occluded),
2143 SkippedSurfaceAction::WaitForWindowEvent
2144 );
2145 assert_eq!(
2146 skipped_surface_action(RendererSurfaceStatus::Outdated),
2147 SkippedSurfaceAction::ReconfigureThenRetry
2148 );
2149 assert_eq!(
2150 skipped_surface_action(RendererSurfaceStatus::Lost),
2151 SkippedSurfaceAction::Fail
2152 );
2153 assert_eq!(
2154 skipped_surface_action(RendererSurfaceStatus::Validation),
2155 SkippedSurfaceAction::Fail
2156 );
2157
2158 let lost =
2159 FrameComposerError::Frame(RendererFrameError::Surface(RendererSurfaceStatus::Lost));
2160 assert_eq!(
2161 renderer_failure_action(&lost),
2162 RendererFailureAction::RecoverDeviceAndSurface {
2163 reset_wall_clock_on_success: true,
2164 }
2165 );
2166 }
2167
2168 #[test]
2169 fn resize_and_render_skip_do_not_advance_fixed_state() -> Result<(), Box<dyn Error>> {
2170 let mut runner = parity_runner()?;
2171 let pressed = [InputEvent::key(PhysicalKeyCode::KeyD, ButtonState::Pressed)];
2172 let first = advance_shared_core(
2173 &mut runner,
2174 FrameRequest::new(Duration::from_millis(17), &pressed, viewport(800.0, 600.0)?),
2175 );
2176 assert!(matches!(first, FrameOutcome::Advanced(_)));
2177 let before_resize = runner
2178 .components::<Transform2d>()
2179 .next()
2180 .map(|(_, transform)| transform.translation())
2181 .ok_or("test World should contain a transform")?;
2182
2183 assert!(!extent_is_occluded(1_200, 800));
2184 let resized = advance_shared_core(
2185 &mut runner,
2186 FrameRequest::new(Duration::ZERO, &[], viewport(1_200.0, 800.0)?),
2187 );
2188 assert!(matches!(resized, FrameOutcome::Advanced(_)));
2189 assert_eq!(
2190 skipped_surface_action(RendererSurfaceStatus::Timeout),
2191 SkippedSurfaceAction::RetryLater
2192 );
2193
2194 let after_skip = runner
2195 .components::<Transform2d>()
2196 .next()
2197 .map(|(_, transform)| transform.translation())
2198 .ok_or("test World should contain a transform")?;
2199 assert_eq!(before_resize, after_skip);
2200 assert!(extent_is_occluded(0, 800));
2201 assert!(extent_is_occluded(1_200, 0));
2202 Ok(())
2203 }
2204
2205 #[test]
2206 fn transition_and_recovery_clock_reset_policy_is_explicit() {
2207 let application = ApplicationId::from_raw(91);
2208 let old = WorldGeneration::new(application, 1);
2209 let new = WorldGeneration::new(application, 2);
2210 let target = WorldFactoryId::new(application, 0, 1);
2211
2212 assert!(!transition_resets_wall_clock(&FrameTransition::None));
2213 assert!(transition_resets_wall_clock(&FrameTransition::Committed {
2214 old,
2215 new,
2216 target,
2217 warning: None,
2218 }));
2219 assert!(transition_resets_wall_clock(
2220 &FrameTransition::PreparationFailed {
2221 target,
2222 error: CandidateFailure::InvalidFactory,
2223 }
2224 ));
2225
2226 let lost =
2227 FrameComposerError::Frame(RendererFrameError::Surface(RendererSurfaceStatus::Lost));
2228 assert_eq!(
2229 renderer_failure_action(&lost),
2230 RendererFailureAction::RecoverDeviceAndSurface {
2231 reset_wall_clock_on_success: true,
2232 }
2233 );
2234 }
2235}