Skip to main content

VrmAnimation

Struct VrmAnimation 

Source
pub struct VrmAnimation { /* private fields */ }
Expand description

A playable VRM humanoid animation.

Programmatic clips store target-local rotation deltas. Clips loaded from .vrma additionally retain the source rest pose needed for retargeting.

Implementations§

Source§

impl VrmAnimation

Source

pub fn new(duration: f32) -> Self

Creates an empty programmatic clip with the given duration in seconds.

Tracks may be inserted before validation. AvatarRuntime::play validates the complete clip before it becomes active.

Source

pub const fn duration(&self) -> f32

Returns the clip duration in seconds.

Examples found in repository?
examples/vrma.rs (line 19)
8fn main() -> Result<(), Box<dyn std::error::Error>> {
9    let mut arguments = std::env::args().skip(1);
10    let avatar_path = arguments
11        .next()
12        .expect("usage: vrma <avatar.vrm> <motion.vrma>");
13    let animation_path = arguments
14        .next()
15        .expect("usage: vrma <avatar.vrm> <motion.vrma>");
16
17    let avatar = AvatarAsset::load(avatar_path)?;
18    let animation = VrmAnimation::load(animation_path)?;
19    let duration = animation.duration();
20    let mut runtime = AvatarRuntime::new(avatar);
21
22    runtime.play(
23        animation,
24        PlaybackOptions {
25            mode: PlaybackMode::Once,
26            ..PlaybackOptions::default()
27        },
28    )?;
29
30    let delta_seconds = 1.0 / 60.0;
31    let frame_count = ((duration / delta_seconds).ceil() as usize).max(1) + 1;
32    for frame_index in 0..frame_count {
33        let (draw_count, bone_update_count) = {
34            let frame = runtime.update(delta_seconds)?;
35            (frame.gpu().draws().len(), frame.bone_updates().len())
36        };
37
38        if frame_index % 60 == 0 || !runtime.is_playing() {
39            println!(
40                "time={:.3}s draws={} bone_updates={}",
41                runtime.playback_time().unwrap_or(0.0),
42                draw_count,
43                bone_update_count,
44            );
45        }
46        if !runtime.is_playing() {
47            break;
48        }
49    }
50
51    Ok(())
52}
Source

pub fn with_bone_track(self, bone: HumanBone, track: BoneTrack) -> Self

Adds or replaces a humanoid bone track.

Source

pub fn insert_bone_track( &mut self, bone: HumanBone, track: BoneTrack, ) -> Option<BoneTrack>

Inserts a humanoid bone track and returns the previous value, if any.

Source

pub fn with_expression_track( self, name: impl Into<String>, track: Track<f32>, ) -> Self

Adds or replaces an expression weight track.

Source

pub fn insert_expression_track( &mut self, name: impl Into<String>, track: Track<f32>, ) -> Option<Track<f32>>

Inserts an expression weight track and returns the previous value, if any.

Source

pub fn with_look_at_rotation_track(self, track: Track<Quat>) -> Self

Adds or replaces the LookAt rotation track.

Source

pub fn set_look_at_rotation_track( &mut self, track: Track<Quat>, ) -> Option<Track<Quat>>

Replaces the LookAt rotation track and returns the previous value, if any.

Source

pub fn load<P: AsRef<Path>>(path: P) -> Result<Self, AnimationLoadError>

Loads the first animation from a VRMA file using strict validation.

Relative external buffers are resolved against the file’s parent directory. Use Self::load_with_options to collect diagnostics from permissive validation.

§Errors

Returns AnimationLoadError when the file cannot be read, its glTF or VRMC_vrm_animation data is invalid, or it requires an unsupported extension.

§Examples
use vrm_runtime::VrmAnimation;

let animation = VrmAnimation::load("motion.vrma")?;
println!("duration: {} seconds", animation.duration());
Examples found in repository?
examples/vrma.rs (line 18)
8fn main() -> Result<(), Box<dyn std::error::Error>> {
9    let mut arguments = std::env::args().skip(1);
10    let avatar_path = arguments
11        .next()
12        .expect("usage: vrma <avatar.vrm> <motion.vrma>");
13    let animation_path = arguments
14        .next()
15        .expect("usage: vrma <avatar.vrm> <motion.vrma>");
16
17    let avatar = AvatarAsset::load(avatar_path)?;
18    let animation = VrmAnimation::load(animation_path)?;
19    let duration = animation.duration();
20    let mut runtime = AvatarRuntime::new(avatar);
21
22    runtime.play(
23        animation,
24        PlaybackOptions {
25            mode: PlaybackMode::Once,
26            ..PlaybackOptions::default()
27        },
28    )?;
29
30    let delta_seconds = 1.0 / 60.0;
31    let frame_count = ((duration / delta_seconds).ceil() as usize).max(1) + 1;
32    for frame_index in 0..frame_count {
33        let (draw_count, bone_update_count) = {
34            let frame = runtime.update(delta_seconds)?;
35            (frame.gpu().draws().len(), frame.bone_updates().len())
36        };
37
38        if frame_index % 60 == 0 || !runtime.is_playing() {
39            println!(
40                "time={:.3}s draws={} bone_updates={}",
41                runtime.playback_time().unwrap_or(0.0),
42                draw_count,
43                bone_update_count,
44            );
45        }
46        if !runtime.is_playing() {
47            break;
48        }
49    }
50
51    Ok(())
52}
Source

pub fn from_file<P: AsRef<Path>>(path: P) -> Result<Self, AnimationLoadError>

Loads a VRMA file using strict validation.

Source

pub fn from_bytes(bytes: &[u8]) -> Result<Self, AnimationLoadError>

Parses a GLB/VRMA byte slice using strict validation.

Source

pub fn load_with_options<P: AsRef<Path>>( path: P, options: LoadOptions, ) -> Result<AnimationLoadOutcome, AnimationLoadError>

Loads a VRMA file and returns recoverable diagnostics.

Source

pub fn from_file_with_options<P: AsRef<Path>>( path: P, options: LoadOptions, ) -> Result<AnimationLoadOutcome, AnimationLoadError>

Loads a VRMA file and returns recoverable diagnostics.

Source

pub fn from_bytes_with_options( bytes: &[u8], options: LoadOptions, ) -> Result<AnimationLoadOutcome, AnimationLoadError>

Parses a GLB/VRMA byte slice and returns recoverable diagnostics.

Source

pub fn bone_track(&self, bone: HumanBone) -> Option<&BoneTrack>

Returns the channels assigned to a humanoid bone.

Source

pub fn bone_tracks(&self) -> impl Iterator<Item = (HumanBone, &BoneTrack)>

Iterates over bones that have at least one animation channel.

Source

pub fn expression_track(&self, name: &str) -> Option<&Track<f32>>

Returns an expression weight track.

Source

pub fn expression_tracks(&self) -> impl Iterator<Item = (&str, &Track<f32>)>

Iterates over all expression weight tracks.

Source

pub fn look_at_rotation_track(&self) -> Option<&Track<Quat>>

Returns the LookAt rotation track, if present.

Source

pub fn look_at_offset_from_head_bone(&self) -> Option<Vec3>

Returns the source animation’s LookAt origin offset.

Source

pub fn source_bone_rest_pose( &self, bone: HumanBone, ) -> Option<SourceBoneRestPose>

Returns source T-pose information required for humanoid retargeting.

Source

pub fn source_hips_height(&self) -> Option<f32>

Returns the source Hips height used to scale locomotion across avatars.

Source

pub fn validate(&self) -> Result<(), String>

Validates keyframe ordering and all numeric values before playback.

Source

pub fn sample_look_at_rotation(&self, time: f32) -> Option<Quat>

Samples the LookAt rotation while preserving its glTF interpolation.

Source

pub fn sample_programmatic_bone_rotation_delta( &self, bone: HumanBone, time: f32, ) -> Option<Quat>

Samples a target-local rotation delta from a programmatic clip.

This returns None for loaded VRMA tracks because their rotations are source-local poses that must be retargeted.

Source

pub fn sample_source_bone_rotation( &self, bone: HumanBone, time: f32, ) -> Option<Quat>

Samples the raw local-space rotation stored by a loaded VRMA source.

This returns None for programmatic clips, whose rotations already represent target-local deltas.

Source

pub fn sample_normalized_source_bone_rotation( &self, bone: HumanBone, time: f32, ) -> Option<Quat>

Samples a loaded VRMA source rotation in normalized humanoid space.

Source

pub fn sample_retargeted_source_bone_rotation( &self, bone: HumanBone, time: f32, target_world_rest_rotation: Quat, ) -> Option<Quat>

Converts a normalized source pose into the delta expected by a target avatar whose world rest rotation is supplied by the caller.

Source

pub fn sample_bone_translation_delta( &self, bone: HumanBone, time: f32, ) -> Option<Vec3>

Samples the Hips translation delta while preserving its interpolation.

Source

pub fn sample_expression_weight(&self, name: &str, time: f32) -> f32

Samples an expression weight and clamps it to the VRM range.

Trait Implementations§

Source§

impl Clone for VrmAnimation

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl Debug for VrmAnimation

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
Source§

impl Default for VrmAnimation

Source§

fn default() -> Self

Returns the “default value” for a type. Read more

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.