Animatable trait for interpolation and blending

crates/bevy_animation/src/animatable.rs

@@ -0,0 +1,221 @@
+use crate::util;
+use bevy_asset::{Asset, Assets, Handle, HandleId};
+use bevy_core::FloatOrd;
+use bevy_ecs::world::World;
+use bevy_math::*;
+use bevy_reflect::Reflect;
+use bevy_transform::prelude::Transform;
+
+/// An individual input for [`Animatable::blend`].
+pub struct BlendInput<T> {
+    /// The individual item's weight. This may not be bound to the range `[0.0, 1.0]`.
+    pub weight: f32,
+    /// The input value to be blended.
+    pub value: T,
+    /// Whether or not to additively blend this input into the final result.
+    pub additive: bool,
+}
+
+/// An animatable value type.
+pub trait Animatable: Reflect + Sized + Send + Sync + 'static {
+    /// Interpolates between two values of.
+    ///
+    /// The `time` parameter here may not be clamped to the range `[0.0, 1.0]`.
+    fn interpolate(a: &Self, b: &Self, time: f32) -> Self;
+
+    /// Blends one or more values together.
+    ///
+    /// Implementors should return a default value when no inputs are provided here.
+    fn blend(inputs: impl Iterator<Item = BlendInput<Self>>) -> Self;
+
+    /// Post-processes the value using resources in the [`World`].
+    /// Most animatable types do not need to implement this.
+    ///
+    /// # Safety
+    /// All concrete implementors of this function can only read
+    /// into the resources stored in the World. Mutation of any state,
+    /// or reading any component or [`NonSend`] resource data may cause
+    /// undefined behavior or data races.
+    ///
+    /// [`NonSend`]: bevy_ecs::system::NonSend
+    unsafe fn post_process(&mut self, _world: &World) {}
+}
+
+macro_rules! impl_float_animatable {
+    ($ty: ty, $base: ty) => {
+        impl Animatable for $ty {
+            #[inline(always)]
+            fn interpolate(a: &Self, b: &Self, t: f32) -> Self {
+                let t = <$base>::from(t);
+                (*a) * (1.0 - t) + (*b) * t
+            }
+
+            #[inline(always)]
+            fn blend(inputs: impl Iterator<Item = BlendInput<Self>>) -> Self {
+                let mut value = Default::default();
+                for input in inputs {
+                    if input.additive {
+                        value += <$base>::from(input.weight) * input.value;
+                    } else {
+                        value = Self::interpolate(&value, &input.value, input.weight);
+                    }
+                }
+                value
+            }
+        }
+    };
+}
+
+impl_float_animatable!(f32, f32);
+impl_float_animatable!(Vec2, f32);
+impl_float_animatable!(Vec3A, f32);
+impl_float_animatable!(Vec4, f32);
+
+impl_float_animatable!(f64, f64);
+impl_float_animatable!(DVec2, f64);
+impl_float_animatable!(DVec3, f64);
+impl_float_animatable!(DVec4, f64);
+
+// Vec3 is special cased to use Vec3A internally for blending
+impl Animatable for Vec3 {
+    #[inline(always)]
+    fn interpolate(a: &Self, b: &Self, t: f32) -> Self {
+        (*a) * (1.0 - t) + (*b) * t
+    }
+
+    #[inline(always)]
+    fn blend(inputs: impl Iterator<Item = BlendInput<Self>>) -> Self {
+        let mut value = Vec3A::ZERO;
+        for input in inputs {
+            if input.additive {
+                value += input.weight * Vec3A::from(input.value);
+            } else {
+                value = Vec3A::interpolate(&value, &Vec3A::from(input.value), input.weight);
+            }
+        }
+        Self::from(value)
+    }
+}
+
+impl Animatable for bool {
+    #[inline]
+    fn interpolate(a: &Self, b: &Self, t: f32) -> Self {
+        util::step_unclamped(*a, *b, t)
+    }
+
+    #[inline]
+    fn blend(inputs: impl Iterator<Item = BlendInput<Self>>) -> Self {
+        inputs
+            .max_by(|a, b| FloatOrd(a.weight).cmp(&FloatOrd(b.weight)))
+            .map(|input| input.value)
+            .unwrap_or(false)
+    }
+}
+
+impl Animatable for HandleId {
+    #[inline]
+    fn interpolate(a: &Self, b: &Self, t: f32) -> Self {
+        util::step_unclamped(*a, *b, t)
+    }
+
+    #[inline]
+    fn blend(inputs: impl Iterator<Item = BlendInput<Self>>) -> Self {
+        inputs
+            .max_by(|a, b| FloatOrd(a.weight).cmp(&FloatOrd(b.weight)))
+            .map(|input| input.value)
+            .expect("Attempted to blend HandleId with zero inputs.")
+    }
+}
+
+impl<T: Asset> Animatable for Handle<T> {
+    #[inline]
+    fn interpolate(a: &Self, b: &Self, t: f32) -> Self {
+        util::step_unclamped(a.clone_weak(), b.clone_weak(), t)
+    }
+
+    #[inline]
+    fn blend(inputs: impl Iterator<Item = BlendInput<Self>>) -> Self {
+        inputs
+            .max_by(|a, b| FloatOrd(a.weight).cmp(&FloatOrd(b.weight)))
+            .map(|input| input.value)
+            .expect("Attempted to blend Handle with zero inputs.")
+    }
+
+    // SAFE: This implementation only reads resources from the provided
+    // World.
+    unsafe fn post_process(&mut self, world: &World) {
+        // Upgrade weak handles into strong ones.
+        if self.is_strong() {
+            return;
+        }
+        *self = world
+            .get_resource::<Assets<T>>()
+            .expect(
+                "Attempted to animate a Handle<T> without the corresponding Assets<T> resource.",
+            )
+            .get_handle(self.id);
+    }
+}
+
+impl Animatable for Transform {
+    fn interpolate(a: &Self, b: &Self, t: f32) -> Self {
+        Self {
+            translation: Vec3::interpolate(&a.translation, &b.translation, t),
+            rotation: Quat::interpolate(&a.rotation, &b.rotation, t),
+            scale: Vec3::interpolate(&a.scale, &b.scale, t),
+        }
+    }
+
+    fn blend(inputs: impl Iterator<Item = BlendInput<Self>>) -> Self {
+        let mut translation = Vec3A::ZERO;
+        let mut scale = Vec3A::ZERO;
+        let mut rotation = Quat::IDENTITY;
+
+        for input in inputs {
+            if input.additive {
+                translation += input.weight * Vec3A::from(input.value.translation);
+                scale += input.weight * Vec3A::from(input.value.scale);
+                rotation = (input.value.rotation * input.weight) * rotation;
+            } else {
+                translation = Vec3A::interpolate(
+                    &translation,
+                    &Vec3A::from(input.value.translation),
+                    input.weight,
+                );
+                scale = Vec3A::interpolate(&scale, &Vec3A::from(input.value.scale), input.weight);
+                rotation = Quat::interpolate(&rotation, &input.value.rotation, input.weight);
+            }
+        }
+
+        Self {
+            translation: Vec3::from(translation),
+            rotation,
+            scale: Vec3::from(scale),
+        }
+    }
+}
+
+impl Animatable for Quat {
+    /// Performs an nlerp, because it's cheaper and easier to combine with other animations,
+    /// reference: <http://number-none.com/product/Understanding%20Slerp,%20Then%20Not%20Using%20It/>
+    #[inline]
+    fn interpolate(a: &Self, b: &Self, t: f32) -> Self {
+        // Make sure is always the short path, look at this: https://github.com/mgeier/quaternion-nursery
+        let b = if a.dot(*b) < 0.0 { -*b } else { *b };
+
+        let a: Vec4 = (*a).into();
+        let b: Vec4 = b.into();
+        let rot = Vec4::interpolate(&a, &b, t);
+        let inv_mag = util::approx_rsqrt(rot.dot(rot));
+        Quat::from_vec4(rot * inv_mag)
+    }
+
+    #[inline]
+    fn blend(inputs: impl Iterator<Item = BlendInput<Self>>) -> Self {
+        let mut value = Self::IDENTITY;
+        for input in inputs {
+            value = Self::interpolate(&value, &input.value, input.weight);
+        }
+        value
+    }
+}

crates/bevy_animation/src/lib.rs

@@ -2,6 +2,9 @@
 
 #![warn(missing_docs)]
 
+mod animatable;
+mod util;
+
 use std::ops::Deref;
 
 use bevy_app::{App, CoreStage, Plugin};
@@ -25,7 +28,8 @@ use bevy_utils::{tracing::warn, HashMap};
 pub mod prelude {
     #[doc(hidden)]
     pub use crate::{
-        AnimationClip, AnimationPlayer, AnimationPlugin, EntityPath, Keyframes, VariableCurve,
+        animatable::*, AnimationClip, AnimationPlayer, AnimationPlugin, EntityPath, Keyframes,
+        VariableCurve,
     };
 }
 

crates/bevy_animation/src/util.rs

@@ -0,0 +1,28 @@
+/// Fast approximated reciprocal square root.
+#[inline]
+pub(crate) fn approx_rsqrt(x: f32) -> f32 {
+    // Fall back to Quake 3 fast inverse sqrt, is has a higher error
+    // but still good enough and faster than `.sqrt().recip()`,
+    // implementation borrowed from Piston under the MIT License:
+    // [https://github.com/PistonDevelopers/skeletal_animation]
+    let x2: f32 = x * 0.5;
+    let mut y: f32 = x;
+
+    let mut i: i32 = y.to_bits() as i32;
+    i = 0x5f3759df - (i >> 1);
+    y = f32::from_bits(i as u32);
+
+    y = y * (1.5 - (x2 * y * y));
+    y
+}
+
+/// Steps between two different discrete values of any clonable type.
+/// Returns a copy of `b` if `t >= 1.0`, otherwise returns a copy of `b`.
+#[inline]
+pub(crate) fn step_unclamped<T>(a: T, b: T, t: f32) -> T {
+    if t >= 1.0 {
+        a
+    } else {
+        b
+    }
+}