Skip to main content

sim_engine/renderer/
config.rs

1use super::*;
2use std::fmt;
3
4const DEFAULT_MAX_QUARANTINED_DEVICES: usize = 4;
5const MAX_QUARANTINED_DEVICES: usize = 8;
6
7pub(super) struct MultisampleTarget {
8    pub(super) _texture: wgpu::Texture,
9    pub(super) view: wgpu::TextureView,
10}
11
12/// Presentation behavior for the window surface.
13///
14/// `Vsync` requests strict FIFO presentation for stable frame pacing and no
15/// tearing. `NoVsync` requests the fastest available non-VSync mode, but may
16/// fall back to FIFO when the platform exposes no Immediate or Mailbox mode.
17#[derive(Debug, Clone, Copy, PartialEq, Eq)]
18pub enum RendererPresentMode {
19    /// Use strict FIFO presentation synchronized to display refresh.
20    Vsync,
21    /// Prefer Immediate, then Mailbox, and fall back to FIFO when necessary.
22    NoVsync,
23}
24
25/// Concrete presentation mode selected from the active Linux surface.
26///
27/// This is deliberately separate from [`RendererPresentMode`]: `NoVsync` is a
28/// preference with fallbacks, while this type reports the mode actually passed
29/// to `wgpu` after inspecting the surface capabilities. A compositor may still
30/// pace redraw callbacks or scanout independently of this selection.
31#[derive(Debug, Clone, Copy, PartialEq, Eq)]
32pub enum RendererSurfacePresentMode {
33    /// Immediate replacement without a presentation queue or refresh pacing.
34    Immediate,
35    /// Single-slot replacement queue synchronized to display refresh.
36    Mailbox,
37    /// Strict first-in-first-out queue synchronized to display refresh.
38    Fifo,
39    /// FIFO that may tear when a frame misses the refresh interval.
40    FifoRelaxed,
41}
42
43impl RendererSurfacePresentMode {
44    pub(super) const fn to_wgpu(self) -> wgpu::PresentMode {
45        match self {
46            Self::Immediate => wgpu::PresentMode::Immediate,
47            Self::Mailbox => wgpu::PresentMode::Mailbox,
48            Self::Fifo => wgpu::PresentMode::Fifo,
49            Self::FifoRelaxed => wgpu::PresentMode::FifoRelaxed,
50        }
51    }
52
53    /// Returns whether this mode presents on display refresh boundaries.
54    pub const fn is_refresh_synchronized(self) -> bool {
55        !matches!(self, Self::Immediate)
56    }
57}
58
59impl fmt::Display for RendererSurfacePresentMode {
60    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
61        match self {
62            Self::Immediate => formatter.write_str("Immediate"),
63            Self::Mailbox => formatter.write_str("Mailbox"),
64            Self::Fifo => formatter.write_str("FIFO"),
65            Self::FifoRelaxed => formatter.write_str("FIFO relaxed"),
66        }
67    }
68}
69
70pub(super) fn select_surface_present_mode(
71    requested: RendererPresentMode,
72    supported: &[wgpu::PresentMode],
73) -> RendererSurfacePresentMode {
74    match requested {
75        RendererPresentMode::Vsync => RendererSurfacePresentMode::Fifo,
76        RendererPresentMode::NoVsync => [
77            RendererSurfacePresentMode::Immediate,
78            RendererSurfacePresentMode::Mailbox,
79            RendererSurfacePresentMode::Fifo,
80        ]
81        .into_iter()
82        .find(|candidate| supported.contains(&candidate.to_wgpu()))
83        .unwrap_or(RendererSurfacePresentMode::Fifo),
84    }
85}
86
87/// Options used when creating a [`WgpuRenderer`].
88#[derive(Debug, Clone, Copy, PartialEq)]
89pub struct WgpuRendererOptions {
90    present_mode: RendererPresentMode,
91    scale_factor: f64,
92    max_quarantined_devices: usize,
93}
94
95impl WgpuRendererOptions {
96    /// Builds options from presentation behavior and display scale.
97    ///
98    /// `scale_factor` is physical surface pixels per logical screen pixel. It
99    /// must be finite, representable as `f32`, and bounded so every non-empty
100    /// `u32` surface keeps its logical dimensions and reciprocal clip scale in
101    /// the normal finite `f32` range.
102    pub fn new(
103        present_mode: RendererPresentMode,
104        scale_factor: f64,
105    ) -> Result<Self, RendererConfigurationError> {
106        validate_scale_factor(scale_factor)?;
107        Ok(Self {
108            present_mode,
109            scale_factor,
110            max_quarantined_devices: DEFAULT_MAX_QUARANTINED_DEVICES,
111        })
112    }
113
114    /// Sets the bounded number of previous logical devices retained after recovery.
115    ///
116    /// The default is 4 and the supported range is `1..=8`. Retention avoids a
117    /// native Linux driver crash observed when a healthy device is destroyed
118    /// immediately after surface migration. Once the limit is reached, another
119    /// recovery returns [`RendererInitError::RecoveryLimitReached`] before
120    /// requesting or installing a replacement device.
121    pub fn with_max_quarantined_devices(
122        mut self,
123        limit: usize,
124    ) -> Result<Self, RendererConfigurationError> {
125        if !(1..=MAX_QUARANTINED_DEVICES).contains(&limit) {
126            return Err(RendererConfigurationError::InvalidRecoveryLimit { limit });
127        }
128        self.max_quarantined_devices = limit;
129        Ok(self)
130    }
131
132    /// Returns presentation behavior for the surface.
133    pub fn present_mode(self) -> RendererPresentMode {
134        self.present_mode
135    }
136
137    /// Returns physical surface pixels per logical screen pixel.
138    pub fn scale_factor(self) -> f64 {
139        self.scale_factor
140    }
141
142    /// Returns the maximum previous logical devices retained after recovery.
143    pub fn max_quarantined_devices(self) -> usize {
144        self.max_quarantined_devices
145    }
146}
147
148impl Default for WgpuRendererOptions {
149    fn default() -> Self {
150        Self {
151            present_mode: RendererPresentMode::Vsync,
152            scale_factor: 1.0,
153            max_quarantined_devices: DEFAULT_MAX_QUARANTINED_DEVICES,
154        }
155    }
156}
157
158pub(super) fn create_multisample_target(
159    device: &wgpu::Device,
160    config: &wgpu::SurfaceConfiguration,
161    sample_count: u32,
162) -> Option<MultisampleTarget> {
163    if sample_count <= 1 {
164        return None;
165    }
166
167    let texture = device.create_texture(&wgpu::TextureDescriptor {
168        label: Some("sim-engine multisample target"),
169        size: wgpu::Extent3d {
170            width: config.width,
171            height: config.height,
172            depth_or_array_layers: 1,
173        },
174        mip_level_count: 1,
175        sample_count,
176        dimension: wgpu::TextureDimension::D2,
177        format: config.format,
178        usage: wgpu::TextureUsages::RENDER_ATTACHMENT,
179        view_formats: &[],
180    });
181    let view = texture.create_view(&wgpu::TextureViewDescriptor::default());
182
183    Some(MultisampleTarget {
184        _texture: texture,
185        view,
186    })
187}
188
189pub(super) fn validate_scale_factor(scale_factor: f64) -> Result<(), RendererConfigurationError> {
190    let scale_factor_f32 = scale_factor as f32;
191    if scale_factor_f32.is_finite()
192        && crate::units::stable_physical_per_logical(scale_factor)
193        && crate::units::stable_physical_per_logical(f64::from(scale_factor_f32))
194    {
195        Ok(())
196    } else {
197        Err(RendererConfigurationError::InvalidScaleFactor { scale_factor })
198    }
199}
200
201pub(super) fn validate_surface_dimensions(
202    width: u32,
203    height: u32,
204    limit: u32,
205) -> Result<(), RendererConfigurationError> {
206    if width <= limit && height <= limit {
207        Ok(())
208    } else {
209        Err(RendererConfigurationError::SurfaceDimensionsTooLarge {
210            width,
211            height,
212            limit,
213        })
214    }
215}
216
217pub(super) fn physical_to_logical_screen(
218    position: PhysicalScreenPosition,
219    scale_factor: f32,
220) -> Result<LogicalScreenPosition, RendererCoordinateError> {
221    let logical = position.to_vec2() / scale_factor;
222    (position.is_finite() && logical.is_finite())
223        .then_some(LogicalScreenPosition::from_vec2(logical))
224        .ok_or(RendererCoordinateError::NonFiniteConversion)
225}
226
227pub(super) fn logical_to_physical_screen(
228    position: LogicalScreenPosition,
229    scale_factor: f32,
230) -> Result<PhysicalScreenPosition, RendererCoordinateError> {
231    let physical = position.to_vec2() * scale_factor;
232    (position.is_finite() && physical.is_finite())
233        .then_some(PhysicalScreenPosition::from_vec2(physical))
234        .ok_or(RendererCoordinateError::NonFiniteConversion)
235}
236
237impl WgpuRenderer {
238    /// Requests a replacement logical device for the existing surface and
239    /// recreates all renderer-owned transient pipelines and buffers.
240    ///
241    /// Every external retained GPU resource deliberately keeps the previous
242    /// renderer identity and is rejected until restored after this succeeds.
243    /// Restore prepared and prepared-screen scenes, dynamic meshes, particle
244    /// fields, scalar fields, 2D targets, and trails with their matching
245    /// `restore_*` methods. Restore images before dependent image batches;
246    /// glyph atlases before dependent glyph runs; and retained 3D meshes/scenes
247    /// before their empty 3D target. Both 2D/3D targets and trails restore
248    /// without prior pixels and must be redrawn. See each resource's
249    /// `WgpuRenderer::restore_*` method for its exact retained-state contract.
250    ///
251    /// Replaced logical devices enter a bounded quarantine until this renderer
252    /// is dropped. Some native swapchain drivers crash if a healthy previous
253    /// device is destroyed immediately after the surface migrates to its
254    /// replacement. Device recovery should therefore remain exceptional rather
255    /// than a normal quality switch. Query
256    /// [`WgpuRenderer::remaining_device_recoveries`] before attempting it.
257    pub async fn recover_device_and_surface(&mut self) -> Result<(), RendererInitError> {
258        if !recovery_quarantine_has_capacity(
259            self.retired_devices.len(),
260            self.max_quarantined_devices,
261        ) {
262            return Err(RendererInitError::RecoveryLimitReached {
263                limit: self.max_quarantined_devices,
264            });
265        }
266        self.retired_devices.try_reserve(1).map_err(|_| {
267            RendererInitError::RecoveryAllocationFailed {
268                requested_bytes: std::mem::size_of::<RetiredDevice>(),
269            }
270        })?;
271        let _ = self.device.poll(wgpu::PollType::wait_indefinitely());
272        let adapter = self
273            ._instance
274            .request_adapter(&wgpu::RequestAdapterOptions {
275                power_preference: wgpu::PowerPreference::HighPerformance,
276                force_fallback_adapter: false,
277                compatible_surface: Some(&self.surface),
278                apply_limit_buckets: false,
279            })
280            .await
281            .map_err(RendererInitError::RequestAdapter)?;
282        let adapter_info = adapter.get_info();
283        let (device, queue) = adapter
284            .request_device(&wgpu::DeviceDescriptor {
285                label: Some("sim-engine recovered device"),
286                required_features: wgpu::Features::empty(),
287                required_limits: wgpu::Limits::default(),
288                experimental_features: wgpu::ExperimentalFeatures::disabled(),
289                memory_hints: wgpu::MemoryHints::Performance,
290                trace: wgpu::Trace::Off,
291            })
292            .await
293            .map_err(RendererInitError::RequestDevice)?;
294        let dimension_limit = device.limits().max_texture_dimension_2d;
295        if self.config.width > dimension_limit || self.config.height > dimension_limit {
296            return Err(RendererInitError::SurfaceDimensionsTooLarge {
297                width: self.config.width,
298                height: self.config.height,
299                limit: dimension_limit,
300            });
301        }
302        let mut config = self
303            .surface
304            .get_default_config(&adapter, self.config.width, self.config.height)
305            .ok_or(RendererInitError::NoSurfaceConfig)?;
306        let surface_capabilities = self.surface.get_capabilities(&adapter);
307        let surface_present_mode = select_surface_present_mode(
308            self.requested_present_mode,
309            &surface_capabilities.present_modes,
310        );
311        config.present_mode = surface_present_mode.to_wgpu();
312        let sample_count = preferred_sample_count(&adapter, config.format);
313        let PipelineResources {
314            pipeline,
315            target_pipeline,
316            dynamic_pipeline,
317            particle_pipeline,
318            target_particle_pipeline,
319            heatmap_pipeline,
320            target_heatmap_pipeline,
321            composition_pipelines,
322            target_composition_pipelines,
323            camera_uniform_buffer,
324            camera_bind_group,
325            camera_bind_group_layout,
326            heatmap_uniform_buffer,
327            heatmap_bind_group_layout,
328        } = create_pipeline(&device, config.format, sample_count);
329        let vertex_buffer = Arc::new(create_vertex_buffer(&device, INITIAL_VERTEX_CAPACITY));
330        let particle_unit_buffer = create_submitted_particle_unit_buffer(&device, &queue);
331        let multisample_target = create_multisample_target(&device, &config, sample_count);
332        let image_renderer = ImageRenderer::new(&device, config.format, sample_count);
333        let mesh3d_renderer = Mesh3dRenderer::new(&device, config.format);
334        self.surface.configure(&device, &config);
335
336        self.renderer_identity = Arc::new(());
337        let retired_device = RetiredDevice {
338            _adapter: std::mem::replace(&mut self._adapter, adapter),
339            _device: std::mem::replace(&mut self.device, device),
340            _queue: std::mem::replace(&mut self.queue, queue),
341        };
342        self.retired_devices.push(retired_device);
343        self.adapter_info = adapter_info;
344        self.config = config;
345        self.surface_present_mode = surface_present_mode;
346        self.pipeline = pipeline;
347        self.target_pipeline = target_pipeline;
348        self.dynamic_pipeline = dynamic_pipeline;
349        self.particle_pipeline = particle_pipeline;
350        self.target_particle_pipeline = target_particle_pipeline;
351        self.heatmap_pipeline = heatmap_pipeline;
352        self.target_heatmap_pipeline = target_heatmap_pipeline;
353        self.composition_pipelines = composition_pipelines;
354        self.target_composition_pipelines = target_composition_pipelines;
355        self.image_renderer = image_renderer;
356        self.mesh3d_renderer = mesh3d_renderer;
357        self.camera_uniform_buffer = camera_uniform_buffer;
358        self.camera_bind_group = camera_bind_group;
359        self.camera_bind_group_layout = camera_bind_group_layout;
360        self.heatmap_uniform_buffer = heatmap_uniform_buffer;
361        self.heatmap_bind_group_layout = heatmap_bind_group_layout;
362        self.color_map_cache = None;
363        self.vertex_buffer = vertex_buffer;
364        self.particle_unit_buffer = particle_unit_buffer;
365        self.vertex_capacity = INITIAL_VERTEX_CAPACITY;
366        self.multisample_target = multisample_target;
367        self.sample_count = sample_count;
368        self.vertices.clear();
369        self.draw_batches.clear();
370        Ok(())
371    }
372}
373
374pub(super) fn recovery_quarantine_has_capacity(retired: usize, limit: usize) -> bool {
375    retired < limit
376}