keyframe 1.1.1

A simple library for animation in Rust
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178

use core::borrow::Borrow;
use core::mem::MaybeUninit;

pub(crate) use crate::*;

#[cfg(feature = "mint_types")]
pub use mint_type_impls::*;

/// Implementation of a 2D curve function for easing between two points
pub trait EasingFunction {
	/// For an X position on the curve, calculate the Y position.
	/// 0.0-1.0 is start and end on both axes but values can go out of bounds.
	///
	/// # Note
	///
	/// Because this method has a `&self` argument this trait can be used to both implement a "static" curve function (e.g. a linear interpolation)
	/// or a "dynamic" curve function (e.g. a bezier curve with user defined inputs).
	///
	/// Since a static curve function will have zero size the size of a `dyn EasingFunction` will be the same size as a vtable.
	/// This also means you can specify a static curve function with only the name of the type (e.g. `ease(EaseInOut, 0.0, 1.0, 0.5)`).
	fn y(&self, x: f64) -> f64;
}

/// Type that can be used with an easing function
pub trait CanTween {
	/// Returns the interpolated value between `from` and `to` at the specified time.
	///
	/// # Note
	/// This function will always create a new value, so calling it on very large structures is not a good idea.
	fn ease(from: Self, to: Self, time: impl Float) -> Self;
}

impl CanTween for f32 {
	#[inline]
	fn ease(from: Self, to: Self, time: impl Float) -> Self {
		as_t(as_f64(from) + as_f64(to - from) * as_f64(time))
	}
}

impl CanTween for f64 {
	#[inline]
	fn ease(from: Self, to: Self, time: impl Float) -> Self {
		as_t(as_f64(from) + as_f64(to - from) * as_f64(time))
	}
}

impl<T: CanTween, const N: usize> CanTween for [T; N] {
	fn ease(from: Self, to: Self, time: impl Float) -> Self {
		// This is safe, see: https://doc.rust-lang.org/core/mem/union.MaybeUninit.html#initializing-an-array-element-by-element
		let mut result_uninit: [MaybeUninit<T>; N] = unsafe { MaybeUninit::uninit().assume_init() };

		for (i, (f, t)) in IntoIterator::into_iter(from)
			.zip(IntoIterator::into_iter(to))
			.enumerate()
		{
			// Initialize the array while moving elements out of from and to...
			result_uninit[i].write(T::ease(f, t, time));
		}

		unsafe {
			// MaybeUninit<T> is guaranteed to have the same size, alignment, and ABI as T.
			let ptr = result_uninit.as_mut_ptr() as *mut [T; N];
			let result = ptr.read();
			core::mem::forget(result_uninit);

			result
		}
	}
}

/// Returns the value at a specified X position on the curve between point A and point B.
/// The time argument is expected to stay within a range of 0.0 to 1.0 but bounds checking is not enforced.
#[inline]
pub fn ease_with_unbounded_time<V: CanTween, F: EasingFunction>(
	function: impl Borrow<F>,
	from: V,
	to: V,
	time: impl Float,
) -> V {
	V::ease(from, to, function.borrow().y(as_f64(time)))
}

/// Returns the value at a specified X position on the curve between point A and point B.
/// Time is limited to a range between 0.0 and 1.0.
#[inline]
pub fn ease<V: CanTween, T: Float, F: EasingFunction>(function: impl Borrow<F>, from: V, to: V, time: T) -> V {
	ease_with_unbounded_time(
		function,
		from,
		to,
		match time {
			_ if time < T::zero() => T::zero(),
			_ if time > T::one() => T::one(),
			_ => time,
		},
	)
}

/// Returns the value at a specified X position on the curve between point A and point B.
/// Time is limited to a range between 0.0 and `max_time`.
#[inline]
pub fn ease_with_scaled_time<V: CanTween, T: Float, F: EasingFunction>(
	function: impl Borrow<F>,
	from: V,
	to: V,
	time: T,
	max_time: T,
) -> V {
	ease(
		function,
		from,
		to,
		match time {
			_ if time < T::zero() => T::zero(),
			_ if time > max_time => T::one(),
			_ => time / max_time,
		},
	)
}

#[cfg(feature = "mint_types")]
mod mint_type_impls {
	use crate::easing::*;

	impl<V: CanTween> CanTween for Vector2<V> {
		#[inline]
		fn ease(from: Self, to: Self, time: impl Float) -> Self {
			Self {
				x: V::ease(from.x, to.x, time),
				y: V::ease(from.y, to.y, time),
			}
		}
	}

	impl<V: CanTween> CanTween for Vector3<V> {
		#[inline]
		fn ease(from: Self, to: Self, time: impl Float) -> Self {
			Self {
				x: V::ease(from.x, to.x, time),
				y: V::ease(from.y, to.y, time),
				z: V::ease(from.z, to.z, time),
			}
		}
	}

	impl<V: CanTween> CanTween for Vector4<V> {
		#[inline]
		fn ease(from: Self, to: Self, time: impl Float) -> Self {
			Self {
				x: V::ease(from.x, to.x, time),
				y: V::ease(from.y, to.y, time),
				z: V::ease(from.z, to.z, time),
				w: V::ease(from.w, to.w, time),
			}
		}
	}

	impl<V: CanTween> CanTween for Point2<V> {
		#[inline]
		fn ease(from: Self, to: Self, time: impl Float) -> Self {
			Self {
				x: V::ease(from.x, to.x, time),
				y: V::ease(from.y, to.y, time),
			}
		}
	}

	impl<V: CanTween> CanTween for Point3<V> {
		#[inline]
		fn ease(from: Self, to: Self, time: impl Float) -> Self {
			Self {
				x: V::ease(from.x, to.x, time),
				y: V::ease(from.y, to.y, time),
				z: V::ease(from.z, to.z, time),
			}
		}
	}
}