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, positive, representable as `f32`, and large enough that
100    /// every supported physical surface has finite logical dimensions.
101    pub fn new(
102        present_mode: RendererPresentMode,
103        scale_factor: f64,
104    ) -> Result<Self, RendererConfigurationError> {
105        validate_scale_factor(scale_factor)?;
106        Ok(Self {
107            present_mode,
108            scale_factor,
109            max_quarantined_devices: DEFAULT_MAX_QUARANTINED_DEVICES,
110        })
111    }
112
113    /// Sets the bounded number of previous logical devices retained after recovery.
114    ///
115    /// The default is 4 and the supported range is `1..=8`. Retention avoids a
116    /// native Linux driver crash observed when a healthy device is destroyed
117    /// immediately after surface migration. Once the limit is reached, another
118    /// recovery returns [`RendererInitError::RecoveryLimitReached`] before
119    /// requesting or installing a replacement device.
120    pub fn with_max_quarantined_devices(
121        mut self,
122        limit: usize,
123    ) -> Result<Self, RendererConfigurationError> {
124        if !(1..=MAX_QUARANTINED_DEVICES).contains(&limit) {
125            return Err(RendererConfigurationError::InvalidRecoveryLimit { limit });
126        }
127        self.max_quarantined_devices = limit;
128        Ok(self)
129    }
130
131    /// Returns presentation behavior for the surface.
132    pub fn present_mode(self) -> RendererPresentMode {
133        self.present_mode
134    }
135
136    /// Returns physical surface pixels per logical screen pixel.
137    pub fn scale_factor(self) -> f64 {
138        self.scale_factor
139    }
140
141    /// Returns the maximum previous logical devices retained after recovery.
142    pub fn max_quarantined_devices(self) -> usize {
143        self.max_quarantined_devices
144    }
145}
146
147impl Default for WgpuRendererOptions {
148    fn default() -> Self {
149        Self {
150            present_mode: RendererPresentMode::Vsync,
151            scale_factor: 1.0,
152            max_quarantined_devices: DEFAULT_MAX_QUARANTINED_DEVICES,
153        }
154    }
155}
156
157pub(super) fn create_multisample_target(
158    device: &wgpu::Device,
159    config: &wgpu::SurfaceConfiguration,
160    sample_count: u32,
161) -> Option<MultisampleTarget> {
162    if sample_count <= 1 {
163        return None;
164    }
165
166    let texture = device.create_texture(&wgpu::TextureDescriptor {
167        label: Some("sim-engine multisample target"),
168        size: wgpu::Extent3d {
169            width: config.width,
170            height: config.height,
171            depth_or_array_layers: 1,
172        },
173        mip_level_count: 1,
174        sample_count,
175        dimension: wgpu::TextureDimension::D2,
176        format: config.format,
177        usage: wgpu::TextureUsages::RENDER_ATTACHMENT,
178        view_formats: &[],
179    });
180    let view = texture.create_view(&wgpu::TextureViewDescriptor::default());
181
182    Some(MultisampleTarget {
183        _texture: texture,
184        view,
185    })
186}
187
188pub(super) fn validate_scale_factor(scale_factor: f64) -> Result<(), RendererConfigurationError> {
189    let scale_factor_f32 = scale_factor as f32;
190    let minimum_scale_factor = u32::MAX as f64 / f32::MAX as f64;
191    if scale_factor.is_finite()
192        && scale_factor_f32.is_finite()
193        && scale_factor >= minimum_scale_factor
194    {
195        Ok(())
196    } else {
197        Err(RendererConfigurationError::InvalidScaleFactor { scale_factor })
198    }
199}
200
201pub(super) fn physical_to_logical_screen(
202    position: PhysicalScreenPosition,
203    scale_factor: f32,
204) -> Result<LogicalScreenPosition, RendererCoordinateError> {
205    let logical = position.to_vec2() / scale_factor;
206    (position.is_finite() && logical.is_finite())
207        .then_some(LogicalScreenPosition::from_vec2(logical))
208        .ok_or(RendererCoordinateError::NonFiniteConversion)
209}
210
211pub(super) fn logical_to_physical_screen(
212    position: LogicalScreenPosition,
213    scale_factor: f32,
214) -> Result<PhysicalScreenPosition, RendererCoordinateError> {
215    let physical = position.to_vec2() * scale_factor;
216    (position.is_finite() && physical.is_finite())
217        .then_some(PhysicalScreenPosition::from_vec2(physical))
218        .ok_or(RendererCoordinateError::NonFiniteConversion)
219}
220
221impl WgpuRenderer {
222    /// Requests a replacement logical device for the existing surface and
223    /// recreates all renderer-owned transient pipelines and buffers.
224    ///
225    /// External prepared, dynamic, particle, scalar, target, and trail
226    /// resources deliberately retain the previous renderer identity. Recreate
227    /// them with the matching `restore_*` methods after this call succeeds.
228    /// Targets and trails restore empty and must be redrawn.
229    ///
230    /// Replaced logical devices enter a bounded quarantine until this renderer
231    /// is dropped. Some native swapchain drivers crash if a healthy previous
232    /// device is destroyed immediately after the surface migrates to its
233    /// replacement. Device recovery should therefore remain exceptional rather
234    /// than a normal quality switch. Query
235    /// [`WgpuRenderer::remaining_device_recoveries`] before attempting it.
236    pub async fn recover_device_and_surface(&mut self) -> Result<(), RendererInitError> {
237        if !recovery_quarantine_has_capacity(
238            self.retired_devices.len(),
239            self.max_quarantined_devices,
240        ) {
241            return Err(RendererInitError::RecoveryLimitReached {
242                limit: self.max_quarantined_devices,
243            });
244        }
245        let _ = self.device.poll(wgpu::PollType::wait_indefinitely());
246        let adapter = self
247            ._instance
248            .request_adapter(&wgpu::RequestAdapterOptions {
249                power_preference: wgpu::PowerPreference::HighPerformance,
250                force_fallback_adapter: false,
251                compatible_surface: Some(&self.surface),
252                apply_limit_buckets: false,
253            })
254            .await
255            .map_err(RendererInitError::RequestAdapter)?;
256        let (device, queue) = adapter
257            .request_device(&wgpu::DeviceDescriptor {
258                label: Some("sim-engine recovered device"),
259                required_features: wgpu::Features::empty(),
260                required_limits: wgpu::Limits::default(),
261                experimental_features: wgpu::ExperimentalFeatures::disabled(),
262                memory_hints: wgpu::MemoryHints::Performance,
263                trace: wgpu::Trace::Off,
264            })
265            .await
266            .map_err(RendererInitError::RequestDevice)?;
267        let mut config = self
268            .surface
269            .get_default_config(&adapter, self.config.width, self.config.height)
270            .ok_or(RendererInitError::NoSurfaceConfig)?;
271        let surface_capabilities = self.surface.get_capabilities(&adapter);
272        let surface_present_mode = select_surface_present_mode(
273            self.requested_present_mode,
274            &surface_capabilities.present_modes,
275        );
276        config.present_mode = surface_present_mode.to_wgpu();
277        let sample_count = preferred_sample_count(&adapter, config.format);
278        let (
279            pipeline,
280            dynamic_pipeline,
281            particle_pipeline,
282            target_particle_pipeline,
283            heatmap_pipeline,
284            target_heatmap_pipeline,
285            composition_pipelines,
286            target_composition_pipelines,
287            camera_uniform_buffer,
288            camera_bind_group,
289            heatmap_uniform_buffer,
290            heatmap_bind_group_layout,
291        ) = create_pipeline(&device, config.format, sample_count);
292        let vertex_buffer = Arc::new(create_vertex_buffer(&device, INITIAL_VERTEX_CAPACITY));
293        let particle_unit_buffer = create_particle_unit_buffer(&device, &queue);
294        let multisample_target = create_multisample_target(&device, &config, sample_count);
295        let mesh3d_renderer = Mesh3dRenderer::new(&device, config.format);
296        self.surface.configure(&device, &config);
297
298        self.renderer_identity = Arc::new(());
299        let retired_device = RetiredDevice {
300            _adapter: std::mem::replace(&mut self._adapter, adapter),
301            _device: std::mem::replace(&mut self.device, device),
302            _queue: std::mem::replace(&mut self.queue, queue),
303        };
304        self.retired_devices.push(retired_device);
305        self.config = config;
306        self.surface_present_mode = surface_present_mode;
307        self.pipeline = pipeline;
308        self.dynamic_pipeline = dynamic_pipeline;
309        self.particle_pipeline = particle_pipeline;
310        self.target_particle_pipeline = target_particle_pipeline;
311        self.heatmap_pipeline = heatmap_pipeline;
312        self.target_heatmap_pipeline = target_heatmap_pipeline;
313        self.composition_pipelines = composition_pipelines;
314        self.target_composition_pipelines = target_composition_pipelines;
315        self.mesh3d_renderer = mesh3d_renderer;
316        self.camera_uniform_buffer = camera_uniform_buffer;
317        self.camera_bind_group = camera_bind_group;
318        self.heatmap_uniform_buffer = heatmap_uniform_buffer;
319        self.heatmap_bind_group_layout = heatmap_bind_group_layout;
320        self.color_map_cache = None;
321        self.vertex_buffer = vertex_buffer;
322        self.particle_unit_buffer = particle_unit_buffer;
323        self.vertex_capacity = INITIAL_VERTEX_CAPACITY;
324        self.multisample_target = multisample_target;
325        self.sample_count = sample_count;
326        self.vertices.clear();
327        self.draw_batches.clear();
328        Ok(())
329    }
330}
331
332pub(super) fn recovery_quarantine_has_capacity(retired: usize, limit: usize) -> bool {
333    retired < limit
334}