Skip to main content

rayengine_core/tween/
ease.rs

1//! Standard easing curves as pure functions of normalized progress.
2//!
3//! Every function clamps its input to `[0, 1]` (NaN counts as zero) and returns
4//! exactly `0.0` at the start and `1.0` at the end. Back and elastic curves
5//! deliberately overshoot between the endpoints.
6
7use std::f32::consts::PI;
8
9const BACK: f32 = 1.70158;
10const BACK_IN_OUT: f32 = BACK * 1.525;
11
12/// Clamps progress and pins both endpoints so curves never drift at boundaries.
13#[inline]
14fn bounded(t: f32, curve: impl FnOnce(f32) -> f32) -> f32 {
15    if t.is_nan() || t <= 0.0 {
16        0.0
17    } else if t >= 1.0 {
18        1.0
19    } else {
20        curve(t)
21    }
22}
23
24/// Constant rate.
25pub fn linear(t: f32) -> f32 {
26    bounded(t, |t| t)
27}
28
29/// Quadratic acceleration from rest.
30pub fn quad_in(t: f32) -> f32 {
31    bounded(t, |t| t * t)
32}
33/// Quadratic deceleration to rest.
34pub fn quad_out(t: f32) -> f32 {
35    bounded(t, |t| 1.0 - (1.0 - t) * (1.0 - t))
36}
37/// Quadratic acceleration, then deceleration.
38pub fn quad_in_out(t: f32) -> f32 {
39    bounded(t, |t| {
40        if t < 0.5 {
41            2.0 * t * t
42        } else {
43            1.0 - (-2.0 * t + 2.0).powi(2) / 2.0
44        }
45    })
46}
47
48/// Cubic acceleration from rest.
49pub fn cubic_in(t: f32) -> f32 {
50    bounded(t, |t| t * t * t)
51}
52/// Cubic deceleration to rest.
53pub fn cubic_out(t: f32) -> f32 {
54    bounded(t, |t| 1.0 - (1.0 - t).powi(3))
55}
56/// Cubic acceleration, then deceleration.
57pub fn cubic_in_out(t: f32) -> f32 {
58    bounded(t, |t| {
59        if t < 0.5 {
60            4.0 * t * t * t
61        } else {
62            1.0 - (-2.0 * t + 2.0).powi(3) / 2.0
63        }
64    })
65}
66
67/// Quarter-sine acceleration from rest.
68pub fn sine_in(t: f32) -> f32 {
69    bounded(t, |t| 1.0 - (t * PI / 2.0).cos())
70}
71/// Quarter-sine deceleration to rest.
72pub fn sine_out(t: f32) -> f32 {
73    bounded(t, |t| (t * PI / 2.0).sin())
74}
75/// Half-cosine acceleration, then deceleration.
76pub fn sine_in_out(t: f32) -> f32 {
77    bounded(t, |t| -((PI * t).cos() - 1.0) / 2.0)
78}
79
80/// Exponential acceleration (base 2, ten doublings).
81pub fn expo_in(t: f32) -> f32 {
82    bounded(t, |t| 2f32.powf(10.0 * t - 10.0))
83}
84/// Exponential deceleration (base 2, ten halvings).
85pub fn expo_out(t: f32) -> f32 {
86    bounded(t, |t| 1.0 - 2f32.powf(-10.0 * t))
87}
88/// Exponential acceleration, then deceleration.
89pub fn expo_in_out(t: f32) -> f32 {
90    bounded(t, |t| {
91        if t < 0.5 {
92            2f32.powf(20.0 * t - 10.0) / 2.0
93        } else {
94            (2.0 - 2f32.powf(-20.0 * t + 10.0)) / 2.0
95        }
96    })
97}
98
99/// Pulls back below zero before accelerating.
100pub fn back_in(t: f32) -> f32 {
101    bounded(t, |t| (BACK + 1.0) * t * t * t - BACK * t * t)
102}
103/// Overshoots above one before settling.
104pub fn back_out(t: f32) -> f32 {
105    bounded(t, |t| {
106        let u = t - 1.0;
107        1.0 + (BACK + 1.0) * u * u * u + BACK * u * u
108    })
109}
110/// Pulls back at the start and overshoots at the end.
111pub fn back_in_out(t: f32) -> f32 {
112    bounded(t, |t| {
113        if t < 0.5 {
114            (2.0 * t).powi(2) * ((BACK_IN_OUT + 1.0) * 2.0 * t - BACK_IN_OUT) / 2.0
115        } else {
116            ((2.0 * t - 2.0).powi(2) * ((BACK_IN_OUT + 1.0) * (t * 2.0 - 2.0) + BACK_IN_OUT) + 2.0)
117                / 2.0
118        }
119    })
120}
121
122/// Growing oscillation before release.
123pub fn elastic_in(t: f32) -> f32 {
124    bounded(t, |t| {
125        -2f32.powf(10.0 * t - 10.0) * ((t * 10.0 - 10.75) * (2.0 * PI / 3.0)).sin()
126    })
127}
128/// Decaying oscillation around the target.
129pub fn elastic_out(t: f32) -> f32 {
130    bounded(t, |t| {
131        2f32.powf(-10.0 * t) * ((t * 10.0 - 0.75) * (2.0 * PI / 3.0)).sin() + 1.0
132    })
133}
134/// Growing, then decaying oscillation.
135pub fn elastic_in_out(t: f32) -> f32 {
136    bounded(t, |t| {
137        let wave = ((20.0 * t - 11.125) * (2.0 * PI / 4.5)).sin();
138        if t < 0.5 {
139            -(2f32.powf(20.0 * t - 10.0) * wave) / 2.0
140        } else {
141            2f32.powf(-20.0 * t + 10.0) * wave / 2.0 + 1.0
142        }
143    })
144}
145
146/// Bounces that grow before leaving the start.
147pub fn bounce_in(t: f32) -> f32 {
148    bounded(t, |t| 1.0 - bounce(1.0 - t))
149}
150/// Decaying bounces against the target.
151pub fn bounce_out(t: f32) -> f32 {
152    bounded(t, bounce)
153}
154/// Growing bounces, then decaying bounces.
155pub fn bounce_in_out(t: f32) -> f32 {
156    bounded(t, |t| {
157        if t < 0.5 {
158            (1.0 - bounce(1.0 - 2.0 * t)) / 2.0
159        } else {
160            (1.0 + bounce(2.0 * t - 1.0)) / 2.0
161        }
162    })
163}
164
165fn bounce(t: f32) -> f32 {
166    const N: f32 = 7.5625;
167    const D: f32 = 2.75;
168    if t < 1.0 / D {
169        N * t * t
170    } else if t < 2.0 / D {
171        let t = t - 1.5 / D;
172        N * t * t + 0.75
173    } else if t < 2.5 / D {
174        let t = t - 2.25 / D;
175        N * t * t + 0.9375
176    } else {
177        let t = t - 2.625 / D;
178        N * t * t + 0.984375
179    }
180}
181
182/// A copyable selection of one easing function, stored by tweens without boxing.
183///
184/// ```
185/// use rayengine_core::tween::Ease;
186/// assert_eq!(Ease::CubicOut.apply(1.0), 1.0);
187/// assert_eq!(Ease::Linear.apply(0.25), 0.25);
188/// assert!(Ease::BackOut.apply(0.6) > 1.0); // overshoots before settling
189/// ```
190#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)]
191#[allow(missing_docs)]
192pub enum Ease {
193    #[default]
194    Linear,
195    QuadIn,
196    QuadOut,
197    QuadInOut,
198    CubicIn,
199    CubicOut,
200    CubicInOut,
201    SineIn,
202    SineOut,
203    SineInOut,
204    ExpoIn,
205    ExpoOut,
206    ExpoInOut,
207    BackIn,
208    BackOut,
209    BackInOut,
210    ElasticIn,
211    ElasticOut,
212    ElasticInOut,
213    BounceIn,
214    BounceOut,
215    BounceInOut,
216}
217
218impl Ease {
219    /// Every curve, in declaration order.
220    pub const ALL: [Ease; 22] = [
221        Ease::Linear,
222        Ease::QuadIn,
223        Ease::QuadOut,
224        Ease::QuadInOut,
225        Ease::CubicIn,
226        Ease::CubicOut,
227        Ease::CubicInOut,
228        Ease::SineIn,
229        Ease::SineOut,
230        Ease::SineInOut,
231        Ease::ExpoIn,
232        Ease::ExpoOut,
233        Ease::ExpoInOut,
234        Ease::BackIn,
235        Ease::BackOut,
236        Ease::BackInOut,
237        Ease::ElasticIn,
238        Ease::ElasticOut,
239        Ease::ElasticInOut,
240        Ease::BounceIn,
241        Ease::BounceOut,
242        Ease::BounceInOut,
243    ];
244
245    /// The pure function for this curve.
246    pub fn function(self) -> fn(f32) -> f32 {
247        match self {
248            Ease::Linear => linear,
249            Ease::QuadIn => quad_in,
250            Ease::QuadOut => quad_out,
251            Ease::QuadInOut => quad_in_out,
252            Ease::CubicIn => cubic_in,
253            Ease::CubicOut => cubic_out,
254            Ease::CubicInOut => cubic_in_out,
255            Ease::SineIn => sine_in,
256            Ease::SineOut => sine_out,
257            Ease::SineInOut => sine_in_out,
258            Ease::ExpoIn => expo_in,
259            Ease::ExpoOut => expo_out,
260            Ease::ExpoInOut => expo_in_out,
261            Ease::BackIn => back_in,
262            Ease::BackOut => back_out,
263            Ease::BackInOut => back_in_out,
264            Ease::ElasticIn => elastic_in,
265            Ease::ElasticOut => elastic_out,
266            Ease::ElasticInOut => elastic_in_out,
267            Ease::BounceIn => bounce_in,
268            Ease::BounceOut => bounce_out,
269            Ease::BounceInOut => bounce_in_out,
270        }
271    }
272
273    /// Eases clamped progress; exactly `0.0` at the start and `1.0` at the end.
274    pub fn apply(self, t: f32) -> f32 {
275        self.function()(t)
276    }
277}