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