From 0824add179bfc3f1687aae2b38c5aeb52e84932e Mon Sep 17 00:00:00 2001 From: Patrick Walton Date: Thu, 26 Sep 2024 23:31:48 -0700 Subject: [PATCH] Impose a more sensible ordering for animation graph evaluation. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This commit changes the animation graph evaluation to be operate in a more sensible order and updates the semantics of blend nodes to conform to [the animation composition RFC]. Prior to this patch, a node graph like this: ┌─────┐ │ │ │ 1 │ │ │ └──┬──┘ │ ┌───────┴───────┐ │ │ ▼ ▼ ┌─────┐ ┌─────┐ │ │ │ │ │ 2 │ │ 3 │ │ │ │ │ └──┬──┘ └──┬──┘ │ │ ┌───┴───┐ ┌───┴───┐ │ │ │ │ ▼ ▼ ▼ ▼ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ │ │ │ │ │ │ │ │ │ 4 │ │ 6 │ │ 5 │ │ 7 │ │ │ │ │ │ │ │ │ └─────┘ └─────┘ └─────┘ └─────┘ Would be evaluated as (((4 ⊕ 5) ⊕ 6) ⊕ 7), with the blend (lerp/slerp) operation notated as ⊕. As quaternion multiplication isn't commutative, this is very counterintuitive and will especially lead to trouble with the forthcoming additive blending feature (#15198). This patch fixes the issue by changing the evaluation order to postorder, with children of a node evaluated in ascending order by node index. To do so, this patch revamps `Keyframes` to be based on an *evaluation stack* and a *blend register*. During target evaluation, the graph evaluator traverses the graph in postorder. When encountering a clip node, the evaluator pushes the possibly-interpolated value onto the evaluation stack. When encountering a blend node, the evaluator pops values off the stack into the blend register, accumulating weights as appropriate. When the graph is completely evaluated, the top element on the stack is *committed* to the property of the component. A new system, the *graph threading* system, is added in order to cache the sorted postorder traversal to avoid the overhead of sorting children at animation evaluation time. Mask evaluation has been moved to this system so that the graph only has to be traversed at most once per frame. Unlike the `ActiveAnimation` list, the *threaded graph* is cached from frame to frame and only has to be regenerated when the animation graph asset changes. This patch currently regresses the `animate_target` performance in `many_foxes` by around 50%, resulting in an FPS loss of about 2-3 FPS. I'd argue that this is an acceptable price to pay for a much more intuitive system. In the future, we can mitigate the regression with a fast path that avoids consulting the graph if only one animation is playing. However, in the interest of keeping this patch simple, I didn't do so here. [the animation composition RFC]: https://github.com/bevyengine/rfcs/blob/main/rfcs/51-animation-composition.md --- crates/bevy_animation/Cargo.toml | 1 + crates/bevy_animation/src/animatable.rs | 8 +- crates/bevy_animation/src/graph.rs | 216 +++++- crates/bevy_animation/src/keyframes.rs | 863 +++++++++++++++++++----- crates/bevy_animation/src/lib.rs | 371 +++++----- crates/bevy_gltf/src/loader.rs | 3 +- examples/animation/animation_graph.rs | 14 +- 7 files changed, 1140 insertions(+), 336 deletions(-) diff --git a/crates/bevy_animation/Cargo.toml b/crates/bevy_animation/Cargo.toml index ae1e8ee23cdc9..a773973aa5fc4 100644 --- a/crates/bevy_animation/Cargo.toml +++ b/crates/bevy_animation/Cargo.toml @@ -41,6 +41,7 @@ blake3 = { version = "1.0" } thiserror = "1" thread_local = "1" uuid = { version = "1.7", features = ["v4"] } +smallvec = "1" [lints] workspace = true diff --git a/crates/bevy_animation/src/animatable.rs b/crates/bevy_animation/src/animatable.rs index 1a0cce53bfeec..29316df50d72f 100644 --- a/crates/bevy_animation/src/animatable.rs +++ b/crates/bevy_animation/src/animatable.rs @@ -206,14 +206,12 @@ pub(crate) trait GetKeyframe { /// This is factored out so that it can be shared between implementations of /// [`crate::keyframes::Keyframes`]. pub(crate) fn interpolate_keyframes( - dest: &mut T, keyframes: &(impl GetKeyframe + ?Sized), interpolation: Interpolation, step_start: usize, time: f32, - weight: f32, duration: f32, -) -> Result<(), AnimationEvaluationError> +) -> Result where T: Animatable + Clone, { @@ -265,9 +263,7 @@ where } }; - *dest = T::interpolate(dest, &value, weight); - - Ok(()) + Ok(value) } /// Evaluates a cubic Bézier curve at a value `t`, given two endpoints and the diff --git a/crates/bevy_animation/src/graph.rs b/crates/bevy_animation/src/graph.rs index 1ce683409a3f9..855a91c3aa117 100644 --- a/crates/bevy_animation/src/graph.rs +++ b/crates/bevy_animation/src/graph.rs @@ -1,14 +1,25 @@ //! The animation graph, which allows animations to be blended together. -use core::ops::{Index, IndexMut}; +use core::iter; +use core::ops::{Index, IndexMut, Range}; use std::io::{self, Write}; -use bevy_asset::{io::Reader, Asset, AssetId, AssetLoader, AssetPath, Handle, LoadContext}; +use bevy_asset::{ + io::Reader, Asset, AssetEvent, AssetId, AssetLoader, AssetPath, Assets, Handle, LoadContext, +}; +use bevy_ecs::{ + event::EventReader, + system::{Res, ResMut, Resource}, +}; use bevy_reflect::{Reflect, ReflectSerialize}; use bevy_utils::HashMap; -use petgraph::graph::{DiGraph, NodeIndex}; +use petgraph::{ + graph::{DiGraph, NodeIndex}, + Direction, +}; use ron::de::SpannedError; use serde::{Deserialize, Serialize}; +use smallvec::SmallVec; use thiserror::Error; use crate::{AnimationClip, AnimationTargetId}; @@ -172,6 +183,96 @@ pub enum AnimationGraphLoadError { SpannedRon(#[from] SpannedError), } +/// Acceleration structures for animation graphs that allows Bevy to evaluate +/// them quickly. +/// +/// These are kept up to date as [`AnimationGraph`] instances are added, +/// modified, and removed. +#[derive(Default, Reflect, Resource)] +pub struct ThreadedAnimationGraphs( + pub(crate) HashMap, ThreadedAnimationGraph>, +); + +/// An acceleration structure for an animation graph that allows Bevy to +/// evaluate it quickly. +/// +/// This is kept up to date as the associated [`AnimationGraph`] instance is +/// added, modified, or removed. +#[derive(Default, Reflect)] +pub(crate) struct ThreadedAnimationGraph { + /// A cached postorder traversal of the graph. + /// + /// The node indices here are stored in postorder. Siblings are stored in + /// descending order. This is because the [`KeyframeEvaluator`] uses a stack + /// for evaluation. Consider this graph: + /// + /// ┌─────┐ + /// │ │ + /// │ 1 │ + /// │ │ + /// └──┬──┘ + /// │ + /// ┌───────┼───────┐ + /// │ │ │ + /// ▼ ▼ ▼ + /// ┌─────┐ ┌─────┐ ┌─────┐ + /// │ │ │ │ │ │ + /// │ 2 │ │ 3 │ │ 4 │ + /// │ │ │ │ │ │ + /// └──┬──┘ └─────┘ └─────┘ + /// │ + /// ┌───┴───┐ + /// │ │ + /// ▼ ▼ + /// ┌─────┐ ┌─────┐ + /// │ │ │ │ + /// │ 5 │ │ 6 │ + /// │ │ │ │ + /// └─────┘ └─────┘ + /// + /// The postorder traversal in this case will be (4, 3, 6, 5, 2, 1). + /// + /// The fact that the children of each node are sorted in reverse ensures + /// that, at each level, the order of blending proceeds in ascending order + /// by node index, as we guarantee. To illustrate this, consider the way + /// the graph above is evaluated. (Interpolation is represented with the ⊕ + /// symbol.) + /// + /// | Step | Node | Operation | Stack (after operation) | Blend Register | + /// | ---- | -----| ---------- | ----------------------- | -------------- | + /// | 1 | 4 | Push | 4 | | + /// | 2 | 3 | Push | 4 3 | | + /// | 3 | 6 | Push | 4 3 6 | | + /// | 4 | 5 | Push | 4 3 6 5 | | + /// | 5 | 2 | Blend 5 | 4 3 6 | 5 | + /// | 6 | 2 | Blend 6 | 4 3 | 5 ⊕ 6 | + /// | 7 | 2 | Push Blend | 4 3 2 | | + /// | 8 | 1 | Blend 2 | 4 3 | 2 | + /// | 9 | 1 | Blend 3 | 4 | 2 ⊕ 3 | + /// | 10 | 1 | Blend 4 | | 2 ⊕ 3 ⊕ 4 | + /// | 11 | 1 | Push Blend | 1 | | + /// | 12 | | Commit | | | + pub(crate) threaded_graph: Vec, + + /// A mapping from each parent node index to the range within + /// [`Self::sorted_edges`]. + /// + /// This allows for quick lookup of the children of each node, sorted in + /// ascending order of node index, without having to sort the result of the + /// `petgraph` traversal functions every frame. + pub(crate) sorted_edge_ranges: Vec>, + + /// A list of the children of each node, sorted in ascending order. + pub(crate) sorted_edges: Vec, + + /// A mapping from node index to a bitfield specifying the mask groups that + /// this node masks *out* (i.e. doesn't animate). + /// + /// A 1 in bit position N indicates that this node doesn't animate any + /// targets of mask group N. + pub(crate) computed_masks: Vec, +} + /// A version of [`AnimationGraph`] suitable for serializing as an asset. /// /// Animation nodes can refer to external animation clips, and the [`AssetId`] @@ -571,3 +672,112 @@ impl From for SerializedAnimationGraph { } } } + +/// A system that creates, updates, and removes [`ThreadedAnimationGraph`] +/// structures for every changed [`AnimationGraph`]. +/// +/// The [`ThreadedAnimationGraph`] contains acceleration structures that allow +/// for quick evaluation of that graph's animations. +pub(crate) fn thread_animation_graphs( + mut threaded_animation_graphs: ResMut, + animation_graphs: Res>, + mut animation_graph_asset_events: EventReader>, +) { + for animation_graph_asset_event in animation_graph_asset_events.read() { + match *animation_graph_asset_event { + AssetEvent::Added { id } + | AssetEvent::Modified { id } + | AssetEvent::LoadedWithDependencies { id } => { + // Fetch the animation graph. + let Some(animation_graph) = animation_graphs.get(id) else { + continue; + }; + + // Reuse the allocation if possible. + let mut threaded_animation_graph = + threaded_animation_graphs.0.remove(&id).unwrap_or_default(); + threaded_animation_graph.clear(); + + // Recursively thread the graph in postorder. + threaded_animation_graph.init(animation_graph); + threaded_animation_graph.build_from( + &animation_graph.graph, + animation_graph.root, + 0, + ); + + // Write in the threaded graph. + threaded_animation_graphs + .0 + .insert(id, threaded_animation_graph); + } + + AssetEvent::Removed { id } => { + threaded_animation_graphs.0.remove(&id); + } + AssetEvent::Unused { .. } => {} + } + } +} + +impl ThreadedAnimationGraph { + /// Removes all the data in this [`ThreadedAnimationGraph`], keeping the + /// memory around for later reuse. + fn clear(&mut self) { + self.threaded_graph.clear(); + self.sorted_edge_ranges.clear(); + self.sorted_edges.clear(); + } + + /// Prepares the [`ThreadedAnimationGraph`] for recursion. + fn init(&mut self, animation_graph: &AnimationGraph) { + let node_count = animation_graph.graph.node_count(); + let edge_count = animation_graph.graph.edge_count(); + + self.threaded_graph.reserve(node_count); + self.sorted_edges.reserve(edge_count); + + self.sorted_edge_ranges.clear(); + self.sorted_edge_ranges + .extend(iter::repeat(0..0).take(node_count)); + + self.computed_masks.clear(); + self.computed_masks.extend(iter::repeat(0).take(node_count)); + } + + /// Recursively constructs the [`ThreadedAnimationGraph`] for the subtree + /// rooted at the given node. + /// + /// `mask` specifies the computed mask of the parent node. (It could be + /// fetched from the [`Self::computed_masks`] field, but we pass it + /// explicitly as a micro-optimization.) + fn build_from( + &mut self, + graph: &AnimationDiGraph, + node_index: AnimationNodeIndex, + mut mask: u64, + ) { + // Accumulate the mask. + mask |= graph.node_weight(node_index).unwrap().mask; + self.computed_masks.insert(node_index.index(), mask); + + // Gather up the indices of our children, and sort them. + let mut kids: SmallVec<[AnimationNodeIndex; 8]> = graph + .neighbors_directed(node_index, Direction::Outgoing) + .collect(); + kids.sort_unstable(); + + // Write in the list of kids. + self.sorted_edge_ranges[node_index.index()] = + (self.sorted_edges.len() as u32)..((self.sorted_edges.len() + kids.len()) as u32); + self.sorted_edges.extend_from_slice(&kids); + + // Recurse. (This is a postorder traversal.) + for kid in kids.into_iter().rev() { + self.build_from(graph, kid, mask); + } + + // Finally, push our index. + self.threaded_graph.push(node_index); + } +} diff --git a/crates/bevy_animation/src/keyframes.rs b/crates/bevy_animation/src/keyframes.rs index b85feb5af1e61..dfcd5995d00e7 100644 --- a/crates/bevy_animation/src/keyframes.rs +++ b/crates/bevy_animation/src/keyframes.rs @@ -1,8 +1,9 @@ //! Keyframes of animation clips. use core::{ - any::TypeId, + any::{Any, TypeId}, fmt::{self, Debug, Formatter}, + marker::PhantomData, }; use bevy_derive::{Deref, DerefMut}; @@ -14,6 +15,7 @@ use bevy_transform::prelude::Transform; use crate::{ animatable, + graph::AnimationNodeIndex, prelude::{Animatable, GetKeyframe}, AnimationEntityMut, AnimationEvaluationError, Interpolation, }; @@ -80,7 +82,7 @@ pub trait AnimatableProperty: Reflect + TypePath + 'static { /// Keyframes in a [`crate::VariableCurve`] that animate an /// [`AnimatableProperty`]. /// -/// This is the a generic type of [`Keyframes`] that can animate any +/// This is the generic type of [`Keyframes`] that can animate any /// [`AnimatableProperty`]. See the documentation for [`AnimatableProperty`] for /// more information as to how to use this type. /// @@ -92,6 +94,18 @@ pub struct AnimatablePropertyKeyframes

(pub Vec) where P: AnimatableProperty; +/// A [`KeyframeEvaluator`] for [`AnimatableProperty`] instances. +/// +/// You shouldn't ordinarily need to instantiate one of these manually. Bevy +/// will automatically do so when you use an [`AnimatablePropertyKeyframes`] +/// instance. +#[derive(Reflect)] +pub struct AnimatablePropertyKeyframeEvaluator

( + SimpleKeyframeEvaluator, P::Property>, +) +where + P: AnimatableProperty; + impl

Clone for AnimatablePropertyKeyframes

where P: AnimatableProperty, @@ -101,6 +115,15 @@ where } } +impl

Clone for AnimatablePropertyKeyframeEvaluator

+where + P: AnimatableProperty, +{ + fn clone(&self) -> Self { + Self(self.0.clone()) + } +} + impl

Debug for AnimatablePropertyKeyframes

where P: AnimatableProperty, @@ -112,70 +135,139 @@ where } } -/// A low-level trait for use in [`crate::VariableCurve`] that provides fine -/// control over how animations are evaluated. +impl

Debug for AnimatablePropertyKeyframeEvaluator

+where + P: AnimatableProperty, +{ + fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result { + f.debug_tuple("AnimatablePropertyKeyframeEvaluator") + .field(&self.0) + .finish() + } +} + +/// A low-level trait for use in [`crate::VariableCurve`] that allows a custom +/// [`KeyframeEvaluator`] to be constructed. /// -/// You can implement this trait when the generic -/// [`AnimatablePropertyKeyframes`] isn't sufficiently-expressive for your -/// needs. For example, [`MorphWeights`] implements this trait instead of using -/// [`AnimatablePropertyKeyframes`] because it needs to animate arbitrarily many -/// weights at once, which can't be done with [`Animatable`] as that works on -/// fixed-size values only. +/// You should usually prefer to use [`AnimatablePropertyKeyframes`] instead of +/// implementing this trait manually. Only implement this trait if you need a +/// custom [`KeyframeEvaluator`]. See the [`KeyframeEvaluator`] documentation +/// for more information on when this might be necessary. pub trait Keyframes: Reflect + Debug + Send + Sync { /// Returns a boxed clone of this value. fn clone_value(&self) -> Box; - /// Interpolates between the existing value and the value of the first - /// keyframe, and writes the value into `transform` and/or `entity` as - /// appropriate. + /// Returns this value upcast to [`Any`]. + fn as_any(&self) -> &dyn Any; + + /// Returns a newly-instantiated [`KeyframeEvaluator`] for use with these + /// keyframes. + fn create_keyframe_evaluator(&self) -> Box; +} + +/// A low-level trait for use in [`crate::VariableCurve`] that provides fine +/// control over how animations are evaluated. +/// +/// You can implement this trait when the generic +/// [`AnimatablePropertyKeyframeEvaluator`] isn't sufficiently-expressive for +/// your needs. For example, [`MorphWeights`] implements this trait instead of +/// using [`AnimatablePropertyKeyframeEvaluator`] because it needs to animate +/// arbitrarily many weights at once, which can't be done with [`Animatable`] as +/// that works on fixed-size values only. +/// +/// If you implement this trait, you should also implement [`Keyframes`], as +/// that trait allows creating instances of this one. +/// +/// Implementations of [`KeyframeEvaluator`] should maintain a *stack* of +/// (value, weight, node index) triples, as well as a *blend register*, which is +/// either a (value, weight) pair or empty. *Value* here refers to an instance +/// of the value being animated: for example, [`Vec3`] in the case of +/// translation keyframes. The stack stores intermediate values generated while +/// evaluating the [`AnimationGraph`], while the blend register stores the +/// result of a blend operation. +pub trait KeyframeEvaluator: Reflect { + /// Blends the top element of the stack with the blend register. /// - /// Arguments: + /// The semantics of this method are as follows: /// - /// * `transform`: The transform of the entity, if present. + /// 1. Pop the top element of the stack. Call its value vₘ and its weight + /// wₘ. If the stack was empty, return success. /// - /// * `entity`: Allows access to the rest of the components of the entity. + /// 2. If the blend register is empty, set the blend register value to vₘ + /// and the blend register weight to wₘ; then, return success. /// - /// * `weight`: The blend weight between the existing component value (0.0) - /// and the one computed from the keyframes (1.0). - fn apply_single_keyframe<'a>( - &self, - transform: Option>, - entity: AnimationEntityMut<'a>, + /// 3. If the blend register is nonempty, call its current value vₙ and its + /// current weight wₙ. Then, set the value of the blend register to + /// `interpolate(vₙ, vₘ, wₘ / (wₘ + wₙ))`, and set the weight of the blend + /// register to wₘ + wₙ. + /// + /// 4. Return success. + fn blend(&mut self, graph_node: AnimationNodeIndex) -> Result<(), AnimationEvaluationError>; + + /// Pushes the current value of the blend register onto the stack. + /// + /// If the blend register is empty, this method does nothing successfully. + /// Otherwise, this method pushes the current value of the blend register + /// onto the stack, alongside the weight and graph node supplied to this + /// function. The weight present in the blend register is discarded; only + /// the weight parameter to this function is pushed onto the stack. The + /// blend register is emptied after this process. + fn push_blend_register( + &mut self, weight: f32, + graph_node: AnimationNodeIndex, ) -> Result<(), AnimationEvaluationError>; - /// Interpolates between the existing value and the value of the two nearest - /// keyframes, and writes the value into `transform` and/or `entity` as - /// appropriate. + /// Pops the top value off the stack and writes it into the appropriate component. /// - /// Arguments: + /// If the stack is empty, this method does nothing successfully. Otherwise, + /// it pops the top value off the stack, fetches the associated component + /// from either the `transform` or `entity` values as appropriate, and + /// updates the appropriate property with the value popped from the stack. + /// The weight and node index associated with the popped stack element are + /// discarded. After doing this, the stack is emptied. /// - /// * `transform`: The transform of the entity, if present. - /// - /// * `entity`: Allows access to the rest of the components of the entity. - /// - /// * `interpolation`: The type of interpolation to use. - /// - /// * `step_start`: The index of the first keyframe. - /// - /// * `time`: The blend weight between the first keyframe (0.0) and the next - /// keyframe (1.0). + /// The property on the component must be overwritten with the value from + /// the stack, not blended with it. + fn commit<'a>( + &mut self, + transform: Option>, + entity: AnimationEntityMut<'a>, + ) -> Result<(), AnimationEvaluationError>; + + /// Pushes the value from the first keyframe (keyframe 0) onto the stack + /// alongside the given weight and graph node. + fn apply_single_keyframe( + &mut self, + keyframes: &dyn Keyframes, + weight: f32, + graph_node: AnimationNodeIndex, + ) -> Result<(), AnimationEvaluationError>; + + /// Samples the value in between two keyframes according to the given + /// interpolation mode. /// - /// * `weight`: The blend weight between the existing component value (0.0) - /// and the one computed from the keyframes (1.0). + /// This method first computes the interpolated value in between keyframe + /// `step_start` and keyframe `step_start + 1` according to the + /// `interpolation` mode and the `time` value. For example, an interpolation + /// mode of `Interpolation::Linear` and a time value of 0.5 computes a value + /// halfway between the keyframe `step_start` and the following one. Then, + /// this method pushes the resulting value onto the stack, alongside the + /// given `weight` and `graph_node`. /// - /// If `interpolation` is `Interpolation::Linear`, then pseudocode for this - /// function could be `property = lerp(property, lerp(keyframes[step_start], - /// keyframes[step_start + 1], time), weight)`. + /// Be sure not to confuse the `time` and `weight` values. The former + /// determines the amount by which two *keyframes* are blended together, + /// while `weight` ultimately determines how much the *stack values* will be + /// blended together (see the definition of [`KeyframeEvaluator::blend`]). #[allow(clippy::too_many_arguments)] - fn apply_tweened_keyframes<'a>( - &self, - transform: Option>, - entity: AnimationEntityMut<'a>, + fn apply_tweened_keyframes( + &mut self, + keyframes: &dyn Keyframes, interpolation: Interpolation, step_start: usize, time: f32, weight: f32, + graph_node: AnimationNodeIndex, duration: f32, ) -> Result<(), AnimationEvaluationError>; } @@ -200,6 +292,13 @@ pub trait Keyframes: Reflect + Debug + Send + Sync { #[derive(Clone, Reflect, Debug, Deref, DerefMut)] pub struct TranslationKeyframes(pub Vec); +/// A [`KeyframeEvaluator`] for use with [`TranslationKeyframes`]. +/// +/// You shouldn't need to instantiate this manually; Bevy will automatically do +/// so. +#[derive(Clone, Default, Reflect, Debug)] +pub struct TranslationKeyframeEvaluator(SimpleKeyframeEvaluator); + /// Keyframes for animating [`Transform::scale`]. /// /// An example of a [`crate::AnimationClip`] that animates translation: @@ -220,6 +319,13 @@ pub struct TranslationKeyframes(pub Vec); #[derive(Clone, Reflect, Debug, Deref, DerefMut)] pub struct ScaleKeyframes(pub Vec); +/// A [`KeyframeEvaluator`] for use with [`ScaleKeyframes`]. +/// +/// You shouldn't need to instantiate this manually; Bevy will automatically do +/// so. +#[derive(Clone, Default, Reflect, Debug)] +pub struct ScaleKeyframeEvaluator(SimpleKeyframeEvaluator); + /// Keyframes for animating [`Transform::rotation`]. /// /// An example of a [`crate::AnimationClip`] that animates translation: @@ -241,11 +347,18 @@ pub struct ScaleKeyframes(pub Vec); #[derive(Clone, Reflect, Debug, Deref, DerefMut)] pub struct RotationKeyframes(pub Vec); +/// A [`KeyframeEvaluator`] for use with [`RotationKeyframes`]. +/// +/// You shouldn't need to instantiate this manually; Bevy will automatically do +/// so. +#[derive(Clone, Default, Reflect, Debug)] +pub struct RotationKeyframeEvaluator(SimpleKeyframeEvaluator); + /// Keyframes for animating [`MorphWeights`]. #[derive(Clone, Debug, Reflect)] pub struct MorphWeightsKeyframes { /// The total number of morph weights. - pub morph_target_count: usize, + pub morph_target_count: u32, /// The morph weights. /// @@ -254,6 +367,46 @@ pub struct MorphWeightsKeyframes { pub weights: Vec, } +/// A [`KeyframeEvaluator`] for use with [`MorphWeightsKeyframes`]. +/// +/// You shouldn't need to instantiate this manually; Bevy will automatically do +/// so. +#[derive(Clone, Debug, Reflect)] +pub struct MorphWeightsKeyframeEvaluator { + /// The values of the stack, in which each element is a list of morph target + /// weights. + /// + /// The stack elements are concatenated and tightly packed together. + /// + /// The number of elements in this stack will always be a multiple of + /// [`Self::morph_target_count`]. + stack_morph_target_weights: Vec, + + /// The blend weights and graph node indices for each element of the stack. + /// + /// This should have as many elements as there are stack nodes. In other + /// words, `Self::stack_morph_target_weights.len() * + /// Self::morph_target_counts as usize == + /// Self::stack_blend_weights_and_graph_nodes`. + stack_blend_weights_and_graph_nodes: Vec<(f32, AnimationNodeIndex)>, + + /// The morph target weights in the blend register, if any. + /// + /// This field should be ignored if [`Self::blend_register_blend_weight`] is + /// `None`. If non-empty, it will always have [`Self::morph_target_count`] + /// elements in it. + blend_register_morph_target_weights: Vec, + + /// The weight in the blend register. + /// + /// This will be `None` if the blend register is empty. In that case, + /// [`Self::blend_register_blend_weight`] will be empty. + blend_register_blend_weight: Option, + + /// The number of morph targets that are to be animated. + morph_target_count: u32, +} + impl From for TranslationKeyframes where T: Into>, @@ -268,44 +421,97 @@ impl Keyframes for TranslationKeyframes { Box::new(self.clone()) } - fn apply_single_keyframe<'a>( - &self, - transform: Option>, + fn as_any(&self) -> &dyn Any { + self + } + + fn create_keyframe_evaluator(&self) -> Box { + Box::new(TranslationKeyframeEvaluator::default()) + } +} + +impl KeyframeEvaluator for TranslationKeyframeEvaluator { + fn blend<'a>( + &mut self, + graph_node: AnimationNodeIndex, + ) -> Result<(), AnimationEvaluationError> { + self.0.blend(graph_node) + } + + fn push_blend_register( + &mut self, + weight: f32, + graph_node: AnimationNodeIndex, + ) -> Result<(), AnimationEvaluationError> { + self.0.push_blend(weight, graph_node) + } + + fn commit<'a>( + &mut self, + mut transform: Option>, _: AnimationEntityMut<'a>, + ) -> Result<(), AnimationEvaluationError> { + transform + .as_mut() + .ok_or_else( + || AnimationEvaluationError::ComponentNotPresent(TypeId::of::()), + )? + .translation = self + .0 + .stack + .pop() + .ok_or_else(inconsistent::)? + .value; + self.0.stack.clear(); + Ok(()) + } + + fn apply_single_keyframe( + &mut self, + keyframes: &dyn Keyframes, weight: f32, + graph_node: AnimationNodeIndex, ) -> Result<(), AnimationEvaluationError> { - let mut component = transform.ok_or_else(|| { - AnimationEvaluationError::ComponentNotPresent(TypeId::of::()) - })?; - let value = self + let value = *Keyframes::as_any(keyframes) + .downcast_ref::() + .unwrap() + .0 .first() .ok_or(AnimationEvaluationError::KeyframeNotPresent(0))?; - component.translation = Animatable::interpolate(&component.translation, value, weight); + self.0.stack.push(SimpleKeyframeEvaluatorStackElement { + value, + weight, + graph_node, + }); Ok(()) } fn apply_tweened_keyframes<'a>( - &self, - transform: Option>, - _: AnimationEntityMut<'a>, + &mut self, + keyframes: &dyn Keyframes, interpolation: Interpolation, step_start: usize, time: f32, weight: f32, + graph_node: AnimationNodeIndex, duration: f32, ) -> Result<(), AnimationEvaluationError> { - let mut component = transform.ok_or_else(|| { - AnimationEvaluationError::ComponentNotPresent(TypeId::of::()) - })?; - animatable::interpolate_keyframes( - &mut component.translation, - &(*self)[..], + let keyframes = Keyframes::as_any(keyframes) + .downcast_ref::() + .unwrap(); + let value = animatable::interpolate_keyframes( + &keyframes.0[..], interpolation, step_start, time, - weight, duration, - ) + )?; + self.0.stack.push(SimpleKeyframeEvaluatorStackElement { + value, + weight, + graph_node, + }); + Ok(()) } } @@ -323,44 +529,94 @@ impl Keyframes for ScaleKeyframes { Box::new(self.clone()) } - fn apply_single_keyframe<'a>( - &self, - transform: Option>, + fn as_any(&self) -> &dyn Any { + self + } + + fn create_keyframe_evaluator(&self) -> Box { + Box::new(ScaleKeyframeEvaluator::default()) + } +} + +impl KeyframeEvaluator for ScaleKeyframeEvaluator { + fn blend(&mut self, graph_node: AnimationNodeIndex) -> Result<(), AnimationEvaluationError> { + self.0.blend(graph_node) + } + + fn push_blend_register( + &mut self, + weight: f32, + graph_node: AnimationNodeIndex, + ) -> Result<(), AnimationEvaluationError> { + self.0.push_blend(weight, graph_node) + } + + fn commit<'a>( + &mut self, + mut transform: Option>, _: AnimationEntityMut<'a>, + ) -> Result<(), AnimationEvaluationError> { + transform + .as_mut() + .ok_or_else( + || AnimationEvaluationError::ComponentNotPresent(TypeId::of::()), + )? + .scale = self + .0 + .stack + .pop() + .ok_or_else(inconsistent::)? + .value; + self.0.stack.clear(); + Ok(()) + } + + fn apply_single_keyframe( + &mut self, + keyframes: &dyn Keyframes, weight: f32, + graph_node: AnimationNodeIndex, ) -> Result<(), AnimationEvaluationError> { - let mut component = transform.ok_or_else(|| { - AnimationEvaluationError::ComponentNotPresent(TypeId::of::()) - })?; - let value = self + let value = *Keyframes::as_any(keyframes) + .downcast_ref::() + .unwrap() + .0 .first() .ok_or(AnimationEvaluationError::KeyframeNotPresent(0))?; - component.scale = Animatable::interpolate(&component.scale, value, weight); + self.0.stack.push(SimpleKeyframeEvaluatorStackElement { + value, + weight, + graph_node, + }); Ok(()) } fn apply_tweened_keyframes<'a>( - &self, - transform: Option>, - _: AnimationEntityMut<'a>, + &mut self, + keyframes: &dyn Keyframes, interpolation: Interpolation, step_start: usize, time: f32, weight: f32, + graph_node: AnimationNodeIndex, duration: f32, ) -> Result<(), AnimationEvaluationError> { - let mut component = transform.ok_or_else(|| { - AnimationEvaluationError::ComponentNotPresent(TypeId::of::()) - })?; - animatable::interpolate_keyframes( - &mut component.scale, - &(*self)[..], + let keyframes = Keyframes::as_any(keyframes) + .downcast_ref::() + .unwrap(); + let value = animatable::interpolate_keyframes( + &keyframes.0[..], interpolation, step_start, time, - weight, duration, - ) + )?; + self.0.stack.push(SimpleKeyframeEvaluatorStackElement { + value, + weight, + graph_node, + }); + Ok(()) } } @@ -378,44 +634,94 @@ impl Keyframes for RotationKeyframes { Box::new(self.clone()) } - fn apply_single_keyframe<'a>( - &self, - transform: Option>, + fn as_any(&self) -> &dyn Any { + self + } + + fn create_keyframe_evaluator(&self) -> Box { + Box::new(RotationKeyframeEvaluator::default()) + } +} + +impl KeyframeEvaluator for RotationKeyframeEvaluator { + fn commit<'a>( + &mut self, + mut transform: Option>, _: AnimationEntityMut<'a>, + ) -> Result<(), AnimationEvaluationError> { + transform + .as_mut() + .ok_or_else( + || AnimationEvaluationError::ComponentNotPresent(TypeId::of::()), + )? + .rotation = self + .0 + .stack + .pop() + .ok_or_else(inconsistent::)? + .value; + self.0.stack.clear(); + Ok(()) + } + + fn apply_single_keyframe( + &mut self, + keyframes: &dyn Keyframes, weight: f32, + graph_node: AnimationNodeIndex, ) -> Result<(), AnimationEvaluationError> { - let mut component = transform.ok_or_else(|| { - AnimationEvaluationError::ComponentNotPresent(TypeId::of::()) - })?; - let value = self + let value = Keyframes::as_any(keyframes) + .downcast_ref::() + .unwrap() + .0 .first() .ok_or(AnimationEvaluationError::KeyframeNotPresent(0))?; - component.rotation = Animatable::interpolate(&component.rotation, value, weight); + self.0.stack.push(SimpleKeyframeEvaluatorStackElement { + value: *value, + weight, + graph_node, + }); Ok(()) } fn apply_tweened_keyframes<'a>( - &self, - transform: Option>, - _: AnimationEntityMut<'a>, + &mut self, + keyframes: &dyn Keyframes, interpolation: Interpolation, step_start: usize, time: f32, weight: f32, + graph_node: AnimationNodeIndex, duration: f32, ) -> Result<(), AnimationEvaluationError> { - let mut component = transform.ok_or_else(|| { - AnimationEvaluationError::ComponentNotPresent(TypeId::of::()) - })?; - animatable::interpolate_keyframes( - &mut component.rotation, - &(*self)[..], + let keyframes = Keyframes::as_any(keyframes) + .downcast_ref::() + .unwrap(); + let value = animatable::interpolate_keyframes( + &keyframes.0[..], interpolation, step_start, time, - weight, duration, - ) + )?; + self.0.stack.push(SimpleKeyframeEvaluatorStackElement { + value, + weight, + graph_node, + }); + Ok(()) + } + + fn blend(&mut self, graph_node: AnimationNodeIndex) -> Result<(), AnimationEvaluationError> { + self.0.blend(graph_node) + } + + fn push_blend_register( + &mut self, + weight: f32, + graph_node: AnimationNodeIndex, + ) -> Result<(), AnimationEvaluationError> { + self.0.push_blend(weight, graph_node) } } @@ -437,48 +743,181 @@ where Box::new((*self).clone()) } - fn apply_single_keyframe<'a>( - &self, + fn as_any(&self) -> &dyn Any { + self + } + + fn create_keyframe_evaluator(&self) -> Box { + Box::new(AnimatablePropertyKeyframeEvaluator::

( + SimpleKeyframeEvaluator::default(), + )) + } +} + +impl

KeyframeEvaluator for AnimatablePropertyKeyframeEvaluator

+where + P: AnimatableProperty, +{ + fn blend(&mut self, graph_node: AnimationNodeIndex) -> Result<(), AnimationEvaluationError> { + self.0.blend(graph_node) + } + + fn push_blend_register( + &mut self, + weight: f32, + graph_node: AnimationNodeIndex, + ) -> Result<(), AnimationEvaluationError> { + self.0.push_blend(weight, graph_node) + } + + fn commit<'a>( + &mut self, _: Option>, mut entity: AnimationEntityMut<'a>, - weight: f32, ) -> Result<(), AnimationEvaluationError> { - let mut component = entity.get_mut::().ok_or_else(|| { + *P::get_mut(&mut *entity.get_mut::().ok_or_else(|| { AnimationEvaluationError::ComponentNotPresent(TypeId::of::()) - })?; - let property = P::get_mut(&mut component) - .ok_or_else(|| AnimationEvaluationError::PropertyNotPresent(TypeId::of::

()))?; - let value = self + })?) + .ok_or_else(|| { + AnimationEvaluationError::PropertyNotPresent(TypeId::of::()) + })? = self.0.stack.pop().ok_or_else(inconsistent::

)?.value; + self.0.stack.clear(); + Ok(()) + } + + fn apply_single_keyframe( + &mut self, + keyframes: &dyn Keyframes, + weight: f32, + graph_node: AnimationNodeIndex, + ) -> Result<(), AnimationEvaluationError> { + let value = (*Keyframes::as_any(keyframes) + .downcast_ref::>() + .unwrap() + .0 .first() - .ok_or(AnimationEvaluationError::KeyframeNotPresent(0))?; - ::interpolate(property, value, weight); + .ok_or(AnimationEvaluationError::KeyframeNotPresent(0))?) + .clone(); + self.0.stack.push(SimpleKeyframeEvaluatorStackElement { + value, + weight, + graph_node, + }); Ok(()) } fn apply_tweened_keyframes<'a>( - &self, - _: Option>, - mut entity: AnimationEntityMut<'a>, + &mut self, + keyframes: &dyn Keyframes, interpolation: Interpolation, step_start: usize, time: f32, weight: f32, + graph_node: AnimationNodeIndex, duration: f32, ) -> Result<(), AnimationEvaluationError> { - let mut component = entity.get_mut::().ok_or_else(|| { - AnimationEvaluationError::ComponentNotPresent(TypeId::of::()) - })?; - let property = P::get_mut(&mut component) - .ok_or_else(|| AnimationEvaluationError::PropertyNotPresent(TypeId::of::

()))?; - animatable::interpolate_keyframes( - property, - self, + let keyframes = (*Keyframes::as_any(keyframes) + .downcast_ref::>() + .unwrap()) + .clone(); + let value = animatable::interpolate_keyframes( + &keyframes.0[..], interpolation, step_start, time, - weight, duration, )?; + self.0.stack.push(SimpleKeyframeEvaluatorStackElement { + value, + weight, + graph_node, + }); + Ok(()) + } +} + +#[derive(Clone, Reflect, Debug)] +struct SimpleKeyframeEvaluator +where + K: Keyframes, + P: Animatable, +{ + stack: Vec>, + blend_register: Option<(P, f32)>, + #[reflect(ignore)] + phantom: PhantomData, +} + +#[derive(Clone, Reflect, Debug)] +struct SimpleKeyframeEvaluatorStackElement

+where + P: Animatable, +{ + value: P, + weight: f32, + graph_node: AnimationNodeIndex, +} + +impl Default for SimpleKeyframeEvaluator +where + K: Keyframes, + P: Animatable, +{ + fn default() -> Self { + SimpleKeyframeEvaluator { + stack: vec![], + blend_register: None, + phantom: PhantomData, + } + } +} + +impl SimpleKeyframeEvaluator +where + K: Keyframes, + P: Animatable + Debug, +{ + fn blend(&mut self, graph_node: AnimationNodeIndex) -> Result<(), AnimationEvaluationError> { + let Some(top) = self.stack.last() else { + return Ok(()); + }; + if top.graph_node != graph_node { + return Ok(()); + } + + let SimpleKeyframeEvaluatorStackElement { + value: value_to_blend, + weight: weight_to_blend, + graph_node: _, + } = self.stack.pop().unwrap(); + + match self.blend_register { + None => self.blend_register = Some((value_to_blend, weight_to_blend)), + Some((ref mut current_value, ref mut current_weight)) => { + *current_weight += weight_to_blend; + *current_value = P::interpolate( + current_value, + &value_to_blend, + weight_to_blend / *current_weight, + ); + } + } + + Ok(()) + } + + fn push_blend( + &mut self, + weight: f32, + graph_node: AnimationNodeIndex, + ) -> Result<(), AnimationEvaluationError> { + if let Some((value, _)) = self.blend_register.take() { + self.stack.push(SimpleKeyframeEvaluatorStackElement { + value, + weight, + graph_node, + }); + } Ok(()) } } @@ -519,55 +958,155 @@ impl Keyframes for MorphWeightsKeyframes { Box::new(self.clone()) } - fn apply_single_keyframe<'a>( - &self, - _: Option>, - mut entity: AnimationEntityMut<'a>, + fn as_any(&self) -> &dyn Any { + self + } + + fn create_keyframe_evaluator(&self) -> Box { + Box::new(MorphWeightsKeyframeEvaluator { + stack_morph_target_weights: vec![], + stack_blend_weights_and_graph_nodes: vec![], + blend_register_morph_target_weights: vec![], + blend_register_blend_weight: None, + morph_target_count: self.morph_target_count, + }) + } +} + +impl KeyframeEvaluator for MorphWeightsKeyframeEvaluator { + fn blend(&mut self, graph_node: AnimationNodeIndex) -> Result<(), AnimationEvaluationError> { + let Some(&(_, top_graph_node)) = self.stack_blend_weights_and_graph_nodes.last() else { + return Ok(()); + }; + if top_graph_node != graph_node { + return Ok(()); + } + + let (weight_to_blend, _) = self.stack_blend_weights_and_graph_nodes.pop().unwrap(); + let stack_iter = self + .stack_morph_target_weights + .drain((self.stack_morph_target_weights.len() - self.morph_target_count as usize)..); + + match self.blend_register_blend_weight { + None => { + self.blend_register_blend_weight = Some(weight_to_blend); + self.blend_register_morph_target_weights.clear(); + self.blend_register_morph_target_weights.extend(stack_iter); + } + + Some(ref mut current_weight) => { + *current_weight += weight_to_blend; + for (dest, src) in self + .blend_register_morph_target_weights + .iter_mut() + .zip(stack_iter) + { + *dest = f32::interpolate(dest, &src, weight_to_blend / *current_weight); + } + } + } + + Ok(()) + } + + fn push_blend_register( + &mut self, weight: f32, + graph_node: AnimationNodeIndex, ) -> Result<(), AnimationEvaluationError> { - let mut dest = entity.get_mut::().ok_or_else(|| { - AnimationEvaluationError::ComponentNotPresent(TypeId::of::()) - })?; + if self.blend_register_blend_weight.take().is_some() { + self.stack_morph_target_weights + .append(&mut self.blend_register_morph_target_weights); + self.stack_blend_weights_and_graph_nodes + .push((weight, graph_node)); + } + Ok(()) + } - // TODO: Go 4 weights at a time to make better use of SIMD. - for (morph_target_index, morph_weight) in dest.weights_mut().iter_mut().enumerate() { - *morph_weight = - f32::interpolate(morph_weight, &self.weights[morph_target_index], weight); + fn commit<'a>( + &mut self, + _: Option>, + mut entity: AnimationEntityMut<'a>, + ) -> Result<(), AnimationEvaluationError> { + for (dest, src) in entity + .get_mut::() + .ok_or_else(|| { + AnimationEvaluationError::ComponentNotPresent(TypeId::of::()) + })? + .weights_mut() + .iter_mut() + .zip( + self.stack_morph_target_weights + [(self.stack_morph_target_weights.len() - self.morph_target_count as usize)..] + .iter(), + ) + { + *dest = *src; } + self.stack_morph_target_weights.clear(); + self.stack_blend_weights_and_graph_nodes.clear(); + Ok(()) + } + fn apply_single_keyframe( + &mut self, + keyframes: &dyn Keyframes, + weight: f32, + graph_node: AnimationNodeIndex, + ) -> Result<(), AnimationEvaluationError> { + let morph_weights_keyframes = Keyframes::as_any(keyframes) + .downcast_ref::() + .unwrap(); + if morph_weights_keyframes.weights.len() + < (morph_weights_keyframes.morph_target_count as usize) + { + return Err(AnimationEvaluationError::KeyframeNotPresent(0)); + } + self.stack_morph_target_weights.extend( + morph_weights_keyframes.weights + [0..(morph_weights_keyframes.morph_target_count as usize)] + .iter() + .cloned(), + ); + self.stack_blend_weights_and_graph_nodes + .push((weight, graph_node)); Ok(()) } fn apply_tweened_keyframes<'a>( - &self, - _: Option>, - mut entity: AnimationEntityMut<'a>, + &mut self, + keyframes: &dyn Keyframes, interpolation: Interpolation, step_start: usize, time: f32, weight: f32, + graph_node: AnimationNodeIndex, duration: f32, ) -> Result<(), AnimationEvaluationError> { - let mut dest = entity.get_mut::().ok_or_else(|| { - AnimationEvaluationError::ComponentNotPresent(TypeId::of::()) - })?; + let morph_weights_keyframes = Keyframes::as_any(keyframes) + .downcast_ref::() + .unwrap(); // TODO: Go 4 weights at a time to make better use of SIMD. - for (morph_target_index, morph_weight) in dest.weights_mut().iter_mut().enumerate() { - animatable::interpolate_keyframes( - morph_weight, - &GetMorphWeightKeyframe { - keyframes: self, - morph_target_index, - }, - interpolation, - step_start, - time, - weight, - duration, - )?; + self.stack_morph_target_weights + .reserve(self.morph_target_count as usize); + for morph_target_index in 0..self.morph_target_count { + self.stack_morph_target_weights + .push(animatable::interpolate_keyframes( + &GetMorphWeightKeyframe { + keyframes: morph_weights_keyframes, + morph_target_index: morph_target_index as usize, + }, + interpolation, + step_start, + time, + duration, + )?); } + self.stack_blend_weights_and_graph_nodes + .push((weight, graph_node)); + Ok(()) } } @@ -576,9 +1115,15 @@ impl GetKeyframe for GetMorphWeightKeyframe<'_> { type Output = f32; fn get_keyframe(&self, keyframe_index: usize) -> Option<&Self::Output> { - self.keyframes - .weights - .as_slice() - .get(keyframe_index * self.keyframes.morph_target_count + self.morph_target_index) + self.keyframes.weights.as_slice().get( + keyframe_index * self.keyframes.morph_target_count as usize + self.morph_target_index, + ) } } + +fn inconsistent

() -> AnimationEvaluationError +where + P: 'static, +{ + AnimationEvaluationError::InconsistentKeyframeImplementation(TypeId::of::

()) +} diff --git a/crates/bevy_animation/src/lib.rs b/crates/bevy_animation/src/lib.rs index 0b1339d2fb3d9..3265af361b9c4 100755 --- a/crates/bevy_animation/src/lib.rs +++ b/crates/bevy_animation/src/lib.rs @@ -15,7 +15,6 @@ pub mod keyframes; pub mod transition; mod util; -use alloc::collections::BTreeMap; use core::{ any::{Any, TypeId}, cell::RefCell, @@ -43,11 +42,11 @@ use bevy_ui::UiSystem; use bevy_utils::{ hashbrown::HashMap, tracing::{trace, warn}, - NoOpHash, + NoOpHash, TypeIdMap, }; -use fixedbitset::FixedBitSet; -use graph::AnimationMask; -use petgraph::{graph::NodeIndex, Direction}; +use graph::ThreadedAnimationGraphs; +use petgraph::graph::NodeIndex; +use prelude::KeyframeEvaluator; use serde::{Deserialize, Serialize}; use thread_local::ThreadLocal; use uuid::Uuid; @@ -623,17 +622,31 @@ pub enum AnimationEvaluationError { /// timestamps. For curves with `Interpolation::CubicBezier`, the /// `keyframes` array must have at least 3× the number of elements as /// keyframe timestamps, in order to account for the tangents. + /// + /// The given `usize` specifies the index of the keyframe that was expected. KeyframeNotPresent(usize), /// The component to be animated isn't present on the animation target. /// /// To fix this error, make sure the entity to be animated contains all /// components that have animation curves. + /// + /// The given [`TypeId`] specifies the type of the component that was + /// expected to be present. ComponentNotPresent(TypeId), /// The component to be animated was present, but the property on the /// component wasn't present. + /// + /// The given [`TypeId`] specifies the type of the property to be animated. PropertyNotPresent(TypeId), + + /// An internal error occurred in the implementation of + /// [`KeyframeEvaluator`]. + /// + /// You shouldn't ordinarily see this error unless you implemented + /// [`KeyframeEvaluator`] yourself. + InconsistentKeyframeImplementation(TypeId), } /// An animation that an [`AnimationPlayer`] is currently either playing or was @@ -644,12 +657,8 @@ pub enum AnimationEvaluationError { pub struct ActiveAnimation { /// The factor by which the weight from the [`AnimationGraph`] is multiplied. weight: f32, - /// The actual weight of this animation this frame, taking the - /// [`AnimationGraph`] into account. - computed_weight: f32, /// The mask groups that are masked out (i.e. won't be animated) this frame, /// taking the `AnimationGraph` into account. - computed_mask: AnimationMask, repeat: RepeatAnimation, speed: f32, /// Total time the animation has been played. @@ -670,8 +679,6 @@ impl Default for ActiveAnimation { fn default() -> Self { Self { weight: 1.0, - computed_weight: 1.0, - computed_mask: 0, repeat: RepeatAnimation::default(), speed: 1.0, elapsed: 0.0, @@ -831,9 +838,7 @@ impl ActiveAnimation { #[derive(Component, Default, Reflect)] #[reflect(Component, Default)] pub struct AnimationPlayer { - /// We use a `BTreeMap` instead of a `HashMap` here to ensure a consistent - /// ordering when applying the animations. - active_animations: BTreeMap, + active_animations: HashMap, blend_weights: HashMap, } @@ -852,27 +857,26 @@ impl Clone for AnimationPlayer { } } -/// Information needed during the traversal of the animation graph in -/// [`advance_animations`]. +/// Temporary data that the [`animate_targets`] system maintains. #[derive(Default)] -pub struct AnimationGraphEvaluator { - /// The stack used for the depth-first search of the graph. - dfs_stack: Vec, - /// The list of visited nodes during the depth-first traversal. - dfs_visited: FixedBitSet, - /// Accumulated weights and masks for each node. - nodes: Vec, -} - -/// The accumulated weight and computed mask for a single node. -#[derive(Clone, Copy, Default, Debug)] -struct EvaluatedAnimationGraphNode { - /// The weight that has been accumulated for this node, taking its - /// ancestors' weights into account. - weight: f32, - /// The mask that has been computed for this node, taking its ancestors' - /// masks into account. - mask: AnimationMask, +pub struct AnimationEvaluationState { + /// A mapping from each [`Keyframes`] type being animated to its + /// [`KeyframeEvaluator`]. + /// + /// For efficiency's sake, the [`KeyframeEvaluator`]s are cached from frame + /// to frame and animation target to animation target. Therefore, there may + /// be entries in this list corresponding to properties that the current + /// [`AnimationPlayer`] doesn't animate. To iterate only over the properties + /// that are currently being animated, consult the + /// [`Self::current_keyframe_types`] set. + keyframe_evaluators: TypeIdMap>, + + /// The set of [`Keyframes`] types that the current [`AnimationPlayer`] is + /// animating. + /// + /// This is built up as new keyframes are encountered during graph + /// traversal. + current_keyframe_types: TypeIdMap<()>, } impl AnimationPlayer { @@ -1018,7 +1022,6 @@ pub fn advance_animations( animation_clips: Res>, animation_graphs: Res>, mut players: Query<(&mut AnimationPlayer, &Handle)>, - animation_graph_evaluator: Local>>, ) { let delta_seconds = time.delta_seconds(); players @@ -1029,40 +1032,15 @@ pub fn advance_animations( }; // Tick animations, and schedule them. - // - // We use a thread-local here so we can reuse allocations across - // frames. - let mut evaluator = animation_graph_evaluator.get_or_default().borrow_mut(); let AnimationPlayer { ref mut active_animations, - ref blend_weights, .. } = *player; - // Reset our state. - evaluator.reset(animation_graph.root, animation_graph.graph.node_count()); - - while let Some(node_index) = evaluator.dfs_stack.pop() { - // Skip if we've already visited this node. - if evaluator.dfs_visited.put(node_index.index()) { - continue; - } - + for node_index in animation_graph.graph.node_indices() { let node = &animation_graph[node_index]; - // Calculate weight and mask from the graph. - let (mut weight, mut mask) = (node.weight, node.mask); - for parent_index in animation_graph - .graph - .neighbors_directed(node_index, Direction::Incoming) - { - let evaluated_parent = &evaluator.nodes[parent_index.index()]; - weight *= evaluated_parent.weight; - mask |= evaluated_parent.mask; - } - evaluator.nodes[node_index.index()] = EvaluatedAnimationGraphNode { weight, mask }; - if let Some(active_animation) = active_animations.get_mut(&node_index) { // Tick the animation if necessary. if !active_animation.paused { @@ -1072,24 +1050,7 @@ pub fn advance_animations( } } } - - weight *= active_animation.weight; - } else if let Some(&blend_weight) = blend_weights.get(&node_index) { - weight *= blend_weight; } - - // Write in the computed weight and mask for this node. - if let Some(active_animation) = active_animations.get_mut(&node_index) { - active_animation.computed_weight = weight; - active_animation.computed_mask = mask; - } - - // Push children. - evaluator.dfs_stack.extend( - animation_graph - .graph - .neighbors_directed(node_index, Direction::Outgoing), - ); } }); } @@ -1110,17 +1071,19 @@ pub type AnimationEntityMut<'w> = EntityMutExcept< pub fn animate_targets( clips: Res>, graphs: Res>, + threaded_animation_graphs: Res, players: Query<(&AnimationPlayer, &Handle)>, mut targets: Query<(&AnimationTarget, Option<&mut Transform>, AnimationEntityMut)>, + animation_evaluation_state: Local>>, ) { // Evaluate all animation targets in parallel. targets .par_iter_mut() - .for_each(|(target, mut transform, mut entity_mut)| { - let &AnimationTarget { + .for_each(|(animation_target, transform, entity_mut)| { + let AnimationTarget { id: target_id, player: player_id, - } = target; + } = *animation_target; let (animation_player, animation_graph_id) = if let Ok((player, graph_handle)) = players.get(player_id) { @@ -1141,6 +1104,12 @@ pub fn animate_targets( return; }; + let Some(threaded_animation_graph) = + threaded_animation_graphs.0.get(&animation_graph_id) + else { + return; + }; + // Determine which mask groups this animation target belongs to. let target_mask = animation_graph .mask_groups @@ -1148,88 +1117,121 @@ pub fn animate_targets( .cloned() .unwrap_or_default(); - // Apply the animations one after another. The way we accumulate - // weights ensures that the order we apply them in doesn't matter. - // - // Proof: Consider three animations A₀, A₁, A₂, … with weights w₀, - // w₁, w₂, … respectively. We seek the value: - // - // A₀w₀ + A₁w₁ + A₂w₂ + ⋯ - // - // Defining lerp(a, b, t) = a + t(b - a), we have: - // - // ⎛ ⎛ w₁ ⎞ w₂ ⎞ - // A₀w₀ + A₁w₁ + A₂w₂ + ⋯ = ⋯ lerp⎜lerp⎜A₀, A₁, ⎯⎯⎯⎯⎯⎯⎯⎯⎟, A₂, ⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎟ ⋯ - // ⎝ ⎝ w₀ + w₁⎠ w₀ + w₁ + w₂⎠ - // - // Each step of the following loop corresponds to one of the lerp - // operations above. - let mut total_weight = 0.0; - for (&animation_graph_node_index, active_animation) in - animation_player.active_animations.iter() - { - // If the weight is zero or the current animation target is - // masked out, stop here. - if active_animation.weight == 0.0 - || (target_mask & active_animation.computed_mask) != 0 - { - continue; - } + let mut evaluation_state = animation_evaluation_state.get_or_default().borrow_mut(); + let evaluation_state = &mut *evaluation_state; - let Some(clip) = animation_graph - .get(animation_graph_node_index) - .and_then(|animation_graph_node| animation_graph_node.clip.as_ref()) - .and_then(|animation_clip_handle| clips.get(animation_clip_handle)) + // Evaluate the graph. + for &animation_graph_node_index in threaded_animation_graph.threaded_graph.iter() { + let Some(animation_graph_node) = animation_graph.get(animation_graph_node_index) else { continue; }; - let Some(curves) = clip.curves_for_target(target_id) else { - continue; - }; - - let weight = active_animation.computed_weight; - total_weight += weight; - - let weight = weight / total_weight; - let seek_time = active_animation.seek_time; + match animation_graph_node.clip { + None => { + // This is a blend node. + for edge_index in threaded_animation_graph.sorted_edge_ranges + [animation_graph_node_index.index()] + .clone() + { + if let Err(err) = evaluation_state.blend_all( + threaded_animation_graph.sorted_edges[edge_index as usize], + ) { + warn!("Failed to blend animation: {:?}", err); + } + } - for curve in curves { - // Some curves have only one keyframe used to set a transform - if curve.keyframe_timestamps.len() == 1 { - if let Err(err) = curve.keyframes.apply_single_keyframe( - transform.as_mut().map(|transform| transform.reborrow()), - entity_mut.reborrow(), - weight, + if let Err(err) = evaluation_state.push_blend_register_all( + animation_graph_node.weight, + animation_graph_node_index, ) { - warn!("Animation application failed: {:?}", err); + warn!("Failed to blend animation: {:?}", err); } - - continue; } - // Find the best keyframe to interpolate from - let step_start = curve.find_interpolation_start_keyframe(seek_time); - - let timestamp_start = curve.keyframe_timestamps[step_start]; - let timestamp_end = curve.keyframe_timestamps[step_start + 1]; - // Compute how far we are through the keyframe, normalized to [0, 1] - let lerp = f32::inverse_lerp(timestamp_start, timestamp_end, seek_time) - .clamp(0.0, 1.0); - - if let Err(err) = curve.keyframes.apply_tweened_keyframes( - transform.as_mut().map(|transform| transform.reborrow()), - entity_mut.reborrow(), - curve.interpolation, - step_start, - lerp, - weight, - timestamp_end - timestamp_start, - ) { - warn!("Animation application failed: {:?}", err); + Some(ref animation_clip_handle) => { + // This is a clip node. + let Some(active_animation) = animation_player + .active_animations + .get(&animation_graph_node_index) + else { + continue; + }; + + // If the weight is zero or the current animation target is + // masked out, stop here. + if active_animation.weight == 0.0 + || (target_mask + & threaded_animation_graph.computed_masks + [animation_graph_node_index.index()]) + != 0 + { + continue; + } + + let Some(clip) = clips.get(animation_clip_handle) else { + continue; + }; + + let Some(curves) = clip.curves_for_target(target_id) else { + continue; + }; + + let weight = active_animation.weight; + let seek_time = active_animation.seek_time; + + for curve in curves { + let keyframe_type_id = (*curve.keyframes).type_id(); + let keyframe_evaluator = evaluation_state + .keyframe_evaluators + .entry(keyframe_type_id) + .or_insert_with(|| curve.keyframes.create_keyframe_evaluator()); + + evaluation_state + .current_keyframe_types + .insert(keyframe_type_id, ()); + + // Some curves have only one keyframe used to set a transform + if curve.keyframe_timestamps.len() == 1 { + if let Err(err) = keyframe_evaluator.apply_single_keyframe( + &*curve.keyframes, + weight, + animation_graph_node_index, + ) { + warn!("Animation application failed: {:?}", err); + } + + continue; + } + + // Find the best keyframe to interpolate from + let step_start = curve.find_interpolation_start_keyframe(seek_time); + + let timestamp_start = curve.keyframe_timestamps[step_start]; + let timestamp_end = curve.keyframe_timestamps[step_start + 1]; + // Compute how far we are through the keyframe, normalized to [0, 1] + let lerp = f32::inverse_lerp(timestamp_start, timestamp_end, seek_time) + .clamp(0.0, 1.0); + + if let Err(err) = keyframe_evaluator.apply_tweened_keyframes( + &*curve.keyframes, + curve.interpolation, + step_start, + lerp, + weight, + animation_graph_node_index, + timestamp_end - timestamp_start, + ) { + warn!("Animation application failed: {:?}", err); + } + } } } } + + if let Err(err) = evaluation_state.commit_all(transform, entity_mut) { + warn!("Animation application failed: {:?}", err); + } }); } @@ -1248,9 +1250,12 @@ impl Plugin for AnimationPlugin { .register_type::() .register_type::() .register_type::() + .register_type::() + .init_resource::() .add_systems( PostUpdate, ( + graph::thread_animation_graphs, advance_transitions, advance_animations, // TODO: `animate_targets` can animate anything, so @@ -1304,18 +1309,64 @@ impl MapEntities for AnimationTarget { } } -impl AnimationGraphEvaluator { - // Starts a new depth-first search. - fn reset(&mut self, root: AnimationNodeIndex, node_count: usize) { - self.dfs_stack.clear(); - self.dfs_stack.push(root); +impl AnimationEvaluationState { + /// Calls [`KeyframeEvaluator::blend`] on all keyframe types that we've been + /// building up for a single target. + /// + /// The given `node_index` is the node that we're evaluating. + fn blend_all( + &mut self, + node_index: AnimationNodeIndex, + ) -> Result<(), AnimationEvaluationError> { + for keyframe_type in self.current_keyframe_types.keys() { + self.keyframe_evaluators + .get_mut(keyframe_type) + .unwrap() + .blend(node_index)?; + } + Ok(()) + } - self.dfs_visited.grow(node_count); - self.dfs_visited.clear(); + /// Calls [`KeyframeEvaluator::push_blend_register`] on all keyframe types + /// that we've been building up for a single target. + /// + /// The `weight` parameter is the weight that should be pushed onto the + /// stack, while the `node_index` parameter is the node that we're + /// evaluating. + fn push_blend_register_all( + &mut self, + weight: f32, + node_index: AnimationNodeIndex, + ) -> Result<(), AnimationEvaluationError> { + for keyframe_type in self.current_keyframe_types.keys() { + self.keyframe_evaluators + .get_mut(keyframe_type) + .unwrap() + .push_blend_register(weight, node_index)?; + } + Ok(()) + } - self.nodes.clear(); - self.nodes - .extend(iter::repeat(EvaluatedAnimationGraphNode::default()).take(node_count)); + /// Calls [`KeyframeEvaluator::commit`] on all keyframe types that we've + /// been building up for a single target. + /// + /// This is the call that actually writes the computed values into the + /// components being animated. + fn commit_all( + &mut self, + mut transform: Option>, + mut entity_mut: AnimationEntityMut, + ) -> Result<(), AnimationEvaluationError> { + for (keyframe_type, _) in self.current_keyframe_types.drain() { + self.keyframe_evaluators + .get_mut(&keyframe_type) + .unwrap() + .commit( + transform.as_mut().map(|transform| transform.reborrow()), + entity_mut.reborrow(), + )?; + } + Ok(()) } } diff --git a/crates/bevy_gltf/src/loader.rs b/crates/bevy_gltf/src/loader.rs index 147d0f3232805..c6dc1cf763a4b 100644 --- a/crates/bevy_gltf/src/loader.rs +++ b/crates/bevy_gltf/src/loader.rs @@ -313,7 +313,8 @@ async fn load_gltf<'a, 'b, 'c>( ReadOutputs::MorphTargetWeights(weights) => { let weights: Vec<_> = weights.into_f32().collect(); Box::new(MorphWeightsKeyframes { - morph_target_count: weights.len() / keyframe_timestamps.len(), + morph_target_count: (weights.len() / keyframe_timestamps.len()) + as u32, weights, }) as Box } diff --git a/examples/animation/animation_graph.rs b/examples/animation/animation_graph.rs index 94b9a2e52295e..f9b4280e593ea 100644 --- a/examples/animation/animation_graph.rs +++ b/examples/animation/animation_graph.rs @@ -47,24 +47,24 @@ static NODE_RECTS: [NodeRect; 5] = [ NodeRect::new(10.00, 10.00, 97.64, 48.41), NodeRect::new(10.00, 78.41, 97.64, 48.41), NodeRect::new(286.08, 78.41, 97.64, 48.41), - NodeRect::new(148.04, 44.20, 97.64, 48.41), + NodeRect::new(148.04, 112.61, 97.64, 48.41), // was 44.20 NodeRect::new(10.00, 146.82, 97.64, 48.41), ]; /// The positions of the horizontal lines in the UI. static HORIZONTAL_LINES: [Line; 6] = [ - Line::new(107.64, 34.21, 20.20), + Line::new(107.64, 34.21, 158.24), Line::new(107.64, 102.61, 20.20), - Line::new(107.64, 171.02, 158.24), - Line::new(127.84, 68.41, 20.20), - Line::new(245.68, 68.41, 20.20), + Line::new(107.64, 171.02, 20.20), + Line::new(127.84, 136.82, 20.20), + Line::new(245.68, 136.82, 20.20), Line::new(265.88, 102.61, 20.20), ]; /// The positions of the vertical lines in the UI. static VERTICAL_LINES: [Line; 2] = [ - Line::new(127.83, 34.21, 68.40), - Line::new(265.88, 68.41, 102.61), + Line::new(127.83, 102.61, 68.40), + Line::new(265.88, 34.21, 102.61), ]; /// Initializes the app.