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