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;
28const 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#[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 pub fn source(&self) -> &Mesh3d {
384 &self.source
385 }
386
387 pub fn triangle_count(&self) -> usize {
389 self.source.triangle_count()
390 }
391
392 pub const fn gpu_allocation_bytes(&self) -> usize {
394 self.gpu_allocation_bytes
395 }
396
397 pub fn recovery_memory_bytes(&self) -> usize {
399 self.source.recovery_memory_bytes()
400 }
401}
402
403#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
405pub struct Object3dId {
406 scene_id: u64,
407 object_id: u64,
408}
409
410impl Object3dId {
411 pub const fn get(self) -> u64 {
416 self.object_id
417 }
418}
419
420#[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 pub const fn id(&self) -> Object3dId {
448 self.id
449 }
450
451 pub const fn mesh(&self) -> &RetainedMesh3d {
453 &self.mesh
454 }
455
456 pub const fn transform(&self) -> Transform3d {
458 self.transform
459 }
460
461 pub const fn style(&self) -> MeshStyle3d {
463 self.style
464 }
465
466 pub const fn is_visible(&self) -> bool {
468 self.visible
469 }
470
471 pub const fn wireframe(&self) -> Option<WireframeStyle3d> {
473 self.style.wireframe_style()
474 }
475}
476
477pub struct Scene3d {
479 scene_id: u64,
480 background: Color,
481 instances: Vec<Mesh3dInstance>,
482 next_object_id: u64,
483}
484
485impl Scene3d {
486 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 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 pub const fn background(&self) -> Color {
527 self.background
528 }
529
530 pub fn instances(&self) -> &[Mesh3dInstance] {
532 &self.instances
533 }
534
535 pub fn object_count(&self) -> usize {
537 self.instances.len()
538 }
539
540 pub fn visible_object_count(&self) -> usize {
542 self.instances
543 .iter()
544 .filter(|instance| instance.visible)
545 .count()
546 }
547
548 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 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 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 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
614pub 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 pub fn width(&self) -> u32 {
627 self.color.width()
628 }
629
630 pub fn height(&self) -> u32 {
632 self.color.height()
633 }
634
635 pub const fn logical_viewport(&self) -> LogicalViewport {
637 self.logical_viewport
638 }
639
640 pub const fn pixels_per_logical(&self) -> PhysicalPerLogical {
642 self.pixels_per_logical
643 }
644
645 pub const fn color_target(&self) -> &RenderTarget2d {
647 &self.color
648 }
649
650 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#[derive(Debug, Clone, Copy, PartialEq, Eq)]
662pub enum Scene3dError {
663 InvalidBackground,
665 EmptyStyle,
667 StyleHasNoMatchingGeometry,
669 SceneIdExhausted,
671 ObjectIdExhausted,
673 ObjectNotFound {
675 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#[derive(Debug, Clone, Copy, PartialEq)]
713pub enum Mesh3dResourceError {
714 CapacityTooLarge,
716 HostAllocationFailed {
718 requested_bytes: u64,
720 },
721 Target(RenderTargetError),
723 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#[derive(Debug, Clone, Copy, PartialEq, Eq)]
748pub enum Mesh3dRenderError {
749 RendererMismatch,
751 InvalidGeometryTransform,
753 InstanceCapacityTooLarge,
755 CameraTargetAspectMismatch,
757 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#[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 pub const fn object_count(self) -> usize {
801 self.object_count
802 }
803
804 pub const fn triangle_count(self) -> usize {
806 self.triangle_count
807 }
808
809 pub const fn edge_count(self) -> usize {
811 self.edge_count
812 }
813
814 pub const fn upload(self) -> Duration {
816 self.upload
817 }
818
819 pub const fn encode_submit(self) -> Duration {
821 self.encode_submit
822 }
823}
824
825#[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 pub const fn object_count(self) -> usize {
837 self.object_count
838 }
839
840 pub const fn migrated_object_count(self) -> usize {
842 self.migrated_object_count
843 }
844
845 pub const fn restored_mesh_count(self) -> usize {
847 self.restored_mesh_count
848 }
849
850 pub const fn restored_gpu_bytes(self) -> usize {
852 self.restored_gpu_bytes
853 }
854}
855
856impl WgpuRenderer {
857 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 pub fn restore_mesh3d(
874 &self,
875 source: &RetainedMesh3d,
876 ) -> Result<RetainedMesh3d, Mesh3dResourceError> {
877 self.create_mesh3d(source.source.clone())
878 }
879
880 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 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 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 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}