Skip to main content

sui_platform/
lib.rs

1#![deny(unsafe_code)]
2
3mod accessibility;
4#[cfg(target_os = "android")]
5#[allow(unsafe_code)]
6mod android_clipboard;
7mod debug_capture;
8mod desktop;
9mod display_capabilities;
10mod file_dialog;
11mod frame_pacing;
12mod headless;
13mod motion_preference;
14#[cfg(any(target_os = "windows", target_os = "macos", target_os = "linux"))]
15mod os_clipboard;
16mod present;
17#[cfg(any(target_arch = "wasm32", test))]
18mod web_interop;
19#[cfg(target_os = "windows")]
20mod windows_accessibility;
21
22use web_time::Instant;
23
24use sui_core::WindowId;
25use sui_render_wgpu::{
26    ColorManagementMode, RendererFrameStats, RequestedColorManagementMode,
27    RequestedDynamicRangeMode, RequestedOutputColorPrimaries, RequestedToneMappingMode,
28    TextCoveragePolicy, WgpuRenderer,
29};
30use sui_runtime::{
31    CacheMetrics, FramePhase, FramePhaseSample, PresentationLatencyDiagnostics, RenderOutput,
32    RendererSubmissionDiagnostics, RetainedPacketHotspotDiagnostics,
33    RetainedPacketRebuildDiagnostics, SceneStatistics, TextCacheDiagnostics,
34    WindowColorManagementMode, WindowDynamicRangeMode, WindowOutputColorPrimaries,
35    WindowPerformanceSnapshot, WindowTextCoveragePolicy, WindowToneMappingMode,
36    clear_window_performance_snapshot, clear_window_performance_snapshots,
37    publish_window_performance_snapshot, window_performance_text_caches,
38    window_scene_statistics_detail_mode,
39};
40
41pub(crate) use accessibility::AccessibilityBridge;
42pub use accessibility::{
43    AccessibilityIssue, AccessibilityIssueSeverity, AccessibilityIssueTarget,
44    AccessibilitySnapshot, validate_accessibility_snapshot,
45};
46pub use debug_capture::{
47    DebugCaptureTicket, has_pending_window_debug_captures, request_window_debug_capture,
48    service_window_debug_captures, take_window_debug_capture,
49};
50#[cfg(target_os = "android")]
51pub use desktop::AndroidApp;
52pub use desktop::{
53    DesktopAutomationAction, DesktopAutomationConfig, DesktopExtension, DesktopExtensionContext,
54    DesktopFramePresented, DesktopPlatform, DesktopWindow, WakeSignal, Waker,
55};
56pub use display_capabilities::{
57    WindowOutputDiagnostics, clear_window_output_diagnostics, clear_window_output_diagnostics_all,
58    detect_window_display_capabilities, publish_window_output_diagnostics,
59    resolve_sdr_content_brightness_nits, window_output_diagnostics,
60    window_output_diagnostics_signal,
61};
62pub use file_dialog::{
63    FileDialogFilter, FileDialogFuture, FileDialogMode, FileDialogRequest, FileDialogSelection,
64    FileDialogService, NativeFileDialogs, PlatformFile, show_file_dialog,
65};
66pub use headless::{HeadlessPlatform, PlatformWindow};
67#[cfg(any(target_os = "windows", target_os = "macos", target_os = "linux"))]
68pub use os_clipboard::OsClipboardBackend;
69pub use present::{PresentedFrame, present_window_frame};
70
71pub(crate) fn reset_window_performance_store() {
72    clear_window_performance_snapshots();
73    clear_window_output_diagnostics_all();
74}
75
76pub(crate) fn map_window_text_coverage_policy(
77    policy: WindowTextCoveragePolicy,
78) -> TextCoveragePolicy {
79    match policy.normalized() {
80        WindowTextCoveragePolicy::Perceptual => TextCoveragePolicy::Perceptual,
81        WindowTextCoveragePolicy::Linear => TextCoveragePolicy::Linear,
82        WindowTextCoveragePolicy::Gamma(gamma) => TextCoveragePolicy::Gamma(gamma),
83        WindowTextCoveragePolicy::CoverageBoost(amount) => {
84            TextCoveragePolicy::CoverageBoost(amount)
85        }
86        WindowTextCoveragePolicy::TwoCoverageMinusCoverageSq => {
87            TextCoveragePolicy::TwoCoverageMinusCoverageSq
88        }
89    }
90}
91
92pub(crate) fn map_window_color_management(
93    mode: WindowColorManagementMode,
94    primaries: WindowOutputColorPrimaries,
95    dynamic_range: WindowDynamicRangeMode,
96    tone_mapping: WindowToneMappingMode,
97    sdr_content_brightness_nits: f32,
98) -> ColorManagementMode {
99    ColorManagementMode {
100        mode: match mode {
101            WindowColorManagementMode::Automatic => RequestedColorManagementMode::Automatic,
102            WindowColorManagementMode::ForceSdr => RequestedColorManagementMode::ForceSdr,
103            WindowColorManagementMode::PreferWideGamut => {
104                RequestedColorManagementMode::PreferWideGamut
105            }
106            WindowColorManagementMode::PreferHdr => RequestedColorManagementMode::PreferHdr,
107        },
108        output_primaries: match primaries {
109            WindowOutputColorPrimaries::Automatic => RequestedOutputColorPrimaries::Automatic,
110            WindowOutputColorPrimaries::Srgb => RequestedOutputColorPrimaries::Srgb,
111            WindowOutputColorPrimaries::DisplayP3 => RequestedOutputColorPrimaries::DisplayP3,
112        },
113        dynamic_range: match dynamic_range {
114            WindowDynamicRangeMode::Automatic => RequestedDynamicRangeMode::Automatic,
115            WindowDynamicRangeMode::StandardDynamicRange => {
116                RequestedDynamicRangeMode::StandardDynamicRange
117            }
118            WindowDynamicRangeMode::HighDynamicRange => RequestedDynamicRangeMode::HighDynamicRange,
119        },
120        tone_mapping: match tone_mapping {
121            WindowToneMappingMode::Automatic => RequestedToneMappingMode::Automatic,
122            WindowToneMappingMode::Clamp => RequestedToneMappingMode::Clamp,
123            WindowToneMappingMode::Reinhard => RequestedToneMappingMode::Reinhard,
124        },
125        sdr_content_brightness_nits,
126    }
127}
128
129pub(crate) fn clear_window_performance(window_id: WindowId) {
130    clear_window_performance_snapshot(window_id);
131    clear_window_output_diagnostics(window_id);
132    debug_capture::clear_window_debug_captures(window_id);
133}
134
135fn retained_packet_rebuild_diagnostics(
136    rebuilds: sui_render_wgpu::RetainedPacketRebuildStats,
137) -> RetainedPacketRebuildDiagnostics {
138    RetainedPacketRebuildDiagnostics::new(
139        rebuilds.new_count,
140        rebuilds.coordinate_space_count,
141        rebuilds.signature_count,
142        rebuilds.scene_count,
143        rebuilds.state_count,
144    )
145}
146
147fn renderer_submission_diagnostics_from_frame_stats(
148    renderer_stats: &RendererFrameStats,
149) -> RendererSubmissionDiagnostics {
150    RendererSubmissionDiagnostics::new(
151        renderer_stats.pass_count,
152        renderer_stats.draw_count,
153        renderer_stats.uploaded_vertex_bytes,
154        renderer_stats.text_glyph_instance_count,
155        renderer_stats.text_vertex_bytes,
156        renderer_stats.visible_layer_count,
157        renderer_stats.direct_packet_count,
158        renderer_stats.retained_state_update_time_us,
159        renderer_stats.composition_time_us,
160        renderer_stats.retained_scene_traversal_time_us,
161        renderer_stats.retained_packet_build_time_us,
162        renderer_stats.retained_packet_build_count,
163        retained_packet_rebuild_diagnostics(renderer_stats.retained_packet_rebuilds),
164        renderer_stats.text_atlas_miss_count,
165        renderer_stats.text_atlas_miss_time_us,
166        renderer_stats.surface_acquire_time_us,
167        renderer_stats.resource_collection_time_us,
168        renderer_stats.bind_group_prepare_time_us,
169        renderer_stats.image_bind_group_time_us,
170        renderer_stats.analytic_path_bind_group_time_us,
171        renderer_stats.analytic_path_bind_group_miss_count,
172        renderer_stats.analytic_path_bind_group_upload_bytes,
173        renderer_stats.text_atlas_bind_group_time_us,
174        renderer_stats.text_atlas_upload_copy_time_us,
175        renderer_stats.text_atlas_upload_write_time_us,
176        renderer_stats.text_atlas_upload_bytes,
177        renderer_stats.batch_prepare_time_us,
178        renderer_stats.gpu_upload_time_us,
179        renderer_stats.pass_encode_time_us,
180        renderer_stats.queue_submit_time_us,
181        renderer_stats.surface_present_time_us,
182    )
183    .with_retained_packet_breakdown(
184        renderer_stats.retained_packet_normalize_time_us,
185        renderer_stats.retained_packet_signature_time_us,
186        renderer_stats.retained_packet_raster_state_init_time_us,
187        renderer_stats.retained_packet_scene_build_time_us,
188        renderer_stats.retained_packet_command_count,
189        renderer_stats.retained_packet_text_command_count,
190        renderer_stats.retained_packet_path_command_count,
191        renderer_stats.retained_packet_clip_path_command_count,
192        renderer_stats.retained_packet_image_command_count,
193        renderer_stats.retained_packet_rect_command_count,
194        renderer_stats.retained_packet_text_command_time_us,
195        renderer_stats.retained_packet_path_command_time_us,
196        renderer_stats.retained_packet_clip_path_command_time_us,
197        renderer_stats.retained_packet_image_command_time_us,
198        renderer_stats.retained_packet_rect_command_time_us,
199    )
200}
201
202fn retained_packet_hotspot_diagnostics_from_frame_stats(
203    renderer_stats: &RendererFrameStats,
204) -> Option<RetainedPacketHotspotDiagnostics> {
205    renderer_stats
206        .retained_packet_hotspot
207        .clone()
208        .map(|hotspot| RetainedPacketHotspotDiagnostics {
209            container_layer_id: hotspot.container_layer_id,
210            owner_widget_id: hotspot.owner_widget_id,
211            segment_index: hotspot.segment_index,
212            total_time_us: hotspot.total_time_us,
213            scene_build_time_us: hotspot.scene_build_time_us,
214            command_count: hotspot.command_count,
215            text_command_count: hotspot.text_command_count,
216            path_command_count: hotspot.path_command_count,
217            rect_command_count: hotspot.rect_command_count,
218            text_command_time_us: hotspot.text_command_time_us,
219            path_command_time_us: hotspot.path_command_time_us,
220            rect_command_time_us: hotspot.rect_command_time_us,
221            text_sample: hotspot.text_sample,
222        })
223}
224
225fn split_renderer_phase_times_ms(
226    renderer_time_ms: f64,
227    renderer_stats: &RendererFrameStats,
228) -> (f64, f64) {
229    let renderer_time_ms = renderer_time_ms.max(0.0);
230    let surface_wait_time_ms = ((renderer_stats
231        .surface_acquire_time_us
232        .saturating_add(renderer_stats.surface_present_time_us))
233        as f64
234        / 1000.0)
235        .min(renderer_time_ms);
236    let renderer_work_time_ms = (renderer_time_ms - surface_wait_time_ms).max(0.0);
237    (renderer_work_time_ms, surface_wait_time_ms)
238}
239
240#[allow(clippy::too_many_arguments)]
241pub fn publish_frame_performance(
242    window_id: WindowId,
243    frame_index: u64,
244    event_time_ms: f64,
245    redraw_time_ms: f64,
246    runtime_time_ms: f64,
247    presentation_latency: PresentationLatencyDiagnostics,
248    output: &RenderOutput,
249    renderer: &WgpuRenderer,
250    renderer_time_ms: f64,
251) {
252    let detail_mode = window_scene_statistics_detail_mode(window_id);
253    let total_time_ms = event_time_ms + redraw_time_ms + runtime_time_ms + renderer_time_ms;
254
255    if !detail_mode.is_detailed() {
256        let scene =
257            SceneStatistics::minimal(&output.frame, output.diagnostics.widget_count, detail_mode)
258                .with_animation_counters(
259                    output.diagnostics.active_animated_widget_count,
260                    output.diagnostics.animation_frame_wake_count,
261                    output.diagnostics.animation_repaint_frame_count,
262                    output
263                        .diagnostics
264                        .animation_transform_effect_only_frame_count,
265                );
266        publish_window_performance_snapshot(
267            WindowPerformanceSnapshot::with_total_time_ms(
268                window_id,
269                frame_index,
270                total_time_ms,
271                Vec::new(),
272                RendererSubmissionDiagnostics::default(),
273                TextCacheDiagnostics::default(),
274                Default::default(),
275                scene,
276            )
277            .with_presentation_latency(presentation_latency)
278            .with_runtime_text_timing(output.diagnostics.runtime_text_timing)
279            .with_widget_timings(output.diagnostics.widget_timings.clone())
280            .with_event_traces(
281                output.diagnostics.command_dispatches.clone(),
282                output.diagnostics.invalidations.clone(),
283            ),
284        );
285        return;
286    }
287
288    let diagnostics_started = Instant::now();
289    let mut phase_timings = Vec::with_capacity(output.diagnostics.phase_timings.len() + 3);
290    let renderer_text_cache = renderer.text_cache_snapshot(window_id);
291    let text_caches = TextCacheDiagnostics {
292        runtime_layout: output.diagnostics.text_caches.runtime_layout,
293        renderer_layout: CacheMetrics::new(
294            renderer_text_cache.layout.entries,
295            renderer_text_cache.layout.hits,
296            renderer_text_cache.layout.misses,
297        ),
298        renderer_glyph: CacheMetrics::new(
299            renderer_text_cache.glyph.entries,
300            renderer_text_cache.glyph.hits,
301            renderer_text_cache.glyph.misses,
302        ),
303        renderer_path: CacheMetrics::new(
304            renderer_text_cache.path.entries,
305            renderer_text_cache.path.hits,
306            renderer_text_cache.path.misses,
307        ),
308    };
309    let text_cache_deltas = window_performance_text_caches(window_id)
310        .map(|previous| text_caches.delta_from(&previous))
311        .unwrap_or_else(|| text_caches.delta_from(&TextCacheDiagnostics::default()));
312    let renderer_stats = renderer.last_frame_stats(window_id).unwrap_or_default();
313
314    if event_time_ms > 0.0 {
315        phase_timings.push(FramePhaseSample::new(FramePhase::Event, event_time_ms));
316    }
317
318    if redraw_time_ms > 0.0 {
319        phase_timings.push(FramePhaseSample::new(FramePhase::Redraw, redraw_time_ms));
320    }
321
322    phase_timings.extend(output.diagnostics.phase_timings.iter().copied());
323    let (renderer_work_time_ms, surface_wait_time_ms) =
324        split_renderer_phase_times_ms(renderer_time_ms, &renderer_stats);
325    if renderer_work_time_ms > 0.0 {
326        phase_timings.push(FramePhaseSample::new(
327            FramePhase::Renderer,
328            renderer_work_time_ms,
329        ));
330    }
331    if surface_wait_time_ms > 0.0 {
332        phase_timings.push(FramePhaseSample::new(
333            FramePhase::SurfaceWait,
334            surface_wait_time_ms,
335        ));
336    }
337    phase_timings.push(FramePhaseSample::new(
338        FramePhase::Diagnostics,
339        diagnostics_started.elapsed().as_secs_f64() * 1000.0,
340    ));
341    let total_time_ms = event_time_ms
342        + redraw_time_ms
343        + runtime_time_ms
344        + renderer_time_ms
345        + diagnostics_started.elapsed().as_secs_f64() * 1000.0;
346
347    let scene = SceneStatistics::from_frame_with_mode(
348        &output.frame,
349        output.diagnostics.widget_count,
350        detail_mode,
351    )
352    .with_animation_counters(
353        output.diagnostics.active_animated_widget_count,
354        output.diagnostics.animation_frame_wake_count,
355        output.diagnostics.animation_repaint_frame_count,
356        output
357            .diagnostics
358            .animation_transform_effect_only_frame_count,
359    );
360
361    publish_window_performance_snapshot(
362        WindowPerformanceSnapshot::with_total_time_ms(
363            window_id,
364            frame_index,
365            total_time_ms,
366            phase_timings,
367            renderer_submission_diagnostics_from_frame_stats(&renderer_stats),
368            text_caches,
369            text_cache_deltas,
370            scene,
371        )
372        .with_presentation_latency(presentation_latency)
373        .with_runtime_text_timing(output.diagnostics.runtime_text_timing)
374        .with_retained_packet_hotspot(retained_packet_hotspot_diagnostics_from_frame_stats(
375            &renderer_stats,
376        ))
377        .with_widget_timings(output.diagnostics.widget_timings.clone())
378        .with_event_traces(
379            output.diagnostics.command_dispatches.clone(),
380            output.diagnostics.invalidations.clone(),
381        ),
382    );
383}
384
385#[cfg(test)]
386mod tests {
387    use super::{
388        renderer_submission_diagnostics_from_frame_stats,
389        retained_packet_hotspot_diagnostics_from_frame_stats, retained_packet_rebuild_diagnostics,
390        split_renderer_phase_times_ms,
391    };
392    use sui_render_wgpu::{RendererFrameStats, RendererPacketHotspot, RetainedPacketRebuildStats};
393
394    #[test]
395    fn retained_packet_rebuild_diagnostics_bridge_preserves_named_buckets() {
396        let rebuilds = RetainedPacketRebuildStats::new(2, 3, 5, 7, 11);
397
398        let diagnostics = retained_packet_rebuild_diagnostics(rebuilds);
399
400        assert_eq!(diagnostics.new_count, 2);
401        assert_eq!(diagnostics.coordinate_space_count, 3);
402        assert_eq!(diagnostics.signature_count, 5);
403        assert_eq!(diagnostics.scene_count, 7);
404        assert_eq!(diagnostics.state_count, 11);
405    }
406
407    #[test]
408    fn renderer_submission_diagnostics_from_frame_stats_preserves_retained_details() {
409        let renderer_stats = RendererFrameStats {
410            pass_count: 3,
411            draw_count: 9,
412            uploaded_vertex_bytes: 4096,
413            text_glyph_instance_count: 42,
414            text_vertex_bytes: 2048,
415            visible_layer_count: 4,
416            direct_packet_count: 6,
417            retained_state_update_time_us: 31,
418            composition_time_us: 32,
419            retained_scene_traversal_time_us: 33,
420            retained_packet_build_time_us: 34,
421            retained_packet_build_count: 2,
422            retained_packet_rebuilds: RetainedPacketRebuildStats::new(1, 0, 1, 1, 0),
423            retained_packet_normalize_time_us: 41,
424            retained_packet_signature_time_us: 42,
425            retained_packet_raster_state_init_time_us: 43,
426            retained_packet_scene_build_time_us: 44,
427            retained_packet_command_count: 45,
428            retained_packet_text_command_count: 46,
429            retained_packet_path_command_count: 47,
430            retained_packet_clip_path_command_count: 48,
431            retained_packet_image_command_count: 49,
432            retained_packet_rect_command_count: 50,
433            retained_packet_text_command_time_us: 51,
434            retained_packet_path_command_time_us: 52,
435            retained_packet_clip_path_command_time_us: 53,
436            retained_packet_image_command_time_us: 54,
437            retained_packet_rect_command_time_us: 55,
438            text_atlas_miss_count: 7,
439            text_atlas_miss_time_us: 56,
440            surface_acquire_time_us: 57,
441            resource_collection_time_us: 58,
442            bind_group_prepare_time_us: 59,
443            image_bind_group_time_us: 60,
444            analytic_path_bind_group_time_us: 61,
445            analytic_path_bind_group_miss_count: 8,
446            analytic_path_bind_group_upload_bytes: 62,
447            text_atlas_bind_group_time_us: 63,
448            text_atlas_upload_copy_time_us: 64,
449            text_atlas_upload_write_time_us: 65,
450            text_atlas_upload_bytes: 66,
451            batch_prepare_time_us: 67,
452            gpu_upload_time_us: 68,
453            pass_encode_time_us: 69,
454            queue_submit_time_us: 70,
455            surface_present_time_us: 71,
456            retained_packet_hotspot: Some(RendererPacketHotspot {
457                container_layer_id: Some(101),
458                owner_widget_id: Some(202),
459                segment_index: 3,
460                total_time_us: 72,
461                scene_build_time_us: 73,
462                command_count: 74,
463                text_command_count: 75,
464                path_command_count: 76,
465                rect_command_count: 77,
466                text_command_time_us: 78,
467                path_command_time_us: 79,
468                rect_command_time_us: 80,
469                text_sample: Some("packet text".to_string()),
470            }),
471            ..Default::default()
472        };
473
474        let diagnostics = renderer_submission_diagnostics_from_frame_stats(&renderer_stats);
475
476        assert_eq!(diagnostics.pass_count, 3);
477        assert_eq!(diagnostics.retained_packet_build_count, 2);
478        assert_eq!(diagnostics.retained_packet_rebuilds.new_count, 1);
479        assert_eq!(diagnostics.retained_packet_rebuilds.signature_count, 1);
480        assert_eq!(diagnostics.retained_packet_rebuilds.scene_count, 1);
481        assert_eq!(diagnostics.retained_packet_normalize_time_us, 41);
482        assert_eq!(diagnostics.retained_packet_command_count, 45);
483        assert_eq!(diagnostics.text_atlas_miss_count, 7);
484    }
485
486    #[test]
487    fn renderer_phase_split_separates_surface_wait_from_work() {
488        let renderer_stats = RendererFrameStats {
489            surface_acquire_time_us: 4_000,
490            surface_present_time_us: 8_000,
491            ..Default::default()
492        };
493
494        let (renderer_work_time_ms, surface_wait_time_ms) =
495            split_renderer_phase_times_ms(20.0, &renderer_stats);
496
497        assert_eq!(renderer_work_time_ms, 8.0);
498        assert_eq!(surface_wait_time_ms, 12.0);
499    }
500
501    #[test]
502    fn renderer_phase_split_caps_wait_at_renderer_wall_time() {
503        let renderer_stats = RendererFrameStats {
504            surface_acquire_time_us: 9_000,
505            surface_present_time_us: 9_000,
506            ..Default::default()
507        };
508
509        let (renderer_work_time_ms, surface_wait_time_ms) =
510            split_renderer_phase_times_ms(10.0, &renderer_stats);
511
512        assert_eq!(renderer_work_time_ms, 0.0);
513        assert_eq!(surface_wait_time_ms, 10.0);
514    }
515
516    #[test]
517    fn retained_packet_hotspot_diagnostics_bridge_preserves_hotspot_fields() {
518        let renderer_stats = RendererFrameStats {
519            retained_packet_hotspot: Some(RendererPacketHotspot {
520                container_layer_id: Some(11),
521                owner_widget_id: Some(22),
522                segment_index: 3,
523                total_time_us: 44,
524                scene_build_time_us: 55,
525                command_count: 66,
526                text_command_count: 77,
527                path_command_count: 88,
528                rect_command_count: 99,
529                text_command_time_us: 111,
530                path_command_time_us: 222,
531                rect_command_time_us: 333,
532                text_sample: Some("sample".to_string()),
533            }),
534            ..Default::default()
535        };
536
537        let hotspot = retained_packet_hotspot_diagnostics_from_frame_stats(&renderer_stats)
538            .expect("expected hotspot diagnostics");
539
540        assert_eq!(hotspot.container_layer_id, Some(11));
541        assert_eq!(hotspot.owner_widget_id, Some(22));
542        assert_eq!(hotspot.segment_index, 3);
543        assert_eq!(hotspot.total_time_us, 44);
544        assert_eq!(hotspot.scene_build_time_us, 55);
545        assert_eq!(hotspot.command_count, 66);
546        assert_eq!(hotspot.text_command_count, 77);
547        assert_eq!(hotspot.path_command_count, 88);
548        assert_eq!(hotspot.rect_command_count, 99);
549        assert_eq!(hotspot.text_command_time_us, 111);
550        assert_eq!(hotspot.path_command_time_us, 222);
551        assert_eq!(hotspot.rect_command_time_us, 333);
552        assert_eq!(hotspot.text_sample.as_deref(), Some("sample"));
553    }
554}