Skip to main content

sui_platform/
present.rs

1//! Presenting a window's frame. Every host (the desktop and headless
2//! platforms and the live test harness) presents through
3//! [`present_window_frame`], so windows render, report their output, and
4//! style HDR content the same way everywhere.
5
6use sui_core::{Result, WindowId};
7use sui_render_wgpu::{
8    DisplayCapabilities, FeatheringOptions, OutputGamut, OutputStrategy, WgpuRenderer,
9};
10use sui_runtime::{
11    OutputColorRange, RenderOutput, Runtime, WindowRenderOptions, set_window_output_color_range,
12    window_render_options, window_scene_statistics_detail_mode,
13};
14use web_time::Instant;
15
16use crate::{
17    WindowOutputDiagnostics, map_window_color_management, map_window_text_coverage_policy,
18    publish_window_output_diagnostics, resolve_sdr_content_brightness_nits,
19};
20
21/// What presenting a frame produced, for the host's own bookkeeping.
22pub struct PresentedFrame {
23    pub output: RenderOutput,
24    pub runtime_time_ms: f64,
25    pub renderer_time_ms: f64,
26    /// When the renderer returned from presenting, before diagnostics were
27    /// published.
28    pub presented_at: Instant,
29}
30
31/// Render `window_id`'s next frame and present it with `renderer`.
32///
33/// This applies the window's render options to the renderer, records what
34/// its output can show so widgets style HDR content to fit
35/// ([`OutputColorRange`]), renders and presents the runtime's frame, and
36/// publishes the window's output diagnostics. Hosts set the window's display
37/// capabilities on the renderer beforehand, and afterwards service debug
38/// captures and do their own bookkeeping with the result.
39pub fn present_window_frame(
40    runtime: &mut Runtime,
41    renderer: &mut WgpuRenderer,
42    window_id: WindowId,
43) -> Result<PresentedFrame> {
44    let setup_started = Instant::now();
45    let options = apply_render_options(renderer, window_id)?;
46    // Before the runtime paints, so widgets style for this frame's output.
47    if let Some(strategy) = renderer.window_output_strategy(window_id) {
48        let gamut = strategy.gamut(
49            &renderer
50                .window_display_capabilities(window_id)
51                .unwrap_or_default(),
52        );
53        set_window_output_color_range(window_id, output_color_range(strategy, gamut));
54    }
55    let setup_time = setup_started.elapsed();
56
57    let runtime_started = Instant::now();
58    let output = runtime.render(window_id)?;
59    let runtime_time_ms = runtime_started.elapsed().as_secs_f64() * 1000.0;
60
61    let renderer_started = Instant::now();
62    renderer.render(&output.frame)?;
63    let presented_at = Instant::now();
64    publish_output_diagnostics(renderer, window_id, &options);
65    let renderer_time_ms = (setup_time + renderer_started.elapsed()).as_secs_f64() * 1000.0;
66
67    Ok(PresentedFrame {
68        output,
69        runtime_time_ms,
70        renderer_time_ms,
71        presented_at,
72    })
73}
74
75/// The window's options as the renderer applied them.
76struct AppliedOptions {
77    options: WindowRenderOptions,
78    sdr_content_brightness_nits: f32,
79}
80
81fn apply_render_options(
82    renderer: &mut WgpuRenderer,
83    window_id: WindowId,
84) -> Result<AppliedOptions> {
85    renderer.set_runtime_diagnostics_enabled(
86        window_scene_statistics_detail_mode(window_id).is_detailed(),
87    );
88    let render_options = window_render_options(window_id);
89    renderer.set_runtime_feathering_override(
90        render_options.map(|options| {
91            FeatheringOptions::new(options.feathering_enabled, options.feather_width)
92        }),
93    );
94    renderer.set_runtime_text_hinting_override(
95        render_options.map(|options| options.text_hinting.normalized()),
96    );
97    renderer.set_runtime_stem_darkening_override(
98        render_options.map(|options| options.stem_darkening.normalized()),
99    );
100    renderer.set_runtime_text_coverage_policy_override(
101        render_options.map(|options| map_window_text_coverage_policy(options.text_coverage_policy)),
102    );
103    renderer.set_runtime_text_subpixel_order_override(
104        render_options.map(|options| options.text_subpixel_order),
105    );
106    renderer.set_runtime_system_text_smoothing_enabled(
107        render_options.is_none_or(|options| options.use_system_text_smoothing),
108    );
109
110    // Without options, color management uses the defaults.
111    let options = render_options.unwrap_or_else(|| WindowRenderOptions::new(false, 0.0));
112    let sdr_content_brightness_nits = resolve_sdr_content_brightness_nits(
113        options.sdr_content_brightness_nits,
114        options.use_system_sdr_content_brightness,
115        &renderer
116            .window_display_capabilities(window_id)
117            .unwrap_or_default(),
118    );
119    renderer.set_window_color_management(
120        window_id,
121        map_window_color_management(
122            options.color_management_mode,
123            options.output_color_primaries,
124            options.dynamic_range_mode,
125            options.tone_mapping_mode,
126            sdr_content_brightness_nits,
127        ),
128    )?;
129    Ok(AppliedOptions {
130        options,
131        sdr_content_brightness_nits,
132    })
133}
134
135/// What an output presenting with `strategy` in `gamut` can show.
136fn output_color_range(strategy: OutputStrategy, gamut: OutputGamut) -> OutputColorRange {
137    match strategy {
138        OutputStrategy::HdrNativeSurface { .. } => OutputColorRange::HighDynamicRange,
139        _ if gamut.is_wide() => OutputColorRange::WideGamut,
140        _ => OutputColorRange::Standard,
141    }
142}
143
144fn publish_output_diagnostics(
145    renderer: &WgpuRenderer,
146    window_id: WindowId,
147    applied: &AppliedOptions,
148) {
149    let (Some(mut display_capabilities), Some(active_output_strategy)) = (
150        renderer.window_display_capabilities(window_id),
151        renderer.window_output_strategy(window_id),
152    ) else {
153        return;
154    };
155    if let Some(formats) = renderer.window_surface_formats(window_id) {
156        append_note(
157            &mut display_capabilities,
158            &format!("Surface formats: {formats:?}."),
159        );
160    }
161    let options = &applied.options;
162    let output_gamut = active_output_strategy.gamut(&display_capabilities);
163    publish_window_output_diagnostics(
164        window_id,
165        WindowOutputDiagnostics {
166            system_sdr_content_brightness_nits: display_capabilities.sdr_white_nits,
167            display_capabilities,
168            requested_color_management_mode: options.color_management_mode,
169            requested_output_primaries: options.output_color_primaries,
170            requested_dynamic_range_mode: options.dynamic_range_mode,
171            requested_tone_mapping_mode: options.tone_mapping_mode,
172            requested_sdr_content_brightness_nits: applied.sdr_content_brightness_nits,
173            configured_sdr_content_brightness_nits: options.sdr_content_brightness_nits,
174            use_system_sdr_content_brightness: options.use_system_sdr_content_brightness,
175            active_output_strategy,
176            output_gamut,
177        },
178    );
179}
180
181fn append_note(capabilities: &mut DisplayCapabilities, note: &str) {
182    if !capabilities.notes.is_empty() {
183        capabilities.notes.push(' ');
184    }
185    capabilities.notes.push_str(note);
186}