vrm-runtime 0.1.0

Renderer-agnostic VRM 1.0 loader, validator, animation system, and runtime
Documentation
use glam::{Mat4, Vec3};

use crate::primitive::{PrimitiveTopology, RenderPrimitive};
use crate::runtime::SkinningPalette;
use crate::{Avatar, MaterialId, NodeId, PrimitiveId};

/// A single primitive with every CPU-side transform already applied: morph
/// weights accumulated, skinned primitives deformed by their joint matrices
/// and non-skinned ones placed by their node's world transform.
///
/// A renderer can upload these buffers directly without a morph or skinning
/// shader. For valid assets, the result follows the same morphing and skinning
/// semantics as the corresponding GPU path.
#[derive(Debug, Clone)]
pub struct CpuMesh {
    /// Stable identifier of the source primitive.
    pub primitive_id: PrimitiveId,
    /// Typed identifier of the source node.
    pub node_id: NodeId,
    /// Material selected by the source primitive.
    pub material_id: Option<MaterialId>,
    /// Final vertex positions (world space).
    pub positions: Vec<[f32; 3]>,
    /// Final normals, normalized after transformation.
    pub normals: Vec<[f32; 3]>,
    /// Final tangents (xyz normalized, w handedness preserved).
    pub tangents: Vec<[f32; 4]>,
    /// Triangle/line/point indices into the vertex attributes.
    pub indices: Vec<u32>,
    /// Consecutive `TEXCOORD_n` buffers.
    pub texcoord_sets: Vec<Vec<[f32; 2]>>,
    /// Vertex colors (RGBA).
    pub colors: Vec<[f32; 4]>,
    /// Draw topology.
    pub topology: PrimitiveTopology,
}

/// Bakes the dynamic state of one evaluated frame into CPU vertex buffers.
pub(crate) fn bake_frame(
    asset: &Avatar,
    world_matrices: &[Mat4],
    skinning_palettes: &[SkinningPalette],
    morph_weights: &[Vec<f32>],
) -> Vec<CpuMesh> {
    asset
        .primitives()
        .iter()
        .enumerate()
        .map(|(index, primitive)| {
            let world = world_matrices
                .get(primitive.node_index() as usize)
                .copied()
                .unwrap_or(Mat4::IDENTITY);
            render_primitive(
                PrimitiveId::from_index(index),
                primitive,
                morph_weights.get(index).map(Vec::as_slice).unwrap_or(&[]),
                world,
                skinning_palettes,
            )
        })
        .collect()
}

/// Transforms one vertex by `transform`, treating it as a point for
/// positions (`w = 1`) and as a direction for normals/tangents (`w = 0`).
fn transform_vertex(
    transform: Mat4,
    position: [f32; 3],
    normal: [f32; 3],
    tangent: [f32; 4],
) -> ([f32; 3], [f32; 3], [f32; 4]) {
    let position = transform
        .transform_point3(Vec3::from_array(position))
        .to_array();
    let normal = transform
        .transform_vector3(Vec3::from_array(normal))
        .normalize_or_zero()
        .to_array();
    let tangent_xyz = transform
        .transform_vector3(Vec3::from_array([tangent[0], tangent[1], tangent[2]]))
        .normalize_or_zero();
    (
        position,
        normal,
        [tangent_xyz.x, tangent_xyz.y, tangent_xyz.z, tangent[3]],
    )
}

fn render_primitive(
    primitive_id: PrimitiveId,
    primitive: &RenderPrimitive,
    morph_weights: &[f32],
    world_transform: Mat4,
    skinning_palettes: &[SkinningPalette],
) -> CpuMesh {
    let morphed = primitive.morphed_vertices_with_weights(morph_weights);
    let vertex_count = morphed.positions.len();

    let mut positions = morphed.positions;
    let mut normals = morphed.normals;
    let mut tangents = morphed.tangents;

    match primitive.skin_index() {
        Some(skin_index) => {
            let joint_matrices = skinning_palettes
                .iter()
                .find(|palette| palette.skin_id.index() == skin_index)
                .map(|palette| palette.joint_matrices.as_slice())
                .unwrap_or(&[]);
            for i in 0..vertex_count {
                // Unweighted vertices stay at their rest position, matching
                // the consuming renderer's vertex shader.
                let weight_sum: f32 = primitive
                    .skinning_sets()
                    .iter()
                    .flat_map(|set| set.weights()[i])
                    .sum();
                if weight_sum == 0.0 || joint_matrices.is_empty() {
                    continue;
                }
                let mut skin_mat = Mat4::ZERO;
                let mut valid_palette = true;
                'sets: for set in primitive.skinning_sets() {
                    for (&joint, &weight) in set.joints()[i].iter().zip(&set.weights()[i]) {
                        if weight > 0.0 {
                            let Some(joint_matrix) = joint_matrices.get(joint as usize) else {
                                valid_palette = false;
                                break 'sets;
                            };
                            skin_mat += *joint_matrix * weight;
                        }
                    }
                }
                if !valid_palette {
                    continue;
                }
                let (position, normal, tangent) =
                    transform_vertex(skin_mat, positions[i], normals[i], tangents[i]);
                positions[i] = position;
                normals[i] = normal;
                tangents[i] = tangent;
            }
        }
        None => {
            for i in 0..vertex_count {
                let (position, normal, tangent) =
                    transform_vertex(world_transform, positions[i], normals[i], tangents[i]);
                positions[i] = position;
                normals[i] = normal;
                tangents[i] = tangent;
            }
        }
    }

    CpuMesh {
        primitive_id,
        node_id: NodeId::from_index(primitive.node_index() as usize),
        material_id: primitive.material_index().map(MaterialId::from_index),
        positions,
        normals,
        tangents,
        indices: primitive.indices().to_vec(),
        texcoord_sets: primitive.texcoord_sets().to_vec(),
        colors: primitive.colors().to_vec(),
        topology: primitive.topology(),
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::morph_target::MorphTarget;
    use crate::primitive::RenderPrimitive;
    use crate::runtime::SkinningPalette;
    use crate::{SkinId, Transform};

    fn build_primitive(
        world_transform: Transform,
        skin_index: Option<usize>,
        weights: Vec<[f32; 4]>,
        morph_targets: Vec<MorphTarget>,
        morph_weights: Vec<f32>,
    ) -> RenderPrimitive {
        RenderPrimitive::new(
            3,
            world_transform,
            vec![[0.0, 0.0, 0.0], [1.0, 0.0, 0.0]],
            vec![[0.0, 0.0, 1.0], [0.0, 0.0, 1.0]],
            vec![0, 1],
            vec![[0, 1, 0, 0], [0, 1, 0, 0]],
            weights,
            morph_targets,
            vec![[0.0, 0.0], [1.0, 0.0]],
            vec![[1.0, 0.0, 0.0, 1.0], [1.0, 0.0, 0.0, 1.0]],
            vec![[1.0, 1.0, 1.0, 1.0]; 2],
            vec![[0.0, 0.0]; 2],
            None,
            None,
            PrimitiveTopology::Lines,
            morph_weights,
            false,
            skin_index,
            0,
        )
    }

    fn plain() -> RenderPrimitive {
        build_primitive(
            Transform::IDENTITY,
            None,
            vec![[0.0; 4]; 2],
            Vec::new(),
            Vec::new(),
        )
    }

    fn render_for_test(primitive: &RenderPrimitive, palettes: &[SkinningPalette]) -> CpuMesh {
        render_primitive(
            PrimitiveId::from_index(0),
            primitive,
            primitive.morph_weights(),
            primitive.world_transform().to_mat4(),
            palettes,
        )
    }

    #[test]
    fn non_skinned_uses_world_transform() {
        let transform = Transform::from_translation(glam::Vec3::new(5.0, 0.0, 0.0));
        let primitive = build_primitive(transform, None, vec![[0.0; 4]; 2], Vec::new(), Vec::new());
        let mesh = render_for_test(&primitive, &[]);

        assert_eq!(mesh.positions[0], [5.0, 0.0, 0.0]);
        assert_eq!(mesh.positions[1], [6.0, 0.0, 0.0]);
        assert_eq!(mesh.normals[0], [0.0, 0.0, 1.0]);
        assert_eq!(mesh.indices, vec![0, 1]);
        assert_eq!(mesh.node_id, NodeId::from_index(3));
    }

    #[test]
    fn skinned_primitive_moves_by_joint_matrix() {
        let primitive = build_primitive(
            Transform::IDENTITY,
            Some(0),
            vec![[1.0, 0.0, 0.0, 0.0]; 2],
            Vec::new(),
            Vec::new(),
        );
        let palette = SkinningPalette {
            skin_id: SkinId::from_index(0),
            // Vertex 0 binds joint 0, vertex 1 binds joint 1.
            joint_matrices: vec![
                Mat4::from_translation(glam::Vec3::new(1.0, 0.0, 0.0)),
                Mat4::from_translation(glam::Vec3::new(2.0, 0.0, 0.0)),
            ],
        };
        let mesh = render_for_test(&primitive, &[palette]);

        assert_eq!(mesh.positions[0], [1.0, 0.0, 0.0]);
        assert_eq!(mesh.positions[1], [2.0, 0.0, 0.0]);
    }

    #[test]
    fn skinned_vertex_with_zero_weight_stays_put() {
        let primitive = build_primitive(
            Transform::IDENTITY,
            Some(0),
            vec![[0.0; 4]; 2],
            Vec::new(),
            Vec::new(),
        );
        let palette = SkinningPalette {
            skin_id: SkinId::from_index(0),
            joint_matrices: vec![Mat4::from_translation(glam::Vec3::new(9.0, 0.0, 0.0))],
        };
        let mesh = render_for_test(&primitive, &[palette]);

        // Unweighted vertices keep their rest position.
        assert_eq!(mesh.positions[0], [0.0, 0.0, 0.0]);
        assert_eq!(mesh.positions[1], [1.0, 0.0, 0.0]);
    }

    #[test]
    fn skinned_vertex_with_missing_palette_stays_put() {
        let primitive = build_primitive(
            Transform::IDENTITY,
            Some(3),
            vec![[1.0, 0.0, 0.0, 0.0]; 2],
            Vec::new(),
            Vec::new(),
        );
        let mesh = render_for_test(&primitive, &[]);

        assert_eq!(mesh.positions[0], [0.0, 0.0, 0.0]);
    }

    #[test]
    fn malformed_runtime_palette_does_not_panic_or_partially_skin() {
        let primitive = build_primitive(
            Transform::IDENTITY,
            Some(0),
            vec![[0.0, 1.0, 0.0, 0.0]; 2],
            Vec::new(),
            Vec::new(),
        );
        let palette = SkinningPalette {
            skin_id: SkinId::from_index(0),
            // The private test constructor can bypass asset validation, so
            // this intentionally omits the weighted joint at palette index 1.
            joint_matrices: vec![Mat4::IDENTITY],
        };

        let mesh = render_for_test(&primitive, &[palette]);

        assert_eq!(mesh.positions[0], [0.0, 0.0, 0.0]);
        assert_eq!(mesh.positions[1], [1.0, 0.0, 0.0]);
    }

    #[test]
    fn tangent_handedness_is_preserved() {
        let mesh = render_for_test(&plain(), &[]);
        assert_eq!(mesh.tangents[0], [1.0, 0.0, 0.0, 1.0]);
    }

    #[test]
    fn morph_weights_are_applied() {
        let target = MorphTarget::new(vec![[2.0, 0.0, 0.0], [0.0, 3.0, 0.0]], None, None);
        let primitive = build_primitive(
            Transform::IDENTITY,
            None,
            vec![[0.0; 4]; 2],
            vec![target],
            vec![0.5],
        );
        let mesh = render_for_test(&primitive, &[]);

        // base + 0.5 * delta
        assert_eq!(mesh.positions[0], [1.0, 0.0, 0.0]);
        assert_eq!(mesh.positions[1], [1.0, 1.5, 0.0]);
    }
}