Skip to main content

sim_engine/renderer/
mod.rs

1use std::{
2    borrow::Cow,
3    error::Error,
4    fmt,
5    ops::Range,
6    sync::{Arc, Mutex},
7    time::{Duration, Instant},
8};
9
10use crate::{
11    Camera2d, Circle, Color, ColorMap, DrawCommand, Fill, Line, LogicalScreenPosition,
12    LogicalViewport, LogicalViewportRegion, ParticleInstance2d, PhysicalPerLogical,
13    PhysicalScreenPosition, Polyline, PrimitiveCommandCounts, Rect, ScalarField, Scene,
14    SceneBudgetResource, ScreenClipRect, ScreenScene, Shadow, ShapeStyle, Stroke, Vec2,
15    scene::{CIRCLE_SEGMENTS, CORNER_SEGMENTS, ROUND_CAP_SEGMENTS, TESSELLATED_VERTEX_BYTES},
16    screen::screen_camera,
17};
18use config::select_surface_present_mode;
19
20const INITIAL_VERTEX_CAPACITY: usize = 4096;
21const PREFERRED_SAMPLE_COUNT: u32 = 4;
22const COLOR_MAP_LUT_SIZE: u32 = 256;
23// Stay inside the WGSL division accuracy domain and reject denormal geometric
24// operands. This deliberately narrow transform envelope is shared by every GPU path.
25const MAX_PORTABLE_SHADER_VALUE: f32 = f32::from_bits((247_u32) << 23); // 2^120
26
27fn is_portable_shader_source(value: f32) -> bool {
28    value.is_finite()
29        && value.abs() <= MAX_PORTABLE_SHADER_VALUE
30        && (value == 0.0 || value.abs() >= f32::MIN_POSITIVE)
31}
32
33#[repr(C)]
34#[derive(Clone, Copy, Debug, bytemuck::Pod, bytemuck::Zeroable)]
35struct Vertex {
36    world_position: [f32; 2],
37    depth: f32,
38    world_offset: [f32; 2],
39    screen_offset: [f32; 2],
40    previous_direction: [f32; 2],
41    next_direction: [f32; 2],
42    normal_distance: f32,
43    tangent_distance: f32,
44    miter_limit: f32,
45    stroke_role: f32,
46    stroke_parameter: f32,
47    color: [f32; 4],
48}
49
50const _: () = assert!(std::mem::size_of::<Vertex>() == TESSELLATED_VERTEX_BYTES);
51
52#[repr(C)]
53#[derive(Clone, Copy, Debug, PartialEq, bytemuck::Pod, bytemuck::Zeroable)]
54struct DynamicGpu {
55    world_position: [f32; 2],
56    depth: f32,
57    color: [f32; 4],
58}
59
60#[repr(C)]
61#[derive(Clone, Copy, Debug, PartialEq, bytemuck::Pod, bytemuck::Zeroable)]
62struct CameraUniform {
63    camera_center: [f32; 4],
64    world_to_screen_x: [f32; 4],
65    world_to_screen_y: [f32; 4],
66    screen_to_clip: [f32; 4],
67}
68
69#[repr(C)]
70#[derive(Clone, Copy, Debug, bytemuck::Pod, bytemuck::Zeroable)]
71struct HeatmapUniform {
72    value_range: [f32; 4],
73    dimensions: [u32; 4],
74    destination: [f32; 4],
75}
76
77impl HeatmapUniform {
78    fn new(
79        minimum: f32,
80        value_extent: f32,
81        width: usize,
82        height: usize,
83        sampling: ScalarFieldSampling,
84    ) -> Self {
85        Self {
86            value_range: [minimum, value_extent, 0.0, 0.0],
87            dimensions: [width as u32, height as u32, sampling.shader_value(), 0],
88            destination: [1.0, 1.0, 0.0, 0.0],
89        }
90    }
91
92    fn in_region(mut self, region: LogicalViewportRegion, target: LogicalViewport) -> Option<Self> {
93        let destination = CompositeUniform::in_region(1.0, region, target)?.destination;
94        self.destination = destination;
95        Some(self)
96    }
97}
98
99#[repr(C)]
100#[derive(Clone, Copy, Debug, bytemuck::Pod, bytemuck::Zeroable)]
101struct CompositeUniform {
102    opacity: [f32; 4],
103    destination: [f32; 4],
104}
105
106impl CompositeUniform {
107    const fn full_surface(opacity: f32) -> Self {
108        Self {
109            opacity: [opacity, 0.0, 0.0, 0.0],
110            destination: [1.0, 1.0, 0.0, 0.0],
111        }
112    }
113
114    fn in_region(
115        opacity: f32,
116        region: LogicalViewportRegion,
117        target: LogicalViewport,
118    ) -> Option<Self> {
119        let origin = region.origin().to_vec2();
120        let viewport = region.viewport();
121        let scale_x = viewport.width() / target.width();
122        let scale_y = viewport.height() / target.height();
123        let offset_x = (origin.x.mul_add(2.0, viewport.width())) / target.width() - 1.0;
124        let offset_y = 1.0 - (origin.y.mul_add(2.0, viewport.height())) / target.height();
125        [scale_x, scale_y, offset_x, offset_y]
126            .into_iter()
127            .all(f32::is_finite)
128            .then_some(Self {
129                opacity: [opacity, 0.0, 0.0, 0.0],
130                destination: [scale_x, scale_y, offset_x, offset_y],
131            })
132    }
133}
134
135/// Scalar-field sampling mode used by heatmap rendering.
136#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
137pub enum ScalarFieldSampling {
138    /// Select one exact source texel for each output fragment.
139    #[default]
140    Nearest,
141    /// Bilinearly interpolate neighboring source texels in shader math.
142    Linear,
143}
144
145impl ScalarFieldSampling {
146    fn shader_value(self) -> u32 {
147        match self {
148            Self::Nearest => 0,
149            Self::Linear => 1,
150        }
151    }
152}
153
154/// How a render target is combined with the presentation surface.
155#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
156pub enum BlendMode {
157    /// Standard source-alpha compositing.
158    #[default]
159    Alpha,
160    /// Adds source light to the existing destination, useful for glow and trails.
161    Additive,
162    /// Replaces destination pixels with the source target.
163    Replace,
164}
165
166/// How a target-rendering pass initializes its destination pixels.
167#[derive(Debug, Clone, Copy, PartialEq)]
168pub enum RenderTargetLoad {
169    /// Preserve existing target pixels and blend new geometry over them.
170    Load,
171    /// Clear the target to normalized finite straight-linear RGBA before drawing.
172    Clear(Color),
173}
174
175#[derive(Debug, Clone, Copy)]
176struct GeometryExtents {
177    world_min: Vec2,
178    world_max: Vec2,
179    world_offset_min: Vec2,
180    world_offset_max: Vec2,
181    depth_min: f32,
182    depth_max: f32,
183    direction_min: Vec2,
184    direction_max: Vec2,
185    screen_offset_max_abs: Vec2,
186    normal_distance_max_abs: f32,
187    tangent_distance_max_abs: f32,
188    miter_limit_max: f32,
189    vertex_count: usize,
190    empty: bool,
191}
192
193#[derive(Debug, Clone, Copy, PartialEq, Eq)]
194struct ScissorRect {
195    x: u32,
196    y: u32,
197    width: u32,
198    height: u32,
199}
200
201#[derive(Debug, Clone, Copy)]
202struct ParticleDrawPreparation {
203    camera_uniform: CameraUniform,
204    visible_count: usize,
205    statistics: ParticleStatistics,
206}
207
208#[derive(Debug, Clone, PartialEq)]
209struct PreparedDrawBatch {
210    vertex_range: Range<u32>,
211    screen_clip: Option<ScreenClipRect>,
212}
213
214/// Outcome of converting accepted scene commands into GPU vertices.
215///
216/// A dropped command had finite source fields but produced no finite triangle
217/// vertices, usually because arithmetic overflowed while expanding geometry.
218/// Hosts can surface this separately from presentation success.
219#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
220pub struct TessellationStats {
221    command_count: usize,
222    rendered_command_count: usize,
223    dropped_command_count: usize,
224    command_counts: PrimitiveCommandCounts,
225    rendered_counts: PrimitiveCommandCounts,
226    dropped_counts: PrimitiveCommandCounts,
227    vertex_count: usize,
228    draw_batch_count: usize,
229    upload_bytes: usize,
230}
231
232impl TessellationStats {
233    /// Returns accepted source commands examined by the tessellator.
234    pub fn command_count(self) -> usize {
235        self.command_count
236    }
237
238    /// Returns source commands that emitted finite triangle vertices.
239    pub fn rendered_command_count(self) -> usize {
240        self.rendered_command_count
241    }
242
243    /// Returns source commands discarded because tessellation emitted no valid geometry.
244    pub fn dropped_command_count(self) -> usize {
245        self.dropped_command_count
246    }
247
248    /// Returns accepted commands examined, grouped by primitive category.
249    pub const fn command_counts(self) -> PrimitiveCommandCounts {
250        self.command_counts
251    }
252
253    /// Returns commands that emitted geometry, grouped by primitive category.
254    pub const fn rendered_counts(self) -> PrimitiveCommandCounts {
255        self.rendered_counts
256    }
257
258    /// Returns commands that emitted no geometry, grouped by primitive category.
259    pub const fn dropped_counts(self) -> PrimitiveCommandCounts {
260        self.dropped_counts
261    }
262
263    /// Returns finite triangle-list vertices generated for this scene.
264    pub fn vertex_count(self) -> usize {
265        self.vertex_count
266    }
267
268    /// Returns draw batches generated after compatible adjacent commands merge.
269    pub fn draw_batch_count(self) -> usize {
270        self.draw_batch_count
271    }
272
273    /// Returns bytes required to upload the generated vertices.
274    pub fn upload_bytes(self) -> usize {
275        self.upload_bytes
276    }
277}
278
279#[derive(Debug, Clone, Copy, PartialEq, Eq)]
280enum TessellationError {
281    AllocationFailed {
282        requested_bytes: usize,
283    },
284    CapacityTooLarge,
285    BudgetExceeded {
286        resource: SceneBudgetResource,
287        limit: usize,
288        actual: usize,
289    },
290}
291
292impl Vertex {
293    const ATTRIBUTES: [wgpu::VertexAttribute; 12] = wgpu::vertex_attr_array![
294        0 => Float32x2,
295        1 => Float32,
296        2 => Float32x2,
297        3 => Float32x2,
298        4 => Float32x2,
299        5 => Float32x2,
300        6 => Float32,
301        7 => Float32,
302        8 => Float32,
303        9 => Float32,
304        10 => Float32,
305        11 => Float32x4
306    ];
307
308    const LAYOUT: wgpu::VertexBufferLayout<'static> = wgpu::VertexBufferLayout {
309        array_stride: std::mem::size_of::<Self>() as wgpu::BufferAddress,
310        step_mode: wgpu::VertexStepMode::Vertex,
311        attributes: &Self::ATTRIBUTES,
312    };
313
314    fn is_finite(self) -> bool {
315        self.world_position.iter().all(|value| value.is_finite())
316            && self.depth.is_finite()
317            && self.world_offset.iter().all(|value| value.is_finite())
318            && self.screen_offset.iter().all(|value| value.is_finite())
319            && self
320                .previous_direction
321                .iter()
322                .all(|value| value.is_finite())
323            && self.next_direction.iter().all(|value| value.is_finite())
324            && self.normal_distance.is_finite()
325            && self.tangent_distance.is_finite()
326            && self.miter_limit.is_finite()
327            && self.stroke_role.is_finite()
328            && self.stroke_parameter.is_finite()
329            && self.color.iter().all(|value| value.is_finite())
330    }
331}
332
333impl DynamicGpu {
334    const ATTRIBUTES: [wgpu::VertexAttribute; 3] =
335        wgpu::vertex_attr_array![0 => Float32x2, 1 => Float32, 2 => Float32x4];
336
337    const LAYOUT: wgpu::VertexBufferLayout<'static> = wgpu::VertexBufferLayout {
338        array_stride: std::mem::size_of::<Self>() as wgpu::BufferAddress,
339        step_mode: wgpu::VertexStepMode::Vertex,
340        attributes: &Self::ATTRIBUTES,
341    };
342}
343
344#[repr(C)]
345#[derive(Clone, Copy, Debug, bytemuck::Pod, bytemuck::Zeroable)]
346struct ParticleUnitVertex {
347    direction: [f32; 2],
348}
349
350impl ParticleUnitVertex {
351    const ATTRIBUTES: [wgpu::VertexAttribute; 1] = wgpu::vertex_attr_array![0 => Float32x2];
352
353    const LAYOUT: wgpu::VertexBufferLayout<'static> = wgpu::VertexBufferLayout {
354        array_stride: std::mem::size_of::<Self>() as wgpu::BufferAddress,
355        step_mode: wgpu::VertexStepMode::Vertex,
356        attributes: &Self::ATTRIBUTES,
357    };
358}
359
360#[repr(C)]
361#[derive(Clone, Copy, Debug, bytemuck::Pod, bytemuck::Zeroable)]
362struct ParticleGpu {
363    world_position: [f32; 2],
364    depth: f32,
365    radius: f32,
366    color: [f32; 4],
367}
368
369impl ParticleGpu {
370    const ATTRIBUTES: [wgpu::VertexAttribute; 4] = wgpu::vertex_attr_array![
371        1 => Float32x2,
372        2 => Float32,
373        3 => Float32,
374        4 => Float32x4
375    ];
376
377    const LAYOUT: wgpu::VertexBufferLayout<'static> = wgpu::VertexBufferLayout {
378        array_stride: std::mem::size_of::<Self>() as wgpu::BufferAddress,
379        step_mode: wgpu::VertexStepMode::Instance,
380        attributes: &Self::ATTRIBUTES,
381    };
382
383    #[cfg(test)]
384    fn screen_position(self, camera: CameraUniform) -> Vec2 {
385        let relative_x = self.world_position[0] - camera.camera_center[0];
386        let relative_y = self.world_position[1] - camera.camera_center[1];
387        Vec2::new(
388            camera.world_to_screen_x[0] * relative_x
389                + camera.world_to_screen_x[1] * relative_y
390                + camera.world_to_screen_x[2] * self.depth
391                + camera.world_to_screen_x[3],
392            camera.world_to_screen_y[0] * relative_x
393                + camera.world_to_screen_y[1] * relative_y
394                + camera.world_to_screen_y[2] * self.depth
395                + camera.world_to_screen_y[3],
396        )
397    }
398
399    fn is_safe_for(self, camera: CameraUniform, viewport: LogicalViewport) -> bool {
400        self.validated_viewport_intersection(camera, viewport)
401            .is_some()
402    }
403
404    fn transform_sources_are_portable(self) -> bool {
405        self.world_position
406            .into_iter()
407            .chain([self.depth, self.radius])
408            .all(is_portable_shader_source)
409    }
410
411    fn projected_screen_bounds(self, camera: CameraUniform) -> Option<((f64, f64), (f64, f64))> {
412        let center = self.projected_screen_center_bounds(camera)?;
413        let radius = f64::from(self.radius);
414        Some((
415            shader_interval_sum_range([center.0, (-radius, radius)])?,
416            shader_interval_sum_range([center.1, (-radius, radius)])?,
417        ))
418    }
419
420    fn projected_screen_center_bounds(
421        self,
422        camera: CameraUniform,
423    ) -> Option<((f64, f64), (f64, f64))> {
424        let relative_x = shader_relative_component_bounds(
425            self.world_position[0],
426            self.world_position[0],
427            camera.camera_center[0],
428            0.0,
429            0.0,
430        )?;
431        let relative_y = shader_relative_component_bounds(
432            self.world_position[1],
433            self.world_position[1],
434            camera.camera_center[1],
435            0.0,
436            0.0,
437        )?;
438        let relative_minimum = [relative_x.0, relative_y.0];
439        let relative_maximum = [relative_x.1, relative_y.1];
440        Some((
441            shader_world_dot_range(
442                camera.world_to_screen_x,
443                relative_minimum,
444                relative_maximum,
445                self.depth,
446                self.depth,
447            )?,
448            shader_world_dot_range(
449                camera.world_to_screen_y,
450                relative_minimum,
451                relative_maximum,
452                self.depth,
453                self.depth,
454            )?,
455        ))
456    }
457
458    fn screen_bounds_intersect_viewport(
459        bounds: ((f64, f64), (f64, f64)),
460        viewport: LogicalViewport,
461    ) -> bool {
462        bounds.0.1 >= 0.0
463            && bounds.0.0 <= f64::from(viewport.width())
464            && bounds.1.1 >= 0.0
465            && bounds.1.0 <= f64::from(viewport.height())
466    }
467
468    fn validated_viewport_intersection(
469        self,
470        camera: CameraUniform,
471        viewport: LogicalViewport,
472    ) -> Option<bool> {
473        if !self.transform_sources_are_portable() || !camera.sources_are_portable() {
474            return None;
475        }
476        let center = self.projected_screen_center_bounds(camera)?;
477        if !self.clip_expansion_is_stable(center, camera) {
478            return None;
479        }
480        let radius = f64::from(self.radius);
481        let width = f64::from(viewport.width());
482        let height = f64::from(viewport.height());
483        let wholly_outside = center.0.1 + radius < 0.0
484            || center.0.0 - radius > width
485            || center.1.1 + radius < 0.0
486            || center.1.0 - radius > height;
487        if wholly_outside {
488            return Some(false);
489        }
490        // Every permitted dot/FMA association must leave a positive-area
491        // portion of the quad inside the viewport. If visibility itself can
492        // change between legal shader lowerings, fail closed before upload.
493        let always_intersects = center.0.0 + radius > 0.0
494            && center.0.1 - radius < width
495            && center.1.0 + radius > 0.0
496            && center.1.1 - radius < height;
497        always_intersects.then_some(true)
498    }
499
500    fn clip_expansion_is_stable(
501        self,
502        center: ((f64, f64), (f64, f64)),
503        camera: CameraUniform,
504    ) -> bool {
505        (0..2).all(|axis| {
506            let center_clip = rounded_f32_product_range(
507                center_axis(center, axis),
508                (
509                    f64::from(camera.screen_to_clip[axis]),
510                    f64::from(camera.screen_to_clip[axis]),
511                ),
512            )
513            .and_then(|scaled| {
514                rounded_f32_add_range(
515                    scaled,
516                    (
517                        f64::from(camera.screen_to_clip[axis + 2]),
518                        f64::from(camera.screen_to_clip[axis + 2]),
519                    ),
520                    false,
521                )
522            });
523            let extent = rounded_f32_product_range(
524                (f64::from(self.radius), f64::from(self.radius)),
525                (
526                    f64::from(camera.screen_to_clip[axis].abs()),
527                    f64::from(camera.screen_to_clip[axis].abs()),
528                ),
529            );
530            let (Some(center_clip), Some(extent)) = (center_clip, extent) else {
531                return false;
532            };
533            if extent.0 < f64::from(f32::MIN_POSITIVE) {
534                return false;
535            }
536            let Some(negative) = rounded_f32_add_range(center_clip, extent, true) else {
537                return false;
538            };
539            let Some(positive) = rounded_f32_add_range(center_clip, extent, false) else {
540                return false;
541            };
542            positive.0 - negative.1 >= f64::from(f32::MIN_POSITIVE)
543        })
544    }
545
546    fn intersects_viewport(self, camera: CameraUniform, viewport: LogicalViewport) -> bool {
547        // Validation precedes production culling. If this helper is called on
548        // an invalid instance, keep it conservatively instead of silently
549        // dropping geometry based on one CPU association of the shader dot.
550        self.projected_screen_bounds(camera)
551            .is_none_or(|bounds| Self::screen_bounds_intersect_viewport(bounds, viewport))
552    }
553}
554
555mod validation2d;
556#[cfg(test)]
557use validation2d::{
558    GEOMETRY_VALIDATION_CACHE_CAPACITY, dynamic_triangle_topology_is_portable,
559    geometry_vertex_centers_are_portable, logical_stroke_branches_are_stable,
560    shader_interval_sum_is_safe, shader_stroke_screen_bounds,
561    tessellated_triangle_topology_is_portable, tessellated_vertex_clip_ranges,
562};
563use validation2d::{
564    GeometryValidationCache, GeometryValidationSource, center_axis,
565    clip_triangle_has_stable_signed_area, clip_triangle_is_wholly_outside, geometry_is_safe_for,
566    geometry_is_safe_for_cached, geometry_sources_are_portable, interval_products_f64,
567    is_nonzero_subnormal, logical_stroke_vertex_screen_ranges, range_abs, range_dot, range_negate,
568    range_vector_add, range_vector_scale, rounded_f32_add_range, rounded_f32_product_range,
569    screen_ranges_to_clip, shader_clip_interval_is_safe, shader_direction_dot_range,
570    shader_interval_sum_range, shader_relative_component_bounds, shader_world_dot_range,
571    stroke_safe_unit_range, tessellated_vertex_base_screen_ranges, triangle_position_sources_equal,
572};
573
574mod outcomes;
575pub use outcomes::{
576    PreparedSceneError, PreparedSceneRenderError, RenderReport, RenderStatus,
577    RendererConfigurationError, RendererCoordinateError, RendererFrameError, RendererFrameMetrics,
578    RendererInitError, RendererSurfaceStatus,
579};
580
581/// Immutable scene geometry tessellated and uploaded once for repeated drawing.
582///
583/// Camera movement, zoom, rotation, projection tilt, viewport resizing, and DPI
584/// changes do not invalidate prepared geometry. Shape, style, gradient, layer,
585/// or clip changes require preparing a replacement. A prepared scene can only be
586/// rendered by the [`WgpuRenderer`] that created it. Use
587/// [`WgpuRenderer::restore_prepared_scene`] to recreate its GPU buffer for a
588/// replacement renderer after device loss. Portable shader arithmetic is proved
589/// once per exact camera/viewport uniform and retained in a bounded cache.
590pub struct PreparedScene {
591    renderer_identity: Arc<()>,
592    background: Color,
593    vertex_buffer: Arc<wgpu::Buffer>,
594    vertices: Arc<Vec<Vertex>>,
595    command_count: usize,
596    vertex_count: usize,
597    geometry_extents: GeometryExtents,
598    draw_batches: Vec<PreparedDrawBatch>,
599    tessellation: TessellationStats,
600    geometry_validation_cache: GeometryValidationCache,
601}
602
603/// Immutable prepared geometry whose positions are logical screen pixels.
604///
605/// This distinct wrapper prevents a world camera from being supplied to fixed
606/// UI geometry. It is created by [`WgpuRenderer::prepare_screen_scene`].
607pub struct PreparedScreenScene {
608    scene: PreparedScene,
609}
610
611impl PreparedScene {
612    /// Returns the number of accepted source scene commands.
613    pub fn command_count(&self) -> usize {
614        self.command_count
615    }
616
617    /// Returns the number of triangle-list vertices stored in the GPU buffer.
618    pub fn vertex_count(&self) -> usize {
619        self.vertex_count
620    }
621
622    /// Returns the number of clip-compatible draw batches.
623    pub fn draw_batch_count(&self) -> usize {
624        self.draw_batches.len()
625    }
626
627    /// Returns currently allocated CPU recovery bytes for vertices and draw batches.
628    pub fn recovery_memory_bytes(&self) -> usize {
629        self.vertices
630            .capacity()
631            .saturating_mul(std::mem::size_of::<Vertex>())
632            .saturating_add(
633                self.draw_batches
634                    .capacity()
635                    .saturating_mul(std::mem::size_of::<PreparedDrawBatch>()),
636            )
637    }
638
639    /// Returns command-level tessellation results captured during preparation.
640    pub fn tessellation_stats(&self) -> TessellationStats {
641        self.tessellation
642    }
643}
644
645impl PreparedScreenScene {
646    /// Returns the number of accepted source screen commands.
647    pub fn command_count(&self) -> usize {
648        self.scene.command_count()
649    }
650
651    /// Returns the retained triangle-list vertex count.
652    pub fn vertex_count(&self) -> usize {
653        self.scene.vertex_count()
654    }
655
656    /// Returns the number of clip-compatible draw batches.
657    pub fn draw_batch_count(&self) -> usize {
658        self.scene.draw_batch_count()
659    }
660
661    /// Returns retained CPU bytes available for device-loss recovery.
662    pub fn recovery_memory_bytes(&self) -> usize {
663        self.scene.recovery_memory_bytes()
664    }
665
666    /// Returns preparation-time tessellation statistics.
667    pub fn tessellation_stats(&self) -> TessellationStats {
668        self.scene.tessellation_stats()
669    }
670}
671
672/// `wgpu` backend that renders [`Scene`] commands into a presentation surface.
673///
674/// The renderer owns the GPU device, queue, surface, pipeline, and transient
675/// vertex buffer. Window creation stays outside the library so each application
676/// can choose its own windowing framework.
677pub struct WgpuRenderer {
678    renderer_identity: Arc<()>,
679    _instance: wgpu::Instance,
680    surface: wgpu::Surface<'static>,
681    _adapter: wgpu::Adapter,
682    adapter_info: wgpu::AdapterInfo,
683    device: wgpu::Device,
684    queue: wgpu::Queue,
685    config: wgpu::SurfaceConfiguration,
686    requested_present_mode: RendererPresentMode,
687    surface_present_mode: RendererSurfacePresentMode,
688    pre_present_notify: Option<Arc<dyn Fn() + Send + Sync>>,
689    scale_factor: f64,
690    pipeline: wgpu::RenderPipeline,
691    target_pipeline: wgpu::RenderPipeline,
692    dynamic_pipeline: wgpu::RenderPipeline,
693    particle_pipeline: wgpu::RenderPipeline,
694    target_particle_pipeline: wgpu::RenderPipeline,
695    heatmap_pipeline: wgpu::RenderPipeline,
696    target_heatmap_pipeline: wgpu::RenderPipeline,
697    composition_pipelines: CompositionPipelines,
698    target_composition_pipelines: CompositionPipelines,
699    image_renderer: ImageRenderer,
700    mesh3d_renderer: Mesh3dRenderer,
701    gpu_timing: gpu_timing::GpuTimingCollector,
702    gpu_timing_requested: bool,
703    camera_uniform_buffer: wgpu::Buffer,
704    camera_bind_group: wgpu::BindGroup,
705    camera_bind_group_layout: wgpu::BindGroupLayout,
706    heatmap_uniform_buffer: wgpu::Buffer,
707    heatmap_bind_group_layout: wgpu::BindGroupLayout,
708    color_map_cache: Option<CachedColorMap>,
709    frame_cache: frame::FrameCache,
710    vertex_buffer: Arc<wgpu::Buffer>,
711    particle_unit_buffer: wgpu::Buffer,
712    vertex_capacity: usize,
713    multisample_target: Option<MultisampleTarget>,
714    sample_count: u32,
715    vertices: Vec<Vertex>,
716    draw_batches: Vec<PreparedDrawBatch>,
717    retired_devices: Vec<RetiredDevice>,
718    max_quarantined_devices: usize,
719}
720
721struct RetiredDevice {
722    _adapter: wgpu::Adapter,
723    _device: wgpu::Device,
724    _queue: wgpu::Queue,
725}
726
727fn invoke_pre_present_notify(
728    present_mode: RendererSurfacePresentMode,
729    notify: Option<&(dyn Fn() + Send + Sync)>,
730) {
731    if present_mode.is_refresh_synchronized()
732        && let Some(notify) = notify
733    {
734        notify();
735    }
736}
737
738fn prepared_scene_belongs_to(renderer_identity: &Arc<()>, scene_identity: &Arc<()>) -> bool {
739    Arc::ptr_eq(renderer_identity, scene_identity)
740}
741
742fn render_target_allocation_bytes(
743    format: wgpu::TextureFormat,
744    width: u32,
745    height: u32,
746) -> Option<usize> {
747    let bytes_per_texel = u64::from(format.block_copy_size(None)?);
748    let byte_count = u64::from(width)
749        .checked_mul(u64::from(height))?
750        .checked_mul(bytes_per_texel)?;
751    usize::try_from(byte_count).ok()
752}
753
754fn dynamic_vertices_to_gpu(
755    vertices: &[DynamicVertex2d],
756) -> Result<Vec<DynamicGpu>, DynamicMeshError> {
757    validate_dynamic_vertices(vertices)?;
758    let requested_bytes = dynamic_mesh_bytes(vertices.len())?;
759    let mut converted = Vec::new();
760    converted
761        .try_reserve_exact(vertices.len())
762        .map_err(|_| DynamicMeshError::AllocationFailed { requested_bytes })?;
763    converted.extend(vertices.iter().copied().map(dynamic_vertex_to_gpu));
764    Ok(converted)
765}
766
767fn replace_dynamic_mesh_resources(
768    device: &wgpu::Device,
769    queue: &wgpu::Queue,
770    mesh: &mut DynamicMesh2d,
771    vertices: &[DynamicVertex2d],
772) -> Result<DynamicMeshUpdateReport, DynamicMeshError> {
773    let update_started_at = Instant::now();
774    validate_dynamic_vertices(vertices)?;
775    if let Some(budget) = mesh.budget {
776        validate_dynamic_mesh_budget(budget, vertices.len())?;
777    }
778    let reallocated = vertices.len() > mesh.vertex_capacity;
779    let replacement_capacity = if reallocated {
780        let capacity = dynamic_vertex_capacity(vertices.len())
781            .filter(|capacity| buffer_capacity_fits::<DynamicGpu>(device, *capacity))
782            .ok_or(DynamicMeshError::CapacityTooLarge)?;
783        Some(capacity)
784    } else {
785        None
786    };
787    let replacement_vertices = dynamic_vertices_to_gpu(vertices)?;
788    if let Some(budget) = mesh.budget {
789        validate_dynamic_retained_capacity(budget, &replacement_vertices)?;
790    }
791    let replacement = if let Some(capacity) = replacement_capacity {
792        let buffer = Arc::new(create_dynamic_vertex_buffer(device, capacity));
793        Some((buffer, capacity))
794    } else {
795        None
796    };
797    let upload_buffer = replacement
798        .as_ref()
799        .map_or(mesh.vertex_buffer.as_ref(), |(buffer, _)| buffer.as_ref());
800    if !replacement_vertices.is_empty() {
801        queue.write_buffer(
802            upload_buffer,
803            0,
804            bytemuck::cast_slice(&replacement_vertices),
805        );
806        submit_pending_uploads(queue);
807    }
808    if let Some((buffer, capacity)) = replacement {
809        mesh.vertex_buffer = buffer;
810        mesh.vertex_capacity = capacity;
811    }
812    mesh.geometry_extents = GeometryExtents::from_dynamic_vertices(&replacement_vertices);
813    mesh.vertices = replacement_vertices;
814    mesh.geometry_validation_cache.clear();
815    Ok(DynamicMeshUpdateReport {
816        vertex_count: mesh.vertices.len(),
817        upload: update_started_at.elapsed(),
818        reallocated,
819    })
820}
821
822fn dynamic_mesh_bytes(vertex_count: usize) -> Result<usize, DynamicMeshError> {
823    vertex_count
824        .checked_mul(std::mem::size_of::<DynamicGpu>())
825        .ok_or(DynamicMeshError::CapacityTooLarge)
826}
827
828fn validate_dynamic_mesh_budget(
829    budget: DynamicMeshBudget,
830    vertex_count: usize,
831) -> Result<(), DynamicMeshError> {
832    if u32::try_from(vertex_count).is_err() {
833        return Err(DynamicMeshError::CapacityTooLarge);
834    }
835    if vertex_count > budget.max_vertices {
836        return Err(DynamicMeshError::BudgetExceeded {
837            resource: DynamicMeshBudgetResource::Vertices,
838            limit: budget.max_vertices,
839            actual: vertex_count,
840        });
841    }
842    let bytes = dynamic_mesh_bytes(vertex_count)?;
843    if bytes > budget.max_retained_bytes {
844        return Err(DynamicMeshError::BudgetExceeded {
845            resource: DynamicMeshBudgetResource::RetainedBytes,
846            limit: budget.max_retained_bytes,
847            actual: bytes,
848        });
849    }
850    if bytes > budget.max_upload_bytes {
851        return Err(DynamicMeshError::BudgetExceeded {
852            resource: DynamicMeshBudgetResource::UploadBytes,
853            limit: budget.max_upload_bytes,
854            actual: bytes,
855        });
856    }
857    Ok(())
858}
859
860fn validate_dynamic_retained_capacity(
861    budget: DynamicMeshBudget,
862    vertices: &Vec<DynamicGpu>,
863) -> Result<(), DynamicMeshError> {
864    let actual = vertices
865        .capacity()
866        .checked_mul(std::mem::size_of::<DynamicGpu>())
867        .ok_or(DynamicMeshError::CapacityTooLarge)?;
868    if actual > budget.max_retained_bytes {
869        return Err(DynamicMeshError::BudgetExceeded {
870            resource: DynamicMeshBudgetResource::RetainedBytes,
871            limit: budget.max_retained_bytes,
872            actual,
873        });
874    }
875    Ok(())
876}
877
878fn validate_dynamic_vertices(vertices: &[DynamicVertex2d]) -> Result<(), DynamicMeshError> {
879    if u32::try_from(vertices.len()).is_err() {
880        return Err(DynamicMeshError::CapacityTooLarge);
881    }
882    if !vertices.len().is_multiple_of(3) {
883        return Err(DynamicMeshError::InvalidVertexCount);
884    }
885    if vertices.iter().any(|vertex| {
886        ![
887            vertex.world_position.x,
888            vertex.world_position.y,
889            vertex.depth,
890        ]
891        .into_iter()
892        .all(is_portable_shader_source)
893    }) {
894        return Err(DynamicMeshError::InvalidVertex);
895    }
896    // Private fields and the only public constructor make finiteness an
897    // invariant of DynamicVertex2d. Keep the assertion in development without
898    // rescanning an already-validated high-volume stream in release builds.
899    debug_assert!(vertices.iter().all(|vertex| {
900        vertex.world_position.is_finite()
901            && vertex.depth.is_finite()
902            && vertex.color.is_normalized()
903    }));
904    Ok(())
905}
906
907fn dynamic_vertex_to_gpu(vertex: DynamicVertex2d) -> DynamicGpu {
908    DynamicGpu {
909        world_position: [vertex.world_position.x, vertex.world_position.y],
910        depth: vertex.depth,
911        color: vertex.color.to_array(),
912    }
913}
914
915fn dynamic_vertex_capacity(vertex_count: usize) -> Option<usize> {
916    vertex_count.max(1).checked_next_power_of_two()
917}
918
919fn particle_instances_to_gpu(
920    instances: &[ParticleInstance2d],
921) -> Result<Vec<ParticleGpu>, ParticleFieldError> {
922    if u32::try_from(instances.len()).is_err() {
923        return Err(ParticleFieldError::CapacityTooLarge);
924    }
925    let requested_bytes = instances
926        .len()
927        .checked_mul(std::mem::size_of::<ParticleGpu>())
928        .ok_or(ParticleFieldError::CapacityTooLarge)?;
929    if instances.iter().copied().any(|instance| {
930        let world_position = instance.world_position();
931        let radius = instance.radius();
932        let color = instance.color();
933        let depth = instance.depth();
934        ![world_position.x, world_position.y, radius, depth]
935            .into_iter()
936            .all(is_portable_shader_source)
937            || radius <= 0.0
938            || !color.is_normalized()
939    }) {
940        return Err(ParticleFieldError::InvalidInstance);
941    }
942    let mut output = Vec::new();
943    output
944        .try_reserve_exact(instances.len())
945        .map_err(|_| ParticleFieldError::AllocationFailed { requested_bytes })?;
946    output.extend(instances.iter().copied().map(|instance| {
947        let world_position = instance.world_position();
948        ParticleGpu {
949            world_position: [world_position.x, world_position.y],
950            depth: instance.depth(),
951            radius: instance.radius(),
952            color: instance.color().to_array(),
953        }
954    }));
955    Ok(output)
956}
957
958fn particle_retained_bytes(instance_count: usize) -> Option<usize> {
959    instance_count.checked_mul(std::mem::size_of::<ParticleGpu>())
960}
961
962fn validate_particle_retained_count(
963    instance_count: usize,
964    budget: ParticleRenderBudget,
965) -> Result<(), ParticleFieldError> {
966    let staging_count = particle_staging_target(instance_count, budget);
967    let retained_count = instance_count
968        .checked_add(staging_count)
969        .ok_or(ParticleFieldError::CapacityTooLarge)?;
970    let actual =
971        particle_retained_bytes(retained_count).ok_or(ParticleFieldError::CapacityTooLarge)?;
972    if actual > budget.max_retained_bytes {
973        return Err(ParticleFieldError::RetainedBudgetExceeded {
974            limit: budget.max_retained_bytes,
975            actual,
976        });
977    }
978    Ok(())
979}
980
981fn validate_particle_retained_capacities(
982    instance_capacity: usize,
983    staging_capacity: usize,
984    budget: ParticleRenderBudget,
985) -> Result<(), ParticleFieldError> {
986    let retained_capacity = instance_capacity
987        .checked_add(staging_capacity)
988        .ok_or(ParticleFieldError::CapacityTooLarge)?;
989    let actual =
990        particle_retained_bytes(retained_capacity).ok_or(ParticleFieldError::CapacityTooLarge)?;
991    if actual > budget.max_retained_bytes {
992        return Err(ParticleFieldError::RetainedBudgetExceeded {
993            limit: budget.max_retained_bytes,
994            actual,
995        });
996    }
997    Ok(())
998}
999
1000fn compact_particle_instances(
1001    source: &[ParticleGpu],
1002    current_capacity: usize,
1003    staging_capacity: usize,
1004    budget: ParticleRenderBudget,
1005) -> Result<Option<Vec<ParticleGpu>>, ParticleFieldError> {
1006    validate_particle_retained_count(source.len(), budget)?;
1007    if validate_particle_retained_capacities(current_capacity, staging_capacity, budget).is_ok() {
1008        return Ok(None);
1009    }
1010    let requested_bytes =
1011        particle_retained_bytes(source.len()).ok_or(ParticleFieldError::CapacityTooLarge)?;
1012    let mut compact = Vec::new();
1013    compact
1014        .try_reserve_exact(source.len())
1015        .map_err(|_| ParticleFieldError::AllocationFailed { requested_bytes })?;
1016    compact.extend_from_slice(source);
1017    validate_particle_retained_capacities(compact.capacity(), staging_capacity, budget)?;
1018    Ok(Some(compact))
1019}
1020
1021fn particle_instance_capacity(instance_count: usize) -> Option<usize> {
1022    instance_count.max(1).checked_next_power_of_two()
1023}
1024
1025fn particle_budgeted_capacity(
1026    instance_count: usize,
1027    budget: ParticleRenderBudget,
1028) -> Option<usize> {
1029    let limit = budget.instance_limit();
1030    let required = instance_count.min(limit).max(1);
1031    particle_instance_capacity(required).map(|capacity| capacity.min(limit))
1032}
1033
1034fn allocate_particle_staging(
1035    instance_count: usize,
1036    budget: ParticleRenderBudget,
1037) -> Result<Vec<ParticleGpu>, ParticleFieldError> {
1038    let target = particle_staging_target(instance_count, budget);
1039    let requested_bytes = target
1040        .checked_mul(std::mem::size_of::<ParticleGpu>())
1041        .ok_or(ParticleFieldError::CapacityTooLarge)?;
1042    let mut staging = Vec::new();
1043    staging
1044        .try_reserve_exact(target)
1045        .map_err(|_| ParticleFieldError::AllocationFailed { requested_bytes })?;
1046    Ok(staging)
1047}
1048
1049fn particle_staging_target(instance_count: usize, budget: ParticleRenderBudget) -> usize {
1050    let visibility_checked = instance_count.min(budget.max_visibility_checks_per_frame);
1051    if visibility_checked < instance_count {
1052        visibility_checked
1053    } else {
1054        instance_count.min(budget.instance_limit())
1055    }
1056}
1057
1058fn buffer_allocation_bytes<T>(capacity: usize) -> Option<u64> {
1059    u64::try_from(capacity)
1060        .ok()?
1061        .checked_mul(std::mem::size_of::<T>() as u64)
1062}
1063
1064fn buffer_capacity_fits<T>(device: &wgpu::Device, capacity: usize) -> bool {
1065    buffer_allocation_bytes::<T>(capacity)
1066        .is_some_and(|bytes| bytes <= device.limits().max_buffer_size)
1067}
1068
1069fn scene_estimate_fits_prepared_device(scene: &Scene, device: &wgpu::Device) -> bool {
1070    buffer_capacity_fits::<Vertex>(
1071        device,
1072        scene.statistics().estimated_tessellated_vertices().max(1),
1073    )
1074}
1075
1076fn scene_estimate_fits_streaming_device(
1077    scene: &Scene,
1078    device: &wgpu::Device,
1079    prefix: usize,
1080    current_capacity: usize,
1081) -> bool {
1082    let Some(required) = prefix.checked_add(scene.statistics().estimated_tessellated_vertices())
1083    else {
1084        return false;
1085    };
1086    required <= current_capacity
1087        || dynamic_vertex_capacity(required)
1088            .is_some_and(|capacity| buffer_capacity_fits::<Vertex>(device, capacity))
1089}
1090
1091fn particle_update_range(
1092    first_instance: usize,
1093    replacement_count: usize,
1094    current_count: usize,
1095) -> Result<Range<usize>, ParticleFieldError> {
1096    let end = first_instance
1097        .checked_add(replacement_count)
1098        .ok_or(ParticleFieldError::UpdateRangeOutOfBounds)?;
1099    (end <= current_count)
1100        .then_some(first_instance..end)
1101        .ok_or(ParticleFieldError::UpdateRangeOutOfBounds)
1102}
1103
1104fn validate_particle_staging_capacity(
1105    instances: &Vec<ParticleGpu>,
1106    target_len: usize,
1107) -> Result<(), RendererFrameError> {
1108    let requested_bytes = target_len
1109        .checked_mul(std::mem::size_of::<ParticleGpu>())
1110        .ok_or(RendererFrameError::GeometryCapacityTooLarge)?;
1111    (instances.capacity() >= target_len)
1112        .then_some(())
1113        .ok_or(RendererFrameError::ParticleAllocationFailed { requested_bytes })
1114}
1115
1116#[cfg(test)]
1117fn visible_particle_instances(
1118    instances: &[ParticleGpu],
1119    camera: CameraUniform,
1120    viewport: LogicalViewport,
1121) -> Result<Vec<ParticleGpu>, RendererFrameError> {
1122    visible_particle_count(instances, camera, viewport)?;
1123    Ok(instances
1124        .iter()
1125        .copied()
1126        .filter(|instance| instance.intersects_viewport(camera, viewport))
1127        .collect())
1128}
1129
1130fn visible_particle_count(
1131    instances: &[ParticleGpu],
1132    camera: CameraUniform,
1133    viewport: LogicalViewport,
1134) -> Result<usize, RendererFrameError> {
1135    let mut visible = 0;
1136    for instance in instances.iter().copied() {
1137        let Some(intersects) = instance.validated_viewport_intersection(camera, viewport) else {
1138            return Err(RendererFrameError::InvalidGeometryTransform);
1139        };
1140        visible += usize::from(intersects);
1141    }
1142    Ok(visible)
1143}
1144
1145fn particle_visible_index_is_selected(
1146    visible_index: usize,
1147    visible_count: usize,
1148    selected_count: usize,
1149) -> bool {
1150    if visible_count == 0 || selected_count == 0 {
1151        return false;
1152    }
1153    let before = visible_index as u128 * selected_count as u128 / visible_count as u128;
1154    let after = (visible_index as u128 + 1) * selected_count as u128 / visible_count as u128;
1155    before < after
1156}
1157
1158fn uniformly_sampled_index(sample_index: usize, source_count: usize, sample_count: usize) -> usize {
1159    debug_assert!(sample_index < sample_count);
1160    debug_assert!(sample_count <= source_count);
1161    (((sample_index as u128 + 1) * source_count as u128 - 1) / sample_count as u128) as usize
1162}
1163
1164fn particle_idle_statistics(instance_count: usize) -> ParticleStatistics {
1165    ParticleStatistics {
1166        submitted: instance_count,
1167        visibility_checked: 0,
1168        visible: 0,
1169        culled: 0,
1170        budget_limited: 0,
1171        dropped: 0,
1172        rendered: 0,
1173    }
1174}
1175
1176#[cfg(test)]
1177fn particle_statistics(
1178    instance_count: usize,
1179    visible: usize,
1180    rendered: usize,
1181) -> ParticleStatistics {
1182    particle_statistics_with_budget(instance_count, instance_count, visible, visible, rendered)
1183}
1184
1185fn particle_statistics_with_budget(
1186    instance_count: usize,
1187    visibility_checked: usize,
1188    visible: usize,
1189    selected: usize,
1190    rendered: usize,
1191) -> ParticleStatistics {
1192    ParticleStatistics {
1193        submitted: instance_count,
1194        visibility_checked,
1195        visible,
1196        culled: visibility_checked.saturating_sub(visible),
1197        budget_limited: instance_count
1198            .saturating_sub(visibility_checked)
1199            .saturating_add(visible.saturating_sub(selected)),
1200        dropped: 0,
1201        rendered,
1202    }
1203}
1204
1205fn prepare_scene_resources(
1206    device: &wgpu::Device,
1207    queue: &wgpu::Queue,
1208    renderer_identity: Arc<()>,
1209    scene: &Scene,
1210) -> Result<PreparedScene, PreparedSceneError> {
1211    if !scene_command_sources_are_portable(scene) {
1212        return Err(PreparedSceneError::InvalidGeometrySources);
1213    }
1214    if !scene_estimate_fits_prepared_device(scene, device) {
1215        return Err(PreparedSceneError::CapacityTooLarge);
1216    }
1217    let mut vertices = Vec::new();
1218    let mut draw_batches = Vec::new();
1219    let tessellation = tessellate_scene(scene, &mut vertices, &mut draw_batches)?;
1220    let geometry_extents = GeometryExtents::from_vertices(&vertices);
1221    if !geometry_sources_are_portable(GeometryValidationSource::Tessellated(&vertices)) {
1222        return Err(PreparedSceneError::InvalidGeometrySources);
1223    }
1224    if !buffer_capacity_fits::<Vertex>(device, vertices.len().max(1)) {
1225        return Err(PreparedSceneError::CapacityTooLarge);
1226    }
1227    // Retain the tessellator allocation directly. Wrapping a Vec is O(1) and
1228    // avoids an infallible caller-scale Vec -> Arc<[T]> copy after GPU writes.
1229    let vertices = Arc::new(vertices);
1230    let vertex_buffer = Arc::new(create_vertex_buffer(device, vertices.len()));
1231    if !vertices.is_empty() {
1232        queue.write_buffer(&vertex_buffer, 0, bytemuck::cast_slice(&vertices));
1233        submit_pending_uploads(queue);
1234    }
1235    let vertex_count = vertices.len();
1236
1237    Ok(PreparedScene {
1238        renderer_identity,
1239        background: scene.background(),
1240        vertex_buffer,
1241        vertices,
1242        command_count: scene.command_count(),
1243        vertex_count,
1244        geometry_extents,
1245        draw_batches,
1246        tessellation,
1247        geometry_validation_cache: GeometryValidationCache::default(),
1248    })
1249}
1250
1251fn scene_command_sources_are_portable(scene: &Scene) -> bool {
1252    scene.commands().iter().all(|command| {
1253        is_portable_shader_source(command.depth())
1254            && command.screen_clip().is_none_or(|clip| {
1255                portable_vec2(clip.min().to_vec2()) && portable_vec2(clip.max().to_vec2())
1256            })
1257            && match command.command() {
1258                DrawCommand::Circle(circle) => {
1259                    portable_vec2(circle.center())
1260                        && is_portable_shader_source(circle.radius())
1261                        && portable_shape_style(circle.style())
1262                }
1263                DrawCommand::Rect(rectangle) => {
1264                    portable_vec2(rectangle.rect().min())
1265                        && portable_vec2(rectangle.rect().max())
1266                        && is_portable_shader_source(rectangle.corner_radius())
1267                        && portable_shape_style(rectangle.style())
1268                }
1269                DrawCommand::Line(line) => {
1270                    portable_vec2(line.from())
1271                        && portable_vec2(line.to())
1272                        && portable_stroke_style(line.stroke_style())
1273                }
1274                DrawCommand::Polyline(polyline) => {
1275                    polyline.points().iter().copied().all(portable_vec2)
1276                        && portable_stroke_style(polyline.stroke_style())
1277                }
1278            }
1279    })
1280}
1281
1282fn portable_vec2(value: Vec2) -> bool {
1283    is_portable_shader_source(value.x) && is_portable_shader_source(value.y)
1284}
1285
1286fn portable_shape_style(style: ShapeStyle) -> bool {
1287    style
1288        .stroke()
1289        .is_none_or(|stroke| is_portable_shader_source(stroke.width()))
1290        && style.shadow().is_none_or(|shadow| {
1291            portable_vec2(shadow.offset().to_vec2()) && is_portable_shader_source(shadow.spread())
1292        })
1293}
1294
1295fn portable_stroke_style(style: crate::StrokeStyle2d) -> bool {
1296    let stroke = style.stroke();
1297    is_portable_shader_source(stroke.width())
1298        && is_portable_shader_source(style.miter_limit())
1299        && style.dash_pattern().is_none_or(|dash| {
1300            dash.lengths()
1301                .iter()
1302                .copied()
1303                .chain([dash.phase()])
1304                .all(is_portable_shader_source)
1305        })
1306        && style.start_marker().is_none_or(|marker| {
1307            is_portable_shader_source(marker.length().get())
1308                && is_portable_shader_source(marker.width().get())
1309        })
1310        && style.end_marker().is_none_or(|marker| {
1311            is_portable_shader_source(marker.length().get())
1312                && is_portable_shader_source(marker.width().get())
1313        })
1314}
1315
1316fn restore_prepared_scene_resources(
1317    device: &wgpu::Device,
1318    queue: &wgpu::Queue,
1319    renderer_identity: Arc<()>,
1320    source: &PreparedScene,
1321) -> Result<PreparedScene, PreparedSceneError> {
1322    if !buffer_capacity_fits::<Vertex>(device, source.vertices.len().max(1)) {
1323        return Err(PreparedSceneError::CapacityTooLarge);
1324    }
1325    if !geometry_sources_are_portable(GeometryValidationSource::Tessellated(&source.vertices)) {
1326        return Err(PreparedSceneError::InvalidGeometrySources);
1327    }
1328    let requested_bytes = source
1329        .draw_batches
1330        .len()
1331        .checked_mul(std::mem::size_of::<PreparedDrawBatch>())
1332        .ok_or(PreparedSceneError::CapacityTooLarge)?;
1333    let mut draw_batches = Vec::new();
1334    draw_batches
1335        .try_reserve_exact(source.draw_batches.len())
1336        .map_err(|_| PreparedSceneError::AllocationFailed { requested_bytes })?;
1337    draw_batches.extend_from_slice(&source.draw_batches);
1338    let vertex_buffer = Arc::new(create_vertex_buffer(device, source.vertices.len()));
1339    if !source.vertices.is_empty() {
1340        queue.write_buffer(
1341            &vertex_buffer,
1342            0,
1343            bytemuck::cast_slice(source.vertices.as_ref()),
1344        );
1345        submit_pending_uploads(queue);
1346    }
1347
1348    Ok(PreparedScene {
1349        renderer_identity,
1350        background: source.background,
1351        vertex_buffer,
1352        vertices: Arc::clone(&source.vertices),
1353        command_count: source.command_count,
1354        vertex_count: source.vertex_count,
1355        geometry_extents: source.geometry_extents,
1356        draw_batches,
1357        tessellation: source.tessellation,
1358        geometry_validation_cache: GeometryValidationCache::default(),
1359    })
1360}
1361
1362fn restore_dynamic_mesh_resources(
1363    device: &wgpu::Device,
1364    queue: &wgpu::Queue,
1365    renderer_identity: Arc<()>,
1366    source: &DynamicMesh2d,
1367) -> Result<DynamicMesh2d, DynamicMeshError> {
1368    if !buffer_capacity_fits::<DynamicGpu>(device, source.vertex_capacity) {
1369        return Err(DynamicMeshError::CapacityTooLarge);
1370    }
1371    if let Some(budget) = source.budget {
1372        validate_dynamic_mesh_budget(budget, source.vertices.len())?;
1373    }
1374    let requested_bytes = dynamic_mesh_bytes(source.vertices.len())?;
1375    let mut vertices = Vec::new();
1376    vertices
1377        .try_reserve_exact(source.vertices.len())
1378        .map_err(|_| DynamicMeshError::AllocationFailed { requested_bytes })?;
1379    vertices.extend_from_slice(&source.vertices);
1380    if let Some(budget) = source.budget {
1381        validate_dynamic_retained_capacity(budget, &vertices)?;
1382    }
1383    let vertex_buffer = Arc::new(create_dynamic_vertex_buffer(device, source.vertex_capacity));
1384    if !vertices.is_empty() {
1385        queue.write_buffer(&vertex_buffer, 0, bytemuck::cast_slice(vertices.as_slice()));
1386        submit_pending_uploads(queue);
1387    }
1388    Ok(DynamicMesh2d {
1389        renderer_identity,
1390        vertex_buffer,
1391        vertices,
1392        vertex_capacity: source.vertex_capacity,
1393        geometry_extents: source.geometry_extents,
1394        geometry_validation_cache: GeometryValidationCache::default(),
1395        budget: source.budget,
1396    })
1397}
1398
1399fn restore_particle_field_resources(
1400    device: &wgpu::Device,
1401    _queue: &wgpu::Queue,
1402    renderer_identity: Arc<()>,
1403    source: &ParticleField2d,
1404) -> Result<ParticleField2d, ParticleFieldError> {
1405    validate_particle_retained_count(source.instances.len(), source.budget)?;
1406    if !buffer_capacity_fits::<ParticleGpu>(device, source.instance_capacity) {
1407        return Err(ParticleFieldError::CapacityTooLarge);
1408    }
1409    let requested_bytes = source
1410        .instances
1411        .len()
1412        .checked_mul(std::mem::size_of::<ParticleGpu>())
1413        .ok_or(ParticleFieldError::CapacityTooLarge)?;
1414    let mut instances = Vec::new();
1415    instances
1416        .try_reserve_exact(source.instances.len())
1417        .map_err(|_| ParticleFieldError::AllocationFailed { requested_bytes })?;
1418    instances.extend_from_slice(&source.instances);
1419    let visible_instances = allocate_particle_staging(instances.len(), source.budget)?;
1420    validate_particle_retained_capacities(
1421        instances.capacity(),
1422        visible_instances.capacity(),
1423        source.budget,
1424    )?;
1425    let instance_buffer = Arc::new(create_particle_instance_buffer(
1426        device,
1427        source.instance_capacity,
1428    ));
1429    Ok(ParticleField2d {
1430        renderer_identity,
1431        instance_buffer,
1432        instances,
1433        visible_instances,
1434        instance_capacity: source.instance_capacity,
1435        budget: source.budget,
1436        statistics: particle_idle_statistics(source.instances.len()),
1437    })
1438}
1439
1440#[allow(clippy::too_many_arguments)]
1441fn render_report(
1442    status: RenderStatus,
1443    tessellation: Duration,
1444    upload: Duration,
1445    camera_uniform_upload: Duration,
1446    surface_acquire: Duration,
1447    encode_submit_present: Duration,
1448    total_cpu: Duration,
1449    geometry_reused: bool,
1450    geometry_streamed: bool,
1451    tessellation_stats: TessellationStats,
1452) -> RenderReport {
1453    RenderReport {
1454        status,
1455        metrics: RendererFrameMetrics {
1456            tessellation,
1457            upload,
1458            camera_uniform_upload,
1459            surface_acquire,
1460            encode_submit_present,
1461            total_cpu,
1462            geometry_reused,
1463            geometry_streamed,
1464            tessellation_stats,
1465        },
1466    }
1467}
1468
1469fn preferred_sample_count(adapter: &wgpu::Adapter, format: wgpu::TextureFormat) -> u32 {
1470    let flags = adapter.get_texture_format_features(format).flags;
1471    if flags.contains(
1472        wgpu::TextureFormatFeatureFlags::MULTISAMPLE_X4
1473            | wgpu::TextureFormatFeatureFlags::MULTISAMPLE_RESOLVE,
1474    ) {
1475        PREFERRED_SAMPLE_COUNT
1476    } else {
1477        1
1478    }
1479}
1480
1481fn create_vertex_buffer(device: &wgpu::Device, capacity: usize) -> wgpu::Buffer {
1482    device.create_buffer(&wgpu::BufferDescriptor {
1483        label: Some("sim-engine vertex buffer"),
1484        size: (capacity.max(1) * std::mem::size_of::<Vertex>()) as wgpu::BufferAddress,
1485        usage: wgpu::BufferUsages::VERTEX
1486            | wgpu::BufferUsages::COPY_DST
1487            | wgpu::BufferUsages::COPY_SRC,
1488        mapped_at_creation: false,
1489    })
1490}
1491
1492fn create_dynamic_vertex_buffer(device: &wgpu::Device, capacity: usize) -> wgpu::Buffer {
1493    device.create_buffer(&wgpu::BufferDescriptor {
1494        label: Some("sim-engine dynamic vertex buffer"),
1495        size: (capacity.max(1) * std::mem::size_of::<DynamicGpu>()) as wgpu::BufferAddress,
1496        usage: wgpu::BufferUsages::VERTEX
1497            | wgpu::BufferUsages::COPY_DST
1498            | wgpu::BufferUsages::COPY_SRC,
1499        mapped_at_creation: false,
1500    })
1501}
1502
1503fn scalar_field_extent(field: &ScalarField) -> Result<wgpu::Extent3d, ScalarFieldTextureError> {
1504    let width =
1505        u32::try_from(field.width()).map_err(|_| ScalarFieldTextureError::DimensionsTooLarge)?;
1506    let height =
1507        u32::try_from(field.height()).map_err(|_| ScalarFieldTextureError::DimensionsTooLarge)?;
1508    let _bytes_per_row = width
1509        .checked_mul(std::mem::size_of::<f32>() as u32)
1510        .ok_or(ScalarFieldTextureError::DimensionsTooLarge)?;
1511    Ok(wgpu::Extent3d {
1512        width,
1513        height,
1514        depth_or_array_layers: 1,
1515    })
1516}
1517
1518fn clone_scalar_field_for_restore(
1519    source: &ScalarField,
1520) -> Result<ScalarField, ScalarFieldTextureError> {
1521    let requested_bytes = source
1522        .values()
1523        .len()
1524        .checked_mul(std::mem::size_of::<f32>())
1525        .ok_or(ScalarFieldTextureError::DimensionsTooLarge)?;
1526    let mut values = Vec::new();
1527    values
1528        .try_reserve_exact(source.values().len())
1529        .map_err(|_| ScalarFieldTextureError::AllocationFailed { requested_bytes })?;
1530    values.extend_from_slice(source.values());
1531    // The retained source already satisfies ScalarField's shape and finite
1532    // invariants. Keep the impossible defensive branch structured.
1533    ScalarField::new(source.width(), source.height(), values)
1534        .map_err(|_| ScalarFieldTextureError::DimensionsTooLarge)
1535}
1536
1537fn scalar_value_range_extent(minimum: f32, maximum: f32) -> Option<f32> {
1538    if !is_portable_shader_source(minimum)
1539        || !is_portable_shader_source(maximum)
1540        || maximum <= minimum
1541    {
1542        return None;
1543    }
1544    let extent = maximum - minimum;
1545    (is_portable_shader_source(extent) && extent > 0.0).then_some(extent)
1546}
1547
1548fn scalar_field_sources_are_portable(field: &ScalarField) -> bool {
1549    if field
1550        .values()
1551        .iter()
1552        .copied()
1553        .any(|value| !is_portable_shader_source(value))
1554    {
1555        return false;
1556    }
1557    let (minimum, maximum) = field.value_range();
1558    let extent = f64::from(maximum) - f64::from(minimum);
1559    extent.is_finite() && extent <= f64::from(MAX_PORTABLE_SHADER_VALUE)
1560}
1561
1562fn scalar_normalization_is_portable(
1563    texture: &ScalarFieldTexture,
1564    minimum: f32,
1565    value_extent: f32,
1566) -> bool {
1567    if !is_portable_shader_source(minimum)
1568        || !is_portable_shader_source(value_extent)
1569        || value_extent <= 0.0
1570    {
1571        return false;
1572    }
1573    let Some(numerator) = shader_interval_sum_range([
1574        (
1575            f64::from(texture.source_minimum),
1576            f64::from(texture.source_maximum),
1577        ),
1578        (-f64::from(minimum), -f64::from(minimum)),
1579    ]) else {
1580        return false;
1581    };
1582    [numerator.0, numerator.1].into_iter().all(|value| {
1583        let normalized = value / f64::from(value_extent);
1584        normalized.is_finite() && normalized.abs() <= f64::from(MAX_PORTABLE_SHADER_VALUE)
1585    })
1586}
1587
1588fn compact_scalar_field_for_retention(
1589    field: ScalarField,
1590) -> Result<ScalarField, ScalarFieldTextureError> {
1591    let requested_bytes = field
1592        .values()
1593        .len()
1594        .checked_mul(std::mem::size_of::<f32>())
1595        .ok_or(ScalarFieldTextureError::DimensionsTooLarge)?;
1596    if field.value_allocation_bytes() <= requested_bytes {
1597        return Ok(field);
1598    }
1599    clone_scalar_field_for_restore(&field)
1600}
1601
1602fn premultiplied_wgpu_color(color: Color) -> wgpu::Color {
1603    let [red, green, blue, alpha] = color.to_array();
1604    wgpu::Color {
1605        r: f64::from(red * alpha),
1606        g: f64::from(green * alpha),
1607        b: f64::from(blue * alpha),
1608        a: f64::from(alpha),
1609    }
1610}
1611
1612fn create_scalar_field_texture(
1613    device: &wgpu::Device,
1614    field: &ScalarField,
1615) -> Result<wgpu::Texture, ScalarFieldTextureError> {
1616    let extent = scalar_field_extent(field)?;
1617    let limits = device.limits();
1618    if extent.width > limits.max_texture_dimension_2d
1619        || extent.height > limits.max_texture_dimension_2d
1620    {
1621        return Err(ScalarFieldTextureError::DimensionsTooLarge);
1622    }
1623    Ok(device.create_texture(&wgpu::TextureDescriptor {
1624        label: Some("sim-engine scalar field texture"),
1625        size: extent,
1626        mip_level_count: 1,
1627        sample_count: 1,
1628        dimension: wgpu::TextureDimension::D2,
1629        format: wgpu::TextureFormat::R32Float,
1630        usage: wgpu::TextureUsages::TEXTURE_BINDING
1631            | wgpu::TextureUsages::COPY_DST
1632            | wgpu::TextureUsages::COPY_SRC,
1633        view_formats: &[],
1634    }))
1635}
1636
1637fn validate_scalar_field_device_extent(
1638    device: &wgpu::Device,
1639    field: &ScalarField,
1640) -> Result<wgpu::Extent3d, ScalarFieldTextureError> {
1641    let extent = scalar_field_extent(field)?;
1642    let limit = device.limits().max_texture_dimension_2d;
1643    if extent.width > limit || extent.height > limit {
1644        return Err(ScalarFieldTextureError::DimensionsTooLarge);
1645    }
1646    Ok(extent)
1647}
1648
1649fn upload_scalar_field_texture(
1650    queue: &wgpu::Queue,
1651    texture: &wgpu::Texture,
1652    field: &ScalarField,
1653) -> Result<(), ScalarFieldTextureError> {
1654    let extent = scalar_field_extent(field)?;
1655    queue.write_texture(
1656        wgpu::TexelCopyTextureInfo {
1657            texture,
1658            mip_level: 0,
1659            origin: wgpu::Origin3d::ZERO,
1660            aspect: wgpu::TextureAspect::All,
1661        },
1662        bytemuck::cast_slice(field.values()),
1663        wgpu::TexelCopyBufferLayout {
1664            offset: 0,
1665            bytes_per_row: Some(extent.width * std::mem::size_of::<f32>() as u32),
1666            rows_per_image: Some(extent.height),
1667        },
1668        extent,
1669    );
1670    submit_pending_uploads(queue);
1671    Ok(())
1672}
1673
1674fn upload_scalar_field_texture_region(
1675    queue: &wgpu::Queue,
1676    texture: &wgpu::Texture,
1677    x: usize,
1678    y: usize,
1679    width: usize,
1680    height: usize,
1681    values: &[f32],
1682) -> Result<(), ScalarFieldTextureError> {
1683    let width = u32::try_from(width).map_err(|_| ScalarFieldTextureError::DimensionsTooLarge)?;
1684    let height = u32::try_from(height).map_err(|_| ScalarFieldTextureError::DimensionsTooLarge)?;
1685    let x = u32::try_from(x).map_err(|_| ScalarFieldTextureError::DimensionsTooLarge)?;
1686    let y = u32::try_from(y).map_err(|_| ScalarFieldTextureError::DimensionsTooLarge)?;
1687    let bytes_per_row = width
1688        .checked_mul(std::mem::size_of::<f32>() as u32)
1689        .ok_or(ScalarFieldTextureError::DimensionsTooLarge)?;
1690    queue.write_texture(
1691        wgpu::TexelCopyTextureInfo {
1692            texture,
1693            mip_level: 0,
1694            origin: wgpu::Origin3d { x, y, z: 0 },
1695            aspect: wgpu::TextureAspect::All,
1696        },
1697        bytemuck::cast_slice(values),
1698        wgpu::TexelCopyBufferLayout {
1699            offset: 0,
1700            bytes_per_row: Some(bytes_per_row),
1701            rows_per_image: Some(height),
1702        },
1703        wgpu::Extent3d {
1704            width,
1705            height,
1706            depth_or_array_layers: 1,
1707        },
1708    );
1709    submit_pending_uploads(queue);
1710    Ok(())
1711}
1712
1713/// Submits deferred `Queue::write_*` transfers without waiting for GPU completion.
1714///
1715/// Native `wgpu` retains staging allocations until a queue submission starts
1716/// their transfer. Standalone retained-resource mutations call this immediately;
1717/// render paths instead combine their writes with the draw submission.
1718pub(super) fn submit_pending_uploads(queue: &wgpu::Queue) {
1719    let _ = queue.submit([]);
1720}
1721
1722#[allow(clippy::too_many_arguments)]
1723fn validate_scalar_field_texture_region(
1724    texture_width: usize,
1725    texture_height: usize,
1726    x: usize,
1727    y: usize,
1728    width: usize,
1729    height: usize,
1730    value_count: usize,
1731) -> Result<(), ScalarFieldTextureError> {
1732    let expected = width
1733        .checked_mul(height)
1734        .ok_or(ScalarFieldTextureError::DimensionsTooLarge)?;
1735    if value_count != expected {
1736        return Err(ScalarFieldTextureError::InvalidUpdateValueCount);
1737    }
1738    if width == 0
1739        || height == 0
1740        || x.checked_add(width).is_none_or(|end| end > texture_width)
1741        || y.checked_add(height).is_none_or(|end| end > texture_height)
1742    {
1743        return Err(ScalarFieldTextureError::UpdateRegionOutOfBounds);
1744    }
1745    for value in [x, y, width, height] {
1746        u32::try_from(value).map_err(|_| ScalarFieldTextureError::DimensionsTooLarge)?;
1747    }
1748    u32::try_from(width)
1749        .ok()
1750        .and_then(|width| width.checked_mul(std::mem::size_of::<f32>() as u32))
1751        .ok_or(ScalarFieldTextureError::DimensionsTooLarge)?;
1752    Ok(())
1753}
1754
1755fn scalar_region_result_range(
1756    field: &ScalarField,
1757    x: usize,
1758    y: usize,
1759    width: usize,
1760    height: usize,
1761    values: &[f32],
1762) -> (f32, f32) {
1763    let mut minimum = f32::INFINITY;
1764    let mut maximum = f32::NEG_INFINITY;
1765    for row in 0..field.height() {
1766        for column in 0..field.width() {
1767            let value = if (x..x + width).contains(&column) && (y..y + height).contains(&row) {
1768                values[(row - y) * width + (column - x)]
1769            } else {
1770                field.values()[row * field.width() + column]
1771            };
1772            minimum = minimum.min(value);
1773            maximum = maximum.max(value);
1774        }
1775    }
1776    (minimum, maximum)
1777}
1778
1779fn create_scalar_field_texture_resources(
1780    device: &wgpu::Device,
1781    queue: &wgpu::Queue,
1782    renderer_identity: Arc<()>,
1783    field: ScalarField,
1784) -> Result<ScalarFieldTexture, ScalarFieldTextureError> {
1785    validate_scalar_field_device_extent(device, &field)?;
1786    if !scalar_field_sources_are_portable(&field) {
1787        return Err(ScalarFieldTextureError::NonPortableValue);
1788    }
1789    let field = compact_scalar_field_for_retention(field)?;
1790    let (source_minimum, source_maximum) = field.value_range();
1791    let texture = create_scalar_field_texture(device, &field)?;
1792    upload_scalar_field_texture(queue, &texture, &field)?;
1793    Ok(ScalarFieldTexture {
1794        renderer_identity,
1795        texture,
1796        field,
1797        source_minimum,
1798        source_maximum,
1799    })
1800}
1801
1802fn color_map_lut(color_map: &ColorMap) -> [u8; COLOR_MAP_LUT_SIZE as usize * 4] {
1803    let mut bytes = [0_u8; COLOR_MAP_LUT_SIZE as usize * 4];
1804    for index in 0..COLOR_MAP_LUT_SIZE {
1805        let color = color_map.sample_normalized(index as f32 / (COLOR_MAP_LUT_SIZE - 1) as f32);
1806        let offset = index as usize * 4;
1807        bytes[offset..offset + 4].copy_from_slice(
1808            &color
1809                .to_array()
1810                .map(|channel| (channel * 255.0).round() as u8),
1811        );
1812    }
1813    bytes
1814}
1815
1816fn create_cached_color_map(
1817    device: &wgpu::Device,
1818    queue: &wgpu::Queue,
1819    lut: [u8; COLOR_MAP_LUT_SIZE as usize * 4],
1820) -> CachedColorMap {
1821    let texture = device.create_texture(&wgpu::TextureDescriptor {
1822        label: Some("sim-engine color map texture"),
1823        size: wgpu::Extent3d {
1824            width: COLOR_MAP_LUT_SIZE,
1825            height: 1,
1826            depth_or_array_layers: 1,
1827        },
1828        mip_level_count: 1,
1829        sample_count: 1,
1830        dimension: wgpu::TextureDimension::D2,
1831        format: wgpu::TextureFormat::Rgba8Unorm,
1832        usage: wgpu::TextureUsages::TEXTURE_BINDING | wgpu::TextureUsages::COPY_DST,
1833        view_formats: &[],
1834    });
1835    queue.write_texture(
1836        wgpu::TexelCopyTextureInfo {
1837            texture: &texture,
1838            mip_level: 0,
1839            origin: wgpu::Origin3d::ZERO,
1840            aspect: wgpu::TextureAspect::All,
1841        },
1842        &lut,
1843        wgpu::TexelCopyBufferLayout {
1844            offset: 0,
1845            bytes_per_row: Some(1024),
1846            rows_per_image: Some(1),
1847        },
1848        wgpu::Extent3d {
1849            width: COLOR_MAP_LUT_SIZE,
1850            height: 1,
1851            depth_or_array_layers: 1,
1852        },
1853    );
1854    let view = texture.create_view(&wgpu::TextureViewDescriptor::default());
1855    CachedColorMap {
1856        lut,
1857        _texture: texture,
1858        view,
1859    }
1860}
1861
1862fn create_submitted_particle_unit_buffer(
1863    device: &wgpu::Device,
1864    queue: &wgpu::Queue,
1865) -> wgpu::Buffer {
1866    let buffer = device.create_buffer(&wgpu::BufferDescriptor {
1867        label: Some("sim-engine particle unit quad buffer"),
1868        size: (6 * std::mem::size_of::<ParticleUnitVertex>()) as wgpu::BufferAddress,
1869        usage: wgpu::BufferUsages::VERTEX | wgpu::BufferUsages::COPY_DST,
1870        mapped_at_creation: false,
1871    });
1872    let unit_quad = [
1873        ParticleUnitVertex {
1874            direction: [-1.0, -1.0],
1875        },
1876        ParticleUnitVertex {
1877            direction: [1.0, -1.0],
1878        },
1879        ParticleUnitVertex {
1880            direction: [1.0, 1.0],
1881        },
1882        ParticleUnitVertex {
1883            direction: [-1.0, -1.0],
1884        },
1885        ParticleUnitVertex {
1886            direction: [1.0, 1.0],
1887        },
1888        ParticleUnitVertex {
1889            direction: [-1.0, 1.0],
1890        },
1891    ];
1892    queue.write_buffer(&buffer, 0, bytemuck::cast_slice(&unit_quad));
1893    submit_pending_uploads(queue);
1894    buffer
1895}
1896
1897fn create_particle_instance_buffer(device: &wgpu::Device, capacity: usize) -> wgpu::Buffer {
1898    device.create_buffer(&wgpu::BufferDescriptor {
1899        label: Some("sim-engine particle instance buffer"),
1900        size: (capacity.max(1) * std::mem::size_of::<ParticleGpu>()) as wgpu::BufferAddress,
1901        usage: wgpu::BufferUsages::VERTEX | wgpu::BufferUsages::COPY_DST,
1902        mapped_at_creation: false,
1903    })
1904}
1905
1906mod config;
1907mod dynamic_mesh;
1908mod exact_markers;
1909mod frame;
1910mod geometry;
1911mod glyph;
1912mod gpu_timing;
1913mod image;
1914mod initialization;
1915mod mesh3d;
1916mod particles;
1917mod pipelines;
1918mod scalar_fields;
1919mod scenes;
1920mod targets;
1921mod tessellation;
1922#[cfg(feature = "text")]
1923mod text;
1924#[cfg(feature = "text")]
1925pub use text::{
1926    PreparedTextError, TextAtlas2d, TextAtlasBudget, TextError, TextRun2d, TextUpdateReport,
1927};
1928mod visualization;
1929use config::{
1930    MultisampleTarget, create_multisample_target, logical_to_physical_screen,
1931    physical_to_logical_screen, validate_scale_factor, validate_surface_dimensions,
1932};
1933pub use config::{RendererPresentMode, RendererSurfacePresentMode, WgpuRendererOptions};
1934pub use dynamic_mesh::{
1935    DynamicMesh2d, DynamicMeshBudget, DynamicMeshBudgetResource, DynamicMeshError,
1936    DynamicMeshRenderError, DynamicMeshUpdateReport, DynamicVertex2d,
1937};
1938pub use frame::{
1939    FrameBudget, FrameBudgetResource, FrameCacheBudget, FrameCacheStatistics, FrameComposer,
1940    FrameComposerError, FramePassOptions, FrameReport, FrameSourceKind, FrameSourceStatistics,
1941    FrameStatistics,
1942};
1943pub use glyph::{
1944    GlyphAtlas2d, GlyphAtlasBudget, GlyphAtlasEntry, GlyphError, GlyphId, GlyphRun2d,
1945    GlyphRunBounds, GlyphRunBudget, GlyphRunStatistics, GlyphRunUploadReport, GlyphUploadReport,
1946    PositionedGlyph2d,
1947};
1948pub use gpu_timing::{
1949    GpuTimingBatch, GpuTimingId, GpuTimingSample, GpuTimingSource, GpuTimingStatistics,
1950    GpuTimingStatus,
1951};
1952pub use image::{
1953    Image2d, ImageBatch2d, ImageBatchBudget, ImageBatchPlacement, ImageBatchUploadReport,
1954    ImageBudget, ImageError, ImageSampling, ImageSprite2d, ImageTexelRect, ImageUploadReport,
1955};
1956use image::{ImageRenderer, ImageUniform};
1957use mesh3d::Mesh3dRenderer;
1958pub use mesh3d::{
1959    DynamicMesh3dBudget, DynamicMesh3dBudgetResource, DynamicMesh3dError,
1960    DynamicMesh3dUpdateReport, Mesh3dInstance, Mesh3dObjectError, Mesh3dPreflightReport,
1961    Mesh3dRenderBudget, Mesh3dRenderError, Mesh3dRenderReport, Mesh3dResourceError,
1962    Mesh3dSurfaceError, Mesh3dUploadBudget, Mesh3dUploadBudgetResource, Mesh3dUploadReport,
1963    Object3dId, RenderTarget3d, RetainedMesh3d, Scene3d, Scene3dBudget, Scene3dBudgetResource,
1964    Scene3dError, Scene3dMeshUpdateReport, Scene3dRestoreReport, Scene3dStatistics,
1965    SurfaceRasterization3d, Texture3d, Texture3dError, Texture3dOptions, Texture3dUpdateBudget,
1966    Texture3dUpdateBudgetResource, Texture3dUpdateError, Texture3dUpdateReport, TextureMaterial3d,
1967    TextureMipmaps3d,
1968};
1969pub use particles::{
1970    ParticleBudgetError, ParticleField2d, ParticleFieldError, ParticleFieldRenderError,
1971    ParticleFieldUpdateReport, ParticleRenderBudget, ParticleStatistics,
1972};
1973use pipelines::{PipelineResources, create_pipeline};
1974pub use scalar_fields::{
1975    ScalarFieldRenderError, ScalarFieldTexture, ScalarFieldTextureError, ScalarFieldUploadReport,
1976};
1977pub use targets::{RenderTarget2d, RenderTargetError, TrailBuffer2d};
1978use tessellation::{
1979    logical_viewport_scissor, offset_scissor, screen_clip_to_scissor, tessellate_scene,
1980};
1981use visualization::{CachedColorMap, CompositionPipelines};
1982pub use visualization::{
1983    LayeredVisualizationError, LayeredVisualizationOptions, LayeredVisualizationReport,
1984};
1985
1986#[cfg(test)]
1987use tessellation::world_vertex;
1988
1989#[cfg(test)]
1990mod tests;
1991
1992#[cfg(test)]
1993mod test_support;