Eliminate redundant clamping from sample-interpolated curves (#15620)

# Objective

Currently, sample-interpolated curves (such as those used by the glTF
loader for animations) do unnecessary extra work when `sample_clamped`
is called, since their implementations of `sample_unchecked` are already
clamped. Eliminating this redundant sampling is a small, easy
performance win which doesn't compromise on the animation system's
internal usage of `sample_clamped`, which guarantees that it never
samples curves out-of-bounds.

## Solution

For sample-interpolated curves, define `sample_clamped` in the way
`sample_unchecked` is currently defined, and then redirect
`sample_unchecked` to `sample_clamped`. This is arguably a more
idiomatic way of using the `cores` as well, which is nice.

## Testing

Ran `many_foxes` to make sure I didn't break anything.

crates/bevy_animation/src/animation_curves.rs

@@ -1021,14 +1021,14 @@ where
     }
 
     #[inline]
-    fn sample_unchecked(&self, t: f32) -> T {
+    fn sample_clamped(&self, t: f32) -> T {
+        // `UnevenCore::sample_with` is implicitly clamped.
         self.core.sample_with(t, <T as Animatable>::interpolate)
     }
 
     #[inline]
-    fn sample_clamped(&self, t: f32) -> T {
+    fn sample_unchecked(&self, t: f32) -> T {
-        // Sampling by keyframes is automatically clamped to the keyframe bounds.
+        self.sample_clamped(t)
-        self.sample_unchecked(t)
     }
 }
 

crates/bevy_animation/src/gltf_curves.rs

@@ -23,10 +23,15 @@ where
     }
 
     #[inline]
-    fn sample_unchecked(&self, t: f32) -> T {
+    fn sample_clamped(&self, t: f32) -> T {
         self.core
             .sample_with(t, |x, y, t| if t >= 1.0 { y.clone() } else { x.clone() })
     }
+
+    #[inline]
+    fn sample_unchecked(&self, t: f32) -> T {
+        self.sample_clamped(t)
+    }
 }
 
 impl<T> SteppedKeyframeCurve<T> {
@@ -57,7 +62,7 @@ where
     }
 
     #[inline]
-    fn sample_unchecked(&self, t: f32) -> V {
+    fn sample_clamped(&self, t: f32) -> V {
         match self.core.sample_interp_timed(t) {
             // In all the cases where only one frame matters, defer to the position within it.
             InterpolationDatum::Exact((_, v))
@@ -69,6 +74,11 @@ where
             }
         }
     }
+
+    #[inline]
+    fn sample_unchecked(&self, t: f32) -> V {
+        self.sample_clamped(t)
+    }
 }
 
 impl<T> CubicKeyframeCurve<T> {
@@ -112,7 +122,7 @@ impl Curve<Quat> for CubicRotationCurve {
     }
 
     #[inline]
-    fn sample_unchecked(&self, t: f32) -> Quat {
+    fn sample_clamped(&self, t: f32) -> Quat {
         let vec = match self.core.sample_interp_timed(t) {
             // In all the cases where only one frame matters, defer to the position within it.
             InterpolationDatum::Exact((_, v))
@@ -125,6 +135,11 @@ impl Curve<Quat> for CubicRotationCurve {
         };
         Quat::from_vec4(vec.normalize())
     }
+
+    #[inline]
+    fn sample_unchecked(&self, t: f32) -> Quat {
+        self.sample_clamped(t)
+    }
 }
 
 impl CubicRotationCurve {
@@ -170,7 +185,7 @@ where
     }
 
     #[inline]
-    fn sample_iter_unchecked(&self, t: f32) -> impl Iterator<Item = T> {
+    fn sample_iter_clamped(&self, t: f32) -> impl Iterator<Item = T> {
         match self.core.sample_interp(t) {
             InterpolationDatum::Exact(v)
             | InterpolationDatum::LeftTail(v)
@@ -182,6 +197,11 @@ where
             }
         }
     }
+
+    #[inline]
+    fn sample_iter_unchecked(&self, t: f32) -> impl Iterator<Item = T> {
+        self.sample_iter_clamped(t)
+    }
 }
 
 impl<T> WideLinearKeyframeCurve<T> {
@@ -219,7 +239,7 @@ where
     }
 
     #[inline]
-    fn sample_iter_unchecked(&self, t: f32) -> impl Iterator<Item = T> {
+    fn sample_iter_clamped(&self, t: f32) -> impl Iterator<Item = T> {
         match self.core.sample_interp(t) {
             InterpolationDatum::Exact(v)
             | InterpolationDatum::LeftTail(v)
@@ -234,6 +254,11 @@ where
             }
         }
     }
+
+    #[inline]
+    fn sample_iter_unchecked(&self, t: f32) -> impl Iterator<Item = T> {
+        self.sample_iter_clamped(t)
+    }
 }
 
 impl<T> WideSteppedKeyframeCurve<T> {
@@ -269,7 +294,7 @@ where
         self.core.domain()
     }
 
-    fn sample_iter_unchecked(&self, t: f32) -> impl Iterator<Item = T> {
+    fn sample_iter_clamped(&self, t: f32) -> impl Iterator<Item = T> {
         match self.core.sample_interp_timed(t) {
             InterpolationDatum::Exact((_, v))
             | InterpolationDatum::LeftTail((_, v))
@@ -285,6 +310,11 @@ where
             ),
         }
     }
+
+    #[inline]
+    fn sample_iter_unchecked(&self, t: f32) -> impl Iterator<Item = T> {
+        self.sample_iter_clamped(t)
+    }
 }
 
 /// An error indicating that a multisampling keyframe curve could not be constructed.

crates/bevy_color/src/color_gradient.rs

@@ -54,13 +54,21 @@ impl<T> Curve<T> for ColorCurve<T>
 where
     T: Mix + Clone,
 {
+    #[inline]
     fn domain(&self) -> Interval {
         self.core.domain()
     }
 
-    fn sample_unchecked(&self, t: f32) -> T {
+    #[inline]
+    fn sample_clamped(&self, t: f32) -> T {
+        // `EvenCore::sample_with` clamps the input implicitly.
         self.core.sample_with(t, T::mix)
     }
+
+    #[inline]
+    fn sample_unchecked(&self, t: f32) -> T {
+        self.sample_clamped(t)
+    }
 }
 
 #[cfg(test)]

crates/bevy_math/src/curve/sample_curves.rs

@@ -94,9 +94,15 @@ where
     }
 
     #[inline]
-    fn sample_unchecked(&self, t: f32) -> T {
+    fn sample_clamped(&self, t: f32) -> T {
+        // `EvenCore::sample_with` is implicitly clamped.
         self.core.sample_with(t, &self.interpolation)
     }
+
+    #[inline]
+    fn sample_unchecked(&self, t: f32) -> T {
+        self.sample_clamped(t)
+    }
 }
 
 impl<T, I> SampleCurve<T, I> {
@@ -143,10 +149,16 @@ where
     }
 
     #[inline]
-    fn sample_unchecked(&self, t: f32) -> T {
+    fn sample_clamped(&self, t: f32) -> T {
+        // `EvenCore::sample_with` is implicitly clamped.
         self.core
             .sample_with(t, <T as StableInterpolate>::interpolate_stable)
     }
+
+    #[inline]
+    fn sample_unchecked(&self, t: f32) -> T {
+        self.sample_clamped(t)
+    }
 }
 
 impl<T> SampleAutoCurve<T> {
@@ -242,9 +254,15 @@ where
     }
 
     #[inline]
-    fn sample_unchecked(&self, t: f32) -> T {
+    fn sample_clamped(&self, t: f32) -> T {
+        // `UnevenCore::sample_with` is implicitly clamped.
         self.core.sample_with(t, &self.interpolation)
     }
+
+    #[inline]
+    fn sample_unchecked(&self, t: f32) -> T {
+        self.sample_clamped(t)
+    }
 }
 
 impl<T, I> UnevenSampleCurve<T, I> {
@@ -301,10 +319,16 @@ where
     }
 
     #[inline]
-    fn sample_unchecked(&self, t: f32) -> T {
+    fn sample_clamped(&self, t: f32) -> T {
+        // `UnevenCore::sample_with` is implicitly clamped.
         self.core
             .sample_with(t, <T as StableInterpolate>::interpolate_stable)
     }
+
+    #[inline]
+    fn sample_unchecked(&self, t: f32) -> T {
+        self.sample_clamped(t)
+    }
 }
 
 impl<T> UnevenSampleAutoCurve<T> {