Skip to main content

sim_engine/renderer/
mesh3d.rs

1use super::*;
2use crate::{
3    Camera3d, LogicalPixels, Mesh3d, MeshStyle3d, PhysicalPerLogical, Transform3d, Vec3,
4    WireframeStyle3d,
5};
6use std::sync::atomic::{AtomicU64, Ordering};
7
8#[path = "mesh3d_validation.rs"]
9mod validation;
10use validation::validate_points_for_policy;
11pub use validation::{Mesh3dSurfaceError, SurfaceRasterization3d};
12
13#[path = "mesh3d_surface.rs"]
14mod surface;
15pub use surface::{Mesh3dPreflightReport, Mesh3dRenderBudget};
16use surface::{SurfaceClipEdge, SurfaceClipVertex, SurfaceFrame, SurfaceObject};
17
18#[path = "mesh3d_texture.rs"]
19mod texture;
20use texture::{MeshTextureRenderer, MeshUvGpu};
21#[path = "mesh3d_restoration.rs"]
22mod restoration;
23use restoration::restore_retained_mesh;
24#[path = "mesh3d_colors.rs"]
25mod colors;
26use crate::mesh3d::{SurfaceAlphaMode3d, SurfaceSidedness3d};
27use colors::MeshColorGpu;
28#[path = "mesh3d_normals.rs"]
29mod normals;
30use normals::MeshNormalGpu;
31#[path = "mesh3d_lighting.rs"]
32mod lighting;
33use crate::mesh3d::{Fog3d, Lighting3d, SurfaceLighting3d};
34use lighting::{SurfaceEnvironmentGpu, SurfaceLightingVertex, SurfaceTransport};
35#[path = "mesh3d_surface_pipeline.rs"]
36mod surface_pipeline;
37use surface_pipeline::{SurfaceLayout, SurfacePipelines, create_surface_pipelines};
38#[cfg(test)]
39#[path = "mesh3d_lighting_tests.rs"]
40mod lighting_tests;
41#[path = "mesh3d_material.rs"]
42mod material;
43#[cfg(test)]
44#[path = "mesh3d_material_tests.rs"]
45mod material_tests;
46#[cfg(test)]
47#[path = "mesh3d_native_acceptance_tests.rs"]
48mod native_acceptance_tests;
49
50#[cfg(test)]
51#[path = "mesh3d_material_resource_tests.rs"]
52mod material_resource_tests;
53pub use texture::{
54    Texture3d, Texture3dError, Texture3dOptions, Texture3dUpdateBudget,
55    Texture3dUpdateBudgetResource, Texture3dUpdateError, Texture3dUpdateReport, TextureMaterial3d,
56    TextureMipmaps3d,
57};
58
59#[cfg(test)]
60use crate::{MeshEdge3d, Projection3d, Rotation3d, SurfaceStyle3d, WorldLength};
61
62#[cfg(test)]
63#[path = "mesh3d_lifetime_tests.rs"]
64mod lifetime_tests;
65
66#[cfg(test)]
67#[path = "mesh3d_vertex_color_tests.rs"]
68mod vertex_color_tests;
69
70#[cfg(test)]
71#[path = "mesh3d_color_budget_tests.rs"]
72mod color_budget_tests;
73
74#[cfg(test)]
75#[path = "mesh3d_timing_tests.rs"]
76mod timing_tests;
77#[cfg(test)]
78pub(super) use timing_tests::assert_gpu_scene_timing_and_upload_contract;
79
80#[cfg(test)]
81fn logical(value: f32) -> LogicalPixels {
82    LogicalPixels::new(value).unwrap()
83}
84
85#[cfg(test)]
86fn physical_per_logical(value: f32) -> PhysicalPerLogical {
87    PhysicalPerLogical::new(value).unwrap()
88}
89
90#[cfg(test)]
91fn world(value: f32) -> WorldLength {
92    WorldLength::new(value).unwrap()
93}
94
95const INITIAL_INSTANCE_CAPACITY: usize = 16;
96const DEPTH_FORMAT: wgpu::TextureFormat = wgpu::TextureFormat::Depth32Float;
97// Hidden fragments are biased one implementation depth unit away from the
98// camera; visible fragments are biased one unit toward it and are rendered
99// last. This defines a two-unit coplanar tolerance: exact/shared surface edges
100// resolve solid, while occlusion must exceed that tolerance to resolve dashed.
101const HIDDEN_EDGE_DEPTH_BIAS: i32 = 1;
102const VISIBLE_EDGE_DEPTH_BIAS: i32 = -1;
103static NEXT_SCENE3D_ID: AtomicU64 = AtomicU64::new(1);
104
105#[repr(C)]
106#[derive(Clone, Copy, Debug, bytemuck::Pod, bytemuck::Zeroable)]
107struct MeshVertexGpu {
108    position: [f32; 3],
109}
110
111impl MeshVertexGpu {
112    const ATTRIBUTES: [wgpu::VertexAttribute; 1] = wgpu::vertex_attr_array![0 => Float32x3];
113    const LAYOUT: wgpu::VertexBufferLayout<'static> = wgpu::VertexBufferLayout {
114        array_stride: std::mem::size_of::<Self>() as wgpu::BufferAddress,
115        step_mode: wgpu::VertexStepMode::Vertex,
116        attributes: &Self::ATTRIBUTES,
117    };
118}
119
120#[repr(C)]
121#[derive(Clone, Copy, Debug, bytemuck::Pod, bytemuck::Zeroable)]
122struct MeshInstanceGpu {
123    model_row_0: [f32; 4],
124    model_row_1: [f32; 4],
125    model_row_2: [f32; 4],
126    color: [f32; 4],
127    surface: [f32; 4],
128    normal_row_0: [f32; 4],
129    normal_row_1: [f32; 4],
130    normal_row_2: [f32; 4],
131    uv_transform: [f32; 4],
132}
133
134impl MeshInstanceGpu {
135    const ATTRIBUTES: [wgpu::VertexAttribute; 9] = wgpu::vertex_attr_array![1 => Float32x4, 2 => Float32x4, 3 => Float32x4, 4 => Float32x4, 7 => Float32x4, 9 => Float32x4, 10 => Float32x4, 11 => Float32x4, 12 => Float32x4];
136    const LAYOUT: wgpu::VertexBufferLayout<'static> = wgpu::VertexBufferLayout {
137        array_stride: std::mem::size_of::<Self>() as wgpu::BufferAddress,
138        step_mode: wgpu::VertexStepMode::Instance,
139        attributes: &Self::ATTRIBUTES,
140    };
141}
142
143#[repr(C)]
144#[derive(Clone, Copy, Debug, bytemuck::Pod, bytemuck::Zeroable)]
145struct Camera3dUniform {
146    clip_row_0: [f32; 4],
147    clip_row_1: [f32; 4],
148    clip_row_2: [f32; 4],
149    clip_row_3: [f32; 4],
150    viewport: [f32; 4],
151    environment: SurfaceEnvironmentGpu,
152}
153
154impl Camera3dUniform {
155    fn new(
156        camera: Camera3d,
157        width: u32,
158        height: u32,
159        scale_factor: PhysicalPerLogical,
160    ) -> Result<Self, Mesh3dRenderError> {
161        let rows = camera
162            .world_to_clip_rows()
163            .map_err(|_| Mesh3dRenderError::InvalidGeometryTransform)?;
164        let uniform = Self {
165            clip_row_0: rows[0],
166            clip_row_1: rows[1],
167            clip_row_2: rows[2],
168            clip_row_3: rows[3],
169            viewport: [width as f32, height as f32, scale_factor.get(), 0.0],
170            environment: SurfaceEnvironmentGpu::default(),
171        };
172        uniform
173            .rows()
174            .into_iter()
175            .flatten()
176            .chain(uniform.viewport)
177            .all(is_portable_shader_source)
178            .then_some(uniform)
179            .ok_or(Mesh3dRenderError::InvalidGeometryTransform)
180    }
181
182    fn rows(self) -> [[f32; 4]; 4] {
183        [
184            self.clip_row_0,
185            self.clip_row_1,
186            self.clip_row_2,
187            self.clip_row_3,
188        ]
189    }
190}
191
192#[repr(C)]
193#[derive(Clone, Copy, Debug, bytemuck::Pod, bytemuck::Zeroable)]
194struct MeshEdgeGpu {
195    start: [f32; 3],
196    end: [f32; 3],
197}
198
199impl MeshEdgeGpu {
200    const ATTRIBUTES: [wgpu::VertexAttribute; 2] =
201        wgpu::vertex_attr_array![0 => Float32x3, 1 => Float32x3];
202    const LAYOUT: wgpu::VertexBufferLayout<'static> = wgpu::VertexBufferLayout {
203        array_stride: std::mem::size_of::<Self>() as wgpu::BufferAddress,
204        step_mode: wgpu::VertexStepMode::Instance,
205        attributes: &Self::ATTRIBUTES,
206    };
207}
208
209#[repr(C)]
210#[derive(Clone, Copy, Debug, bytemuck::Pod, bytemuck::Zeroable)]
211struct EdgeObjectUniform {
212    model_row_0: [f32; 4],
213    model_row_1: [f32; 4],
214    model_row_2: [f32; 4],
215    visible_color: [f32; 4],
216    hidden_color: [f32; 4],
217    edge_style: [f32; 4],
218}
219
220#[cfg(test)]
221#[repr(C)]
222#[derive(Clone, Copy, Debug, bytemuck::Pod, bytemuck::Zeroable)]
223struct ClipProbeInputGpu {
224    start_clip: [f32; 4],
225    end_clip: [f32; 4],
226}
227
228#[cfg(test)]
229#[repr(C)]
230#[derive(Clone, Copy, Debug, bytemuck::Pod, bytemuck::Zeroable)]
231struct ClipProbeOutputGpu {
232    start_clip: [f32; 4],
233    end_clip: [f32; 4],
234    range: [f32; 2],
235    visible: u32,
236    padding: u32,
237}
238
239pub(super) struct Mesh3dRenderer {
240    dynamic_scratch: dynamic::DynamicMesh3dScratch,
241    textures: MeshTextureRenderer,
242    pipeline: SurfacePipelines,
243    colored_pipeline: SurfacePipelines,
244    colored_clipped_pipeline: SurfacePipelines,
245    clipped_color_buffer: Option<wgpu::Buffer>,
246    clipped_color_capacity: usize,
247    clipped_lighting_buffer: Option<wgpu::Buffer>,
248    clipped_lighting_capacity: usize,
249    clipped_surface_pipeline: SurfacePipelines,
250    clipped_surface_buffer: Option<wgpu::Buffer>,
251    clipped_surface_capacity: usize,
252    clipped_surface_objects: Vec<SurfaceObject>,
253    clipped_visible_edge_pipeline: wgpu::RenderPipeline,
254    clipped_hidden_edge_pipeline: wgpu::RenderPipeline,
255    clipped_edge_buffer: Option<wgpu::Buffer>,
256    clipped_edge_capacity: usize,
257    visible_edge_pipeline: wgpu::RenderPipeline,
258    hidden_edge_pipeline: wgpu::RenderPipeline,
259    camera_uniform_buffer: wgpu::Buffer,
260    camera_bind_group: wgpu::BindGroup,
261    instance_buffer: wgpu::Buffer,
262    instance_capacity: usize,
263    instances: Vec<MeshInstanceGpu>,
264    edge_object_layout: wgpu::BindGroupLayout,
265    edge_object_bind_group: wgpu::BindGroup,
266    edge_object_buffer: wgpu::Buffer,
267    edge_object_stride: usize,
268    edge_object_capacity: usize,
269    edge_object_bytes: Vec<u8>,
270}
271
272impl Mesh3dRenderer {
273    pub(super) fn new(device: &wgpu::Device, format: wgpu::TextureFormat) -> Self {
274        let shader = device.create_shader_module(wgpu::ShaderModuleDescriptor {
275            label: Some("sim-engine retained 3D mesh shader"),
276            source: wgpu::ShaderSource::Wgsl(lighting::shader_source(include_str!("mesh3d.wgsl"))),
277        });
278        let camera_uniform_buffer = device.create_buffer(&wgpu::BufferDescriptor {
279            label: Some("sim-engine 3D camera uniform buffer"),
280            size: std::mem::size_of::<Camera3dUniform>() as wgpu::BufferAddress,
281            usage: wgpu::BufferUsages::UNIFORM | wgpu::BufferUsages::COPY_DST,
282            mapped_at_creation: false,
283        });
284        let camera_layout = device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
285            label: Some("sim-engine 3D camera bind group layout"),
286            entries: &[wgpu::BindGroupLayoutEntry {
287                binding: 0,
288                visibility: wgpu::ShaderStages::VERTEX_FRAGMENT,
289                ty: wgpu::BindingType::Buffer {
290                    ty: wgpu::BufferBindingType::Uniform,
291                    has_dynamic_offset: false,
292                    min_binding_size: None,
293                },
294                count: None,
295            }],
296        });
297        let camera_bind_group = device.create_bind_group(&wgpu::BindGroupDescriptor {
298            label: Some("sim-engine 3D camera bind group"),
299            layout: &camera_layout,
300            entries: &[wgpu::BindGroupEntry {
301                binding: 0,
302                resource: camera_uniform_buffer.as_entire_binding(),
303            }],
304        });
305        let edge_object_stride = align_to(
306            std::mem::size_of::<EdgeObjectUniform>(),
307            device.limits().min_uniform_buffer_offset_alignment as usize,
308        );
309        let edge_object_layout =
310            device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
311                label: Some("sim-engine 3D edge object bind group layout"),
312                entries: &[wgpu::BindGroupLayoutEntry {
313                    binding: 0,
314                    visibility: wgpu::ShaderStages::VERTEX_FRAGMENT,
315                    ty: wgpu::BindingType::Buffer {
316                        ty: wgpu::BufferBindingType::Uniform,
317                        has_dynamic_offset: true,
318                        min_binding_size: wgpu::BufferSize::new(
319                            std::mem::size_of::<EdgeObjectUniform>() as u64,
320                        ),
321                    },
322                    count: None,
323                }],
324            });
325        let edge_object_buffer =
326            create_edge_object_buffer(device, edge_object_stride, INITIAL_INSTANCE_CAPACITY);
327        let edge_object_bind_group =
328            create_edge_object_bind_group(device, &edge_object_layout, &edge_object_buffer);
329        let pipeline_layout = device.create_pipeline_layout(&wgpu::PipelineLayoutDescriptor {
330            label: Some("sim-engine retained 3D mesh pipeline layout"),
331            bind_group_layouts: &[Some(&camera_layout)],
332            immediate_size: 0,
333        });
334        let pipeline = create_surface_pipelines(
335            device,
336            format,
337            &pipeline_layout,
338            &shader,
339            SurfaceLayout {
340                clipped: false,
341                textured: false,
342                colored: false,
343            },
344        );
345        let clipped_surface_pipeline = create_surface_pipelines(
346            device,
347            format,
348            &pipeline_layout,
349            &shader,
350            SurfaceLayout {
351                clipped: true,
352                textured: false,
353                colored: false,
354            },
355        );
356        let edge_pipeline_layout = device.create_pipeline_layout(&wgpu::PipelineLayoutDescriptor {
357            label: Some("sim-engine 3D edge pipeline layout"),
358            bind_group_layouts: &[Some(&camera_layout), Some(&edge_object_layout)],
359            immediate_size: 0,
360        });
361        let visible_edge_pipeline = create_edge_pipeline(
362            device,
363            &shader,
364            &edge_pipeline_layout,
365            format,
366            wgpu::CompareFunction::LessEqual,
367            "mesh3d_visible_edge_fs_main",
368            "sim-engine visible 3D edge pipeline",
369            false,
370        );
371        let hidden_edge_pipeline = create_edge_pipeline(
372            device,
373            &shader,
374            &edge_pipeline_layout,
375            format,
376            wgpu::CompareFunction::Greater,
377            "mesh3d_hidden_edge_fs_main",
378            "sim-engine hidden 3D edge pipeline",
379            false,
380        );
381        let clipped_visible_edge_pipeline = create_edge_pipeline(
382            device,
383            &shader,
384            &edge_pipeline_layout,
385            format,
386            wgpu::CompareFunction::LessEqual,
387            "mesh3d_visible_edge_fs_main",
388            "sim-engine canonical visible 3D edge pipeline",
389            true,
390        );
391        let clipped_hidden_edge_pipeline = create_edge_pipeline(
392            device,
393            &shader,
394            &edge_pipeline_layout,
395            format,
396            wgpu::CompareFunction::Greater,
397            "mesh3d_hidden_edge_fs_main",
398            "sim-engine canonical hidden 3D edge pipeline",
399            true,
400        );
401        Self {
402            dynamic_scratch: dynamic::DynamicMesh3dScratch::default(),
403            textures: MeshTextureRenderer::new(device, format, &camera_layout),
404            pipeline,
405            colored_pipeline: create_surface_pipelines(
406                device,
407                format,
408                &pipeline_layout,
409                &shader,
410                SurfaceLayout {
411                    clipped: false,
412                    textured: false,
413                    colored: true,
414                },
415            ),
416            colored_clipped_pipeline: create_surface_pipelines(
417                device,
418                format,
419                &pipeline_layout,
420                &shader,
421                SurfaceLayout {
422                    clipped: true,
423                    textured: false,
424                    colored: true,
425                },
426            ),
427            clipped_color_buffer: None,
428            clipped_color_capacity: 0,
429            clipped_lighting_buffer: None,
430            clipped_lighting_capacity: 0,
431            clipped_surface_pipeline,
432            clipped_surface_buffer: None,
433            clipped_surface_capacity: 0,
434            clipped_surface_objects: Vec::new(),
435            clipped_visible_edge_pipeline,
436            clipped_hidden_edge_pipeline,
437            clipped_edge_buffer: None,
438            clipped_edge_capacity: 0,
439            visible_edge_pipeline,
440            hidden_edge_pipeline,
441            camera_uniform_buffer,
442            camera_bind_group,
443            instance_buffer: create_instance_buffer(device, INITIAL_INSTANCE_CAPACITY),
444            instance_capacity: INITIAL_INSTANCE_CAPACITY,
445            instances: Vec::new(),
446            edge_object_layout,
447            edge_object_bind_group,
448            edge_object_buffer,
449            edge_object_stride,
450            edge_object_capacity: INITIAL_INSTANCE_CAPACITY,
451            edge_object_bytes: Vec::new(),
452        }
453    }
454
455    fn ensure_frame_capacity(
456        &mut self,
457        device: &wgpu::Device,
458        object_count: usize,
459    ) -> Result<(), Mesh3dRenderError> {
460        let instance_capacity = if object_count > self.instance_capacity {
461            Some(
462                object_count
463                    .checked_next_power_of_two()
464                    .filter(|capacity| buffer_capacity_fits::<MeshInstanceGpu>(device, *capacity))
465                    .ok_or(Mesh3dRenderError::InstanceCapacityTooLarge)?,
466            )
467        } else {
468            None
469        };
470        let edge_capacity = if object_count > self.edge_object_capacity {
471            Some(
472                object_count
473                    .checked_next_power_of_two()
474                    .filter(|capacity| {
475                        capacity
476                            .checked_mul(self.edge_object_stride)
477                            .is_some_and(|bytes| {
478                                bytes as u64 <= device.limits().max_buffer_size
479                                    && bytes <= u32::MAX as usize
480                            })
481                    })
482                    .ok_or(Mesh3dRenderError::InstanceCapacityTooLarge)?,
483            )
484        } else {
485            None
486        };
487        let required_edge_bytes = object_count
488            .checked_mul(self.edge_object_stride)
489            .ok_or(Mesh3dRenderError::InstanceCapacityTooLarge)?;
490        let replace_instance_staging = self.instances.capacity() < object_count;
491        let replace_edge_staging = self.edge_object_bytes.capacity() < required_edge_bytes;
492        if instance_capacity.is_none()
493            && edge_capacity.is_none()
494            && !replace_instance_staging
495            && !replace_edge_staging
496        {
497            return Ok(());
498        }
499        let replacement_instances = if replace_instance_staging {
500            let mut instances = Vec::new();
501            instances
502                .try_reserve_exact(object_count)
503                .map_err(|_| Mesh3dRenderError::InstanceCapacityTooLarge)?;
504            Some(instances)
505        } else {
506            None
507        };
508        let replacement_edge_bytes = if replace_edge_staging {
509            let mut bytes = Vec::new();
510            bytes
511                .try_reserve_exact(required_edge_bytes)
512                .map_err(|_| Mesh3dRenderError::InstanceCapacityTooLarge)?;
513            Some(bytes)
514        } else {
515            None
516        };
517        let replacement_instance_buffer =
518            instance_capacity.map(|capacity| create_instance_buffer(device, capacity));
519        let replacement_edge_resources = edge_capacity.map(|capacity| {
520            let buffer = create_edge_object_buffer(device, self.edge_object_stride, capacity);
521            let bind_group =
522                create_edge_object_bind_group(device, &self.edge_object_layout, &buffer);
523            (buffer, bind_group)
524        });
525        // No fallible operation remains after the first renderer field changes.
526        if let Some(instances) = replacement_instances {
527            self.instances = instances;
528        }
529        if let (Some(capacity), Some(buffer)) = (instance_capacity, replacement_instance_buffer) {
530            self.instance_buffer = buffer;
531            self.instance_capacity = capacity;
532        }
533        if let Some(bytes) = replacement_edge_bytes {
534            self.edge_object_bytes = bytes;
535        }
536        if let (Some(capacity), Some((buffer, bind_group))) =
537            (edge_capacity, replacement_edge_resources)
538        {
539            self.edge_object_buffer = buffer;
540            self.edge_object_bind_group = bind_group;
541            self.edge_object_capacity = capacity;
542        }
543        Ok(())
544    }
545}
546
547/// Immutable retained GPU buffers for one validated [`Mesh3d`].
548///
549/// The resource belongs to the renderer that created it and retains the core
550/// topology for explicit device-loss restoration.
551#[derive(Clone)]
552pub struct RetainedMesh3d {
553    renderer_identity: Arc<()>,
554    vertex_buffer: Arc<wgpu::Buffer>,
555    index_buffer: Option<Arc<wgpu::Buffer>>,
556    edge_buffer: Option<Arc<wgpu::Buffer>>,
557    texture_coordinate_buffer: Option<Arc<wgpu::Buffer>>,
558    color_buffer: Option<Arc<wgpu::Buffer>>,
559    normal_buffer: Option<Arc<wgpu::Buffer>>,
560    material: Option<TextureMaterial3d>,
561    source: Mesh3d,
562    index_count: u32,
563    edge_count: u32,
564    gpu_allocation_bytes: usize,
565    budget: Mesh3dUploadBudget,
566    allocation: Mesh3dUploadLayout,
567}
568
569impl RetainedMesh3d {
570    /// Returns a material-free handle sharing the same immutable topology and
571    /// attribute buffers. No CPU geometry is copied and no GPU resource is
572    /// allocated or uploaded. Existing handles and scene objects are unchanged.
573    /// UVs, normals, vertex colors, display edges and reserved capacity remain
574    /// available for later rebinding. Device provenance is unchanged; a stale
575    /// handle still needs restoration before rendering on a replacement device.
576    pub fn without_material(&self) -> Self {
577        let mut mesh = self.clone();
578        mesh.material = None;
579        mesh
580    }
581
582    /// Returns the optional shared texture/filter/tint material for this handle.
583    /// Mesh clones share buffers while retaining independent material selection.
584    pub const fn material(&self) -> Option<&TextureMaterial3d> {
585        self.material.as_ref()
586    }
587    /// Returns this revision's upload and restoration capacity limits.
588    pub const fn budget(&self) -> Mesh3dUploadBudget {
589        self.budget
590    }
591    /// Returns the immutable core topology retained for recovery.
592    pub fn source(&self) -> &Mesh3d {
593        &self.source
594    }
595
596    /// Returns the retained triangle count.
597    pub fn triangle_count(&self) -> usize {
598        self.source.triangle_count()
599    }
600
601    /// Returns allocated vertex, optional UV, triangle-index and display-edge
602    /// buffer capacity bytes, including dynamic reserve beyond live geometry.
603    /// Shared material texels are reported separately by `Texture3d`.
604    pub const fn gpu_allocation_bytes(&self) -> usize {
605        self.gpu_allocation_bytes
606    }
607
608    /// Returns CPU topology/UV bytes retained for device-loss restoration.
609    /// Shared material pixels are reported separately by `Texture3d`.
610    pub fn recovery_memory_bytes(&self) -> usize {
611        self.source.recovery_memory_bytes()
612    }
613}
614
615#[path = "mesh3d_dynamic.rs"]
616mod dynamic;
617#[path = "mesh3d_objects.rs"]
618mod objects;
619#[path = "mesh3d_upload.rs"]
620mod upload;
621pub use dynamic::{
622    DynamicMesh3dBudget, DynamicMesh3dBudgetResource, DynamicMesh3dError, DynamicMesh3dUpdateReport,
623};
624pub use objects::{
625    Mesh3dInstance, Object3dId, Scene3d, Scene3dBudget, Scene3dBudgetResource, Scene3dError,
626    Scene3dMeshUpdateReport, Scene3dStatistics,
627};
628pub use upload::{Mesh3dUploadBudget, Mesh3dUploadBudgetResource, Mesh3dUploadReport};
629
630/// Offscreen color and depth attachments for stereometry rendering.
631pub struct RenderTarget3d {
632    renderer_identity: Arc<()>,
633    color: RenderTarget2d,
634    _depth_texture: wgpu::Texture,
635    depth_view: wgpu::TextureView,
636    logical_viewport: LogicalViewport,
637    pixels_per_logical: PhysicalPerLogical,
638}
639
640impl RenderTarget3d {
641    /// Returns target width in physical texture pixels.
642    pub fn width(&self) -> u32 {
643        self.color.width()
644    }
645
646    /// Returns target height in physical texture pixels.
647    pub fn height(&self) -> u32 {
648        self.color.height()
649    }
650
651    /// Returns the logical viewport represented by the offscreen texture.
652    pub const fn logical_viewport(&self) -> LogicalViewport {
653        self.logical_viewport
654    }
655
656    /// Returns target texels per logical screen pixel.
657    pub const fn pixels_per_logical(&self) -> PhysicalPerLogical {
658        self.pixels_per_logical
659    }
660
661    /// Returns the composable 2D color attachment.
662    pub const fn color_target(&self) -> &RenderTarget2d {
663        &self.color
664    }
665
666    /// Returns nominal color plus depth texel-storage bytes, excluding opaque
667    /// backend alignment and resource metadata.
668    pub fn allocation_bytes(&self) -> usize {
669        self.color.allocation_bytes().saturating_add(
670            (self.width() as usize)
671                .saturating_mul(self.height() as usize)
672                .saturating_mul(4),
673        )
674    }
675}
676
677fn validate_mesh_style(mesh: &RetainedMesh3d, style: MeshStyle3d) -> Result<(), Scene3dError> {
678    validate_mesh_source_style(mesh.source(), style)
679}
680
681fn validate_mesh_source_style(source: &Mesh3d, style: MeshStyle3d) -> Result<(), Scene3dError> {
682    let has_surface = style.surface_style().is_some() && source.triangle_count() > 0;
683    if has_surface
684        && style
685            .surface_style()
686            .is_some_and(|surface| surface.lighting() == SurfaceLighting3d::Lambert)
687        && source.normals().is_empty()
688    {
689        return Err(Scene3dError::MissingNormals);
690    }
691    let has_wireframe = style.wireframe_style().is_some() && !source.display_edges().is_empty();
692    (has_surface || has_wireframe)
693        .then_some(())
694        .ok_or(Scene3dError::StyleHasNoMatchingGeometry)
695}
696
697fn validate_scene3d_transform(transform: Transform3d) -> Result<(), Scene3dError> {
698    transform
699        .model_rows()
700        .ok()
701        .is_some_and(|rows| rows.into_iter().flatten().all(is_portable_shader_source))
702        .then_some(())
703        .ok_or(Scene3dError::InvalidTransform)
704}
705
706/// Resource creation or ownership failure for retained 3D rendering.
707#[derive(Debug, Clone, Copy, PartialEq)]
708pub enum Mesh3dResourceError {
709    /// Texture creation, restoration or material validation failed.
710    Texture(Texture3dError),
711    /// A retained UV is subnormal and outside the portable shader envelope.
712    NonPortableTextureCoordinate,
713    /// Explicit mesh upload limits must be nonzero.
714    InvalidBudget,
715    /// The replaced resource belongs to another logical renderer generation.
716    RendererMismatch,
717    /// Upload limits rejected bytes before caller-scale allocation.
718    BudgetExceeded {
719        /// Rejected byte category.
720        resource: Mesh3dUploadBudgetResource,
721        /// Configured maximum.
722        limit: usize,
723        /// Required bytes.
724        actual: usize,
725    },
726    /// Vertex, index, or edge data exceeds the active device's buffer-size limit.
727    CapacityTooLarge,
728    /// At least one retained model-space vertex is outside the portable shader envelope.
729    NonPortableVertex,
730    /// Host staging memory could not be reserved after capacity preflight.
731    HostAllocationFailed {
732        /// Bytes requested for the rejected staging buffer.
733        requested_bytes: u64,
734    },
735    /// Color/depth target creation failed.
736    Target(RenderTargetError),
737    /// Physical texture and logical viewport aspect ratios differ.
738    InvalidViewportAspect,
739}
740
741impl fmt::Display for Mesh3dResourceError {
742    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
743        match self {
744            Self::Texture(error) => write!(formatter, "{error}"),
745            Self::NonPortableTextureCoordinate => write!(
746                formatter,
747                "3D texture coordinate is outside the portable shader envelope"
748            ),
749            Self::InvalidBudget => write!(formatter, "3D mesh upload limits must be nonzero"),
750            Self::RendererMismatch => {
751                write!(formatter, "3D mesh belongs to another renderer generation")
752            }
753            Self::BudgetExceeded {
754                resource,
755                limit,
756                actual,
757            } => write!(
758                formatter,
759                "3D mesh {resource:?} budget exceeded: {actual} > {limit}"
760            ),
761            Self::CapacityTooLarge => write!(formatter, "3D mesh exceeds GPU buffer limits"),
762            Self::NonPortableVertex => write!(
763                formatter,
764                "3D mesh contains a vertex outside the portable shader envelope"
765            ),
766            Self::HostAllocationFailed { requested_bytes } => write!(
767                formatter,
768                "3D mesh could not reserve a {requested_bytes}-byte host staging buffer"
769            ),
770            Self::Target(error) => write!(formatter, "3D target creation failed: {error}"),
771            Self::InvalidViewportAspect => write!(
772                formatter,
773                "3D target texture and logical viewport must have one aspect ratio"
774            ),
775        }
776    }
777}
778
779impl Error for Mesh3dResourceError {}
780
781/// Failure while encoding a depth-tested 3D scene.
782#[derive(Debug, Clone, Copy, PartialEq, Eq)]
783pub enum Mesh3dRenderError {
784    /// Transient Blend ordering capacity exceeded its explicit byte ceiling.
785    SortingBudgetExceeded {
786        /// Configured sorting-array byte limit.
787        limit: usize,
788        /// Required or actually reserved bytes.
789        actual: usize,
790    },
791    /// A mesh or target belongs to another renderer/device identity.
792    RendererMismatch,
793    /// Model/camera inputs or their arithmetic leave the portable GPU envelope.
794    InvalidGeometryTransform,
795    /// A surface triangle has clipping topology or a projected orientation
796    /// that is not stable across portable shader arithmetic.
797    UnportableSurfaceTopology,
798    /// The visible per-frame object buffers exceed a GPU or host capacity.
799    InstanceCapacityTooLarge,
800    /// Camera projection aspect does not match the target logical viewport.
801    CameraTargetAspectMismatch,
802    /// Edge clipping, projection, or style arithmetic is not portable for this target.
803    InvalidEdgeProjection,
804    /// A visible object's transform, surface or edge proof failed. The stable
805    /// handle identifies that exact object even when several share one mesh.
806    ObjectFailure {
807        /// Complete scene-provenance-bearing object handle.
808        object_id: Object3dId,
809        /// Source-context or object-level numerical validation failure.
810        reason: Mesh3dObjectError,
811    },
812    /// Generated clipping topology exceeds a caller budget or device capacity.
813    GeneratedGeometryCapacityTooLarge,
814    /// Exact retained plus generated surface submissions exceed the caller limit.
815    SurfaceTriangleBudgetExceeded {
816        /// Configured maximum surface submissions for this frame.
817        limit: usize,
818        /// Submitted count reached by authoritative preflight before rejection.
819        actual: usize,
820    },
821}
822
823/// Instance-local numerical rejection category from authoritative 3D preflight.
824#[derive(Debug, Clone, Copy, PartialEq, Eq)]
825pub enum Mesh3dObjectError {
826    /// Model/camera arithmetic cannot be represented portably.
827    InvalidGeometryTransform,
828    /// Clipped surface topology or projected orientation remains ambiguous.
829    UnportableSurfaceTopology,
830    /// Display-edge clipping or extrusion cannot be represented portably.
831    InvalidEdgeProjection,
832    /// A source surface triangle failed authoritative validation. The index is
833    /// zero-based in the source mesh, not in a generated clipping fan.
834    SurfaceTriangle {
835        /// Original index into `Mesh3d::triangle_indices().chunks_exact(3)`.
836        triangle_index: usize,
837        /// Specific arithmetic or topology proof that failed.
838        reason: Mesh3dSurfaceError,
839    },
840    /// A source vertex not referenced by any surface triangle failed validation.
841    Vertex {
842        /// Zero-based position in the source mesh vertex array.
843        vertex_index: usize,
844        /// Specific arithmetic or clip-classification failure.
845        reason: Mesh3dSurfaceError,
846    },
847}
848
849impl Mesh3dRenderError {
850    fn for_object(self, object_id: Object3dId) -> Self {
851        let reason = match self {
852            Self::InvalidGeometryTransform => Mesh3dObjectError::InvalidGeometryTransform,
853            Self::UnportableSurfaceTopology => Mesh3dObjectError::UnportableSurfaceTopology,
854            Self::InvalidEdgeProjection => Mesh3dObjectError::InvalidEdgeProjection,
855            _ => return self,
856        };
857        Self::ObjectFailure { object_id, reason }
858    }
859
860    /// Returns an offending object when the failure is uniquely instance-local.
861    /// Ownership, camera/target mismatch and aggregate capacity errors return
862    /// `None`; they must not be attributed to an arbitrary visible object.
863    pub const fn object_id(self) -> Option<Object3dId> {
864        match self {
865            Self::ObjectFailure { object_id, .. } => Some(object_id),
866            _ => None,
867        }
868    }
869
870    /// Returns the original source triangle index for a surface-local failure.
871    /// Unused-vertex, edge, scene capacity and resource ownership failures have
872    /// no source triangle and return `None`.
873    pub const fn source_triangle_index(self) -> Option<usize> {
874        match self {
875            Self::ObjectFailure {
876                reason: Mesh3dObjectError::SurfaceTriangle { triangle_index, .. },
877                ..
878            } => Some(triangle_index),
879            _ => None,
880        }
881    }
882
883    /// Returns the source vertex index for failures without a surface triangle.
884    /// A referenced vertex is attributed to its first source triangle instead.
885    pub const fn source_vertex_index(self) -> Option<usize> {
886        match self {
887            Self::ObjectFailure {
888                reason: Mesh3dObjectError::Vertex { vertex_index, .. },
889                ..
890            } => Some(vertex_index),
891            _ => None,
892        }
893    }
894
895    /// Returns the specific source-surface or vertex rejection reason, when available.
896    pub const fn surface_reason(self) -> Option<Mesh3dSurfaceError> {
897        match self {
898            Self::ObjectFailure {
899                reason:
900                    Mesh3dObjectError::SurfaceTriangle { reason, .. }
901                    | Mesh3dObjectError::Vertex { reason, .. },
902                ..
903            } => Some(reason),
904            _ => None,
905        }
906    }
907}
908
909impl fmt::Display for Mesh3dRenderError {
910    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
911        match self {
912            Self::SortingBudgetExceeded { limit, actual } => write!(
913                formatter,
914                "3D sorting storage {actual} exceeds {limit} bytes"
915            ),
916            Self::RendererMismatch => {
917                write!(formatter, "3D scene resource belongs to another renderer")
918            }
919            Self::InvalidGeometryTransform => {
920                write!(
921                    formatter,
922                    "3D transform is outside the portable GPU geometry envelope"
923                )
924            }
925            Self::UnportableSurfaceTopology => write!(
926                formatter,
927                "3D surface clipping or projected triangle topology is outside the portable GPU envelope"
928            ),
929            Self::InstanceCapacityTooLarge => write!(
930                formatter,
931                "visible 3D objects exceed per-frame GPU or host buffer capacity"
932            ),
933            Self::CameraTargetAspectMismatch => write!(
934                formatter,
935                "3D camera aspect does not match the target logical viewport"
936            ),
937            Self::InvalidEdgeProjection => write!(
938                formatter,
939                "3D edge clipping or screen-space arithmetic is outside the portable GPU envelope"
940            ),
941            Self::ObjectFailure { object_id, reason } => write!(
942                formatter,
943                "3D object {} failed preflight: {reason:?}",
944                object_id.get()
945            ),
946            Self::GeneratedGeometryCapacityTooLarge => write!(
947                formatter,
948                "generated 3D surface topology exceeds frame or device capacity"
949            ),
950            Self::SurfaceTriangleBudgetExceeded { limit, actual } => write!(
951                formatter,
952                "3D surface submissions {actual} exceed frame triangle limit {limit}"
953            ),
954        }
955    }
956}
957
958impl Error for Mesh3dRenderError {}
959
960/// CPU-side result of one depth-tested offscreen 3D draw.
961#[derive(Debug, Clone, Copy, PartialEq, Eq)]
962pub struct Mesh3dRenderReport {
963    object_count: usize,
964    triangle_count: usize,
965    edge_count: usize,
966    render_pass_count: usize,
967    draw_call_count: usize,
968    upload: Duration,
969    preflight_duration: Duration,
970    staging_upload_duration: Duration,
971    encode_submit: Duration,
972    preflight: Mesh3dPreflightReport,
973    gpu_timing_id: Option<GpuTimingId>,
974    uploaded_bytes: usize,
975    upload_calls: usize,
976    buffer_allocation_count: usize,
977    retained_frame_cpu_bytes: usize,
978    retained_frame_gpu_bytes: usize,
979    staging_capacity_bytes: usize,
980    peak_frame_cpu_bytes: usize,
981    peak_frame_gpu_bytes: usize,
982}
983
984impl Mesh3dRenderReport {
985    /// Returns exact clipping/generated-work counts from authoritative preflight.
986    pub const fn preflight(self) -> Mesh3dPreflightReport {
987        self.preflight
988    }
989    /// Returns independently transformed visible objects submitted for drawing.
990    ///
991    /// Objects wholly outside a common frustum plane remain submitted objects
992    /// even when rasterization produces no fragments. See `preflight()` for
993    /// explicitly clipped and discarded source-triangle counts.
994    pub const fn object_count(self) -> usize {
995        self.object_count
996    }
997
998    /// Returns indexed and generated triangles submitted across every object.
999    pub const fn triangle_count(self) -> usize {
1000        self.triangle_count
1001    }
1002
1003    /// Returns explicit mathematical edges submitted for depth classification.
1004    pub const fn edge_count(self) -> usize {
1005        self.edge_count
1006    }
1007
1008    /// Returns GPU render passes encoded for the retained scene.
1009    ///
1010    /// A successful draw always encodes one pass because clearing the color
1011    /// and depth attachments is observable even when the scene is empty.
1012    pub const fn render_pass_count(self) -> usize {
1013        self.render_pass_count
1014    }
1015
1016    /// Returns surface, hidden-edge, and visible-edge draw calls actually
1017    /// encoded for the retained scene.
1018    pub const fn draw_call_count(self) -> usize {
1019        self.draw_call_count
1020    }
1021
1022    /// Returns CPU time spent validating, staging, growing reusable buffers,
1023    /// and enqueuing camera/instance uploads.
1024    pub const fn upload(self) -> Duration {
1025        self.upload
1026    }
1027
1028    /// CPU time in authoritative source validation, clipping and draw ordering.
1029    pub const fn preflight_duration(self) -> Duration {
1030        self.preflight_duration
1031    }
1032
1033    /// CPU time after preflight spent preparing/growing staging and GPU buffers
1034    /// and enqueueing writes. Together with preflight this forms `upload()`;
1035    /// none of these CPU measurements represents GPU execution time.
1036    pub const fn staging_upload_duration(self) -> Duration {
1037        self.staging_upload_duration
1038    }
1039
1040    /// Correlation key for optional asynchronous GPU pass timing. `None` means
1041    /// disabled/unavailable timing or a full ring, not a zero-duration pass.
1042    pub const fn gpu_timing_id(self) -> Option<GpuTimingId> {
1043        self.gpu_timing_id
1044    }
1045
1046    /// Actual camera, instance, edge-uniform and generated-stream bytes written
1047    /// for this draw. Retained topology/texture updates and diagnostic timestamp
1048    /// resolution/readback are separate operations and are excluded.
1049    pub const fn uploaded_bytes(self) -> usize {
1050        self.uploaded_bytes
1051    }
1052
1053    /// Number of nonempty queue buffer writes corresponding to `uploaded_bytes`.
1054    pub const fn upload_calls(self) -> usize {
1055        self.upload_calls
1056    }
1057
1058    /// Reusable frame GPU buffers newly allocated by this draw. Excludes renderer
1059    /// initialization, immutable scene resources, bind groups and driver internals.
1060    pub const fn buffer_allocation_count(self) -> usize {
1061        self.buffer_allocation_count
1062    }
1063
1064    /// Retained CPU instance, edge-uniform and clipped-object array capacity after
1065    /// the draw. Excludes scene sources, dynamic-update scratch and backend memory.
1066    pub const fn retained_frame_cpu_bytes(self) -> usize {
1067        self.retained_frame_cpu_bytes
1068    }
1069
1070    /// Nominal reusable camera/instance/edge/generated GPU buffer bytes after this
1071    /// draw. Render targets, scene resources and timestamp diagnostics are excluded.
1072    pub const fn retained_frame_gpu_bytes(self) -> usize {
1073        self.retained_frame_gpu_bytes
1074    }
1075
1076    /// Live CPU frame-array capacities during encoding: retained frame arrays
1077    /// plus this draw's temporary clipping/color/lighting/edge/sorting arrays.
1078    pub const fn staging_capacity_bytes(self) -> usize {
1079        self.staging_capacity_bytes
1080    }
1081
1082    /// Maximum simultaneous old/new frame-array capacity during preparation.
1083    /// Excludes caller data, backend allocations and allocator metadata.
1084    pub const fn peak_frame_cpu_bytes(self) -> usize {
1085        self.peak_frame_cpu_bytes
1086    }
1087
1088    /// Old reusable GPU buffers plus newly allocated replacements for this draw;
1089    /// driver retirement/in-flight allocations are not inferred from this count.
1090    pub const fn peak_frame_gpu_bytes(self) -> usize {
1091        self.peak_frame_gpu_bytes
1092    }
1093
1094    /// Returns CPU time spent encoding and submitting the pass.
1095    pub const fn encode_submit(self) -> Duration {
1096        self.encode_submit
1097    }
1098}
1099
1100/// Result of atomically migrating a retained 3D scene to the active renderer device.
1101#[derive(Debug, Clone, Copy, PartialEq, Eq)]
1102pub struct Scene3dRestoreReport {
1103    object_count: usize,
1104    migrated_object_count: usize,
1105    restored_mesh_count: usize,
1106    restored_gpu_bytes: usize,
1107    restored_texture_count: usize,
1108    restored_texture_bytes: usize,
1109}
1110
1111impl Scene3dRestoreReport {
1112    /// Returns distinct shared textures recreated on the active device.
1113    pub const fn restored_texture_count(self) -> usize {
1114        self.restored_texture_count
1115    }
1116    /// Returns nominal texel bytes recreated across distinct shared textures.
1117    pub const fn restored_texture_bytes(self) -> usize {
1118        self.restored_texture_bytes
1119    }
1120    /// Returns all scene objects whose stable IDs and visual state were preserved.
1121    pub const fn object_count(self) -> usize {
1122        self.object_count
1123    }
1124
1125    /// Returns objects whose stale mesh reference was replaced in this call.
1126    pub const fn migrated_object_count(self) -> usize {
1127        self.migrated_object_count
1128    }
1129
1130    /// Returns distinct retained mesh resources recreated on the active device.
1131    pub const fn restored_mesh_count(self) -> usize {
1132        self.restored_mesh_count
1133    }
1134
1135    /// Returns total GPU bytes represented by the recreated distinct meshes.
1136    pub const fn restored_gpu_bytes(self) -> usize {
1137        self.restored_gpu_bytes
1138    }
1139}
1140
1141impl WgpuRenderer {
1142    /// Uploads validated immutable topology into retained GPU buffers.
1143    ///
1144    /// Counts, byte arithmetic, draw-count representation, and active-device
1145    /// buffer limits are checked before conversion staging allocation. Host
1146    /// staging reservation failure is returned explicitly; GPU allocation
1147    /// itself follows wgpu's device-error model.
1148    pub fn create_mesh3d(&self, source: Mesh3d) -> Result<RetainedMesh3d, Mesh3dResourceError> {
1149        create_retained_mesh(
1150            &self.device,
1151            &self.queue,
1152            Arc::clone(&self.renderer_identity),
1153            source,
1154        )
1155    }
1156
1157    /// Restores retained topology and its complete optional texture material
1158    /// onto this renderer after device replacement. Attribute/reserved buffer
1159    /// capacities, committed mip bytes/options, filtering, tint, UV transform,
1160    /// addressing and opaque/alpha-capable rebinding policy are preserved.
1161    /// Source handles remain unchanged. Separate calls restore separate GPU
1162    /// resources; use `restore_scene3d` to deduplicate shared scene resources.
1163    pub fn restore_mesh3d(
1164        &self,
1165        source: &RetainedMesh3d,
1166    ) -> Result<RetainedMesh3d, Mesh3dResourceError> {
1167        restore_retained_mesh(
1168            &self.device,
1169            &self.queue,
1170            Arc::clone(&self.renderer_identity),
1171            &self.mesh3d_renderer.textures.layout,
1172            source,
1173        )
1174    }
1175
1176    /// Atomically restores every stale retained mesh referenced by a 3D scene.
1177    ///
1178    /// Distinct shared mesh and texture resources are uploaded once. Per-handle
1179    /// texture/filter/tint choices remain independent when topology is shared.
1180    /// Object IDs, insertion
1181    /// order, transforms, styles, visibility, scene provenance, and the next ID
1182    /// remain unchanged. If any capacity or host-staging allocation fails, the
1183    /// original scene is not modified. Targets remain separate resources and
1184    /// must be restored with [`WgpuRenderer::restore_render_target3d`].
1185    pub fn restore_scene3d(
1186        &self,
1187        scene: &mut Scene3d,
1188    ) -> Result<Scene3dRestoreReport, Mesh3dResourceError> {
1189        restore_scene3d_resources(
1190            &self.device,
1191            &self.queue,
1192            &self.mesh3d_renderer.textures.layout,
1193            Arc::clone(&self.renderer_identity),
1194            scene,
1195        )
1196    }
1197
1198    /// Creates color/depth attachments for an explicit logical viewport.
1199    ///
1200    /// `width` and `height` are physical target texels. Their aspect must match
1201    /// `logical_viewport`; the resulting texels-per-logical-pixel ratio controls
1202    /// wireframe width independently of the window DPI scale.
1203    pub fn create_render_target3d(
1204        &self,
1205        width: u32,
1206        height: u32,
1207        logical_viewport: LogicalViewport,
1208    ) -> Result<RenderTarget3d, Mesh3dResourceError> {
1209        let pixels_per_logical = target_pixels_per_logical(width, height, logical_viewport)
1210            .ok_or(Mesh3dResourceError::InvalidViewportAspect)?;
1211        let color = self
1212            .create_render_target(width, height)
1213            .map_err(Mesh3dResourceError::Target)?;
1214        let depth_texture = create_depth_texture(&self.device, width, height);
1215        let depth_view = depth_texture.create_view(&wgpu::TextureViewDescriptor::default());
1216        Ok(RenderTarget3d {
1217            renderer_identity: Arc::clone(&self.renderer_identity),
1218            color,
1219            _depth_texture: depth_texture,
1220            depth_view,
1221            logical_viewport,
1222            pixels_per_logical,
1223        })
1224    }
1225
1226    /// Restores empty color/depth attachments with the source dimensions.
1227    pub fn restore_render_target3d(
1228        &self,
1229        source: &RenderTarget3d,
1230    ) -> Result<RenderTarget3d, Mesh3dResourceError> {
1231        self.create_render_target3d(source.width(), source.height(), source.logical_viewport())
1232    }
1233
1234    /// Draws retained opaque/masked surfaces, sorted blended surfaces, then edges
1235    /// into a reusable premultiplied color/depth target.
1236    ///
1237    /// Object insertion order does not determine visibility. Every surface
1238    /// writes and tests hardware depth. Model transforms are uploaded through a
1239    /// reusable instance buffer. Wholly inside objects retain their indexed
1240    /// topology; crossing surfaces use bounded homogeneous CPU clipping against
1241    /// all six frustum planes. Ambiguous classification/orientation produces an
1242    /// object-attributed error. Explicit display edges retain their complete
1243    /// interval-validated homogeneous shader clipper.
1244    pub fn render_scene3d_to_target(
1245        &mut self,
1246        target: &RenderTarget3d,
1247        scene: &Scene3d,
1248        camera: Camera3d,
1249    ) -> Result<Mesh3dRenderReport, Mesh3dRenderError> {
1250        self.render_scene3d_to_target_with_budget(
1251            target,
1252            scene,
1253            camera,
1254            Mesh3dRenderBudget::default(),
1255        )
1256    }
1257
1258    /// Validates every visible object and exact submitted/generated work without
1259    /// changing target pixels, retained resources or submitting GPU work.
1260    ///
1261    /// This is the same authoritative preflight used by rendering. Private
1262    /// bounded scratch may be allocated; the report is not a reusable draw
1263    /// authorization after the scene, target or camera changes.
1264    /// [`Mesh3dRenderBudget::surface_policy`] controls filled surfaces only.
1265    /// Native mode reports no CPU clipped/discarded source counts.
1266    pub fn validate_scene3d_for_target(
1267        &self,
1268        target: &RenderTarget3d,
1269        scene: &Scene3d,
1270        camera: Camera3d,
1271        budget: Mesh3dRenderBudget,
1272    ) -> Result<Mesh3dPreflightReport, Mesh3dRenderError> {
1273        self.mesh3d_renderer
1274            .preflight_scene3d(
1275                &self.device,
1276                &self.renderer_identity,
1277                target,
1278                scene,
1279                camera,
1280                budget,
1281            )
1282            .map(|(_, frame)| frame.report)
1283    }
1284
1285    /// Draws a scene with explicit surface policy and submitted/generated limits.
1286    ///
1287    /// All validation, generated counts and host/GPU capacity checks complete
1288    /// before the first GPU write or target mutation. Numerical ambiguity is
1289    /// attributed to the exact visible object; aggregate capacity remains a
1290    /// scene-level error. Wholly inside objects retain their indexed GPU path.
1291    /// With [`SurfaceRasterization3d::Native`], all filled surfaces keep their
1292    /// original indices and hardware clipping defines boundary coverage. Finite
1293    /// shader arithmetic and independent mathematical-edge proofs still apply.
1294    pub fn render_scene3d_to_target_with_budget(
1295        &mut self,
1296        target: &RenderTarget3d,
1297        scene: &Scene3d,
1298        camera: Camera3d,
1299        budget: Mesh3dRenderBudget,
1300    ) -> Result<Mesh3dRenderReport, Mesh3dRenderError> {
1301        self.mesh3d_renderer.render_scene3d_with_timing(
1302            &self.device,
1303            &self.queue,
1304            &self.renderer_identity,
1305            target,
1306            scene,
1307            camera,
1308            budget,
1309            Some(&mut self.gpu_timing),
1310        )
1311    }
1312}
1313
1314impl Mesh3dRenderer {
1315    fn retained_frame_cpu_bytes(&self) -> usize {
1316        self.instances
1317            .capacity()
1318            .saturating_mul(std::mem::size_of::<MeshInstanceGpu>())
1319            .saturating_add(self.edge_object_bytes.capacity())
1320            .saturating_add(
1321                self.clipped_surface_objects
1322                    .capacity()
1323                    .saturating_mul(std::mem::size_of::<SurfaceObject>()),
1324            )
1325    }
1326
1327    fn retained_frame_gpu_bytes(&self) -> usize {
1328        [
1329            Some(&self.camera_uniform_buffer),
1330            Some(&self.instance_buffer),
1331            Some(&self.edge_object_buffer),
1332            self.clipped_surface_buffer.as_ref(),
1333            self.clipped_color_buffer.as_ref(),
1334            self.clipped_lighting_buffer.as_ref(),
1335            self.clipped_edge_buffer.as_ref(),
1336        ]
1337        .into_iter()
1338        .flatten()
1339        .fold(0usize, |total, buffer| {
1340            total.saturating_add(buffer.size() as usize)
1341        })
1342    }
1343
1344    fn preflight_scene3d(
1345        &self,
1346        device: &wgpu::Device,
1347        renderer_identity: &Arc<()>,
1348        target: &RenderTarget3d,
1349        scene: &Scene3d,
1350        camera: Camera3d,
1351        budget: Mesh3dRenderBudget,
1352    ) -> Result<(Camera3dUniform, SurfaceFrame), Mesh3dRenderError> {
1353        validate_target_identity(renderer_identity, target)?;
1354        validate_camera_target_aspect(camera, target.logical_viewport())?;
1355        let mut camera_uniform = Camera3dUniform::new(
1356            camera,
1357            target.width(),
1358            target.height(),
1359            target.pixels_per_logical(),
1360        )?;
1361        let capacity = scene
1362            .visible_object_count()
1363            .max(1)
1364            .checked_next_power_of_two()
1365            .ok_or(Mesh3dRenderError::InstanceCapacityTooLarge)?;
1366        if !buffer_capacity_fits::<MeshInstanceGpu>(device, capacity)
1367            || capacity
1368                .checked_mul(self.edge_object_stride)
1369                .is_none_or(|bytes| {
1370                    bytes as u64 > device.limits().max_buffer_size || bytes > u32::MAX as usize
1371                })
1372        {
1373            return Err(Mesh3dRenderError::InstanceCapacityTooLarge);
1374        }
1375        camera_uniform.environment = SurfaceEnvironmentGpu::new(scene, camera);
1376        let order = material::prepare_order(scene, camera, budget)?;
1377        let mut frame = surface::preflight(
1378            renderer_identity,
1379            scene,
1380            camera_uniform,
1381            budget,
1382            device.limits().max_buffer_size,
1383        )?;
1384        frame.report.sorting_capacity_bytes =
1385            order.capacity() * std::mem::size_of::<material::SurfaceDraw>();
1386        frame.order = order;
1387        Ok((camera_uniform, frame))
1388    }
1389    #[cfg(test)]
1390    #[allow(clippy::too_many_arguments)]
1391    fn render_scene3d(
1392        &mut self,
1393        device: &wgpu::Device,
1394        queue: &wgpu::Queue,
1395        renderer_identity: &Arc<()>,
1396        target: &RenderTarget3d,
1397        scene: &Scene3d,
1398        camera: Camera3d,
1399        budget: Mesh3dRenderBudget,
1400    ) -> Result<Mesh3dRenderReport, Mesh3dRenderError> {
1401        self.render_scene3d_with_timing(
1402            device,
1403            queue,
1404            renderer_identity,
1405            target,
1406            scene,
1407            camera,
1408            budget,
1409            None,
1410        )
1411    }
1412
1413    #[allow(clippy::too_many_arguments)]
1414    fn render_scene3d_with_timing(
1415        &mut self,
1416        device: &wgpu::Device,
1417        queue: &wgpu::Queue,
1418        renderer_identity: &Arc<()>,
1419        target: &RenderTarget3d,
1420        scene: &Scene3d,
1421        camera: Camera3d,
1422        budget: Mesh3dRenderBudget,
1423        mut gpu_timing: Option<&mut gpu_timing::GpuTimingCollector>,
1424    ) -> Result<Mesh3dRenderReport, Mesh3dRenderError> {
1425        let upload_started_at = Instant::now();
1426        let previous_frame_cpu_bytes = self.retained_frame_cpu_bytes();
1427        let previous_frame_gpu_bytes = self.retained_frame_gpu_bytes();
1428        let (camera_uniform, surface_frame) =
1429            self.preflight_scene3d(device, renderer_identity, target, scene, camera, budget)?;
1430        let preflight_duration = upload_started_at.elapsed();
1431        let transient_frame_cpu_bytes = surface_frame
1432            .vertices
1433            .capacity()
1434            .saturating_mul(std::mem::size_of::<SurfaceClipVertex>())
1435            .saturating_add(
1436                surface_frame
1437                    .colors
1438                    .capacity()
1439                    .saturating_mul(std::mem::size_of::<MeshColorGpu>()),
1440            )
1441            .saturating_add(
1442                surface_frame
1443                    .lighting
1444                    .capacity()
1445                    .saturating_mul(std::mem::size_of::<SurfaceLightingVertex>()),
1446            )
1447            .saturating_add(
1448                surface_frame
1449                    .edges
1450                    .capacity()
1451                    .saturating_mul(std::mem::size_of::<SurfaceClipEdge>()),
1452            )
1453            .saturating_add(
1454                surface_frame
1455                    .order
1456                    .capacity()
1457                    .saturating_mul(std::mem::size_of::<material::SurfaceDraw>()),
1458            );
1459        let incoming_object_bytes = surface_frame
1460            .objects
1461            .capacity()
1462            .saturating_mul(std::mem::size_of::<SurfaceObject>());
1463        let visible_count = scene.visible_object_count();
1464        let uploaded_bytes = std::mem::size_of::<Camera3dUniform>()
1465            .saturating_add(visible_count.saturating_mul(std::mem::size_of::<MeshInstanceGpu>()))
1466            .saturating_add(visible_count.saturating_mul(self.edge_object_stride))
1467            .saturating_add(surface_frame.report.generated_upload_bytes());
1468        let upload_calls = 1
1469            + usize::from(visible_count > 0) * 2
1470            + usize::from(!surface_frame.vertices.is_empty())
1471            + usize::from(!surface_frame.colors.is_empty())
1472            + usize::from(!surface_frame.lighting.is_empty())
1473            + usize::from(!surface_frame.edges.is_empty());
1474        let replacement_surface_buffer =
1475            if surface_frame.vertices.len() > self.clipped_surface_capacity {
1476                Some(device.create_buffer(&wgpu::BufferDescriptor {
1477                    label: Some("sim-engine clipped 3D surface buffer"),
1478                    size: (surface_frame.vertices.len() * std::mem::size_of::<SurfaceClipVertex>())
1479                        as u64,
1480                    usage: wgpu::BufferUsages::VERTEX | wgpu::BufferUsages::COPY_DST,
1481                    mapped_at_creation: false,
1482                }))
1483            } else {
1484                None
1485            };
1486        let replacement_lighting_buffer = if surface_frame.lighting.len()
1487            > self.clipped_lighting_capacity
1488        {
1489            Some(device.create_buffer(&wgpu::BufferDescriptor {
1490                label: Some("sim-engine canonical 3D lighting attributes"),
1491                size: (surface_frame.lighting.len() * std::mem::size_of::<SurfaceLightingVertex>())
1492                    as u64,
1493                usage: wgpu::BufferUsages::VERTEX | wgpu::BufferUsages::COPY_DST,
1494                mapped_at_creation: false,
1495            }))
1496        } else {
1497            None
1498        };
1499        let replacement_color_buffer = if surface_frame.colors.len() > self.clipped_color_capacity {
1500            Some(device.create_buffer(&wgpu::BufferDescriptor {
1501                label: Some("sim-engine clipped 3D vertex color buffer"),
1502                size: (surface_frame.colors.len() * std::mem::size_of::<MeshColorGpu>()) as u64,
1503                usage: wgpu::BufferUsages::VERTEX | wgpu::BufferUsages::COPY_DST,
1504                mapped_at_creation: false,
1505            }))
1506        } else {
1507            None
1508        };
1509        let replacement_edge_buffer = if surface_frame.edges.len() > self.clipped_edge_capacity {
1510            Some(device.create_buffer(&wgpu::BufferDescriptor {
1511                label: Some("sim-engine canonical clip-space 3D edge buffer"),
1512                size: (surface_frame.edges.len() * std::mem::size_of::<SurfaceClipEdge>()) as u64,
1513                usage: wgpu::BufferUsages::VERTEX | wgpu::BufferUsages::COPY_DST,
1514                mapped_at_creation: false,
1515            }))
1516        } else {
1517            None
1518        };
1519        let replace_instance_buffer = visible_count > self.instance_capacity;
1520        let replace_edge_buffer = visible_count > self.edge_object_capacity;
1521        let replace_instance_staging = visible_count > self.instances.capacity();
1522        let replace_edge_staging =
1523            visible_count * self.edge_object_stride > self.edge_object_bytes.capacity();
1524        let generated_replacements = [
1525            replacement_surface_buffer.as_ref(),
1526            replacement_lighting_buffer.as_ref(),
1527            replacement_color_buffer.as_ref(),
1528            replacement_edge_buffer.as_ref(),
1529        ];
1530        let buffer_allocation_count = generated_replacements.iter().flatten().count()
1531            + usize::from(replace_instance_buffer)
1532            + usize::from(replace_edge_buffer);
1533        let replacement_generated_bytes = generated_replacements
1534            .into_iter()
1535            .flatten()
1536            .fold(0usize, |total, buffer| {
1537                total.saturating_add(buffer.size() as usize)
1538            });
1539        self.ensure_frame_capacity(device, visible_count)?;
1540        let peak_frame_cpu_bytes = previous_frame_cpu_bytes
1541            .saturating_add(transient_frame_cpu_bytes)
1542            .saturating_add(incoming_object_bytes)
1543            .saturating_add(if replace_instance_staging {
1544                self.instances
1545                    .capacity()
1546                    .saturating_mul(std::mem::size_of::<MeshInstanceGpu>())
1547            } else {
1548                0
1549            })
1550            .saturating_add(if replace_edge_staging {
1551                self.edge_object_bytes.capacity()
1552            } else {
1553                0
1554            });
1555        let peak_frame_gpu_bytes = previous_frame_gpu_bytes
1556            .saturating_add(replacement_generated_bytes)
1557            .saturating_add(if replace_instance_buffer {
1558                self.instance_buffer.size() as usize
1559            } else {
1560                0
1561            })
1562            .saturating_add(if replace_edge_buffer {
1563                self.edge_object_buffer.size() as usize
1564            } else {
1565                0
1566            });
1567        if let Some(buffer) = replacement_surface_buffer {
1568            self.clipped_surface_buffer = Some(buffer);
1569            self.clipped_surface_capacity = surface_frame.vertices.len();
1570        }
1571        if let Some(buffer) = replacement_edge_buffer {
1572            self.clipped_edge_buffer = Some(buffer);
1573            self.clipped_edge_capacity = surface_frame.edges.len();
1574        }
1575        if let Some(buffer) = replacement_lighting_buffer {
1576            self.clipped_lighting_buffer = Some(buffer);
1577            self.clipped_lighting_capacity = surface_frame.lighting.len();
1578        }
1579        if let Some(buffer) = &self.clipped_lighting_buffer
1580            && !surface_frame.lighting.is_empty()
1581        {
1582            queue.write_buffer(buffer, 0, bytemuck::cast_slice(&surface_frame.lighting));
1583        }
1584        if let Some(buffer) = replacement_color_buffer {
1585            self.clipped_color_buffer = Some(buffer);
1586            self.clipped_color_capacity = surface_frame.colors.len();
1587        }
1588        self.clipped_surface_objects = surface_frame.objects;
1589        if let Some(buffer) = &self.clipped_color_buffer
1590            && !surface_frame.colors.is_empty()
1591        {
1592            queue.write_buffer(buffer, 0, bytemuck::cast_slice(&surface_frame.colors));
1593        }
1594        if let Some(buffer) = &self.clipped_surface_buffer
1595            && !surface_frame.vertices.is_empty()
1596        {
1597            queue.write_buffer(buffer, 0, bytemuck::cast_slice(&surface_frame.vertices));
1598        }
1599        if let Some(buffer) = &self.clipped_edge_buffer
1600            && !surface_frame.edges.is_empty()
1601        {
1602            queue.write_buffer(buffer, 0, bytemuck::cast_slice(&surface_frame.edges));
1603        }
1604        self.instances.clear();
1605        self.edge_object_bytes.clear();
1606        self.edge_object_bytes
1607            .resize(visible_count.saturating_mul(self.edge_object_stride), 0);
1608        let triangle_count = surface_frame.report.submitted_triangle_count();
1609        let mut edge_count = 0usize;
1610        let mut draw_call_count = 0usize;
1611        for (object_index, instance) in scene
1612            .instances()
1613            .iter()
1614            .filter(|instance| instance.visible)
1615            .enumerate()
1616        {
1617            let model_rows = self.clipped_surface_objects[object_index].model_rows;
1618            let normal_rows = self.clipped_surface_objects[object_index]
1619                .transport
1620                .normal_rows;
1621            self.instances.push(MeshInstanceGpu {
1622                normal_row_0: normal_rows[0],
1623                normal_row_1: normal_rows[1],
1624                normal_row_2: normal_rows[2],
1625                model_row_0: model_rows[0],
1626                model_row_1: model_rows[1],
1627                model_row_2: model_rows[2],
1628                surface: material::surface_parameters(instance.style.surface_style()),
1629                uv_transform: texture::material_uv_parameters(instance.mesh.material()),
1630                color: {
1631                    let color = instance
1632                        .style
1633                        .surface_style()
1634                        .map_or(Color::BLACK, |surface| surface.color())
1635                        .to_array();
1636                    let tint = instance
1637                        .mesh
1638                        .material()
1639                        .map_or(Color::WHITE, TextureMaterial3d::tint)
1640                        .to_array();
1641                    std::array::from_fn(|index| color[index] * tint[index])
1642                },
1643            });
1644            if instance.style.surface_style().is_some() {
1645                let generated = self.clipped_surface_objects[object_index]
1646                    .generated
1647                    .as_ref();
1648                if generated.map_or(instance.mesh.index_count > 0, |range| !range.is_empty()) {
1649                    draw_call_count = draw_call_count.saturating_add(1);
1650                }
1651            }
1652            if let Some(style) = instance.wireframe() {
1653                let instance_edge_count = instance.mesh.source().display_edges().len();
1654                edge_count = edge_count.saturating_add(instance_edge_count);
1655                if instance_edge_count > 0 {
1656                    draw_call_count = draw_call_count.saturating_add(1);
1657                    if style.hidden_enabled() {
1658                        draw_call_count = draw_call_count.saturating_add(1);
1659                    }
1660                }
1661                let hidden_color = style.hidden_color().unwrap_or(style.visible_color());
1662                let hidden_width = style.hidden_width().map_or(0.0, LogicalPixels::get);
1663                let (dash_length, gap_length) = style
1664                    .hidden_pattern()
1665                    .map_or((1.0, 1.0), |(dash, gap)| (dash.get(), gap.get()));
1666                let edge_uniform = EdgeObjectUniform {
1667                    model_row_0: model_rows[0],
1668                    model_row_1: model_rows[1],
1669                    model_row_2: model_rows[2],
1670                    visible_color: style.visible_color().to_array(),
1671                    hidden_color: hidden_color.to_array(),
1672                    edge_style: [
1673                        style.visible_width().get(),
1674                        hidden_width,
1675                        dash_length,
1676                        gap_length,
1677                    ],
1678                };
1679                let start = object_index * self.edge_object_stride;
1680                let end = start + std::mem::size_of::<EdgeObjectUniform>();
1681                self.edge_object_bytes[start..end]
1682                    .copy_from_slice(bytemuck::bytes_of(&edge_uniform));
1683            }
1684        }
1685
1686        queue.write_buffer(
1687            &self.camera_uniform_buffer,
1688            0,
1689            bytemuck::bytes_of(&camera_uniform),
1690        );
1691        if !self.instances.is_empty() {
1692            queue.write_buffer(
1693                &self.instance_buffer,
1694                0,
1695                bytemuck::cast_slice(&self.instances),
1696            );
1697        }
1698        if !self.edge_object_bytes.is_empty() {
1699            queue.write_buffer(&self.edge_object_buffer, 0, &self.edge_object_bytes);
1700        }
1701        let upload = upload_started_at.elapsed();
1702        let staging_upload_duration = upload.saturating_sub(preflight_duration);
1703        let encode_started_at = Instant::now();
1704        let mut encoder = device.create_command_encoder(&wgpu::CommandEncoderDescriptor {
1705            label: Some("sim-engine retained 3D scene encoder"),
1706        });
1707        let timing = gpu_timing
1708            .as_deref_mut()
1709            .and_then(|collector| collector.reserve(GpuTimingSource::Scene3d));
1710        encode_ordered_scene_pass(
1711            &mut encoder,
1712            self,
1713            &target.color.view,
1714            &target.depth_view,
1715            scene.background(),
1716            scene.instances(),
1717            &surface_frame.order,
1718            timing.as_ref().map(|timing| timing.timestamp_writes()),
1719        );
1720        if let Some(timing) = &timing {
1721            timing.resolve(&mut encoder);
1722        }
1723        queue.submit([encoder.finish()]);
1724        let gpu_timing_id = match (gpu_timing, timing) {
1725            (Some(collector), Some(timing)) => Some(collector.submitted(timing)),
1726            _ => None,
1727        };
1728        let encode_submit = encode_started_at.elapsed();
1729        Ok(Mesh3dRenderReport {
1730            object_count: visible_count,
1731            triangle_count,
1732            edge_count,
1733            render_pass_count: 1,
1734            draw_call_count,
1735            upload,
1736            preflight_duration,
1737            staging_upload_duration,
1738            encode_submit,
1739            preflight: surface_frame.report,
1740            gpu_timing_id,
1741            uploaded_bytes,
1742            upload_calls,
1743            buffer_allocation_count,
1744            retained_frame_cpu_bytes: self.retained_frame_cpu_bytes(),
1745            retained_frame_gpu_bytes: self.retained_frame_gpu_bytes(),
1746            staging_capacity_bytes: self
1747                .retained_frame_cpu_bytes()
1748                .saturating_add(transient_frame_cpu_bytes),
1749            peak_frame_cpu_bytes,
1750            peak_frame_gpu_bytes,
1751        })
1752    }
1753}
1754
1755fn create_retained_mesh(
1756    device: &wgpu::Device,
1757    queue: &wgpu::Queue,
1758    renderer_identity: Arc<()>,
1759    source: Mesh3d,
1760) -> Result<RetainedMesh3d, Mesh3dResourceError> {
1761    let prepared = upload::prepare_with_budget(device, source, Mesh3dUploadBudget::default())?;
1762    Ok(upload_prepared_retained_mesh(
1763        device,
1764        queue,
1765        renderer_identity,
1766        prepared,
1767    ))
1768}
1769
1770struct PreparedRetainedMeshUpload {
1771    source: Mesh3d,
1772    layout: Mesh3dUploadLayout,
1773    allocation: Mesh3dUploadLayout,
1774    vertices: Vec<MeshVertexGpu>,
1775    edges: Vec<MeshEdgeGpu>,
1776    texture_coordinates: Vec<MeshUvGpu>,
1777    colors: Vec<MeshColorGpu>,
1778    normals: Vec<MeshNormalGpu>,
1779    budget: Mesh3dUploadBudget,
1780}
1781
1782impl PreparedRetainedMeshUpload {
1783    fn staging_capacity_bytes(&self) -> usize {
1784        self.vertices
1785            .capacity()
1786            .saturating_mul(std::mem::size_of::<MeshVertexGpu>())
1787            .saturating_add(
1788                self.edges
1789                    .capacity()
1790                    .saturating_mul(std::mem::size_of::<MeshEdgeGpu>()),
1791            )
1792            .saturating_add(
1793                self.texture_coordinates
1794                    .capacity()
1795                    .saturating_mul(std::mem::size_of::<MeshUvGpu>()),
1796            )
1797            .saturating_add(
1798                self.colors
1799                    .capacity()
1800                    .saturating_mul(std::mem::size_of::<MeshColorGpu>()),
1801            )
1802            .saturating_add(
1803                self.normals
1804                    .capacity()
1805                    .saturating_mul(std::mem::size_of::<MeshNormalGpu>()),
1806            )
1807    }
1808}
1809
1810fn prepare_retained_mesh_upload(
1811    device: &wgpu::Device,
1812    source: Mesh3d,
1813) -> Result<PreparedRetainedMeshUpload, Mesh3dResourceError> {
1814    let layout = preflight_mesh3d_source(&source, device.limits().max_buffer_size)?;
1815    if !mesh3d_source_is_portable(&source) {
1816        return Err(Mesh3dResourceError::NonPortableVertex);
1817    }
1818    if source.texture_coordinates().iter().any(|coordinate| {
1819        !is_portable_shader_source(coordinate.u()) || !is_portable_shader_source(coordinate.v())
1820    }) {
1821        return Err(Mesh3dResourceError::NonPortableTextureCoordinate);
1822    }
1823    let mut normals = Vec::new();
1824    normals
1825        .try_reserve_exact(source.normals().len())
1826        .map_err(|_| Mesh3dResourceError::HostAllocationFailed {
1827            requested_bytes: layout.normal_bytes,
1828        })?;
1829    normals.extend(source.normals().iter().map(MeshNormalGpu::from_source));
1830    let mut colors = Vec::new();
1831    colors
1832        .try_reserve_exact(source.vertex_colors().len())
1833        .map_err(|_| Mesh3dResourceError::HostAllocationFailed {
1834            requested_bytes: layout.color_bytes,
1835        })?;
1836    colors.extend(source.vertex_colors().iter().map(|color| MeshColorGpu {
1837        color: color.to_array(),
1838    }));
1839    let mut texture_coordinates = Vec::new();
1840    texture_coordinates
1841        .try_reserve_exact(source.texture_coordinates().len())
1842        .map_err(|_| Mesh3dResourceError::HostAllocationFailed {
1843            requested_bytes: layout.texture_coordinate_bytes,
1844        })?;
1845    texture_coordinates.extend(
1846        source
1847            .texture_coordinates()
1848            .iter()
1849            .map(|coordinate| MeshUvGpu {
1850                coordinate: [coordinate.u(), coordinate.v()],
1851            }),
1852    );
1853    let mut vertices = Vec::new();
1854    vertices
1855        .try_reserve_exact(source.vertices().len())
1856        .map_err(|_| Mesh3dResourceError::HostAllocationFailed {
1857            requested_bytes: layout.vertex_bytes,
1858        })?;
1859    vertices.extend(source.vertices().iter().map(|vertex| MeshVertexGpu {
1860        position: [vertex.x(), vertex.y(), vertex.z()],
1861    }));
1862    let mut edges = Vec::new();
1863    edges
1864        .try_reserve_exact(source.display_edges().len())
1865        .map_err(|_| Mesh3dResourceError::HostAllocationFailed {
1866            requested_bytes: layout.edge_bytes,
1867        })?;
1868    edges.extend(source.display_edges().iter().map(|edge| {
1869        let start = source.vertices()[edge.start() as usize];
1870        let end = source.vertices()[edge.end() as usize];
1871        MeshEdgeGpu {
1872            start: [start.x(), start.y(), start.z()],
1873            end: [end.x(), end.y(), end.z()],
1874        }
1875    }));
1876    Ok(PreparedRetainedMeshUpload {
1877        source,
1878        layout,
1879        allocation: layout,
1880        vertices,
1881        edges,
1882        texture_coordinates,
1883        colors,
1884        normals,
1885        budget: Mesh3dUploadBudget::default(),
1886    })
1887}
1888
1889fn mesh3d_source_is_portable(source: &Mesh3d) -> bool {
1890    source.vertices().iter().all(|vertex| {
1891        [vertex.x(), vertex.y(), vertex.z()]
1892            .into_iter()
1893            .all(is_portable_shader_source)
1894    })
1895}
1896
1897fn upload_prepared_retained_mesh(
1898    device: &wgpu::Device,
1899    queue: &wgpu::Queue,
1900    renderer_identity: Arc<()>,
1901    prepared: PreparedRetainedMeshUpload,
1902) -> RetainedMesh3d {
1903    let PreparedRetainedMeshUpload {
1904        source,
1905        layout,
1906        allocation,
1907        vertices,
1908        edges,
1909        texture_coordinates,
1910        colors,
1911        normals,
1912        budget,
1913    } = prepared;
1914    let mesh = allocate_retained_mesh(
1915        device,
1916        renderer_identity,
1917        source,
1918        layout,
1919        allocation,
1920        budget,
1921    );
1922    write_retained_mesh_uploads(
1923        queue,
1924        &mesh,
1925        &vertices,
1926        &edges,
1927        &texture_coordinates,
1928        &colors,
1929        &normals,
1930    );
1931    submit_pending_uploads(queue);
1932    mesh
1933}
1934
1935fn allocate_retained_mesh(
1936    device: &wgpu::Device,
1937    renderer_identity: Arc<()>,
1938    source: Mesh3d,
1939    live: Mesh3dUploadLayout,
1940    allocation: Mesh3dUploadLayout,
1941    budget: Mesh3dUploadBudget,
1942) -> RetainedMesh3d {
1943    let vertex_buffer = Arc::new(device.create_buffer(&wgpu::BufferDescriptor {
1944        label: Some("sim-engine retained 3D vertex buffer"),
1945        size: allocation.vertex_bytes,
1946        usage: wgpu::BufferUsages::VERTEX | wgpu::BufferUsages::COPY_DST,
1947        mapped_at_creation: false,
1948    }));
1949    let index_buffer = if allocation.index_bytes == 0 {
1950        None
1951    } else {
1952        Some(Arc::new(device.create_buffer(&wgpu::BufferDescriptor {
1953            label: Some("sim-engine retained 3D index buffer"),
1954            size: allocation.index_bytes,
1955            usage: wgpu::BufferUsages::INDEX | wgpu::BufferUsages::COPY_DST,
1956            mapped_at_creation: false,
1957        })))
1958    };
1959    let edge_buffer = if allocation.edge_bytes == 0 {
1960        None
1961    } else {
1962        let buffer = Arc::new(device.create_buffer(&wgpu::BufferDescriptor {
1963            label: Some("sim-engine retained 3D edge buffer"),
1964            size: allocation.edge_bytes,
1965            usage: wgpu::BufferUsages::VERTEX | wgpu::BufferUsages::COPY_DST,
1966            mapped_at_creation: false,
1967        }));
1968        Some(buffer)
1969    };
1970    let texture_coordinate_buffer = if allocation.texture_coordinate_bytes == 0 {
1971        None
1972    } else {
1973        let buffer = Arc::new(device.create_buffer(&wgpu::BufferDescriptor {
1974            label: Some("sim-engine 3D UV buffer"),
1975            size: allocation.texture_coordinate_bytes,
1976            usage: wgpu::BufferUsages::VERTEX | wgpu::BufferUsages::COPY_DST,
1977            mapped_at_creation: false,
1978        }));
1979        Some(buffer)
1980    };
1981    let color_buffer = (allocation.color_bytes > 0).then(|| {
1982        Arc::new(device.create_buffer(&wgpu::BufferDescriptor {
1983            label: Some("sim-engine 3D vertex color buffer"),
1984            size: allocation.color_bytes,
1985            usage: wgpu::BufferUsages::VERTEX | wgpu::BufferUsages::COPY_DST,
1986            mapped_at_creation: false,
1987        }))
1988    });
1989    let normal_buffer = (allocation.normal_bytes > 0).then(|| {
1990        Arc::new(device.create_buffer(&wgpu::BufferDescriptor {
1991            label: Some("sim-engine 3D normal buffer"),
1992            size: allocation.normal_bytes,
1993            usage: wgpu::BufferUsages::VERTEX | wgpu::BufferUsages::COPY_DST,
1994            mapped_at_creation: false,
1995        }))
1996    });
1997    RetainedMesh3d {
1998        renderer_identity,
1999        vertex_buffer,
2000        index_buffer,
2001        edge_buffer,
2002        texture_coordinate_buffer,
2003        color_buffer,
2004        normal_buffer,
2005        material: None,
2006        source,
2007        index_count: live.index_count,
2008        edge_count: live.edge_count,
2009        gpu_allocation_bytes: allocation.total_bytes as usize,
2010        budget,
2011        allocation,
2012    }
2013}
2014
2015#[allow(clippy::too_many_arguments)]
2016fn write_retained_mesh_uploads(
2017    queue: &wgpu::Queue,
2018    mesh: &RetainedMesh3d,
2019    vertices: &[MeshVertexGpu],
2020    edges: &[MeshEdgeGpu],
2021    coordinates: &[MeshUvGpu],
2022    colors: &[MeshColorGpu],
2023    normals: &[MeshNormalGpu],
2024) -> usize {
2025    let mut calls = 0;
2026    for (buffer, bytes) in [
2027        (Some(&mesh.vertex_buffer), bytemuck::cast_slice(vertices)),
2028        (
2029            mesh.index_buffer.as_ref(),
2030            bytemuck::cast_slice(mesh.source.triangle_indices()),
2031        ),
2032        (mesh.edge_buffer.as_ref(), bytemuck::cast_slice(edges)),
2033        (mesh.color_buffer.as_ref(), bytemuck::cast_slice(colors)),
2034        (mesh.normal_buffer.as_ref(), bytemuck::cast_slice(normals)),
2035        (
2036            mesh.texture_coordinate_buffer.as_ref(),
2037            bytemuck::cast_slice(coordinates),
2038        ),
2039    ] {
2040        if let Some(buffer) = buffer
2041            && !bytes.is_empty()
2042        {
2043            queue.write_buffer(buffer, 0, bytes);
2044            calls += 1;
2045        }
2046    }
2047    calls
2048}
2049
2050fn restore_scene3d_resources(
2051    device: &wgpu::Device,
2052    queue: &wgpu::Queue,
2053    texture_layout: &wgpu::BindGroupLayout,
2054    renderer_identity: Arc<()>,
2055    scene: &mut Scene3d,
2056) -> Result<Scene3dRestoreReport, Mesh3dResourceError> {
2057    let prepared_textures = texture::prepare_scene_restoration(device, &renderer_identity, scene)?;
2058    let mut restored_textures = Vec::new();
2059    restored_textures
2060        .try_reserve_exact(prepared_textures.len())
2061        .map_err(|_| Mesh3dResourceError::HostAllocationFailed {
2062            requested_bytes: prepared_textures
2063                .len()
2064                .saturating_mul(std::mem::size_of::<(usize, Texture3d)>())
2065                as u64,
2066        })?;
2067    let pending_staging_bytes = scene
2068        .instances
2069        .len()
2070        .checked_mul(std::mem::size_of::<(usize, RetainedMesh3d)>())
2071        .and_then(|bytes| u64::try_from(bytes).ok())
2072        .ok_or(Mesh3dResourceError::CapacityTooLarge)?;
2073    let prepared_staging_bytes = scene
2074        .instances
2075        .len()
2076        .checked_mul(std::mem::size_of::<(
2077            usize,
2078            Arc<wgpu::Buffer>,
2079            PreparedRetainedMeshUpload,
2080        )>())
2081        .and_then(|bytes| u64::try_from(bytes).ok())
2082        .ok_or(Mesh3dResourceError::CapacityTooLarge)?;
2083    let restored_staging_bytes = scene
2084        .instances
2085        .len()
2086        .checked_mul(std::mem::size_of::<(usize, RetainedMesh3d)>())
2087        .and_then(|bytes| u64::try_from(bytes).ok())
2088        .ok_or(Mesh3dResourceError::CapacityTooLarge)?;
2089    let replacement_staging_bytes = scene
2090        .instances
2091        .len()
2092        .checked_mul(std::mem::size_of::<Mesh3dInstance>())
2093        .and_then(|bytes| u64::try_from(bytes).ok())
2094        .ok_or(Mesh3dResourceError::CapacityTooLarge)?;
2095    let mut pending = Vec::<(usize, RetainedMesh3d)>::new();
2096    pending
2097        .try_reserve_exact(scene.instances.len())
2098        .map_err(|_| Mesh3dResourceError::HostAllocationFailed {
2099            requested_bytes: pending_staging_bytes,
2100        })?;
2101    let mut prepared = Vec::<(usize, Arc<wgpu::Buffer>, PreparedRetainedMeshUpload)>::new();
2102    prepared
2103        .try_reserve_exact(scene.instances.len())
2104        .map_err(|_| Mesh3dResourceError::HostAllocationFailed {
2105            requested_bytes: prepared_staging_bytes,
2106        })?;
2107    let mut restored = Vec::<(usize, RetainedMesh3d)>::new();
2108    restored
2109        .try_reserve_exact(scene.instances.len())
2110        .map_err(|_| Mesh3dResourceError::HostAllocationFailed {
2111            requested_bytes: restored_staging_bytes,
2112        })?;
2113    let mut replacement_instances = Vec::new();
2114    replacement_instances
2115        .try_reserve_exact(scene.instances.len())
2116        .map_err(|_| Mesh3dResourceError::HostAllocationFailed {
2117            requested_bytes: replacement_staging_bytes,
2118        })?;
2119    replacement_instances.extend(scene.instances.iter().cloned());
2120
2121    for instance in &scene.instances {
2122        if Arc::ptr_eq(&renderer_identity, &instance.mesh.renderer_identity) {
2123            continue;
2124        }
2125        let key = Arc::as_ptr(&instance.mesh.vertex_buffer) as usize;
2126        pending.push((key, instance.mesh.clone()));
2127    }
2128    pending.sort_unstable_by_key(|entry| entry.0);
2129    pending.dedup_by_key(|entry| entry.0);
2130
2131    // Complete every device-limit check and caller-scale host allocation
2132    // before the first replacement GPU resource is created or written.
2133    for (key, mesh) in pending {
2134        let upload = upload::prepare_restoration(device, &mesh)?;
2135        prepared.push((key, Arc::clone(&mesh.vertex_buffer), upload));
2136    }
2137    for (key, _old_vertex_buffer, upload) in prepared {
2138        let replacement =
2139            upload_prepared_retained_mesh(device, queue, Arc::clone(&renderer_identity), upload);
2140        restored.push((key, replacement));
2141    }
2142    for prepared in prepared_textures {
2143        if let Some(chain) = prepared.chain {
2144            let restored = texture::upload_chain(
2145                device,
2146                queue,
2147                &renderer_identity,
2148                texture_layout,
2149                chain,
2150                prepared.source.preserves_alpha(),
2151            );
2152            restored_textures.push((prepared.key, restored));
2153        }
2154    }
2155
2156    let mut migrated_object_count = 0;
2157    for instance in &mut replacement_instances {
2158        let key = Arc::as_ptr(&instance.mesh.vertex_buffer) as usize;
2159        let previous_material = instance.mesh.material.clone();
2160        let mut migrated = false;
2161        if let Ok(index) = restored.binary_search_by_key(&key, |entry| entry.0) {
2162            instance.mesh = restored[index].1.clone();
2163            migrated = true;
2164        }
2165        if let Some(material) = previous_material {
2166            if let Ok(index) = restored_textures
2167                .binary_search_by_key(&material.texture().identity_key(), |entry| entry.0)
2168            {
2169                instance.mesh.material =
2170                    Some(material.with_restored_texture(&restored_textures[index].1));
2171                migrated = true;
2172            } else {
2173                instance.mesh.material = Some(material);
2174            }
2175        }
2176        migrated_object_count += usize::from(migrated);
2177    }
2178    let restored_gpu_bytes = restored.iter().fold(0_usize, |total, (_, mesh)| {
2179        total.saturating_add(mesh.gpu_allocation_bytes())
2180    });
2181    scene.instances = replacement_instances;
2182    scene.renderer_identity = Some(renderer_identity);
2183    scene.rebuild_resource_keys();
2184    Ok(Scene3dRestoreReport {
2185        object_count: scene.object_count(),
2186        migrated_object_count,
2187        restored_mesh_count: restored.len(),
2188        restored_gpu_bytes,
2189        restored_texture_count: restored_textures.len(),
2190        restored_texture_bytes: restored_textures
2191            .iter()
2192            .map(|(_, texture)| texture.gpu_allocation_bytes())
2193            .sum(),
2194    })
2195}
2196
2197#[derive(Debug, Clone, Copy, PartialEq, Eq)]
2198struct Mesh3dUploadLayout {
2199    vertex_bytes: u64,
2200    index_bytes: u64,
2201    edge_bytes: u64,
2202    texture_coordinate_bytes: u64,
2203    color_bytes: u64,
2204    normal_bytes: u64,
2205    total_bytes: u64,
2206    index_count: u32,
2207    edge_count: u32,
2208}
2209
2210fn preflight_mesh3d_source(
2211    source: &Mesh3d,
2212    max_buffer_size: u64,
2213) -> Result<Mesh3dUploadLayout, Mesh3dResourceError> {
2214    let mut layout = preflight_mesh3d_upload(
2215        source.vertices().len(),
2216        source.triangle_indices().len(),
2217        source.display_edges().len(),
2218        max_buffer_size,
2219    )?;
2220    layout.texture_coordinate_bytes = source
2221        .texture_coordinates()
2222        .len()
2223        .checked_mul(std::mem::size_of::<MeshUvGpu>())
2224        .and_then(|bytes| u64::try_from(bytes).ok())
2225        .filter(|bytes| *bytes <= max_buffer_size)
2226        .ok_or(Mesh3dResourceError::CapacityTooLarge)?;
2227    layout.color_bytes = source
2228        .vertex_colors()
2229        .len()
2230        .checked_mul(std::mem::size_of::<MeshColorGpu>())
2231        .and_then(|bytes| u64::try_from(bytes).ok())
2232        .filter(|bytes| *bytes <= max_buffer_size)
2233        .ok_or(Mesh3dResourceError::CapacityTooLarge)?;
2234    layout.normal_bytes = source
2235        .normals()
2236        .len()
2237        .checked_mul(std::mem::size_of::<MeshNormalGpu>())
2238        .and_then(|bytes| u64::try_from(bytes).ok())
2239        .filter(|bytes| *bytes <= max_buffer_size)
2240        .ok_or(Mesh3dResourceError::CapacityTooLarge)?;
2241    layout.total_bytes = layout
2242        .total_bytes
2243        .checked_add(layout.texture_coordinate_bytes)
2244        .and_then(|bytes| bytes.checked_add(layout.color_bytes))
2245        .and_then(|bytes| bytes.checked_add(layout.normal_bytes))
2246        .filter(|bytes| usize::try_from(*bytes).is_ok())
2247        .ok_or(Mesh3dResourceError::CapacityTooLarge)?;
2248    Ok(layout)
2249}
2250
2251fn preflight_mesh3d_upload(
2252    vertex_count: usize,
2253    index_count: usize,
2254    edge_count: usize,
2255    max_buffer_size: u64,
2256) -> Result<Mesh3dUploadLayout, Mesh3dResourceError> {
2257    let draw_index_count =
2258        u32::try_from(index_count).map_err(|_| Mesh3dResourceError::CapacityTooLarge)?;
2259    let draw_edge_count =
2260        u32::try_from(edge_count).map_err(|_| Mesh3dResourceError::CapacityTooLarge)?;
2261    let checked_buffer_bytes = |element_size: usize, element_count: usize| {
2262        u64::try_from(element_size)
2263            .ok()
2264            .and_then(|size| u64::try_from(element_count).ok()?.checked_mul(size))
2265            .filter(|bytes| *bytes <= max_buffer_size && usize::try_from(*bytes).is_ok())
2266            .ok_or(Mesh3dResourceError::CapacityTooLarge)
2267    };
2268    let vertex_bytes = checked_buffer_bytes(std::mem::size_of::<MeshVertexGpu>(), vertex_count)?;
2269    let index_bytes = checked_buffer_bytes(std::mem::size_of::<u32>(), index_count)?;
2270    let edge_bytes = checked_buffer_bytes(std::mem::size_of::<MeshEdgeGpu>(), edge_count)?;
2271    let total_bytes = vertex_bytes
2272        .checked_add(index_bytes)
2273        .and_then(|bytes| bytes.checked_add(edge_bytes))
2274        .ok_or(Mesh3dResourceError::CapacityTooLarge)?;
2275    usize::try_from(total_bytes).map_err(|_| Mesh3dResourceError::CapacityTooLarge)?;
2276    Ok(Mesh3dUploadLayout {
2277        vertex_bytes,
2278        index_bytes,
2279        edge_bytes,
2280        texture_coordinate_bytes: 0,
2281        color_bytes: 0,
2282        normal_bytes: 0,
2283        total_bytes,
2284        index_count: draw_index_count,
2285        edge_count: draw_edge_count,
2286    })
2287}
2288
2289fn create_instance_buffer(device: &wgpu::Device, capacity: usize) -> wgpu::Buffer {
2290    device.create_buffer(&wgpu::BufferDescriptor {
2291        label: Some("sim-engine 3D instance buffer"),
2292        size: (capacity.max(1) * std::mem::size_of::<MeshInstanceGpu>()) as wgpu::BufferAddress,
2293        usage: wgpu::BufferUsages::VERTEX | wgpu::BufferUsages::COPY_DST,
2294        mapped_at_creation: false,
2295    })
2296}
2297
2298#[allow(clippy::too_many_arguments)]
2299fn create_edge_pipeline(
2300    device: &wgpu::Device,
2301    shader: &wgpu::ShaderModule,
2302    layout: &wgpu::PipelineLayout,
2303    format: wgpu::TextureFormat,
2304    depth_compare: wgpu::CompareFunction,
2305    fragment_entry: &'static str,
2306    label: &'static str,
2307    clip_space: bool,
2308) -> wgpu::RenderPipeline {
2309    let (vertex_entry, depth_bias) = if depth_compare == wgpu::CompareFunction::Greater {
2310        (
2311            "mesh3d_hidden_edge_vs_main",
2312            wgpu::DepthBiasState {
2313                constant: HIDDEN_EDGE_DEPTH_BIAS,
2314                slope_scale: 0.0,
2315                clamp: 0.0,
2316            },
2317        )
2318    } else {
2319        (
2320            "mesh3d_visible_edge_vs_main",
2321            wgpu::DepthBiasState {
2322                constant: VISIBLE_EDGE_DEPTH_BIAS,
2323                slope_scale: 0.0,
2324                clamp: 0.0,
2325            },
2326        )
2327    };
2328    let vertex_entry = if clip_space {
2329        if depth_compare == wgpu::CompareFunction::Greater {
2330            "mesh3d_clipped_hidden_edge_vs_main"
2331        } else {
2332            "mesh3d_clipped_visible_edge_vs_main"
2333        }
2334    } else {
2335        vertex_entry
2336    };
2337    device.create_render_pipeline(&wgpu::RenderPipelineDescriptor {
2338        label: Some(label),
2339        layout: Some(layout),
2340        vertex: wgpu::VertexState {
2341            module: shader,
2342            entry_point: Some(vertex_entry),
2343            compilation_options: wgpu::PipelineCompilationOptions::default(),
2344            buffers: &[Some(if clip_space {
2345                SurfaceClipEdge::LAYOUT
2346            } else {
2347                MeshEdgeGpu::LAYOUT
2348            })],
2349        },
2350        primitive: wgpu::PrimitiveState {
2351            topology: wgpu::PrimitiveTopology::TriangleList,
2352            ..Default::default()
2353        },
2354        depth_stencil: Some(wgpu::DepthStencilState {
2355            format: DEPTH_FORMAT,
2356            depth_write_enabled: Some(false),
2357            depth_compare: Some(depth_compare),
2358            stencil: wgpu::StencilState::default(),
2359            bias: depth_bias,
2360        }),
2361        multisample: wgpu::MultisampleState::default(),
2362        fragment: Some(wgpu::FragmentState {
2363            module: shader,
2364            entry_point: Some(fragment_entry),
2365            compilation_options: wgpu::PipelineCompilationOptions::default(),
2366            targets: &[Some(wgpu::ColorTargetState {
2367                format,
2368                blend: Some(wgpu::BlendState::ALPHA_BLENDING),
2369                write_mask: wgpu::ColorWrites::ALL,
2370            })],
2371        }),
2372        multiview_mask: None,
2373        cache: None,
2374    })
2375}
2376
2377fn align_to(value: usize, alignment: usize) -> usize {
2378    if alignment <= 1 {
2379        value
2380    } else {
2381        value.div_ceil(alignment).saturating_mul(alignment)
2382    }
2383}
2384
2385fn create_edge_object_buffer(
2386    device: &wgpu::Device,
2387    stride: usize,
2388    capacity: usize,
2389) -> wgpu::Buffer {
2390    device.create_buffer(&wgpu::BufferDescriptor {
2391        label: Some("sim-engine 3D edge object uniform buffer"),
2392        size: capacity.max(1).saturating_mul(stride) as wgpu::BufferAddress,
2393        usage: wgpu::BufferUsages::UNIFORM | wgpu::BufferUsages::COPY_DST,
2394        mapped_at_creation: false,
2395    })
2396}
2397
2398fn create_edge_object_bind_group(
2399    device: &wgpu::Device,
2400    layout: &wgpu::BindGroupLayout,
2401    buffer: &wgpu::Buffer,
2402) -> wgpu::BindGroup {
2403    device.create_bind_group(&wgpu::BindGroupDescriptor {
2404        label: Some("sim-engine 3D edge object bind group"),
2405        layout,
2406        entries: &[wgpu::BindGroupEntry {
2407            binding: 0,
2408            resource: wgpu::BindingResource::Buffer(wgpu::BufferBinding {
2409                buffer,
2410                offset: 0,
2411                size: wgpu::BufferSize::new(std::mem::size_of::<EdgeObjectUniform>() as u64),
2412            }),
2413        }],
2414    })
2415}
2416
2417fn create_depth_texture(device: &wgpu::Device, width: u32, height: u32) -> wgpu::Texture {
2418    device.create_texture(&wgpu::TextureDescriptor {
2419        label: Some("sim-engine 3D depth target"),
2420        size: wgpu::Extent3d {
2421            width,
2422            height,
2423            depth_or_array_layers: 1,
2424        },
2425        mip_level_count: 1,
2426        sample_count: 1,
2427        dimension: wgpu::TextureDimension::D2,
2428        format: DEPTH_FORMAT,
2429        usage: wgpu::TextureUsages::RENDER_ATTACHMENT,
2430        view_formats: &[],
2431    })
2432}
2433
2434fn target_pixels_per_logical(
2435    width: u32,
2436    height: u32,
2437    viewport: LogicalViewport,
2438) -> Option<PhysicalPerLogical> {
2439    let horizontal = width as f64 / viewport.width() as f64;
2440    let vertical = height as f64 / viewport.height() as f64;
2441    if !horizontal.is_finite()
2442        || !vertical.is_finite()
2443        || horizontal <= 0.0
2444        || vertical <= 0.0
2445        || !aspect_matches(horizontal, vertical)
2446        || horizontal > f32::MAX as f64
2447    {
2448        return None;
2449    }
2450    PhysicalPerLogical::new(horizontal as f32).ok()
2451}
2452
2453fn aspect_matches(left: f64, right: f64) -> bool {
2454    if !left.is_finite() || !right.is_finite() || left <= 0.0 || right <= 0.0 {
2455        return false;
2456    }
2457    let scale = left.abs().max(right.abs());
2458    (left - right).abs() <= scale * 1.0e-5
2459}
2460
2461fn validate_camera_target_aspect(
2462    camera: Camera3d,
2463    viewport: LogicalViewport,
2464) -> Result<(), Mesh3dRenderError> {
2465    aspect_matches(
2466        f64::from(camera.projection().aspect_ratio()),
2467        f64::from(viewport.width()) / f64::from(viewport.height()),
2468    )
2469    .then_some(())
2470    .ok_or(Mesh3dRenderError::CameraTargetAspectMismatch)
2471}
2472
2473fn validate_target_identity(
2474    renderer_identity: &Arc<()>,
2475    target: &RenderTarget3d,
2476) -> Result<(), Mesh3dRenderError> {
2477    (Arc::ptr_eq(renderer_identity, &target.renderer_identity)
2478        && Arc::ptr_eq(renderer_identity, &target.color.renderer_identity))
2479    .then_some(())
2480    .ok_or(Mesh3dRenderError::RendererMismatch)
2481}
2482
2483fn validate_mesh_identity(
2484    renderer_identity: &Arc<()>,
2485    mesh: &RetainedMesh3d,
2486) -> Result<(), Mesh3dRenderError> {
2487    (Arc::ptr_eq(renderer_identity, &mesh.renderer_identity)
2488        && mesh
2489            .material()
2490            .is_none_or(|material| material.texture().belongs_to(renderer_identity)))
2491    .then_some(())
2492    .ok_or(Mesh3dRenderError::RendererMismatch)
2493}
2494
2495#[cfg(test)]
2496fn validate_shader_transform(
2497    mesh: &Mesh3d,
2498    model_rows: [[f32; 4]; 3],
2499    camera_rows: [[f32; 4]; 4],
2500) -> Result<(), Mesh3dRenderError> {
2501    validate_shader_points(mesh, model_rows, camera_rows)?;
2502    validate_surface_triangle_topology(mesh, model_rows, camera_rows)
2503}
2504
2505#[cfg(test)]
2506fn validate_shader_points(
2507    mesh: &Mesh3d,
2508    model_rows: [[f32; 4]; 3],
2509    camera_rows: [[f32; 4]; 4],
2510) -> Result<(), Mesh3dRenderError> {
2511    // Validate actual retained coordinates. An AABB-only proof cannot exclude
2512    // an interior source product entering the backend-dependent subnormal
2513    // domain, even when every synthetic corner has a stable clip side.
2514    for vertex in mesh.vertices() {
2515        validate_shader_point(*vertex, model_rows, camera_rows)?;
2516    }
2517    Ok(())
2518}
2519
2520#[cfg(test)]
2521fn validate_surface_triangle_topology(
2522    mesh: &Mesh3d,
2523    model_rows: [[f32; 4]; 3],
2524    camera_rows: [[f32; 4]; 4],
2525) -> Result<(), Mesh3dRenderError> {
2526    surface::classify_surface(mesh, model_rows, camera_rows, |_, _, _| Ok(()))
2527}
2528
2529fn validate_projected_triangle_orientation(
2530    clips: [[ShaderValueRange; 4]; 3],
2531) -> Result<(), Mesh3dRenderError> {
2532    let minimum_normal = f64::from(f32::MIN_POSITIVE);
2533    let ndc = clips.map(|clip| {
2534        let denominator = (clip[3].minimum, clip[3].maximum);
2535        [
2536            wgsl_division_range((clip[0].minimum, clip[0].maximum), denominator),
2537            wgsl_division_range((clip[1].minimum, clip[1].maximum), denominator),
2538        ]
2539    });
2540    let ndc = [
2541        [
2542            ndc[0][0].ok_or(Mesh3dRenderError::UnportableSurfaceTopology)?,
2543            ndc[0][1].ok_or(Mesh3dRenderError::UnportableSurfaceTopology)?,
2544        ],
2545        [
2546            ndc[1][0].ok_or(Mesh3dRenderError::UnportableSurfaceTopology)?,
2547            ndc[1][1].ok_or(Mesh3dRenderError::UnportableSurfaceTopology)?,
2548        ],
2549        [
2550            ndc[2][0].ok_or(Mesh3dRenderError::UnportableSurfaceTopology)?,
2551            ndc[2][1].ok_or(Mesh3dRenderError::UnportableSurfaceTopology)?,
2552        ],
2553    ];
2554    let first_x = rounded_f32_add_range(ndc[1][0], ndc[0][0], true)
2555        .ok_or(Mesh3dRenderError::UnportableSurfaceTopology)?;
2556    let first_y = rounded_f32_add_range(ndc[2][1], ndc[0][1], true)
2557        .ok_or(Mesh3dRenderError::UnportableSurfaceTopology)?;
2558    let second_y = rounded_f32_add_range(ndc[1][1], ndc[0][1], true)
2559        .ok_or(Mesh3dRenderError::UnportableSurfaceTopology)?;
2560    let second_x = rounded_f32_add_range(ndc[2][0], ndc[0][0], true)
2561        .ok_or(Mesh3dRenderError::UnportableSurfaceTopology)?;
2562    let positive = rounded_f32_product_range(first_x, first_y)
2563        .ok_or(Mesh3dRenderError::UnportableSurfaceTopology)?;
2564    let negative = rounded_f32_product_range(second_y, second_x)
2565        .ok_or(Mesh3dRenderError::UnportableSurfaceTopology)?;
2566    let signed_area = rounded_f32_add_range(positive, negative, true)
2567        .ok_or(Mesh3dRenderError::UnportableSurfaceTopology)?;
2568    let stable_area = signed_area.0 >= minimum_normal || signed_area.1 <= -minimum_normal;
2569    if !stable_area {
2570        return Err(Mesh3dRenderError::UnportableSurfaceTopology);
2571    }
2572    Ok(())
2573}
2574
2575#[cfg(test)]
2576fn validate_shader_point(
2577    point: Vec3,
2578    model_rows: [[f32; 4]; 3],
2579    camera_rows: [[f32; 4]; 4],
2580) -> Result<(), Mesh3dRenderError> {
2581    validate_clip_classification(shader_clip_point_ranges(point, model_rows, camera_rows)?)
2582}
2583
2584fn shader_clip_point_ranges(
2585    point: Vec3,
2586    model_rows: [[f32; 4]; 3],
2587    camera_rows: [[f32; 4]; 4],
2588) -> Result<[ShaderValueRange; 4], Mesh3dRenderError> {
2589    let model_point = [point.x(), point.y(), point.z(), 1.0].map(ShaderValueRange::exact);
2590    let world = [
2591        shader_dot_range(model_rows[0], model_point)?,
2592        shader_dot_range(model_rows[1], model_point)?,
2593        shader_dot_range(model_rows[2], model_point)?,
2594        ShaderValueRange::exact(1.0),
2595    ];
2596    Ok([
2597        shader_dot_range(camera_rows[0], world)?,
2598        shader_dot_range(camera_rows[1], world)?,
2599        shader_dot_range(camera_rows[2], world)?,
2600        shader_dot_range(camera_rows[3], world)?,
2601    ])
2602}
2603
2604fn validate_clip_classification(clip: [ShaderValueRange; 4]) -> Result<(), Mesh3dRenderError> {
2605    let plane_ranges = clip_plane_ranges(clip)?;
2606    // Rasterization is portable only when no critical plane classification
2607    // changes across legal dot associations and the vertex is either always
2608    // inside or has at least one common outside plane. A crossing range can
2609    // otherwise turn the same retained triangle from visible to clipped on
2610    // another conforming backend.
2611    let minimum_normal = f64::from(f32::MIN_POSITIVE);
2612    let stable_planes = plane_ranges
2613        .iter()
2614        .all(|range| range.0 >= 0.0 || range.1 <= -minimum_normal);
2615    let always_inside =
2616        plane_ranges.iter().all(|range| range.0 >= 0.0) && clip[3].minimum >= minimum_normal;
2617    let always_outside = plane_ranges.iter().any(|range| range.1 <= -minimum_normal);
2618    (stable_planes && (always_inside || always_outside))
2619        .then_some(())
2620        .ok_or(Mesh3dRenderError::InvalidGeometryTransform)
2621}
2622
2623fn clip_plane_ranges(clip: [ShaderValueRange; 4]) -> Result<[(f64, f64); 6], Mesh3dRenderError> {
2624    let x = clip[0];
2625    let y = clip[1];
2626    let z = clip[2];
2627    let w = clip[3];
2628    // These are sign envelopes, not a mirror of a raw f32 add. The edge
2629    // shader first applies a common normal homogeneous scale and hardware
2630    // clipping is homogeneous as well; the plane-sign envelope is evaluated
2631    // separately from the bounded shader add used by edge normalization.
2632    let plane_ranges = [
2633        (w.minimum + x.minimum, w.maximum + x.maximum),
2634        (w.minimum - x.maximum, w.maximum - x.minimum),
2635        (w.minimum + y.minimum, w.maximum + y.maximum),
2636        (w.minimum - y.maximum, w.maximum - y.minimum),
2637        (z.minimum, z.maximum),
2638        (w.minimum - z.maximum, w.maximum - z.minimum),
2639    ];
2640    plane_ranges
2641        .iter()
2642        .all(|range| range.0.is_finite() && range.1.is_finite())
2643        .then_some(plane_ranges)
2644        .ok_or(Mesh3dRenderError::InvalidGeometryTransform)
2645}
2646
2647type ClipPlaneRanges = [(f64, f64); 6];
2648type EdgeClipPlaneRanges = [ClipPlaneRanges; 2];
2649
2650type ClipComponentRange = (f64, f64);
2651type ClipPointRanges = [ClipComponentRange; 4];
2652type EdgeClipRanges = [ClipPointRanges; 2];
2653
2654#[derive(Clone, Copy)]
2655struct NormalizedEdgeRanges {
2656    clip: EdgeClipRanges,
2657    planes: EdgeClipPlaneRanges,
2658}
2659
2660fn clip_ranges_share_outside_plane(start: ClipPlaneRanges, end: ClipPlaneRanges) -> bool {
2661    let minimum_normal = f64::from(f32::MIN_POSITIVE);
2662    start
2663        .into_iter()
2664        .zip(end)
2665        .any(|(start, end)| start.1 <= -minimum_normal && end.1 <= -minimum_normal)
2666}
2667
2668fn validate_edge_homogeneous_classification(
2669    start: [ShaderValueRange; 4],
2670    end: [ShaderValueRange; 4],
2671) -> Result<NormalizedEdgeRanges, Mesh3dRenderError> {
2672    let minimum_magnitude = start
2673        .into_iter()
2674        .chain(end)
2675        .map(shader_range_minimum_magnitude)
2676        .fold(0.0_f64, f64::max)
2677        .max(1.0);
2678    let maximum_magnitude = start
2679        .into_iter()
2680        .chain(end)
2681        .map(|value| value.minimum.abs().max(value.maximum.abs()))
2682        .fold(1.0_f64, f64::max);
2683    if !minimum_magnitude.is_finite() || !maximum_magnitude.is_finite() {
2684        return Err(Mesh3dRenderError::InvalidEdgeProjection);
2685    }
2686    let scale = wgsl_division_range(
2687        (1.0, 1.0),
2688        (minimum_magnitude.max(1.0), maximum_magnitude.max(1.0)),
2689    )
2690    .ok_or(Mesh3dRenderError::InvalidEdgeProjection)?;
2691
2692    let mut normalized_clip = [[(0.0, 0.0); 4]; 2];
2693    let mut normalized_planes = [[(0.0, 0.0); 6]; 2];
2694    for (endpoint_index, clip) in [start, end].into_iter().enumerate() {
2695        let normalized = clip.map(|component| {
2696            rounded_f32_product_range((component.minimum, component.maximum), scale)
2697        });
2698        if normalized.iter().any(Option::is_none) {
2699            return Err(Mesh3dRenderError::InvalidEdgeProjection);
2700        }
2701        let normalized = normalized.map(Option::unwrap);
2702        normalized_clip[endpoint_index] = normalized;
2703        let x = normalized[0];
2704        let y = normalized[1];
2705        let z = normalized[2];
2706        let w = normalized[3];
2707        let planes = [
2708            rounded_f32_add_range(w, x, false),
2709            rounded_f32_add_range(w, x, true),
2710            rounded_f32_add_range(w, y, false),
2711            rounded_f32_add_range(w, y, true),
2712            Some(z),
2713            rounded_f32_add_range(w, z, true),
2714        ];
2715        if planes.iter().any(Option::is_none) {
2716            return Err(Mesh3dRenderError::InvalidEdgeProjection);
2717        }
2718        let planes = planes.map(Option::unwrap);
2719        normalized_planes[endpoint_index] = planes;
2720    }
2721    validate_normalized_plane_sides([start, end], normalized_planes)?;
2722    Ok(NormalizedEdgeRanges {
2723        clip: normalized_clip,
2724        planes: normalized_planes,
2725    })
2726}
2727
2728fn validate_normalized_plane_sides(
2729    raw_clip: [[ShaderValueRange; 4]; 2],
2730    normalized_planes: EdgeClipPlaneRanges,
2731) -> Result<(), Mesh3dRenderError> {
2732    let minimum_normal = f64::from(f32::MIN_POSITIVE);
2733    for (raw_clip, normalized_planes) in raw_clip.into_iter().zip(normalized_planes) {
2734        for (raw, normalized) in clip_plane_ranges(raw_clip)?
2735            .into_iter()
2736            .zip(normalized_planes)
2737        {
2738            let raw_inside = raw.0 >= 0.0;
2739            let raw_outside = raw.1 <= -minimum_normal;
2740            let normalized_inside = normalized.0 >= 0.0;
2741            let normalized_outside = normalized.1 <= -minimum_normal;
2742            if (raw_inside && !normalized_inside) || (raw_outside && !normalized_outside) {
2743                // Surface clipping classifies the unscaled homogeneous
2744                // coordinates. The edge shader scales every component in f32
2745                // first and only then evaluates the plane. Reject any case in
2746                // which those separately rounded operations can change side,
2747                // including a negative distance becoming inclusive `-0`.
2748                return Err(Mesh3dRenderError::InvalidEdgeProjection);
2749            }
2750        }
2751    }
2752    Ok(())
2753}
2754
2755fn shader_range_minimum_magnitude(value: ShaderValueRange) -> f64 {
2756    if value.minimum <= 0.0 && value.maximum >= 0.0 {
2757        0.0
2758    } else {
2759        value.minimum.abs().min(value.maximum.abs())
2760    }
2761}
2762
2763fn rounded_f32_product_range(left: (f64, f64), right: (f64, f64)) -> Option<(f64, f64)> {
2764    let products = [
2765        left.0 * right.0,
2766        left.0 * right.1,
2767        left.1 * right.0,
2768        left.1 * right.1,
2769    ];
2770    rounded_f32_range(
2771        products.into_iter().fold(f64::INFINITY, f64::min),
2772        products.into_iter().fold(f64::NEG_INFINITY, f64::max),
2773    )
2774}
2775
2776fn rounded_f32_add_range(
2777    left: (f64, f64),
2778    right: (f64, f64),
2779    subtract: bool,
2780) -> Option<(f64, f64)> {
2781    let (minimum, maximum) = if subtract {
2782        (left.0 - right.1, left.1 - right.0)
2783    } else {
2784        (left.0 + right.0, left.1 + right.1)
2785    };
2786    rounded_f32_range(minimum, maximum)
2787}
2788
2789fn rounded_f32_range(minimum: f64, maximum: f64) -> Option<(f64, f64)> {
2790    if !minimum.is_finite()
2791        || !maximum.is_finite()
2792        || minimum < -f64::from(MAX_PORTABLE_SHADER_VALUE)
2793        || maximum > f64::from(MAX_PORTABLE_SHADER_VALUE)
2794    {
2795        return None;
2796    }
2797    let mut minimum = f64::from(next_f32_down(minimum as f32)?);
2798    let mut maximum = f64::from(next_f32_up(maximum as f32)?);
2799    let minimum_normal = f64::from(f32::MIN_POSITIVE);
2800    if maximum > 0.0 && minimum < minimum_normal {
2801        minimum = minimum.min(0.0);
2802    }
2803    if minimum < 0.0 && maximum > -minimum_normal {
2804        maximum = maximum.max(0.0);
2805    }
2806    Some((minimum, maximum))
2807}
2808
2809fn next_f32_down(value: f32) -> Option<f32> {
2810    if !value.is_finite() {
2811        return None;
2812    }
2813    let next = if value == 0.0 {
2814        -f32::from_bits(1)
2815    } else if value > 0.0 {
2816        f32::from_bits(value.to_bits().checked_sub(1)?)
2817    } else {
2818        f32::from_bits(value.to_bits().checked_add(1)?)
2819    };
2820    next.is_finite().then_some(next)
2821}
2822
2823fn next_f32_up(value: f32) -> Option<f32> {
2824    if !value.is_finite() {
2825        return None;
2826    }
2827    let next = if value == 0.0 {
2828        f32::from_bits(1)
2829    } else if value > 0.0 {
2830        f32::from_bits(value.to_bits().checked_add(1)?)
2831    } else {
2832        f32::from_bits(value.to_bits().checked_sub(1)?)
2833    };
2834    next.is_finite().then_some(next)
2835}
2836
2837fn wgsl_division_range(numerator: (f64, f64), denominator: (f64, f64)) -> Option<(f64, f64)> {
2838    let minimum_normal = f64::from(f32::MIN_POSITIVE);
2839    let maximum_divisor = 2.0_f64.powi(126);
2840    if denominator.0 < minimum_normal || denominator.1 > maximum_divisor {
2841        return None;
2842    }
2843    let quotients = [
2844        numerator.0 / denominator.0,
2845        numerator.0 / denominator.1,
2846        numerator.1 / denominator.0,
2847        numerator.1 / denominator.1,
2848    ];
2849    let mut range = rounded_f32_range(
2850        quotients.into_iter().fold(f64::INFINITY, f64::min),
2851        quotients.into_iter().fold(f64::NEG_INFINITY, f64::max),
2852    )?;
2853    // Division permits 2.5 ULP. rounded_f32_range already contributed one
2854    // outward neighbor, so add two more on each side.
2855    for _ in 0..2 {
2856        range.0 = f64::from(next_f32_down(range.0 as f32)?);
2857        range.1 = f64::from(next_f32_up(range.1 as f32)?);
2858    }
2859    Some(range)
2860}
2861
2862fn wgsl_signed_division_range(
2863    numerator: (f64, f64),
2864    denominator: (f64, f64),
2865) -> Option<(f64, f64)> {
2866    if denominator.0 > 0.0 {
2867        wgsl_division_range(numerator, denominator)
2868    } else if denominator.1 < 0.0 {
2869        wgsl_division_range(
2870            (-numerator.1, -numerator.0),
2871            (-denominator.1, -denominator.0),
2872        )
2873    } else {
2874        None
2875    }
2876}
2877
2878fn interval_lerp_range(
2879    start: (f64, f64),
2880    end: (f64, f64),
2881    amount: (f64, f64),
2882) -> Option<(f64, f64)> {
2883    let delta = rounded_f32_add_range(end, start, true)?;
2884    let scaled_delta = rounded_f32_product_range(delta, amount)?;
2885    rounded_f32_add_range(start, scaled_delta, false)
2886}
2887
2888fn interval_clip_edge_to_frustum(
2889    normalized: NormalizedEdgeRanges,
2890) -> Result<Option<EdgeClipRanges>, Mesh3dRenderError> {
2891    let minimum_normal = f64::from(f32::MIN_POSITIVE);
2892    let mut enter = (0.0_f64, 0.0_f64);
2893    let mut exit = (1.0_f64, 1.0_f64);
2894    for (start_distance, end_distance) in normalized.planes[0].into_iter().zip(normalized.planes[1])
2895    {
2896        let start_outside = start_distance.1 <= -minimum_normal;
2897        let end_outside = end_distance.1 <= -minimum_normal;
2898        if start_outside && end_outside {
2899            return Ok(None);
2900        }
2901        if start_outside || end_outside {
2902            let denominator = rounded_f32_add_range(start_distance, end_distance, true)
2903                .ok_or(Mesh3dRenderError::InvalidEdgeProjection)?;
2904            let amount = wgsl_signed_division_range(start_distance, denominator)
2905                .ok_or(Mesh3dRenderError::InvalidEdgeProjection)?;
2906            if amount.0 < 0.0 || amount.1 > 1.0 {
2907                return Err(Mesh3dRenderError::InvalidEdgeProjection);
2908            }
2909            if start_outside {
2910                enter = (enter.0.max(amount.0), enter.1.max(amount.1));
2911            } else {
2912                exit = (exit.0.min(amount.0), exit.1.min(amount.1));
2913            }
2914        }
2915    }
2916    if enter.0 > exit.1 {
2917        return Ok(None);
2918    }
2919    if enter.1 > exit.0 {
2920        return Err(Mesh3dRenderError::InvalidEdgeProjection);
2921    }
2922    let clipped_start = std::array::from_fn(|axis| {
2923        interval_lerp_range(normalized.clip[0][axis], normalized.clip[1][axis], enter)
2924    });
2925    let clipped_end = std::array::from_fn(|axis| {
2926        interval_lerp_range(normalized.clip[0][axis], normalized.clip[1][axis], exit)
2927    });
2928    if clipped_start.iter().any(Option::is_none) || clipped_end.iter().any(Option::is_none) {
2929        return Err(Mesh3dRenderError::InvalidEdgeProjection);
2930    }
2931    let clipped = [
2932        clipped_start.map(Option::unwrap),
2933        clipped_end.map(Option::unwrap),
2934    ];
2935    if clipped[0][3].0 < minimum_normal || clipped[1][3].0 < minimum_normal {
2936        return Err(Mesh3dRenderError::InvalidEdgeProjection);
2937    }
2938    Ok(Some(clipped))
2939}
2940
2941fn projected_screen_axis_range(
2942    numerator: (f64, f64),
2943    denominator: (f64, f64),
2944    dimension: f32,
2945    inverted: bool,
2946) -> Option<(f64, f64)> {
2947    let ndc = wgsl_division_range(numerator, denominator)?;
2948    let half_ndc = rounded_f32_product_range(ndc, (0.5, 0.5))?;
2949    let normalized = rounded_f32_add_range((0.5, 0.5), half_ndc, inverted)?;
2950    rounded_f32_product_range(normalized, {
2951        let dimension = f64::from(dimension.max(1.0));
2952        (dimension, dimension)
2953    })
2954}
2955
2956fn validate_edge_projection_range(
2957    start: [(f64, f64); 4],
2958    end: [(f64, f64); 4],
2959    viewport: [f32; 4],
2960    fixed_delta: [f32; 2],
2961) -> Result<(), Mesh3dRenderError> {
2962    let start_x = projected_screen_axis_range(start[0], start[3], viewport[0], false)
2963        .ok_or(Mesh3dRenderError::InvalidEdgeProjection)?;
2964    let start_y = projected_screen_axis_range(start[1], start[3], viewport[1], true)
2965        .ok_or(Mesh3dRenderError::InvalidEdgeProjection)?;
2966    let end_x = projected_screen_axis_range(end[0], end[3], viewport[0], false)
2967        .ok_or(Mesh3dRenderError::InvalidEdgeProjection)?;
2968    let end_y = projected_screen_axis_range(end[1], end[3], viewport[1], true)
2969        .ok_or(Mesh3dRenderError::InvalidEdgeProjection)?;
2970    let delta_x = rounded_f32_add_range(end_x, start_x, true)
2971        .ok_or(Mesh3dRenderError::InvalidEdgeProjection)?;
2972    let delta_y = rounded_f32_add_range(end_y, start_y, true)
2973        .ok_or(Mesh3dRenderError::InvalidEdgeProjection)?;
2974    let component_minimum = |range: (f64, f64)| {
2975        if range.0 > 0.0 {
2976            range.0
2977        } else if range.1 < 0.0 {
2978            -range.1
2979        } else {
2980            0.0
2981        }
2982    };
2983    let minimum_length = component_minimum(delta_x).hypot(component_minimum(delta_y));
2984    let maximum_length = delta_x
2985        .0
2986        .abs()
2987        .max(delta_x.1.abs())
2988        .hypot(delta_y.0.abs().max(delta_y.1.abs()));
2989    let extrusion_threshold = 0.0001_f64;
2990    if !minimum_length.is_finite()
2991        || !maximum_length.is_finite()
2992        || (minimum_length <= extrusion_threshold && maximum_length > extrusion_threshold)
2993    {
2994        return Err(Mesh3dRenderError::InvalidEdgeProjection);
2995    }
2996    if maximum_length <= extrusion_threshold {
2997        return Ok(());
2998    }
2999
3000    let fixed_x = f64::from(fixed_delta[0]);
3001    let fixed_y = f64::from(fixed_delta[1]);
3002    let fixed_length = fixed_x.hypot(fixed_y);
3003    let minimum_dot = fixed_x * if fixed_x >= 0.0 { delta_x.0 } else { delta_x.1 }
3004        + fixed_y * if fixed_y >= 0.0 { delta_y.0 } else { delta_y.1 };
3005    if !fixed_length.is_finite()
3006        || fixed_length <= extrusion_threshold
3007        || !minimum_dot.is_finite()
3008        || minimum_dot <= 0.0
3009    {
3010        return Err(Mesh3dRenderError::InvalidEdgeProjection);
3011    }
3012    Ok(())
3013}
3014
3015fn validate_edge_projection(
3016    mesh: &Mesh3d,
3017    model_rows: [[f32; 4]; 3],
3018    camera_rows: [[f32; 4]; 4],
3019    style: WireframeStyle3d,
3020    viewport: [f32; 4],
3021) -> Result<(), Mesh3dRenderError> {
3022    let style_sources = [
3023        style.visible_width().get(),
3024        style.hidden_width().map_or(0.0, LogicalPixels::get),
3025        style
3026            .hidden_pattern()
3027            .map_or(0.0, |pattern| pattern.0.get()),
3028        style
3029            .hidden_pattern()
3030            .map_or(0.0, |pattern| pattern.1.get()),
3031    ];
3032    if !viewport
3033        .into_iter()
3034        .chain(style_sources)
3035        .all(is_portable_shader_source)
3036    {
3037        return Err(Mesh3dRenderError::InvalidEdgeProjection);
3038    }
3039    let pixels_per_logical = PhysicalPerLogical::new(viewport[2])
3040        .map_err(|_| Mesh3dRenderError::InvalidEdgeProjection)?;
3041    let visible_raster = edge_raster_envelope(style.visible_width(), pixels_per_logical)
3042        .ok_or(Mesh3dRenderError::InvalidEdgeProjection)?;
3043    let hidden_raster = match style.hidden_width() {
3044        Some(width) => Some(
3045            edge_raster_envelope(width, pixels_per_logical)
3046                .ok_or(Mesh3dRenderError::InvalidEdgeProjection)?,
3047        ),
3048        None => None,
3049    };
3050    let hidden_period = style.hidden_pattern().map(|(dash, gap)| {
3051        let dash = dash.get();
3052        let gap = gap.get();
3053        if is_nonzero_subnormal(dash) || is_nonzero_subnormal(gap) {
3054            return f32::NAN;
3055        }
3056        let period = f64::from(dash) + f64::from(gap);
3057        if period > f64::from(MAX_PORTABLE_SHADER_VALUE) {
3058            f32::NAN
3059        } else {
3060            dash + gap
3061        }
3062    });
3063    if hidden_period.is_some_and(|period| !period.is_finite()) {
3064        return Err(Mesh3dRenderError::InvalidEdgeProjection);
3065    }
3066    validate_hidden_dash_envelope(viewport, hidden_period)?;
3067
3068    for edge in mesh.display_edges() {
3069        let mut clip_ranges = [[ShaderValueRange::exact(0.0); 4]; 2];
3070        let mut clip = [[0.0_f32; 4]; 2];
3071        for (endpoint_index, vertex_index) in [edge.start(), edge.end()].into_iter().enumerate() {
3072            let vertex = mesh.vertices()[vertex_index as usize];
3073            clip_ranges[endpoint_index] =
3074                shader_clip_point_ranges(vertex, model_rows, camera_rows)?;
3075            validate_clip_classification(clip_ranges[endpoint_index])?;
3076            clip[endpoint_index] = clip_ranges[endpoint_index].map(|value| value.fixed);
3077        }
3078        let normalized_ranges =
3079            validate_edge_homogeneous_classification(clip_ranges[0], clip_ranges[1])?;
3080        if clip_ranges_share_outside_plane(normalized_ranges.planes[0], normalized_ranges.planes[1])
3081        {
3082            continue;
3083        }
3084        let Some(clipped_ranges) = interval_clip_edge_to_frustum(normalized_ranges)? else {
3085            continue;
3086        };
3087        let Some(clipped) = clip_edge_to_frustum(clip[0], clip[1])? else {
3088            // The interval proof established stable visibility; disagreement
3089            // with the host diagnostic fold is not portable.
3090            return Err(Mesh3dRenderError::InvalidEdgeProjection);
3091        };
3092        let mut screen = [[0.0_f32; 2]; 2];
3093        for (endpoint_index, clip) in clipped.into_iter().enumerate() {
3094            let ndc_x = clip[0] / clip[3];
3095            let ndc_y = clip[1] / clip[3];
3096            screen[endpoint_index] = [
3097                (ndc_x * 0.5 + 0.5) * viewport[0],
3098                (0.5 - ndc_y * 0.5) * viewport[1],
3099            ];
3100            if !screen[endpoint_index][0].is_finite() || !screen[endpoint_index][1].is_finite() {
3101                return Err(Mesh3dRenderError::InvalidEdgeProjection);
3102            }
3103        }
3104        let delta_x = screen[1][0] - screen[0][0];
3105        let delta_y = screen[1][1] - screen[0][1];
3106        let length_squared = delta_x * delta_x + delta_y * delta_y;
3107        if !delta_x.is_finite() || !delta_y.is_finite() || !length_squared.is_finite() {
3108            return Err(Mesh3dRenderError::InvalidEdgeProjection);
3109        }
3110        let threshold_squared = 0.0001_f32 * 0.0001_f32;
3111        if length_squared > threshold_squared * 0.99 && length_squared < threshold_squared * 1.01 {
3112            return Err(Mesh3dRenderError::InvalidEdgeProjection);
3113        }
3114        let screen_length = length_squared.sqrt();
3115        validate_edge_projection_range(
3116            clipped_ranges[0],
3117            clipped_ranges[1],
3118            viewport,
3119            [delta_x, delta_y],
3120        )?;
3121        let screen_normal = if screen_length > 0.0001 {
3122            [-delta_y / screen_length, delta_x / screen_length]
3123        } else {
3124            [0.0, 0.0]
3125        };
3126        if !screen_normal.into_iter().all(f32::is_finite) {
3127            return Err(Mesh3dRenderError::InvalidEdgeProjection);
3128        }
3129        validate_edge_shader_arithmetic(clipped_ranges, viewport, visible_raster, None)?;
3130        if let Some(hidden_raster) = hidden_raster {
3131            validate_edge_shader_arithmetic(
3132                clipped_ranges,
3133                viewport,
3134                hidden_raster,
3135                hidden_period,
3136            )?;
3137        }
3138    }
3139    Ok(())
3140}
3141
3142fn validate_hidden_dash_envelope(
3143    viewport: [f32; 4],
3144    dash_period: Option<f32>,
3145) -> Result<(), Mesh3dRenderError> {
3146    let Some(period) = dash_period else {
3147        return Ok(());
3148    };
3149    if period <= 0.0 || is_nonzero_subnormal(period) {
3150        return Err(Mesh3dRenderError::InvalidEdgeProjection);
3151    }
3152
3153    // Frustum-clipped endpoints lie inside the physical target, regardless of
3154    // which legal association/FMA choice produced their clip coordinates.
3155    // Validate dash arithmetic against that complete envelope rather than the
3156    // one fixed CPU fold used by the diagnostic clipping mirror below.
3157    let width = f64::from(viewport[0]);
3158    let height = f64::from(viewport[1]);
3159    let pixels_per_logical = f64::from(viewport[2]);
3160    let screen_diagonal = width.hypot(height) * (1.0 + 8.0 * f64::from(f32::EPSILON));
3161    let maximum_logical_distance = screen_diagonal / pixels_per_logical;
3162    let maximum_repetition = maximum_logical_distance / f64::from(period);
3163    if !screen_diagonal.is_finite()
3164        || !maximum_logical_distance.is_finite()
3165        || !maximum_repetition.is_finite()
3166        || maximum_logical_distance > f64::from(MAX_PORTABLE_SHADER_VALUE)
3167        || maximum_repetition > f64::from(MAX_PORTABLE_SHADER_VALUE)
3168    {
3169        return Err(Mesh3dRenderError::InvalidEdgeProjection);
3170    }
3171    Ok(())
3172}
3173
3174fn clip_edge_to_frustum(
3175    start: [f32; 4],
3176    end: [f32; 4],
3177) -> Result<Option<[[f32; 4]; 2]>, Mesh3dRenderError> {
3178    Ok(clip_edge_to_frustum_details(start, end)?.map(|clipped| clipped.clip))
3179}
3180
3181#[derive(Debug, Clone, Copy, PartialEq)]
3182struct ClippedEdgeCpu {
3183    clip: [[f32; 4]; 2],
3184    enter: f32,
3185    exit: f32,
3186}
3187
3188fn clip_edge_to_frustum_details(
3189    start: [f32; 4],
3190    end: [f32; 4],
3191) -> Result<Option<ClippedEdgeCpu>, Mesh3dRenderError> {
3192    let pair_max = start
3193        .into_iter()
3194        .chain(end)
3195        .map(f32::abs)
3196        .fold(0.0_f32, f32::max);
3197    if !pair_max.is_finite() {
3198        return Err(Mesh3dRenderError::InvalidEdgeProjection);
3199    }
3200    if pair_max > MAX_PORTABLE_SHADER_VALUE {
3201        return Err(Mesh3dRenderError::InvalidEdgeProjection);
3202    }
3203    let homogeneous_scale = 1.0 / pair_max.max(1.0);
3204    let start = start.map(|component| component * homogeneous_scale);
3205    let end = end.map(|component| component * homogeneous_scale);
3206    let start_distances = clip_plane_distances(start)?;
3207    let end_distances = clip_plane_distances(end)?;
3208    let mut enter = 0.0_f32;
3209    let mut exit = 1.0_f32;
3210    for (start_distance, end_distance) in start_distances.into_iter().zip(end_distances) {
3211        if start_distance < 0.0 && end_distance < 0.0 {
3212            return Ok(None);
3213        }
3214        if start_distance < 0.0 || end_distance < 0.0 {
3215            let denominator = start_distance - end_distance;
3216            let amount = start_distance / denominator;
3217            if !denominator.is_finite() || !amount.is_finite() {
3218                return Err(Mesh3dRenderError::InvalidEdgeProjection);
3219            }
3220            if start_distance < 0.0 {
3221                enter = enter.max(amount);
3222            } else {
3223                exit = exit.min(amount);
3224            }
3225        }
3226    }
3227    if enter > exit {
3228        return Ok(None);
3229    }
3230    let clipped_start = shader_lerp_clip(start, end, enter)?;
3231    let clipped_end = shader_lerp_clip(start, end, exit)?;
3232    if clipped_start[3] <= 0.0 || clipped_end[3] <= 0.0 {
3233        return Ok(None);
3234    }
3235    Ok(Some(ClippedEdgeCpu {
3236        clip: [clipped_start, clipped_end],
3237        enter,
3238        exit,
3239    }))
3240}
3241
3242fn clip_plane_distances(clip: [f32; 4]) -> Result<[f32; 6], Mesh3dRenderError> {
3243    let add = |left: f32, right: f32| {
3244        let result = left + right;
3245        result
3246            .is_finite()
3247            .then_some(result)
3248            .ok_or(Mesh3dRenderError::InvalidEdgeProjection)
3249    };
3250    let subtract = |left: f32, right: f32| {
3251        let result = left - right;
3252        result
3253            .is_finite()
3254            .then_some(result)
3255            .ok_or(Mesh3dRenderError::InvalidEdgeProjection)
3256    };
3257    Ok([
3258        add(clip[3], clip[0])?,
3259        subtract(clip[3], clip[0])?,
3260        add(clip[3], clip[1])?,
3261        subtract(clip[3], clip[1])?,
3262        clip[2],
3263        subtract(clip[3], clip[2])?,
3264    ])
3265}
3266
3267fn shader_lerp_clip(
3268    start: [f32; 4],
3269    end: [f32; 4],
3270    amount: f32,
3271) -> Result<[f32; 4], Mesh3dRenderError> {
3272    let mut output = [0.0_f32; 4];
3273    for axis in 0..4 {
3274        let delta = end[axis] - start[axis];
3275        let value = start[axis] + delta * amount;
3276        if !delta.is_finite() || !value.is_finite() {
3277            return Err(Mesh3dRenderError::InvalidEdgeProjection);
3278        }
3279        output[axis] = value;
3280    }
3281    Ok(output)
3282}
3283
3284#[derive(Debug, Clone, Copy)]
3285struct EdgeRasterEnvelope {
3286    physical_half_width: f32,
3287    raster_half_width: f32,
3288}
3289
3290fn edge_raster_envelope(
3291    logical_width: LogicalPixels,
3292    pixels_per_logical: PhysicalPerLogical,
3293) -> Option<EdgeRasterEnvelope> {
3294    let logical_width = logical_width.get();
3295    let pixels_per_logical = pixels_per_logical.get();
3296    if !is_portable_shader_source(logical_width) || !is_portable_shader_source(pixels_per_logical) {
3297        return None;
3298    }
3299    let physical_half_width_f64 = f64::from(logical_width) * f64::from(pixels_per_logical) * 0.5;
3300    let raster_half_width_f64 = (physical_half_width_f64 + 0.5).max(1.0);
3301    let maximum = f64::from(MAX_PORTABLE_SHADER_VALUE);
3302    if !physical_half_width_f64.is_finite()
3303        || physical_half_width_f64 <= 0.0
3304        || raster_half_width_f64 * 2.0 > maximum
3305    {
3306        return None;
3307    }
3308    let physical_half_width = logical_width * pixels_per_logical * 0.5;
3309    let raster_half_width = (physical_half_width + 0.5).max(1.0);
3310    let doubled_raster_width = raster_half_width * 2.0;
3311    (physical_half_width.is_finite()
3312        && physical_half_width > 0.0
3313        && raster_half_width.is_finite()
3314        && doubled_raster_width.is_finite())
3315    .then_some(EdgeRasterEnvelope {
3316        physical_half_width,
3317        raster_half_width,
3318    })
3319}
3320
3321fn validate_edge_shader_arithmetic(
3322    clipped: EdgeClipRanges,
3323    viewport: [f32; 4],
3324    raster: EdgeRasterEnvelope,
3325    dash_period: Option<f32>,
3326) -> Result<(), Mesh3dRenderError> {
3327    let maximum_screen_length = f64::from(viewport[0]).hypot(f64::from(viewport[1]))
3328        * (1.0 + 8.0 * f64::from(f32::EPSILON));
3329    let logical_distance = maximum_screen_length / f64::from(viewport[2]);
3330    if !maximum_screen_length.is_finite()
3331        || !logical_distance.is_finite()
3332        || logical_distance > f64::from(MAX_PORTABLE_SHADER_VALUE)
3333        || !(raster.physical_half_width + 0.5).is_finite()
3334        || !(raster.raster_half_width * 2.0).is_finite()
3335    {
3336        return Err(Mesh3dRenderError::InvalidEdgeProjection);
3337    }
3338    if let Some(period) = dash_period {
3339        let repetition = logical_distance / f64::from(period);
3340        let repeated_distance = repetition.floor() * f64::from(period);
3341        let within_period = logical_distance - repeated_distance;
3342        if !period.is_finite()
3343            || period <= 0.0
3344            || !repetition.is_finite()
3345            || !repeated_distance.is_finite()
3346            || !within_period.is_finite()
3347            || repetition.abs() > f64::from(MAX_PORTABLE_SHADER_VALUE)
3348            || repeated_distance.abs() > f64::from(MAX_PORTABLE_SHADER_VALUE)
3349            || within_period.abs() > f64::from(MAX_PORTABLE_SHADER_VALUE)
3350        {
3351            return Err(Mesh3dRenderError::InvalidEdgeProjection);
3352        }
3353    }
3354
3355    let dimensions = [viewport[0].max(1.0), viewport[1].max(1.0)];
3356    for axis in 0..2 {
3357        // A normalized screen direction can place the full raster half-width
3358        // on either axis. Use that complete envelope rather than one host
3359        // normalization result.
3360        let normalized_component_bound = 1.0 + 4.0 * f64::from(f32::EPSILON);
3361        let screen_offset = rounded_f32_product_range(
3362            (-normalized_component_bound, normalized_component_bound),
3363            (
3364                f64::from(raster.raster_half_width),
3365                f64::from(raster.raster_half_width),
3366            ),
3367        )
3368        .ok_or(Mesh3dRenderError::InvalidEdgeProjection)?;
3369        let doubled_screen_offset = rounded_f32_product_range(screen_offset, (2.0, 2.0))
3370            .ok_or(Mesh3dRenderError::InvalidEdgeProjection)?;
3371        let ndc_offset = wgsl_division_range(
3372            doubled_screen_offset,
3373            (f64::from(dimensions[axis]), f64::from(dimensions[axis])),
3374        )
3375        .ok_or(Mesh3dRenderError::InvalidEdgeProjection)?;
3376        for endpoint in clipped {
3377            let offset = rounded_f32_product_range(ndc_offset, endpoint[3])
3378                .ok_or(Mesh3dRenderError::InvalidEdgeProjection)?;
3379            if rounded_f32_add_range(endpoint[axis], offset, false).is_none() {
3380                return Err(Mesh3dRenderError::InvalidEdgeProjection);
3381            }
3382        }
3383    }
3384    Ok(())
3385}
3386
3387#[derive(Debug, Clone, Copy)]
3388struct ShaderValueRange {
3389    fixed: f32,
3390    minimum: f64,
3391    maximum: f64,
3392}
3393
3394impl ShaderValueRange {
3395    fn exact(value: f32) -> Self {
3396        Self {
3397            fixed: value,
3398            minimum: f64::from(value),
3399            maximum: f64::from(value),
3400        }
3401    }
3402}
3403
3404fn shader_dot_range(
3405    row: [f32; 4],
3406    point: [ShaderValueRange; 4],
3407) -> Result<ShaderValueRange, Mesh3dRenderError> {
3408    for axis in 0..4 {
3409        if !is_portable_shader_source(row[axis])
3410            || !is_portable_shader_source(point[axis].fixed)
3411            || point[axis].minimum < -f64::from(MAX_PORTABLE_SHADER_VALUE)
3412            || point[axis].maximum > f64::from(MAX_PORTABLE_SHADER_VALUE)
3413            || (point[axis].minimum != 0.0
3414                && point[axis].minimum.abs() < f64::from(f32::MIN_POSITIVE))
3415            || (point[axis].maximum != 0.0
3416                && point[axis].maximum.abs() < f64::from(f32::MIN_POSITIVE))
3417        {
3418            return Err(Mesh3dRenderError::InvalidGeometryTransform);
3419        }
3420    }
3421    let terms: [(f64, f64); 4] = std::array::from_fn(|axis| {
3422        interval_products_f64(row[axis], point[axis].minimum, point[axis].maximum)
3423    });
3424    let (minimum, maximum) =
3425        shader_interval_sum_range(terms).ok_or(Mesh3dRenderError::InvalidGeometryTransform)?;
3426    let mut result = 0.0_f32;
3427    for axis in 0..4 {
3428        let product = row[axis] * point[axis].fixed;
3429        result += product;
3430        if !product.is_finite() || !result.is_finite() {
3431            return Err(Mesh3dRenderError::InvalidGeometryTransform);
3432        }
3433    }
3434    Ok(ShaderValueRange {
3435        fixed: result,
3436        minimum,
3437        maximum,
3438    })
3439}
3440
3441#[cfg(test)]
3442fn shader_dot(row: [f32; 4], point: [f32; 4]) -> Result<f32, Mesh3dRenderError> {
3443    shader_dot_range(row, point.map(ShaderValueRange::exact)).map(|value| value.fixed)
3444}
3445
3446#[cfg(test)]
3447fn encode_scene_pass(
3448    encoder: &mut wgpu::CommandEncoder,
3449    renderer: &Mesh3dRenderer,
3450    color_view: &wgpu::TextureView,
3451    depth_view: &wgpu::TextureView,
3452    background: Color,
3453    instances: &[Mesh3dInstance],
3454) {
3455    encode_ordered_scene_pass(
3456        encoder,
3457        renderer,
3458        color_view,
3459        depth_view,
3460        background,
3461        instances,
3462        &[],
3463        None,
3464    );
3465}
3466
3467#[allow(clippy::too_many_arguments)]
3468fn encode_ordered_scene_pass(
3469    encoder: &mut wgpu::CommandEncoder,
3470    renderer: &Mesh3dRenderer,
3471    color_view: &wgpu::TextureView,
3472    depth_view: &wgpu::TextureView,
3473    background: Color,
3474    instances: &[Mesh3dInstance],
3475    order: &[material::SurfaceDraw],
3476    timestamp_writes: Option<wgpu::RenderPassTimestampWrites<'_>>,
3477) {
3478    let mut pass = encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
3479        label: Some("sim-engine retained 3D mesh pass"),
3480        color_attachments: &[Some(wgpu::RenderPassColorAttachment {
3481            view: color_view,
3482            depth_slice: None,
3483            resolve_target: None,
3484            ops: wgpu::Operations {
3485                load: wgpu::LoadOp::Clear(premultiplied_wgpu_color(background)),
3486                store: wgpu::StoreOp::Store,
3487            },
3488        })],
3489        depth_stencil_attachment: Some(wgpu::RenderPassDepthStencilAttachment {
3490            view: depth_view,
3491            depth_ops: Some(wgpu::Operations {
3492                load: wgpu::LoadOp::Clear(1.0),
3493                store: wgpu::StoreOp::Store,
3494            }),
3495            stencil_ops: None,
3496        }),
3497        timestamp_writes,
3498        occlusion_query_set: None,
3499        multiview_mask: None,
3500    });
3501    pass.set_pipeline(&renderer.pipeline);
3502    pass.set_bind_group(0, &renderer.camera_bind_group, &[]);
3503    let mut insertion = instances
3504        .iter()
3505        .filter(|instance| instance.visible)
3506        .enumerate();
3507    let mut sorted = order.iter();
3508    loop {
3509        let next = if order.is_empty() {
3510            insertion.next()
3511        } else {
3512            sorted
3513                .next()
3514                .map(|entry| (entry.visible_index, &instances[entry.scene_index]))
3515        };
3516        let Some((instance_index, instance)) = next else {
3517            break;
3518        };
3519        if instance.style.surface_style().is_none() || instance.mesh.index_count == 0 {
3520            continue;
3521        }
3522        let instance_start =
3523            (instance_index * std::mem::size_of::<MeshInstanceGpu>()) as wgpu::BufferAddress;
3524        let instance_end =
3525            instance_start + std::mem::size_of::<MeshInstanceGpu>() as wgpu::BufferAddress;
3526        let Some(surface_style) = instance.style.surface_style() else {
3527            continue;
3528        };
3529        let material = instance.mesh.material();
3530        let colored = instance.mesh.color_buffer.is_some();
3531        if let Some(material) = material {
3532            pass.set_bind_group(1, material.bind_group(), &[]);
3533        }
3534        let object = renderer.clipped_surface_objects.get(instance_index);
3535        if let Some(range) = object.and_then(|object| object.generated.as_ref()) {
3536            if range.is_empty() {
3537                continue;
3538            }
3539            let Some(buffer) = &renderer.clipped_surface_buffer else {
3540                continue;
3541            };
3542            let pipelines = match (material.is_some(), colored) {
3543                (false, false) => &renderer.clipped_surface_pipeline,
3544                (false, true) => &renderer.colored_clipped_pipeline,
3545                (true, false) => &renderer.textures.clipped_pipeline,
3546                (true, true) => &renderer.textures.colored_clipped_pipeline,
3547            };
3548            pass.set_pipeline(pipelines.for_style(surface_style));
3549            let stride = std::mem::size_of::<SurfaceClipVertex>() as u64;
3550            pass.set_vertex_buffer(
3551                0,
3552                buffer.slice(u64::from(range.start) * stride..u64::from(range.end) * stride),
3553            );
3554            pass.set_vertex_buffer(
3555                1,
3556                renderer.instance_buffer.slice(instance_start..instance_end),
3557            );
3558            if let (Some(buffer), Some(colors)) = (
3559                &renderer.clipped_color_buffer,
3560                object.and_then(|object| object.generated_colors.as_ref()),
3561            ) {
3562                let stride = std::mem::size_of::<MeshColorGpu>() as u64;
3563                pass.set_vertex_buffer(
3564                    2,
3565                    buffer.slice(u64::from(colors.start) * stride..u64::from(colors.end) * stride),
3566                );
3567            }
3568            if let (Some(buffer), Some(lighting)) = (
3569                &renderer.clipped_lighting_buffer,
3570                object.and_then(|object| object.generated_lighting.as_ref()),
3571            ) {
3572                let stride = std::mem::size_of::<SurfaceLightingVertex>() as u64;
3573                pass.set_vertex_buffer(
3574                    2 + u32::from(colored),
3575                    buffer.slice(
3576                        u64::from(lighting.start) * stride..u64::from(lighting.end) * stride,
3577                    ),
3578                );
3579            }
3580            pass.draw(0..range.end - range.start, 0..1);
3581            continue;
3582        }
3583        let Some(index_buffer) = &instance.mesh.index_buffer else {
3584            continue;
3585        };
3586        let pipelines = match (material.is_some(), colored) {
3587            (false, false) => &renderer.pipeline,
3588            (false, true) => &renderer.colored_pipeline,
3589            (true, false) => &renderer.textures.retained_pipeline,
3590            (true, true) => &renderer.textures.colored_retained_pipeline,
3591        };
3592        pass.set_pipeline(pipelines.for_style(surface_style));
3593        pass.set_vertex_buffer(0, instance.mesh.vertex_buffer.slice(..));
3594        let instance_slot = if material.is_some() {
3595            if let Some(coordinates) = &instance.mesh.texture_coordinate_buffer {
3596                pass.set_vertex_buffer(1, coordinates.slice(..));
3597            }
3598            2
3599        } else {
3600            1
3601        };
3602        pass.set_vertex_buffer(
3603            instance_slot,
3604            renderer.instance_buffer.slice(instance_start..instance_end),
3605        );
3606        if let Some(buffer) = &instance.mesh.color_buffer {
3607            pass.set_vertex_buffer(instance_slot + 1, buffer.slice(..));
3608        }
3609        if surface_style.lighting() == SurfaceLighting3d::Lambert
3610            && let Some(buffer) = &instance.mesh.normal_buffer
3611        {
3612            pass.set_vertex_buffer(instance_slot + 1 + u32::from(colored), buffer.slice(..));
3613        }
3614        pass.set_index_buffer(index_buffer.slice(..), wgpu::IndexFormat::Uint32);
3615        pass.draw_indexed(0..instance.mesh.index_count, 0, 0..1);
3616    }
3617    pass.set_pipeline(&renderer.hidden_edge_pipeline);
3618    for (object_index, instance) in instances
3619        .iter()
3620        .filter(|instance| instance.visible)
3621        .enumerate()
3622    {
3623        let Some(style) = instance.wireframe() else {
3624            continue;
3625        };
3626        let Some(edge_buffer) = instance.mesh.edge_buffer.as_ref() else {
3627            continue;
3628        };
3629        if !style.hidden_enabled() || instance.mesh.edge_count == 0 {
3630            continue;
3631        }
3632        let dynamic_offset = (object_index * renderer.edge_object_stride) as u32;
3633        pass.set_bind_group(1, &renderer.edge_object_bind_group, &[dynamic_offset]);
3634        if let Some(range) = renderer
3635            .clipped_surface_objects
3636            .get(object_index)
3637            .and_then(|object| object.generated_edges.as_ref())
3638        {
3639            if let Some(buffer) = &renderer.clipped_edge_buffer
3640                && !range.is_empty()
3641            {
3642                pass.set_pipeline(&renderer.clipped_hidden_edge_pipeline);
3643                pass.set_vertex_buffer(0, buffer.slice(..));
3644                pass.draw(0..6, range.clone());
3645            }
3646            continue;
3647        }
3648        pass.set_pipeline(&renderer.hidden_edge_pipeline);
3649        pass.set_vertex_buffer(0, edge_buffer.slice(..));
3650        pass.draw(0..6, 0..instance.mesh.edge_count);
3651    }
3652    pass.set_pipeline(&renderer.visible_edge_pipeline);
3653    for (object_index, instance) in instances
3654        .iter()
3655        .filter(|instance| instance.visible)
3656        .enumerate()
3657    {
3658        if instance.wireframe().is_none() || instance.mesh.edge_count == 0 {
3659            continue;
3660        }
3661        let Some(edge_buffer) = instance.mesh.edge_buffer.as_ref() else {
3662            continue;
3663        };
3664        let dynamic_offset = (object_index * renderer.edge_object_stride) as u32;
3665        pass.set_bind_group(1, &renderer.edge_object_bind_group, &[dynamic_offset]);
3666        if let Some(range) = renderer
3667            .clipped_surface_objects
3668            .get(object_index)
3669            .and_then(|object| object.generated_edges.as_ref())
3670        {
3671            if let Some(buffer) = &renderer.clipped_edge_buffer
3672                && !range.is_empty()
3673            {
3674                pass.set_pipeline(&renderer.clipped_visible_edge_pipeline);
3675                pass.set_vertex_buffer(0, buffer.slice(..));
3676                pass.draw(0..6, range.clone());
3677            }
3678            continue;
3679        }
3680        pass.set_pipeline(&renderer.visible_edge_pipeline);
3681        pass.set_vertex_buffer(0, edge_buffer.slice(..));
3682        pass.draw(0..6, 0..instance.mesh.edge_count);
3683    }
3684}
3685
3686#[cfg(test)]
3687pub(super) fn assert_gpu_depth_contract(
3688    device: &wgpu::Device,
3689    queue: &wgpu::Queue,
3690    format: wgpu::TextureFormat,
3691) {
3692    dynamic::assert_gpu_dynamic_contract(device, queue, format);
3693    vertex_color_tests::assert_gpu_vertex_color_contract(device, queue, format);
3694    material_tests::assert_gpu_material_contract(device, queue, format);
3695    lighting_tests::assert_gpu_lighting_contract(device, queue, format);
3696    material_resource_tests::assert_gpu_sort_budget(device, queue, format);
3697    color_budget_tests::assert_gpu_color_budget(device, queue, format);
3698    surface::assert_gpu_surface_contract(device, queue, format);
3699    surface::assert_gpu_native_surface_policy(device, queue, format);
3700    surface::assert_gpu_native_edge_validation(device, queue, format);
3701    texture::assert_gpu_texture_contract(device, queue, format);
3702    texture::assert_gpu_texture_lifecycle(device, queue, format);
3703    native_acceptance_tests::assert_gpu_native_acceptance(device, queue, format);
3704    assert_gpu_clip_equivalence(device, queue);
3705    let identity = Arc::new(());
3706    let mut renderer = Mesh3dRenderer::new(device, format);
3707    let vertices = vec![
3708        Vec3::new(-1.0, -1.0, 0.0).unwrap(),
3709        Vec3::new(1.0, -1.0, 0.0).unwrap(),
3710        Vec3::new(0.0, 1.0, 0.0).unwrap(),
3711    ];
3712    let near_triangle = Mesh3d::with_display_edges(
3713        vertices.clone(),
3714        vec![0, 1, 2],
3715        vec![MeshEdge3d::new(0, 1).unwrap()],
3716    )
3717    .unwrap();
3718    let far_triangle = Mesh3d::with_display_edges(
3719        vertices,
3720        vec![0, 1, 2],
3721        vec![MeshEdge3d::new(0, 2).unwrap()],
3722    )
3723    .unwrap();
3724    let near_mesh = create_retained_mesh(device, queue, Arc::clone(&identity), near_triangle)
3725        .expect("3D test mesh should upload");
3726    let far_mesh = create_retained_mesh(device, queue, Arc::clone(&identity), far_triangle)
3727        .expect("3D test mesh should upload");
3728    let near_crossing_edge = Mesh3d::with_display_edges(
3729        vec![
3730            Vec3::new(0.0, 0.0, 4.95).unwrap(),
3731            Vec3::new(0.5, 0.5, 4.0).unwrap(),
3732        ],
3733        Vec::new(),
3734        vec![MeshEdge3d::new(0, 1).unwrap()],
3735    )
3736    .unwrap();
3737    let near_crossing_mesh =
3738        create_retained_mesh(device, queue, Arc::clone(&identity), near_crossing_edge)
3739            .expect("near-crossing 3D test edge should upload");
3740    let classification_edge = Mesh3d::with_display_edges(
3741        vec![
3742            Vec3::new(-0.5, -0.5, 0.0).unwrap(),
3743            Vec3::new(0.5, -0.5, 0.0).unwrap(),
3744        ],
3745        Vec::new(),
3746        vec![MeshEdge3d::new(0, 1).unwrap()],
3747    )
3748    .unwrap();
3749    let classification_mesh =
3750        create_retained_mesh(device, queue, Arc::clone(&identity), classification_edge)
3751            .expect("classification test edge should upload");
3752    let projection = Projection3d::perspective(0.927_295_2, 1.0, world(0.1), world(20.0)).unwrap();
3753    let camera = Camera3d::look_at(
3754        Vec3::new(0.0, 0.0, 5.0).unwrap(),
3755        Vec3::ZERO,
3756        Vec3::Y,
3757        projection,
3758    )
3759    .unwrap();
3760    let camera_uniform = Camera3dUniform::new(camera, 64, 64, physical_per_logical(1.0)).unwrap();
3761    let near_transform = Transform3d::new(
3762        Vec3::new(0.0, 0.0, 1.0).unwrap(),
3763        Rotation3d::IDENTITY,
3764        Vec3::new(1.0, 1.0, 1.0).unwrap(),
3765    )
3766    .unwrap();
3767    let far_transform = Transform3d::new(
3768        Vec3::new(0.0, 0.0, -1.0).unwrap(),
3769        Rotation3d::IDENTITY,
3770        Vec3::new(1.0, 1.0, 1.0).unwrap(),
3771    )
3772    .unwrap();
3773    let mut scene = Scene3d::new(Color::BLACK).unwrap();
3774    let near_id = scene
3775        .try_push(
3776            &near_mesh,
3777            near_transform,
3778            MeshStyle3d::surface(SurfaceStyle3d::opaque(Color::rgb(0.0, 1.0, 0.0)).unwrap())
3779                .with_wireframe(
3780                    WireframeStyle3d::visible(Color::rgb(0.0, 0.0, 1.0), logical(2.0))
3781                        .unwrap()
3782                        .with_hidden(
3783                            Color::rgb(1.0, 0.0, 1.0),
3784                            logical(2.0),
3785                            logical(4.0),
3786                            logical(4.0),
3787                        )
3788                        .unwrap(),
3789                ),
3790        )
3791        .unwrap();
3792    let mut other_scene = Scene3d::new(Color::BLACK).unwrap();
3793    let other_scene_id = other_scene
3794        .try_push(
3795            &near_mesh,
3796            Transform3d::IDENTITY,
3797            MeshStyle3d::surface(SurfaceStyle3d::opaque(Color::WHITE).unwrap()),
3798        )
3799        .unwrap();
3800    assert_eq!(near_id.get(), other_scene_id.get());
3801    assert_ne!(near_id, other_scene_id);
3802    assert_eq!(
3803        other_scene.set_visible(near_id, false),
3804        Err(Scene3dError::ObjectNotFound { object_id: near_id })
3805    );
3806    assert_eq!(other_scene.visible_object_count(), 1);
3807    assert_eq!(
3808        scene.set_visible(other_scene_id, false),
3809        Err(Scene3dError::ObjectNotFound {
3810            object_id: other_scene_id,
3811        })
3812    );
3813    assert_eq!(scene.visible_object_count(), 1);
3814    let far_id = scene
3815        .try_push(
3816            &far_mesh,
3817            far_transform,
3818            MeshStyle3d::surface(SurfaceStyle3d::opaque(Color::rgb(1.0, 0.0, 0.0)).unwrap())
3819                .with_wireframe(
3820                    WireframeStyle3d::visible(Color::rgb(1.0, 0.0, 0.0), logical(2.0))
3821                        .unwrap()
3822                        .with_hidden(Color::WHITE, logical(2.0), logical(4.0), logical(4.0))
3823                        .unwrap(),
3824                ),
3825        )
3826        .unwrap();
3827    scene
3828        .try_push(
3829            &near_crossing_mesh,
3830            Transform3d::IDENTITY,
3831            MeshStyle3d::wireframe(
3832                WireframeStyle3d::visible(Color::rgb(1.0, 1.0, 0.0), logical(2.0)).unwrap(),
3833            ),
3834        )
3835        .unwrap();
3836    let coplanar_transform = Transform3d::new(
3837        Vec3::new(0.0, 0.0, 1.0).unwrap(),
3838        Rotation3d::IDENTITY,
3839        Vec3::new(1.0, 1.0, 1.0).unwrap(),
3840    )
3841    .unwrap();
3842    scene
3843        .try_push(
3844            &classification_mesh,
3845            coplanar_transform,
3846            MeshStyle3d::wireframe(
3847                WireframeStyle3d::visible(Color::rgb(0.0, 1.0, 1.0), logical(2.0))
3848                    .unwrap()
3849                    .with_hidden(
3850                        Color::rgb(1.0, 0.0, 1.0),
3851                        logical(2.0),
3852                        logical(4.0),
3853                        logical(4.0),
3854                    )
3855                    .unwrap(),
3856            ),
3857        )
3858        .unwrap();
3859    let sub_depth_resolution_transform = Transform3d::new(
3860        Vec3::new(0.0, 0.2, 0.999_999).unwrap(),
3861        Rotation3d::IDENTITY,
3862        Vec3::new(1.0, 1.0, 1.0).unwrap(),
3863    )
3864    .unwrap();
3865    scene
3866        .try_push(
3867            &classification_mesh,
3868            sub_depth_resolution_transform,
3869            MeshStyle3d::wireframe(
3870                WireframeStyle3d::visible(Color::rgb(1.0, 0.5, 0.0), logical(2.0))
3871                    .unwrap()
3872                    .with_hidden(
3873                        Color::rgb(1.0, 0.0, 1.0),
3874                        logical(2.0),
3875                        logical(4.0),
3876                        logical(4.0),
3877                    )
3878                    .unwrap(),
3879            ),
3880        )
3881        .unwrap();
3882    let moved_near_transform = Transform3d::new(
3883        Vec3::new(0.25, 0.0, 1.0).unwrap(),
3884        Rotation3d::IDENTITY,
3885        Vec3::new(1.0, 1.0, 1.0).unwrap(),
3886    )
3887    .unwrap();
3888    scene.set_transform(near_id, moved_near_transform).unwrap();
3889    assert_eq!(scene.instances()[0].transform(), moved_near_transform);
3890    assert_eq!(scene.instances()[1].transform(), far_transform);
3891    assert_eq!(scene.instances()[1].id(), far_id);
3892    scene.set_visible(far_id, false).unwrap();
3893    assert_eq!(scene.visible_object_count(), 4);
3894    scene.set_visible(far_id, true).unwrap();
3895    assert_eq!(scene.visible_object_count(), 5);
3896    scene.set_transform(near_id, near_transform).unwrap();
3897    renderer
3898        .ensure_frame_capacity(device, scene.object_count())
3899        .unwrap();
3900    renderer.instances = scene
3901        .instances()
3902        .iter()
3903        .map(|instance| {
3904            let rows = instance.transform.model_rows().unwrap();
3905            MeshInstanceGpu {
3906                normal_row_0: [0.0; 4],
3907                normal_row_1: [0.0; 4],
3908                normal_row_2: [0.0; 4],
3909                model_row_0: rows[0],
3910                model_row_1: rows[1],
3911                model_row_2: rows[2],
3912                surface: material::surface_parameters(instance.style.surface_style()),
3913                uv_transform: texture::material_uv_parameters(instance.mesh.material()),
3914                color: instance
3915                    .style
3916                    .surface_style()
3917                    .map_or(Color::BLACK, SurfaceStyle3d::color)
3918                    .to_array(),
3919            }
3920        })
3921        .collect();
3922    renderer
3923        .edge_object_bytes
3924        .resize(scene.object_count() * renderer.edge_object_stride, 0);
3925    let near_rows = near_transform.model_rows().unwrap();
3926    let near_edge_uniform = EdgeObjectUniform {
3927        model_row_0: near_rows[0],
3928        model_row_1: near_rows[1],
3929        model_row_2: near_rows[2],
3930        visible_color: Color::rgb(0.0, 0.0, 1.0).to_array(),
3931        hidden_color: Color::rgb(1.0, 0.0, 1.0).to_array(),
3932        edge_style: [2.0, 2.0, 4.0, 4.0],
3933    };
3934    renderer.edge_object_bytes[..std::mem::size_of::<EdgeObjectUniform>()]
3935        .copy_from_slice(bytemuck::bytes_of(&near_edge_uniform));
3936    let far_rows = far_transform.model_rows().unwrap();
3937    let far_edge_uniform = EdgeObjectUniform {
3938        model_row_0: far_rows[0],
3939        model_row_1: far_rows[1],
3940        model_row_2: far_rows[2],
3941        visible_color: Color::rgb(1.0, 0.0, 0.0).to_array(),
3942        hidden_color: Color::WHITE.to_array(),
3943        edge_style: [2.0, 2.0, 4.0, 4.0],
3944    };
3945    let edge_start = renderer.edge_object_stride;
3946    let edge_end = edge_start + std::mem::size_of::<EdgeObjectUniform>();
3947    renderer.edge_object_bytes[edge_start..edge_end]
3948        .copy_from_slice(bytemuck::bytes_of(&far_edge_uniform));
3949    let crossing_rows = Transform3d::IDENTITY.model_rows().unwrap();
3950    let crossing_edge_uniform = EdgeObjectUniform {
3951        model_row_0: crossing_rows[0],
3952        model_row_1: crossing_rows[1],
3953        model_row_2: crossing_rows[2],
3954        visible_color: Color::rgb(1.0, 1.0, 0.0).to_array(),
3955        hidden_color: Color::rgb(1.0, 1.0, 0.0).to_array(),
3956        edge_style: [2.0, 0.0, 1.0, 1.0],
3957    };
3958    let crossing_edge_start = 2 * renderer.edge_object_stride;
3959    let crossing_edge_end = crossing_edge_start + std::mem::size_of::<EdgeObjectUniform>();
3960    renderer.edge_object_bytes[crossing_edge_start..crossing_edge_end]
3961        .copy_from_slice(bytemuck::bytes_of(&crossing_edge_uniform));
3962    let coplanar_rows = coplanar_transform.model_rows().unwrap();
3963    let coplanar_edge_uniform = EdgeObjectUniform {
3964        model_row_0: coplanar_rows[0],
3965        model_row_1: coplanar_rows[1],
3966        model_row_2: coplanar_rows[2],
3967        visible_color: Color::rgb(0.0, 1.0, 1.0).to_array(),
3968        hidden_color: Color::rgb(1.0, 0.0, 1.0).to_array(),
3969        edge_style: [2.0, 2.0, 4.0, 4.0],
3970    };
3971    let coplanar_edge_start = 3 * renderer.edge_object_stride;
3972    let coplanar_edge_end = coplanar_edge_start + std::mem::size_of::<EdgeObjectUniform>();
3973    renderer.edge_object_bytes[coplanar_edge_start..coplanar_edge_end]
3974        .copy_from_slice(bytemuck::bytes_of(&coplanar_edge_uniform));
3975    let sub_depth_rows = sub_depth_resolution_transform.model_rows().unwrap();
3976    let sub_depth_edge_uniform = EdgeObjectUniform {
3977        model_row_0: sub_depth_rows[0],
3978        model_row_1: sub_depth_rows[1],
3979        model_row_2: sub_depth_rows[2],
3980        visible_color: Color::rgb(1.0, 0.5, 0.0).to_array(),
3981        hidden_color: Color::rgb(1.0, 0.0, 1.0).to_array(),
3982        edge_style: [2.0, 2.0, 4.0, 4.0],
3983    };
3984    let sub_depth_edge_start = 4 * renderer.edge_object_stride;
3985    let sub_depth_edge_end = sub_depth_edge_start + std::mem::size_of::<EdgeObjectUniform>();
3986    renderer.edge_object_bytes[sub_depth_edge_start..sub_depth_edge_end]
3987        .copy_from_slice(bytemuck::bytes_of(&sub_depth_edge_uniform));
3988    queue.write_buffer(
3989        &renderer.camera_uniform_buffer,
3990        0,
3991        bytemuck::bytes_of(&camera_uniform),
3992    );
3993    queue.write_buffer(
3994        &renderer.instance_buffer,
3995        0,
3996        bytemuck::cast_slice(&renderer.instances),
3997    );
3998    queue.write_buffer(&renderer.edge_object_buffer, 0, &renderer.edge_object_bytes);
3999    let color_texture = device.create_texture(&wgpu::TextureDescriptor {
4000        label: Some("sim-engine 3D depth test color"),
4001        size: wgpu::Extent3d {
4002            width: 64,
4003            height: 64,
4004            depth_or_array_layers: 1,
4005        },
4006        mip_level_count: 1,
4007        sample_count: 1,
4008        dimension: wgpu::TextureDimension::D2,
4009        format,
4010        usage: wgpu::TextureUsages::RENDER_ATTACHMENT | wgpu::TextureUsages::COPY_SRC,
4011        view_formats: &[],
4012    });
4013    let color_view = color_texture.create_view(&wgpu::TextureViewDescriptor::default());
4014    let depth_texture = create_depth_texture(device, 64, 64);
4015    let depth_view = depth_texture.create_view(&wgpu::TextureViewDescriptor::default());
4016    let readback = device.create_buffer(&wgpu::BufferDescriptor {
4017        label: Some("sim-engine 3D depth test readback"),
4018        size: 256 * 64,
4019        usage: wgpu::BufferUsages::COPY_DST | wgpu::BufferUsages::MAP_READ,
4020        mapped_at_creation: false,
4021    });
4022    let mut encoder = device.create_command_encoder(&wgpu::CommandEncoderDescriptor {
4023        label: Some("sim-engine 3D depth test encoder"),
4024    });
4025    encode_scene_pass(
4026        &mut encoder,
4027        &renderer,
4028        &color_view,
4029        &depth_view,
4030        Color::BLACK,
4031        scene.instances(),
4032    );
4033    encoder.copy_texture_to_buffer(
4034        wgpu::TexelCopyTextureInfo {
4035            texture: &color_texture,
4036            mip_level: 0,
4037            origin: wgpu::Origin3d::ZERO,
4038            aspect: wgpu::TextureAspect::All,
4039        },
4040        wgpu::TexelCopyBufferInfo {
4041            buffer: &readback,
4042            layout: wgpu::TexelCopyBufferLayout {
4043                offset: 0,
4044                bytes_per_row: Some(256),
4045                rows_per_image: Some(64),
4046            },
4047        },
4048        wgpu::Extent3d {
4049            width: 64,
4050            height: 64,
4051            depth_or_array_layers: 1,
4052        },
4053    );
4054    queue.submit([encoder.finish()]);
4055    device
4056        .poll(wgpu::PollType::wait_indefinitely())
4057        .expect("3D depth test submission should complete");
4058    let slice = readback.slice(..);
4059    let (sender, receiver) = std::sync::mpsc::channel();
4060    slice.map_async(wgpu::MapMode::Read, move |result| {
4061        sender.send(result).unwrap();
4062    });
4063    device
4064        .poll(wgpu::PollType::wait_indefinitely())
4065        .expect("3D depth test mapping should complete");
4066    receiver
4067        .recv_timeout(Duration::from_secs(5))
4068        .expect("3D depth test callback should run")
4069        .expect("3D depth readback should map");
4070    let bytes = slice.get_mapped_range().expect("3D depth bytes");
4071    let [red, green, blue] = match format {
4072        wgpu::TextureFormat::Rgba8Unorm | wgpu::TextureFormat::Rgba8UnormSrgb => [0, 1, 2],
4073        wgpu::TextureFormat::Bgra8Unorm | wgpu::TextureFormat::Bgra8UnormSrgb => [2, 1, 0],
4074        _ => panic!("unsupported 3D byte-channel oracle format: {format:?}"),
4075    };
4076    let center_offset = 32 * 256 + 32 * 4;
4077    assert!(
4078        bytes[center_offset + green] > 200,
4079        "near green surface must win depth testing"
4080    );
4081    assert!(
4082        bytes[center_offset + red] < 20,
4083        "far red surface must remain occluded"
4084    );
4085    for x in 20..44 {
4086        let offset = 48 * 256 + x * 4;
4087        assert!(
4088            bytes[offset + blue] > 180 && bytes[offset + red] < 80,
4089            "coplanar near edge must remain solid visible blue at x={x}"
4090        );
4091    }
4092    let mut hidden_pattern = Vec::new();
4093    for step in 1..20 {
4094        let amount = step as f32 / 20.0;
4095        let x = (21.33 + (32.0 - 21.33) * amount).round() as usize;
4096        let y = (42.67 + (21.33 - 42.67) * amount).round() as usize;
4097        let offset = y * 256 + x * 4;
4098        hidden_pattern
4099            .push(bytes[offset] > 220 && bytes[offset + 1] > 220 && bytes[offset + 2] > 220);
4100    }
4101    assert!(
4102        hidden_pattern.windows(2).any(|pair| pair == [true, false])
4103            && hidden_pattern.windows(2).any(|pair| pair == [false, true]),
4104        "hidden edge must alternate ordered white dashes and gaps: {hidden_pattern:?}"
4105    );
4106    let near_clipped_yellow_pixels = bytes
4107        .chunks_exact(4)
4108        .filter(|pixel| pixel[red] > 180 && pixel[green] > 180 && pixel[blue] < 80)
4109        .count();
4110    assert!(
4111        near_clipped_yellow_pixels >= 4,
4112        "edge crossing the near plane must remain visible after homogeneous clipping: {near_clipped_yellow_pixels} yellow pixels"
4113    );
4114    let different_object_coplanar_pixels = bytes
4115        .chunks_exact(4)
4116        .filter(|pixel| pixel[red] < 80 && pixel[green] > 180 && pixel[blue] > 180)
4117        .count();
4118    assert!(
4119        different_object_coplanar_pixels >= 4,
4120        "a coplanar edge from another object must resolve visible: {different_object_coplanar_pixels} cyan pixels"
4121    );
4122    let sub_depth_resolution_pixels = bytes
4123        .chunks_exact(4)
4124        .filter(|pixel| pixel[red] > 180 && pixel[green] > 100 && pixel[blue] < 80)
4125        .count();
4126    assert!(
4127        sub_depth_resolution_pixels >= 4,
4128        "sub-depth-resolution separation must conservatively resolve visible: {sub_depth_resolution_pixels} orange pixels"
4129    );
4130    drop(bytes);
4131    readback.unmap();
4132}
4133
4134#[cfg(test)]
4135pub(super) fn assert_gpu_scene_recovery_contract(
4136    source_device: &wgpu::Device,
4137    source_queue: &wgpu::Queue,
4138    recovery_device: &wgpu::Device,
4139    recovery_queue: &wgpu::Queue,
4140    format: wgpu::TextureFormat,
4141) {
4142    texture::assert_dev5_contract(
4143        source_device,
4144        source_queue,
4145        recovery_device,
4146        recovery_queue,
4147        format,
4148    );
4149    texture::assert_gpu_texture_lifecycle_recovery(
4150        source_device,
4151        source_queue,
4152        recovery_device,
4153        recovery_queue,
4154        format,
4155    );
4156    dynamic::assert_gpu_dynamic_recovery(
4157        source_device,
4158        source_queue,
4159        recovery_device,
4160        recovery_queue,
4161    );
4162    material_resource_tests::assert_gpu_alpha_recovery(
4163        source_device,
4164        source_queue,
4165        recovery_device,
4166        recovery_queue,
4167    );
4168    lifetime_tests::assert_lifetime_contract(
4169        source_device,
4170        source_queue,
4171        recovery_device,
4172        recovery_queue,
4173    );
4174    surface::assert_gpu_clipped_recovery(
4175        source_device,
4176        source_queue,
4177        recovery_device,
4178        recovery_queue,
4179    );
4180    texture::assert_gpu_textured_recovery(
4181        source_device,
4182        source_queue,
4183        recovery_device,
4184        recovery_queue,
4185    );
4186    let source_identity = Arc::new(());
4187    let recovery_identity = Arc::new(());
4188    let topology = Mesh3d::with_display_edges(
4189        vec![
4190            Vec3::new(-0.5, -0.5, 0.0).unwrap(),
4191            Vec3::new(0.5, -0.5, 0.0).unwrap(),
4192            Vec3::new(0.0, 0.5, 0.0).unwrap(),
4193        ],
4194        vec![0, 1, 2],
4195        vec![MeshEdge3d::new(0, 1).unwrap()],
4196    )
4197    .unwrap();
4198    let source_mesh = create_retained_mesh(
4199        source_device,
4200        source_queue,
4201        Arc::clone(&source_identity),
4202        topology,
4203    )
4204    .unwrap();
4205    let transform_a = Transform3d::IDENTITY;
4206    let transform_b = Transform3d::new(
4207        Vec3::new(1.0, 2.0, 3.0).unwrap(),
4208        Rotation3d::IDENTITY,
4209        Vec3::new(2.0, 2.0, 2.0).unwrap(),
4210    )
4211    .unwrap();
4212    let style = MeshStyle3d::surface(SurfaceStyle3d::opaque(Color::WHITE).unwrap())
4213        .with_wireframe(WireframeStyle3d::visible(Color::BLACK, logical(1.0)).unwrap());
4214    let mut scene = Scene3d::new(Color::BLACK).unwrap();
4215    let first_id = scene.try_push(&source_mesh, transform_a, style).unwrap();
4216    let second_id = scene.try_push(&source_mesh, transform_b, style).unwrap();
4217    scene.set_visible(second_id, false).unwrap();
4218
4219    assert_eq!(
4220        validate_mesh_identity(&recovery_identity, scene.instances()[0].mesh()),
4221        Err(Mesh3dRenderError::RendererMismatch)
4222    );
4223    let report = restore_scene3d_resources(
4224        recovery_device,
4225        recovery_queue,
4226        &Mesh3dRenderer::new(recovery_device, wgpu::TextureFormat::Rgba8UnormSrgb)
4227            .textures
4228            .layout,
4229        Arc::clone(&recovery_identity),
4230        &mut scene,
4231    )
4232    .unwrap();
4233    assert_eq!(report.object_count(), 2);
4234    assert_eq!(report.migrated_object_count(), 2);
4235    assert_eq!(report.restored_mesh_count(), 1);
4236    assert_eq!(
4237        report.restored_gpu_bytes(),
4238        source_mesh.gpu_allocation_bytes()
4239    );
4240    assert_eq!(scene.instances()[0].id(), first_id);
4241    assert_eq!(scene.instances()[1].id(), second_id);
4242    assert_eq!(scene.instances()[0].transform(), transform_a);
4243    assert_eq!(scene.instances()[1].transform(), transform_b);
4244    assert_eq!(scene.instances()[0].style(), style);
4245    assert_eq!(scene.instances()[1].style(), style);
4246    assert!(scene.instances()[0].is_visible());
4247    assert!(!scene.instances()[1].is_visible());
4248    assert!(Arc::ptr_eq(
4249        &scene.instances()[0].mesh.vertex_buffer,
4250        &scene.instances()[1].mesh.vertex_buffer,
4251    ));
4252    for instance in scene.instances() {
4253        assert_eq!(
4254            validate_mesh_identity(&recovery_identity, instance.mesh()),
4255            Ok(())
4256        );
4257        assert_eq!(
4258            validate_mesh_identity(&source_identity, instance.mesh()),
4259            Err(Mesh3dRenderError::RendererMismatch)
4260        );
4261    }
4262
4263    let no_op_report = restore_scene3d_resources(
4264        recovery_device,
4265        recovery_queue,
4266        &Mesh3dRenderer::new(recovery_device, wgpu::TextureFormat::Rgba8UnormSrgb)
4267            .textures
4268            .layout,
4269        recovery_identity,
4270        &mut scene,
4271    )
4272    .unwrap();
4273    assert_eq!(no_op_report.object_count(), 2);
4274    assert_eq!(no_op_report.migrated_object_count(), 0);
4275    assert_eq!(no_op_report.restored_mesh_count(), 0);
4276    assert_eq!(no_op_report.restored_gpu_bytes(), 0);
4277}
4278
4279#[cfg(test)]
4280fn assert_gpu_clip_equivalence(device: &wgpu::Device, queue: &wgpu::Queue) {
4281    let inputs = seeded_clip_probe_inputs();
4282    let input_bytes = bytemuck::cast_slice(&inputs);
4283    let output_size = (inputs.len() * std::mem::size_of::<ClipProbeOutputGpu>()) as u64;
4284    let input_buffer = device.create_buffer(&wgpu::BufferDescriptor {
4285        label: Some("sim-engine 3D clip probe input"),
4286        size: input_bytes.len() as u64,
4287        usage: wgpu::BufferUsages::STORAGE | wgpu::BufferUsages::COPY_DST,
4288        mapped_at_creation: false,
4289    });
4290    let output_buffer = device.create_buffer(&wgpu::BufferDescriptor {
4291        label: Some("sim-engine 3D clip probe output"),
4292        size: output_size,
4293        usage: wgpu::BufferUsages::STORAGE | wgpu::BufferUsages::COPY_SRC,
4294        mapped_at_creation: false,
4295    });
4296    let readback = device.create_buffer(&wgpu::BufferDescriptor {
4297        label: Some("sim-engine 3D clip probe readback"),
4298        size: output_size,
4299        usage: wgpu::BufferUsages::COPY_DST | wgpu::BufferUsages::MAP_READ,
4300        mapped_at_creation: false,
4301    });
4302    queue.write_buffer(&input_buffer, 0, input_bytes);
4303
4304    let shader = device.create_shader_module(wgpu::ShaderModuleDescriptor {
4305        label: Some("sim-engine 3D clip equivalence shader"),
4306        source: wgpu::ShaderSource::Wgsl(lighting::shader_source(include_str!("mesh3d.wgsl"))),
4307    });
4308    let empty_layout = device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
4309        label: Some("sim-engine empty clip probe layout"),
4310        entries: &[],
4311    });
4312    let probe_layout = device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
4313        label: Some("sim-engine 3D clip probe layout"),
4314        entries: &[
4315            wgpu::BindGroupLayoutEntry {
4316                binding: 0,
4317                visibility: wgpu::ShaderStages::COMPUTE,
4318                ty: wgpu::BindingType::Buffer {
4319                    ty: wgpu::BufferBindingType::Storage { read_only: true },
4320                    has_dynamic_offset: false,
4321                    min_binding_size: None,
4322                },
4323                count: None,
4324            },
4325            wgpu::BindGroupLayoutEntry {
4326                binding: 1,
4327                visibility: wgpu::ShaderStages::COMPUTE,
4328                ty: wgpu::BindingType::Buffer {
4329                    ty: wgpu::BufferBindingType::Storage { read_only: false },
4330                    has_dynamic_offset: false,
4331                    min_binding_size: None,
4332                },
4333                count: None,
4334            },
4335        ],
4336    });
4337    let pipeline_layout = device.create_pipeline_layout(&wgpu::PipelineLayoutDescriptor {
4338        label: Some("sim-engine 3D clip probe pipeline layout"),
4339        bind_group_layouts: &[
4340            Some(&empty_layout),
4341            Some(&empty_layout),
4342            Some(&probe_layout),
4343        ],
4344        immediate_size: 0,
4345    });
4346    let pipeline = device.create_compute_pipeline(&wgpu::ComputePipelineDescriptor {
4347        label: Some("sim-engine 3D clip probe pipeline"),
4348        layout: Some(&pipeline_layout),
4349        module: &shader,
4350        entry_point: Some("mesh3d_clip_probe_main"),
4351        compilation_options: wgpu::PipelineCompilationOptions::default(),
4352        cache: None,
4353    });
4354    let bind_group = device.create_bind_group(&wgpu::BindGroupDescriptor {
4355        label: Some("sim-engine 3D clip probe bind group"),
4356        layout: &probe_layout,
4357        entries: &[
4358            wgpu::BindGroupEntry {
4359                binding: 0,
4360                resource: input_buffer.as_entire_binding(),
4361            },
4362            wgpu::BindGroupEntry {
4363                binding: 1,
4364                resource: output_buffer.as_entire_binding(),
4365            },
4366        ],
4367    });
4368    let mut encoder = device.create_command_encoder(&wgpu::CommandEncoderDescriptor {
4369        label: Some("sim-engine 3D clip probe encoder"),
4370    });
4371    {
4372        let mut pass = encoder.begin_compute_pass(&wgpu::ComputePassDescriptor {
4373            label: Some("sim-engine 3D clip probe pass"),
4374            timestamp_writes: None,
4375        });
4376        pass.set_pipeline(&pipeline);
4377        pass.set_bind_group(2, &bind_group, &[]);
4378        pass.dispatch_workgroups((inputs.len() as u32).div_ceil(64), 1, 1);
4379    }
4380    encoder.copy_buffer_to_buffer(&output_buffer, 0, &readback, 0, output_size);
4381    queue.submit([encoder.finish()]);
4382    device
4383        .poll(wgpu::PollType::wait_indefinitely())
4384        .expect("3D clip probe submission should complete");
4385    let slice = readback.slice(..);
4386    let (sender, receiver) = std::sync::mpsc::channel();
4387    slice.map_async(wgpu::MapMode::Read, move |result| {
4388        sender.send(result).unwrap();
4389    });
4390    device
4391        .poll(wgpu::PollType::wait_indefinitely())
4392        .expect("3D clip probe mapping should complete");
4393    receiver
4394        .recv_timeout(Duration::from_secs(5))
4395        .expect("3D clip probe callback should run")
4396        .expect("3D clip probe readback should map");
4397    let bytes = slice.get_mapped_range().expect("3D clip probe bytes");
4398    let outputs: &[ClipProbeOutputGpu] = bytemuck::cast_slice(&bytes);
4399    for (case_index, (input, actual)) in inputs.iter().zip(outputs).enumerate() {
4400        let expected = clip_edge_to_frustum_details(input.start_clip, input.end_clip)
4401            .expect("finite seeded clip input should not overflow after normalization");
4402        assert_eq!(
4403            actual.visible,
4404            u32::from(expected.is_some()),
4405            "CPU/WGSL clip visibility differs for seeded case {case_index}: {input:?}"
4406        );
4407        let Some(expected) = expected else {
4408            continue;
4409        };
4410        for (actual, expected) in actual
4411            .start_clip
4412            .into_iter()
4413            .chain(actual.end_clip)
4414            .chain(actual.range)
4415            .zip(
4416                expected.clip[0]
4417                    .into_iter()
4418                    .chain(expected.clip[1])
4419                    .chain([expected.enter, expected.exit]),
4420            )
4421        {
4422            let tolerance = 32.0 * f32::EPSILON * expected.abs().max(1.0);
4423            assert!(
4424                (actual - expected).abs() <= tolerance,
4425                "CPU/WGSL clip value differs for seeded case {case_index}: actual={actual}, expected={expected}, tolerance={tolerance}, input={input:?}"
4426            );
4427        }
4428    }
4429    drop(bytes);
4430    readback.unmap();
4431}
4432
4433#[cfg(test)]
4434fn seeded_clip_probe_inputs() -> Vec<ClipProbeInputGpu> {
4435    let maximum = MAX_PORTABLE_SHADER_VALUE;
4436    let mut inputs = vec![
4437        ClipProbeInputGpu {
4438            start_clip: [0.0, 0.0, 0.5, 1.0],
4439            end_clip: [0.5, 0.5, 0.75, 1.0],
4440        },
4441        ClipProbeInputGpu {
4442            start_clip: [-2.0, 0.0, 0.5, 1.0],
4443            end_clip: [0.5, 0.0, 0.5, 1.0],
4444        },
4445        ClipProbeInputGpu {
4446            start_clip: [0.0, 0.0, 0.5, 1.0],
4447            end_clip: [2.0, 0.0, 0.5, 1.0],
4448        },
4449        ClipProbeInputGpu {
4450            start_clip: [0.0, -2.0, 0.5, 1.0],
4451            end_clip: [0.0, 0.5, 0.5, 1.0],
4452        },
4453        ClipProbeInputGpu {
4454            start_clip: [0.0, 0.0, 0.5, 1.0],
4455            end_clip: [0.0, 2.0, 0.5, 1.0],
4456        },
4457        ClipProbeInputGpu {
4458            start_clip: [0.0, 0.0, -1.0, 1.0],
4459            end_clip: [0.0, 0.0, 0.5, 1.0],
4460        },
4461        ClipProbeInputGpu {
4462            start_clip: [0.0, 0.0, 0.5, 1.0],
4463            end_clip: [0.0, 0.0, 2.0, 1.0],
4464        },
4465        ClipProbeInputGpu {
4466            start_clip: [-2.0, -2.0, 0.5, 1.0],
4467            end_clip: [0.5, 0.5, 0.5, 1.0],
4468        },
4469        ClipProbeInputGpu {
4470            start_clip: [0.0, 0.0, 0.5, 1.0],
4471            end_clip: [2.0, 2.0, 2.0, 1.0],
4472        },
4473        ClipProbeInputGpu {
4474            start_clip: [-1.0, 1.0, 0.0, 1.0],
4475            end_clip: [1.0, -1.0, 1.0, 1.0],
4476        },
4477        ClipProbeInputGpu {
4478            start_clip: [maximum, 0.0, maximum * 0.5, maximum],
4479            end_clip: [-maximum, maximum, maximum, maximum],
4480        },
4481        ClipProbeInputGpu {
4482            start_clip: [0.0, 0.0, -maximum, -maximum],
4483            end_clip: [0.0, 0.0, -maximum * 0.5, -maximum * 0.5],
4484        },
4485    ];
4486    let mut state = 0x5eed_c1a5_u32;
4487    for _ in 0..244 {
4488        let mut next_component = || {
4489            state = state.wrapping_mul(1_664_525).wrapping_add(1_013_904_223);
4490            ((state >> 8) as f32 / 16_777_215.0) * 4.0 - 2.0
4491        };
4492        inputs.push(ClipProbeInputGpu {
4493            start_clip: [
4494                next_component(),
4495                next_component(),
4496                next_component(),
4497                next_component(),
4498            ],
4499            end_clip: [
4500                next_component(),
4501                next_component(),
4502                next_component(),
4503                next_component(),
4504            ],
4505        });
4506    }
4507    debug_assert_eq!(inputs.len(), 256);
4508    inputs
4509}
4510
4511#[cfg(test)]
4512mod tests {
4513    use super::*;
4514
4515    #[test]
4516    fn shader_transform_validation_rejects_finite_overflow() {
4517        let maximum = f32::MAX;
4518        let mesh = Mesh3d::new(
4519            vec![
4520                Vec3::new(maximum, 0.0, 0.0).unwrap(),
4521                Vec3::new(maximum, 1.0, 0.0).unwrap(),
4522                Vec3::new(maximum, 0.0, 1.0).unwrap(),
4523            ],
4524            vec![0, 1, 2],
4525        )
4526        .unwrap();
4527        let transform = Transform3d::new(
4528            Vec3::ZERO,
4529            Rotation3d::IDENTITY,
4530            Vec3::new(maximum, 1.0, 1.0).unwrap(),
4531        )
4532        .unwrap();
4533        let camera = Camera3d::look_at(
4534            Vec3::new(0.0, 0.0, 5.0).unwrap(),
4535            Vec3::ZERO,
4536            Vec3::Y,
4537            Projection3d::orthographic(world(4.0), 1.0, world(0.1), world(20.0)).unwrap(),
4538        )
4539        .unwrap();
4540        assert_eq!(
4541            validate_shader_transform(
4542                &mesh,
4543                transform.model_rows().unwrap(),
4544                camera.world_to_clip_rows().unwrap(),
4545            ),
4546            Err(Mesh3dRenderError::InvalidGeometryTransform)
4547        );
4548    }
4549
4550    #[test]
4551    fn shader_transform_rejects_ftz_sensitive_vertex_operands() {
4552        let largest_subnormal = f32::from_bits(0x007f_ffff);
4553        let mesh = Mesh3d::with_display_edges(
4554            vec![Vec3::ZERO, Vec3::new(largest_subnormal, 0.0, 0.0).unwrap()],
4555            Vec::new(),
4556            vec![MeshEdge3d::new(0, 1).unwrap()],
4557        )
4558        .unwrap();
4559        let camera = Camera3d::look_at(
4560            Vec3::new(0.0, 0.0, 2.0).unwrap(),
4561            Vec3::ZERO,
4562            Vec3::Y,
4563            Projection3d::orthographic(world(2.0), 1.0, world(0.1), world(10.0)).unwrap(),
4564        )
4565        .unwrap();
4566
4567        assert_eq!(
4568            validate_shader_transform(
4569                &mesh,
4570                Transform3d::IDENTITY.model_rows().unwrap(),
4571                camera.world_to_clip_rows().unwrap(),
4572            ),
4573            Err(Mesh3dRenderError::InvalidGeometryTransform)
4574        );
4575    }
4576
4577    #[test]
4578    fn shader_transform_rejects_subnormal_row_operands_uniformly() {
4579        let largest_subnormal = f32::from_bits(0x007f_ffff);
4580        let mesh = Mesh3d::with_display_edges(
4581            vec![Vec3::ZERO, Vec3::new(0.0, 1.0, 0.0).unwrap()],
4582            Vec::new(),
4583            vec![MeshEdge3d::new(0, 1).unwrap()],
4584        )
4585        .unwrap();
4586        let transform = Transform3d::new(
4587            Vec3::ZERO,
4588            Rotation3d::IDENTITY,
4589            Vec3::new(largest_subnormal, 1.0, 1.0).unwrap(),
4590        )
4591        .unwrap();
4592        let camera = Camera3d::look_at(
4593            Vec3::new(0.0, 0.0, 2.0).unwrap(),
4594            Vec3::ZERO,
4595            Vec3::Y,
4596            Projection3d::orthographic(world(2.0), 1.0, world(0.1), world(10.0)).unwrap(),
4597        )
4598        .unwrap();
4599
4600        assert_eq!(
4601            validate_shader_transform(
4602                &mesh,
4603                transform.model_rows().unwrap(),
4604                camera.world_to_clip_rows().unwrap(),
4605            ),
4606            Err(Mesh3dRenderError::InvalidGeometryTransform)
4607        );
4608    }
4609
4610    #[test]
4611    fn shader_transform_rejects_subnormal_source_absorbed_by_translation() {
4612        let point = Vec3::new(f32::from_bits(1), 0.0, 0.0).unwrap();
4613        let mesh = Mesh3d::with_display_edges(
4614            vec![point, Vec3::new(0.5, 0.0, 0.0).unwrap()],
4615            Vec::new(),
4616            vec![MeshEdge3d::new(0, 1).unwrap()],
4617        )
4618        .unwrap();
4619        let transform = Transform3d::new(
4620            Vec3::new(1.0, 0.0, 0.0).unwrap(),
4621            Rotation3d::IDENTITY,
4622            Vec3::new(1.0, 1.0, 1.0).unwrap(),
4623        )
4624        .unwrap();
4625        let camera = Camera3d::look_at(
4626            Vec3::new(0.0, 0.0, -4.0).unwrap(),
4627            Vec3::ZERO,
4628            Vec3::Y,
4629            Projection3d::orthographic(world(4.0), 1.0, world(0.1), world(10.0)).unwrap(),
4630        )
4631        .unwrap();
4632        let model_rows = transform.model_rows().unwrap();
4633        let model_x = shader_dot_range(
4634            model_rows[0],
4635            [point.x(), point.y(), point.z(), 1.0].map(ShaderValueRange::exact),
4636        );
4637
4638        assert!(matches!(
4639            model_x,
4640            Err(Mesh3dRenderError::InvalidGeometryTransform)
4641        ));
4642        assert_eq!(
4643            validate_shader_transform(&mesh, model_rows, camera.world_to_clip_rows().unwrap()),
4644            Err(Mesh3dRenderError::InvalidGeometryTransform)
4645        );
4646    }
4647
4648    #[test]
4649    fn surface_triangle_ftz_high_scale_is_rejected() {
4650        let largest_subnormal = f32::from_bits(0x007f_ffff);
4651        let mesh = Mesh3d::new(
4652            vec![
4653                Vec3::ZERO,
4654                Vec3::new(largest_subnormal, 0.0, 0.0).unwrap(),
4655                Vec3::new(0.0, largest_subnormal, 0.0).unwrap(),
4656            ],
4657            vec![0, 1, 2],
4658        )
4659        .unwrap();
4660        let transform = Transform3d::new(
4661            Vec3::ZERO,
4662            Rotation3d::IDENTITY,
4663            Vec3::new(f32::MAX, f32::MAX, 1.0).unwrap(),
4664        )
4665        .unwrap();
4666        let camera = Camera3d::look_at(
4667            Vec3::new(0.0, 0.0, 4.0).unwrap(),
4668            Vec3::ZERO,
4669            Vec3::Y,
4670            Projection3d::orthographic(world(8.0), 1.0, world(0.1), world(10.0)).unwrap(),
4671        )
4672        .unwrap();
4673
4674        assert_eq!(
4675            validate_shader_transform(
4676                &mesh,
4677                transform.model_rows().unwrap(),
4678                camera.world_to_clip_rows().unwrap(),
4679            ),
4680            Err(Mesh3dRenderError::InvalidGeometryTransform)
4681        );
4682    }
4683
4684    #[test]
4685    fn shader_transform_rejects_extreme_component_selection_after_interval_dot() {
4686        let rotation = Rotation3d::from_euler_xyz(
4687            0.0,
4688            std::f32::consts::FRAC_PI_4,
4689            -(1.0_f32 / 3.0_f32.sqrt()).asin(),
4690        )
4691        .unwrap();
4692        let unit_rows = Transform3d::new(Vec3::ZERO, rotation, Vec3::new(1.0, 1.0, 1.0).unwrap())
4693            .unwrap()
4694            .model_rows()
4695            .unwrap();
4696        let first_scale = 1.0 / unit_rows[0][0];
4697        let scale = Vec3::new(
4698            f32::from_bits(first_scale.to_bits() + 1),
4699            1.0 / unit_rows[0][1],
4700            1.0 / unit_rows[0][2],
4701        )
4702        .unwrap();
4703        let transform = Transform3d::new(Vec3::ZERO, rotation, scale).unwrap();
4704        let model_rows = transform.model_rows().unwrap();
4705        assert_eq!(model_rows[0], [1.0, 1.0, 1.0, 0.0]);
4706
4707        let point = Vec3::new(
4708            f32::from_bits(0x7ea1_07f9),
4709            f32::from_bits(0x7ecc_fe95),
4710            f32::from_bits(0x7e91_f970),
4711        )
4712        .unwrap();
4713        let mesh = Mesh3d::with_display_edges(
4714            vec![point, point.checked_scale(0.5).unwrap()],
4715            Vec::new(),
4716            vec![MeshEdge3d::new(0, 1).unwrap()],
4717        )
4718        .unwrap();
4719        let camera = Camera3d::look_at(
4720            Vec3::ZERO,
4721            Vec3::new(0.0, 0.0, 1.0).unwrap(),
4722            Vec3::Y,
4723            Projection3d::orthographic(world(2.0), 1.0, world(1.0), world(10.0)).unwrap(),
4724        )
4725        .unwrap();
4726
4727        assert_eq!(
4728            validate_shader_transform(&mesh, model_rows, camera.world_to_clip_rows().unwrap()),
4729            Err(Mesh3dRenderError::InvalidGeometryTransform)
4730        );
4731    }
4732
4733    #[test]
4734    fn shader_transform_rejects_pairwise_dot_overflow_after_finite_cpu_transform() {
4735        let maximum = f32::MAX;
4736        let angle = 0.5_f32.acos();
4737        let model_x = -0.2 * maximum;
4738        let model_z = (0.51 * maximum) / angle.sin();
4739        let mesh = Mesh3d::with_display_edges(
4740            vec![
4741                Vec3::new(model_x, -1.0e30, model_z).unwrap(),
4742                Vec3::new(model_x, 1.0e30, model_z).unwrap(),
4743            ],
4744            Vec::new(),
4745            vec![MeshEdge3d::new(0, 1).unwrap()],
4746        )
4747        .unwrap();
4748        let transform = Transform3d::new(
4749            Vec3::new(0.51 * maximum, 0.0, 0.0).unwrap(),
4750            Rotation3d::from_axis_angle(Vec3::Y, angle).unwrap(),
4751            Vec3::new(1.0, 1.0, 1.0).unwrap(),
4752        )
4753        .unwrap();
4754        let model_center = Vec3::new(model_x, 0.0, model_z).unwrap();
4755        let world_center = transform.transform_point(model_center).unwrap();
4756        assert!(
4757            world_center.x().is_finite()
4758                && world_center.y().is_finite()
4759                && world_center.z().is_finite()
4760        );
4761
4762        let camera = Camera3d::look_at(
4763            Vec3::new(
4764                world_center.x(),
4765                world_center.y(),
4766                world_center.z() - 1.0e32,
4767            )
4768            .unwrap(),
4769            world_center,
4770            Vec3::Y,
4771            Projection3d::perspective(2.8, 1.0, world(1.0e30), world(1.0e34)).unwrap(),
4772        )
4773        .unwrap();
4774        assert!(
4775            camera
4776                .project_world(world_center, LogicalViewport::new(64.0, 64.0).unwrap())
4777                .unwrap()
4778                .inside_view()
4779        );
4780        assert_eq!(
4781            validate_shader_transform(
4782                &mesh,
4783                transform.model_rows().unwrap(),
4784                camera.world_to_clip_rows().unwrap(),
4785            ),
4786            Err(Mesh3dRenderError::InvalidGeometryTransform)
4787        );
4788    }
4789
4790    #[test]
4791    fn shader_transform_propagates_model_association_range_into_camera_dot() {
4792        let point = Vec3::new(-6.593_279_5e37, 2.460_645_7e38, 9.006_588e37).unwrap();
4793        let mesh = Mesh3d::with_display_edges(
4794            vec![point, point.checked_scale(0.5).unwrap()],
4795            Vec::new(),
4796            vec![MeshEdge3d::new(0, 1).unwrap()],
4797        )
4798        .unwrap();
4799        let axis = Vec3::new(1.0, 1.0, 1.0).unwrap().normalized().unwrap();
4800        let transform = Transform3d::new(
4801            Vec3::ZERO,
4802            Rotation3d::from_axis_angle(axis, std::f32::consts::FRAC_PI_2).unwrap(),
4803            Vec3::new(1.0, 1.0, 1.0).unwrap(),
4804        )
4805        .unwrap();
4806        let camera = Camera3d::look_at(
4807            Vec3::new(0.0, 0.0, -1.0e37).unwrap(),
4808            Vec3::ZERO,
4809            Vec3::Y,
4810            Projection3d::orthographic(world(2.0 / 7.0e7), 1.0, world(1.0), world(3.0e38)).unwrap(),
4811        )
4812        .unwrap();
4813        let model_rows = transform.model_rows().unwrap();
4814        let model_point = [point.x(), point.y(), point.z(), 1.0];
4815
4816        assert_eq!(
4817            shader_dot(model_rows[0], model_point),
4818            Err(Mesh3dRenderError::InvalidGeometryTransform)
4819        );
4820        assert_eq!(
4821            validate_shader_transform(&mesh, model_rows, camera.world_to_clip_rows().unwrap()),
4822            Err(Mesh3dRenderError::InvalidGeometryTransform)
4823        );
4824    }
4825
4826    #[test]
4827    fn shader_transform_rejects_association_dependent_clip_classification() {
4828        let point = Vec3::new(1.732_050_8e20, -1.732_050_8e20, 3.808_820_2e12).unwrap();
4829        let mesh = Mesh3d::new(
4830            vec![
4831                point,
4832                Vec3::new(1.269_606_6e12, 1.269_606_6e12, 1.269_606_6e12).unwrap(),
4833                Vec3::new(6.590_675_4e19, -6.590_675_4e19, 3.202_013e12).unwrap(),
4834            ],
4835            vec![0, 1, 2],
4836        )
4837        .unwrap();
4838        let field_of_view = f32::from_bits(std::f32::consts::PI.to_bits() - 1);
4839        let camera = Camera3d::look_at(
4840            Vec3::ZERO,
4841            Vec3::new(1.0, 1.0, 1.0).unwrap(),
4842            Vec3::new(-1.0e20, -9.999_999e19, 2.0e20).unwrap(),
4843            Projection3d::perspective(field_of_view, 16.0, world(f32::MIN_POSITIVE), world(1.0e30))
4844                .unwrap(),
4845        )
4846        .unwrap();
4847        let model_rows = Transform3d::IDENTITY.model_rows().unwrap();
4848        let camera_rows = camera.world_to_clip_rows().unwrap();
4849        let model_point = [point.x(), point.y(), point.z(), 1.0].map(ShaderValueRange::exact);
4850        let world = [
4851            shader_dot_range(model_rows[0], model_point).unwrap(),
4852            shader_dot_range(model_rows[1], model_point).unwrap(),
4853            shader_dot_range(model_rows[2], model_point).unwrap(),
4854            ShaderValueRange::exact(1.0),
4855        ];
4856        let clip_w = shader_dot_range(camera_rows[3], world).unwrap();
4857
4858        assert!(clip_w.minimum <= 0.0 && clip_w.maximum > 1.0e12);
4859        assert_eq!(
4860            validate_shader_transform(&mesh, model_rows, camera_rows),
4861            Err(Mesh3dRenderError::InvalidGeometryTransform)
4862        );
4863    }
4864
4865    #[test]
4866    fn surface_triangle_rejects_association_dependent_projected_collapse() {
4867        let scale = f32::from_bits(0x5d52_e40a);
4868        let coordinate = f32::from_bits(0x5d72_6836);
4869        let adjacent = f32::from_bits(0x5d72_6837);
4870        let product = f32::from_bits(0x7b47_b16b);
4871        let mesh = Mesh3d::new(
4872            vec![
4873                Vec3::new(coordinate, coordinate, 0.0).unwrap(),
4874                Vec3::new(adjacent, coordinate, 0.0).unwrap(),
4875                Vec3::new(coordinate, adjacent, 0.0).unwrap(),
4876            ],
4877            vec![0, 1, 2],
4878        )
4879        .unwrap();
4880        let transform = Transform3d::new(
4881            Vec3::new(-product, -product, 0.0).unwrap(),
4882            Rotation3d::IDENTITY,
4883            Vec3::new(scale, scale, 1.0).unwrap(),
4884        )
4885        .unwrap();
4886        let model_rows = transform.model_rows().unwrap();
4887        let camera = Camera3d::look_at(
4888            Vec3::new(0.0, 0.0, 5.0).unwrap(),
4889            Vec3::ZERO,
4890            Vec3::Y,
4891            Projection3d::orthographic(world(2.0_f32.powi(103)), 1.0, world(0.1), world(10.0))
4892                .unwrap(),
4893        )
4894        .unwrap();
4895        let camera_rows = camera.world_to_clip_rows().unwrap();
4896
4897        // The shader's legal separate multiply/add association collapses all
4898        // three vertices, while a fused association retains a visible
4899        // triangle. Point/plane classification alone cannot detect that.
4900        for vertex in mesh.vertices() {
4901            assert_eq!(
4902                shader_dot(model_rows[0], [vertex.x(), vertex.y(), vertex.z(), 1.0]),
4903                Ok(0.0)
4904            );
4905            assert_eq!(
4906                shader_dot(model_rows[1], [vertex.x(), vertex.y(), vertex.z(), 1.0]),
4907                Ok(0.0)
4908            );
4909        }
4910        assert_eq!(
4911            validate_shader_points(&mesh, model_rows, camera_rows),
4912            Ok(())
4913        );
4914        assert_eq!(
4915            validate_surface_triangle_topology(&mesh, model_rows, camera_rows),
4916            Err(Mesh3dRenderError::UnportableSurfaceTopology)
4917        );
4918        assert_eq!(
4919            validate_shader_transform(&mesh, model_rows, camera_rows),
4920            Err(Mesh3dRenderError::UnportableSurfaceTopology)
4921        );
4922    }
4923
4924    #[test]
4925    fn surface_triangle_frustum_branches_are_explicit() {
4926        let camera = Camera3d::look_at(
4927            Vec3::new(0.0, 0.0, 5.0).unwrap(),
4928            Vec3::ZERO,
4929            Vec3::Y,
4930            Projection3d::orthographic(world(2.0), 1.0, world(0.1), world(10.0)).unwrap(),
4931        )
4932        .unwrap();
4933        let model_rows = Transform3d::IDENTITY.model_rows().unwrap();
4934        let camera_rows = camera.world_to_clip_rows().unwrap();
4935        let mesh = |vertices| Mesh3d::new(vertices, vec![0, 1, 2]).unwrap();
4936
4937        let inside = mesh(vec![
4938            Vec3::new(-0.25, -0.25, 0.0).unwrap(),
4939            Vec3::new(0.25, -0.25, 0.0).unwrap(),
4940            Vec3::new(0.0, 0.25, 0.0).unwrap(),
4941        ]);
4942        assert_eq!(
4943            validate_surface_triangle_topology(&inside, model_rows, camera_rows),
4944            Ok(())
4945        );
4946
4947        let crossing = mesh(vec![
4948            Vec3::new(-0.25, -0.25, 0.0).unwrap(),
4949            Vec3::new(1.5, -0.25, 0.0).unwrap(),
4950            Vec3::new(0.0, 0.25, 0.0).unwrap(),
4951        ]);
4952        assert_eq!(
4953            validate_shader_points(&crossing, model_rows, camera_rows),
4954            Ok(())
4955        );
4956        assert_eq!(
4957            validate_surface_triangle_topology(&crossing, model_rows, camera_rows),
4958            Ok(())
4959        );
4960
4961        let outside = mesh(vec![
4962            Vec3::new(1.5, -0.25, 0.0).unwrap(),
4963            Vec3::new(2.0, -0.25, 0.0).unwrap(),
4964            Vec3::new(1.75, 0.25, 0.0).unwrap(),
4965        ]);
4966        assert_eq!(outside.triangle_count(), 1);
4967        assert_eq!(
4968            validate_surface_triangle_topology(&outside, model_rows, camera_rows),
4969            Ok(())
4970        );
4971    }
4972
4973    #[test]
4974    fn shader_transform_rejects_extreme_correlated_sparse_vertices() {
4975        let extent = 0.9 * f32::MAX;
4976        let mesh = Mesh3d::with_display_edges(
4977            vec![
4978                Vec3::new(extent, 0.0, 0.0).unwrap(),
4979                Vec3::new(0.0, extent, 0.0).unwrap(),
4980            ],
4981            Vec::new(),
4982            vec![MeshEdge3d::new(0, 1).unwrap()],
4983        )
4984        .unwrap();
4985        let transform = Transform3d::new(
4986            Vec3::ZERO,
4987            Rotation3d::from_axis_angle(Vec3::Z, -std::f32::consts::FRAC_PI_4).unwrap(),
4988            Vec3::new(1.0, 1.0, 1.0).unwrap(),
4989        )
4990        .unwrap();
4991        let first = transform.transform_point(mesh.vertices()[0]).unwrap();
4992        let second = transform.transform_point(mesh.vertices()[1]).unwrap();
4993        for vertex in [first, second] {
4994            assert!(vertex.x().is_finite() && vertex.y().is_finite() && vertex.z().is_finite());
4995        }
4996        let target = Vec3::new(first.x(), 0.0, 0.0).unwrap();
4997        let camera = Camera3d::look_at(
4998            Vec3::new(target.x(), 0.0, 2.0e38).unwrap(),
4999            target,
5000            Vec3::Y,
5001            Projection3d::perspective(2.8, 1.0, world(1.0), world(3.0e38)).unwrap(),
5002        )
5003        .unwrap();
5004        let viewport = LogicalViewport::new(64.0, 64.0).unwrap();
5005        assert!(camera.project_world(first, viewport).unwrap().inside_view());
5006        assert!(
5007            camera
5008                .project_world(second, viewport)
5009                .unwrap()
5010                .inside_view()
5011        );
5012        assert_eq!(
5013            validate_shader_transform(
5014                &mesh,
5015                transform.model_rows().unwrap(),
5016                camera.world_to_clip_rows().unwrap(),
5017            ),
5018            Err(Mesh3dRenderError::InvalidGeometryTransform)
5019        );
5020    }
5021
5022    #[test]
5023    fn edge_projection_rejects_post_width_shader_overflow() {
5024        let mesh = Mesh3d::with_display_edges(
5025            vec![
5026                Vec3::new(-0.5, 0.0, 0.0).unwrap(),
5027                Vec3::new(0.5, 0.0, 0.0).unwrap(),
5028            ],
5029            Vec::new(),
5030            vec![MeshEdge3d::new(0, 1).unwrap()],
5031        )
5032        .unwrap();
5033        let style = WireframeStyle3d::visible(Color::WHITE, logical(1_048_576.0)).unwrap();
5034        let camera = Camera3d::look_at(
5035            Vec3::new(0.0, 0.0, 2.0).unwrap(),
5036            Vec3::ZERO,
5037            Vec3::Y,
5038            Projection3d::orthographic(world(2.0), 1.0, world(0.1), world(10.0)).unwrap(),
5039        )
5040        .unwrap();
5041
5042        assert_eq!(
5043            validate_edge_projection(
5044                &mesh,
5045                Transform3d::IDENTITY.model_rows().unwrap(),
5046                camera.world_to_clip_rows().unwrap(),
5047                style,
5048                [1.0, 1.0, 5.0e32, 0.0],
5049            ),
5050            Err(Mesh3dRenderError::InvalidEdgeProjection)
5051        );
5052    }
5053
5054    #[test]
5055    fn edge_projection_rejects_logical_distance_overflow() {
5056        let mesh = Mesh3d::with_display_edges(
5057            vec![
5058                Vec3::new(-0.5, 0.0, 0.0).unwrap(),
5059                Vec3::new(0.5, 0.0, 0.0).unwrap(),
5060            ],
5061            Vec::new(),
5062            vec![MeshEdge3d::new(0, 1).unwrap()],
5063        )
5064        .unwrap();
5065        let style = WireframeStyle3d::visible(Color::WHITE, logical(1_048_576.0)).unwrap();
5066        let camera = Camera3d::look_at(
5067            Vec3::new(0.0, 0.0, 2.0).unwrap(),
5068            Vec3::ZERO,
5069            Vec3::Y,
5070            Projection3d::orthographic(world(2.0), 1.0, world(0.1), world(10.0)).unwrap(),
5071        )
5072        .unwrap();
5073
5074        assert_eq!(
5075            validate_edge_projection(
5076                &mesh,
5077                Transform3d::IDENTITY.model_rows().unwrap(),
5078                camera.world_to_clip_rows().unwrap(),
5079                style,
5080                [1_024.0, 1_024.0, f32::MIN_POSITIVE, 0.0],
5081            ),
5082            Err(Mesh3dRenderError::InvalidEdgeProjection)
5083        );
5084    }
5085
5086    #[test]
5087    fn edge_projection_rejects_hidden_dash_phase_overflow() {
5088        let mesh = Mesh3d::with_display_edges(
5089            vec![
5090                Vec3::new(-0.5, 0.0, 0.0).unwrap(),
5091                Vec3::new(0.5, 0.0, 0.0).unwrap(),
5092            ],
5093            Vec::new(),
5094            vec![MeshEdge3d::new(0, 1).unwrap()],
5095        )
5096        .unwrap();
5097        let smallest = logical(f32::MIN_POSITIVE);
5098        let style = WireframeStyle3d::visible(Color::WHITE, logical(1.0))
5099            .unwrap()
5100            .with_hidden(Color::WHITE, logical(1.0), smallest, smallest)
5101            .unwrap();
5102        let camera = Camera3d::look_at(
5103            Vec3::new(0.0, 0.0, 2.0).unwrap(),
5104            Vec3::ZERO,
5105            Vec3::Y,
5106            Projection3d::orthographic(world(2.0), 1.0, world(0.1), world(10.0)).unwrap(),
5107        )
5108        .unwrap();
5109
5110        assert_eq!(
5111            validate_edge_projection(
5112                &mesh,
5113                Transform3d::IDENTITY.model_rows().unwrap(),
5114                camera.world_to_clip_rows().unwrap(),
5115                style,
5116                [1_024.0, 1_024.0, 1.0, 0.0],
5117            ),
5118            Err(Mesh3dRenderError::InvalidEdgeProjection)
5119        );
5120    }
5121
5122    #[test]
5123    fn edge_projection_bounds_dash_across_legal_shader_associations() {
5124        let point = Vec3::new(-6.593_279e17, 2.460_645_7e18, 9.006_587e17).unwrap();
5125        let mesh = Mesh3d::with_display_edges(
5126            vec![point, point.checked_scale(0.5).unwrap()],
5127            Vec::new(),
5128            vec![MeshEdge3d::new(0, 1).unwrap()],
5129        )
5130        .unwrap();
5131        let axis = Vec3::new(1.0, 1.0, 1.0).unwrap().normalized().unwrap();
5132        let transform = Transform3d::new(
5133            Vec3::ZERO,
5134            Rotation3d::from_axis_angle(axis, std::f32::consts::FRAC_PI_2).unwrap(),
5135            Vec3::new(1.0, 1.0, 1.0).unwrap(),
5136        )
5137        .unwrap();
5138        let camera = Camera3d::look_at(
5139            Vec3::ZERO,
5140            Vec3::new(0.0, 0.0, 1.0).unwrap(),
5141            Vec3::Y,
5142            Projection3d::orthographic(world(5.0e10), 1.0, world(1.0), world(3.0e18)).unwrap(),
5143        )
5144        .unwrap();
5145        let tiny = logical(1.5e-38);
5146        let style = WireframeStyle3d::visible(Color::WHITE, logical(1.0))
5147            .unwrap()
5148            .with_hidden(Color::WHITE, logical(1.0), tiny, tiny)
5149            .unwrap();
5150
5151        let model_rows = transform.model_rows().unwrap();
5152        let model_point = [point.x(), point.y(), point.z(), 1.0];
5153        assert_eq!(shader_dot(model_rows[0], model_point), Ok(0.0));
5154        assert_eq!(
5155            validate_edge_projection(
5156                &mesh,
5157                model_rows,
5158                camera.world_to_clip_rows().unwrap(),
5159                style,
5160                [100.0, 100.0, 1.0, 0.0],
5161            ),
5162            Err(Mesh3dRenderError::InvalidEdgeProjection)
5163        );
5164    }
5165
5166    #[test]
5167    fn edge_projection_rejects_association_dependent_collapse() {
5168        let point = Vec3::new(-6.593_279e17, 2.460_645_7e18, 9.006_587e17).unwrap();
5169        let mesh = Mesh3d::with_display_edges(
5170            vec![point, point.checked_scale(0.5).unwrap()],
5171            Vec::new(),
5172            vec![MeshEdge3d::new(0, 1).unwrap()],
5173        )
5174        .unwrap();
5175        let axis = Vec3::new(1.0, 1.0, 1.0).unwrap().normalized().unwrap();
5176        let transform = Transform3d::new(
5177            Vec3::ZERO,
5178            Rotation3d::from_axis_angle(axis, std::f32::consts::FRAC_PI_2).unwrap(),
5179            Vec3::new(1.0, 1.0, 1.0).unwrap(),
5180        )
5181        .unwrap();
5182        let camera = Camera3d::look_at(
5183            Vec3::ZERO,
5184            Vec3::new(0.0, 0.0, 1.0).unwrap(),
5185            Vec3::Y,
5186            Projection3d::orthographic(world(1.0e13), 1.0, world(1.0), world(3.0e18)).unwrap(),
5187        )
5188        .unwrap();
5189        let style = WireframeStyle3d::visible(Color::WHITE, logical(5.0)).unwrap();
5190        let model_rows = transform.model_rows().unwrap();
5191        let camera_rows = camera.world_to_clip_rows().unwrap();
5192
5193        assert_eq!(
5194            validate_shader_transform(&mesh, model_rows, camera_rows),
5195            Ok(())
5196        );
5197        assert_eq!(
5198            validate_edge_projection(
5199                &mesh,
5200                model_rows,
5201                camera_rows,
5202                style,
5203                [1_000.0, 1_000.0, 1.0, 0.0],
5204            ),
5205            Err(Mesh3dRenderError::InvalidEdgeProjection)
5206        );
5207    }
5208
5209    #[test]
5210    fn edge_projection_rejects_extreme_homogeneous_sources_before_clipping() {
5211        let outside_x = f32::from_bits(1.0_f32.to_bits() + 1);
5212        let mesh = Mesh3d::with_display_edges(
5213            vec![
5214                Vec3::new(-outside_x, f32::MAX, 1.0).unwrap(),
5215                Vec3::new(-outside_x, -f32::MAX, 1.0).unwrap(),
5216            ],
5217            Vec::new(),
5218            vec![MeshEdge3d::new(0, 1).unwrap()],
5219        )
5220        .unwrap();
5221        let camera = Camera3d::look_at(
5222            Vec3::ZERO,
5223            Vec3::new(0.0, 0.0, 1.0).unwrap(),
5224            Vec3::Y,
5225            Projection3d::orthographic(world(2.0), 1.0, world(1.0), world(10.0)).unwrap(),
5226        )
5227        .unwrap();
5228        let style = WireframeStyle3d::visible(Color::WHITE, logical(1.0)).unwrap();
5229        let model_rows = Transform3d::IDENTITY.model_rows().unwrap();
5230        let camera_rows = camera.world_to_clip_rows().unwrap();
5231
5232        assert_eq!(
5233            validate_shader_transform(&mesh, model_rows, camera_rows),
5234            Err(Mesh3dRenderError::InvalidGeometryTransform)
5235        );
5236        assert_eq!(
5237            validate_edge_projection(
5238                &mesh,
5239                model_rows,
5240                camera_rows,
5241                style,
5242                [128.0, 128.0, 1.0, 0.0],
5243            ),
5244            Err(Mesh3dRenderError::InvalidGeometryTransform)
5245        );
5246    }
5247
5248    #[test]
5249    fn edge_projection_rejects_subnormal_component_scaled_clip_boundary() {
5250        let near = f32::from_bits(0x327e_4a5c) * 0.5;
5251        let clip_w = f32::from_bits(0x327e_4a5c);
5252        let clip_x = f32::from_bits(clip_w.to_bits() + 1);
5253        let clip_y = f32::from_bits(0x41db_c900);
5254        let camera = Camera3d::look_at(
5255            Vec3::ZERO,
5256            Vec3::new(0.0, 0.0, 1.0).unwrap(),
5257            Vec3::Y,
5258            Projection3d::perspective(std::f32::consts::FRAC_PI_2, 1.0, world(near), world(1.0))
5259                .unwrap(),
5260        )
5261        .unwrap();
5262        let camera_rows = camera.world_to_clip_rows().unwrap();
5263        let start = Vec3::new(
5264            clip_x / camera_rows[0][0],
5265            clip_y / camera_rows[1][1],
5266            clip_w,
5267        )
5268        .unwrap();
5269        let end = Vec3::new(
5270            clip_x / camera_rows[0][0],
5271            -clip_y / camera_rows[1][1],
5272            clip_w,
5273        )
5274        .unwrap();
5275        let mesh = Mesh3d::with_display_edges(
5276            vec![start, end],
5277            Vec::new(),
5278            vec![MeshEdge3d::new(0, 1).unwrap()],
5279        )
5280        .unwrap();
5281        let model_rows = Transform3d::IDENTITY.model_rows().unwrap();
5282        let start_clip = shader_clip_point_ranges(start, model_rows, camera_rows).unwrap();
5283        assert_eq!(start_clip[0].fixed, clip_x);
5284        assert_eq!(start_clip[1].fixed, clip_y);
5285        assert_eq!(start_clip[3].fixed, clip_w);
5286
5287        assert_eq!(
5288            validate_shader_transform(&mesh, model_rows, camera_rows),
5289            Err(Mesh3dRenderError::InvalidGeometryTransform)
5290        );
5291        assert_eq!(
5292            validate_edge_projection(
5293                &mesh,
5294                model_rows,
5295                camera_rows,
5296                WireframeStyle3d::visible(Color::WHITE, logical(1.0)).unwrap(),
5297                [128.0, 128.0, 1.0, 0.0],
5298            ),
5299            Err(Mesh3dRenderError::InvalidGeometryTransform)
5300        );
5301    }
5302
5303    #[test]
5304    fn edge_projection_rejects_ftz_sensitive_pair_scale_inputs() {
5305        let largest_subnormal = f32::from_bits(0x007f_ffff);
5306        let mesh = Mesh3d::with_display_edges(
5307            vec![
5308                Vec3::new(0.0, largest_subnormal, 1.0).unwrap(),
5309                Vec3::new(0.5, largest_subnormal, 1.0).unwrap(),
5310            ],
5311            Vec::new(),
5312            vec![MeshEdge3d::new(0, 1).unwrap()],
5313        )
5314        .unwrap();
5315        let transform = Transform3d::new(
5316            Vec3::new(0.0, f32::from_bits(1.0_f32.to_bits() + 1), 0.0).unwrap(),
5317            Rotation3d::IDENTITY,
5318            Vec3::new(1.0, f32::MAX, 1.0).unwrap(),
5319        )
5320        .unwrap();
5321        let camera = Camera3d::look_at(
5322            Vec3::ZERO,
5323            Vec3::new(0.0, 0.0, 1.0).unwrap(),
5324            Vec3::Y,
5325            Projection3d::orthographic(world(2.0), 1.0, world(1.0), world(10.0)).unwrap(),
5326        )
5327        .unwrap();
5328        let model_rows = transform.model_rows().unwrap();
5329        let camera_rows = camera.world_to_clip_rows().unwrap();
5330
5331        assert_eq!(
5332            validate_shader_transform(&mesh, model_rows, camera_rows),
5333            Err(Mesh3dRenderError::InvalidGeometryTransform)
5334        );
5335        assert_eq!(
5336            validate_edge_projection(
5337                &mesh,
5338                model_rows,
5339                camera_rows,
5340                WireframeStyle3d::visible(Color::WHITE, logical(1.0)).unwrap(),
5341                [128.0, 128.0, 1.0, 0.0],
5342            ),
5343            Err(Mesh3dRenderError::InvalidGeometryTransform)
5344        );
5345    }
5346
5347    #[test]
5348    fn edge_projection_rejects_values_outside_portable_width_envelope() {
5349        let maximum_width = logical(1_048_576.0);
5350        let requested_scale = f32::MAX / maximum_width.get();
5351        let logical_viewport =
5352            LogicalViewport::new(1.0 / requested_scale, 8_192.0 / requested_scale).unwrap();
5353        let pixels_per_logical = target_pixels_per_logical(1, 8_192, logical_viewport).unwrap();
5354        let scaled_width = maximum_width.get() * pixels_per_logical.get();
5355        assert!(scaled_width.is_finite());
5356
5357        let view_depth = f32::from_bits(0x7f4d_1ce4);
5358        let aspect = 1.0 / 8_192.0;
5359        let vertical_fov = 1.0_f32;
5360        let horizontal_scale = (vertical_fov * 0.5).tan() * aspect;
5361        let half_x = view_depth * 0.5 * horizontal_scale;
5362        let mesh = Mesh3d::with_display_edges(
5363            vec![
5364                Vec3::new(-half_x, 0.0, -view_depth).unwrap(),
5365                Vec3::new(half_x, 0.0, -view_depth).unwrap(),
5366            ],
5367            Vec::new(),
5368            vec![MeshEdge3d::new(0, 1).unwrap()],
5369        )
5370        .unwrap();
5371        let camera = Camera3d::look_at(
5372            Vec3::ZERO,
5373            Vec3::new(0.0, 0.0, -1.0).unwrap(),
5374            Vec3::Y,
5375            Projection3d::perspective(vertical_fov, aspect, world(1.0), world(f32::MAX)).unwrap(),
5376        )
5377        .unwrap();
5378        let style = WireframeStyle3d::visible(Color::WHITE, maximum_width).unwrap();
5379
5380        assert_eq!(
5381            validate_edge_projection(
5382                &mesh,
5383                Transform3d::IDENTITY.model_rows().unwrap(),
5384                camera.world_to_clip_rows().unwrap(),
5385                style,
5386                [1.0, 8_192.0, pixels_per_logical.get(), 0.0],
5387            ),
5388            Err(Mesh3dRenderError::InvalidEdgeProjection)
5389        );
5390    }
5391
5392    #[test]
5393    fn scene3d_rejects_out_of_range_clear_colors() {
5394        assert!(matches!(
5395            Scene3d::new(Color::rgb(1.01, 0.0, 0.0)),
5396            Err(Scene3dError::InvalidBackground)
5397        ));
5398    }
5399
5400    #[test]
5401    fn retained_mesh_and_scene_transform_reject_nonportable_shader_sources() {
5402        let subnormal = f32::from_bits(1);
5403        let mesh = Mesh3d::with_display_edges(
5404            vec![
5405                Vec3::new(subnormal, 0.0, 0.0).unwrap(),
5406                Vec3::new(1.0, 0.0, 0.0).unwrap(),
5407            ],
5408            Vec::new(),
5409            vec![MeshEdge3d::new(0, 1).unwrap()],
5410        )
5411        .unwrap();
5412        assert!(!mesh3d_source_is_portable(&mesh));
5413
5414        let transform = Transform3d::new(
5415            Vec3::new(subnormal, 0.0, 0.0).unwrap(),
5416            Rotation3d::IDENTITY,
5417            Vec3::new(1.0, 1.0, 1.0).unwrap(),
5418        )
5419        .unwrap();
5420        assert_eq!(
5421            validate_scene3d_transform(transform),
5422            Err(Scene3dError::InvalidTransform)
5423        );
5424        assert_eq!(validate_scene3d_transform(Transform3d::IDENTITY), Ok(()));
5425    }
5426
5427    #[test]
5428    fn edge_crossing_near_plane_is_clipped_before_wgsl_division() {
5429        let mesh = Mesh3d::with_display_edges(
5430            vec![
5431                Vec3::new(0.0, 0.0, -0.05).unwrap(),
5432                Vec3::new(0.5, 0.0, -1.0).unwrap(),
5433            ],
5434            Vec::new(),
5435            vec![MeshEdge3d::new(0, 1).unwrap()],
5436        )
5437        .unwrap();
5438        let camera = Camera3d::look_at(
5439            Vec3::ZERO,
5440            Vec3::new(0.0, 0.0, -1.0).unwrap(),
5441            Vec3::Y,
5442            Projection3d::perspective(1.0, 1.0, world(0.1), world(10.0)).unwrap(),
5443        )
5444        .unwrap();
5445        let style = WireframeStyle3d::visible(Color::WHITE, logical(1.0)).unwrap();
5446        assert_eq!(
5447            validate_edge_projection(
5448                &mesh,
5449                Transform3d::IDENTITY.model_rows().unwrap(),
5450                camera.world_to_clip_rows().unwrap(),
5451                style,
5452                [100.0, 100.0, 1.0, 0.0],
5453            ),
5454            Ok(())
5455        );
5456    }
5457
5458    #[test]
5459    fn fully_clipped_edges_do_not_reject_the_frame() {
5460        let mesh = Mesh3d::with_display_edges(
5461            vec![
5462                Vec3::new(0.0, 0.0, -0.01).unwrap(),
5463                Vec3::new(0.01, 0.0, -0.05).unwrap(),
5464            ],
5465            Vec::new(),
5466            vec![MeshEdge3d::new(0, 1).unwrap()],
5467        )
5468        .unwrap();
5469        let camera = Camera3d::look_at(
5470            Vec3::ZERO,
5471            Vec3::new(0.0, 0.0, -1.0).unwrap(),
5472            Vec3::Y,
5473            Projection3d::perspective(1.0, 1.0, world(0.1), world(10.0)).unwrap(),
5474        )
5475        .unwrap();
5476        assert_eq!(
5477            validate_edge_projection(
5478                &mesh,
5479                Transform3d::IDENTITY.model_rows().unwrap(),
5480                camera.world_to_clip_rows().unwrap(),
5481                WireframeStyle3d::visible(Color::WHITE, logical(1.0)).unwrap(),
5482                [100.0, 100.0, 1.0, 0.0],
5483            ),
5484            Ok(())
5485        );
5486    }
5487
5488    #[test]
5489    fn homogeneous_edge_clipping_covers_near_far_and_camera_half_spaces() {
5490        let near = clip_edge_to_frustum([0.0, 0.0, -0.5, 1.0], [0.0, 0.0, 0.5, 1.0])
5491            .unwrap()
5492            .unwrap();
5493        assert!(near[0][2].abs() <= f32::EPSILON);
5494        assert_eq!(near[1], [0.0, 0.0, 0.5, 1.0]);
5495
5496        let far = clip_edge_to_frustum([0.0, 0.0, 0.5, 1.0], [0.0, 0.0, 2.0, 1.0])
5497            .unwrap()
5498            .unwrap();
5499        assert!((far[1][2] - far[1][3]).abs() <= f32::EPSILON);
5500
5501        assert_eq!(
5502            clip_edge_to_frustum([0.0, 0.0, -2.0, -1.0], [0.0, 0.0, -1.0, -0.5]),
5503            Ok(None)
5504        );
5505        assert_eq!(
5506            clip_edge_to_frustum([-3.0, 0.0, 0.5, 1.0], [-2.0, 0.0, 0.5, 1.0]),
5507            Ok(None)
5508        );
5509    }
5510
5511    #[test]
5512    fn target_pixel_scale_is_independent_of_window_dpi() {
5513        let viewport = LogicalViewport::new(1000.0, 500.0).unwrap();
5514        assert_eq!(
5515            target_pixels_per_logical(2000, 1000, viewport),
5516            Some(physical_per_logical(2.0))
5517        );
5518        assert_eq!(
5519            target_pixels_per_logical(500, 250, viewport),
5520            Some(physical_per_logical(0.5))
5521        );
5522        assert_eq!(target_pixels_per_logical(500, 300, viewport), None);
5523        assert!(aspect_matches(16.0 / 9.0, 1920.0 / 1080.0));
5524        assert!(!aspect_matches(16.0 / 9.0, 4.0 / 3.0));
5525        assert!(!aspect_matches(1.0 / 8_192.0, (1.0 / 8_192.0) * 1.08));
5526        assert_eq!(
5527            target_pixels_per_logical(
5528                1,
5529                8_192,
5530                LogicalViewport::new(100_000.0, 431_157_900.0).unwrap(),
5531            ),
5532            None
5533        );
5534    }
5535
5536    #[test]
5537    fn camera_target_aspect_mismatch_is_rejected_by_render_contract() {
5538        let camera = Camera3d::look_at(
5539            Vec3::new(0.0, 0.0, 5.0).unwrap(),
5540            Vec3::ZERO,
5541            Vec3::Y,
5542            Projection3d::perspective(1.0, 16.0 / 9.0, world(0.1), world(10.0)).unwrap(),
5543        )
5544        .unwrap();
5545        let target = LogicalViewport::new(800.0, 600.0).unwrap();
5546        assert_eq!(
5547            validate_camera_target_aspect(camera, target),
5548            Err(Mesh3dRenderError::CameraTargetAspectMismatch)
5549        );
5550    }
5551
5552    #[test]
5553    fn logical_edge_width_is_equal_for_native_and_half_resolution_target() {
5554        let logical_width = logical(1.0);
5555        for pixels_per_logical in [physical_per_logical(2.0), physical_per_logical(0.5)] {
5556            let physical_width = edge_raster_envelope(logical_width, pixels_per_logical)
5557                .unwrap()
5558                .physical_half_width
5559                * 2.0;
5560            assert_eq!(
5561                physical_width / pixels_per_logical.get(),
5562                logical_width.get()
5563            );
5564        }
5565    }
5566
5567    #[test]
5568    fn mesh_upload_preflight_rejects_each_buffer_before_staging_allocation() {
5569        let max_buffer_size = 48;
5570        let layout = preflight_mesh3d_upload(4, 12, 2, max_buffer_size).unwrap();
5571        assert_eq!(layout.vertex_bytes, 48);
5572        assert_eq!(layout.index_bytes, 48);
5573        assert_eq!(layout.edge_bytes, 48);
5574        assert_eq!(layout.total_bytes, 144);
5575
5576        assert_eq!(
5577            preflight_mesh3d_upload(5, 0, 0, max_buffer_size),
5578            Err(Mesh3dResourceError::CapacityTooLarge)
5579        );
5580        assert_eq!(
5581            preflight_mesh3d_upload(1, 13, 0, max_buffer_size),
5582            Err(Mesh3dResourceError::CapacityTooLarge)
5583        );
5584        assert_eq!(
5585            preflight_mesh3d_upload(1, 0, 3, max_buffer_size),
5586            Err(Mesh3dResourceError::CapacityTooLarge)
5587        );
5588
5589        if usize::BITS > u32::BITS {
5590            let first_draw_count_overflow = u32::MAX as usize + 1;
5591            assert_eq!(
5592                preflight_mesh3d_upload(1, first_draw_count_overflow, 0, u64::MAX),
5593                Err(Mesh3dResourceError::CapacityTooLarge)
5594            );
5595            assert_eq!(
5596                preflight_mesh3d_upload(1, 0, first_draw_count_overflow, u64::MAX),
5597                Err(Mesh3dResourceError::CapacityTooLarge)
5598            );
5599        }
5600    }
5601}