sim-engine 0.4.2

A validated high-performance visualization engine for simulations
Documentation
//! Surface rasterization policy and source-attributed numerical validation.

use super::{
    MAX_PORTABLE_SHADER_VALUE, Mesh3d, Mesh3dObjectError, Mesh3dRenderError, Object3dId, Vec3,
    interval_products_f64, is_portable_shader_source, shader_clip_point_ranges,
    validate_clip_classification,
};

mod bounds;

#[cfg(test)]
mod tests;

pub(super) fn native_mesh_is_outside(
    mesh: &Mesh3d,
    model_rows: [[f32; 4]; 3],
    camera_rows: [[f32; 4]; 4],
) -> bool {
    bounds::native_mesh_is_outside(mesh, model_rows, camera_rows)
}

pub(super) fn fog_transform_is_proven(
    mesh: &Mesh3d,
    model_rows: [[f32; 4]; 3],
    depth_row: [f32; 4],
) -> bool {
    bounds::fog_transform_is_proven(mesh, model_rows, depth_row)
}

/// Selects the portability contract for filled 3D surfaces, not display edges.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
#[non_exhaustive]
pub enum SurfaceRasterization3d {
    /// Proves clip classification and projected orientation across the portable
    /// shader arithmetic envelope, using canonical CPU clipping for crossings.
    /// Ambiguous and edge-on triangles return a source-attributed error.
    #[default]
    StrictPortable,
    /// Submits original indexed surfaces for native hardware clipping and
    /// rasterization. Finite shader arithmetic is still validated, but grazing,
    /// edge-on and camera-plane surfaces need no CPU topology proof.
    ///
    /// Coverage at numerical boundaries may differ across adapters. No uncertain
    /// source triangles are dropped by the CPU. Hardware-clipped/zero-area
    /// primitives may produce no fragments; preflight reports submissions, not
    /// visibility, and does not claim CPU classification counts in this mode.
    /// Mathematical display edges retain their independent strict validation.
    Native,
}

/// Specific cause of failure for an original source surface triangle.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum Mesh3dSurfaceError {
    /// An active Lambert source normal loses a provably usable transformed direction.
    NormalTransform,
    /// Active fog camera-forward world-distance arithmetic leaves the finite envelope.
    FogArithmetic,
    /// Model/camera products or sums leave the finite portable shader envelope.
    TransformArithmetic,
    /// A vertex's side of a clipping plane cannot be proved consistently.
    ClipPlaneClassification,
    /// A clip intersection or its interpolated attributes cannot be proved safe.
    ClipIntersection,
    /// Rounded coincident endpoints cannot be proved to be the same vertex.
    ClippedVertexIdentity,
    /// The fixed clipping polygon capacity would be exceeded.
    ClippedPolygonCapacity,
    /// A nonempty clipped polygon has fewer than three proven vertices.
    ClippedPolygonDegenerate,
    /// A surviving vertex cannot be safely divided by its homogeneous W.
    PerspectiveDivide,
    /// A generated vertex cannot be proved inside the complete clip volume.
    ClippedVertexOutside,
    /// The projected signed area cannot be proved to have a nonzero sign.
    ProjectedOrientation,
}

impl Mesh3dSurfaceError {
    #[cfg(test)]
    pub(super) fn legacy(self) -> Mesh3dRenderError {
        match self {
            Self::TransformArithmetic => Mesh3dRenderError::InvalidGeometryTransform,
            _ => Mesh3dRenderError::UnportableSurfaceTopology,
        }
    }

    pub(super) fn for_triangle(
        self,
        object_id: Object3dId,
        triangle_index: usize,
    ) -> Mesh3dRenderError {
        Mesh3dRenderError::ObjectFailure {
            object_id,
            reason: Mesh3dObjectError::SurfaceTriangle {
                triangle_index,
                reason: self,
            },
        }
    }
}

pub(super) fn validate_points_for_policy(
    mesh: &Mesh3d,
    model_rows: [[f32; 4]; 3],
    camera_rows: [[f32; 4]; 4],
    policy: SurfaceRasterization3d,
    object_id: Object3dId,
) -> Result<(), Mesh3dRenderError> {
    if policy == SurfaceRasterization3d::Native
        && bounds::native_transform_is_proven(mesh, model_rows, camera_rows)
    {
        return Ok(());
    }
    for (vertex_index, vertex) in mesh.vertices().iter().enumerate() {
        let result = validate_point_for_policy(*vertex, model_rows, camera_rows, policy);
        if let Err(reason) = result {
            // Only failures search for a source owner; the ordinary path does
            // not allocate an adjacency map or validate shared vertices twice.
            return Err(Mesh3dRenderError::ObjectFailure {
                object_id,
                reason: source_point_error(mesh, vertex_index, reason),
            });
        }
    }
    Ok(())
}

fn source_point_error(
    mesh: &Mesh3d,
    vertex_index: usize,
    reason: Mesh3dSurfaceError,
) -> Mesh3dObjectError {
    match mesh
        .triangle_indices()
        .iter()
        .position(|index| *index as usize == vertex_index)
    {
        Some(index) => Mesh3dObjectError::SurfaceTriangle {
            triangle_index: index / 3,
            reason,
        },
        None => Mesh3dObjectError::Vertex {
            vertex_index,
            reason,
        },
    }
}

pub(super) fn validate_point_for_policy(
    vertex: Vec3,
    model_rows: [[f32; 4]; 3],
    camera_rows: [[f32; 4]; 4],
    policy: SurfaceRasterization3d,
) -> Result<(), Mesh3dSurfaceError> {
    let clip = shader_clip_point_ranges(vertex, model_rows, camera_rows)
        .map_err(|_| Mesh3dSurfaceError::TransformArithmetic)?;
    if policy == SurfaceRasterization3d::StrictPortable {
        validate_clip_classification(clip)
            .map_err(|_| Mesh3dSurfaceError::ClipPlaneClassification)?;
    }
    Ok(())
}