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