Skip to main content

sui_render_wgpu/
renderer.rs

1use crate::WgpuRenderer;
2use crate::device::default_wgpu_instance;
3use crate::diagnostics::RendererFrameStats;
4use crate::interop::WgpuExternalTextureRegistry;
5use crate::output::ColorManagementMode;
6use crate::output::DisplayCapabilities;
7use crate::output::OutputStrategy;
8use crate::output::RendererCapabilities;
9use crate::resources::FrameResources;
10use crate::resources::{IMAGE_CACHE_BUDGET_BYTES, IMAGE_CACHE_IDLE};
11use crate::surface::normalize_framebuffer_size;
12use crate::text::RendererTextCacheSnapshot;
13use crate::text_engine::TextEngine;
14use crate::text_policy::FeatheringOptions;
15use crate::text_policy::StemDarkening;
16use crate::text_policy::TextCoveragePolicy;
17use crate::text_policy::TextHinting;
18use crate::text_policy::TextRenderMode;
19use std::collections::HashMap;
20use std::fmt;
21use sui_core::Result;
22use sui_core::WindowId;
23use sui_scene::SceneFrame;
24pub use sui_scene::TextSubpixelOrder;
25
26/// The image textures to release: those unused for `idle`, then the least
27/// recently used until the rest fit `budget` bytes. Textures used by frame
28/// `drawn` are kept even over budget, since the screen still shows them.
29pub(crate) fn image_textures_to_evict<K: Copy>(
30    entries: impl Iterator<Item = (K, usize, web_time::Instant, u64)>,
31    drawn: usize,
32    now: web_time::Instant,
33    idle: std::time::Duration,
34    budget: u64,
35) -> Vec<K> {
36    let mut evicted = Vec::new();
37    let mut kept = Vec::new();
38    let mut total = 0;
39    for (key, last_used_frame, last_used_at, bytes) in entries {
40        let used = last_used_frame >= drawn;
41        if used || now.duration_since(last_used_at) <= idle {
42            total += bytes;
43            if !used {
44                kept.push((last_used_at, bytes, key));
45            }
46        } else {
47            evicted.push(key);
48        }
49    }
50    kept.sort_by_key(|(last_used_at, _, _)| *last_used_at);
51    for (_, bytes, key) in kept {
52        if total <= budget {
53            break;
54        }
55        evicted.push(key);
56        total -= bytes;
57    }
58    evicted
59}
60
61/// How much memory [`WgpuRenderer::trim_memory`] gives up.
62#[derive(Debug, Clone, Copy, PartialEq, Eq)]
63pub enum MemoryTrimLevel {
64    /// The app is in the background: free what is quick to recreate and
65    /// keep the retained scene, so returning to the app stays fast.
66    Background,
67    /// The system is short of memory: free everything that can be rebuilt.
68    Critical,
69}
70
71impl WgpuRenderer {
72    pub fn new() -> Self {
73        Self::default()
74    }
75
76    pub fn with_feathering(mut self, feathering: FeatheringOptions) -> Self {
77        self.set_feathering(feathering);
78        self
79    }
80
81    pub fn with_feathering_enabled(mut self, enabled: bool) -> Self {
82        self.set_feathering_enabled(enabled);
83        self
84    }
85
86    pub fn with_text_coverage_policy(mut self, policy: TextCoveragePolicy) -> Self {
87        self.set_text_coverage_policy(policy);
88        self
89    }
90
91    pub fn with_text_render_mode(mut self, mode: TextRenderMode) -> Self {
92        self.set_text_render_mode(mode);
93        self
94    }
95
96    pub fn with_text_subpixel_order(mut self, order: TextSubpixelOrder) -> Self {
97        self.set_text_subpixel_order(order);
98        self
99    }
100
101    pub fn with_text_hinting(mut self, hinting: TextHinting) -> Self {
102        self.set_text_hinting(hinting);
103        self
104    }
105
106    pub fn with_stem_darkening(mut self, darkening: StemDarkening) -> Self {
107        self.set_stem_darkening(darkening);
108        self
109    }
110
111    pub fn with_feather_width(mut self, feather_width: f32) -> Self {
112        self.set_feather_width(feather_width);
113        self
114    }
115
116    pub fn with_vsync_enabled(mut self, enabled: bool) -> Self {
117        self.set_vsync_enabled(enabled);
118        self
119    }
120
121    pub fn with_external_texture_registry(mut self, registry: WgpuExternalTextureRegistry) -> Self {
122        self.set_external_texture_registry(registry);
123        self
124    }
125
126    pub fn feathering(&self) -> FeatheringOptions {
127        FeatheringOptions::new(self.feathering_enabled, self.feather_width)
128    }
129
130    pub fn feathering_enabled(&self) -> bool {
131        self.feathering_enabled
132    }
133
134    pub fn feather_width(&self) -> f32 {
135        self.feather_width
136    }
137
138    pub fn vsync_enabled(&self) -> bool {
139        self.vsync_enabled
140    }
141
142    pub fn external_texture_registry(&self) -> Option<&WgpuExternalTextureRegistry> {
143        self.external_texture_registry.as_ref()
144    }
145
146    pub fn set_external_texture_registry(&mut self, registry: WgpuExternalTextureRegistry) {
147        if let Some(shared) = &self.shared {
148            registry.attach(
149                shared.device.clone(),
150                shared.queue.clone(),
151                shared.adapter.get_info(),
152            );
153        }
154        self.external_texture_registry = Some(registry);
155        self.external_image_cache.clear();
156    }
157
158    pub fn text_coverage_policy(&self) -> TextCoveragePolicy {
159        self.text_coverage_policy
160    }
161
162    pub fn text_render_mode(&self) -> TextRenderMode {
163        self.text_render_mode
164    }
165
166    pub fn text_subpixel_order(&self) -> TextSubpixelOrder {
167        self.text_subpixel_order
168    }
169
170    pub fn text_hinting(&self) -> TextHinting {
171        self.text_hinting
172    }
173
174    pub fn stem_darkening(&self) -> StemDarkening {
175        self.stem_darkening
176    }
177
178    pub fn set_feathering(&mut self, feathering: FeatheringOptions) {
179        let feathering = feathering.clamped();
180        self.feathering_enabled = feathering.enabled;
181        self.feather_width = feathering.width;
182    }
183
184    pub fn set_feathering_enabled(&mut self, enabled: bool) {
185        self.feathering_enabled = enabled;
186    }
187
188    pub fn set_text_coverage_policy(&mut self, policy: TextCoveragePolicy) {
189        let policy = policy.normalized();
190        if self.text_coverage_policy == policy {
191            return;
192        }
193
194        self.text_coverage_policy = policy;
195        if let Some(text_engine) = self.text_engine.as_mut() {
196            text_engine.set_text_coverage_policy(policy);
197        }
198        self.invalidate_text_render_state();
199    }
200
201    pub fn set_text_render_mode(&mut self, mode: TextRenderMode) {
202        if self.text_render_mode == mode {
203            return;
204        }
205
206        self.text_render_mode = mode;
207        if let Some(text_engine) = self.text_engine.as_mut() {
208            text_engine.set_text_render_mode(mode);
209        }
210        self.invalidate_text_render_state();
211    }
212
213    pub fn set_text_subpixel_order(&mut self, order: TextSubpixelOrder) {
214        if self.text_subpixel_order == order {
215            return;
216        }
217
218        self.text_subpixel_order = order;
219        if let Some(text_engine) = self.text_engine.as_mut() {
220            text_engine.set_text_subpixel_order(order);
221        }
222        self.invalidate_text_render_state();
223    }
224
225    pub fn set_text_hinting(&mut self, hinting: TextHinting) {
226        let hinting = hinting.normalized();
227        if self.text_hinting == hinting {
228            return;
229        }
230
231        self.text_hinting = hinting;
232        if let Some(text_engine) = self.text_engine.as_mut() {
233            text_engine.set_text_hinting(hinting);
234        }
235    }
236
237    pub fn set_stem_darkening(&mut self, darkening: StemDarkening) {
238        let darkening = darkening.normalized();
239        if self.stem_darkening == darkening {
240            return;
241        }
242
243        self.stem_darkening = darkening;
244        if let Some(text_engine) = self.text_engine.as_mut() {
245            text_engine.set_stem_darkening(darkening);
246        }
247    }
248
249    pub fn set_feather_width(&mut self, feather_width: f32) {
250        self.feather_width = feather_width.max(0.0);
251    }
252
253    pub fn set_vsync_enabled(&mut self, enabled: bool) {
254        self.vsync_enabled = enabled;
255    }
256
257    pub fn set_window_display_capabilities(
258        &mut self,
259        window_id: WindowId,
260        capabilities: DisplayCapabilities,
261    ) -> Result<()> {
262        let Some(surface) = self.surfaces.get_mut(&window_id) else {
263            // Offscreen windows render as if presenting to this display.
264            self.offscreen_outputs
265                .entry(window_id)
266                .or_default()
267                .display_capabilities = capabilities;
268            return Ok(());
269        };
270        if surface.display_capabilities == capabilities {
271            return Ok(());
272        }
273        surface.display_capabilities = capabilities;
274        self.configure_existing_surface(window_id)
275    }
276
277    /// The subpixel order the system antialiases text for on the window's
278    /// display, without cloning its whole capability profile.
279    pub(crate) fn window_system_text_subpixel_order(
280        &self,
281        window_id: WindowId,
282    ) -> TextSubpixelOrder {
283        self.surfaces
284            .get(&window_id)
285            .map(|surface| surface.display_capabilities.text_subpixel_order)
286            .or_else(|| {
287                self.offscreen_outputs
288                    .get(&window_id)
289                    .map(|output| output.display_capabilities.text_subpixel_order)
290            })
291            .unwrap_or_default()
292    }
293
294    pub fn window_display_capabilities(&self, window_id: WindowId) -> Option<DisplayCapabilities> {
295        self.surfaces
296            .get(&window_id)
297            .map(|surface| surface.display_capabilities.clone())
298            .or_else(|| {
299                self.offscreen_outputs
300                    .get(&window_id)
301                    .map(|output| output.display_capabilities.clone())
302            })
303    }
304
305    pub fn set_window_color_management(
306        &mut self,
307        window_id: WindowId,
308        color_management: ColorManagementMode,
309    ) -> Result<()> {
310        let Some(surface) = self.surfaces.get_mut(&window_id) else {
311            // Offscreen windows fit and capture with it too.
312            self.offscreen_outputs
313                .entry(window_id)
314                .or_default()
315                .color_management = color_management;
316            return Ok(());
317        };
318        if surface.color_management == color_management {
319            return Ok(());
320        }
321        surface.color_management = color_management;
322        self.configure_existing_surface(window_id)
323    }
324
325    /// The color management `window_id` renders with.
326    pub fn window_color_management(&self, window_id: WindowId) -> ColorManagementMode {
327        self.surfaces
328            .get(&window_id)
329            .map(|surface| surface.color_management)
330            .or_else(|| {
331                self.offscreen_outputs
332                    .get(&window_id)
333                    .map(|output| output.color_management)
334            })
335            .unwrap_or_default()
336    }
337
338    /// The strategy `window_id` presents with. A window without a surface
339    /// reports the strategy it would use on the display it was given.
340    pub fn window_output_strategy(&self, window_id: WindowId) -> Option<OutputStrategy> {
341        self.surfaces
342            .get(&window_id)
343            .map(|surface| surface.output_strategy)
344            .or_else(|| {
345                self.offscreen_outputs
346                    .get(&window_id)
347                    .map(crate::output::OffscreenOutput::output_strategy)
348            })
349    }
350
351    pub fn window_surface_formats(&self, window_id: WindowId) -> Option<Vec<wgpu::TextureFormat>> {
352        self.surfaces
353            .get(&window_id)
354            .map(|surface| surface.available_surface_formats.clone())
355    }
356
357    pub fn set_runtime_feathering_override(&mut self, feathering: Option<FeatheringOptions>) {
358        self.runtime_feathering_override = feathering.map(FeatheringOptions::clamped);
359    }
360
361    pub fn set_runtime_text_subpixel_order_override(&mut self, order: Option<TextSubpixelOrder>) {
362        self.runtime_text_subpixel_order_override = order;
363    }
364
365    /// Whether the window being rendered follows the system's text smoothing:
366    /// LCD text in the order its display capabilities report
367    /// ([`DisplayCapabilities::text_subpixel_order`]). On by default.
368    pub fn set_runtime_system_text_smoothing_enabled(&mut self, enabled: bool) {
369        self.runtime_system_text_smoothing_enabled = enabled;
370    }
371
372    pub fn set_runtime_text_hinting_override(&mut self, hinting: Option<TextHinting>) {
373        self.runtime_text_hinting_override = hinting.map(TextHinting::normalized);
374    }
375
376    pub fn set_runtime_stem_darkening_override(&mut self, darkening: Option<StemDarkening>) {
377        self.runtime_stem_darkening_override = darkening.map(StemDarkening::normalized);
378    }
379
380    pub fn set_runtime_text_coverage_policy_override(
381        &mut self,
382        policy: Option<TextCoveragePolicy>,
383    ) {
384        self.runtime_text_coverage_policy_override = policy.map(TextCoveragePolicy::normalized);
385    }
386
387    pub fn set_runtime_diagnostics_enabled(&mut self, enabled: bool) {
388        self.runtime_diagnostics_enabled = enabled;
389        if let Some(shared) = &mut self.shared {
390            shared.collect_pipeline_timings = enabled;
391        }
392        if let Some(text_engine) = self.text_engine.as_mut() {
393            text_engine.set_diagnostics_enabled(enabled);
394        }
395        for compositor in self.compositors.values_mut() {
396            compositor.set_diagnostics_enabled(enabled);
397        }
398    }
399
400    pub(crate) fn active_feather_width(&self) -> f32 {
401        self.runtime_feathering_override
402            .unwrap_or_else(|| self.feathering())
403            .effective_width()
404    }
405
406    pub(crate) fn active_text_hinting(&self) -> TextHinting {
407        self.runtime_text_hinting_override
408            .unwrap_or(self.text_hinting)
409            .normalized()
410    }
411
412    pub(crate) fn active_text_subpixel_order(&self) -> TextSubpixelOrder {
413        self.runtime_text_subpixel_order_override
414            .unwrap_or(self.text_subpixel_order)
415    }
416
417    pub(crate) fn active_stem_darkening(&self) -> StemDarkening {
418        self.runtime_stem_darkening_override
419            .unwrap_or(self.stem_darkening)
420            .normalized()
421    }
422
423    pub(crate) fn active_text_coverage_policy(&self) -> TextCoveragePolicy {
424        self.runtime_text_coverage_policy_override
425            .unwrap_or(self.text_coverage_policy)
426            .normalized()
427    }
428
429    pub(crate) fn invalidate_text_render_state(&mut self) {
430        self.text_engine = None;
431        self.text_atlas_array = None;
432        self.compositors.clear();
433        self.last_frames.clear();
434        self.last_frame_stats.clear();
435    }
436
437    /// Give up retained memory the renderer can rebuild.
438    ///
439    /// [`MemoryTrimLevel::Background`] keeps what makes the next frame
440    /// cheap, the retained scene and its GPU geometry, and frees textures
441    /// and staging memory that are quick to recreate. Call it when the app
442    /// is backgrounded. [`MemoryTrimLevel::Critical`] frees everything that
443    /// can be rebuilt, at the cost of rebuilding it on the next frame. Call
444    /// it when the system reports memory pressure.
445    pub fn trim_memory(&mut self, level: MemoryTrimLevel) {
446        self.image_cache.clear();
447        self.frame_resources.uploads.release();
448        self.frame_resources.stencil = None;
449        // Frames of windows without a surface are not being shown.
450        let dropped = self
451            .offscreen_targets
452            .keys()
453            .chain(self.intermediate_targets.keys())
454            .chain(self.swapchain_frames.keys())
455            .copied()
456            .filter(|window_id| {
457                level == MemoryTrimLevel::Critical || !self.surfaces.contains_key(window_id)
458            })
459            .collect::<Vec<_>>();
460        for window_id in dropped {
461            self.offscreen_targets.remove(&window_id);
462            self.intermediate_targets.remove(&window_id);
463            self.swapchain_frames.remove(&window_id);
464            // A recreated target shows nothing yet.
465            self.frame_resources.target_contents.remove(&window_id);
466        }
467        if level == MemoryTrimLevel::Critical {
468            self.text_engine = None;
469            self.text_atlas_array = None;
470            self.compositors.clear();
471            self.analytic_path_cache.clear();
472            self.frame_resources.analytic_path_arena = Default::default();
473            self.frame_resources.fragments.clear();
474            self.frame_resources.fragment_groups.clear();
475            self.frame_resources.packet_bounds.clear();
476            self.frame_resources.target_contents.clear();
477        }
478    }
479
480    /// Release image textures unused for [`IMAGE_CACHE_IDLE`], then the least
481    /// recently used ones until the cache fits [`IMAGE_CACHE_BUDGET_BYTES`].
482    /// Textures the frame just drawn used are always kept.
483    fn evict_image_textures(&mut self) {
484        let evicted = image_textures_to_evict(
485            self.image_cache
486                .iter()
487                .map(|(key, entry)| (*key, entry.last_used_frame, entry.last_used_at, entry.bytes)),
488            self.frames_rendered.saturating_sub(1),
489            web_time::Instant::now(),
490            IMAGE_CACHE_IDLE,
491            IMAGE_CACHE_BUDGET_BYTES,
492        );
493        for key in evicted {
494            self.image_cache.remove(&key);
495        }
496    }
497
498    /// Release only `window_id`'s surface, as a mobile host must when the
499    /// app is backgrounded. Everything retained for the window stays, so the
500    /// first frame after [`register_window`](Self::register_window) reuses
501    /// it instead of rebuilding the whole scene.
502    pub fn suspend_window(&mut self, window_id: WindowId) {
503        self.prepared_surfaces.remove(&window_id);
504        self.surfaces.remove(&window_id);
505    }
506
507    pub fn remove_window(&mut self, window_id: WindowId) {
508        self.prepared_surfaces.remove(&window_id);
509        #[cfg(any(target_os = "linux", target_os = "windows", target_os = "macos"))]
510        if self
511            .device_preparation
512            .as_ref()
513            .is_some_and(|pending| pending.window == Some(window_id))
514        {
515            self.device_preparation = None;
516        }
517        self.frame_resources.fragments.remove(&window_id);
518        self.frame_resources.output_transforms.remove(&window_id);
519        self.frame_resources
520            .fragment_translations
521            .remove(&window_id);
522        self.frame_resources.fragment_groups.remove(&window_id);
523        self.frame_resources.target_contents.remove(&window_id);
524        self.frame_resources.packet_bounds.remove(&window_id);
525        self.surfaces.remove(&window_id);
526        self.offscreen_outputs.remove(&window_id);
527        self.offscreen_targets.remove(&window_id);
528        self.intermediate_targets.remove(&window_id);
529        self.swapchain_frames.remove(&window_id);
530        self.last_frames.remove(&window_id);
531        self.last_frame_stats.remove(&window_id);
532        self.compositors.remove(&window_id);
533        self.debug_captures_in_flight
534            .retain(|capture| capture.window_id != window_id);
535    }
536
537    pub fn render(&mut self, frame: &SceneFrame) -> Result<()> {
538        let pipeline_before = self.shared.as_ref().map_or((0, 0), |shared| {
539            (shared.pipeline_create_time_us, shared.pipeline_create_count)
540        });
541        let viewport = normalize_framebuffer_size(frame.surface_size);
542        let mut frame_stats = RendererFrameStats::default();
543
544        if let Some(size) = viewport {
545            if self.surfaces.contains_key(&frame.window_id) {
546                frame_stats = self.render_surface(frame, size)?;
547            } else {
548                frame_stats = self.render_offscreen(frame, size)?;
549            }
550        }
551
552        frame_stats.device_prepare_time_us =
553            std::mem::take(&mut self.pending_device_prepare_time_us);
554        frame_stats.device_prepare_wait_time_us =
555            std::mem::take(&mut self.pending_device_wait_time_us);
556        if let Some(shared) = &self.shared {
557            frame_stats.pipeline_create_time_us =
558                shared.pipeline_create_time_us - pipeline_before.0;
559            frame_stats.pipeline_create_count = shared.pipeline_create_count - pipeline_before.1;
560        }
561        self.frames_rendered += 1;
562        self.last_frames.insert(frame.window_id, frame.clone());
563        self.last_frame_stats.insert(frame.window_id, frame_stats);
564        self.analytic_path_cache
565            .retain(|_, entry| self.frames_rendered.saturating_sub(entry.last_used_frame) <= 120);
566        self.evict_image_textures();
567        Ok(())
568    }
569
570    pub fn capabilities(&self) -> RendererCapabilities {
571        self.capabilities
572    }
573
574    /// Adapter metadata after initialization, without requiring an interop registry.
575    pub fn adapter_info(&self) -> Option<wgpu::AdapterInfo> {
576        self.shared.as_ref().map(|shared| shared.adapter.get_info())
577    }
578
579    pub fn frames_rendered(&self) -> usize {
580        self.frames_rendered
581    }
582
583    pub fn last_frame(&self, window_id: WindowId) -> Option<&SceneFrame> {
584        self.last_frames.get(&window_id)
585    }
586
587    pub fn last_frame_stats(&self, window_id: WindowId) -> Option<RendererFrameStats> {
588        self.last_frame_stats.get(&window_id).cloned()
589    }
590
591    pub fn text_cache_snapshot(&self, window_id: WindowId) -> RendererTextCacheSnapshot {
592        let mut snapshot = self
593            .text_engine
594            .as_ref()
595            .map(TextEngine::cache_snapshot)
596            .unwrap_or_default();
597        snapshot.path = self
598            .compositors
599            .get(&window_id)
600            .map(|compositor| compositor.path_cache.snapshot())
601            .unwrap_or_default();
602        snapshot
603    }
604}
605
606impl Default for WgpuRenderer {
607    fn default() -> Self {
608        Self {
609            instance: default_wgpu_instance(),
610            feathering_enabled: FeatheringOptions::default().enabled,
611            feather_width: FeatheringOptions::default().width,
612            text_render_mode: TextRenderMode::default(),
613            text_subpixel_order: TextSubpixelOrder::default(),
614            text_hinting: TextHinting::default(),
615            stem_darkening: StemDarkening::default(),
616            text_coverage_policy: TextCoveragePolicy::default(),
617            vsync_enabled: true,
618            runtime_feathering_override: None,
619            runtime_text_subpixel_order_override: None,
620            runtime_system_text_smoothing_enabled: true,
621            runtime_text_hinting_override: None,
622            runtime_stem_darkening_override: None,
623            runtime_text_coverage_policy_override: None,
624            runtime_diagnostics_enabled: true,
625            pending_device_prepare_time_us: 0,
626            pending_device_wait_time_us: 0,
627            #[cfg(any(target_os = "linux", target_os = "windows", target_os = "macos"))]
628            device_preparation: None,
629            prepared_surfaces: HashMap::new(),
630            frames_rendered: 0,
631            capabilities: RendererCapabilities::default(),
632            last_frames: HashMap::new(),
633            last_frame_stats: HashMap::new(),
634            shared: None,
635            text_engine: None,
636            image_cache: HashMap::new(),
637            external_texture_registry: None,
638            external_image_cache: HashMap::new(),
639            text_atlas_array: None,
640            analytic_path_cache: HashMap::new(),
641            compositors: HashMap::new(),
642            surfaces: HashMap::new(),
643            offscreen_targets: HashMap::new(),
644            intermediate_targets: HashMap::new(),
645            swapchain_frames: HashMap::new(),
646            offscreen_outputs: HashMap::new(),
647            frame_resources: FrameResources::default(),
648            debug_captures_in_flight: Vec::new(),
649            next_debug_capture_id: 1,
650        }
651    }
652}
653
654impl fmt::Debug for WgpuRenderer {
655    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
656        f.debug_struct("WgpuRenderer")
657            .field("feathering_enabled", &self.feathering_enabled)
658            .field("feather_width", &self.feather_width)
659            .field("text_coverage_policy", &self.text_coverage_policy)
660            .field("frames_rendered", &self.frames_rendered)
661            .field("capabilities", &self.capabilities)
662            .field("last_frame_count", &self.last_frames.len())
663            .field("last_frame_stats_count", &self.last_frame_stats.len())
664            .field("has_device", &self.shared.is_some())
665            .field("surface_count", &self.surfaces.len())
666            .finish()
667    }
668}