Skip to main content

sim_engine/renderer/mesh3d/
mod.rs

1#[cfg(test)]
2mod tests;
3#[cfg(test)]
4pub(super) use tests::{assert_gpu_depth_contract, assert_gpu_scene_recovery_contract};
5mod encoding;
6use encoding::encode_ordered_scene_pass;
7#[cfg(test)]
8use encoding::encode_scene_pass;
9mod api;
10mod frame;
11mod pipelines;
12mod report;
13mod upload_changes;
14pub use report::{
15    Mesh3dObjectError, Mesh3dRenderError, Mesh3dRenderReport, Mesh3dResourceError,
16    Scene3dRestoreReport,
17};
18mod allocation;
19use allocation::{
20    PreparedRetainedMeshUpload, allocate_retained_mesh, create_retained_mesh,
21    mesh3d_source_is_portable, prepare_retained_mesh_upload, upload_prepared_retained_mesh,
22    write_retained_mesh_uploads,
23};
24mod scene_restore;
25use scene_restore::restore_scene3d_resources;
26mod upload_layout;
27use upload_layout::{Mesh3dUploadLayout, preflight_mesh3d_source, preflight_mesh3d_upload};
28mod resources;
29use resources::{
30    align_to, create_depth_texture, create_edge_object_bind_group, create_edge_object_buffer,
31    create_edge_pipeline, create_instance_buffer,
32};
33mod vertex_proof;
34use vertex_proof::{
35    clip_plane_ranges, shader_clip_point_ranges, validate_clip_classification,
36    validate_projected_triangle_orientation,
37};
38#[cfg(test)]
39use vertex_proof::{
40    validate_shader_points, validate_shader_transform, validate_surface_triangle_topology,
41};
42mod edge_proof;
43use edge_proof::validate_edge_projection;
44#[cfg(test)]
45use edge_proof::{clip_edge_to_frustum, clip_edge_to_frustum_details, edge_raster_envelope};
46mod shader_math;
47#[cfg(test)]
48use shader_math::shader_dot;
49use shader_math::{
50    ShaderValueRange, interval_lerp_range, shader_dot_range, shader_range_minimum_magnitude,
51    wgsl_division_range, wgsl_signed_division_range,
52};
53use shader_math::{rounded_f32_add_range, rounded_f32_product_range};
54
55use super::{
56    Arc, Color, Cow, Duration, Error, GpuTimingId, GpuTimingSource, ImageBudget, ImageError,
57    ImageSampling, ImageTexelRect, Instant, LogicalViewport, MAX_PORTABLE_SHADER_VALUE,
58    RenderTarget2d, RenderTargetError, WgpuRenderer, buffer_capacity_fits, fmt, gpu_timing, image,
59    interval_products_f64, is_nonzero_subnormal, is_portable_shader_source,
60    premultiplied_wgpu_color, shader_interval_sum_range, submit_pending_uploads,
61};
62use crate::{
63    Camera3d, LogicalPixels, Mesh3d, MeshStyle3d, PhysicalPerLogical, Transform3d, Vec3,
64    WireframeStyle3d,
65};
66use std::sync::atomic::{AtomicU64, Ordering};
67
68mod validation;
69use validation::validate_points_for_policy;
70pub use validation::{Mesh3dSurfaceError, SurfaceRasterization3d};
71
72mod batch;
73
74mod surface;
75pub use surface::{Mesh3dPreflightReport, Mesh3dRenderBudget};
76use surface::{SurfaceClipEdge, SurfaceClipVertex, SurfaceFrame};
77
78mod texture;
79use texture::{MeshTextureRenderer, MeshUvGpu};
80mod restoration;
81use restoration::restore_retained_mesh;
82mod colors;
83use crate::mesh3d::{SurfaceAlphaMode3d, SurfaceSidedness3d};
84use colors::MeshColorGpu;
85mod normals;
86use normals::MeshNormalGpu;
87mod lighting;
88use crate::mesh3d::{Fog3d, Lighting3d, SurfaceLighting3d};
89use lighting::{SurfaceEnvironmentGpu, SurfaceLightingVertex, SurfaceTransport};
90mod surface_pipeline;
91use surface_pipeline::{SurfaceLayout, SurfacePipelines, create_surface_pipelines};
92mod material;
93
94pub use texture::{
95    Texture3d, Texture3dError, Texture3dOptions, Texture3dUpdateBudget,
96    Texture3dUpdateBudgetResource, Texture3dUpdateError, Texture3dUpdateReport, TextureMaterial3d,
97    TextureMipmaps3d,
98};
99
100#[cfg(test)]
101use crate::{MeshEdge3d, Projection3d, Rotation3d, SurfaceStyle3d, WorldLength};
102
103#[cfg(test)]
104pub(super) use tests::assert_gpu_scene_timing_and_upload_contract;
105
106#[cfg(test)]
107fn logical(value: f32) -> LogicalPixels {
108    LogicalPixels::new(value).unwrap()
109}
110
111#[cfg(test)]
112fn physical_per_logical(value: f32) -> PhysicalPerLogical {
113    PhysicalPerLogical::new(value).unwrap()
114}
115
116#[cfg(test)]
117fn world(value: f32) -> WorldLength {
118    WorldLength::new(value).unwrap()
119}
120
121const INITIAL_INSTANCE_CAPACITY: usize = 16;
122const DEPTH_FORMAT: wgpu::TextureFormat = wgpu::TextureFormat::Depth32Float;
123// Hidden fragments are biased one implementation depth unit away from the
124// camera; visible fragments are biased one unit toward it and are rendered
125// last. This defines a two-unit coplanar tolerance: exact/shared surface edges
126// resolve solid, while occlusion must exceed that tolerance to resolve dashed.
127const HIDDEN_EDGE_DEPTH_BIAS: i32 = 1;
128const VISIBLE_EDGE_DEPTH_BIAS: i32 = -1;
129static NEXT_SCENE3D_ID: AtomicU64 = AtomicU64::new(1);
130
131#[repr(C)]
132#[derive(Clone, Copy, Debug, bytemuck::Pod, bytemuck::Zeroable)]
133struct MeshVertexGpu {
134    position: [f32; 3],
135}
136
137impl MeshVertexGpu {
138    const ATTRIBUTES: [wgpu::VertexAttribute; 1] = wgpu::vertex_attr_array![0 => Float32x3];
139    const LAYOUT: wgpu::VertexBufferLayout<'static> = wgpu::VertexBufferLayout {
140        array_stride: std::mem::size_of::<Self>() as wgpu::BufferAddress,
141        step_mode: wgpu::VertexStepMode::Vertex,
142        attributes: &Self::ATTRIBUTES,
143    };
144}
145
146#[repr(C)]
147#[derive(Clone, Copy, Debug, bytemuck::Pod, bytemuck::Zeroable)]
148struct MeshInstanceGpu {
149    model_row_0: [f32; 4],
150    model_row_1: [f32; 4],
151    model_row_2: [f32; 4],
152    color: [f32; 4],
153    surface: [f32; 4],
154    normal_row_0: [f32; 4],
155    normal_row_1: [f32; 4],
156    normal_row_2: [f32; 4],
157    uv_transform: [f32; 4],
158}
159
160impl MeshInstanceGpu {
161    const ATTRIBUTES: [wgpu::VertexAttribute; 9] = wgpu::vertex_attr_array![1 => Float32x4, 2 => Float32x4, 3 => Float32x4, 4 => Float32x4, 7 => Float32x4, 9 => Float32x4, 10 => Float32x4, 11 => Float32x4, 12 => Float32x4];
162    const LAYOUT: wgpu::VertexBufferLayout<'static> = wgpu::VertexBufferLayout {
163        array_stride: std::mem::size_of::<Self>() as wgpu::BufferAddress,
164        step_mode: wgpu::VertexStepMode::Instance,
165        attributes: &Self::ATTRIBUTES,
166    };
167}
168
169#[repr(C)]
170#[derive(Clone, Copy, Debug, bytemuck::Pod, bytemuck::Zeroable)]
171struct Camera3dUniform {
172    clip_row_0: [f32; 4],
173    clip_row_1: [f32; 4],
174    clip_row_2: [f32; 4],
175    clip_row_3: [f32; 4],
176    viewport: [f32; 4],
177    environment: SurfaceEnvironmentGpu,
178}
179
180impl Camera3dUniform {
181    fn new(
182        camera: Camera3d,
183        width: u32,
184        height: u32,
185        scale_factor: PhysicalPerLogical,
186    ) -> Result<Self, Mesh3dRenderError> {
187        let rows = camera
188            .world_to_clip_rows()
189            .map_err(|_| Mesh3dRenderError::InvalidGeometryTransform)?;
190        let uniform = Self {
191            clip_row_0: rows[0],
192            clip_row_1: rows[1],
193            clip_row_2: rows[2],
194            clip_row_3: rows[3],
195            viewport: [width as f32, height as f32, scale_factor.get(), 0.0],
196            environment: SurfaceEnvironmentGpu::default(),
197        };
198        uniform
199            .rows()
200            .into_iter()
201            .flatten()
202            .chain(uniform.viewport)
203            .all(is_portable_shader_source)
204            .then_some(uniform)
205            .ok_or(Mesh3dRenderError::InvalidGeometryTransform)
206    }
207
208    fn rows(self) -> [[f32; 4]; 4] {
209        [
210            self.clip_row_0,
211            self.clip_row_1,
212            self.clip_row_2,
213            self.clip_row_3,
214        ]
215    }
216}
217
218#[repr(C)]
219#[derive(Clone, Copy, Debug, bytemuck::Pod, bytemuck::Zeroable)]
220struct MeshEdgeGpu {
221    start: [f32; 3],
222    end: [f32; 3],
223}
224
225impl MeshEdgeGpu {
226    const ATTRIBUTES: [wgpu::VertexAttribute; 2] =
227        wgpu::vertex_attr_array![0 => Float32x3, 1 => Float32x3];
228    const LAYOUT: wgpu::VertexBufferLayout<'static> = wgpu::VertexBufferLayout {
229        array_stride: std::mem::size_of::<Self>() as wgpu::BufferAddress,
230        step_mode: wgpu::VertexStepMode::Instance,
231        attributes: &Self::ATTRIBUTES,
232    };
233}
234
235#[repr(C)]
236#[derive(Clone, Copy, Debug, bytemuck::Pod, bytemuck::Zeroable)]
237struct EdgeObjectUniform {
238    model_row_0: [f32; 4],
239    model_row_1: [f32; 4],
240    model_row_2: [f32; 4],
241    visible_color: [f32; 4],
242    hidden_color: [f32; 4],
243    edge_style: [f32; 4],
244}
245
246#[cfg(test)]
247#[repr(C)]
248#[derive(Clone, Copy, Debug, bytemuck::Pod, bytemuck::Zeroable)]
249struct ClipProbeInputGpu {
250    start_clip: [f32; 4],
251    end_clip: [f32; 4],
252}
253
254#[cfg(test)]
255#[repr(C)]
256#[derive(Clone, Copy, Debug, bytemuck::Pod, bytemuck::Zeroable)]
257struct ClipProbeOutputGpu {
258    start_clip: [f32; 4],
259    end_clip: [f32; 4],
260    range: [f32; 2],
261    visible: u32,
262    padding: u32,
263}
264
265pub(super) struct Mesh3dRenderer {
266    dynamic_scratch: dynamic::DynamicMesh3dScratch,
267    textures: MeshTextureRenderer,
268    pipeline: SurfacePipelines,
269    colored_pipeline: SurfacePipelines,
270    colored_clipped_pipeline: SurfacePipelines,
271    clipped_color_buffer: Option<wgpu::Buffer>,
272    clipped_color_capacity: usize,
273    clipped_lighting_buffer: Option<wgpu::Buffer>,
274    clipped_lighting_capacity: usize,
275    clipped_surface_pipeline: SurfacePipelines,
276    clipped_surface_buffer: Option<wgpu::Buffer>,
277    clipped_surface_capacity: usize,
278    surface_frame: SurfaceFrame,
279    clipped_visible_edge_pipeline: wgpu::RenderPipeline,
280    clipped_hidden_edge_pipeline: wgpu::RenderPipeline,
281    clipped_edge_buffer: Option<wgpu::Buffer>,
282    clipped_edge_capacity: usize,
283    visible_edge_pipeline: wgpu::RenderPipeline,
284    hidden_edge_pipeline: wgpu::RenderPipeline,
285    camera_uniform_buffer: wgpu::Buffer,
286    previous_camera: Option<Camera3dUniform>,
287    camera_bind_group: wgpu::BindGroup,
288    instance_buffer: wgpu::Buffer,
289    instance_capacity: usize,
290    instances: Vec<MeshInstanceGpu>,
291    edge_object_layout: wgpu::BindGroupLayout,
292    edge_object_bind_group: wgpu::BindGroup,
293    edge_object_buffer: wgpu::Buffer,
294    edge_object_stride: usize,
295    edge_object_capacity: usize,
296    edge_object_bytes: Vec<u8>,
297}
298
299/// Immutable retained GPU buffers for one validated [`Mesh3d`].
300///
301/// The resource belongs to the renderer that created it and retains the core
302/// topology for explicit device-loss restoration.
303#[derive(Clone)]
304pub struct RetainedMesh3d {
305    renderer_identity: Arc<()>,
306    vertex_buffer: Arc<wgpu::Buffer>,
307    index_buffer: Option<Arc<wgpu::Buffer>>,
308    edge_buffer: Option<Arc<wgpu::Buffer>>,
309    texture_coordinate_buffer: Option<Arc<wgpu::Buffer>>,
310    color_buffer: Option<Arc<wgpu::Buffer>>,
311    normal_buffer: Option<Arc<wgpu::Buffer>>,
312    material: Option<TextureMaterial3d>,
313    source: Mesh3d,
314    index_count: u32,
315    edge_count: u32,
316    gpu_allocation_bytes: usize,
317    budget: Mesh3dUploadBudget,
318    allocation: Mesh3dUploadLayout,
319}
320
321impl RetainedMesh3d {
322    /// Returns a material-free handle sharing the same immutable topology and
323    /// attribute buffers. No CPU geometry is copied and no GPU resource is
324    /// allocated or uploaded. Existing handles and scene objects are unchanged.
325    /// UVs, normals, vertex colors, display edges and reserved capacity remain
326    /// available for later rebinding. Device provenance is unchanged; a stale
327    /// handle still needs restoration before rendering on a replacement device.
328    pub fn without_material(&self) -> Self {
329        let mut mesh = self.clone();
330        mesh.material = None;
331        mesh
332    }
333
334    /// Returns the optional shared texture/filter/tint material for this handle.
335    /// Mesh clones share buffers while retaining independent material selection.
336    pub const fn material(&self) -> Option<&TextureMaterial3d> {
337        self.material.as_ref()
338    }
339    /// Returns this revision's upload and restoration capacity limits.
340    pub const fn budget(&self) -> Mesh3dUploadBudget {
341        self.budget
342    }
343    /// Returns the immutable core topology retained for recovery.
344    pub fn source(&self) -> &Mesh3d {
345        &self.source
346    }
347
348    /// Returns the retained triangle count.
349    pub fn triangle_count(&self) -> usize {
350        self.source.triangle_count()
351    }
352
353    /// Returns allocated vertex, optional UV, triangle-index and display-edge
354    /// buffer capacity bytes, including dynamic reserve beyond live geometry.
355    /// Shared material texels are reported separately by `Texture3d`.
356    pub const fn gpu_allocation_bytes(&self) -> usize {
357        self.gpu_allocation_bytes
358    }
359
360    /// Returns CPU topology/UV bytes retained for device-loss restoration.
361    /// Shared material pixels are reported separately by `Texture3d`.
362    pub fn recovery_memory_bytes(&self) -> usize {
363        self.source.recovery_memory_bytes()
364    }
365}
366
367mod dynamic;
368mod objects;
369mod upload;
370pub use dynamic::{
371    DynamicMesh3dBudget, DynamicMesh3dBudgetResource, DynamicMesh3dError, DynamicMesh3dUpdateReport,
372};
373pub use objects::{
374    Mesh3dInstance, Object3dId, Scene3d, Scene3dBudget, Scene3dBudgetResource, Scene3dError,
375    Scene3dMeshUpdateReport, Scene3dStatistics,
376};
377pub use upload::{Mesh3dUploadBudget, Mesh3dUploadBudgetResource, Mesh3dUploadReport};
378
379/// Offscreen color and depth attachments for stereometry rendering.
380pub struct RenderTarget3d {
381    renderer_identity: Arc<()>,
382    color: RenderTarget2d,
383    _depth_texture: wgpu::Texture,
384    depth_view: wgpu::TextureView,
385    logical_viewport: LogicalViewport,
386    pixels_per_logical: PhysicalPerLogical,
387}
388
389impl RenderTarget3d {
390    /// Returns target width in physical texture pixels.
391    pub fn width(&self) -> u32 {
392        self.color.width()
393    }
394
395    /// Returns target height in physical texture pixels.
396    pub fn height(&self) -> u32 {
397        self.color.height()
398    }
399
400    /// Returns the logical viewport represented by the offscreen texture.
401    pub const fn logical_viewport(&self) -> LogicalViewport {
402        self.logical_viewport
403    }
404
405    /// Returns target texels per logical screen pixel.
406    pub const fn pixels_per_logical(&self) -> PhysicalPerLogical {
407        self.pixels_per_logical
408    }
409
410    /// Returns the composable 2D color attachment.
411    pub const fn color_target(&self) -> &RenderTarget2d {
412        &self.color
413    }
414
415    /// Returns nominal color plus depth texel-storage bytes, excluding opaque
416    /// backend alignment and resource metadata.
417    pub fn allocation_bytes(&self) -> usize {
418        self.color.allocation_bytes().saturating_add(
419            (self.width() as usize)
420                .saturating_mul(self.height() as usize)
421                .saturating_mul(4),
422        )
423    }
424}
425
426fn validate_mesh_style(mesh: &RetainedMesh3d, style: MeshStyle3d) -> Result<(), Scene3dError> {
427    validate_mesh_source_style(mesh.source(), style)
428}
429
430fn validate_mesh_source_style(source: &Mesh3d, style: MeshStyle3d) -> Result<(), Scene3dError> {
431    let has_surface = style.surface_style().is_some() && source.triangle_count() > 0;
432    if has_surface
433        && style
434            .surface_style()
435            .is_some_and(|surface| surface.lighting() == SurfaceLighting3d::Lambert)
436        && source.normals().is_empty()
437    {
438        return Err(Scene3dError::MissingNormals);
439    }
440    let has_wireframe = style.wireframe_style().is_some() && !source.display_edges().is_empty();
441    (has_surface || has_wireframe)
442        .then_some(())
443        .ok_or(Scene3dError::StyleHasNoMatchingGeometry)
444}
445
446fn validate_scene3d_transform(transform: Transform3d) -> Result<(), Scene3dError> {
447    transform
448        .model_rows()
449        .ok()
450        .is_some_and(|rows| rows.into_iter().flatten().all(is_portable_shader_source))
451        .then_some(())
452        .ok_or(Scene3dError::InvalidTransform)
453}
454
455fn target_pixels_per_logical(
456    width: u32,
457    height: u32,
458    viewport: LogicalViewport,
459) -> Option<PhysicalPerLogical> {
460    let horizontal = width as f64 / viewport.width() as f64;
461    let vertical = height as f64 / viewport.height() as f64;
462    if !horizontal.is_finite()
463        || !vertical.is_finite()
464        || horizontal <= 0.0
465        || vertical <= 0.0
466        || !aspect_matches(horizontal, vertical)
467        || horizontal > f32::MAX as f64
468    {
469        return None;
470    }
471    PhysicalPerLogical::new(horizontal as f32).ok()
472}
473
474fn aspect_matches(left: f64, right: f64) -> bool {
475    if !left.is_finite() || !right.is_finite() || left <= 0.0 || right <= 0.0 {
476        return false;
477    }
478    let scale = left.abs().max(right.abs());
479    (left - right).abs() <= scale * 1.0e-5
480}
481
482fn validate_camera_target_aspect(
483    camera: Camera3d,
484    viewport: LogicalViewport,
485) -> Result<(), Mesh3dRenderError> {
486    aspect_matches(
487        f64::from(camera.projection().aspect_ratio()),
488        f64::from(viewport.width()) / f64::from(viewport.height()),
489    )
490    .then_some(())
491    .ok_or(Mesh3dRenderError::CameraTargetAspectMismatch)
492}
493
494fn validate_target_identity(
495    renderer_identity: &Arc<()>,
496    target: &RenderTarget3d,
497) -> Result<(), Mesh3dRenderError> {
498    (Arc::ptr_eq(renderer_identity, &target.renderer_identity)
499        && Arc::ptr_eq(renderer_identity, &target.color.renderer_identity))
500    .then_some(())
501    .ok_or(Mesh3dRenderError::RendererMismatch)
502}
503
504fn validate_mesh_identity(
505    renderer_identity: &Arc<()>,
506    mesh: &RetainedMesh3d,
507) -> Result<(), Mesh3dRenderError> {
508    (Arc::ptr_eq(renderer_identity, &mesh.renderer_identity)
509        && mesh
510            .material()
511            .is_none_or(|material| material.texture().belongs_to(renderer_identity)))
512    .then_some(())
513    .ok_or(Mesh3dRenderError::RendererMismatch)
514}