Curve-based animation

[mweatherley]

Objective

This PR extends and reworks the material from #15282 by allowing arbitrary curves to be used by the animation system to animate arbitrary properties. The goals of this work are to:

• Allow far greater flexibility in how animations are allowed to be defined in order to be used with bevy_animation.
• Delegate responsibility over keyframe interpolation to bevy_math and the Curve libraries and reduce reliance on keyframes in animation definitions generally.
• Move away from allowing the glTF spec to completely define animations on a mechanical level.

Solution

Overview

At a high level, curves have been incorporated into the animation system using the AnimationCurve trait (closely related to what was Keyframes). From the top down:

1. In animate_targets, animations are driven by VariableCurve, which is now a thin wrapper around a Box<dyn AnimationCurve>.
2. AnimationCurve is something built out of a Curve, and it tells the animation system how to use the curve's output to actually mutate component properties. The trait looks like this:

/// A low-level trait that provides control over how curves are actually applied to entities
/// by the animation system.
///
/// Typically, this will not need to be implemented manually, since it is automatically
/// implemented by [`AnimatableCurve`] and other curves used by the animation system
/// (e.g. those that animate parts of transforms or morph weights). However, this can be
/// implemented manually when `AnimatableCurve` is not sufficiently expressive.
///
/// In many respects, this behaves like a type-erased form of [`Curve`], where the output
/// type of the curve is remembered only in the components that are mutated in the
/// implementation of [`apply`].
///
/// [`apply`]: AnimationCurve::apply
pub trait AnimationCurve: Reflect + Debug + Send + Sync {
    /// Returns a boxed clone of this value.
    fn clone_value(&self) -> Box<dyn AnimationCurve>;

    /// The range of times for which this animation is defined.
    fn domain(&self) -> Interval;

    /// Write the value of sampling this curve at time `t` into `transform` or `entity`,
    /// as appropriate, interpolating between the existing value and the sampled value
    /// using the given `weight`.
    fn apply<'a>(
        &self,
        t: f32,
        transform: Option<Mut<'a, Transform>>,
        entity: EntityMutExcept<'a, (Transform, AnimationPlayer, Handle<AnimationGraph>)>,
        weight: f32,
    ) -> Result<(), AnimationEvaluationError>;
}

3. The conversion process from a Curve to an AnimationCurve involves using wrappers which communicate the intent to animate a particular property. For example, here is TranslationCurve, which wraps a Curve<Vec3> and uses it to animate Transform::translation:

/// This type allows a curve valued in `Vec3` to become an [`AnimationCurve`] that animates
/// the translation component of a transform.
pub struct TranslationCurve<C>(pub C);

Animatable Properties

The AnimatableProperty trait survives in the transition, and it can be used to allow curves to animate arbitrary component properties. The updated documentation for AnimatableProperty explains this process:

Expand AnimatableProperty example

An AnimatableProperty is a value on a component that Bevy can animate.

You can implement this trait on a unit struct in order to support animating
custom components other than transforms and morph weights. Use that type in
conjunction with AnimatableCurve (and perhaps AnimatableKeyframeCurve
to define the animation itself). For example, in order to animate font size of a
text section from 24 pt. to 80 pt., you might use:

#[derive(Reflect)]
struct FontSizeProperty;

impl AnimatableProperty for FontSizeProperty {
    type Component = Text;
    type Property = f32;
    fn get_mut(component: &mut Self::Component) -> Option<&mut Self::Property> {
        Some(&mut component.sections.get_mut(0)?.style.font_size)
    }
}

You can then create an AnimationClip to animate this property like so:

let mut animation_clip = AnimationClip::default();
animation_clip.add_curve_to_target(
    animation_target_id,
    AnimatableKeyframeCurve::new(
        [
            (0.0, 24.0),
            (1.0, 80.0),
        ]
    )
    .map(AnimatableCurve::<FontSizeProperty, _>::from_curve)
    .expect("Failed to create font size curve")
);

Here, the use of AnimatableKeyframeCurve creates a curve out of the given keyframe time-value
pairs, using the Animatable implementation of f32 to interpolate between them. The
invocation of AnimatableCurve::from_curve with FontSizeProperty indicates that the f32
output from that curve is to be used to animate the font size of a Text component (as
configured above).

glTF Loading

glTF animations are now loaded into Curve types of various kinds, depending on what is being animated and what interpolation mode is being used. Those types get wrapped into and converted into Box<dyn AnimationCurve> and shoved inside of a VariableCurve just like everybody else.

Morph Weights

There is an IterableCurve abstraction which allows sampling these from a contiguous buffer without allocating. Its only reason for existing is that Rust disallows you from naming function types, otherwise we would just use Curve with an iterator output type. (The iterator involves Map, and the name of the function type would have to be able to be named, but it is not.)

A WeightsCurve adaptor turns an IterableCurve into an AnimationCurve, so it behaves like everything else in that regard.

Testing

Tested by running existing animation examples. Interpolation logic has had additional tests added within the Curve API to replace the tests in bevy_animation. Some kinds of out-of-bounds errors have become impossible.

Performance testing on many_foxes (animate_targets) suggests that performance is very similar to the existing implementation. Here are a couple trace histograms across different runs (yellow is this branch, red is main).

---

Migration Guide

Most user code that does not directly deal with AnimationClip and VariableCurve will not need to be changed. On the other hand, VariableCurve has been completely overhauled. If you were previously defining animation curves in code using keyframes, you will need to migrate that code to use curve constructors instead. For example, a rotation animation defined using keyframes and added to an animation clip like this:

animation_clip.add_curve_to_target(
    animation_target_id,
    VariableCurve {
        keyframe_timestamps: vec![0.0, 1.0, 2.0, 3.0, 4.0],
        keyframes: Keyframes::Rotation(vec![
            Quat::IDENTITY,
            Quat::from_axis_angle(Vec3::Y, PI / 2.),
            Quat::from_axis_angle(Vec3::Y, PI / 2. * 2.),
            Quat::from_axis_angle(Vec3::Y, PI / 2. * 3.),
            Quat::IDENTITY,
        ]),
        interpolation: Interpolation::Linear,
    },
);

would now be added like this:

animation_clip.add_curve_to_target(
    animation_target_id,
    AnimatableKeyframeCurve::new([0.0, 1.0, 2.0, 3.0, 4.0].into_iter().zip([
        Quat::IDENTITY,
        Quat::from_axis_angle(Vec3::Y, PI / 2.),
        Quat::from_axis_angle(Vec3::Y, PI / 2. * 2.),
        Quat::from_axis_angle(Vec3::Y, PI / 2. * 3.),
        Quat::IDENTITY,
    ]))
    .map(RotationCurve)
    .expect("Failed to build rotation curve"),
);

Note that the interface of AnimationClip::add_curve_to_target has also changed (as this example shows, if subtly), and now takes its curve input as an impl AnimationCurve. If you need to add a VariableCurve directly, a new method add_variable_curve_to_target accommodates that (and serves as a one-to-one migration in this regard).

For reviewers

The diff is pretty big, and the structure of some of the changes might not be super-obvious:

• keyframes.rs became animation_curves.rs, and AnimationCurve is based heavily on Keyframes, with the adaptors also largely following suite.
• The Curve API adaptor structs were moved from bevy_math::curve::mod into their own module adaptors. There are no functional changes to how these adaptors work; this is just to make room for the specialized reflection implementations since mod.rs was getting kind of cramped.
• The new module gltf_curves holds the additional curve constructions that are needed by the glTF loader. Note that the loader uses a mix of these and off-the-shelf bevy_math curve stuff.
• animatable.rs no longer holds logic related to keyframe interpolation, which is now delegated to the existing abstractions in bevy_math::curve::cores.

[NthTensor]

Skimmed this over and it looks fantastic! We probably do need to profile this a bit before merge just because animation perf tends to be so sensitive to small changes, so consider this a conditional approval. I'm also getting the tracy mismatch error, I'll post if I figure out out.

[mweatherley]

Added some tracing results.

(There is also an easy but small perf win available and untaken, which is special-casing sample_clamped for keyframe curves, avoiding some redundant operations. As I recall from an old version of this glTF transition, the impact is small but measurable.)

[alice-i-cecile]

Delightful. I really like the API, the general direction, and especially the detailed, conversational docs. Merging.

[alice-i-cecile]

Thank you to everyone involved with the authoring or reviewing of this PR! This work is relatively important and needs release notes! Head over to bevyengine/bevy-website#1708 if you'd like to help out.