Skip to main content

sim_engine/renderer/
config.rs

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