draco_io/

fbx_render_mesh.rs

//! Polygon-corner-domain expansion of an [`FbxMeshInstance`].
//!
//! FBX stores geometry as control points plus layer elements that may be
//! addressed per control point, per polygon, or per polygon *corner*. Only the
//! corner domain can express a seam: two triangles meeting at one control
//! point but carrying different UVs or normals across a hard edge.
//!
//! Resolving layers onto control points therefore loses data, silently. This
//! module resolves them onto corners instead, which is what Blender's importer
//! and every renderer do.

use draco_core::draco_types::DataType;
use draco_core::geometry_attribute::{GeometryAttributeType, PointAttribute};
use draco_core::geometry_indices::{FaceIndex, PointIndex};
use draco_core::mesh::Mesh;

use crate::fbx_scene::{
    FbxBinormalSet, FbxColorSet, FbxCreaseLayer, FbxLayerSet, FbxMeshInstance, FbxMeshLayers,
    FbxNormalSet, FbxSmoothingLayer, FbxTangentSet, FbxUvSet,
};

/// One layer element resolved onto the polygon-corner domain.
#[derive(Debug, Clone, Default, PartialEq)]
pub struct FbxRenderLayer<T> {
    /// Layer name from the source file, when it had one.
    pub name: Option<String>,
    /// One value per entry in [`FbxRenderMesh::positions`].
    pub values: Vec<T>,
}

/// An [`FbxMeshInstance`] expanded onto the polygon-corner domain.
///
/// Every list indexed "per corner" has exactly [`Self::corner_count`] entries,
/// so a renderer can upload them as parallel vertex buffers directly.
#[derive(Debug, Clone, Default, PartialEq)]
pub struct FbxRenderMesh {
    /// Corner positions, duplicated wherever a control point is shared.
    pub positions: Vec<[f32; 3]>,
    /// Every `LayerElementNormal`, in source order.
    pub normals: Vec<FbxRenderLayer<[f32; 3]>>,
    /// Every `LayerElementUV`, in source order.
    pub uvs: Vec<FbxRenderLayer<[f32; 2]>>,
    /// Every `LayerElementColor`, in source order. Linear RGBA.
    pub colors: Vec<FbxRenderLayer<[f32; 4]>>,
    /// Every `LayerElementTangent`, in source order, with the handedness sign
    /// in `w` -- the layout glTF's `TANGENT` expects.
    pub tangents: Vec<FbxRenderLayer<[f32; 4]>>,
    /// Every `LayerElementBinormal`, in source order.
    pub binormals: Vec<FbxRenderLayer<[f32; 4]>>,
    /// Triangle-fan indices into the corner arrays.
    pub indices: Vec<u32>,
    /// Corner count of each source polygon, in order.
    ///
    /// Lets a consumer that preserves n-gons -- Blender's importer does --
    /// rebuild the original faces without re-reading the file.
    pub polygon_sizes: Vec<u32>,
    /// Source control point of each corner.
    ///
    /// Skin weights and blend-shape deltas are indexed by control point, so
    /// this is how they are re-indexed onto the expanded mesh.
    pub corner_to_control_point: Vec<u32>,
    /// Source polygon of each corner.
    pub corner_to_polygon: Vec<u32>,
}

impl FbxRenderMesh {
    /// Number of polygon corners, and therefore of per-corner values.
    pub fn corner_count(&self) -> usize {
        self.positions.len()
    }
}

/// Borrowed FBX geometry, as [`expand_to_render_mesh`] and the writer consume
/// it.
///
/// The borrowed counterpart of [`FbxMeshLayers`] plus the positions and
/// indices those layers index into. Flat slices rather than a borrow of the
/// owning struct so the reader can assemble one from decode locals before an
/// [`FbxMeshInstance`] exists, and so it stays `Copy`.
///
/// A struct rather than a positional argument list because the list grows with
/// every layer family the crate learns to read, and nine adjacent slices of
/// nearly interchangeable types are easy to transpose silently.
#[derive(Debug, Clone, Copy, Default)]
pub struct FbxGeometryLayers<'a> {
    /// FBX control-point positions.
    pub control_points: &'a [[f32; 3]],
    /// Polygon-corner indices; a negative value terminates a polygon.
    pub polygon_vertex_indices: &'a [i32],
    /// UV layer elements.
    pub uv_sets: &'a [FbxUvSet],
    /// Normal layer elements.
    pub normal_sets: &'a [FbxNormalSet],
    /// Colour layer elements.
    pub color_sets: &'a [FbxColorSet],
    /// Tangent layer elements.
    pub tangent_sets: &'a [FbxTangentSet],
    /// Binormal layer elements.
    pub binormal_sets: &'a [FbxBinormalSet],
    /// Smoothing layers.
    ///
    /// Scalars on a non-corner domain, so unlike the families above these do
    /// not reach [`FbxRenderMesh`]; they are carried for the writer.
    pub smoothing_layers: &'a [FbxSmoothingLayer],
    /// Edge and vertex crease layers, carried for the writer as above.
    pub crease_layers: &'a [FbxCreaseLayer],
}

impl<'a> FbxGeometryLayers<'a> {
    /// Borrows every layer family from a decoded mesh instance.
    pub fn from_instance(instance: &'a FbxMeshInstance) -> Self {
        Self::new(
            &instance.control_points,
            &instance.polygon_vertex_indices,
            &instance.layers,
        )
    }

    /// Borrows layers that are not (yet) attached to an instance.
    pub fn new(
        control_points: &'a [[f32; 3]],
        polygon_vertex_indices: &'a [i32],
        layers: &'a FbxMeshLayers,
    ) -> Self {
        Self {
            control_points,
            polygon_vertex_indices,
            uv_sets: &layers.uv_sets,
            normal_sets: &layers.normal_sets,
            color_sets: &layers.color_sets,
            tangent_sets: &layers.tangent_sets,
            binormal_sets: &layers.binormal_sets,
            smoothing_layers: &layers.smoothing_layers,
            crease_layers: &layers.crease_layers,
        }
    }
}

/// One emitted polygon corner, carrying every domain a layer element can be
/// addressed in.
#[derive(Debug, Clone, Copy)]
struct EmittedCorner {
    /// Control point this corner references.
    control_point: u32,
    /// Position in the source `PolygonVertexIndex` stream.
    source_corner: usize,
    /// Polygon this corner belongs to.
    polygon: u32,
}

/// Resolves one layer-element value for a corner.
///
/// `mapping` selects the domain the layer is addressed in and `reference`
/// whether values are direct or indirected through `indices`.
fn resolve_layer_value<const N: usize>(
    mapping: Option<&str>,
    reference: Option<&str>,
    indices: &[i32],
    values: &[[f32; N]],
    corner: EmittedCorner,
) -> [f32; N] {
    let logical = match mapping {
        Some("ByPolygonVertex") => corner.source_corner,
        // One value per polygon -- flat shading, typically. Reading this on
        // the control-point domain returned an unrelated value.
        Some("ByPolygon") => corner.polygon as usize,
        Some("AllSame") | Some("AllSameOrPolygon") => 0,
        // `ByVertice`, `ByVertex`, `ByControlPoint` and anything unrecognized
        // address the control point.
        _ => corner.control_point as usize,
    };
    let value_index = if reference == Some("IndexToDirect") {
        match indices.get(logical).copied() {
            // A negative index is corrupt data, not a back-reference.
            Some(index) if index < 0 => return [0.0; N],
            Some(index) => index as usize,
            None => logical,
        }
    } else {
        logical
    };
    values.get(value_index).copied().unwrap_or([0.0; N])
}

/// Resolves one preserved layer element onto every polygon corner.
///
/// Component count is the only thing that differs between UV, normal, colour
/// and tangent layers, and it is a const parameter, so one function covers all
/// of them.
fn resolve_layer<const N: usize>(
    set: &FbxLayerSet<N>,
    corners: &[EmittedCorner],
) -> FbxRenderLayer<[f32; N]> {
    FbxRenderLayer {
        name: set.name.clone(),
        values: corners
            .iter()
            .map(|&corner| {
                resolve_layer_value(
                    set.mapping.as_deref(),
                    set.reference.as_deref(),
                    &set.indices,
                    &set.values,
                    corner,
                )
            })
            .collect(),
    }
}

/// Expands raw FBX geometry onto the polygon-corner domain.
///
/// Takes the parts rather than an [`FbxMeshInstance`] so the reader can call
/// it while decoding, before an instance exists.
///
/// Returns an empty mesh when there is no raw geometry, which is the case for
/// scenes synthesized in memory rather than read from a file.
pub fn expand_to_render_mesh(source: FbxGeometryLayers<'_>) -> FbxRenderMesh {
    let FbxGeometryLayers {
        control_points,
        polygon_vertex_indices,
        uv_sets,
        normal_sets,
        color_sets,
        tangent_sets,
        binormal_sets,
        // Scalars on the edge, polygon, or control-point domain. This mesh is
        // indexed by polygon corner, which cannot represent them.
        smoothing_layers: _,
        crease_layers: _,
    } = source;
    let mut render = FbxRenderMesh::default();
    if control_points.is_empty() || polygon_vertex_indices.is_empty() {
        return render;
    }

    // Walk the polygon-corner stream once, fan-triangulating as we go and
    // recording which source corner each emitted vertex came from. Layer
    // resolution then happens per emitted corner.
    let mut emitted: Vec<EmittedCorner> = Vec::new();
    let mut polygon: Vec<EmittedCorner> = Vec::new();
    let mut polygon_index = 0u32;

    for (corner, encoded) in polygon_vertex_indices.iter().enumerate() {
        let control_point = if *encoded < 0 {
            !*encoded as u32
        } else {
            *encoded as u32
        };
        polygon.push(EmittedCorner {
            control_point,
            source_corner: corner,
            polygon: polygon_index,
        });

        // A negative index terminates the polygon.
        if *encoded < 0 {
            render.polygon_sizes.push(polygon.len() as u32);
            for offset in 1..polygon.len().saturating_sub(1) {
                for &vertex in &[polygon[0], polygon[offset], polygon[offset + 1]] {
                    emitted.push(vertex);
                    render.corner_to_polygon.push(polygon_index);
                }
            }
            polygon.clear();
            polygon_index += 1;
        }
    }

    render.positions = emitted
        .iter()
        .map(|corner| {
            control_points
                .get(corner.control_point as usize)
                .copied()
                .unwrap_or([0.0; 3])
        })
        .collect();
    render.corner_to_control_point = emitted.iter().map(|c| c.control_point).collect();
    render.indices = (0..emitted.len() as u32).collect();
    render.uvs = uv_sets.iter().map(|s| resolve_layer(s, &emitted)).collect();
    render.normals = normal_sets
        .iter()
        .map(|s| resolve_layer(s, &emitted))
        .collect();
    render.colors = color_sets
        .iter()
        .map(|s| resolve_layer(s, &emitted))
        .collect();
    render.tangents = tangent_sets
        .iter()
        .map(|s| resolve_layer(&s.layer, &emitted))
        .collect();
    render.binormals = binormal_sets
        .iter()
        .map(|s| resolve_layer(&s.layer, &emitted))
        .collect();
    render
}

/// [`build_draco_mesh_with_corner_map`]'s output, for a caller that also
/// needs to carry data addressed by the original render corner -- a skin
/// weight or a morph delta, both defined per FBX control point -- onto the
/// welded points that now stand in for them.
pub struct DracoMeshWithCornerMap {
    /// The welded Draco mesh -- identical to what [`build_draco_mesh`] returns.
    pub mesh: Mesh,
    /// The welded point each original render corner collapsed into.
    /// Indexed by corner, length [`FbxRenderMesh::corner_count`].
    pub corner_to_point: Vec<u32>,
    /// One representative render corner per welded point -- the same one
    /// [`build_draco_mesh_with_corner_map`] read the point's attributes from.
    /// Indexed by point, length `mesh.num_points()`.
    pub point_to_corner: Vec<u32>,
}

/// Builds a Draco mesh from corner-domain data, welding corners that agree on
/// every attribute.
///
/// Welding keeps seams -- corners that differ in UV or normal stay separate --
/// while collapsing the interior duplicates that plain corner expansion would
/// triple. This is the same trade-off a glTF exporter makes.
///
/// Only the first UV, normal and colour set reach the Draco mesh; Draco has no
/// concept of multiple sets. The rest stay on [`FbxRenderMesh`].
pub fn build_draco_mesh(render: &FbxRenderMesh) -> Mesh {
    build_draco_mesh_with_corner_map(render).mesh
}

/// [`build_draco_mesh`], additionally returning the corner/point
/// correspondence the weld produced.
///
/// Built one point per corner -- an explicit-mapping attribute would only
/// reproduce the identity this default already is -- and welded through
/// [`draco_core::mesh::Mesh::finalize_returning_corner_map`], the same
/// merge-bit-identical-values-then-merge-points pass the OBJ, PLY and glTF
/// readers all end construction with. One fewer bespoke weld in the crate.
pub fn build_draco_mesh_with_corner_map(render: &FbxRenderMesh) -> DracoMeshWithCornerMap {
    let normals = render.normals.first();
    let uvs = render.uvs.first();
    let colors = render.colors.first();
    let corner_count = render.corner_count();

    let mut mesh = Mesh::new();
    mesh.set_num_points(corner_count);

    let mut position = PointAttribute::new();
    position.init(
        GeometryAttributeType::Position,
        3,
        DataType::Float32,
        false,
        corner_count,
    );
    for (corner, value) in render.positions.iter().enumerate() {
        let bytes: Vec<u8> = value.iter().flat_map(|v| v.to_le_bytes()).collect();
        position.buffer_mut().write(corner * 12, &bytes);
    }
    mesh.add_attribute(position);

    if let Some(layer) = normals {
        let mut normal = PointAttribute::new();
        normal.init(
            GeometryAttributeType::Normal,
            3,
            DataType::Float32,
            false,
            corner_count,
        );
        for (corner, value) in layer.values.iter().enumerate() {
            let bytes: Vec<u8> = value.iter().flat_map(|v| v.to_le_bytes()).collect();
            normal.buffer_mut().write(corner * 12, &bytes);
        }
        mesh.add_attribute(normal);
    }

    if let Some(layer) = uvs {
        let mut tex_coord = PointAttribute::new();
        tex_coord.init(
            GeometryAttributeType::TexCoord,
            2,
            DataType::Float32,
            false,
            corner_count,
        );
        for (corner, value) in layer.values.iter().enumerate() {
            let bytes: Vec<u8> = value.iter().flat_map(|v| v.to_le_bytes()).collect();
            tex_coord.buffer_mut().write(corner * 8, &bytes);
        }
        mesh.add_attribute(tex_coord);
    }

    if let Some(layer) = colors {
        let mut color = PointAttribute::new();
        color.init(
            GeometryAttributeType::Color,
            4,
            DataType::Float32,
            false,
            corner_count,
        );
        for (corner, value) in layer.values.iter().enumerate() {
            let bytes: Vec<u8> = value.iter().flat_map(|v| v.to_le_bytes()).collect();
            color.buffer_mut().write(corner * 16, &bytes);
        }
        mesh.add_attribute(color);
    }

    mesh.set_num_faces(corner_count / 3);
    for face in 0..corner_count / 3 {
        let base = (face * 3) as u32;
        mesh.set_face(
            FaceIndex(face as u32),
            [PointIndex(base), PointIndex(base + 1), PointIndex(base + 2)],
        );
    }

    let corner_to_point = mesh
        .finalize_returning_corner_map()
        .expect("deduplicating an in-memory mesh cannot fail on I/O");

    // The first corner to reach each point, matching what the point's
    // attribute values were themselves read from -- one representative per
    // point, for a caller that needs data (a tangent, a second UV set) this
    // mesh has no attribute for.
    let mut point_to_corner = vec![u32::MAX; mesh.num_points()];
    for (corner, &point) in corner_to_point.iter().enumerate() {
        if point_to_corner[point as usize] == u32::MAX {
            point_to_corner[point as usize] = corner as u32;
        }
    }

    DracoMeshWithCornerMap {
        mesh,
        corner_to_point,
        point_to_corner,
    }
}

impl FbxMeshInstance {
    /// Expands this instance onto the polygon-corner domain.
    pub fn to_render_mesh(&self) -> FbxRenderMesh {
        expand_to_render_mesh(FbxGeometryLayers::from_instance(self))
    }

    /// Corner-domain Draco mesh for this instance, welded by attribute tuple.
    ///
    /// Falls back to the stored mesh when the instance carries no raw FBX
    /// geometry to expand.
    pub fn to_draco_mesh(&self) -> Mesh {
        let render = self.to_render_mesh();
        if render.positions.is_empty() {
            return self.mesh.clone();
        }
        build_draco_mesh(&render)
    }

    /// [`Self::to_draco_mesh`], additionally returning the corner/point
    /// correspondence the weld produced -- what a caller needs to carry a
    /// per-control-point skin weight or morph delta onto the welded points
    /// that now stand in for the corners it used to be duplicated across.
    ///
    /// The stored-mesh fallback has no corners to map from, so both maps are
    /// the identity over its own points -- matching the WASM binding's own
    /// prior assumption that a point *is* its control point when there is no
    /// raw geometry to re-derive one from.
    pub fn to_draco_mesh_with_corner_map(&self) -> DracoMeshWithCornerMap {
        let render = self.to_render_mesh();
        if render.positions.is_empty() {
            let identity: Vec<u32> = (0..self.mesh.num_points() as u32).collect();
            return DracoMeshWithCornerMap {
                mesh: self.mesh.clone(),
                corner_to_point: identity.clone(),
                point_to_corner: identity,
            };
        }
        build_draco_mesh_with_corner_map(&render)
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::fbx_scene::FbxMeshInstance;

    /// Two triangles sharing an edge, with per-corner UVs that disagree across
    /// it -- the seam case that control-point resolution destroys.
    fn seamed_quad() -> FbxMeshInstance {
        FbxMeshInstance {
            control_points: vec![
                [0.0, 0.0, 0.0],
                [1.0, 0.0, 0.0],
                [1.0, 1.0, 0.0],
                [0.0, 1.0, 0.0],
            ],
            // One quad: 0, 1, 2, ~3
            polygon_vertex_indices: vec![0, 1, 2, !3],
            layers: FbxMeshLayers {
                uv_sets: vec![FbxUvSet {
                    name: Some("map1".to_string()),
                    mapping: Some("ByPolygonVertex".to_string()),
                    reference: Some("Direct".to_string()),
                    values: vec![[0.0, 0.0], [1.0, 0.0], [1.0, 1.0], [0.5, 0.5]],
                    indices: Vec::new(),
                }],
                ..Default::default()
            },
            ..Default::default()
        }
    }

    #[test]
    fn a_quad_fans_into_two_triangles_over_four_corners() {
        let render = seamed_quad().to_render_mesh();
        assert_eq!(render.polygon_sizes, vec![4]);
        assert_eq!(render.corner_count(), 6, "two fan triangles");
        assert_eq!(render.indices, vec![0, 1, 2, 3, 4, 5]);
        assert_eq!(render.corner_to_control_point, vec![0, 1, 2, 0, 2, 3]);
        assert!(render.corner_to_polygon.iter().all(|&p| p == 0));
    }

    #[test]
    fn per_corner_uvs_follow_the_corner_not_the_control_point() {
        let render = seamed_quad().to_render_mesh();
        let uv = &render.uvs[0].values;
        // Corner 3 of the fan reuses control point 0 but is source corner 0.
        assert_eq!(uv[0], [0.0, 0.0]);
        assert_eq!(uv[1], [1.0, 0.0]);
        assert_eq!(uv[2], [1.0, 1.0]);
        assert_eq!(render.uvs[0].name.as_deref(), Some("map1"));
    }

    #[test]
    fn welding_keeps_seams_but_drops_exact_duplicates() {
        let mesh = seamed_quad().to_draco_mesh();
        // Corners 0/3 and 2/4 agree on position and UV, so they weld; the
        // quad's four distinct corners survive.
        assert_eq!(mesh.num_points(), 4);
        assert_eq!(mesh.num_faces(), 2);
    }

    /// The weld map's hasher seeds itself per instance, so two builds of the
    /// same geometry hash their keys differently. Nothing about the result may
    /// follow from that: the ids are handed out in corner order and the map is
    /// only ever asked whether it has seen a key, never iterated.
    #[test]
    fn welding_gives_the_same_mesh_whatever_the_hasher_seed_is() {
        let first = seamed_quad().to_draco_mesh();
        let second = seamed_quad().to_draco_mesh();

        assert_eq!(first.num_points(), second.num_points());
        assert_eq!(first.num_faces(), second.num_faces());
        for face in 0..first.num_faces() {
            assert_eq!(
                first.face(FaceIndex(face as u32)),
                second.face(FaceIndex(face as u32)),
                "face {face} came out differently"
            );
        }
    }

    /// Corner 5 of polygon 2, sitting on control point 1.
    fn probe_corner() -> EmittedCorner {
        EmittedCorner {
            control_point: 1,
            source_corner: 5,
            polygon: 2,
        }
    }

    #[test]
    fn a_negative_index_to_direct_entry_yields_a_default_rather_than_panicking() {
        let value: [f32; 2] = resolve_layer_value(
            Some("ByPolygonVertex"),
            Some("IndexToDirect"),
            &[-31],
            &[[1.0, 2.0]],
            EmittedCorner {
                control_point: 0,
                source_corner: 0,
                polygon: 0,
            },
        );
        assert_eq!(value, [0.0, 0.0]);
    }

    #[test]
    fn each_mapping_addresses_its_own_domain() {
        // Distinct per index, so a wrong domain cannot coincidentally match.
        let values: Vec<[f32; 1]> = (0..8).map(|i| [i as f32]).collect();
        let resolve = |mapping| {
            resolve_layer_value(Some(mapping), Some("Direct"), &[], &values, probe_corner())
        };
        assert_eq!(resolve("ByPolygonVertex"), [5.0]);
        assert_eq!(resolve("ByVertice"), [1.0]);
        assert_eq!(resolve("AllSame"), [0.0]);
        // Regression: `ByPolygon` used to fall through to the control point,
        // silently returning the value of an unrelated polygon.
        assert_eq!(resolve("ByPolygon"), [2.0]);
    }

    #[test]
    fn an_instance_without_raw_geometry_expands_to_nothing() {
        let mut instance = seamed_quad();
        instance.control_points.clear();
        instance.polygon_vertex_indices.clear();
        assert_eq!(instance.to_render_mesh(), FbxRenderMesh::default());
    }
}