Skip to main content

sim_engine/renderer/
visualization.rs

1use super::{
2    BlendMode, COLOR_MAP_LUT_SIZE, Camera2d, Color, ColorMap, CompositeUniform, Duration, Error,
3    HeatmapUniform, Instant, ParticleField2d, ParticleStatistics, RenderReport, RenderStatus,
4    RenderTarget2d, RendererFrameError, RendererFrameMetrics, RendererSurfaceStatus,
5    ScalarFieldSampling, ScalarFieldTexture, TessellationStats, WgpuRenderer, fmt,
6    premultiplied_wgpu_color, render_report, scalar_normalization_is_portable,
7    scalar_value_range_extent,
8};
9
10pub(super) struct CompositionPipelines {
11    pub(super) alpha: wgpu::RenderPipeline,
12    pub(super) additive: wgpu::RenderPipeline,
13    pub(super) replace: wgpu::RenderPipeline,
14    pub(super) uniform_buffer: wgpu::Buffer,
15    pub(super) secondary_uniform_buffer: wgpu::Buffer,
16    pub(super) bind_group_layout: wgpu::BindGroupLayout,
17}
18
19pub(super) struct CachedColorMap {
20    pub(super) lut: [u8; COLOR_MAP_LUT_SIZE as usize * 4],
21    pub(super) _texture: wgpu::Texture,
22    pub(super) view: wgpu::TextureView,
23}
24
25impl CompositionPipelines {
26    pub(super) fn pipeline(&self, blend_mode: BlendMode) -> &wgpu::RenderPipeline {
27        match blend_mode {
28            BlendMode::Alpha => &self.alpha,
29            BlendMode::Additive => &self.additive,
30            BlendMode::Replace => &self.replace,
31        }
32    }
33}
34
35pub(super) fn create_composition_pipeline(
36    device: &wgpu::Device,
37    shader: &wgpu::ShaderModule,
38    layout: &wgpu::PipelineLayout,
39    format: wgpu::TextureFormat,
40    sample_count: u32,
41    blend_mode: BlendMode,
42) -> wgpu::RenderPipeline {
43    let blend = match blend_mode {
44        BlendMode::Alpha => Some(wgpu::BlendState::ALPHA_BLENDING),
45        BlendMode::Additive => Some(wgpu::BlendState {
46            color: wgpu::BlendComponent {
47                src_factor: wgpu::BlendFactor::SrcAlpha,
48                dst_factor: wgpu::BlendFactor::One,
49                operation: wgpu::BlendOperation::Add,
50            },
51            alpha: wgpu::BlendComponent {
52                src_factor: wgpu::BlendFactor::One,
53                dst_factor: wgpu::BlendFactor::One,
54                operation: wgpu::BlendOperation::Add,
55            },
56        }),
57        BlendMode::Replace => Some(wgpu::BlendState {
58            // `composite_fs_main` produces straight RGB. Preserve the target
59            // representation by premultiplying on write while replacing every
60            // destination component.
61            color: wgpu::BlendComponent {
62                src_factor: wgpu::BlendFactor::SrcAlpha,
63                dst_factor: wgpu::BlendFactor::Zero,
64                operation: wgpu::BlendOperation::Add,
65            },
66            alpha: wgpu::BlendComponent {
67                src_factor: wgpu::BlendFactor::One,
68                dst_factor: wgpu::BlendFactor::Zero,
69                operation: wgpu::BlendOperation::Add,
70            },
71        }),
72    };
73    device.create_render_pipeline(&wgpu::RenderPipelineDescriptor {
74        label: Some("sim-engine composition pipeline"),
75        layout: Some(layout),
76        vertex: wgpu::VertexState {
77            module: shader,
78            entry_point: Some("composite_vs_main"),
79            compilation_options: wgpu::PipelineCompilationOptions::default(),
80            buffers: &[],
81        },
82        primitive: wgpu::PrimitiveState {
83            topology: wgpu::PrimitiveTopology::TriangleList,
84            ..Default::default()
85        },
86        depth_stencil: None,
87        multisample: wgpu::MultisampleState {
88            count: sample_count,
89            ..Default::default()
90        },
91        fragment: Some(wgpu::FragmentState {
92            module: shader,
93            entry_point: Some("composite_fs_main"),
94            compilation_options: wgpu::PipelineCompilationOptions::default(),
95            targets: &[Some(wgpu::ColorTargetState {
96                format,
97                blend,
98                write_mask: wgpu::ColorWrites::ALL,
99            })],
100        }),
101        multiview_mask: None,
102        cache: None,
103    })
104}
105
106/// Validated presentation settings for a scalar field with a particle overlay.
107///
108/// This is a rendering composition contract, not a simulation data model. The
109/// host remains responsible for producing both the scalar and particle state.
110#[derive(Debug, Clone, Copy, PartialEq)]
111pub struct LayeredVisualizationOptions {
112    minimum: f32,
113    maximum: f32,
114    value_extent: f32,
115    sampling: ScalarFieldSampling,
116    blend_mode: BlendMode,
117    opacity: f32,
118    target_background: Color,
119    surface_background: Color,
120}
121
122impl LayeredVisualizationOptions {
123    /// Creates settings with linear field sampling and opaque replacement.
124    pub fn new(
125        (minimum, maximum): (f32, f32),
126        target_background: Color,
127        surface_background: Color,
128    ) -> Result<Self, LayeredVisualizationError> {
129        let value_extent = scalar_value_range_extent(minimum, maximum)
130            .ok_or(LayeredVisualizationError::InvalidValueRange { minimum, maximum })?;
131        if !target_background.is_normalized() || !surface_background.is_normalized() {
132            return Err(LayeredVisualizationError::InvalidBackground);
133        }
134        Ok(Self {
135            minimum,
136            maximum,
137            value_extent,
138            sampling: ScalarFieldSampling::Linear,
139            blend_mode: BlendMode::Replace,
140            opacity: 1.0,
141            target_background,
142            surface_background,
143        })
144    }
145
146    /// Selects nearest or manual-linear scalar sampling.
147    pub fn with_sampling(mut self, sampling: ScalarFieldSampling) -> Self {
148        self.sampling = sampling;
149        self
150    }
151
152    /// Selects final target composition and validates its opacity.
153    pub fn with_composition(
154        mut self,
155        blend_mode: BlendMode,
156        opacity: f32,
157    ) -> Result<Self, LayeredVisualizationError> {
158        if !opacity.is_finite() || !(0.0..=1.0).contains(&opacity) {
159            return Err(LayeredVisualizationError::InvalidOpacity);
160        }
161        self.blend_mode = blend_mode;
162        self.opacity = opacity;
163        Ok(self)
164    }
165
166    /// Returns the finite scalar range represented by the heatmap.
167    pub fn value_range(self) -> (f32, f32) {
168        (self.minimum, self.maximum)
169    }
170
171    /// Returns the selected scalar sampling mode.
172    pub fn sampling(self) -> ScalarFieldSampling {
173        self.sampling
174    }
175
176    /// Returns final target-to-surface blending.
177    pub fn blend_mode(self) -> BlendMode {
178        self.blend_mode
179    }
180
181    /// Returns final target opacity.
182    pub fn opacity(self) -> f32 {
183        self.opacity
184    }
185}
186
187/// Status, timings, and encoded-work counters for one fused scalar/particle frame.
188#[derive(Debug, Clone, Copy, PartialEq, Eq)]
189pub struct LayeredVisualizationReport {
190    report: RenderReport,
191    render_pass_count: usize,
192    draw_call_count: usize,
193}
194
195impl LayeredVisualizationReport {
196    /// Returns whether the surface frame was drawn or temporarily skipped.
197    pub fn status(self) -> RenderStatus {
198        self.report.status()
199    }
200
201    /// Returns CPU-side renderer stage timings.
202    pub fn metrics(self) -> RendererFrameMetrics {
203        self.report.metrics()
204    }
205
206    /// Returns render passes actually encoded for this call.
207    pub const fn render_pass_count(self) -> usize {
208        self.render_pass_count
209    }
210
211    /// Returns draw calls actually encoded for this call.
212    pub const fn draw_call_count(self) -> usize {
213        self.draw_call_count
214    }
215}
216
217/// Failure while drawing a bounded scalar-field and particle composition.
218#[derive(Debug, Clone, Copy, PartialEq)]
219pub enum LayeredVisualizationError {
220    /// At least one resource belongs to another renderer/device.
221    RendererMismatch,
222    /// Scalar endpoints are invalid or their subtraction overflows `f32`.
223    InvalidValueRange {
224        /// Lower scalar endpoint supplied by the host.
225        minimum: f32,
226        /// Upper scalar endpoint supplied by the host.
227        maximum: f32,
228    },
229    /// A clear color is not normalized finite linear RGBA.
230    InvalidBackground,
231    /// Final composition opacity is outside the normalized finite range.
232    InvalidOpacity,
233    /// Camera arithmetic cannot produce finite particle geometry.
234    InvalidGeometryTransform,
235    /// Particle preparation, surface acquisition, or frame presentation failed.
236    Frame(RendererFrameError),
237}
238
239impl fmt::Display for LayeredVisualizationError {
240    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
241        match self {
242            Self::RendererMismatch => {
243                write!(formatter, "visual resources belong to another renderer")
244            }
245            Self::InvalidValueRange { minimum, maximum } => {
246                write!(formatter, "invalid scalar value range {minimum}..{maximum}")
247            }
248            Self::InvalidBackground => {
249                write!(
250                    formatter,
251                    "visualization colors must be normalized linear RGBA"
252                )
253            }
254            Self::InvalidOpacity => write!(formatter, "visualization opacity must be in 0..=1"),
255            Self::InvalidGeometryTransform => {
256                write!(formatter, "particle camera transform is invalid")
257            }
258            Self::Frame(error) => write!(formatter, "visualization frame failed: {error}"),
259        }
260    }
261}
262
263impl Error for LayeredVisualizationError {}
264
265impl WgpuRenderer {
266    /// Draws a heatmap, overlays a budgeted particle field, and presents the
267    /// target with one command encoder and one queue submission.
268    ///
269    /// This fused path avoids synchronously submitting each layer and leaves
270    /// substantially more CPU time for an expensive host simulation. The
271    /// target should have the presentation surface's aspect ratio; lowering
272    /// both dimensions proportionally bounds raster cost without changing the
273    /// logical camera contract.
274    pub fn render_layered_visualization(
275        &mut self,
276        target: &RenderTarget2d,
277        scalar: &ScalarFieldTexture,
278        color_map: &ColorMap,
279        particles: &mut ParticleField2d,
280        camera: &Camera2d,
281        options: LayeredVisualizationOptions,
282    ) -> Result<LayeredVisualizationReport, LayeredVisualizationError> {
283        let frame_started_at = Instant::now();
284        let preparation_started_at = Instant::now();
285        self.validate_render_target(target)
286            .map_err(|_| LayeredVisualizationError::RendererMismatch)?;
287        self.validate_scalar_field_texture(scalar)
288            .map_err(|_| LayeredVisualizationError::RendererMismatch)?;
289        self.validate_particle_field(particles)
290            .map_err(|_| LayeredVisualizationError::RendererMismatch)?;
291        if !scalar_normalization_is_portable(scalar, options.minimum, options.value_extent) {
292            return Err(LayeredVisualizationError::InvalidValueRange {
293                minimum: options.minimum,
294                maximum: options.maximum,
295            });
296        }
297
298        // Particle validation and all fallible host reservation complete before
299        // any heatmap cache or queue mutation.
300        let preparation = self
301            .prepare_particle_draw(particles, *camera)
302            .map_err(|error| match error {
303                RendererFrameError::InvalidGeometryTransform => {
304                    LayeredVisualizationError::InvalidGeometryTransform
305                }
306                other => LayeredVisualizationError::Frame(other),
307            })?;
308        let preparation_duration = preparation_started_at.elapsed();
309
310        let acquire_started_at = Instant::now();
311        let surface_texture = match self.surface.get_current_texture() {
312            wgpu::CurrentSurfaceTexture::Success(texture)
313            | wgpu::CurrentSurfaceTexture::Suboptimal(texture) => texture,
314            wgpu::CurrentSurfaceTexture::Timeout => {
315                particles.statistics = preparation.statistics;
316                return Ok(skipped_layered_report(layered_report(
317                    RenderStatus::Skipped(RendererSurfaceStatus::Timeout),
318                    preparation_duration,
319                    Duration::ZERO,
320                    Duration::ZERO,
321                    acquire_started_at.elapsed(),
322                    Duration::ZERO,
323                    frame_started_at.elapsed(),
324                )));
325            }
326            wgpu::CurrentSurfaceTexture::Occluded => {
327                particles.statistics = preparation.statistics;
328                return Ok(skipped_layered_report(layered_report(
329                    RenderStatus::Skipped(RendererSurfaceStatus::Occluded),
330                    preparation_duration,
331                    Duration::ZERO,
332                    Duration::ZERO,
333                    acquire_started_at.elapsed(),
334                    Duration::ZERO,
335                    frame_started_at.elapsed(),
336                )));
337            }
338            wgpu::CurrentSurfaceTexture::Outdated => {
339                let _ = self.resize(self.config.width, self.config.height);
340                particles.statistics = preparation.statistics;
341                return Ok(skipped_layered_report(layered_report(
342                    RenderStatus::Skipped(RendererSurfaceStatus::Outdated),
343                    preparation_duration,
344                    Duration::ZERO,
345                    Duration::ZERO,
346                    acquire_started_at.elapsed(),
347                    Duration::ZERO,
348                    frame_started_at.elapsed(),
349                )));
350            }
351            wgpu::CurrentSurfaceTexture::Lost => {
352                return Err(LayeredVisualizationError::Frame(
353                    RendererFrameError::Surface(RendererSurfaceStatus::Lost),
354                ));
355            }
356            wgpu::CurrentSurfaceTexture::Validation => {
357                return Err(LayeredVisualizationError::Frame(
358                    RendererFrameError::Surface(RendererSurfaceStatus::Validation),
359                ));
360            }
361        };
362        let surface_acquire = acquire_started_at.elapsed();
363        let (particle_upload, camera_uniform_upload) =
364            self.upload_particle_draw(particles, preparation);
365        let upload_started_at = Instant::now();
366        let color_map_view = self.color_map_view(color_map);
367        let scalar_view = scalar
368            .texture
369            .create_view(&wgpu::TextureViewDescriptor::default());
370        self.queue.write_buffer(
371            &self.heatmap_uniform_buffer,
372            0,
373            bytemuck::bytes_of(&HeatmapUniform::new(
374                options.minimum,
375                options.value_extent,
376                scalar.width(),
377                scalar.height(),
378                options.sampling,
379            )),
380        );
381        let heatmap_bind_group = self.device.create_bind_group(&wgpu::BindGroupDescriptor {
382            label: Some("sim-engine layered heatmap bind group"),
383            layout: &self.heatmap_bind_group_layout,
384            entries: &[
385                wgpu::BindGroupEntry {
386                    binding: 0,
387                    resource: wgpu::BindingResource::TextureView(&scalar_view),
388                },
389                wgpu::BindGroupEntry {
390                    binding: 1,
391                    resource: wgpu::BindingResource::TextureView(&color_map_view),
392                },
393                wgpu::BindGroupEntry {
394                    binding: 2,
395                    resource: self.heatmap_uniform_buffer.as_entire_binding(),
396                },
397            ],
398        });
399        self.queue.write_buffer(
400            &self.composition_pipelines.uniform_buffer,
401            0,
402            bytemuck::bytes_of(&CompositeUniform::full_surface(options.opacity)),
403        );
404        let composition_bind_group = self.device.create_bind_group(&wgpu::BindGroupDescriptor {
405            label: Some("sim-engine layered composition bind group"),
406            layout: &self.composition_pipelines.bind_group_layout,
407            entries: &[
408                wgpu::BindGroupEntry {
409                    binding: 0,
410                    resource: wgpu::BindingResource::TextureView(&target.view),
411                },
412                wgpu::BindGroupEntry {
413                    binding: 1,
414                    resource: self
415                        .composition_pipelines
416                        .uniform_buffer
417                        .as_entire_binding(),
418                },
419            ],
420        });
421        let upload = combined_layered_upload(particle_upload, upload_started_at.elapsed());
422        let encode_started_at = Instant::now();
423        let surface_view = surface_texture
424            .texture
425            .create_view(&wgpu::TextureViewDescriptor::default());
426        let (view, resolve_target) = match &self.multisample_target {
427            Some(multisample_target) => (&multisample_target.view, Some(&surface_view)),
428            None => (&surface_view, None),
429        };
430        let mut encoder = self
431            .device
432            .create_command_encoder(&wgpu::CommandEncoderDescriptor {
433                label: Some("sim-engine layered visualization encoder"),
434            });
435        let mut render_pass_count = 0_usize;
436        let mut draw_call_count = 0_usize;
437        {
438            let mut pass = encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
439                label: Some("sim-engine layered heatmap pass"),
440                color_attachments: &[Some(wgpu::RenderPassColorAttachment {
441                    view: &target.view,
442                    depth_slice: None,
443                    resolve_target: None,
444                    ops: wgpu::Operations {
445                        load: wgpu::LoadOp::Clear(premultiplied_wgpu_color(
446                            options.target_background,
447                        )),
448                        store: wgpu::StoreOp::Store,
449                    },
450                })],
451                depth_stencil_attachment: None,
452                timestamp_writes: None,
453                occlusion_query_set: None,
454                multiview_mask: None,
455            });
456            pass.set_pipeline(&self.target_heatmap_pipeline);
457            pass.set_bind_group(0, &heatmap_bind_group, &[]);
458            pass.draw(0..6, 0..1);
459            render_pass_count += 1;
460            draw_call_count += 1;
461        }
462        {
463            let mut pass = encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
464                label: Some("sim-engine layered particle pass"),
465                color_attachments: &[Some(wgpu::RenderPassColorAttachment {
466                    view: &target.view,
467                    depth_slice: None,
468                    resolve_target: None,
469                    ops: wgpu::Operations {
470                        load: wgpu::LoadOp::Load,
471                        store: wgpu::StoreOp::Store,
472                    },
473                })],
474                depth_stencil_attachment: None,
475                timestamp_writes: None,
476                occlusion_query_set: None,
477                multiview_mask: None,
478            });
479            if preparation.visible_count > 0 {
480                pass.set_pipeline(&self.target_particle_pipeline);
481                pass.set_bind_group(0, &self.camera_bind_group, &[]);
482                pass.set_vertex_buffer(0, self.particle_unit_buffer.slice(..));
483                pass.set_vertex_buffer(1, particles.instance_buffer.slice(..));
484                pass.draw(0..6, 0..preparation.visible_count as u32);
485                draw_call_count += 1;
486            }
487            render_pass_count += 1;
488        }
489        {
490            let mut pass = encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
491                label: Some("sim-engine layered composition pass"),
492                color_attachments: &[Some(wgpu::RenderPassColorAttachment {
493                    view,
494                    depth_slice: None,
495                    resolve_target,
496                    ops: wgpu::Operations {
497                        load: wgpu::LoadOp::Clear(options.surface_background.to_wgpu()),
498                        store: wgpu::StoreOp::Store,
499                    },
500                })],
501                depth_stencil_attachment: None,
502                timestamp_writes: None,
503                occlusion_query_set: None,
504                multiview_mask: None,
505            });
506            pass.set_pipeline(self.composition_pipelines.pipeline(options.blend_mode));
507            pass.set_bind_group(0, &composition_bind_group, &[]);
508            pass.draw(0..6, 0..1);
509            render_pass_count += 1;
510            draw_call_count += 1;
511        }
512        self.queue.submit([encoder.finish()]);
513        self.notify_before_present();
514        self.queue.present(surface_texture);
515        particles.statistics = ParticleStatistics {
516            rendered: preparation.visible_count,
517            ..preparation.statistics
518        };
519        Ok(LayeredVisualizationReport {
520            report: layered_report(
521                RenderStatus::Drawn,
522                preparation_duration,
523                upload,
524                camera_uniform_upload,
525                surface_acquire,
526                encode_started_at.elapsed(),
527                frame_started_at.elapsed(),
528            ),
529            render_pass_count,
530            draw_call_count,
531        })
532    }
533}
534
535fn skipped_layered_report(report: RenderReport) -> LayeredVisualizationReport {
536    LayeredVisualizationReport {
537        report,
538        render_pass_count: 0,
539        draw_call_count: 0,
540    }
541}
542
543fn layered_report(
544    status: RenderStatus,
545    preparation: Duration,
546    upload: Duration,
547    camera_uniform_upload: Duration,
548    surface_acquire: Duration,
549    encode_submit_present: Duration,
550    total_cpu: Duration,
551) -> RenderReport {
552    render_report(
553        status,
554        preparation,
555        upload,
556        camera_uniform_upload,
557        surface_acquire,
558        encode_submit_present,
559        total_cpu,
560        false,
561        true,
562        TessellationStats::default(),
563    )
564}
565
566fn combined_layered_upload(particle_upload: Duration, remaining_upload: Duration) -> Duration {
567    particle_upload.saturating_add(remaining_upload)
568}
569
570#[cfg(test)]
571mod tests {
572    use super::{combined_layered_upload, layered_report, skipped_layered_report};
573    use crate::{RenderStatus, RendererSurfaceStatus};
574    use std::time::Duration;
575
576    #[test]
577    fn layered_upload_includes_particle_and_composition_uploads() {
578        assert_eq!(
579            combined_layered_upload(Duration::from_millis(7), Duration::from_millis(3)),
580            Duration::from_millis(10)
581        );
582    }
583
584    #[test]
585    fn layered_reports_completed_preparation_for_drawn_and_skipped_frames() {
586        let preparation = Duration::from_millis(4);
587        let drawn = layered_report(
588            RenderStatus::Drawn,
589            preparation,
590            Duration::ZERO,
591            Duration::ZERO,
592            Duration::ZERO,
593            Duration::ZERO,
594            preparation,
595        );
596        let skipped = layered_report(
597            RenderStatus::Skipped(RendererSurfaceStatus::Timeout),
598            preparation,
599            Duration::ZERO,
600            Duration::ZERO,
601            Duration::from_millis(1),
602            Duration::ZERO,
603            Duration::from_millis(5),
604        );
605
606        assert_eq!(drawn.metrics().tessellation(), preparation);
607        assert_eq!(skipped.metrics().tessellation(), preparation);
608        let skipped = skipped_layered_report(skipped);
609        assert_eq!(skipped.render_pass_count(), 0);
610        assert_eq!(skipped.draw_call_count(), 0);
611    }
612}