Skip to main content

vrm_runtime/
runtime.rs

1use std::sync::Arc;
2
3use glam::{Mat4, Quat, Vec3};
4
5use crate::evaluated_material::{EvaluatedMaterial, evaluate_materials};
6use crate::expressions::{MaterialColorUpdate, MorphTargetUpdate, TextureTransformUpdate};
7use crate::instance::{AvatarInstance, BoneUpdate};
8use crate::render::{self, CpuMesh};
9use crate::spring_bone::SpringBoneSimulator;
10use crate::{
11    Avatar, CameraMode, HumanBone, MaterialId, NodeId, PrimitiveId, RenderPrimitive, SkinId,
12    VrmAnimation,
13};
14
15/// Errors caused by invalid persistent controls.
16#[derive(Debug, thiserror::Error, PartialEq)]
17pub enum ControlError {
18    /// The requested expression name is not defined by the asset.
19    #[error("unknown expression `{0}`")]
20    UnknownExpression(String),
21    /// The requested humanoid bone is not mapped by the asset.
22    #[error("humanoid bone `{0:?}` is not mapped by this asset")]
23    MissingBone(HumanBone),
24    /// A control value contains NaN or infinity.
25    #[error("{field} must contain only finite values")]
26    NonFinite {
27        /// The name of the invalid control value.
28        field: &'static str,
29    },
30    /// The animation clip or playback options are invalid.
31    #[error("invalid animation: {0}")]
32    InvalidAnimation(String),
33}
34
35/// Errors produced while evaluating a frame.
36#[derive(Debug, thiserror::Error, PartialEq)]
37pub enum RuntimeError {
38    /// The supplied delta time is negative, NaN, or infinite.
39    #[error("delta time must be finite and non-negative")]
40    InvalidDeltaTime,
41    /// Advancing the material animation clock would overflow to a non-finite value.
42    #[error("material time would become non-finite")]
43    MaterialTimeOverflow,
44    /// Applying the playback speed would make the clip time non-finite.
45    #[error("animation time would become non-finite")]
46    AnimationTimeOverflow,
47}
48
49/// Runtime switches that normally remain unchanged across frames.
50#[derive(Debug, Clone, Copy, PartialEq, Eq)]
51pub struct RuntimeOptions {
52    /// Whether node constraints are evaluated each frame.
53    pub enable_constraints: bool,
54    /// Whether spring-bone simulation is evaluated each frame.
55    pub enable_spring_bone: bool,
56}
57
58impl Default for RuntimeOptions {
59    fn default() -> Self {
60        Self {
61            enable_constraints: true,
62            enable_spring_bone: true,
63        }
64    }
65}
66
67/// Defines what happens when animation time reaches the clip duration.
68#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
69pub enum PlaybackMode {
70    /// Stops on the final frame after one playback.
71    Once,
72    /// Repeats the clip after reaching its duration.
73    #[default]
74    Loop,
75}
76
77/// Persistent animation playback settings.
78#[derive(Debug, Clone, Copy, PartialEq)]
79pub struct PlaybackOptions {
80    /// Playback speed multiplier; must be finite and non-negative.
81    pub speed: f32,
82    /// Behavior when playback reaches the clip duration.
83    pub mode: PlaybackMode,
84    /// Scales loaded VRMA Hips translation by target/source rest-pose height.
85    pub scale_hips_translation: bool,
86}
87
88impl Default for PlaybackOptions {
89    fn default() -> Self {
90        Self {
91            speed: 1.0,
92            mode: PlaybackMode::Loop,
93            scale_hips_translation: true,
94        }
95    }
96}
97
98struct AnimationState {
99    clip: Arc<VrmAnimation>,
100    time: f32,
101    speed: f32,
102    mode: PlaybackMode,
103    scale_hips_translation: bool,
104    playing: bool,
105}
106
107/// Joint matrices for one glTF skin in the current frame.
108#[derive(Debug, Clone, PartialEq)]
109pub struct SkinningPalette {
110    /// Stable identifier of the skin represented by this palette.
111    pub skin_id: SkinId,
112    /// Current joint matrices in the skin's joint order.
113    pub joint_matrices: Vec<Mat4>,
114}
115
116#[derive(Debug, Clone, Default)]
117struct FrameState {
118    world_matrices: Vec<Mat4>,
119    skinning_palettes: Vec<SkinningPalette>,
120    morph_weights: Vec<Vec<f32>>,
121    morph_updates: Vec<MorphTargetUpdate>,
122    material_color_updates: Vec<MaterialColorUpdate>,
123    texture_transform_updates: Vec<TextureTransformUpdate>,
124    evaluated_materials: Vec<EvaluatedMaterial>,
125    bone_updates: Vec<BoneUpdate>,
126}
127
128impl FrameState {
129    fn rest(asset: &Avatar) -> Self {
130        let bone_updates = Vec::new();
131        let world_matrices = asset.compute_world_matrices(&bone_updates);
132        let skinning_palettes = asset
133            .skins()
134            .iter()
135            .enumerate()
136            .map(|(skin_index, skin)| SkinningPalette {
137                skin_id: SkinId::from_index(skin_index),
138                joint_matrices: asset.compute_joint_matrices(skin, &bone_updates),
139            })
140            .collect();
141        // VRMC_vrm's expression update algorithm starts every morph target at
142        // zero, independently of the glTF node/mesh default weights.
143        let morph_weights = asset
144            .primitives()
145            .iter()
146            .map(|primitive| vec![0.0; primitive.morph_targets().len()])
147            .collect();
148        let evaluated_materials = evaluate_materials(asset, &[], &[], 0.0);
149
150        Self {
151            world_matrices,
152            skinning_palettes,
153            morph_weights,
154            evaluated_materials,
155            ..Self::default()
156        }
157    }
158}
159
160/// A high-level VRM instance that owns controls, animation, and simulation.
161pub struct AvatarRuntime {
162    asset: Arc<Avatar>,
163    instance: AvatarInstance,
164    spring_simulator: SpringBoneSimulator,
165    options: RuntimeOptions,
166    animation: Option<AnimationState>,
167    material_time: f32,
168    frame: FrameState,
169}
170
171impl AvatarRuntime {
172    /// Creates an independent runtime from an owned or shared immutable asset.
173    pub fn new(asset: impl Into<Arc<Avatar>>) -> Self {
174        let asset = asset.into();
175        let frame = FrameState::rest(&asset);
176        Self {
177            asset,
178            instance: AvatarInstance::default(),
179            spring_simulator: SpringBoneSimulator::new(),
180            options: RuntimeOptions::default(),
181            animation: None,
182            material_time: 0.0,
183            frame,
184        }
185    }
186
187    /// Returns the immutable avatar asset evaluated by this runtime.
188    pub fn asset(&self) -> &Avatar {
189        &self.asset
190    }
191
192    /// Clones the shared handle to the immutable avatar asset.
193    pub fn shared_asset(&self) -> Arc<Avatar> {
194        Arc::clone(&self.asset)
195    }
196
197    /// Returns the currently active runtime switches.
198    pub fn options(&self) -> RuntimeOptions {
199        self.options
200    }
201
202    /// Enables or disables constraint evaluation for subsequent frames.
203    pub fn set_constraints_enabled(&mut self, enabled: bool) {
204        self.options.enable_constraints = enabled;
205    }
206
207    /// Enables or disables spring-bone simulation for subsequent frames.
208    pub fn set_spring_bone_enabled(&mut self, enabled: bool) {
209        self.options.enable_spring_bone = enabled;
210    }
211
212    /// Sets a persistent expression weight.
213    pub fn set_expression(&mut self, name: &str, weight: f32) -> Result<(), ControlError> {
214        if !weight.is_finite() {
215            return Err(ControlError::NonFinite {
216                field: "expression weight",
217            });
218        }
219        if self.asset.expressions().get(name).is_none() {
220            return Err(ControlError::UnknownExpression(name.to_string()));
221        }
222        self.instance.set_expression(name, weight);
223        Ok(())
224    }
225
226    /// Removes the persistent weight for one expression.
227    pub fn clear_expression(&mut self, name: &str) -> Result<(), ControlError> {
228        if self.asset.expressions().get(name).is_none() {
229            return Err(ControlError::UnknownExpression(name.to_string()));
230        }
231        self.instance.clear_expression(name);
232        Ok(())
233    }
234
235    /// Removes all persistent expression weights.
236    pub fn clear_expressions(&mut self) {
237        self.instance.clear_expressions();
238    }
239
240    /// Returns a persistent expression weight, or zero if it was not set.
241    pub fn expression_weight(&self, name: &str) -> Result<f32, ControlError> {
242        if self.asset.expressions().get(name).is_none() {
243            return Err(ControlError::UnknownExpression(name.to_string()));
244        }
245        Ok(self.instance.expression_weight(name))
246    }
247
248    /// Sets a normalized persistent local-space rotation for a humanoid bone.
249    pub fn set_bone_rotation(
250        &mut self,
251        bone: HumanBone,
252        rotation: Quat,
253    ) -> Result<(), ControlError> {
254        if !rotation.is_finite() {
255            return Err(ControlError::NonFinite {
256                field: "bone rotation",
257            });
258        }
259        if self.asset.humanoid().bone(bone).is_none() {
260            return Err(ControlError::MissingBone(bone));
261        }
262        let normalized = if rotation.length_squared() > f32::EPSILON {
263            rotation.normalize()
264        } else {
265            Quat::IDENTITY
266        };
267        self.instance.set_bone_rotation(bone, normalized);
268        Ok(())
269    }
270
271    /// Removes the persistent rotation override for one humanoid bone.
272    pub fn clear_bone_rotation(&mut self, bone: HumanBone) -> Result<(), ControlError> {
273        if self.asset.humanoid().bone(bone).is_none() {
274            return Err(ControlError::MissingBone(bone));
275        }
276        self.instance.clear_bone_rotation(bone);
277        Ok(())
278    }
279
280    /// Removes all persistent humanoid bone rotation overrides.
281    pub fn clear_bone_rotations(&mut self) {
282        self.instance.clear_bone_rotations();
283    }
284
285    /// Sets a persistent local-space translation for a humanoid bone.
286    pub fn set_bone_translation(
287        &mut self,
288        bone: HumanBone,
289        translation: Vec3,
290    ) -> Result<(), ControlError> {
291        if !translation.is_finite() {
292            return Err(ControlError::NonFinite {
293                field: "bone translation",
294            });
295        }
296        if self.asset.humanoid().bone(bone).is_none() {
297            return Err(ControlError::MissingBone(bone));
298        }
299        self.instance.set_bone_translation(bone, translation);
300        Ok(())
301    }
302
303    /// Removes the persistent translation override for one humanoid bone.
304    pub fn clear_bone_translation(&mut self, bone: HumanBone) -> Result<(), ControlError> {
305        if self.asset.humanoid().bone(bone).is_none() {
306            return Err(ControlError::MissingBone(bone));
307        }
308        self.instance.clear_bone_translation(bone);
309        Ok(())
310    }
311
312    /// Removes all persistent humanoid bone translation overrides.
313    pub fn clear_bone_translations(&mut self) {
314        self.instance.clear_bone_translations();
315    }
316
317    /// Sets the world-space point that the avatar should look toward.
318    pub fn set_look_at_target(&mut self, target: Option<Vec3>) -> Result<(), ControlError> {
319        if target.is_some_and(|target| !target.is_finite()) {
320            return Err(ControlError::NonFinite {
321                field: "look-at target",
322            });
323        }
324        self.instance.set_look_at_target(target);
325        Ok(())
326    }
327
328    /// Removes the persistent look-at target.
329    pub fn clear_look_at_target(&mut self) {
330        self.instance.set_look_at_target(None);
331    }
332
333    /// Validates and starts a clip from time zero.
334    ///
335    /// Loaded VRMA clips are retargeted from their source rest pose to this
336    /// runtime's avatar. [`PlaybackOptions::scale_hips_translation`] controls
337    /// whether Hips motion is scaled by the source and target avatar heights.
338    ///
339    /// # Errors
340    ///
341    /// Returns [`ControlError::InvalidAnimation`] when the clip contains an
342    /// invalid track or when the playback speed is negative or non-finite.
343    pub fn play(
344        &mut self,
345        clip: impl Into<Arc<VrmAnimation>>,
346        options: PlaybackOptions,
347    ) -> Result<(), ControlError> {
348        let clip = clip.into();
349        clip.validate().map_err(ControlError::InvalidAnimation)?;
350        if !options.speed.is_finite() || options.speed < 0.0 {
351            return Err(ControlError::InvalidAnimation(
352                "playback speed must be finite and non-negative".to_string(),
353            ));
354        }
355        self.animation = Some(AnimationState {
356            clip,
357            time: 0.0,
358            speed: options.speed,
359            mode: options.mode,
360            scale_hips_translation: options.scale_hips_translation,
361            playing: true,
362        });
363        Ok(())
364    }
365
366    /// Pauses the current clip without discarding its time.
367    pub fn pause(&mut self) {
368        if let Some(animation) = &mut self.animation {
369            animation.playing = false;
370        }
371    }
372
373    /// Resumes the current clip, if one is loaded.
374    pub fn resume(&mut self) {
375        if let Some(animation) = &mut self.animation {
376            animation.playing = true;
377        }
378    }
379
380    /// Changes playback speed without replacing or rewinding the clip.
381    pub fn set_playback_speed(&mut self, speed: f32) -> Result<(), ControlError> {
382        if !speed.is_finite() || speed < 0.0 {
383            return Err(ControlError::InvalidAnimation(
384                "playback speed must be finite and non-negative".to_string(),
385            ));
386        }
387        if let Some(animation) = &mut self.animation {
388            animation.speed = speed;
389        }
390        Ok(())
391    }
392
393    /// Seeks the current clip to a non-negative time clamped to its duration.
394    pub fn seek(&mut self, time: f32) -> Result<(), ControlError> {
395        if !time.is_finite() || time < 0.0 {
396            return Err(ControlError::NonFinite {
397                field: "animation time",
398            });
399        }
400        if let Some(animation) = &mut self.animation {
401            animation.time = time.min(animation.clip.duration().max(0.0));
402        }
403        Ok(())
404    }
405
406    /// Stops and discards the current animation playback state.
407    pub fn stop(&mut self) {
408        self.animation = None;
409    }
410
411    /// Returns the current clip time, or `None` when no clip is loaded.
412    pub fn playback_time(&self) -> Option<f32> {
413        self.animation.as_ref().map(|animation| animation.time)
414    }
415
416    /// Reports whether a loaded clip is currently advancing.
417    pub fn is_playing(&self) -> bool {
418        self.animation
419            .as_ref()
420            .is_some_and(|animation| animation.playing)
421    }
422
423    /// Evaluates one frame while retaining all persistent controls.
424    ///
425    /// `dt` is elapsed time in seconds. Animation, expressions, LookAt, node
426    /// constraints, SpringBone, world transforms, skinning palettes, and
427    /// dynamic material values are evaluated in their runtime order.
428    ///
429    /// # Errors
430    ///
431    /// Returns [`RuntimeError::InvalidDeltaTime`] for a negative or non-finite
432    /// delta and an overflow variant when a material or animation clock cannot
433    /// advance without becoming non-finite.
434    ///
435    /// Invalid time arithmetic returns an error before either clock or the
436    /// cached frame is mutated.
437    pub fn update(&mut self, dt: f32) -> Result<FrameView<'_>, RuntimeError> {
438        if !dt.is_finite() || dt < 0.0 {
439            return Err(RuntimeError::InvalidDeltaTime);
440        }
441
442        let next_material_time = self.material_time + dt;
443        if !next_material_time.is_finite() {
444            return Err(RuntimeError::MaterialTimeOverflow);
445        }
446
447        let next_animation_time = if let Some(animation) = &self.animation
448            && animation.playing
449        {
450            let advance = dt * animation.speed;
451            let next_time = animation.time + advance;
452            if !advance.is_finite() || !next_time.is_finite() {
453                return Err(RuntimeError::AnimationTimeOverflow);
454            }
455            Some(next_time)
456        } else {
457            None
458        };
459
460        // Commit both clocks only after every time calculation succeeds so an
461        // overflow error leaves the entire runtime at its previous frame.
462        self.material_time = next_material_time;
463
464        if let Some(animation) = &mut self.animation
465            && let Some(next_time) = next_animation_time
466        {
467            animation.time = next_time;
468            if animation.clip.duration() <= 0.0 {
469                animation.time = 0.0;
470                if animation.mode == PlaybackMode::Once {
471                    animation.playing = false;
472                }
473            } else if animation.time >= animation.clip.duration() {
474                match animation.mode {
475                    PlaybackMode::Loop => animation.time %= animation.clip.duration(),
476                    PlaybackMode::Once => {
477                        animation.time = animation.clip.duration();
478                        animation.playing = false;
479                    }
480                }
481            }
482        }
483
484        let mut frame_instance = AvatarInstance::default();
485        if let Some(animation) = &self.animation {
486            frame_instance.apply_animation_with_options(
487                &animation.clip,
488                animation.time,
489                &self.asset,
490                animation.scale_hips_translation,
491            );
492        }
493        frame_instance.overlay(&self.instance);
494        let evaluation = frame_instance.evaluate(&self.asset);
495        let mut bone_updates = evaluation.bone_updates;
496
497        if self.options.enable_constraints {
498            let world = self.asset.compute_world_matrices(&bone_updates);
499            bone_updates.extend(crate::constraint::solve_constraints(&self.asset, &world));
500        }
501
502        if self.options.enable_spring_bone {
503            let world = self.asset.compute_world_matrices(&bone_updates);
504            bone_updates.extend(self.spring_simulator.update(&self.asset, &world, dt));
505        }
506
507        let world_matrices = self.asset.compute_world_matrices(&bone_updates);
508        let skinning_palettes = self
509            .asset
510            .skins()
511            .iter()
512            .enumerate()
513            .map(|(skin_index, skin)| SkinningPalette {
514                skin_id: SkinId::from_index(skin_index),
515                joint_matrices: self.asset.compute_joint_matrices(skin, &bone_updates),
516            })
517            .collect();
518
519        // Reinitialize from zero on every frame before accumulating expression
520        // binds, as required by the VRM expression update algorithm.
521        let mut morph_weights: Vec<Vec<f32>> = self
522            .asset
523            .primitives()
524            .iter()
525            .map(|primitive| vec![0.0; primitive.morph_targets().len()])
526            .collect();
527        for update in &evaluation.morph_updates {
528            for (primitive_index, primitive) in self.asset.primitives().iter().enumerate() {
529                if primitive.node_index() != update.node_index() {
530                    continue;
531                }
532                if let Some(weight) =
533                    morph_weights[primitive_index].get_mut(update.target_index() as usize)
534                {
535                    *weight = update.weight();
536                }
537            }
538        }
539        let evaluated_materials = evaluate_materials(
540            &self.asset,
541            &evaluation.material_color_updates,
542            &evaluation.texture_transform_updates,
543            self.material_time,
544        );
545
546        self.frame = FrameState {
547            world_matrices,
548            skinning_palettes,
549            morph_weights,
550            morph_updates: evaluation.morph_updates,
551            material_color_updates: evaluation.material_color_updates,
552            texture_transform_updates: evaluation.texture_transform_updates,
553            evaluated_materials,
554            bone_updates,
555        };
556
557        Ok(FrameView {
558            asset: &self.asset,
559            state: &self.frame,
560        })
561    }
562
563    /// Resets controls, simulation, and all cached output to the rest state.
564    pub fn reset(&mut self) {
565        self.instance = AvatarInstance::default();
566        self.spring_simulator.reset();
567        self.animation = None;
568        self.material_time = 0.0;
569        self.frame = FrameState::rest(&self.asset);
570    }
571
572    /// Provides mutable low-level state for custom evaluation pipelines.
573    pub fn instance_mut(&mut self) -> &mut AvatarInstance {
574        &mut self.instance
575    }
576
577    /// Provides mutable access to the spring simulator for advanced use.
578    pub fn spring_simulator_mut(&mut self) -> &mut SpringBoneSimulator {
579        &mut self.spring_simulator
580    }
581}
582
583/// A zero-copy view of the most recently evaluated frame.
584#[derive(Clone, Copy)]
585pub struct FrameView<'a> {
586    asset: &'a Arc<Avatar>,
587    state: &'a FrameState,
588}
589
590impl<'a> FrameView<'a> {
591    /// Returns GPU-oriented draw data without copying frame buffers.
592    ///
593    /// Each [`GpuDraw`] combines immutable primitive attributes with the
594    /// current world matrix, morph weights, joint matrices, and evaluated
595    /// material data required by a renderer.
596    pub fn gpu(self) -> GpuFrameView<'a> {
597        GpuFrameView {
598            asset: self.asset.as_ref(),
599            state: self.state,
600        }
601    }
602
603    /// Applies morphing, skinning, and world transforms on the CPU.
604    ///
605    /// The returned [`CpuMesh`] values contain world-space vertices and can be
606    /// rendered without morph-target or skinning shader stages.
607    pub fn bake_cpu(self) -> Vec<CpuMesh> {
608        render::bake_frame(
609            self.asset,
610            &self.state.world_matrices,
611            &self.state.skinning_palettes,
612            &self.state.morph_weights,
613        )
614    }
615
616    /// Bakes CPU meshes with VRM first-person visibility already applied.
617    pub fn bake_cpu_for(self, camera: CameraMode) -> Vec<CpuMesh> {
618        apply_camera_visibility(self.asset, self.bake_cpu(), camera)
619    }
620
621    /// Clones this frame into an independently owned snapshot.
622    pub fn to_owned(self) -> FrameSnapshot {
623        FrameSnapshot {
624            asset: Arc::clone(self.asset),
625            state: self.state.clone(),
626        }
627    }
628
629    /// Returns current world matrices in avatar node order.
630    pub fn world_matrices(self) -> &'a [Mat4] {
631        &self.state.world_matrices
632    }
633
634    /// Returns current joint-matrix palettes in skin order.
635    pub fn skinning_palettes(self) -> &'a [SkinningPalette] {
636        &self.state.skinning_palettes
637    }
638
639    /// Returns expression-produced morph target updates.
640    pub fn morph_updates(self) -> &'a [MorphTargetUpdate] {
641        &self.state.morph_updates
642    }
643
644    /// Returns expression-produced material color updates.
645    pub fn material_color_updates(self) -> &'a [MaterialColorUpdate] {
646        &self.state.material_color_updates
647    }
648
649    /// Returns expression-produced texture transform updates.
650    pub fn texture_transform_updates(self) -> &'a [TextureTransformUpdate] {
651        &self.state.texture_transform_updates
652    }
653
654    /// Returns renderer-ready dynamic values for every material in the asset.
655    pub fn evaluated_materials(self) -> &'a [EvaluatedMaterial] {
656        &self.state.evaluated_materials
657    }
658
659    /// Resolves one renderer-ready material value by its stable identifier.
660    pub fn evaluated_material(self, id: MaterialId) -> Option<&'a EvaluatedMaterial> {
661        self.state.evaluated_materials.get(id.index())
662    }
663
664    /// Returns local humanoid bone updates applied to this frame.
665    pub fn bone_updates(self) -> &'a [BoneUpdate] {
666        &self.state.bone_updates
667    }
668}
669
670/// An owned frame that can be queued or moved to another thread.
671#[derive(Debug, Clone)]
672pub struct FrameSnapshot {
673    asset: Arc<Avatar>,
674    state: FrameState,
675}
676
677impl FrameSnapshot {
678    /// Returns GPU-oriented draw data borrowed from this snapshot.
679    pub fn gpu(&self) -> GpuFrameView<'_> {
680        GpuFrameView {
681            asset: &self.asset,
682            state: &self.state,
683        }
684    }
685
686    /// Applies morphing and skinning on the CPU for every primitive.
687    pub fn bake_cpu(&self) -> Vec<CpuMesh> {
688        render::bake_frame(
689            &self.asset,
690            &self.state.world_matrices,
691            &self.state.skinning_palettes,
692            &self.state.morph_weights,
693        )
694    }
695
696    /// Bakes CPU meshes with VRM first-person visibility already applied.
697    pub fn bake_cpu_for(&self, camera: CameraMode) -> Vec<CpuMesh> {
698        apply_camera_visibility(&self.asset, self.bake_cpu(), camera)
699    }
700
701    /// Returns current world matrices in avatar node order.
702    pub fn world_matrices(&self) -> &[Mat4] {
703        &self.state.world_matrices
704    }
705
706    /// Returns current joint-matrix palettes in skin order.
707    pub fn skinning_palettes(&self) -> &[SkinningPalette] {
708        &self.state.skinning_palettes
709    }
710
711    /// Returns expression-produced morph target updates.
712    pub fn morph_updates(&self) -> &[MorphTargetUpdate] {
713        &self.state.morph_updates
714    }
715
716    /// Returns expression-produced material color updates.
717    pub fn material_color_updates(&self) -> &[MaterialColorUpdate] {
718        &self.state.material_color_updates
719    }
720
721    /// Returns expression-produced texture transform updates.
722    pub fn texture_transform_updates(&self) -> &[TextureTransformUpdate] {
723        &self.state.texture_transform_updates
724    }
725
726    /// Returns renderer-ready dynamic values for every material in the asset.
727    pub fn evaluated_materials(&self) -> &[EvaluatedMaterial] {
728        &self.state.evaluated_materials
729    }
730
731    /// Resolves one renderer-ready material value by its stable identifier.
732    pub fn evaluated_material(&self, id: MaterialId) -> Option<&EvaluatedMaterial> {
733        self.state.evaluated_materials.get(id.index())
734    }
735
736    /// Returns local humanoid bone updates applied to this frame.
737    pub fn bone_updates(&self) -> &[BoneUpdate] {
738        &self.state.bone_updates
739    }
740}
741
742/// GPU-oriented access to static primitive buffers and dynamic frame data.
743#[derive(Clone, Copy)]
744pub struct GpuFrameView<'a> {
745    asset: &'a Avatar,
746    state: &'a FrameState,
747}
748
749impl<'a> GpuFrameView<'a> {
750    /// Iterates over renderer-ready draw records for every primitive.
751    pub fn draws(self) -> impl ExactSizeIterator<Item = GpuDraw<'a>> + 'a {
752        self.asset
753            .primitives()
754            .iter()
755            .enumerate()
756            .map(move |(primitive_index, primitive)| {
757                let skin_id = primitive.skin_index().map(SkinId::from_index);
758                let material_id = primitive.material_index().map(MaterialId::from_index);
759                let joint_matrices = skin_id
760                    .and_then(|skin_id| self.state.skinning_palettes.get(skin_id.index()))
761                    .map(|palette| palette.joint_matrices.as_slice())
762                    .unwrap_or(&[]);
763                GpuDraw {
764                    asset: self.asset,
765                    primitive_id: PrimitiveId::from_index(primitive_index),
766                    node_id: NodeId::from_index(primitive.node_index() as usize),
767                    material_id,
768                    evaluated_material: material_id
769                        .and_then(|id| self.state.evaluated_materials.get(id.index())),
770                    skin_id,
771                    primitive,
772                    world_matrix: self
773                        .state
774                        .world_matrices
775                        .get(primitive.node_index() as usize)
776                        .copied()
777                        .unwrap_or(Mat4::IDENTITY),
778                    morph_weights: self
779                        .state
780                        .morph_weights
781                        .get(primitive_index)
782                        .map(Vec::as_slice)
783                        .unwrap_or(&[]),
784                    joint_matrices,
785                }
786            })
787    }
788}
789
790/// One GPU draw with stable asset identifiers and frame-local values.
791pub struct GpuDraw<'a> {
792    asset: &'a Avatar,
793    /// Stable identifier of the source primitive.
794    pub primitive_id: PrimitiveId,
795    /// Stable identifier of the node that instantiates the primitive.
796    pub node_id: NodeId,
797    /// Stable identifier of the primitive material, if present.
798    pub material_id: Option<MaterialId>,
799    /// Dynamic material values matching `material_id`, when the draw has one.
800    pub evaluated_material: Option<&'a EvaluatedMaterial>,
801    /// Stable identifier of the skin used by the draw, if present.
802    pub skin_id: Option<SkinId>,
803    /// Immutable geometry and attribute data for the draw.
804    pub primitive: &'a RenderPrimitive,
805    /// Current world transform of the primitive node.
806    ///
807    /// Apply this matrix to unskinned primitives. [`Self::joint_matrices`]
808    /// already produce world-space output for skinned primitives, so applying
809    /// both would transform those vertices twice.
810    pub world_matrix: Mat4,
811    /// Current morph weights in the order of [`RenderPrimitive::morph_targets`].
812    pub morph_weights: &'a [f32],
813    /// Current world-space joint matrices in the selected [`crate::Skin`] joint order.
814    ///
815    /// The slice is empty for an unskinned draw. A shader indexes it through
816    /// every consecutive `JOINTS_n` / `WEIGHTS_n` set on [`Self::primitive`].
817    pub joint_matrices: &'a [Mat4],
818}
819
820impl<'a> GpuDraw<'a> {
821    /// Returns the source indices visible to the selected camera.
822    pub fn indices(&self, camera: CameraMode) -> std::borrow::Cow<'a, [u32]> {
823        self.asset
824            .first_person()
825            .visible_indices(self.asset, self.primitive, camera)
826    }
827}
828
829fn apply_camera_visibility(
830    asset: &Avatar,
831    meshes: Vec<CpuMesh>,
832    camera: CameraMode,
833) -> Vec<CpuMesh> {
834    meshes
835        .into_iter()
836        .enumerate()
837        .filter_map(|(index, mut mesh)| {
838            let primitive = asset.primitives().get(index)?;
839            mesh.indices = asset
840                .first_person()
841                .visible_indices(asset, primitive, camera)
842                .into_owned();
843            (!mesh.indices.is_empty()).then_some(mesh)
844        })
845        .collect()
846}
847
848#[cfg(test)]
849mod tests {
850    use super::*;
851    use crate::primitive::{PrimitiveTopology, RenderPrimitive};
852    use crate::{
853        Avatar, AvatarNode, BoneTrack, Expression, Expressions, Humanoid, Interpolation, Keyframe,
854        Material, MaterialColorBind, MaterialColorType, MorphTarget, MorphTargetBind,
855        TextureTransformBind, Track, Transform,
856    };
857
858    fn test_asset() -> Avatar {
859        let expression =
860            Expression::new("happy").with_morph_target_binds(vec![MorphTargetBind::new(0, 0, 1.0)]);
861        let primitive = RenderPrimitive::new(
862            0,
863            Transform::IDENTITY,
864            vec![[0.0, 0.0, 0.0]],
865            vec![[0.0, 0.0, 1.0]],
866            vec![0],
867            vec![[0; 4]],
868            vec![[0.0; 4]],
869            vec![MorphTarget::new(vec![[1.0, 0.0, 0.0]], None, None)],
870            vec![[0.0, 0.0]],
871            vec![[1.0, 0.0, 0.0, 1.0]],
872            vec![[1.0; 4]],
873            vec![[0.0, 0.0]],
874            None,
875            None,
876            PrimitiveTopology::Triangles,
877            vec![0.75],
878            false,
879            None,
880            0,
881        );
882        Avatar::new()
883            .with_expressions(Expressions::new(vec![expression]))
884            .with_primitives(vec![primitive])
885    }
886
887    #[test]
888    fn expression_controls_persist_between_updates() {
889        let mut runtime = AvatarRuntime::new(test_asset());
890        runtime.set_constraints_enabled(false);
891        runtime.set_spring_bone_enabled(false);
892        runtime.set_expression("happy", 0.5).unwrap();
893
894        let first = runtime.update(0.016).unwrap().gpu().draws().next().unwrap();
895        assert_eq!(first.morph_weights, &[0.5]);
896        let second = runtime.update(0.016).unwrap().gpu().draws().next().unwrap();
897        assert_eq!(second.morph_weights, &[0.5]);
898    }
899
900    #[test]
901    fn expression_morphs_start_at_zero_instead_of_gltf_weights() {
902        let mut runtime = AvatarRuntime::new(test_asset());
903        runtime.set_constraints_enabled(false);
904        runtime.set_spring_bone_enabled(false);
905        runtime.set_expression("happy", 0.25).unwrap();
906
907        let draw = runtime.update(0.0).unwrap().gpu().draws().next().unwrap();
908        assert_eq!(draw.morph_weights, &[0.25]);
909    }
910
911    #[test]
912    fn frame_exposes_expression_evaluated_material_values() {
913        let expression = Expression::new("happy")
914            .with_material_color_binds(vec![MaterialColorBind {
915                material_index: 0,
916                color_type: MaterialColorType::Color,
917                target_value: [1.0, 0.0, 0.0, 0.5],
918            }])
919            .with_texture_transform_binds(vec![TextureTransformBind {
920                material_index: 0,
921                scale: [2.0, 3.0],
922                offset: [0.25, 0.5],
923            }]);
924        let mut material = Material::default();
925        material.base_color_factor = [0.2, 0.4, 0.6, 1.0];
926        let mut asset = Avatar::new().with_expressions(Expressions::new(vec![expression]));
927        asset.materials = vec![material];
928        let mut runtime = AvatarRuntime::new(asset);
929        runtime.set_expression("happy", 0.5).unwrap();
930
931        let frame = runtime.update(0.0).unwrap();
932        let evaluated = &frame.evaluated_materials()[0];
933
934        assert_eq!(evaluated.material_id, MaterialId::from_index(0));
935        assert_eq!(evaluated.base_color_factor, [0.6, 0.2, 0.3, 0.75]);
936        assert_eq!(evaluated.texture_transform.scale, [1.5, 2.0]);
937        assert_eq!(evaluated.texture_transform.offset, [0.125, 0.25]);
938    }
939
940    #[test]
941    fn cpu_and_gpu_paths_use_the_same_morph_weights() {
942        let mut runtime = AvatarRuntime::new(test_asset());
943        runtime.set_constraints_enabled(false);
944        runtime.set_spring_bone_enabled(false);
945        runtime.set_expression("happy", 1.0).unwrap();
946
947        let frame = runtime.update(0.0).unwrap();
948        let draw = frame.gpu().draws().next().unwrap();
949        let mesh = frame.bake_cpu().pop().unwrap();
950        assert_eq!(draw.morph_weights, &[1.0]);
951        assert_eq!(mesh.positions[0], [1.0, 0.0, 0.0]);
952    }
953
954    #[test]
955    fn reset_clears_controls_and_cached_morphs() {
956        let mut runtime = AvatarRuntime::new(test_asset());
957        runtime.set_expression("happy", 1.0).unwrap();
958        runtime.update(0.0).unwrap();
959        runtime.reset();
960
961        assert_eq!(runtime.expression_weight("happy").unwrap(), 0.0);
962        let draw = runtime.update(0.0).unwrap().gpu().draws().next().unwrap();
963        assert_eq!(draw.morph_weights, &[0.0]);
964    }
965
966    #[test]
967    fn shared_asset_does_not_share_instance_state() {
968        let asset = Arc::new(test_asset());
969        let mut first = AvatarRuntime::new(Arc::clone(&asset));
970        let mut second = AvatarRuntime::new(asset);
971        first.set_expression("happy", 1.0).unwrap();
972
973        let first_weight = first
974            .update(0.0)
975            .unwrap()
976            .gpu()
977            .draws()
978            .next()
979            .unwrap()
980            .morph_weights[0];
981        let second_weight = second
982            .update(0.0)
983            .unwrap()
984            .gpu()
985            .draws()
986            .next()
987            .unwrap()
988            .morph_weights[0];
989        assert_eq!(first_weight, 1.0);
990        assert_eq!(second_weight, 0.0);
991    }
992
993    #[test]
994    fn rejects_invalid_runtime_inputs() {
995        let mut runtime = AvatarRuntime::new(test_asset());
996        assert!(matches!(
997            runtime.set_expression("missing", 1.0),
998            Err(ControlError::UnknownExpression(_))
999        ));
1000        assert_eq!(
1001            runtime.update(f32::NAN).err(),
1002            Some(RuntimeError::InvalidDeltaTime)
1003        );
1004    }
1005
1006    #[test]
1007    fn rejects_material_clock_overflow_without_mutating_time() {
1008        let mut runtime = AvatarRuntime::new(test_asset());
1009        runtime.set_constraints_enabled(false);
1010        runtime.set_spring_bone_enabled(false);
1011
1012        runtime.update(f32::MAX).unwrap();
1013        let material_time_before_error = runtime.material_time;
1014
1015        assert_eq!(
1016            runtime.update(f32::MAX).err(),
1017            Some(RuntimeError::MaterialTimeOverflow)
1018        );
1019        assert_eq!(runtime.material_time, material_time_before_error);
1020        assert!(runtime.material_time.is_finite());
1021    }
1022
1023    #[test]
1024    fn rejects_animation_step_overflow_without_mutating_any_clock() {
1025        let mut runtime = AvatarRuntime::new(test_asset());
1026        runtime.set_constraints_enabled(false);
1027        runtime.set_spring_bone_enabled(false);
1028        runtime
1029            .play(
1030                VrmAnimation::new(f32::MAX),
1031                PlaybackOptions {
1032                    speed: f32::MAX,
1033                    ..PlaybackOptions::default()
1034                },
1035            )
1036            .unwrap();
1037
1038        assert_eq!(
1039            runtime.update(2.0).err(),
1040            Some(RuntimeError::AnimationTimeOverflow)
1041        );
1042        assert_eq!(runtime.playback_time(), Some(0.0));
1043        assert_eq!(runtime.material_time, 0.0);
1044    }
1045
1046    #[test]
1047    fn update_advances_animation_before_producing_the_frame() {
1048        let asset = Avatar::new()
1049            .with_humanoid(Humanoid::default().with_bone(HumanBone::Hips, 0))
1050            .with_nodes(vec![AvatarNode {
1051                index: 0,
1052                name: Some("hips".to_string()),
1053                parent: None,
1054                children: vec![],
1055                initial_translation: Vec3::ZERO,
1056                initial_rotation: Quat::IDENTITY,
1057                initial_scale: Vec3::ONE,
1058            }]);
1059        let clip = VrmAnimation::new(1.0).with_bone_track(
1060            HumanBone::Hips,
1061            BoneTrack::new().with_translation(Track::new(
1062                Interpolation::Linear,
1063                vec![
1064                    Keyframe::new(0.0, Vec3::ZERO),
1065                    Keyframe::new(1.0, Vec3::new(2.0, 0.0, 0.0)),
1066                ],
1067            )),
1068        );
1069        let mut runtime = AvatarRuntime::new(asset);
1070        runtime.set_constraints_enabled(false);
1071        runtime.set_spring_bone_enabled(false);
1072        runtime
1073            .play(
1074                clip,
1075                PlaybackOptions {
1076                    speed: 1.0,
1077                    mode: PlaybackMode::Once,
1078                    ..PlaybackOptions::default()
1079                },
1080            )
1081            .unwrap();
1082
1083        let frame = runtime.update(0.5).unwrap();
1084        let translation = frame.world_matrices()[0].transform_point3(Vec3::ZERO);
1085
1086        assert!(translation.abs_diff_eq(Vec3::new(1.0, 0.0, 0.0), 1.0e-5));
1087        assert_eq!(runtime.playback_time(), Some(0.5));
1088        assert!(runtime.is_playing());
1089    }
1090
1091    #[test]
1092    fn play_rejects_malformed_keyframes() {
1093        let clip = VrmAnimation::new(1.0).with_bone_track(
1094            HumanBone::Hips,
1095            BoneTrack::new().with_rotation(Track::new(
1096                Interpolation::Linear,
1097                vec![Keyframe::new(f32::NAN, Quat::IDENTITY)],
1098            )),
1099        );
1100        let mut runtime = AvatarRuntime::new(test_asset());
1101
1102        assert!(matches!(
1103            runtime.play(clip, PlaybackOptions::default()),
1104            Err(ControlError::InvalidAnimation(_))
1105        ));
1106    }
1107}