Math for Curves and Interpolations (Lerp and Callmul-Rom)

Cargo.toml

@@ -481,6 +481,11 @@ crate-type = ["cdylib"]
 name = "android"
 path = "examples/android/android.rs"
 
+# Animation
+[[example]]
+name = "smooth_curves"
+path = "examples/animations/smooth_curves.rs"
+
 [package.metadata.android]
 apk_label = "Bevy Example"
 assets = "assets"

benches/Cargo.toml

@@ -9,6 +9,7 @@ edition = "2018"
 
 [dev-dependencies]
 criterion = "0.3"
+rand = "0.8.3"
 bevy = { path = "../" }
 
 [[bench]]
@@ -25,3 +26,8 @@ harness = false
 name = "iter"
 path = "benches/bevy_tasks/iter.rs"
 harness = false
+
+[[bench]]
+name = "curves"
+path = "benches/bevy_math/curves.rs"
+harness = false

benches/benches/bevy_math/curves.rs

@@ -0,0 +1,58 @@
+use bevy::math::{
+    curves::{Curve, KeyframeIndex, CurveVariable},
+    Vec4,
+};
+use criterion::{black_box, criterion_group, criterion_main, Criterion};
+use rand::prelude::*;
+
+criterion_group!(benches, curve_variable);
+criterion_main!(benches);
+
+const SAMPLES_COUNT: usize = 100;
+
+fn curve_sampling<T>(samples: &[f32], curve: &impl Curve<Output = T>) {
+    let mut c: KeyframeIndex = 0;
+    for t in samples {
+        let (nc, v) = curve.sample_with_cursor(c, *t);
+        black_box(v);
+        c = nc;
+    }
+}
+
+fn curve_variable(criterion: &mut Criterion) {
+    let mut group = criterion.benchmark_group("curve_variable");
+    group.warm_up_time(std::time::Duration::from_millis(500));
+    group.measurement_time(std::time::Duration::from_secs(3));
+
+    let curve = CurveVariable::with_auto_tangents(
+        vec![0.0, 1.0, 1.3, 1.6, 1.7, 1.8, 1.9, 2.0],
+        vec![3.0, 0.0, 1.0, 0.0, 0.5, 0.0, 0.25, 0.0]
+            .iter()
+            .map(|x| Vec4::splat(*x))
+            .collect::<Vec<_>>(),
+    )
+    .unwrap();
+
+    let duration = curve.duration();
+    let mut rand = rand::thread_rng();
+
+    let rand_samples = (0..SAMPLES_COUNT)
+        .into_iter()
+        .map(|_| duration * rand.gen::<f32>())
+        .collect::<Vec<_>>();
+
+    let samples = (0..SAMPLES_COUNT)
+        .into_iter()
+        .map(|i| duration * (i as f32) / (SAMPLES_COUNT - 1) as f32)
+        .collect::<Vec<_>>();
+
+    group.bench_function("random_sampling", |bencher| {
+        bencher.iter(|| black_box(curve_sampling(&rand_samples[..], &curve)));
+    });
+
+    group.bench_function("sampling", |bencher| {
+        bencher.iter(|| black_box(curve_sampling(&samples[..], &curve)));
+    });
+
+    group.finish()
+}

crates/bevy_asset/Cargo.toml

@@ -25,6 +25,7 @@ bevy_log = { path = "../bevy_log", version = "0.5.0" }
 bevy_reflect = { path = "../bevy_reflect", version = "0.5.0", features = ["bevy"] }
 bevy_tasks = { path = "../bevy_tasks", version = "0.5.0" }
 bevy_utils = { path = "../bevy_utils", version = "0.5.0" }
+bevy_math = { path = "../bevy_math", version = "0.5.0" }
 
 # other
 serde = { version = "1", features = ["derive"] }

crates/bevy_asset/src/handle.rs

@@ -10,6 +10,7 @@ use crate::{
     Asset, Assets,
 };
 use bevy_ecs::reflect::ReflectComponent;
+use bevy_math::interpolation::{utils::step_unclamped, Interpolate, Lerp, TangentIgnore};
 use bevy_reflect::{Reflect, ReflectDeserialize};
 use bevy_utils::Uuid;
 use crossbeam_channel::{Receiver, Sender};
@@ -230,6 +231,34 @@ impl<T: Asset> Clone for Handle<T> {
     }
 }
 
+impl<T: Asset + 'static> Lerp for Handle<T> {
+    #[inline(always)]
+    fn lerp_unclamped(a: &Self, b: &Self, t: f32) -> Self {
+        step_unclamped(a, b, t)
+    }
+}
+
+impl<T: Asset + 'static> Interpolate for Handle<T> {
+    type Tangent = TangentIgnore;
+    const FLAT_TANGENT: Self::Tangent = TangentIgnore;
+
+    fn interpolate_unclamped(
+        k0: &Self,
+        _: &Self::Tangent,
+        k1: &Self,
+        _: &Self::Tangent,
+        _: bevy_math::interpolation::Interpolation,
+        t: f32,
+        _: f32,
+    ) -> Self {
+        step_unclamped(k0, k1, t)
+    }
+
+    fn auto_tangent(_: f32, _: f32, _: f32, _: &Self, _: &Self, _: &Self) -> Self::Tangent {
+        TangentIgnore
+    }
+}
+
 /// A non-generic version of [Handle]
 ///
 /// This allows handles to be mingled in a cross asset context. For example, storing `Handle<A>` and
@@ -337,6 +366,34 @@ impl Clone for HandleUntyped {
     }
 }
 
+impl Lerp for HandleUntyped {
+    #[inline(always)]
+    fn lerp_unclamped(a: &Self, b: &Self, t: f32) -> Self {
+        step_unclamped(a, b, t)
+    }
+}
+
+impl Interpolate for HandleUntyped {
+    type Tangent = TangentIgnore;
+    const FLAT_TANGENT: Self::Tangent = TangentIgnore;
+
+    fn interpolate_unclamped(
+        k0: &Self,
+        _: &Self::Tangent,
+        k1: &Self,
+        _: &Self::Tangent,
+        _: bevy_math::interpolation::Interpolation,
+        t: f32,
+        _: f32,
+    ) -> Self {
+        step_unclamped(k0, k1, t)
+    }
+
+    fn auto_tangent(_: f32, _: f32, _: f32, _: &Self, _: &Self, _: &Self) -> Self::Tangent {
+        TangentIgnore
+    }
+}
+
 pub(crate) enum RefChange {
     Increment(HandleId),
     Decrement(HandleId),

crates/bevy_math/Cargo.toml

@@ -1,17 +1,18 @@
-[package]
-name = "bevy_math"
-version = "0.5.0"
-edition = "2018"
-authors = [
-    "Bevy Contributors <[email protected]>",
-    "Carter Anderson <[email protected]>",
-]
-description = "Provides math functionality for Bevy Engine"
-homepage = "https://bevyengine.org"
-repository = "https://github.com/bevyengine/bevy"
-license = "MIT"
-keywords = ["bevy"]
-
-[dependencies]
-glam = { version = "0.15.1", features = ["serde", "bytemuck"] }
-bevy_reflect = { path = "../bevy_reflect", version = "0.5.0", features = ["bevy"] }
+[package]
+name = "bevy_math"
+version = "0.5.0"
+edition = "2018"
+authors = [
+    "Bevy Contributors <[email protected]>",
+    "Carter Anderson <[email protected]>",
+]
+description = "Provides math functionality for Bevy Engine"
+homepage = "https://bevyengine.org"
+repository = "https://github.com/bevyengine/bevy"
+license = "MIT"
+keywords = ["bevy"]
+
+[dependencies]
+glam = { version = "0.15.1", features = ["serde", "bytemuck"] }
+bevy_reflect = { path = "../bevy_reflect", version = "0.5.0", features = ["bevy"] }
+thiserror = "1.0"

crates/bevy_math/src/curves/fixed.rs

@@ -0,0 +1,126 @@
+use crate::{
+    curves::{Curve, KeyframeIndex},
+    interpolation::Lerp,
+};
+
+// TODO: impl Serialize, Deserialize
+/// Curve with evenly spaced keyframes, in another words a curve with a fixed frame rate.
+///
+/// This curve maintains the faster sampling rate over a wide range of frame rates, because
+/// it doesn't rely on keyframe cursor. As a downside, it will have a bigger memory foot print.
+#[derive(Default, Debug, Clone)]
+pub struct CurveFixed<T: Lerp + Clone> {
+    /// Frames per second
+    frame_rate: f32,
+    /// Negative number of frames before the curve starts, it's stored
+    /// in a `f32` to avoid castings in the when sampling the curve and also
+    /// negated to use [`std::f32::mul_add`]
+    negative_frame_offset: f32,
+    pub keyframes: Vec<T>,
+}
+
+impl<T: Lerp + Clone> CurveFixed<T> {
+    pub fn from_keyframes(frame_rate: f32, frame_offset: i32, keyframes: Vec<T>) -> Self {
+        Self {
+            frame_rate,
+            negative_frame_offset: -(frame_offset as f32),
+            keyframes,
+        }
+    }
+
+    pub fn from_constant(v: T) -> Self {
+        Self {
+            frame_rate: 30.0,
+            negative_frame_offset: 0.0,
+            keyframes: vec![v],
+        }
+    }
+
+    #[inline]
+    pub fn frame_rate(&self) -> f32 {
+        self.frame_rate
+    }
+
+    #[inline]
+    pub fn set_frame_rate(&mut self, frame_rate: f32) {
+        self.frame_rate = frame_rate;
+    }
+
+    /// Sets the start keyframe index.
+    ///
+    /// Adds a starting delay in multiples of the frame duration `(1 / frame_rate)`
+    #[inline]
+    pub fn set_frame_offset(&mut self, offset: i32) {
+        self.negative_frame_offset = -offset as f32;
+    }
+
+    /// Number of the start keyframe
+    #[inline]
+    pub fn frame_offset(&self) -> i32 {
+        -self.negative_frame_offset as i32
+    }
+
+    /// `true` when this `CurveFixed` doesn't have any keyframe
+    #[inline]
+    pub fn is_empty(&self) -> bool {
+        self.len() == 0
+    }
+
+    #[inline]
+    pub fn iter(&self) -> impl Iterator<Item = &T> {
+        self.keyframes.iter()
+    }
+
+    #[inline]
+    pub fn iter_mut(&mut self) -> impl Iterator<Item = &mut T> {
+        self.keyframes.iter_mut()
+    }
+}
+
+impl<T: Lerp + Clone> Curve for CurveFixed<T> {
+    type Output = T;
+
+    fn duration(&self) -> f32 {
+        ((self.len() as f32 - 1.0 - self.negative_frame_offset) / self.frame_rate).max(0.0)
+    }
+
+    #[inline]
+    fn time_offset(&self) -> f32 {
+        -self.negative_frame_offset / self.frame_rate
+    }
+
+    #[inline]
+    fn len(&self) -> usize {
+        self.keyframes.len()
+    }
+
+    fn sample(&self, time: f32) -> Self::Output {
+        // Make sure to have at least one sample
+        assert!(!self.keyframes.is_empty(), "track is empty");
+
+        let t = time.mul_add(self.frame_rate, self.negative_frame_offset);
+        if t.is_sign_negative() {
+            // Underflow clamp
+            return self.keyframes[0].clone();
+        }
+
+        let f = t.trunc();
+        let t = t - f;
+
+        let f = f as usize;
+        let f_n = self.len() - 1;
+        if f >= f_n {
+            // Overflow clamp
+            return self.keyframes[f_n].clone();
+        }
+
+        // Lerp the value
+        T::lerp_unclamped(&self.keyframes[f], &self.keyframes[f + 1], t)
+    }
+
+    /// Same as the [`sample`] function
+    #[inline]
+    fn sample_with_cursor(&self, _: KeyframeIndex, time: f32) -> (KeyframeIndex, Self::Output) {
+        (0, self.sample(time))
+    }
+}