vrm-runtime 0.1.0

Renderer-agnostic VRM 1.0 loader, validator, animation system, and runtime
Documentation
mod common;

use glam::Vec3;
use vrm_runtime::{
    AlphaMode, AvatarAssetBuilder, AvatarImage, AvatarMeta, AvatarTexture, EmissiveStrengthSource,
    Expression, ExpressionOverrideType, Expressions, ImageId, LookAt, LookAtRangeMap, LookAtType,
    MToonMaterial, MagFilter, Material, MaterialId, MaterialShadingModel, MinFilter, NodeId,
    NormalTextureInfo, OcclusionTextureInfo, PrimitiveTopology, RenderPrimitiveBuilder, Skin,
    SkinId, TextureId, TextureInfo, TextureSampler, TextureTransform, WrapMode,
};

fn asset_builder() -> AvatarAssetBuilder {
    AvatarAssetBuilder::new()
        .with_meta(AvatarMeta::new(
            "Programmatic avatar",
            ["vrm-runtime"],
            "https://vrm.dev/licenses/1.0/",
        ))
        .with_humanoid(common::minimal_humanoid())
        .with_nodes(common::minimal_nodes())
}

fn image() -> AvatarImage {
    AvatarImage::new("image/png", vec![137, 80, 78, 71])
}

#[test]
fn image_constructor_accepts_owned_programmatic_data() {
    let image = AvatarImage::new("image/png", [137, 80, 78, 71]);

    assert_eq!(image.mime_type, "image/png");
    assert_eq!(image.data, vec![137, 80, 78, 71]);
}

#[test]
fn public_builders_create_a_renderable_asset_with_typed_ids() {
    let sampler = TextureSampler {
        mag_filter: Some(MagFilter::Linear),
        min_filter: Some(MinFilter::LinearMipmapLinear),
        wrap_s: WrapMode::ClampToEdge,
        ..TextureSampler::default()
    };
    let texture = AvatarTexture::new(ImageId::from_index(0)).with_sampler(sampler);
    let texture_info = TextureInfo::new(TextureId::from_index(0))
        .with_tex_coord(1)
        .with_transform(TextureTransform {
            offset: [0.25, 0.5],
            rotation: 0.75,
            scale: [2.0, 3.0],
        });
    let material = Material::new()
        .with_base_color_factor([0.8, 0.7, 0.6, 0.5])
        .with_metallic_factor(0.25)
        .with_roughness_factor(0.75)
        .with_emissive_factor([0.1, 0.2, 0.3])
        .with_base_color_texture(texture_info)
        .with_metallic_roughness_texture(texture_info)
        .with_normal_texture(NormalTextureInfo::new(texture_info).with_scale(0.5))
        .with_occlusion_texture(OcclusionTextureInfo::new(texture_info).with_strength(0.75))
        .with_emissive_texture(texture_info)
        .with_emissive_strength(2.0)
        .with_unlit(true)
        .with_mtoon(MToonMaterial::new())
        .with_alpha_mode(AlphaMode::Blend)
        .with_alpha_cutoff(0.4)
        .with_double_sided(true);
    let primitive = RenderPrimitiveBuilder::new(
        NodeId::from_index(0),
        vec![[0.0, 0.0, 0.0], [1.0, 0.0, 0.0], [0.0, 1.0, 0.0]],
        vec![0, 1, 2],
    )
    .with_material(MaterialId::from_index(0))
    .with_base_color_texture(TextureId::from_index(0), 1)
    .with_texcoords(vec![[0.0, 0.0], [1.0, 0.0], [0.0, 1.0]])
    .with_topology(PrimitiveTopology::Triangles)
    .build()
    .expect("valid geometry must build");

    let asset = asset_builder()
        .with_images(vec![image()])
        .with_textures(vec![texture])
        .with_materials(vec![material])
        .with_primitives(vec![primitive])
        .build()
        .expect("the complete programmatic asset must validate");

    let texture = asset
        .texture(TextureId::from_index(0))
        .expect("the typed texture id must resolve");
    assert_eq!(texture.image_id(), ImageId::from_index(0));
    assert_eq!(texture.sampler(), sampler);

    let material = asset
        .material(MaterialId::from_index(0))
        .expect("the typed material id must resolve");
    assert_eq!(material.shading_model(), MaterialShadingModel::MToon);
    assert!(material.unlit());
    assert!(material.double_sided());
    assert_eq!(
        material.emissive_strength_source(),
        EmissiveStrengthSource::KhrMaterialsEmissiveStrength
    );
    assert_eq!(material.base_color_texture(), Some(&texture_info));
    assert_eq!(
        material
            .normal_texture()
            .expect("normal texture must be retained")
            .scale,
        0.5
    );

    let primitive = asset
        .primitives()
        .first()
        .expect("the primitive must be retained");
    assert_eq!(primitive.node_id(), NodeId::from_index(0));
    assert_eq!(primitive.material_id(), Some(MaterialId::from_index(0)));
    assert_eq!(primitive.texture_id(), Some(TextureId::from_index(0)));
    assert_eq!(primitive.base_color_texcoord(), 1);
    assert_eq!(primitive.normals(), &[[0.0, 0.0, 1.0]; 3]);
}

#[test]
fn primitive_builder_rejects_invalid_local_geometry() {
    let out_of_range_index =
        RenderPrimitiveBuilder::new(NodeId::from_index(0), vec![[0.0, 0.0, 0.0]], vec![1])
            .with_topology(PrimitiveTopology::Points)
            .build();
    assert!(out_of_range_index.is_err());

    let mismatched_normals = RenderPrimitiveBuilder::new(
        NodeId::from_index(0),
        vec![[0.0, 0.0, 0.0], [1.0, 0.0, 0.0], [0.0, 1.0, 0.0]],
        vec![0, 1, 2],
    )
    .with_normals(vec![[0.0, 1.0, 0.0]])
    .build();
    assert!(mismatched_normals.is_err());

    let non_finite_position =
        RenderPrimitiveBuilder::new(NodeId::from_index(0), vec![[f32::NAN, 0.0, 0.0]], vec![0])
            .with_topology(PrimitiveTopology::Points)
            .build();
    assert!(non_finite_position.is_err());
}

#[test]
fn asset_builder_validates_every_static_material_texture_slot() {
    let missing = TextureInfo::new(TextureId::from_index(1));
    for material in [
        Material::new().with_metallic_roughness_texture(missing),
        Material::new().with_occlusion_texture(OcclusionTextureInfo::new(missing)),
    ] {
        let result = asset_builder()
            .with_images(vec![image()])
            .with_textures(vec![AvatarTexture::new(ImageId::from_index(0))])
            .with_materials(vec![material])
            .build();
        assert!(
            result.is_err(),
            "missing texture references must be rejected"
        );
    }

    let invalid_transform =
        TextureInfo::new(TextureId::from_index(0)).with_transform(TextureTransform {
            offset: [f32::INFINITY, 0.0],
            ..TextureTransform::default()
        });
    let result = asset_builder()
        .with_images(vec![image()])
        .with_textures(vec![AvatarTexture::new(ImageId::from_index(0))])
        .with_materials(vec![
            Material::new().with_metallic_roughness_texture(invalid_transform),
        ])
        .build();
    assert!(result.is_err(), "non-finite UV transforms must be rejected");
}

#[test]
fn asset_builder_rejects_out_of_range_static_material_values() {
    let invalid_materials = [
        Material::new().with_normal_texture(
            NormalTextureInfo::new(TextureInfo::new(TextureId::from_index(0))).with_scale(f32::NAN),
        ),
        Material::new().with_occlusion_texture(
            OcclusionTextureInfo::new(TextureInfo::new(TextureId::from_index(0)))
                .with_strength(1.5),
        ),
        Material::new().with_emissive_strength(-1.0),
        Material::new().with_alpha_cutoff(f32::INFINITY),
        Material::new().with_mtoon(MToonMaterial {
            render_queue_offset_number: 10,
            ..MToonMaterial::default()
        }),
    ];

    for material in invalid_materials {
        let result = asset_builder()
            .with_images(vec![image()])
            .with_textures(vec![AvatarTexture::new(ImageId::from_index(0))])
            .with_materials(vec![material])
            .build();
        assert!(result.is_err(), "invalid material values must be rejected");
    }
}

#[test]
fn primitive_builder_can_construct_skinned_and_morphed_vertex_data() {
    let primitive =
        RenderPrimitiveBuilder::new(NodeId::from_index(0), vec![[0.0, 0.0, 0.0]], vec![0])
            .with_topology(PrimitiveTopology::Points)
            .with_skinning(vec![[0, 0, 0, 0]], vec![[1.0, 0.0, 0.0, 0.0]])
            .with_morph_target(vec![[1.0, 0.0, 0.0]], None, None)
            .with_morph_weights(vec![0.5])
            .build()
            .expect("matching vertex and morph buffers must build");

    assert_eq!(primitive.joints(), &[[0, 0, 0, 0]]);
    assert_eq!(primitive.weights(), &[[1.0, 0.0, 0.0, 0.0]]);
    assert_eq!(primitive.morph_targets().len(), 1);
    assert_eq!(primitive.morph_weights(), &[0.5]);
    assert_eq!(
        primitive.morphed_vertices().positions,
        vec![[0.5, 0.0, 0.0]]
    );
}

#[test]
fn texture_sampler_defaults_match_gltf() {
    assert_eq!(
        TextureSampler::default(),
        TextureSampler {
            mag_filter: None,
            min_filter: None,
            wrap_s: WrapMode::Repeat,
            wrap_t: WrapMode::Repeat,
        }
    );
    assert_eq!(MToonMaterial::default().shade_color, Vec3::ONE);
}

#[test]
fn asset_builder_rejects_weighted_joint_indices_outside_the_selected_skin() {
    let primitive =
        RenderPrimitiveBuilder::new(NodeId::from_index(0), vec![[0.0, 0.0, 0.0]], vec![0])
            .with_topology(PrimitiveTopology::Points)
            .with_skin(SkinId::from_index(0))
            .with_skinning(vec![[1, 0, 0, 0]], vec![[1.0, 0.0, 0.0, 0.0]])
            .build()
            .expect("local vertex data is valid before the skin is resolved");
    let result = asset_builder()
        .with_skins(vec![Skin::new(vec![0], vec![glam::Mat4::IDENTITY])])
        .with_primitives(vec![primitive])
        .build();

    assert!(result.is_err());
}

#[test]
fn asset_builder_rejects_invalid_look_at_values() {
    let invalid_offset = LookAt {
        look_at_type: LookAtType::Bone,
        offset_from_head_bone: Vec3::new(0.0, f32::INFINITY, 0.0),
        range_map_horizontal_inner: LookAtRangeMap::default(),
        range_map_horizontal_outer: LookAtRangeMap::default(),
        range_map_vertical_down: LookAtRangeMap::default(),
        range_map_vertical_up: LookAtRangeMap::default(),
    };
    assert!(
        asset_builder()
            .with_look_at(invalid_offset)
            .build()
            .is_err()
    );

    let invalid_range = LookAt {
        look_at_type: LookAtType::Expression,
        offset_from_head_bone: Vec3::ZERO,
        range_map_horizontal_inner: LookAtRangeMap {
            input_max_value: 181.0,
            output_scale: 1.0,
        },
        range_map_horizontal_outer: LookAtRangeMap::default(),
        range_map_vertical_down: LookAtRangeMap::default(),
        range_map_vertical_up: LookAtRangeMap::default(),
    };
    assert!(asset_builder().with_look_at(invalid_range).build().is_err());
}

#[test]
fn asset_builder_rejects_expressions_that_override_their_own_category() {
    let invalid_expressions = [
        Expression::new("blink").with_override_blink(ExpressionOverrideType::Blend),
        Expression::new("aa").with_override_mouth(ExpressionOverrideType::Block),
        Expression::new("lookLeft").with_override_look_at(ExpressionOverrideType::Blend),
    ];

    for expression in invalid_expressions {
        let name = expression.name().to_string();
        let result = asset_builder()
            .with_expressions(Expressions::new(vec![expression]))
            .build();

        let error = result.expect_err("same-category overrides must be rejected");
        assert!(error.to_string().contains(&name));
    }
}