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    gpu_timing: bool,
94}
95
96impl WgpuRendererOptions {
97    /// Builds options from presentation behavior and display scale.
98    ///
99    /// `scale_factor` is physical surface pixels per logical screen pixel. It
100    /// must be finite, representable as `f32`, and bounded so every non-empty
101    /// `u32` surface keeps its logical dimensions and reciprocal clip scale in
102    /// the normal finite `f32` range.
103    pub fn new(
104        present_mode: RendererPresentMode,
105        scale_factor: f64,
106    ) -> Result<Self, RendererConfigurationError> {
107        validate_scale_factor(scale_factor)?;
108        Ok(Self {
109            present_mode,
110            scale_factor,
111            max_quarantined_devices: DEFAULT_MAX_QUARANTINED_DEVICES,
112            gpu_timing: false,
113        })
114    }
115
116    /// Sets the bounded number of previous logical devices retained after recovery.
117    ///
118    /// The default is 4 and the supported range is `1..=8`. Retention avoids a
119    /// native Linux driver crash observed when a healthy device is destroyed
120    /// immediately after surface migration. Once the limit is reached, another
121    /// recovery returns [`RendererInitError::RecoveryLimitReached`] before
122    /// requesting or installing a replacement device.
123    pub fn with_max_quarantined_devices(
124        mut self,
125        limit: usize,
126    ) -> Result<Self, RendererConfigurationError> {
127        if !(1..=MAX_QUARANTINED_DEVICES).contains(&limit) {
128            return Err(RendererConfigurationError::InvalidRecoveryLimit { limit });
129        }
130        self.max_quarantined_devices = limit;
131        Ok(self)
132    }
133
134    /// Returns presentation behavior for the surface.
135    pub fn present_mode(self) -> RendererPresentMode {
136        self.present_mode
137    }
138
139    /// Returns physical surface pixels per logical screen pixel.
140    pub fn scale_factor(self) -> f64 {
141        self.scale_factor
142    }
143
144    /// Returns the maximum previous logical devices retained after recovery.
145    pub fn max_quarantined_devices(self) -> usize {
146        self.max_quarantined_devices
147    }
148
149    /// Requests bounded, asynchronous GPU timestamp diagnostics when supported.
150    ///
151    /// Disabled by default, with no query/readback resource cost. Unsupported
152    /// adapters still initialize successfully and report `Unavailable` through
153    /// [`WgpuRenderer::gpu_timing_statistics`]. The measured paths are retained
154    /// 3D target rendering and [`FrameComposer`]; CPU submissions and presentation
155    /// waits are never reported as GPU time. Recovery preserves this preference.
156    pub const fn with_gpu_timing(mut self, enabled: bool) -> Self {
157        self.gpu_timing = enabled;
158        self
159    }
160
161    /// Returns whether optional GPU timestamp diagnostics were requested.
162    pub const fn gpu_timing(self) -> bool {
163        self.gpu_timing
164    }
165}
166
167impl Default for WgpuRendererOptions {
168    fn default() -> Self {
169        Self {
170            present_mode: RendererPresentMode::Vsync,
171            scale_factor: 1.0,
172            max_quarantined_devices: DEFAULT_MAX_QUARANTINED_DEVICES,
173            gpu_timing: false,
174        }
175    }
176}
177
178pub(super) fn create_multisample_target(
179    device: &wgpu::Device,
180    config: &wgpu::SurfaceConfiguration,
181    sample_count: u32,
182) -> Option<MultisampleTarget> {
183    if sample_count <= 1 {
184        return None;
185    }
186
187    let texture = device.create_texture(&wgpu::TextureDescriptor {
188        label: Some("sim-engine multisample target"),
189        size: wgpu::Extent3d {
190            width: config.width,
191            height: config.height,
192            depth_or_array_layers: 1,
193        },
194        mip_level_count: 1,
195        sample_count,
196        dimension: wgpu::TextureDimension::D2,
197        format: config.format,
198        usage: wgpu::TextureUsages::RENDER_ATTACHMENT,
199        view_formats: &[],
200    });
201    let view = texture.create_view(&wgpu::TextureViewDescriptor::default());
202
203    Some(MultisampleTarget {
204        _texture: texture,
205        view,
206    })
207}
208
209pub(super) fn validate_scale_factor(scale_factor: f64) -> Result<(), RendererConfigurationError> {
210    let scale_factor_f32 = scale_factor as f32;
211    if scale_factor_f32.is_finite()
212        && crate::units::stable_physical_per_logical(scale_factor)
213        && crate::units::stable_physical_per_logical(f64::from(scale_factor_f32))
214    {
215        Ok(())
216    } else {
217        Err(RendererConfigurationError::InvalidScaleFactor { scale_factor })
218    }
219}
220
221pub(super) fn validate_surface_dimensions(
222    width: u32,
223    height: u32,
224    limit: u32,
225) -> Result<(), RendererConfigurationError> {
226    if width <= limit && height <= limit {
227        Ok(())
228    } else {
229        Err(RendererConfigurationError::SurfaceDimensionsTooLarge {
230            width,
231            height,
232            limit,
233        })
234    }
235}
236
237pub(super) fn physical_to_logical_screen(
238    position: PhysicalScreenPosition,
239    scale_factor: f32,
240) -> Result<LogicalScreenPosition, RendererCoordinateError> {
241    let logical = position.to_vec2() / scale_factor;
242    (position.is_finite() && logical.is_finite())
243        .then_some(LogicalScreenPosition::from_vec2(logical))
244        .ok_or(RendererCoordinateError::NonFiniteConversion)
245}
246
247pub(super) fn logical_to_physical_screen(
248    position: LogicalScreenPosition,
249    scale_factor: f32,
250) -> Result<PhysicalScreenPosition, RendererCoordinateError> {
251    let physical = position.to_vec2() * scale_factor;
252    (position.is_finite() && physical.is_finite())
253        .then_some(PhysicalScreenPosition::from_vec2(physical))
254        .ok_or(RendererCoordinateError::NonFiniteConversion)
255}
256
257impl WgpuRenderer {
258    /// Requests a replacement logical device for the existing surface and
259    /// recreates all renderer-owned transient pipelines and buffers.
260    ///
261    /// Every external retained GPU resource deliberately keeps the previous
262    /// renderer identity and is rejected until restored after this succeeds.
263    /// Restore prepared and prepared-screen scenes, dynamic meshes, particle
264    /// fields, scalar fields, 2D targets, and trails with their matching
265    /// `restore_*` methods. Restore images before dependent image batches;
266    /// glyph atlases before dependent glyph runs; and retained 3D meshes/scenes
267    /// before their empty 3D target. Both 2D/3D targets and trails restore
268    /// without prior pixels and must be redrawn. See each resource's
269    /// `WgpuRenderer::restore_*` method for its exact retained-state contract.
270    ///
271    /// Replaced logical devices enter a bounded quarantine until this renderer
272    /// is dropped. Some native swapchain drivers crash if a healthy previous
273    /// device is destroyed immediately after the surface migrates to its
274    /// replacement. Device recovery should therefore remain exceptional rather
275    /// than a normal quality switch. Query
276    /// [`WgpuRenderer::remaining_device_recoveries`] before attempting it.
277    pub async fn recover_device_and_surface(&mut self) -> Result<(), RendererInitError> {
278        if !recovery_quarantine_has_capacity(
279            self.retired_devices.len(),
280            self.max_quarantined_devices,
281        ) {
282            return Err(RendererInitError::RecoveryLimitReached {
283                limit: self.max_quarantined_devices,
284            });
285        }
286        self.retired_devices.try_reserve(1).map_err(|_| {
287            RendererInitError::RecoveryAllocationFailed {
288                requested_bytes: std::mem::size_of::<RetiredDevice>(),
289            }
290        })?;
291        let _ = self.device.poll(wgpu::PollType::wait_indefinitely());
292        let adapter = self
293            ._instance
294            .request_adapter(&wgpu::RequestAdapterOptions {
295                power_preference: wgpu::PowerPreference::HighPerformance,
296                force_fallback_adapter: false,
297                compatible_surface: Some(&self.surface),
298                apply_limit_buckets: false,
299            })
300            .await
301            .map_err(RendererInitError::RequestAdapter)?;
302        let adapter_info = adapter.get_info();
303        let (device, queue) = adapter
304            .request_device(&wgpu::DeviceDescriptor {
305                label: Some("sim-engine recovered device"),
306                required_features: gpu_timing::requested_features(
307                    adapter.features(),
308                    self.gpu_timing_requested,
309                ),
310                required_limits: wgpu::Limits::default(),
311                experimental_features: wgpu::ExperimentalFeatures::disabled(),
312                memory_hints: wgpu::MemoryHints::Performance,
313                trace: wgpu::Trace::Off,
314            })
315            .await
316            .map_err(RendererInitError::RequestDevice)?;
317        let dimension_limit = device.limits().max_texture_dimension_2d;
318        if self.config.width > dimension_limit || self.config.height > dimension_limit {
319            return Err(RendererInitError::SurfaceDimensionsTooLarge {
320                width: self.config.width,
321                height: self.config.height,
322                limit: dimension_limit,
323            });
324        }
325        let mut config = self
326            .surface
327            .get_default_config(&adapter, self.config.width, self.config.height)
328            .ok_or(RendererInitError::NoSurfaceConfig)?;
329        let surface_capabilities = self.surface.get_capabilities(&adapter);
330        let surface_present_mode = select_surface_present_mode(
331            self.requested_present_mode,
332            &surface_capabilities.present_modes,
333        );
334        config.present_mode = surface_present_mode.to_wgpu();
335        let sample_count = preferred_sample_count(&adapter, config.format);
336        let PipelineResources {
337            pipeline,
338            target_pipeline,
339            dynamic_pipeline,
340            particle_pipeline,
341            target_particle_pipeline,
342            heatmap_pipeline,
343            target_heatmap_pipeline,
344            composition_pipelines,
345            target_composition_pipelines,
346            camera_uniform_buffer,
347            camera_bind_group,
348            camera_bind_group_layout,
349            heatmap_uniform_buffer,
350            heatmap_bind_group_layout,
351        } = create_pipeline(&device, config.format, sample_count);
352        let vertex_buffer = Arc::new(create_vertex_buffer(&device, INITIAL_VERTEX_CAPACITY));
353        let particle_unit_buffer = create_submitted_particle_unit_buffer(&device, &queue);
354        let multisample_target = create_multisample_target(&device, &config, sample_count);
355        let image_renderer = ImageRenderer::new(&device, config.format, sample_count);
356        let mesh3d_renderer = Mesh3dRenderer::new(&device, config.format);
357        let gpu_timing =
358            gpu_timing::GpuTimingCollector::new(&device, &queue, self.gpu_timing_requested);
359        self.surface.configure(&device, &config);
360
361        self.renderer_identity = Arc::new(());
362        let retired_device = RetiredDevice {
363            _adapter: std::mem::replace(&mut self._adapter, adapter),
364            _device: std::mem::replace(&mut self.device, device),
365            _queue: std::mem::replace(&mut self.queue, queue),
366        };
367        self.retired_devices.push(retired_device);
368        self.adapter_info = adapter_info;
369        self.config = config;
370        self.surface_present_mode = surface_present_mode;
371        self.pipeline = pipeline;
372        self.target_pipeline = target_pipeline;
373        self.dynamic_pipeline = dynamic_pipeline;
374        self.particle_pipeline = particle_pipeline;
375        self.target_particle_pipeline = target_particle_pipeline;
376        self.heatmap_pipeline = heatmap_pipeline;
377        self.target_heatmap_pipeline = target_heatmap_pipeline;
378        self.composition_pipelines = composition_pipelines;
379        self.target_composition_pipelines = target_composition_pipelines;
380        self.image_renderer = image_renderer;
381        self.mesh3d_renderer = mesh3d_renderer;
382        self.gpu_timing = gpu_timing;
383        self.camera_uniform_buffer = camera_uniform_buffer;
384        self.camera_bind_group = camera_bind_group;
385        self.camera_bind_group_layout = camera_bind_group_layout;
386        self.heatmap_uniform_buffer = heatmap_uniform_buffer;
387        self.heatmap_bind_group_layout = heatmap_bind_group_layout;
388        self.color_map_cache = None;
389        self.frame_cache.clear();
390        self.vertex_buffer = vertex_buffer;
391        self.particle_unit_buffer = particle_unit_buffer;
392        self.vertex_capacity = INITIAL_VERTEX_CAPACITY;
393        self.multisample_target = multisample_target;
394        self.sample_count = sample_count;
395        self.vertices.clear();
396        self.draw_batches.clear();
397        Ok(())
398    }
399}
400
401pub(super) fn recovery_quarantine_has_capacity(retired: usize, limit: usize) -> bool {
402    retired < limit
403}