#[derive(Debug, Clone, Copy, PartialEq, Default)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[non_exhaustive]
pub enum OverlayEasing {
#[default]
Linear,
EaseIn,
EaseOut,
EaseInOut,
Pulse,
Back,
Bounce,
Elastic,
CubicBezier {
x1: f32,
y1: f32,
x2: f32,
y2: f32,
},
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
#[non_exhaustive]
pub enum RepeatMode {
#[default]
Once,
Loop,
PingPong,
}
#[derive(Debug, Clone, Copy, PartialEq)]
#[non_exhaustive]
pub struct AnimTrack<T: Copy> {
pub start_time: f64,
pub duration: f32,
pub from: T,
pub to: T,
pub easing: OverlayEasing,
pub repeat: RepeatMode,
}
impl<T: Copy + Default> Default for AnimTrack<T> {
fn default() -> Self {
Self {
start_time: 0.0,
duration: 1.0,
from: T::default(),
to: T::default(),
easing: OverlayEasing::Linear,
repeat: RepeatMode::Once,
}
}
}
#[derive(Debug, Clone, PartialEq, Default)]
#[non_exhaustive]
pub struct OverlayAnimations {
pub epoch: f64,
pub opacity: Option<AnimTrack<f32>>,
pub translate: Option<AnimTrack<[f32; 2]>>,
pub rotation: Option<AnimTrack<f32>>,
pub scale: Option<AnimTrack<f32>>,
pub tint: Option<AnimTrack<[f32; 4]>>,
}
impl OverlayAnimations {
pub fn with_epoch(mut self, epoch: f64) -> Self {
self.epoch = epoch;
self
}
pub fn with_opacity(mut self, track: AnimTrack<f32>) -> Self {
self.opacity = Some(track);
self
}
pub fn with_translate(mut self, track: AnimTrack<[f32; 2]>) -> Self {
self.translate = Some(track);
self
}
pub fn with_rotation(mut self, track: AnimTrack<f32>) -> Self {
self.rotation = Some(track);
self
}
pub fn with_scale(mut self, track: AnimTrack<f32>) -> Self {
self.scale = Some(track);
self
}
pub fn with_tint(mut self, track: AnimTrack<[f32; 4]>) -> Self {
self.tint = Some(track);
self
}
pub fn apply(
&self,
time: f64,
transform: &mut crate::overlay::OverlayTransform,
opacity: &mut f32,
tint: &mut [f32; 4],
) {
let t = time - self.epoch;
if let Some(track) = self.opacity {
*opacity = track.sample(t);
}
if let Some(track) = self.translate {
transform.translate = track.sample(t);
}
if let Some(track) = self.rotation {
transform.rotation = track.sample(t);
}
if let Some(track) = self.scale {
transform.scale = track.sample(t);
}
if let Some(track) = self.tint {
*tint = track.sample(t);
}
}
pub fn is_empty(&self) -> bool {
self.opacity.is_none()
&& self.translate.is_none()
&& self.rotation.is_none()
&& self.scale.is_none()
&& self.tint.is_none()
}
}
pub trait LerpAnim: Copy {
fn lerp(from: Self, to: Self, t: f32) -> Self;
}
impl LerpAnim for f32 {
fn lerp(from: Self, to: Self, t: f32) -> Self {
from * (1.0 - t) + to * t
}
}
impl LerpAnim for [f32; 2] {
fn lerp(from: Self, to: Self, t: f32) -> Self {
[f32::lerp(from[0], to[0], t), f32::lerp(from[1], to[1], t)]
}
}
impl LerpAnim for [f32; 4] {
fn lerp(from: Self, to: Self, t: f32) -> Self {
[
f32::lerp(from[0], to[0], t),
f32::lerp(from[1], to[1], t),
f32::lerp(from[2], to[2], t),
f32::lerp(from[3], to[3], t),
]
}
}
impl<T: Copy> AnimTrack<T> {
pub fn new(start_time: f64, duration: f32, from: T, to: T) -> Self {
Self {
start_time,
duration,
from,
to,
easing: OverlayEasing::Linear,
repeat: RepeatMode::Once,
}
}
pub fn with_easing(mut self, easing: OverlayEasing) -> Self {
self.easing = easing;
self
}
pub fn with_repeat(mut self, repeat: RepeatMode) -> Self {
self.repeat = repeat;
self
}
pub fn with_start_time(mut self, start_time: f64) -> Self {
self.start_time = start_time;
self
}
}
impl<T: Copy + LerpAnim> AnimTrack<T> {
pub fn sample_from(&self, time: f64, epoch: f64) -> T {
self.sample(time - epoch)
}
pub fn sample(&self, time: f64) -> T {
if self.duration <= 0.0 {
return self.to;
}
let raw = ((time - self.start_time) as f32) / self.duration;
let phase = resolve_phase(raw, self.repeat);
let t = apply_easing(phase, self.easing);
T::lerp(self.from, self.to, t)
}
}
fn resolve_phase(raw: f32, repeat: RepeatMode) -> f32 {
match repeat {
RepeatMode::Once => raw.clamp(0.0, 1.0),
RepeatMode::Loop => {
let f = raw - raw.floor();
if f < 0.0 { f + 1.0 } else { f }
}
RepeatMode::PingPong => {
let two = (raw * 0.5).floor() * 2.0;
let r = raw - two;
if r > 1.0 { 2.0 - r } else { r }
}
}
}
fn bezier_axis(t: f32, a: f32, b: f32) -> f32 {
let u = 1.0 - t;
3.0 * u * u * t * a + 3.0 * u * t * t * b + t * t * t
}
fn bezier_axis_slope(t: f32, a: f32, b: f32) -> f32 {
let u = 1.0 - t;
3.0 * u * u * a + 6.0 * u * t * (b - a) + 3.0 * t * t * (1.0 - b)
}
fn cubic_bezier_ease(x: f32, x1: f32, y1: f32, x2: f32, y2: f32) -> f32 {
let x1 = x1.clamp(0.0, 1.0);
let x2 = x2.clamp(0.0, 1.0);
if x <= 0.0 {
return 0.0;
}
if x >= 1.0 {
return 1.0;
}
let mut t = x;
for _ in 0..8 {
let err = bezier_axis(t, x1, x2) - x;
if err.abs() < 1e-5 {
return bezier_axis(t, y1, y2);
}
let slope = bezier_axis_slope(t, x1, x2);
if slope.abs() < 1e-6 {
break;
}
t -= err / slope;
}
let (mut lo, mut hi) = (0.0f32, 1.0f32);
let mut t = x;
for _ in 0..24 {
let cx = bezier_axis(t, x1, x2);
if (cx - x).abs() < 1e-5 {
break;
}
if cx < x {
lo = t;
} else {
hi = t;
}
t = (lo + hi) * 0.5;
}
bezier_axis(t, y1, y2)
}
fn bounce_ease(t: f32) -> f32 {
const N: f32 = 7.5625;
const D: f32 = 2.75;
if t < 1.0 / D {
N * t * t
} else if t < 2.0 / D {
let t = t - 1.5 / D;
N * t * t + 0.75
} else if t < 2.5 / D {
let t = t - 2.25 / D;
N * t * t + 0.9375
} else {
let t = t - 2.625 / D;
N * t * t + 0.984375
}
}
fn apply_easing(phase: f32, easing: OverlayEasing) -> f32 {
match easing {
OverlayEasing::Linear => phase,
OverlayEasing::EaseIn => phase * phase,
OverlayEasing::EaseOut => {
let inv = 1.0 - phase;
1.0 - inv * inv
}
OverlayEasing::EaseInOut => phase * phase * (3.0 - 2.0 * phase),
OverlayEasing::Pulse => (phase * std::f32::consts::PI).sin(),
OverlayEasing::Back => cubic_bezier_ease(phase, 0.68, -0.55, 0.265, 1.55),
OverlayEasing::Bounce => bounce_ease(phase),
OverlayEasing::Elastic => {
if phase <= 0.0 {
0.0
} else if phase >= 1.0 {
1.0
} else {
let c = std::f32::consts::TAU / 3.0;
(2.0f32).powf(-10.0 * phase) * ((phase * 10.0 - 0.75) * c).sin() + 1.0
}
}
OverlayEasing::CubicBezier { x1, y1, x2, y2 } => cubic_bezier_ease(phase, x1, y1, x2, y2),
}
}
#[cfg(test)]
mod tests {
use super::*;
fn close(a: f32, b: f32) -> bool {
(a - b).abs() < 2e-3
}
#[test]
fn cubic_bezier_matches_its_endpoints_and_stays_monotone() {
let ease = OverlayEasing::CubicBezier {
x1: 0.25,
y1: 0.1,
x2: 0.25,
y2: 1.0,
};
assert!(close(apply_easing(0.0, ease), 0.0));
assert!(close(apply_easing(1.0, ease), 1.0));
let mut prev = -1.0;
for i in 0..=50 {
let v = apply_easing(i as f32 / 50.0, ease);
assert!(v >= prev - 1e-3, "not monotone at {i}: {prev} -> {v}");
prev = v;
}
}
#[test]
fn the_identity_bezier_is_linear() {
let ease = OverlayEasing::CubicBezier {
x1: 1.0 / 3.0,
y1: 1.0 / 3.0,
x2: 2.0 / 3.0,
y2: 2.0 / 3.0,
};
for i in 0..=20 {
let t = i as f32 / 20.0;
assert!(close(apply_easing(t, ease), t), "at {t}");
}
}
#[test]
fn bounce_and_elastic_are_not_expressible_as_one_bezier_segment() {
for ease in [OverlayEasing::Bounce, OverlayEasing::Elastic] {
assert!(close(apply_easing(0.0, ease), 0.0), "{ease:?} at 0");
assert!(close(apply_easing(1.0, ease), 1.0), "{ease:?} at 1");
}
let peak = (0..100)
.map(|i| apply_easing(i as f32 / 100.0, OverlayEasing::Elastic))
.fold(f32::MIN, f32::max);
assert!(peak > 1.0, "Elastic never overshoots: peak {peak}");
let mut reversals = 0;
let mut prev = apply_easing(0.0, OverlayEasing::Bounce);
let mut rising = true;
for i in 1..=100 {
let v = apply_easing(i as f32 / 100.0, OverlayEasing::Bounce);
let now = v >= prev;
if now != rising {
reversals += 1;
rising = now;
}
prev = v;
}
assert!(reversals >= 3, "Bounce should reverse several times");
}
#[test]
fn a_start_time_is_a_delay_measured_from_the_epoch() {
let track = AnimTrack {
start_time: 0.5,
duration: 1.0,
from: 0.0f32,
to: 1.0f32,
..Default::default()
};
for epoch in [0.0, 1_700_000_000.0] {
assert!(close(track.sample_from(epoch + 0.5, epoch), 0.0));
assert!(close(track.sample_from(epoch + 1.0, epoch), 0.5));
assert!(close(track.sample_from(epoch + 1.5, epoch), 1.0));
}
}
#[test]
fn apply_writes_the_instance_channels() {
let anims = OverlayAnimations::default()
.with_epoch(100.0)
.with_opacity(AnimTrack {
start_time: 0.0,
duration: 1.0,
from: 0.0,
to: 1.0,
..Default::default()
})
.with_translate(AnimTrack {
start_time: 0.0,
duration: 1.0,
from: [0.0, 0.0],
to: [10.0, 20.0],
..Default::default()
})
.with_rotation(AnimTrack {
start_time: 0.0,
duration: 1.0,
from: 0.0,
to: 1.0,
..Default::default()
})
.with_scale(AnimTrack {
start_time: 0.0,
duration: 1.0,
from: 1.0,
to: 2.0,
..Default::default()
})
.with_tint(AnimTrack {
start_time: 0.0,
duration: 1.0,
from: [1.0, 1.0, 1.0, 1.0],
to: [0.0, 0.5, 1.0, 1.0],
..Default::default()
});
let mut transform = crate::overlay::OverlayTransform::IDENTITY;
let mut opacity = 1.0f32;
let mut tint = [1.0f32; 4];
anims.apply(100.5, &mut transform, &mut opacity, &mut tint);
assert!(close(opacity, 0.5));
assert!(close(transform.translate[0], 5.0));
assert!(close(transform.translate[1], 10.0));
assert!(close(transform.rotation, 0.5));
assert!(close(transform.scale, 1.5));
assert!(close(tint[1], 0.75));
}
}