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        Ok(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    }
98
99    fn rows(self) -> [[f32; 4]; 4] {
100        [
101            self.clip_row_0,
102            self.clip_row_1,
103            self.clip_row_2,
104            self.clip_row_3,
105        ]
106    }
107}
108
109#[repr(C)]
110#[derive(Clone, Copy, Debug, bytemuck::Pod, bytemuck::Zeroable)]
111struct MeshEdgeGpu {
112    start: [f32; 3],
113    end: [f32; 3],
114}
115
116impl MeshEdgeGpu {
117    const ATTRIBUTES: [wgpu::VertexAttribute; 2] =
118        wgpu::vertex_attr_array![0 => Float32x3, 1 => Float32x3];
119    const LAYOUT: wgpu::VertexBufferLayout<'static> = wgpu::VertexBufferLayout {
120        array_stride: std::mem::size_of::<Self>() as wgpu::BufferAddress,
121        step_mode: wgpu::VertexStepMode::Instance,
122        attributes: &Self::ATTRIBUTES,
123    };
124}
125
126#[repr(C)]
127#[derive(Clone, Copy, Debug, bytemuck::Pod, bytemuck::Zeroable)]
128struct EdgeObjectUniform {
129    model_row_0: [f32; 4],
130    model_row_1: [f32; 4],
131    model_row_2: [f32; 4],
132    visible_color: [f32; 4],
133    hidden_color: [f32; 4],
134    edge_style: [f32; 4],
135}
136
137#[cfg(test)]
138#[repr(C)]
139#[derive(Clone, Copy, Debug, bytemuck::Pod, bytemuck::Zeroable)]
140struct ClipProbeInputGpu {
141    start_clip: [f32; 4],
142    end_clip: [f32; 4],
143}
144
145#[cfg(test)]
146#[repr(C)]
147#[derive(Clone, Copy, Debug, bytemuck::Pod, bytemuck::Zeroable)]
148struct ClipProbeOutputGpu {
149    start_clip: [f32; 4],
150    end_clip: [f32; 4],
151    range: [f32; 2],
152    visible: u32,
153    padding: u32,
154}
155
156pub(super) struct Mesh3dRenderer {
157    pipeline: wgpu::RenderPipeline,
158    visible_edge_pipeline: wgpu::RenderPipeline,
159    hidden_edge_pipeline: wgpu::RenderPipeline,
160    camera_uniform_buffer: wgpu::Buffer,
161    camera_bind_group: wgpu::BindGroup,
162    instance_buffer: wgpu::Buffer,
163    instance_capacity: usize,
164    instances: Vec<MeshInstanceGpu>,
165    edge_object_layout: wgpu::BindGroupLayout,
166    edge_object_bind_group: wgpu::BindGroup,
167    edge_object_buffer: wgpu::Buffer,
168    edge_object_stride: usize,
169    edge_object_capacity: usize,
170    edge_object_bytes: Vec<u8>,
171}
172
173impl Mesh3dRenderer {
174    pub(super) fn new(device: &wgpu::Device, format: wgpu::TextureFormat) -> Self {
175        let shader = device.create_shader_module(wgpu::ShaderModuleDescriptor {
176            label: Some("sim-engine retained 3D mesh shader"),
177            source: wgpu::ShaderSource::Wgsl(Cow::Borrowed(include_str!("mesh3d.wgsl"))),
178        });
179        let camera_uniform_buffer = device.create_buffer(&wgpu::BufferDescriptor {
180            label: Some("sim-engine 3D camera uniform buffer"),
181            size: std::mem::size_of::<Camera3dUniform>() as wgpu::BufferAddress,
182            usage: wgpu::BufferUsages::UNIFORM | wgpu::BufferUsages::COPY_DST,
183            mapped_at_creation: false,
184        });
185        let camera_layout = device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
186            label: Some("sim-engine 3D camera bind group layout"),
187            entries: &[wgpu::BindGroupLayoutEntry {
188                binding: 0,
189                visibility: wgpu::ShaderStages::VERTEX,
190                ty: wgpu::BindingType::Buffer {
191                    ty: wgpu::BufferBindingType::Uniform,
192                    has_dynamic_offset: false,
193                    min_binding_size: None,
194                },
195                count: None,
196            }],
197        });
198        let camera_bind_group = device.create_bind_group(&wgpu::BindGroupDescriptor {
199            label: Some("sim-engine 3D camera bind group"),
200            layout: &camera_layout,
201            entries: &[wgpu::BindGroupEntry {
202                binding: 0,
203                resource: camera_uniform_buffer.as_entire_binding(),
204            }],
205        });
206        let edge_object_stride = align_to(
207            std::mem::size_of::<EdgeObjectUniform>(),
208            device.limits().min_uniform_buffer_offset_alignment as usize,
209        );
210        let edge_object_layout =
211            device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
212                label: Some("sim-engine 3D edge object bind group layout"),
213                entries: &[wgpu::BindGroupLayoutEntry {
214                    binding: 0,
215                    visibility: wgpu::ShaderStages::VERTEX_FRAGMENT,
216                    ty: wgpu::BindingType::Buffer {
217                        ty: wgpu::BufferBindingType::Uniform,
218                        has_dynamic_offset: true,
219                        min_binding_size: wgpu::BufferSize::new(
220                            std::mem::size_of::<EdgeObjectUniform>() as u64,
221                        ),
222                    },
223                    count: None,
224                }],
225            });
226        let edge_object_buffer =
227            create_edge_object_buffer(device, edge_object_stride, INITIAL_INSTANCE_CAPACITY);
228        let edge_object_bind_group =
229            create_edge_object_bind_group(device, &edge_object_layout, &edge_object_buffer);
230        let pipeline_layout = device.create_pipeline_layout(&wgpu::PipelineLayoutDescriptor {
231            label: Some("sim-engine retained 3D mesh pipeline layout"),
232            bind_group_layouts: &[Some(&camera_layout)],
233            immediate_size: 0,
234        });
235        let pipeline = device.create_render_pipeline(&wgpu::RenderPipelineDescriptor {
236            label: Some("sim-engine retained 3D mesh pipeline"),
237            layout: Some(&pipeline_layout),
238            vertex: wgpu::VertexState {
239                module: &shader,
240                entry_point: Some("mesh3d_vs_main"),
241                compilation_options: wgpu::PipelineCompilationOptions::default(),
242                buffers: &[Some(MeshVertexGpu::LAYOUT), Some(MeshInstanceGpu::LAYOUT)],
243            },
244            primitive: wgpu::PrimitiveState {
245                topology: wgpu::PrimitiveTopology::TriangleList,
246                ..Default::default()
247            },
248            depth_stencil: Some(wgpu::DepthStencilState {
249                format: DEPTH_FORMAT,
250                depth_write_enabled: Some(true),
251                depth_compare: Some(wgpu::CompareFunction::Less),
252                stencil: wgpu::StencilState::default(),
253                bias: wgpu::DepthBiasState::default(),
254            }),
255            multisample: wgpu::MultisampleState::default(),
256            fragment: Some(wgpu::FragmentState {
257                module: &shader,
258                entry_point: Some("mesh3d_fs_main"),
259                compilation_options: wgpu::PipelineCompilationOptions::default(),
260                targets: &[Some(wgpu::ColorTargetState {
261                    format,
262                    blend: None,
263                    write_mask: wgpu::ColorWrites::ALL,
264                })],
265            }),
266            multiview_mask: None,
267            cache: None,
268        });
269        let edge_pipeline_layout = device.create_pipeline_layout(&wgpu::PipelineLayoutDescriptor {
270            label: Some("sim-engine 3D edge pipeline layout"),
271            bind_group_layouts: &[Some(&camera_layout), Some(&edge_object_layout)],
272            immediate_size: 0,
273        });
274        let visible_edge_pipeline = create_edge_pipeline(
275            device,
276            &shader,
277            &edge_pipeline_layout,
278            format,
279            wgpu::CompareFunction::LessEqual,
280            "mesh3d_visible_edge_fs_main",
281            "sim-engine visible 3D edge pipeline",
282        );
283        let hidden_edge_pipeline = create_edge_pipeline(
284            device,
285            &shader,
286            &edge_pipeline_layout,
287            format,
288            wgpu::CompareFunction::Greater,
289            "mesh3d_hidden_edge_fs_main",
290            "sim-engine hidden 3D edge pipeline",
291        );
292        Self {
293            pipeline,
294            visible_edge_pipeline,
295            hidden_edge_pipeline,
296            camera_uniform_buffer,
297            camera_bind_group,
298            instance_buffer: create_instance_buffer(device, INITIAL_INSTANCE_CAPACITY),
299            instance_capacity: INITIAL_INSTANCE_CAPACITY,
300            instances: Vec::with_capacity(INITIAL_INSTANCE_CAPACITY),
301            edge_object_layout,
302            edge_object_bind_group,
303            edge_object_buffer,
304            edge_object_stride,
305            edge_object_capacity: INITIAL_INSTANCE_CAPACITY,
306            edge_object_bytes: Vec::with_capacity(edge_object_stride * INITIAL_INSTANCE_CAPACITY),
307        }
308    }
309
310    fn ensure_instance_capacity(
311        &mut self,
312        device: &wgpu::Device,
313        instance_count: usize,
314    ) -> Result<(), Mesh3dRenderError> {
315        if instance_count <= self.instance_capacity {
316            return Ok(());
317        }
318        let capacity = instance_count
319            .checked_next_power_of_two()
320            .filter(|capacity| buffer_capacity_fits::<MeshInstanceGpu>(device, *capacity))
321            .ok_or(Mesh3dRenderError::InstanceCapacityTooLarge)?;
322        self.instance_buffer = create_instance_buffer(device, capacity);
323        self.instance_capacity = capacity;
324        self.instances
325            .reserve(capacity.saturating_sub(self.instances.capacity()));
326        Ok(())
327    }
328
329    fn ensure_edge_object_capacity(
330        &mut self,
331        device: &wgpu::Device,
332        object_count: usize,
333    ) -> Result<(), Mesh3dRenderError> {
334        if object_count <= self.edge_object_capacity {
335            return Ok(());
336        }
337        let capacity = object_count
338            .checked_next_power_of_two()
339            .filter(|capacity| {
340                capacity
341                    .checked_mul(self.edge_object_stride)
342                    .is_some_and(|bytes| {
343                        bytes as u64 <= device.limits().max_buffer_size
344                            && bytes <= u32::MAX as usize
345                    })
346            })
347            .ok_or(Mesh3dRenderError::InstanceCapacityTooLarge)?;
348        self.edge_object_buffer =
349            create_edge_object_buffer(device, self.edge_object_stride, capacity);
350        self.edge_object_bind_group = create_edge_object_bind_group(
351            device,
352            &self.edge_object_layout,
353            &self.edge_object_buffer,
354        );
355        self.edge_object_capacity = capacity;
356        self.edge_object_bytes.reserve(
357            capacity
358                .saturating_mul(self.edge_object_stride)
359                .saturating_sub(self.edge_object_bytes.capacity()),
360        );
361        Ok(())
362    }
363}
364
365/// Immutable retained GPU buffers for one validated [`Mesh3d`].
366///
367/// The resource belongs to the renderer that created it and retains the core
368/// topology for explicit device-loss restoration.
369#[derive(Clone)]
370pub struct RetainedMesh3d {
371    renderer_identity: Arc<()>,
372    vertex_buffer: Arc<wgpu::Buffer>,
373    index_buffer: Option<Arc<wgpu::Buffer>>,
374    edge_buffer: Option<Arc<wgpu::Buffer>>,
375    source: Mesh3d,
376    index_count: u32,
377    edge_count: u32,
378    gpu_allocation_bytes: usize,
379}
380
381impl RetainedMesh3d {
382    /// Returns the immutable core topology retained for recovery.
383    pub fn source(&self) -> &Mesh3d {
384        &self.source
385    }
386
387    /// Returns the retained triangle count.
388    pub fn triangle_count(&self) -> usize {
389        self.source.triangle_count()
390    }
391
392    /// Returns exact vertex, triangle-index, and display-edge buffer bytes.
393    pub const fn gpu_allocation_bytes(&self) -> usize {
394        self.gpu_allocation_bytes
395    }
396
397    /// Returns CPU topology bytes retained for device-loss restoration.
398    pub fn recovery_memory_bytes(&self) -> usize {
399        self.source.recovery_memory_bytes()
400    }
401}
402
403/// Stable scene handle for a retained 3D object.
404#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
405pub struct Object3dId {
406    scene_id: u64,
407    object_id: u64,
408}
409
410impl Object3dId {
411    /// Returns the stable scene-local numeric value for diagnostics.
412    ///
413    /// Equality and hashing also include private scene provenance. Store the
414    /// complete handle, rather than only this number, in host object maps.
415    pub const fn get(self) -> u64 {
416        self.object_id
417    }
418}
419
420/// One retained mesh reference plus its independent model transform and style.
421#[derive(Clone)]
422pub struct Mesh3dInstance {
423    id: Object3dId,
424    mesh: RetainedMesh3d,
425    transform: Transform3d,
426    style: MeshStyle3d,
427    visible: bool,
428}
429
430impl Mesh3dInstance {
431    fn new(
432        id: Object3dId,
433        mesh: &RetainedMesh3d,
434        transform: Transform3d,
435        style: MeshStyle3d,
436    ) -> Self {
437        Self {
438            id,
439            mesh: mesh.clone(),
440            transform,
441            style,
442            visible: true,
443        }
444    }
445
446    /// Returns the stable scene object identifier.
447    pub const fn id(&self) -> Object3dId {
448        self.id
449    }
450
451    /// Returns the retained GPU mesh reference.
452    pub const fn mesh(&self) -> &RetainedMesh3d {
453        &self.mesh
454    }
455
456    /// Returns this object's model-to-world transform.
457    pub const fn transform(&self) -> Transform3d {
458        self.transform
459    }
460
461    /// Returns its extensible surface/edge material bundle.
462    pub const fn style(&self) -> MeshStyle3d {
463        self.style
464    }
465
466    /// Returns whether this object participates in drawing and render counts.
467    pub const fn is_visible(&self) -> bool {
468        self.visible
469    }
470
471    /// Returns explicit edge presentation when enabled for this object.
472    pub const fn wireframe(&self) -> Option<WireframeStyle3d> {
473        self.style.wireframe_style()
474    }
475}
476
477/// Ready 3D visual state rendered with one camera and depth attachment.
478pub struct Scene3d {
479    scene_id: u64,
480    background: Color,
481    instances: Vec<Mesh3dInstance>,
482    next_object_id: u64,
483}
484
485impl Scene3d {
486    /// Creates an empty scene with a normalized opaque clear color.
487    pub fn new(background: Color) -> Result<Self, Scene3dError> {
488        if !background.is_normalized() || background.alpha() != 1.0 {
489            return Err(Scene3dError::InvalidBackground);
490        }
491        let scene_id = NEXT_SCENE3D_ID
492            .fetch_update(Ordering::Relaxed, Ordering::Relaxed, |current| {
493                current.checked_add(1)
494            })
495            .map_err(|_| Scene3dError::SceneIdExhausted)?;
496        Ok(Self {
497            scene_id,
498            background,
499            instances: Vec::new(),
500            next_object_id: 0,
501        })
502    }
503
504    /// Adds a retained object and returns a stable handle for later updates.
505    pub fn try_push(
506        &mut self,
507        mesh: &RetainedMesh3d,
508        transform: Transform3d,
509        style: MeshStyle3d,
510    ) -> Result<Object3dId, Scene3dError> {
511        validate_mesh_style(mesh, style)?;
512        let id = Object3dId {
513            scene_id: self.scene_id,
514            object_id: self.next_object_id,
515        };
516        self.next_object_id = self
517            .next_object_id
518            .checked_add(1)
519            .ok_or(Scene3dError::ObjectIdExhausted)?;
520        self.instances
521            .push(Mesh3dInstance::new(id, mesh, transform, style));
522        Ok(id)
523    }
524
525    /// Returns the finite opaque target clear color.
526    pub const fn background(&self) -> Color {
527        self.background
528    }
529
530    /// Returns objects in host insertion order; depth determines visibility.
531    pub fn instances(&self) -> &[Mesh3dInstance] {
532        &self.instances
533    }
534
535    /// Returns the number of independently transformed objects.
536    pub fn object_count(&self) -> usize {
537        self.instances.len()
538    }
539
540    /// Returns objects currently participating in rendering.
541    pub fn visible_object_count(&self) -> usize {
542        self.instances
543            .iter()
544            .filter(|instance| instance.visible)
545            .count()
546    }
547
548    /// Replaces one object's model transform without touching retained topology.
549    pub fn set_transform(
550        &mut self,
551        object_id: Object3dId,
552        transform: Transform3d,
553    ) -> Result<(), Scene3dError> {
554        let instance = self.instance_mut(object_id)?;
555        instance.transform = transform;
556        Ok(())
557    }
558
559    /// Replaces one object's complete extensible visual material bundle.
560    pub fn set_style(
561        &mut self,
562        object_id: Object3dId,
563        style: MeshStyle3d,
564    ) -> Result<(), Scene3dError> {
565        let instance = self.instance_mut(object_id)?;
566        validate_mesh_style(&instance.mesh, style)?;
567        instance.style = style;
568        Ok(())
569    }
570
571    /// Shows or hides one object without releasing retained topology.
572    pub fn set_visible(
573        &mut self,
574        object_id: Object3dId,
575        visible: bool,
576    ) -> Result<(), Scene3dError> {
577        let instance = self.instance_mut(object_id)?;
578        instance.visible = visible;
579        Ok(())
580    }
581
582    /// Enables or disables explicit visible/hidden edges for one object.
583    pub fn set_wireframe(
584        &mut self,
585        object_id: Object3dId,
586        wireframe: Option<WireframeStyle3d>,
587    ) -> Result<(), Scene3dError> {
588        let instance = self.instance_mut(object_id)?;
589        let surface = instance.style.surface_style();
590        let style = match (surface, wireframe) {
591            (Some(surface), Some(wireframe)) => {
592                MeshStyle3d::surface(surface).with_wireframe(wireframe)
593            }
594            (Some(surface), None) => MeshStyle3d::surface(surface),
595            (None, Some(wireframe)) => MeshStyle3d::wireframe(wireframe),
596            (None, None) => return Err(Scene3dError::EmptyStyle),
597        };
598        validate_mesh_style(&instance.mesh, style)?;
599        instance.style = style;
600        Ok(())
601    }
602
603    fn instance_mut(&mut self, object_id: Object3dId) -> Result<&mut Mesh3dInstance, Scene3dError> {
604        if object_id.scene_id != self.scene_id {
605            return Err(Scene3dError::ObjectNotFound { object_id });
606        }
607        self.instances
608            .iter_mut()
609            .find(|instance| instance.id == object_id)
610            .ok_or(Scene3dError::ObjectNotFound { object_id })
611    }
612}
613
614/// Offscreen color and depth attachments for stereometry rendering.
615pub struct RenderTarget3d {
616    renderer_identity: Arc<()>,
617    color: RenderTarget2d,
618    _depth_texture: wgpu::Texture,
619    depth_view: wgpu::TextureView,
620    logical_viewport: LogicalViewport,
621    pixels_per_logical: PhysicalPerLogical,
622}
623
624impl RenderTarget3d {
625    /// Returns target width in physical texture pixels.
626    pub fn width(&self) -> u32 {
627        self.color.width()
628    }
629
630    /// Returns target height in physical texture pixels.
631    pub fn height(&self) -> u32 {
632        self.color.height()
633    }
634
635    /// Returns the logical viewport represented by the offscreen texture.
636    pub const fn logical_viewport(&self) -> LogicalViewport {
637        self.logical_viewport
638    }
639
640    /// Returns target texels per logical screen pixel.
641    pub const fn pixels_per_logical(&self) -> PhysicalPerLogical {
642        self.pixels_per_logical
643    }
644
645    /// Returns the composable 2D color attachment.
646    pub const fn color_target(&self) -> &RenderTarget2d {
647        &self.color
648    }
649
650    /// Returns color plus depth allocation bytes.
651    pub fn allocation_bytes(&self) -> usize {
652        self.color.allocation_bytes().saturating_add(
653            (self.width() as usize)
654                .saturating_mul(self.height() as usize)
655                .saturating_mul(4),
656        )
657    }
658}
659
660/// Rejection reason for 3D scene visual state.
661#[derive(Debug, Clone, Copy, PartialEq, Eq)]
662pub enum Scene3dError {
663    /// The target clear color must be normalized and opaque.
664    InvalidBackground,
665    /// Surface and wireframe were both disabled.
666    EmptyStyle,
667    /// The selected surface/edge modes have no corresponding mesh topology.
668    StyleHasNoMatchingGeometry,
669    /// No more process-unique scene identifiers can be allocated.
670    SceneIdExhausted,
671    /// No more stable object identifiers can be allocated.
672    ObjectIdExhausted,
673    /// An object update referenced a missing stable handle.
674    ObjectNotFound {
675        /// Stable handle that is absent from this scene.
676        object_id: Object3dId,
677    },
678}
679
680impl fmt::Display for Scene3dError {
681    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
682        match self {
683            Self::InvalidBackground => write!(formatter, "3D scene background must be opaque"),
684            Self::EmptyStyle => write!(formatter, "3D object requires a surface or wireframe"),
685            Self::StyleHasNoMatchingGeometry => write!(
686                formatter,
687                "3D object style has no matching triangles or display edges"
688            ),
689            Self::SceneIdExhausted => write!(formatter, "3D scene identifiers exhausted"),
690            Self::ObjectIdExhausted => write!(formatter, "3D scene object identifiers exhausted"),
691            Self::ObjectNotFound { object_id } => write!(
692                formatter,
693                "3D scene object {} does not exist in this scene",
694                object_id.get()
695            ),
696        }
697    }
698}
699
700impl Error for Scene3dError {}
701
702fn validate_mesh_style(mesh: &RetainedMesh3d, style: MeshStyle3d) -> Result<(), Scene3dError> {
703    let has_surface = style.surface_style().is_some() && mesh.triangle_count() > 0;
704    let has_wireframe =
705        style.wireframe_style().is_some() && !mesh.source().display_edges().is_empty();
706    (has_surface || has_wireframe)
707        .then_some(())
708        .ok_or(Scene3dError::StyleHasNoMatchingGeometry)
709}
710
711/// Resource creation or ownership failure for retained 3D rendering.
712#[derive(Debug, Clone, Copy, PartialEq)]
713pub enum Mesh3dResourceError {
714    /// Vertex, index, or edge data exceeds the active device's buffer-size limit.
715    CapacityTooLarge,
716    /// Host staging memory could not be reserved after capacity preflight.
717    HostAllocationFailed {
718        /// Bytes requested for the rejected staging buffer.
719        requested_bytes: u64,
720    },
721    /// Color/depth target creation failed.
722    Target(RenderTargetError),
723    /// Physical texture and logical viewport aspect ratios differ.
724    InvalidViewportAspect,
725}
726
727impl fmt::Display for Mesh3dResourceError {
728    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
729        match self {
730            Self::CapacityTooLarge => write!(formatter, "3D mesh exceeds GPU buffer limits"),
731            Self::HostAllocationFailed { requested_bytes } => write!(
732                formatter,
733                "3D mesh could not reserve a {requested_bytes}-byte host staging buffer"
734            ),
735            Self::Target(error) => write!(formatter, "3D target creation failed: {error}"),
736            Self::InvalidViewportAspect => write!(
737                formatter,
738                "3D target texture and logical viewport must have one aspect ratio"
739            ),
740        }
741    }
742}
743
744impl Error for Mesh3dResourceError {}
745
746/// Failure while encoding a depth-tested 3D scene.
747#[derive(Debug, Clone, Copy, PartialEq, Eq)]
748pub enum Mesh3dRenderError {
749    /// A mesh or target belongs to another renderer/device identity.
750    RendererMismatch,
751    /// A finite model/camera configuration would overflow shader arithmetic.
752    InvalidGeometryTransform,
753    /// The per-frame object buffer exceeds the active device limit.
754    InstanceCapacityTooLarge,
755    /// Camera projection aspect does not match the target logical viewport.
756    CameraTargetAspectMismatch,
757    /// Edge projection or style arithmetic is not finite for this target.
758    InvalidEdgeProjection,
759}
760
761impl fmt::Display for Mesh3dRenderError {
762    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
763        match self {
764            Self::RendererMismatch => {
765                write!(formatter, "3D scene resource belongs to another renderer")
766            }
767            Self::InvalidGeometryTransform => {
768                write!(formatter, "3D transform would produce invalid GPU geometry")
769            }
770            Self::InstanceCapacityTooLarge => write!(
771                formatter,
772                "3D object count exceeds the GPU instance-buffer limit"
773            ),
774            Self::CameraTargetAspectMismatch => write!(
775                formatter,
776                "3D camera aspect does not match the target logical viewport"
777            ),
778            Self::InvalidEdgeProjection => write!(
779                formatter,
780                "3D edge clipping or screen-space arithmetic overflowed"
781            ),
782        }
783    }
784}
785
786impl Error for Mesh3dRenderError {}
787
788/// CPU-side result of one depth-tested offscreen 3D draw.
789#[derive(Debug, Clone, Copy, PartialEq, Eq)]
790pub struct Mesh3dRenderReport {
791    object_count: usize,
792    triangle_count: usize,
793    edge_count: usize,
794    upload: Duration,
795    encode_submit: Duration,
796}
797
798impl Mesh3dRenderReport {
799    /// Returns independently transformed retained objects drawn.
800    pub const fn object_count(self) -> usize {
801        self.object_count
802    }
803
804    /// Returns total indexed triangles submitted across every object.
805    pub const fn triangle_count(self) -> usize {
806        self.triangle_count
807    }
808
809    /// Returns explicit mathematical edges submitted for depth classification.
810    pub const fn edge_count(self) -> usize {
811        self.edge_count
812    }
813
814    /// Returns CPU time spent validating and enqueuing camera/instance uploads.
815    pub const fn upload(self) -> Duration {
816        self.upload
817    }
818
819    /// Returns CPU time spent encoding and submitting the pass.
820    pub const fn encode_submit(self) -> Duration {
821        self.encode_submit
822    }
823}
824
825/// Result of atomically migrating a retained 3D scene to the active renderer device.
826#[derive(Debug, Clone, Copy, PartialEq, Eq)]
827pub struct Scene3dRestoreReport {
828    object_count: usize,
829    migrated_object_count: usize,
830    restored_mesh_count: usize,
831    restored_gpu_bytes: usize,
832}
833
834impl Scene3dRestoreReport {
835    /// Returns all scene objects whose stable IDs and visual state were preserved.
836    pub const fn object_count(self) -> usize {
837        self.object_count
838    }
839
840    /// Returns objects whose stale mesh reference was replaced in this call.
841    pub const fn migrated_object_count(self) -> usize {
842        self.migrated_object_count
843    }
844
845    /// Returns distinct retained mesh resources recreated on the active device.
846    pub const fn restored_mesh_count(self) -> usize {
847        self.restored_mesh_count
848    }
849
850    /// Returns total GPU bytes represented by the recreated distinct meshes.
851    pub const fn restored_gpu_bytes(self) -> usize {
852        self.restored_gpu_bytes
853    }
854}
855
856impl WgpuRenderer {
857    /// Uploads validated immutable topology into retained GPU buffers.
858    ///
859    /// Counts, byte arithmetic, draw-count representation, and active-device
860    /// buffer limits are checked before conversion staging allocation. Host
861    /// staging reservation failure is returned explicitly; GPU allocation
862    /// itself follows wgpu's device-error model.
863    pub fn create_mesh3d(&self, source: Mesh3d) -> Result<RetainedMesh3d, Mesh3dResourceError> {
864        create_retained_mesh(
865            &self.device,
866            &self.queue,
867            Arc::clone(&self.renderer_identity),
868            source,
869        )
870    }
871
872    /// Restores retained topology onto this renderer after device replacement.
873    pub fn restore_mesh3d(
874        &self,
875        source: &RetainedMesh3d,
876    ) -> Result<RetainedMesh3d, Mesh3dResourceError> {
877        self.create_mesh3d(source.source.clone())
878    }
879
880    /// Atomically restores every stale retained mesh referenced by a 3D scene.
881    ///
882    /// Distinct shared mesh resources are uploaded once. Object IDs, insertion
883    /// order, transforms, styles, visibility, scene provenance, and the next ID
884    /// remain unchanged. If any capacity or host-staging allocation fails, the
885    /// original scene is not modified. Targets remain separate resources and
886    /// must be restored with [`WgpuRenderer::restore_render_target3d`].
887    pub fn restore_scene3d(
888        &self,
889        scene: &mut Scene3d,
890    ) -> Result<Scene3dRestoreReport, Mesh3dResourceError> {
891        restore_scene3d_resources(
892            &self.device,
893            &self.queue,
894            Arc::clone(&self.renderer_identity),
895            scene,
896        )
897    }
898
899    /// Creates color/depth attachments for an explicit logical viewport.
900    ///
901    /// `width` and `height` are physical target texels. Their aspect must match
902    /// `logical_viewport`; the resulting texels-per-logical-pixel ratio controls
903    /// wireframe width independently of the window DPI scale.
904    pub fn create_render_target3d(
905        &self,
906        width: u32,
907        height: u32,
908        logical_viewport: LogicalViewport,
909    ) -> Result<RenderTarget3d, Mesh3dResourceError> {
910        let pixels_per_logical = target_pixels_per_logical(width, height, logical_viewport)
911            .ok_or(Mesh3dResourceError::InvalidViewportAspect)?;
912        let color = self
913            .create_render_target(width, height)
914            .map_err(Mesh3dResourceError::Target)?;
915        let depth_texture = create_depth_texture(&self.device, width, height);
916        let depth_view = depth_texture.create_view(&wgpu::TextureViewDescriptor::default());
917        Ok(RenderTarget3d {
918            renderer_identity: Arc::clone(&self.renderer_identity),
919            color,
920            _depth_texture: depth_texture,
921            depth_view,
922            logical_viewport,
923            pixels_per_logical,
924        })
925    }
926
927    /// Restores empty color/depth attachments with the source dimensions.
928    pub fn restore_render_target3d(
929        &self,
930        source: &RenderTarget3d,
931    ) -> Result<RenderTarget3d, Mesh3dResourceError> {
932        self.create_render_target3d(source.width(), source.height(), source.logical_viewport())
933    }
934
935    /// Draws opaque retained objects into a reusable color/depth target.
936    ///
937    /// Object insertion order does not determine visibility. Every surface
938    /// writes and tests hardware depth. Model transforms are uploaded through a
939    /// reusable instance buffer; retained topology is never retessellated.
940    pub fn render_scene3d_to_target(
941        &mut self,
942        target: &RenderTarget3d,
943        scene: &Scene3d,
944        camera: Camera3d,
945    ) -> Result<Mesh3dRenderReport, Mesh3dRenderError> {
946        validate_target_identity(&self.renderer_identity, target)?;
947        for instance in scene.instances() {
948            validate_mesh_identity(&self.renderer_identity, &instance.mesh)?;
949        }
950        validate_camera_target_aspect(camera, target.logical_viewport())?;
951        let camera_uniform = Camera3dUniform::new(
952            camera,
953            target.width(),
954            target.height(),
955            target.pixels_per_logical(),
956        )?;
957        self.mesh3d_renderer
958            .ensure_instance_capacity(&self.device, scene.object_count())?;
959        self.mesh3d_renderer
960            .ensure_edge_object_capacity(&self.device, scene.object_count())?;
961        self.mesh3d_renderer.instances.clear();
962        self.mesh3d_renderer.edge_object_bytes.clear();
963        self.mesh3d_renderer.edge_object_bytes.resize(
964            scene
965                .object_count()
966                .saturating_mul(self.mesh3d_renderer.edge_object_stride),
967            0,
968        );
969        for (object_index, instance) in scene.instances().iter().enumerate() {
970            if !instance.visible {
971                self.mesh3d_renderer.instances.push(MeshInstanceGpu {
972                    model_row_0: [1.0, 0.0, 0.0, 0.0],
973                    model_row_1: [0.0, 1.0, 0.0, 0.0],
974                    model_row_2: [0.0, 0.0, 1.0, 0.0],
975                    color: Color::BLACK.to_array(),
976                });
977                continue;
978            }
979            let model_rows = instance
980                .transform
981                .model_rows()
982                .map_err(|_| Mesh3dRenderError::InvalidGeometryTransform)?;
983            validate_shader_transform(instance.mesh.source(), model_rows, camera_uniform.rows())?;
984            self.mesh3d_renderer.instances.push(MeshInstanceGpu {
985                model_row_0: model_rows[0],
986                model_row_1: model_rows[1],
987                model_row_2: model_rows[2],
988                color: instance
989                    .style
990                    .surface_style()
991                    .map_or(Color::BLACK, |surface| surface.color())
992                    .to_array(),
993            });
994            if let Some(style) = instance.wireframe() {
995                validate_edge_projection(
996                    instance.mesh.source(),
997                    model_rows,
998                    camera_uniform.rows(),
999                    style,
1000                    camera_uniform.viewport,
1001                )?;
1002                let hidden_color = style.hidden_color().unwrap_or(style.visible_color());
1003                let hidden_width = style.hidden_width().map_or(0.0, LogicalPixels::get);
1004                let (dash_length, gap_length) = style
1005                    .hidden_pattern()
1006                    .map_or((1.0, 1.0), |(dash, gap)| (dash.get(), gap.get()));
1007                let edge_uniform = EdgeObjectUniform {
1008                    model_row_0: model_rows[0],
1009                    model_row_1: model_rows[1],
1010                    model_row_2: model_rows[2],
1011                    visible_color: style.visible_color().to_array(),
1012                    hidden_color: hidden_color.to_array(),
1013                    edge_style: [
1014                        style.visible_width().get(),
1015                        hidden_width,
1016                        dash_length,
1017                        gap_length,
1018                    ],
1019                };
1020                let start = object_index * self.mesh3d_renderer.edge_object_stride;
1021                let end = start + std::mem::size_of::<EdgeObjectUniform>();
1022                self.mesh3d_renderer.edge_object_bytes[start..end]
1023                    .copy_from_slice(bytemuck::bytes_of(&edge_uniform));
1024            }
1025        }
1026
1027        let upload_started_at = Instant::now();
1028        self.queue.write_buffer(
1029            &self.mesh3d_renderer.camera_uniform_buffer,
1030            0,
1031            bytemuck::bytes_of(&camera_uniform),
1032        );
1033        if !self.mesh3d_renderer.instances.is_empty() {
1034            self.queue.write_buffer(
1035                &self.mesh3d_renderer.instance_buffer,
1036                0,
1037                bytemuck::cast_slice(&self.mesh3d_renderer.instances),
1038            );
1039        }
1040        if !self.mesh3d_renderer.edge_object_bytes.is_empty() {
1041            self.queue.write_buffer(
1042                &self.mesh3d_renderer.edge_object_buffer,
1043                0,
1044                &self.mesh3d_renderer.edge_object_bytes,
1045            );
1046        }
1047        let upload = upload_started_at.elapsed();
1048        let encode_started_at = Instant::now();
1049        let mut encoder = self
1050            .device
1051            .create_command_encoder(&wgpu::CommandEncoderDescriptor {
1052                label: Some("sim-engine retained 3D scene encoder"),
1053            });
1054        encode_scene_pass(
1055            &mut encoder,
1056            &self.mesh3d_renderer,
1057            &target.color.view,
1058            &target.depth_view,
1059            scene.background(),
1060            scene.instances(),
1061        );
1062        self.queue.submit([encoder.finish()]);
1063        let triangle_count = scene.instances().iter().fold(0usize, |count, instance| {
1064            if instance.visible && instance.style.surface_style().is_some() {
1065                count.saturating_add(instance.mesh.triangle_count())
1066            } else {
1067                count
1068            }
1069        });
1070        let edge_count = scene.instances().iter().fold(0usize, |count, instance| {
1071            if instance.visible && instance.wireframe().is_some() {
1072                count.saturating_add(instance.mesh.source().display_edges().len())
1073            } else {
1074                count
1075            }
1076        });
1077        Ok(Mesh3dRenderReport {
1078            object_count: scene.visible_object_count(),
1079            triangle_count,
1080            edge_count,
1081            upload,
1082            encode_submit: encode_started_at.elapsed(),
1083        })
1084    }
1085}
1086
1087fn create_retained_mesh(
1088    device: &wgpu::Device,
1089    queue: &wgpu::Queue,
1090    renderer_identity: Arc<()>,
1091    source: Mesh3d,
1092) -> Result<RetainedMesh3d, Mesh3dResourceError> {
1093    let layout = preflight_mesh3d_upload(
1094        source.vertices().len(),
1095        source.triangle_indices().len(),
1096        source.display_edges().len(),
1097        device.limits().max_buffer_size,
1098    )?;
1099    let mut vertices = Vec::new();
1100    vertices
1101        .try_reserve_exact(source.vertices().len())
1102        .map_err(|_| Mesh3dResourceError::HostAllocationFailed {
1103            requested_bytes: layout.vertex_bytes,
1104        })?;
1105    vertices.extend(source.vertices().iter().map(|vertex| MeshVertexGpu {
1106        position: [vertex.x(), vertex.y(), vertex.z()],
1107    }));
1108    let mut edges = Vec::new();
1109    edges
1110        .try_reserve_exact(source.display_edges().len())
1111        .map_err(|_| Mesh3dResourceError::HostAllocationFailed {
1112            requested_bytes: layout.edge_bytes,
1113        })?;
1114    edges.extend(source.display_edges().iter().map(|edge| {
1115        let start = source.vertices()[edge.start() as usize];
1116        let end = source.vertices()[edge.end() as usize];
1117        MeshEdgeGpu {
1118            start: [start.x(), start.y(), start.z()],
1119            end: [end.x(), end.y(), end.z()],
1120        }
1121    }));
1122    let vertex_buffer = Arc::new(device.create_buffer(&wgpu::BufferDescriptor {
1123        label: Some("sim-engine retained 3D vertex buffer"),
1124        size: layout.vertex_bytes,
1125        usage: wgpu::BufferUsages::VERTEX | wgpu::BufferUsages::COPY_DST,
1126        mapped_at_creation: false,
1127    }));
1128    let index_buffer = if layout.index_bytes == 0 {
1129        None
1130    } else {
1131        Some(Arc::new(device.create_buffer(&wgpu::BufferDescriptor {
1132            label: Some("sim-engine retained 3D index buffer"),
1133            size: layout.index_bytes,
1134            usage: wgpu::BufferUsages::INDEX | wgpu::BufferUsages::COPY_DST,
1135            mapped_at_creation: false,
1136        })))
1137    };
1138    queue.write_buffer(&vertex_buffer, 0, bytemuck::cast_slice(&vertices));
1139    if let Some(index_buffer) = index_buffer.as_ref() {
1140        queue.write_buffer(
1141            index_buffer,
1142            0,
1143            bytemuck::cast_slice(source.triangle_indices()),
1144        );
1145    }
1146    let edge_buffer = if layout.edge_bytes == 0 {
1147        None
1148    } else {
1149        let buffer = Arc::new(device.create_buffer(&wgpu::BufferDescriptor {
1150            label: Some("sim-engine retained 3D edge buffer"),
1151            size: layout.edge_bytes,
1152            usage: wgpu::BufferUsages::VERTEX | wgpu::BufferUsages::COPY_DST,
1153            mapped_at_creation: false,
1154        }));
1155        queue.write_buffer(&buffer, 0, bytemuck::cast_slice(&edges));
1156        Some(buffer)
1157    };
1158    Ok(RetainedMesh3d {
1159        renderer_identity,
1160        vertex_buffer,
1161        index_buffer,
1162        edge_buffer,
1163        source,
1164        index_count: layout.index_count,
1165        edge_count: layout.edge_count,
1166        gpu_allocation_bytes: usize::try_from(layout.total_bytes).unwrap_or(usize::MAX),
1167    })
1168}
1169
1170fn restore_scene3d_resources(
1171    device: &wgpu::Device,
1172    queue: &wgpu::Queue,
1173    renderer_identity: Arc<()>,
1174    scene: &mut Scene3d,
1175) -> Result<Scene3dRestoreReport, Mesh3dResourceError> {
1176    let mut restored = Vec::<(Arc<wgpu::Buffer>, RetainedMesh3d)>::new();
1177    for instance in &scene.instances {
1178        if Arc::ptr_eq(&renderer_identity, &instance.mesh.renderer_identity)
1179            || restored.iter().any(|(old_vertex_buffer, _)| {
1180                Arc::ptr_eq(old_vertex_buffer, &instance.mesh.vertex_buffer)
1181            })
1182        {
1183            continue;
1184        }
1185        let old_vertex_buffer = Arc::clone(&instance.mesh.vertex_buffer);
1186        let replacement = create_retained_mesh(
1187            device,
1188            queue,
1189            Arc::clone(&renderer_identity),
1190            instance.mesh.source.clone(),
1191        )?;
1192        restored.push((old_vertex_buffer, replacement));
1193    }
1194
1195    let mut replacement_instances = scene.instances.clone();
1196    let mut migrated_object_count = 0;
1197    for instance in &mut replacement_instances {
1198        let Some((_, replacement)) = restored.iter().find(|(old_vertex_buffer, _)| {
1199            Arc::ptr_eq(old_vertex_buffer, &instance.mesh.vertex_buffer)
1200        }) else {
1201            continue;
1202        };
1203        instance.mesh = replacement.clone();
1204        migrated_object_count += 1;
1205    }
1206    let restored_gpu_bytes = restored.iter().fold(0_usize, |total, (_, mesh)| {
1207        total.saturating_add(mesh.gpu_allocation_bytes())
1208    });
1209    scene.instances = replacement_instances;
1210    Ok(Scene3dRestoreReport {
1211        object_count: scene.object_count(),
1212        migrated_object_count,
1213        restored_mesh_count: restored.len(),
1214        restored_gpu_bytes,
1215    })
1216}
1217
1218#[derive(Debug, Clone, Copy, PartialEq, Eq)]
1219struct Mesh3dUploadLayout {
1220    vertex_bytes: u64,
1221    index_bytes: u64,
1222    edge_bytes: u64,
1223    total_bytes: u64,
1224    index_count: u32,
1225    edge_count: u32,
1226}
1227
1228fn preflight_mesh3d_upload(
1229    vertex_count: usize,
1230    index_count: usize,
1231    edge_count: usize,
1232    max_buffer_size: u64,
1233) -> Result<Mesh3dUploadLayout, Mesh3dResourceError> {
1234    let draw_index_count =
1235        u32::try_from(index_count).map_err(|_| Mesh3dResourceError::CapacityTooLarge)?;
1236    let draw_edge_count =
1237        u32::try_from(edge_count).map_err(|_| Mesh3dResourceError::CapacityTooLarge)?;
1238    let checked_buffer_bytes = |element_size: usize, element_count: usize| {
1239        u64::try_from(element_size)
1240            .ok()
1241            .and_then(|size| u64::try_from(element_count).ok()?.checked_mul(size))
1242            .filter(|bytes| *bytes <= max_buffer_size)
1243            .ok_or(Mesh3dResourceError::CapacityTooLarge)
1244    };
1245    let vertex_bytes = checked_buffer_bytes(std::mem::size_of::<MeshVertexGpu>(), vertex_count)?;
1246    let index_bytes = checked_buffer_bytes(std::mem::size_of::<u32>(), index_count)?;
1247    let edge_bytes = checked_buffer_bytes(std::mem::size_of::<MeshEdgeGpu>(), edge_count)?;
1248    let total_bytes = vertex_bytes
1249        .checked_add(index_bytes)
1250        .and_then(|bytes| bytes.checked_add(edge_bytes))
1251        .ok_or(Mesh3dResourceError::CapacityTooLarge)?;
1252    Ok(Mesh3dUploadLayout {
1253        vertex_bytes,
1254        index_bytes,
1255        edge_bytes,
1256        total_bytes,
1257        index_count: draw_index_count,
1258        edge_count: draw_edge_count,
1259    })
1260}
1261
1262fn create_instance_buffer(device: &wgpu::Device, capacity: usize) -> wgpu::Buffer {
1263    device.create_buffer(&wgpu::BufferDescriptor {
1264        label: Some("sim-engine 3D instance buffer"),
1265        size: (capacity.max(1) * std::mem::size_of::<MeshInstanceGpu>()) as wgpu::BufferAddress,
1266        usage: wgpu::BufferUsages::VERTEX | wgpu::BufferUsages::COPY_DST,
1267        mapped_at_creation: false,
1268    })
1269}
1270
1271#[allow(clippy::too_many_arguments)]
1272fn create_edge_pipeline(
1273    device: &wgpu::Device,
1274    shader: &wgpu::ShaderModule,
1275    layout: &wgpu::PipelineLayout,
1276    format: wgpu::TextureFormat,
1277    depth_compare: wgpu::CompareFunction,
1278    fragment_entry: &'static str,
1279    label: &'static str,
1280) -> wgpu::RenderPipeline {
1281    let (vertex_entry, depth_bias) = if depth_compare == wgpu::CompareFunction::Greater {
1282        (
1283            "mesh3d_hidden_edge_vs_main",
1284            wgpu::DepthBiasState {
1285                constant: HIDDEN_EDGE_DEPTH_BIAS,
1286                slope_scale: 0.0,
1287                clamp: 0.0,
1288            },
1289        )
1290    } else {
1291        (
1292            "mesh3d_visible_edge_vs_main",
1293            wgpu::DepthBiasState {
1294                constant: VISIBLE_EDGE_DEPTH_BIAS,
1295                slope_scale: 0.0,
1296                clamp: 0.0,
1297            },
1298        )
1299    };
1300    device.create_render_pipeline(&wgpu::RenderPipelineDescriptor {
1301        label: Some(label),
1302        layout: Some(layout),
1303        vertex: wgpu::VertexState {
1304            module: shader,
1305            entry_point: Some(vertex_entry),
1306            compilation_options: wgpu::PipelineCompilationOptions::default(),
1307            buffers: &[Some(MeshEdgeGpu::LAYOUT)],
1308        },
1309        primitive: wgpu::PrimitiveState {
1310            topology: wgpu::PrimitiveTopology::TriangleList,
1311            ..Default::default()
1312        },
1313        depth_stencil: Some(wgpu::DepthStencilState {
1314            format: DEPTH_FORMAT,
1315            depth_write_enabled: Some(false),
1316            depth_compare: Some(depth_compare),
1317            stencil: wgpu::StencilState::default(),
1318            bias: depth_bias,
1319        }),
1320        multisample: wgpu::MultisampleState::default(),
1321        fragment: Some(wgpu::FragmentState {
1322            module: shader,
1323            entry_point: Some(fragment_entry),
1324            compilation_options: wgpu::PipelineCompilationOptions::default(),
1325            targets: &[Some(wgpu::ColorTargetState {
1326                format,
1327                blend: Some(wgpu::BlendState::ALPHA_BLENDING),
1328                write_mask: wgpu::ColorWrites::ALL,
1329            })],
1330        }),
1331        multiview_mask: None,
1332        cache: None,
1333    })
1334}
1335
1336fn align_to(value: usize, alignment: usize) -> usize {
1337    if alignment <= 1 {
1338        value
1339    } else {
1340        value.div_ceil(alignment).saturating_mul(alignment)
1341    }
1342}
1343
1344fn create_edge_object_buffer(
1345    device: &wgpu::Device,
1346    stride: usize,
1347    capacity: usize,
1348) -> wgpu::Buffer {
1349    device.create_buffer(&wgpu::BufferDescriptor {
1350        label: Some("sim-engine 3D edge object uniform buffer"),
1351        size: capacity.max(1).saturating_mul(stride) as wgpu::BufferAddress,
1352        usage: wgpu::BufferUsages::UNIFORM | wgpu::BufferUsages::COPY_DST,
1353        mapped_at_creation: false,
1354    })
1355}
1356
1357fn create_edge_object_bind_group(
1358    device: &wgpu::Device,
1359    layout: &wgpu::BindGroupLayout,
1360    buffer: &wgpu::Buffer,
1361) -> wgpu::BindGroup {
1362    device.create_bind_group(&wgpu::BindGroupDescriptor {
1363        label: Some("sim-engine 3D edge object bind group"),
1364        layout,
1365        entries: &[wgpu::BindGroupEntry {
1366            binding: 0,
1367            resource: wgpu::BindingResource::Buffer(wgpu::BufferBinding {
1368                buffer,
1369                offset: 0,
1370                size: wgpu::BufferSize::new(std::mem::size_of::<EdgeObjectUniform>() as u64),
1371            }),
1372        }],
1373    })
1374}
1375
1376fn create_depth_texture(device: &wgpu::Device, width: u32, height: u32) -> wgpu::Texture {
1377    device.create_texture(&wgpu::TextureDescriptor {
1378        label: Some("sim-engine 3D depth target"),
1379        size: wgpu::Extent3d {
1380            width,
1381            height,
1382            depth_or_array_layers: 1,
1383        },
1384        mip_level_count: 1,
1385        sample_count: 1,
1386        dimension: wgpu::TextureDimension::D2,
1387        format: DEPTH_FORMAT,
1388        usage: wgpu::TextureUsages::RENDER_ATTACHMENT,
1389        view_formats: &[],
1390    })
1391}
1392
1393fn target_pixels_per_logical(
1394    width: u32,
1395    height: u32,
1396    viewport: LogicalViewport,
1397) -> Option<PhysicalPerLogical> {
1398    let horizontal = width as f64 / viewport.width() as f64;
1399    let vertical = height as f64 / viewport.height() as f64;
1400    if !horizontal.is_finite()
1401        || !vertical.is_finite()
1402        || horizontal <= 0.0
1403        || vertical <= 0.0
1404        || !aspect_matches(horizontal as f32, vertical as f32)
1405        || horizontal > f32::MAX as f64
1406    {
1407        return None;
1408    }
1409    PhysicalPerLogical::new(horizontal as f32).ok()
1410}
1411
1412fn aspect_matches(left: f32, right: f32) -> bool {
1413    if !left.is_finite() || !right.is_finite() || left <= 0.0 || right <= 0.0 {
1414        return false;
1415    }
1416    let scale = left.abs().max(right.abs()).max(1.0);
1417    (left - right).abs() <= scale * 1.0e-5
1418}
1419
1420fn validate_camera_target_aspect(
1421    camera: Camera3d,
1422    viewport: LogicalViewport,
1423) -> Result<(), Mesh3dRenderError> {
1424    aspect_matches(
1425        camera.projection().aspect_ratio(),
1426        viewport.width() / viewport.height(),
1427    )
1428    .then_some(())
1429    .ok_or(Mesh3dRenderError::CameraTargetAspectMismatch)
1430}
1431
1432fn validate_target_identity(
1433    renderer_identity: &Arc<()>,
1434    target: &RenderTarget3d,
1435) -> Result<(), Mesh3dRenderError> {
1436    (Arc::ptr_eq(renderer_identity, &target.renderer_identity)
1437        && Arc::ptr_eq(renderer_identity, &target.color.renderer_identity))
1438    .then_some(())
1439    .ok_or(Mesh3dRenderError::RendererMismatch)
1440}
1441
1442fn validate_mesh_identity(
1443    renderer_identity: &Arc<()>,
1444    mesh: &RetainedMesh3d,
1445) -> Result<(), Mesh3dRenderError> {
1446    Arc::ptr_eq(renderer_identity, &mesh.renderer_identity)
1447        .then_some(())
1448        .ok_or(Mesh3dRenderError::RendererMismatch)
1449}
1450
1451fn validate_shader_transform(
1452    mesh: &Mesh3d,
1453    model_rows: [[f32; 4]; 3],
1454    camera_rows: [[f32; 4]; 4],
1455) -> Result<(), Mesh3dRenderError> {
1456    for corner in bounds_corners(mesh.bounds_min(), mesh.bounds_max()) {
1457        let model_point = [corner.x(), corner.y(), corner.z(), 1.0];
1458        let world = [
1459            shader_dot(model_rows[0], model_point)?,
1460            shader_dot(model_rows[1], model_point)?,
1461            shader_dot(model_rows[2], model_point)?,
1462            1.0,
1463        ];
1464        for row in camera_rows {
1465            let _ = shader_dot(row, world)?;
1466        }
1467    }
1468    Ok(())
1469}
1470
1471fn validate_edge_projection(
1472    mesh: &Mesh3d,
1473    model_rows: [[f32; 4]; 3],
1474    camera_rows: [[f32; 4]; 4],
1475    style: WireframeStyle3d,
1476    viewport: [f32; 4],
1477) -> Result<(), Mesh3dRenderError> {
1478    let pixels_per_logical = PhysicalPerLogical::new(viewport[2])
1479        .map_err(|_| Mesh3dRenderError::InvalidEdgeProjection)?;
1480    if edge_physical_half_width(style.visible_width(), pixels_per_logical).is_none() {
1481        return Err(Mesh3dRenderError::InvalidEdgeProjection);
1482    }
1483    if let (Some(hidden_width), Some((dash, gap))) = (style.hidden_width(), style.hidden_pattern())
1484        && (edge_physical_half_width(hidden_width, pixels_per_logical).is_none()
1485            || !(dash.get() + gap.get()).is_finite())
1486    {
1487        return Err(Mesh3dRenderError::InvalidEdgeProjection);
1488    }
1489
1490    for edge in mesh.display_edges() {
1491        let mut clip = [[0.0_f32; 4]; 2];
1492        for (endpoint_index, vertex_index) in [edge.start(), edge.end()].into_iter().enumerate() {
1493            let vertex = mesh.vertices()[vertex_index as usize];
1494            let model = [vertex.x(), vertex.y(), vertex.z(), 1.0];
1495            let world = [
1496                shader_dot(model_rows[0], model)?,
1497                shader_dot(model_rows[1], model)?,
1498                shader_dot(model_rows[2], model)?,
1499                1.0,
1500            ];
1501            clip[endpoint_index] = [
1502                shader_dot(camera_rows[0], world)?,
1503                shader_dot(camera_rows[1], world)?,
1504                shader_dot(camera_rows[2], world)?,
1505                shader_dot(camera_rows[3], world)?,
1506            ];
1507        }
1508        let Some(clipped) = clip_edge_to_frustum(clip[0], clip[1])? else {
1509            continue;
1510        };
1511        let mut screen = [[0.0_f32; 2]; 2];
1512        for (endpoint_index, clip) in clipped.into_iter().enumerate() {
1513            let ndc_x = clip[0] / clip[3];
1514            let ndc_y = clip[1] / clip[3];
1515            screen[endpoint_index] = [
1516                (ndc_x * 0.5 + 0.5) * viewport[0],
1517                (0.5 - ndc_y * 0.5) * viewport[1],
1518            ];
1519            if !screen[endpoint_index][0].is_finite() || !screen[endpoint_index][1].is_finite() {
1520                return Err(Mesh3dRenderError::InvalidEdgeProjection);
1521            }
1522        }
1523        let delta_x = screen[1][0] - screen[0][0];
1524        let delta_y = screen[1][1] - screen[0][1];
1525        if !delta_x.is_finite()
1526            || !delta_y.is_finite()
1527            || !(delta_x * delta_x + delta_y * delta_y).is_finite()
1528        {
1529            return Err(Mesh3dRenderError::InvalidEdgeProjection);
1530        }
1531    }
1532    Ok(())
1533}
1534
1535fn clip_edge_to_frustum(
1536    start: [f32; 4],
1537    end: [f32; 4],
1538) -> Result<Option<[[f32; 4]; 2]>, Mesh3dRenderError> {
1539    Ok(clip_edge_to_frustum_details(start, end)?.map(|clipped| clipped.clip))
1540}
1541
1542#[derive(Debug, Clone, Copy, PartialEq)]
1543struct ClippedEdgeCpu {
1544    clip: [[f32; 4]; 2],
1545    enter: f32,
1546    exit: f32,
1547}
1548
1549fn clip_edge_to_frustum_details(
1550    start: [f32; 4],
1551    end: [f32; 4],
1552) -> Result<Option<ClippedEdgeCpu>, Mesh3dRenderError> {
1553    let pair_max = start
1554        .into_iter()
1555        .chain(end)
1556        .map(f32::abs)
1557        .fold(0.0_f32, f32::max);
1558    if !pair_max.is_finite() {
1559        return Err(Mesh3dRenderError::InvalidEdgeProjection);
1560    }
1561    let homogeneous_scale = (1.0 / pair_max.max(1.0)).max(f32::MIN_POSITIVE);
1562    let start = start.map(|component| component * homogeneous_scale);
1563    let end = end.map(|component| component * homogeneous_scale);
1564    let start_distances = clip_plane_distances(start)?;
1565    let end_distances = clip_plane_distances(end)?;
1566    let mut enter = 0.0_f32;
1567    let mut exit = 1.0_f32;
1568    for (start_distance, end_distance) in start_distances.into_iter().zip(end_distances) {
1569        if start_distance < 0.0 && end_distance < 0.0 {
1570            return Ok(None);
1571        }
1572        if start_distance < 0.0 || end_distance < 0.0 {
1573            let denominator = start_distance - end_distance;
1574            let amount = start_distance / denominator;
1575            if !denominator.is_finite() || !amount.is_finite() {
1576                return Err(Mesh3dRenderError::InvalidEdgeProjection);
1577            }
1578            if start_distance < 0.0 {
1579                enter = enter.max(amount);
1580            } else {
1581                exit = exit.min(amount);
1582            }
1583        }
1584    }
1585    if enter > exit {
1586        return Ok(None);
1587    }
1588    let clipped_start = shader_lerp_clip(start, end, enter)?;
1589    let clipped_end = shader_lerp_clip(start, end, exit)?;
1590    if clipped_start[3] <= 0.0 || clipped_end[3] <= 0.0 {
1591        return Ok(None);
1592    }
1593    Ok(Some(ClippedEdgeCpu {
1594        clip: [clipped_start, clipped_end],
1595        enter,
1596        exit,
1597    }))
1598}
1599
1600fn clip_plane_distances(clip: [f32; 4]) -> Result<[f32; 6], Mesh3dRenderError> {
1601    let add = |left: f32, right: f32| {
1602        let result = left + right;
1603        result
1604            .is_finite()
1605            .then_some(result)
1606            .ok_or(Mesh3dRenderError::InvalidEdgeProjection)
1607    };
1608    let subtract = |left: f32, right: f32| {
1609        let result = left - right;
1610        result
1611            .is_finite()
1612            .then_some(result)
1613            .ok_or(Mesh3dRenderError::InvalidEdgeProjection)
1614    };
1615    Ok([
1616        add(clip[3], clip[0])?,
1617        subtract(clip[3], clip[0])?,
1618        add(clip[3], clip[1])?,
1619        subtract(clip[3], clip[1])?,
1620        clip[2],
1621        subtract(clip[3], clip[2])?,
1622    ])
1623}
1624
1625fn shader_lerp_clip(
1626    start: [f32; 4],
1627    end: [f32; 4],
1628    amount: f32,
1629) -> Result<[f32; 4], Mesh3dRenderError> {
1630    let mut output = [0.0_f32; 4];
1631    for axis in 0..4 {
1632        let delta = end[axis] - start[axis];
1633        let value = start[axis] + delta * amount;
1634        if !delta.is_finite() || !value.is_finite() {
1635            return Err(Mesh3dRenderError::InvalidEdgeProjection);
1636        }
1637        output[axis] = value;
1638    }
1639    Ok(output)
1640}
1641
1642fn edge_physical_half_width(
1643    logical_width: LogicalPixels,
1644    pixels_per_logical: PhysicalPerLogical,
1645) -> Option<f32> {
1646    let width = logical_width.get() * pixels_per_logical.get() * 0.5;
1647    (width.is_finite() && width > 0.0).then_some(width)
1648}
1649
1650fn shader_dot(row: [f32; 4], point: [f32; 4]) -> Result<f32, Mesh3dRenderError> {
1651    let mut result = 0.0_f32;
1652    for axis in 0..4 {
1653        let product = row[axis] * point[axis];
1654        result += product;
1655        if !product.is_finite() || !result.is_finite() {
1656            return Err(Mesh3dRenderError::InvalidGeometryTransform);
1657        }
1658    }
1659    Ok(result)
1660}
1661
1662fn bounds_corners(minimum: Vec3, maximum: Vec3) -> [Vec3; 8] {
1663    [
1664        Vec3::new_unchecked(minimum.x(), minimum.y(), minimum.z()),
1665        Vec3::new_unchecked(maximum.x(), minimum.y(), minimum.z()),
1666        Vec3::new_unchecked(minimum.x(), maximum.y(), minimum.z()),
1667        Vec3::new_unchecked(maximum.x(), maximum.y(), minimum.z()),
1668        Vec3::new_unchecked(minimum.x(), minimum.y(), maximum.z()),
1669        Vec3::new_unchecked(maximum.x(), minimum.y(), maximum.z()),
1670        Vec3::new_unchecked(minimum.x(), maximum.y(), maximum.z()),
1671        Vec3::new_unchecked(maximum.x(), maximum.y(), maximum.z()),
1672    ]
1673}
1674
1675fn encode_scene_pass(
1676    encoder: &mut wgpu::CommandEncoder,
1677    renderer: &Mesh3dRenderer,
1678    color_view: &wgpu::TextureView,
1679    depth_view: &wgpu::TextureView,
1680    background: Color,
1681    instances: &[Mesh3dInstance],
1682) {
1683    let mut pass = encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
1684        label: Some("sim-engine retained 3D mesh pass"),
1685        color_attachments: &[Some(wgpu::RenderPassColorAttachment {
1686            view: color_view,
1687            depth_slice: None,
1688            resolve_target: None,
1689            ops: wgpu::Operations {
1690                load: wgpu::LoadOp::Clear(background.to_wgpu()),
1691                store: wgpu::StoreOp::Store,
1692            },
1693        })],
1694        depth_stencil_attachment: Some(wgpu::RenderPassDepthStencilAttachment {
1695            view: depth_view,
1696            depth_ops: Some(wgpu::Operations {
1697                load: wgpu::LoadOp::Clear(1.0),
1698                store: wgpu::StoreOp::Store,
1699            }),
1700            stencil_ops: None,
1701        }),
1702        timestamp_writes: None,
1703        occlusion_query_set: None,
1704        multiview_mask: None,
1705    });
1706    pass.set_pipeline(&renderer.pipeline);
1707    pass.set_bind_group(0, &renderer.camera_bind_group, &[]);
1708    for (instance_index, instance) in instances.iter().enumerate() {
1709        if !instance.visible {
1710            continue;
1711        }
1712        if instance.style.surface_style().is_none() {
1713            continue;
1714        }
1715        let Some(index_buffer) = instance.mesh.index_buffer.as_ref() else {
1716            continue;
1717        };
1718        let instance_start =
1719            (instance_index * std::mem::size_of::<MeshInstanceGpu>()) as wgpu::BufferAddress;
1720        let instance_end =
1721            instance_start + std::mem::size_of::<MeshInstanceGpu>() as wgpu::BufferAddress;
1722        pass.set_vertex_buffer(0, instance.mesh.vertex_buffer.slice(..));
1723        pass.set_vertex_buffer(
1724            1,
1725            renderer.instance_buffer.slice(instance_start..instance_end),
1726        );
1727        pass.set_index_buffer(index_buffer.slice(..), wgpu::IndexFormat::Uint32);
1728        pass.draw_indexed(0..instance.mesh.index_count, 0, 0..1);
1729    }
1730    pass.set_pipeline(&renderer.hidden_edge_pipeline);
1731    for (object_index, instance) in instances.iter().enumerate() {
1732        if !instance.visible {
1733            continue;
1734        }
1735        let Some(style) = instance.wireframe() else {
1736            continue;
1737        };
1738        let Some(edge_buffer) = instance.mesh.edge_buffer.as_ref() else {
1739            continue;
1740        };
1741        if !style.hidden_enabled() {
1742            continue;
1743        }
1744        let dynamic_offset = (object_index * renderer.edge_object_stride) as u32;
1745        pass.set_bind_group(1, &renderer.edge_object_bind_group, &[dynamic_offset]);
1746        pass.set_vertex_buffer(0, edge_buffer.slice(..));
1747        pass.draw(0..6, 0..instance.mesh.edge_count);
1748    }
1749    pass.set_pipeline(&renderer.visible_edge_pipeline);
1750    for (object_index, instance) in instances.iter().enumerate() {
1751        if !instance.visible {
1752            continue;
1753        }
1754        if instance.wireframe().is_none() {
1755            continue;
1756        }
1757        let Some(edge_buffer) = instance.mesh.edge_buffer.as_ref() else {
1758            continue;
1759        };
1760        let dynamic_offset = (object_index * renderer.edge_object_stride) as u32;
1761        pass.set_bind_group(1, &renderer.edge_object_bind_group, &[dynamic_offset]);
1762        pass.set_vertex_buffer(0, edge_buffer.slice(..));
1763        pass.draw(0..6, 0..instance.mesh.edge_count);
1764    }
1765}
1766
1767#[cfg(test)]
1768pub(super) fn assert_gpu_depth_contract(
1769    device: &wgpu::Device,
1770    queue: &wgpu::Queue,
1771    format: wgpu::TextureFormat,
1772) {
1773    assert_gpu_clip_equivalence(device, queue);
1774    let identity = Arc::new(());
1775    let mut renderer = Mesh3dRenderer::new(device, format);
1776    let vertices = vec![
1777        Vec3::new(-1.0, -1.0, 0.0).unwrap(),
1778        Vec3::new(1.0, -1.0, 0.0).unwrap(),
1779        Vec3::new(0.0, 1.0, 0.0).unwrap(),
1780    ];
1781    let near_triangle = Mesh3d::with_display_edges(
1782        vertices.clone(),
1783        vec![0, 1, 2],
1784        vec![MeshEdge3d::new(0, 1).unwrap()],
1785    )
1786    .unwrap();
1787    let far_triangle = Mesh3d::with_display_edges(
1788        vertices,
1789        vec![0, 1, 2],
1790        vec![MeshEdge3d::new(0, 2).unwrap()],
1791    )
1792    .unwrap();
1793    let near_mesh = create_retained_mesh(device, queue, Arc::clone(&identity), near_triangle)
1794        .expect("3D test mesh should upload");
1795    let far_mesh = create_retained_mesh(device, queue, Arc::clone(&identity), far_triangle)
1796        .expect("3D test mesh should upload");
1797    let near_crossing_edge = Mesh3d::with_display_edges(
1798        vec![
1799            Vec3::new(0.0, 0.0, 4.95).unwrap(),
1800            Vec3::new(0.5, 0.5, 4.0).unwrap(),
1801        ],
1802        Vec::new(),
1803        vec![MeshEdge3d::new(0, 1).unwrap()],
1804    )
1805    .unwrap();
1806    let near_crossing_mesh =
1807        create_retained_mesh(device, queue, Arc::clone(&identity), near_crossing_edge)
1808            .expect("near-crossing 3D test edge should upload");
1809    let classification_edge = Mesh3d::with_display_edges(
1810        vec![
1811            Vec3::new(-0.5, -0.5, 0.0).unwrap(),
1812            Vec3::new(0.5, -0.5, 0.0).unwrap(),
1813        ],
1814        Vec::new(),
1815        vec![MeshEdge3d::new(0, 1).unwrap()],
1816    )
1817    .unwrap();
1818    let classification_mesh =
1819        create_retained_mesh(device, queue, Arc::clone(&identity), classification_edge)
1820            .expect("classification test edge should upload");
1821    let projection = Projection3d::perspective(0.927_295_2, 1.0, world(0.1), world(20.0)).unwrap();
1822    let camera = Camera3d::look_at(
1823        Vec3::new(0.0, 0.0, 5.0).unwrap(),
1824        Vec3::ZERO,
1825        Vec3::Y,
1826        projection,
1827    )
1828    .unwrap();
1829    let camera_uniform = Camera3dUniform::new(camera, 64, 64, physical_per_logical(1.0)).unwrap();
1830    let near_transform = Transform3d::new(
1831        Vec3::new(0.0, 0.0, 1.0).unwrap(),
1832        Rotation3d::IDENTITY,
1833        Vec3::new(1.0, 1.0, 1.0).unwrap(),
1834    )
1835    .unwrap();
1836    let far_transform = Transform3d::new(
1837        Vec3::new(0.0, 0.0, -1.0).unwrap(),
1838        Rotation3d::IDENTITY,
1839        Vec3::new(1.0, 1.0, 1.0).unwrap(),
1840    )
1841    .unwrap();
1842    let mut scene = Scene3d::new(Color::BLACK).unwrap();
1843    let near_id = scene
1844        .try_push(
1845            &near_mesh,
1846            near_transform,
1847            MeshStyle3d::surface(SurfaceStyle3d::opaque(Color::rgb(0.0, 1.0, 0.0)).unwrap())
1848                .with_wireframe(
1849                    WireframeStyle3d::visible(Color::rgb(0.0, 0.0, 1.0), logical(2.0))
1850                        .unwrap()
1851                        .with_hidden(
1852                            Color::rgb(1.0, 0.0, 1.0),
1853                            logical(2.0),
1854                            logical(4.0),
1855                            logical(4.0),
1856                        )
1857                        .unwrap(),
1858                ),
1859        )
1860        .unwrap();
1861    let mut other_scene = Scene3d::new(Color::BLACK).unwrap();
1862    let other_scene_id = other_scene
1863        .try_push(
1864            &near_mesh,
1865            Transform3d::IDENTITY,
1866            MeshStyle3d::surface(SurfaceStyle3d::opaque(Color::WHITE).unwrap()),
1867        )
1868        .unwrap();
1869    assert_eq!(near_id.get(), other_scene_id.get());
1870    assert_ne!(near_id, other_scene_id);
1871    assert_eq!(
1872        other_scene.set_visible(near_id, false),
1873        Err(Scene3dError::ObjectNotFound { object_id: near_id })
1874    );
1875    assert_eq!(other_scene.visible_object_count(), 1);
1876    assert_eq!(
1877        scene.set_visible(other_scene_id, false),
1878        Err(Scene3dError::ObjectNotFound {
1879            object_id: other_scene_id,
1880        })
1881    );
1882    assert_eq!(scene.visible_object_count(), 1);
1883    let far_id = scene
1884        .try_push(
1885            &far_mesh,
1886            far_transform,
1887            MeshStyle3d::surface(SurfaceStyle3d::opaque(Color::rgb(1.0, 0.0, 0.0)).unwrap())
1888                .with_wireframe(
1889                    WireframeStyle3d::visible(Color::rgb(1.0, 0.0, 0.0), logical(2.0))
1890                        .unwrap()
1891                        .with_hidden(Color::WHITE, logical(2.0), logical(4.0), logical(4.0))
1892                        .unwrap(),
1893                ),
1894        )
1895        .unwrap();
1896    scene
1897        .try_push(
1898            &near_crossing_mesh,
1899            Transform3d::IDENTITY,
1900            MeshStyle3d::wireframe(
1901                WireframeStyle3d::visible(Color::rgb(1.0, 1.0, 0.0), logical(2.0)).unwrap(),
1902            ),
1903        )
1904        .unwrap();
1905    let coplanar_transform = Transform3d::new(
1906        Vec3::new(0.0, 0.0, 1.0).unwrap(),
1907        Rotation3d::IDENTITY,
1908        Vec3::new(1.0, 1.0, 1.0).unwrap(),
1909    )
1910    .unwrap();
1911    scene
1912        .try_push(
1913            &classification_mesh,
1914            coplanar_transform,
1915            MeshStyle3d::wireframe(
1916                WireframeStyle3d::visible(Color::rgb(0.0, 1.0, 1.0), logical(2.0))
1917                    .unwrap()
1918                    .with_hidden(
1919                        Color::rgb(1.0, 0.0, 1.0),
1920                        logical(2.0),
1921                        logical(4.0),
1922                        logical(4.0),
1923                    )
1924                    .unwrap(),
1925            ),
1926        )
1927        .unwrap();
1928    let sub_depth_resolution_transform = Transform3d::new(
1929        Vec3::new(0.0, 0.2, 0.999_999).unwrap(),
1930        Rotation3d::IDENTITY,
1931        Vec3::new(1.0, 1.0, 1.0).unwrap(),
1932    )
1933    .unwrap();
1934    scene
1935        .try_push(
1936            &classification_mesh,
1937            sub_depth_resolution_transform,
1938            MeshStyle3d::wireframe(
1939                WireframeStyle3d::visible(Color::rgb(1.0, 0.5, 0.0), logical(2.0))
1940                    .unwrap()
1941                    .with_hidden(
1942                        Color::rgb(1.0, 0.0, 1.0),
1943                        logical(2.0),
1944                        logical(4.0),
1945                        logical(4.0),
1946                    )
1947                    .unwrap(),
1948            ),
1949        )
1950        .unwrap();
1951    let moved_near_transform = Transform3d::new(
1952        Vec3::new(0.25, 0.0, 1.0).unwrap(),
1953        Rotation3d::IDENTITY,
1954        Vec3::new(1.0, 1.0, 1.0).unwrap(),
1955    )
1956    .unwrap();
1957    scene.set_transform(near_id, moved_near_transform).unwrap();
1958    assert_eq!(scene.instances()[0].transform(), moved_near_transform);
1959    assert_eq!(scene.instances()[1].transform(), far_transform);
1960    assert_eq!(scene.instances()[1].id(), far_id);
1961    scene.set_visible(far_id, false).unwrap();
1962    assert_eq!(scene.visible_object_count(), 4);
1963    scene.set_visible(far_id, true).unwrap();
1964    assert_eq!(scene.visible_object_count(), 5);
1965    scene.set_transform(near_id, near_transform).unwrap();
1966    renderer
1967        .ensure_instance_capacity(device, scene.object_count())
1968        .unwrap();
1969    renderer.instances = scene
1970        .instances()
1971        .iter()
1972        .map(|instance| {
1973            let rows = instance.transform.model_rows().unwrap();
1974            MeshInstanceGpu {
1975                model_row_0: rows[0],
1976                model_row_1: rows[1],
1977                model_row_2: rows[2],
1978                color: instance
1979                    .style
1980                    .surface_style()
1981                    .map_or(Color::BLACK, SurfaceStyle3d::color)
1982                    .to_array(),
1983            }
1984        })
1985        .collect();
1986    renderer
1987        .edge_object_bytes
1988        .resize(scene.object_count() * renderer.edge_object_stride, 0);
1989    let near_rows = near_transform.model_rows().unwrap();
1990    let near_edge_uniform = EdgeObjectUniform {
1991        model_row_0: near_rows[0],
1992        model_row_1: near_rows[1],
1993        model_row_2: near_rows[2],
1994        visible_color: Color::rgb(0.0, 0.0, 1.0).to_array(),
1995        hidden_color: Color::rgb(1.0, 0.0, 1.0).to_array(),
1996        edge_style: [2.0, 2.0, 4.0, 4.0],
1997    };
1998    renderer.edge_object_bytes[..std::mem::size_of::<EdgeObjectUniform>()]
1999        .copy_from_slice(bytemuck::bytes_of(&near_edge_uniform));
2000    let far_rows = far_transform.model_rows().unwrap();
2001    let far_edge_uniform = EdgeObjectUniform {
2002        model_row_0: far_rows[0],
2003        model_row_1: far_rows[1],
2004        model_row_2: far_rows[2],
2005        visible_color: Color::rgb(1.0, 0.0, 0.0).to_array(),
2006        hidden_color: Color::WHITE.to_array(),
2007        edge_style: [2.0, 2.0, 4.0, 4.0],
2008    };
2009    let edge_start = renderer.edge_object_stride;
2010    let edge_end = edge_start + std::mem::size_of::<EdgeObjectUniform>();
2011    renderer.edge_object_bytes[edge_start..edge_end]
2012        .copy_from_slice(bytemuck::bytes_of(&far_edge_uniform));
2013    let crossing_rows = Transform3d::IDENTITY.model_rows().unwrap();
2014    let crossing_edge_uniform = EdgeObjectUniform {
2015        model_row_0: crossing_rows[0],
2016        model_row_1: crossing_rows[1],
2017        model_row_2: crossing_rows[2],
2018        visible_color: Color::rgb(1.0, 1.0, 0.0).to_array(),
2019        hidden_color: Color::rgb(1.0, 1.0, 0.0).to_array(),
2020        edge_style: [2.0, 0.0, 1.0, 1.0],
2021    };
2022    let crossing_edge_start = 2 * renderer.edge_object_stride;
2023    let crossing_edge_end = crossing_edge_start + std::mem::size_of::<EdgeObjectUniform>();
2024    renderer.edge_object_bytes[crossing_edge_start..crossing_edge_end]
2025        .copy_from_slice(bytemuck::bytes_of(&crossing_edge_uniform));
2026    let coplanar_rows = coplanar_transform.model_rows().unwrap();
2027    let coplanar_edge_uniform = EdgeObjectUniform {
2028        model_row_0: coplanar_rows[0],
2029        model_row_1: coplanar_rows[1],
2030        model_row_2: coplanar_rows[2],
2031        visible_color: Color::rgb(0.0, 1.0, 1.0).to_array(),
2032        hidden_color: Color::rgb(1.0, 0.0, 1.0).to_array(),
2033        edge_style: [2.0, 2.0, 4.0, 4.0],
2034    };
2035    let coplanar_edge_start = 3 * renderer.edge_object_stride;
2036    let coplanar_edge_end = coplanar_edge_start + std::mem::size_of::<EdgeObjectUniform>();
2037    renderer.edge_object_bytes[coplanar_edge_start..coplanar_edge_end]
2038        .copy_from_slice(bytemuck::bytes_of(&coplanar_edge_uniform));
2039    let sub_depth_rows = sub_depth_resolution_transform.model_rows().unwrap();
2040    let sub_depth_edge_uniform = EdgeObjectUniform {
2041        model_row_0: sub_depth_rows[0],
2042        model_row_1: sub_depth_rows[1],
2043        model_row_2: sub_depth_rows[2],
2044        visible_color: Color::rgb(1.0, 0.5, 0.0).to_array(),
2045        hidden_color: Color::rgb(1.0, 0.0, 1.0).to_array(),
2046        edge_style: [2.0, 2.0, 4.0, 4.0],
2047    };
2048    let sub_depth_edge_start = 4 * renderer.edge_object_stride;
2049    let sub_depth_edge_end = sub_depth_edge_start + std::mem::size_of::<EdgeObjectUniform>();
2050    renderer.edge_object_bytes[sub_depth_edge_start..sub_depth_edge_end]
2051        .copy_from_slice(bytemuck::bytes_of(&sub_depth_edge_uniform));
2052    queue.write_buffer(
2053        &renderer.camera_uniform_buffer,
2054        0,
2055        bytemuck::bytes_of(&camera_uniform),
2056    );
2057    queue.write_buffer(
2058        &renderer.instance_buffer,
2059        0,
2060        bytemuck::cast_slice(&renderer.instances),
2061    );
2062    queue.write_buffer(&renderer.edge_object_buffer, 0, &renderer.edge_object_bytes);
2063    let color_texture = device.create_texture(&wgpu::TextureDescriptor {
2064        label: Some("sim-engine 3D depth test color"),
2065        size: wgpu::Extent3d {
2066            width: 64,
2067            height: 64,
2068            depth_or_array_layers: 1,
2069        },
2070        mip_level_count: 1,
2071        sample_count: 1,
2072        dimension: wgpu::TextureDimension::D2,
2073        format,
2074        usage: wgpu::TextureUsages::RENDER_ATTACHMENT | wgpu::TextureUsages::COPY_SRC,
2075        view_formats: &[],
2076    });
2077    let color_view = color_texture.create_view(&wgpu::TextureViewDescriptor::default());
2078    let depth_texture = create_depth_texture(device, 64, 64);
2079    let depth_view = depth_texture.create_view(&wgpu::TextureViewDescriptor::default());
2080    let readback = device.create_buffer(&wgpu::BufferDescriptor {
2081        label: Some("sim-engine 3D depth test readback"),
2082        size: 256 * 64,
2083        usage: wgpu::BufferUsages::COPY_DST | wgpu::BufferUsages::MAP_READ,
2084        mapped_at_creation: false,
2085    });
2086    let mut encoder = device.create_command_encoder(&wgpu::CommandEncoderDescriptor {
2087        label: Some("sim-engine 3D depth test encoder"),
2088    });
2089    encode_scene_pass(
2090        &mut encoder,
2091        &renderer,
2092        &color_view,
2093        &depth_view,
2094        Color::BLACK,
2095        scene.instances(),
2096    );
2097    encoder.copy_texture_to_buffer(
2098        wgpu::TexelCopyTextureInfo {
2099            texture: &color_texture,
2100            mip_level: 0,
2101            origin: wgpu::Origin3d::ZERO,
2102            aspect: wgpu::TextureAspect::All,
2103        },
2104        wgpu::TexelCopyBufferInfo {
2105            buffer: &readback,
2106            layout: wgpu::TexelCopyBufferLayout {
2107                offset: 0,
2108                bytes_per_row: Some(256),
2109                rows_per_image: Some(64),
2110            },
2111        },
2112        wgpu::Extent3d {
2113            width: 64,
2114            height: 64,
2115            depth_or_array_layers: 1,
2116        },
2117    );
2118    queue.submit([encoder.finish()]);
2119    device
2120        .poll(wgpu::PollType::wait_indefinitely())
2121        .expect("3D depth test submission should complete");
2122    let slice = readback.slice(..);
2123    let (sender, receiver) = std::sync::mpsc::channel();
2124    slice.map_async(wgpu::MapMode::Read, move |result| {
2125        sender.send(result).unwrap();
2126    });
2127    device
2128        .poll(wgpu::PollType::wait_indefinitely())
2129        .expect("3D depth test mapping should complete");
2130    receiver
2131        .recv_timeout(Duration::from_secs(5))
2132        .expect("3D depth test callback should run")
2133        .expect("3D depth readback should map");
2134    let bytes = slice.get_mapped_range().expect("3D depth bytes");
2135    let center_offset = 32 * 256 + 32 * 4;
2136    assert!(
2137        bytes[center_offset + 1] > 200,
2138        "near green surface must win depth testing"
2139    );
2140    assert!(
2141        bytes[center_offset] < 20,
2142        "far red surface must remain occluded"
2143    );
2144    for x in 20..44 {
2145        let offset = 48 * 256 + x * 4;
2146        assert!(
2147            bytes[offset + 2] > 180 && bytes[offset] < 80,
2148            "coplanar near edge must remain solid visible blue at x={x}"
2149        );
2150    }
2151    let mut hidden_pattern = Vec::new();
2152    for step in 1..20 {
2153        let amount = step as f32 / 20.0;
2154        let x = (21.33 + (32.0 - 21.33) * amount).round() as usize;
2155        let y = (42.67 + (21.33 - 42.67) * amount).round() as usize;
2156        let offset = y * 256 + x * 4;
2157        hidden_pattern
2158            .push(bytes[offset] > 220 && bytes[offset + 1] > 220 && bytes[offset + 2] > 220);
2159    }
2160    assert!(
2161        hidden_pattern.windows(2).any(|pair| pair == [true, false])
2162            && hidden_pattern.windows(2).any(|pair| pair == [false, true]),
2163        "hidden edge must alternate ordered white dashes and gaps: {hidden_pattern:?}"
2164    );
2165    let near_clipped_yellow_pixels = bytes
2166        .chunks_exact(4)
2167        .filter(|pixel| pixel[0] > 180 && pixel[1] > 180 && pixel[2] < 80)
2168        .count();
2169    assert!(
2170        near_clipped_yellow_pixels >= 4,
2171        "edge crossing the near plane must remain visible after homogeneous clipping: {near_clipped_yellow_pixels} yellow pixels"
2172    );
2173    let different_object_coplanar_pixels = bytes
2174        .chunks_exact(4)
2175        .filter(|pixel| pixel[0] < 80 && pixel[1] > 180 && pixel[2] > 180)
2176        .count();
2177    assert!(
2178        different_object_coplanar_pixels >= 4,
2179        "a coplanar edge from another object must resolve visible: {different_object_coplanar_pixels} cyan pixels"
2180    );
2181    let sub_depth_resolution_pixels = bytes
2182        .chunks_exact(4)
2183        .filter(|pixel| pixel[0] > 180 && pixel[1] > 100 && pixel[2] < 80)
2184        .count();
2185    assert!(
2186        sub_depth_resolution_pixels >= 4,
2187        "sub-depth-resolution separation must conservatively resolve visible: {sub_depth_resolution_pixels} orange pixels"
2188    );
2189    drop(bytes);
2190    readback.unmap();
2191}
2192
2193#[cfg(test)]
2194pub(super) fn assert_gpu_scene_recovery_contract(
2195    source_device: &wgpu::Device,
2196    source_queue: &wgpu::Queue,
2197    recovery_device: &wgpu::Device,
2198    recovery_queue: &wgpu::Queue,
2199) {
2200    let source_identity = Arc::new(());
2201    let recovery_identity = Arc::new(());
2202    let topology = Mesh3d::with_display_edges(
2203        vec![
2204            Vec3::new(-0.5, -0.5, 0.0).unwrap(),
2205            Vec3::new(0.5, -0.5, 0.0).unwrap(),
2206            Vec3::new(0.0, 0.5, 0.0).unwrap(),
2207        ],
2208        vec![0, 1, 2],
2209        vec![MeshEdge3d::new(0, 1).unwrap()],
2210    )
2211    .unwrap();
2212    let source_mesh = create_retained_mesh(
2213        source_device,
2214        source_queue,
2215        Arc::clone(&source_identity),
2216        topology,
2217    )
2218    .unwrap();
2219    let transform_a = Transform3d::IDENTITY;
2220    let transform_b = Transform3d::new(
2221        Vec3::new(1.0, 2.0, 3.0).unwrap(),
2222        Rotation3d::IDENTITY,
2223        Vec3::new(2.0, 2.0, 2.0).unwrap(),
2224    )
2225    .unwrap();
2226    let style = MeshStyle3d::surface(SurfaceStyle3d::opaque(Color::WHITE).unwrap())
2227        .with_wireframe(WireframeStyle3d::visible(Color::BLACK, logical(1.0)).unwrap());
2228    let mut scene = Scene3d::new(Color::BLACK).unwrap();
2229    let first_id = scene.try_push(&source_mesh, transform_a, style).unwrap();
2230    let second_id = scene.try_push(&source_mesh, transform_b, style).unwrap();
2231    scene.set_visible(second_id, false).unwrap();
2232
2233    assert_eq!(
2234        validate_mesh_identity(&recovery_identity, scene.instances()[0].mesh()),
2235        Err(Mesh3dRenderError::RendererMismatch)
2236    );
2237    let report = restore_scene3d_resources(
2238        recovery_device,
2239        recovery_queue,
2240        Arc::clone(&recovery_identity),
2241        &mut scene,
2242    )
2243    .unwrap();
2244    assert_eq!(report.object_count(), 2);
2245    assert_eq!(report.migrated_object_count(), 2);
2246    assert_eq!(report.restored_mesh_count(), 1);
2247    assert_eq!(
2248        report.restored_gpu_bytes(),
2249        source_mesh.gpu_allocation_bytes()
2250    );
2251    assert_eq!(scene.instances()[0].id(), first_id);
2252    assert_eq!(scene.instances()[1].id(), second_id);
2253    assert_eq!(scene.instances()[0].transform(), transform_a);
2254    assert_eq!(scene.instances()[1].transform(), transform_b);
2255    assert_eq!(scene.instances()[0].style(), style);
2256    assert_eq!(scene.instances()[1].style(), style);
2257    assert!(scene.instances()[0].is_visible());
2258    assert!(!scene.instances()[1].is_visible());
2259    assert!(Arc::ptr_eq(
2260        &scene.instances()[0].mesh.vertex_buffer,
2261        &scene.instances()[1].mesh.vertex_buffer,
2262    ));
2263    for instance in scene.instances() {
2264        assert_eq!(
2265            validate_mesh_identity(&recovery_identity, instance.mesh()),
2266            Ok(())
2267        );
2268        assert_eq!(
2269            validate_mesh_identity(&source_identity, instance.mesh()),
2270            Err(Mesh3dRenderError::RendererMismatch)
2271        );
2272    }
2273
2274    let no_op_report = restore_scene3d_resources(
2275        recovery_device,
2276        recovery_queue,
2277        recovery_identity,
2278        &mut scene,
2279    )
2280    .unwrap();
2281    assert_eq!(no_op_report.object_count(), 2);
2282    assert_eq!(no_op_report.migrated_object_count(), 0);
2283    assert_eq!(no_op_report.restored_mesh_count(), 0);
2284    assert_eq!(no_op_report.restored_gpu_bytes(), 0);
2285}
2286
2287#[cfg(test)]
2288fn assert_gpu_clip_equivalence(device: &wgpu::Device, queue: &wgpu::Queue) {
2289    let inputs = seeded_clip_probe_inputs();
2290    let input_bytes = bytemuck::cast_slice(&inputs);
2291    let output_size = (inputs.len() * std::mem::size_of::<ClipProbeOutputGpu>()) as u64;
2292    let input_buffer = device.create_buffer(&wgpu::BufferDescriptor {
2293        label: Some("sim-engine 3D clip probe input"),
2294        size: input_bytes.len() as u64,
2295        usage: wgpu::BufferUsages::STORAGE | wgpu::BufferUsages::COPY_DST,
2296        mapped_at_creation: false,
2297    });
2298    let output_buffer = device.create_buffer(&wgpu::BufferDescriptor {
2299        label: Some("sim-engine 3D clip probe output"),
2300        size: output_size,
2301        usage: wgpu::BufferUsages::STORAGE | wgpu::BufferUsages::COPY_SRC,
2302        mapped_at_creation: false,
2303    });
2304    let readback = device.create_buffer(&wgpu::BufferDescriptor {
2305        label: Some("sim-engine 3D clip probe readback"),
2306        size: output_size,
2307        usage: wgpu::BufferUsages::COPY_DST | wgpu::BufferUsages::MAP_READ,
2308        mapped_at_creation: false,
2309    });
2310    queue.write_buffer(&input_buffer, 0, input_bytes);
2311
2312    let shader = device.create_shader_module(wgpu::ShaderModuleDescriptor {
2313        label: Some("sim-engine 3D clip equivalence shader"),
2314        source: wgpu::ShaderSource::Wgsl(Cow::Borrowed(include_str!("mesh3d.wgsl"))),
2315    });
2316    let empty_layout = device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
2317        label: Some("sim-engine empty clip probe layout"),
2318        entries: &[],
2319    });
2320    let probe_layout = device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
2321        label: Some("sim-engine 3D clip probe layout"),
2322        entries: &[
2323            wgpu::BindGroupLayoutEntry {
2324                binding: 0,
2325                visibility: wgpu::ShaderStages::COMPUTE,
2326                ty: wgpu::BindingType::Buffer {
2327                    ty: wgpu::BufferBindingType::Storage { read_only: true },
2328                    has_dynamic_offset: false,
2329                    min_binding_size: None,
2330                },
2331                count: None,
2332            },
2333            wgpu::BindGroupLayoutEntry {
2334                binding: 1,
2335                visibility: wgpu::ShaderStages::COMPUTE,
2336                ty: wgpu::BindingType::Buffer {
2337                    ty: wgpu::BufferBindingType::Storage { read_only: false },
2338                    has_dynamic_offset: false,
2339                    min_binding_size: None,
2340                },
2341                count: None,
2342            },
2343        ],
2344    });
2345    let pipeline_layout = device.create_pipeline_layout(&wgpu::PipelineLayoutDescriptor {
2346        label: Some("sim-engine 3D clip probe pipeline layout"),
2347        bind_group_layouts: &[
2348            Some(&empty_layout),
2349            Some(&empty_layout),
2350            Some(&probe_layout),
2351        ],
2352        immediate_size: 0,
2353    });
2354    let pipeline = device.create_compute_pipeline(&wgpu::ComputePipelineDescriptor {
2355        label: Some("sim-engine 3D clip probe pipeline"),
2356        layout: Some(&pipeline_layout),
2357        module: &shader,
2358        entry_point: Some("mesh3d_clip_probe_main"),
2359        compilation_options: wgpu::PipelineCompilationOptions::default(),
2360        cache: None,
2361    });
2362    let bind_group = device.create_bind_group(&wgpu::BindGroupDescriptor {
2363        label: Some("sim-engine 3D clip probe bind group"),
2364        layout: &probe_layout,
2365        entries: &[
2366            wgpu::BindGroupEntry {
2367                binding: 0,
2368                resource: input_buffer.as_entire_binding(),
2369            },
2370            wgpu::BindGroupEntry {
2371                binding: 1,
2372                resource: output_buffer.as_entire_binding(),
2373            },
2374        ],
2375    });
2376    let mut encoder = device.create_command_encoder(&wgpu::CommandEncoderDescriptor {
2377        label: Some("sim-engine 3D clip probe encoder"),
2378    });
2379    {
2380        let mut pass = encoder.begin_compute_pass(&wgpu::ComputePassDescriptor {
2381            label: Some("sim-engine 3D clip probe pass"),
2382            timestamp_writes: None,
2383        });
2384        pass.set_pipeline(&pipeline);
2385        pass.set_bind_group(2, &bind_group, &[]);
2386        pass.dispatch_workgroups((inputs.len() as u32).div_ceil(64), 1, 1);
2387    }
2388    encoder.copy_buffer_to_buffer(&output_buffer, 0, &readback, 0, output_size);
2389    queue.submit([encoder.finish()]);
2390    device
2391        .poll(wgpu::PollType::wait_indefinitely())
2392        .expect("3D clip probe submission should complete");
2393    let slice = readback.slice(..);
2394    let (sender, receiver) = std::sync::mpsc::channel();
2395    slice.map_async(wgpu::MapMode::Read, move |result| {
2396        sender.send(result).unwrap();
2397    });
2398    device
2399        .poll(wgpu::PollType::wait_indefinitely())
2400        .expect("3D clip probe mapping should complete");
2401    receiver
2402        .recv_timeout(Duration::from_secs(5))
2403        .expect("3D clip probe callback should run")
2404        .expect("3D clip probe readback should map");
2405    let bytes = slice.get_mapped_range().expect("3D clip probe bytes");
2406    let outputs: &[ClipProbeOutputGpu] = bytemuck::cast_slice(&bytes);
2407    for (case_index, (input, actual)) in inputs.iter().zip(outputs).enumerate() {
2408        let expected = clip_edge_to_frustum_details(input.start_clip, input.end_clip)
2409            .expect("finite seeded clip input should not overflow after normalization");
2410        assert_eq!(
2411            actual.visible,
2412            u32::from(expected.is_some()),
2413            "CPU/WGSL clip visibility differs for seeded case {case_index}: {input:?}"
2414        );
2415        let Some(expected) = expected else {
2416            continue;
2417        };
2418        for (actual, expected) in actual
2419            .start_clip
2420            .into_iter()
2421            .chain(actual.end_clip)
2422            .chain(actual.range)
2423            .zip(
2424                expected.clip[0]
2425                    .into_iter()
2426                    .chain(expected.clip[1])
2427                    .chain([expected.enter, expected.exit]),
2428            )
2429        {
2430            let tolerance = 32.0 * f32::EPSILON * expected.abs().max(1.0);
2431            assert!(
2432                (actual - expected).abs() <= tolerance,
2433                "CPU/WGSL clip value differs for seeded case {case_index}: actual={actual}, expected={expected}, tolerance={tolerance}, input={input:?}"
2434            );
2435        }
2436    }
2437    drop(bytes);
2438    readback.unmap();
2439}
2440
2441#[cfg(test)]
2442fn seeded_clip_probe_inputs() -> Vec<ClipProbeInputGpu> {
2443    let maximum = f32::from_bits(f32::MAX.to_bits() - 1);
2444    let mut inputs = vec![
2445        ClipProbeInputGpu {
2446            start_clip: [0.0, 0.0, 0.5, 1.0],
2447            end_clip: [0.5, 0.5, 0.75, 1.0],
2448        },
2449        ClipProbeInputGpu {
2450            start_clip: [-2.0, 0.0, 0.5, 1.0],
2451            end_clip: [0.5, 0.0, 0.5, 1.0],
2452        },
2453        ClipProbeInputGpu {
2454            start_clip: [0.0, 0.0, 0.5, 1.0],
2455            end_clip: [2.0, 0.0, 0.5, 1.0],
2456        },
2457        ClipProbeInputGpu {
2458            start_clip: [0.0, -2.0, 0.5, 1.0],
2459            end_clip: [0.0, 0.5, 0.5, 1.0],
2460        },
2461        ClipProbeInputGpu {
2462            start_clip: [0.0, 0.0, 0.5, 1.0],
2463            end_clip: [0.0, 2.0, 0.5, 1.0],
2464        },
2465        ClipProbeInputGpu {
2466            start_clip: [0.0, 0.0, -1.0, 1.0],
2467            end_clip: [0.0, 0.0, 0.5, 1.0],
2468        },
2469        ClipProbeInputGpu {
2470            start_clip: [0.0, 0.0, 0.5, 1.0],
2471            end_clip: [0.0, 0.0, 2.0, 1.0],
2472        },
2473        ClipProbeInputGpu {
2474            start_clip: [-2.0, -2.0, 0.5, 1.0],
2475            end_clip: [0.5, 0.5, 0.5, 1.0],
2476        },
2477        ClipProbeInputGpu {
2478            start_clip: [0.0, 0.0, 0.5, 1.0],
2479            end_clip: [2.0, 2.0, 2.0, 1.0],
2480        },
2481        ClipProbeInputGpu {
2482            start_clip: [-1.0, 1.0, 0.0, 1.0],
2483            end_clip: [1.0, -1.0, 1.0, 1.0],
2484        },
2485        ClipProbeInputGpu {
2486            start_clip: [maximum, 0.0, maximum * 0.5, maximum],
2487            end_clip: [-maximum, maximum, maximum, maximum],
2488        },
2489        ClipProbeInputGpu {
2490            start_clip: [0.0, 0.0, -maximum, -maximum],
2491            end_clip: [0.0, 0.0, -maximum * 0.5, -maximum * 0.5],
2492        },
2493    ];
2494    let mut state = 0x5eed_c1a5_u32;
2495    for _ in 0..244 {
2496        let mut next_component = || {
2497            state = state.wrapping_mul(1_664_525).wrapping_add(1_013_904_223);
2498            ((state >> 8) as f32 / 16_777_215.0) * 4.0 - 2.0
2499        };
2500        inputs.push(ClipProbeInputGpu {
2501            start_clip: [
2502                next_component(),
2503                next_component(),
2504                next_component(),
2505                next_component(),
2506            ],
2507            end_clip: [
2508                next_component(),
2509                next_component(),
2510                next_component(),
2511                next_component(),
2512            ],
2513        });
2514    }
2515    debug_assert_eq!(inputs.len(), 256);
2516    inputs
2517}
2518
2519#[cfg(test)]
2520mod tests {
2521    use super::*;
2522
2523    #[test]
2524    fn shader_transform_validation_rejects_finite_overflow() {
2525        let maximum = f32::MAX;
2526        let mesh = Mesh3d::new(
2527            vec![
2528                Vec3::new(maximum, 0.0, 0.0).unwrap(),
2529                Vec3::new(maximum, 1.0, 0.0).unwrap(),
2530                Vec3::new(maximum, 0.0, 1.0).unwrap(),
2531            ],
2532            vec![0, 1, 2],
2533        )
2534        .unwrap();
2535        let transform = Transform3d::new(
2536            Vec3::ZERO,
2537            Rotation3d::IDENTITY,
2538            Vec3::new(maximum, 1.0, 1.0).unwrap(),
2539        )
2540        .unwrap();
2541        let camera = Camera3d::look_at(
2542            Vec3::new(0.0, 0.0, 5.0).unwrap(),
2543            Vec3::ZERO,
2544            Vec3::Y,
2545            Projection3d::orthographic(world(4.0), 1.0, world(0.1), world(20.0)).unwrap(),
2546        )
2547        .unwrap();
2548        assert_eq!(
2549            validate_shader_transform(
2550                &mesh,
2551                transform.model_rows().unwrap(),
2552                camera.world_to_clip_rows().unwrap(),
2553            ),
2554            Err(Mesh3dRenderError::InvalidGeometryTransform)
2555        );
2556    }
2557
2558    #[test]
2559    fn scene3d_rejects_out_of_range_clear_colors() {
2560        assert!(matches!(
2561            Scene3d::new(Color::rgb(1.01, 0.0, 0.0)),
2562            Err(Scene3dError::InvalidBackground)
2563        ));
2564    }
2565
2566    #[test]
2567    fn edge_crossing_near_plane_is_clipped_before_wgsl_division() {
2568        let mesh = Mesh3d::with_display_edges(
2569            vec![
2570                Vec3::new(0.0, 0.0, -0.05).unwrap(),
2571                Vec3::new(0.5, 0.0, -1.0).unwrap(),
2572            ],
2573            Vec::new(),
2574            vec![MeshEdge3d::new(0, 1).unwrap()],
2575        )
2576        .unwrap();
2577        let camera = Camera3d::look_at(
2578            Vec3::ZERO,
2579            Vec3::new(0.0, 0.0, -1.0).unwrap(),
2580            Vec3::Y,
2581            Projection3d::perspective(1.0, 1.0, world(0.1), world(10.0)).unwrap(),
2582        )
2583        .unwrap();
2584        let style = WireframeStyle3d::visible(Color::WHITE, logical(1.0)).unwrap();
2585        assert_eq!(
2586            validate_edge_projection(
2587                &mesh,
2588                Transform3d::IDENTITY.model_rows().unwrap(),
2589                camera.world_to_clip_rows().unwrap(),
2590                style,
2591                [100.0, 100.0, 1.0, 0.0],
2592            ),
2593            Ok(())
2594        );
2595    }
2596
2597    #[test]
2598    fn fully_clipped_edges_do_not_reject_the_frame() {
2599        let mesh = Mesh3d::with_display_edges(
2600            vec![
2601                Vec3::new(0.0, 0.0, -0.01).unwrap(),
2602                Vec3::new(0.01, 0.0, -0.05).unwrap(),
2603            ],
2604            Vec::new(),
2605            vec![MeshEdge3d::new(0, 1).unwrap()],
2606        )
2607        .unwrap();
2608        let camera = Camera3d::look_at(
2609            Vec3::ZERO,
2610            Vec3::new(0.0, 0.0, -1.0).unwrap(),
2611            Vec3::Y,
2612            Projection3d::perspective(1.0, 1.0, world(0.1), world(10.0)).unwrap(),
2613        )
2614        .unwrap();
2615        assert_eq!(
2616            validate_edge_projection(
2617                &mesh,
2618                Transform3d::IDENTITY.model_rows().unwrap(),
2619                camera.world_to_clip_rows().unwrap(),
2620                WireframeStyle3d::visible(Color::WHITE, logical(1.0)).unwrap(),
2621                [100.0, 100.0, 1.0, 0.0],
2622            ),
2623            Ok(())
2624        );
2625    }
2626
2627    #[test]
2628    fn homogeneous_edge_clipping_covers_near_far_and_camera_half_spaces() {
2629        let near = clip_edge_to_frustum([0.0, 0.0, -0.5, 1.0], [0.0, 0.0, 0.5, 1.0])
2630            .unwrap()
2631            .unwrap();
2632        assert!(near[0][2].abs() <= f32::EPSILON);
2633        assert_eq!(near[1], [0.0, 0.0, 0.5, 1.0]);
2634
2635        let far = clip_edge_to_frustum([0.0, 0.0, 0.5, 1.0], [0.0, 0.0, 2.0, 1.0])
2636            .unwrap()
2637            .unwrap();
2638        assert!((far[1][2] - far[1][3]).abs() <= f32::EPSILON);
2639
2640        assert_eq!(
2641            clip_edge_to_frustum([0.0, 0.0, -2.0, -1.0], [0.0, 0.0, -1.0, -0.5]),
2642            Ok(None)
2643        );
2644        assert_eq!(
2645            clip_edge_to_frustum([-3.0, 0.0, 0.5, 1.0], [-2.0, 0.0, 0.5, 1.0]),
2646            Ok(None)
2647        );
2648    }
2649
2650    #[test]
2651    fn target_pixel_scale_is_independent_of_window_dpi() {
2652        let viewport = LogicalViewport::new(1000.0, 500.0).unwrap();
2653        assert_eq!(
2654            target_pixels_per_logical(2000, 1000, viewport),
2655            Some(physical_per_logical(2.0))
2656        );
2657        assert_eq!(
2658            target_pixels_per_logical(500, 250, viewport),
2659            Some(physical_per_logical(0.5))
2660        );
2661        assert_eq!(target_pixels_per_logical(500, 300, viewport), None);
2662        assert!(aspect_matches(16.0 / 9.0, 1920.0 / 1080.0));
2663        assert!(!aspect_matches(16.0 / 9.0, 4.0 / 3.0));
2664    }
2665
2666    #[test]
2667    fn camera_target_aspect_mismatch_is_rejected_by_render_contract() {
2668        let camera = Camera3d::look_at(
2669            Vec3::new(0.0, 0.0, 5.0).unwrap(),
2670            Vec3::ZERO,
2671            Vec3::Y,
2672            Projection3d::perspective(1.0, 16.0 / 9.0, world(0.1), world(10.0)).unwrap(),
2673        )
2674        .unwrap();
2675        let target = LogicalViewport::new(800.0, 600.0).unwrap();
2676        assert_eq!(
2677            validate_camera_target_aspect(camera, target),
2678            Err(Mesh3dRenderError::CameraTargetAspectMismatch)
2679        );
2680    }
2681
2682    #[test]
2683    fn logical_edge_width_is_equal_for_native_and_half_resolution_target() {
2684        let logical_width = logical(1.0);
2685        for pixels_per_logical in [physical_per_logical(2.0), physical_per_logical(0.5)] {
2686            let physical_width =
2687                edge_physical_half_width(logical_width, pixels_per_logical).unwrap() * 2.0;
2688            assert_eq!(
2689                physical_width / pixels_per_logical.get(),
2690                logical_width.get()
2691            );
2692        }
2693    }
2694
2695    #[test]
2696    fn mesh_upload_preflight_rejects_each_buffer_before_staging_allocation() {
2697        let max_buffer_size = 48;
2698        let layout = preflight_mesh3d_upload(4, 12, 2, max_buffer_size).unwrap();
2699        assert_eq!(layout.vertex_bytes, 48);
2700        assert_eq!(layout.index_bytes, 48);
2701        assert_eq!(layout.edge_bytes, 48);
2702        assert_eq!(layout.total_bytes, 144);
2703
2704        assert_eq!(
2705            preflight_mesh3d_upload(5, 0, 0, max_buffer_size),
2706            Err(Mesh3dResourceError::CapacityTooLarge)
2707        );
2708        assert_eq!(
2709            preflight_mesh3d_upload(1, 13, 0, max_buffer_size),
2710            Err(Mesh3dResourceError::CapacityTooLarge)
2711        );
2712        assert_eq!(
2713            preflight_mesh3d_upload(1, 0, 3, max_buffer_size),
2714            Err(Mesh3dResourceError::CapacityTooLarge)
2715        );
2716
2717        if usize::BITS > u32::BITS {
2718            let first_draw_count_overflow = u32::MAX as usize + 1;
2719            assert_eq!(
2720                preflight_mesh3d_upload(1, first_draw_count_overflow, 0, u64::MAX),
2721                Err(Mesh3dResourceError::CapacityTooLarge)
2722            );
2723            assert_eq!(
2724                preflight_mesh3d_upload(1, 0, first_draw_count_overflow, u64::MAX),
2725                Err(Mesh3dResourceError::CapacityTooLarge)
2726            );
2727        }
2728    }
2729}