sgl-3d 0.4.2

Caller-driven 3D rendering for SGL games, native and in the browser (WebGPU)
Documentation
//! Prepared geometry (the architecture's "Prepared geometry"): everything
//! of building a model that depends only on its meshes, done without a
//! device or a scene, so a game prepares its models on whichever threads
//! it chooses and `Scene::add_model` and `set_model` only place and copy
//! them (`models`).
use super::SceneError;
use super::deformation::{self, PreparedDeformation};
use super::mesh_ranges::{INDICES_PER_LEAF, MeshRanges};
use super::rays::{self, PreparedRayModel, RayMesh};
use super::shadow_clusters::ClusteredIndices;
use crate::asset::{self, Vertex};
use crate::content::identity::MaterialId;
use crate::content::model::ModelMesh;
use crate::counters::{BuildStep, step};
use crate::shading::culling::MAX_MESH_SECTIONS;
use crate::shading::packed_vertex::UvRect;
use crate::shading::vertex::CasterVertex;
use glam::{Vec2, Vec3};

/// A model's geometry, prepared for `Scene::add_model` or `Scene::set_model`
/// by `PreparedModel::new`, which needs no device and no scene: build it on
/// any thread and give it to the scene on the one that edits it. The
/// operation consumes it.
pub struct PreparedModel {
    pub(super) bounds: [Vec3; 2],
    pub(super) meshes: Vec<PreparedMesh>,
    pub(super) rays: PreparedRayModel,
    pub(super) deformation: Option<PreparedDeformation>,
}

/// One mesh of a prepared model.
pub(super) struct PreparedMesh {
    pub material: MaterialId,
    /// Every vertex has an authored tangent frame.
    pub tangents: bool,
    /// Its shadow casters' positions; none when its model deforms, whose
    /// instances' casters read their deformed positions from the ray source.
    pub positions: Vec<CasterVertex>,
    pub indices: Vec<u32>,
    pub ranges: MeshRanges,
    /// None without triangles.
    pub clusters: Option<ClusteredIndices>,
}

/// `vertices` and `indices` as a mesh: indices name vertices, positions,
/// UVs and lightmap UVs are finite, the UVs' rectangle has a finite extent,
/// and normals are finite and not zero, as a packed vertex needs
/// (`shading::packed_vertex`): its frame a normal, and its UVs fractions of
/// their mesh's rectangle, which an infinite extent collapses onto its
/// corner. Returns whether every vertex has an authored tangent frame.
pub(super) fn validate_geometry(vertices: &[Vertex], indices: &[u32]) -> Result<bool, SceneError> {
    if indices
        .iter()
        .any(|&index| index as usize >= vertices.len())
    {
        return Err(SceneError::IndexOutOfRange);
    }
    if !vertices.iter().all(|vertex| {
        (vertex.position.iter())
            .chain(&vertex.uv)
            .chain(&vertex.lightmap_uv)
            .all(|x| x.is_finite())
            && Vec3::from_array(vertex.normal)
                .as_dvec3()
                .try_normalize()
                .is_some()
    }) || !Vec2::from_array(UvRect::of(vertices).extent).is_finite()
    {
        return Err(SceneError::NonFiniteGeometry);
    }
    Ok(asset::tangent_frames(vertices))
}

/// Whether a mesh of `triangles` holds at most `MAX_MESH_SECTIONS`
/// sections, the most a GPU-built list's section cull strides over.
pub(crate) fn fits_sections(triangles: usize) -> bool {
    triangles.div_ceil(INDICES_PER_LEAF / 3) <= MAX_MESH_SECTIONS as usize
}

impl PreparedModel {
    /// `meshes`, an ordered list each drawn with a material of the scene
    /// that will take them, prepared: validated (indices name vertices,
    /// positions, UVs and normals are as `Vertex` requires, a deformation
    /// fits its vertices, a mesh
    /// holds at most 65,536 sections of 128 triangles), with each mesh's
    /// culling hierarchy, whose leaves are its sections, and shadow-caster
    /// clusters, the model's BVH, and its ray-source words (its section
    /// tables among them) and shadow-caster geometry packed. What needs the
    /// scene or the device (its materials, the device's limits) is checked
    /// when it is added.
    pub fn new(meshes: Vec<ModelMesh>) -> Result<Self, SceneError> {
        let streams = vec![Vec::new(); meshes.len()];
        Self::prepare(meshes, streams)
    }

    /// `meshes` prepared as `new` prepares them, each with the data its
    /// material's shader reads per vertex (`MaterialVertex::shader_data`):
    /// `shader_data[i]` is mesh `i`'s, empty for none, whose vertices read
    /// zero, or one entry per vertex, held beside its vertices once, 16
    /// bytes a vertex. A mesh given another count is refused
    /// (`SceneError::ShaderDataLength`).
    pub fn with_shader_data(
        meshes: Vec<ModelMesh>,
        shader_data: Vec<Vec<[f32; 4]>>,
    ) -> Result<Self, SceneError> {
        if let Some(mesh) = (0..meshes.len().max(shader_data.len())).find(|&index| {
            match (meshes.get(index), shader_data.get(index)) {
                (Some(mesh), Some(data)) => !data.is_empty() && data.len() != mesh.vertices.len(),
                _ => true,
            }
        }) {
            return Err(SceneError::ShaderDataLength { mesh });
        }
        Self::prepare(meshes, shader_data)
    }

    fn prepare(
        meshes: Vec<ModelMesh>,
        shader_data: Vec<Vec<[f32; 4]>>,
    ) -> Result<Self, SceneError> {
        let tangents = step(BuildStep::Validate, || {
            if !meshes
                .iter()
                .all(|mesh| fits_sections(mesh.indices.len() / 3))
            {
                return Err(SceneError::TooManySections);
            }
            let tangents = meshes
                .iter()
                .map(|mesh| validate_geometry(&mesh.vertices, &mesh.indices))
                .collect::<Result<Vec<_>, _>>()?;
            deformation::validate(&meshes)?;
            Ok::<_, SceneError>(tangents)
        })?;
        let ranges: Vec<_> = step(BuildStep::Ranges, || {
            meshes
                .iter()
                .map(|mesh| MeshRanges::new(&mesh.vertices, &mesh.indices))
                .collect()
        });
        let ray_meshes: Vec<_> = meshes
            .iter()
            .zip(&ranges)
            .zip(&shader_data)
            .map(|((mesh, ranges), shader_data)| RayMesh {
                vertices: &mesh.vertices,
                indices: &mesh.indices,
                ranges,
                shader_data,
            })
            .collect();
        let rays = rays::prepare_model(&ray_meshes)?;
        let deformation = step(BuildStep::Pack, || PreparedDeformation::new(&meshes));
        let deforms = deformation.is_some();
        let bounds = meshes.iter().flat_map(|mesh| &mesh.vertices).fold(
            [Vec3::splat(f32::INFINITY), Vec3::splat(f32::NEG_INFINITY)],
            |bounds, vertex| {
                let p = Vec3::from_array(vertex.position);
                [bounds[0].min(p), bounds[1].max(p)]
            },
        );
        let meshes = meshes
            .into_iter()
            .zip(tangents)
            .zip(ranges)
            .map(|((mesh, tangents), ranges)| {
                let positions = step(BuildStep::Pack, || {
                    if deforms {
                        Vec::new()
                    } else {
                        mesh.vertices
                            .iter()
                            .map(|vertex| CasterVertex {
                                position: vertex.position,
                            })
                            .collect()
                    }
                });
                PreparedMesh {
                    material: mesh.material,
                    tangents,
                    positions,
                    ranges,
                    clusters: step(BuildStep::Clusters, || {
                        ClusteredIndices::new(&mesh.vertices, &mesh.indices)
                    }),
                    indices: mesh.indices,
                }
            })
            .collect();
        Ok(Self {
            bounds,
            meshes,
            rays,
            deformation,
        })
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::content::identity::Identity;
    use wasm_bindgen_test::wasm_bindgen_test;

    /// One mesh of triangles at `vertices`, three to a triangle.
    fn model(vertices: Vec<Vertex>) -> Result<PreparedModel, SceneError> {
        meshes(vec![vertices])
    }

    /// A mesh of triangles at each of `meshes`' vertices, three to a
    /// triangle.
    fn meshes(meshes: Vec<Vec<Vertex>>) -> Result<PreparedModel, SceneError> {
        PreparedModel::new(
            meshes
                .into_iter()
                .map(|vertices| ModelMesh {
                    material: MaterialId::issue(0, 0),
                    indices: (0..vertices.len() as u32).collect(),
                    vertices,
                    deformation: Default::default(),
                })
                .collect(),
        )
    }

    // Individually finite weights can still overflow their f32 sum. The
    // validator must reject that before normalization loses every influence.
    #[wasm_bindgen_test(unsupported = test)]
    fn overflowing_skin_weight_sums_are_rejected() {
        use crate::deformation::{Influence, MeshDeformation};
        let mut mesh = ModelMesh {
            material: MaterialId::issue(0, 0),
            vertices: vec![vertex([0., 0., 1.], [0., 0., 1., 1.])],
            indices: Vec::new(),
            deformation: MeshDeformation {
                influences: vec![Influence {
                    joints: [0; 4],
                    weights: [f32::MAX, f32::MAX, 0., 0.],
                }],
                morph_targets: Vec::new(),
            },
        };
        assert!(matches!(
            deformation::validate(std::slice::from_ref(&mesh)),
            Err(SceneError::InvalidDeformation)
        ));
        mesh.deformation.influences[0].weights = [f32::MAX, 0., 0., 0.];
        assert!(deformation::validate(&[mesh]).is_ok());
    }

    fn vertex(normal: [f32; 3], lightmap_bounds: [f32; 4]) -> Vertex {
        Vertex {
            position: [0.; 3],
            normal,
            lightmap_bounds,
            ..bytemuck::Zeroable::zeroed()
        }
    }

    // Plausible defects: a vertex whose normal has no frame reaching the
    // encoder, which cannot pack it; a non-finite UV or lightmap UV
    // accepted, where one infinite UV collapses its whole mesh's packed UVs
    // onto one texel (#584); a mesh past what a packed vertex's 16-bit chart
    // index can name accepted, aliasing charts, or one at the limit refused
    // (an off-by-one); the limit counted across a model's meshes rather than
    // within each, which refused Hyperdrive's courses (#182); or the refusal
    // naming another mesh. The oracle is the Vertex encoding's contract: a
    // zero or non-finite normal, or a non-finite UV or lightmap UV, refuses
    // the mesh as a non-finite position does, and each mesh may name up to
    // 65,536 distinct chart bounds, a refusal naming the mesh's index. CPU
    // only.
    #[wasm_bindgen_test(unsupported = test)]
    fn unpackable_vertices_are_refused() {
        let unit = [0., 0., 1.];
        assert!(model(vec![vertex(unit, [0.; 4]); 3]).is_ok());
        for normal in [[0.; 3], [f32::NAN, 0., 1.], [f32::INFINITY, 0., 0.]] {
            assert!(matches!(
                model(vec![
                    vertex(unit, [0.; 4]),
                    vertex(normal, [0.; 4]),
                    vertex(unit, [0.; 4])
                ]),
                Err(SceneError::NonFiniteGeometry)
            ));
        }
        let with = |uv: [f32; 2], lightmap_uv: [f32; 2]| {
            let mut vertices = vec![vertex(unit, [0.; 4]); 3];
            vertices[1].uv = uv;
            vertices[1].lightmap_uv = lightmap_uv;
            model(vertices)
        };
        assert!(with([-1e30, 1e30], [-1., 2.]).is_ok());
        // Finite UVs whose rectangle's extent overflows f32 collapse as an
        // infinite one does.
        let mut spanning = vec![vertex(unit, [0.; 4]); 3];
        spanning[0].uv = [-3e38, 0.];
        spanning[1].uv = [3e38, 0.];
        assert!(matches!(
            model(spanning),
            Err(SceneError::NonFiniteGeometry)
        ));
        for (uv, lightmap_uv) in [
            ([f32::INFINITY, 0.], [0.; 2]),
            ([0., f32::NAN], [0.; 2]),
            ([0.; 2], [f32::NEG_INFINITY, 0.]),
            ([0.; 2], [0., f32::NAN]),
        ] {
            assert!(matches!(
                with(uv, lightmap_uv),
                Err(SceneError::NonFiniteGeometry)
            ));
        }
        // `count` distinct chart bounds, offset by `first` so that no two
        // meshes name the same one.
        let charts = |first: usize, count: usize| {
            (0..count.div_ceil(3) * 3)
                .map(|index| {
                    let chart = first + index.min(count - 1);
                    vertex(unit, [chart as f32, 0., 1., 1.])
                })
                .collect::<Vec<_>>()
        };
        assert!(model(charts(0, 1 << 16)).is_ok());
        assert!(matches!(
            model(charts(0, (1 << 16) + 1)),
            Err(SceneError::TooManyLightmapCharts { mesh: 0 })
        ));
        assert!(meshes(vec![charts(0, 40_000), charts(40_000, 40_000)]).is_ok());
        assert!(matches!(
            meshes(vec![charts(0, 3), charts(3, (1 << 16) + 1)]),
            Err(SceneError::TooManyLightmapCharts { mesh: 1 })
        ));
    }
}