Skip to main content

sui_platform/
lib.rs

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