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
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
//! Validated sprite regions and CPU-only animation with explicit simulation time.
use glam::Vec2;
use std::{fmt, sync::Arc, time::Duration};
/// Invalid sprite geometry or animation definition.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum SpriteError {
/// Region dimensions are zero or their endpoints overflow `u32`.
InvalidRegion,
/// Clip name is empty or contains only whitespace.
EmptyName,
/// Clip has no frames.
EmptyClip,
/// Frame duration is zero.
ZeroDuration,
/// Sum of frame durations exceeds [`Duration::MAX`].
DurationOverflow,
}
impl fmt::Display for SpriteError {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.write_str(match self {
Self::InvalidRegion => "sprite region must have nonzero dimensions and u32 endpoints",
Self::EmptyName => "animation clip must have a nonblank name",
Self::EmptyClip => "animation clip must contain at least one frame",
Self::ZeroDuration => "animation frame duration must be nonzero",
Self::DurationOverflow => "animation clip duration exceeds Duration::MAX",
})
}
}
impl std::error::Error for SpriteError {}
/// A positive, axis-aligned source rectangle in top-left texture pixel coordinates.
/// Bounds against an actual texture are checked at drawing time.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct SpriteRegion {
x: u32,
y: u32,
width: u32,
height: u32,
}
impl SpriteRegion {
/// Rejects zero dimensions and overflowing endpoints. Flips belong to
/// [`SpriteTransform`], so source dimensions are always positive.
pub fn new(x: u32, y: u32, width: u32, height: u32) -> Result<Self, SpriteError> {
if width == 0
|| height == 0
|| x.checked_add(width).is_none()
|| y.checked_add(height).is_none()
{
return Err(SpriteError::InvalidRegion);
}
Ok(Self {
x,
y,
width,
height,
})
}
/// Left edge in texture pixels.
pub fn x(self) -> u32 {
self.x
}
/// Top edge in texture pixels.
pub fn y(self) -> u32 {
self.y
}
/// Width in texture pixels.
pub fn width(self) -> u32 {
self.width
}
/// Height in texture pixels.
pub fn height(self) -> u32 {
self.height
}
/// Whether the entire region is inside these texture dimensions.
pub fn fits(self, width: u32, height: u32) -> bool {
self.x + self.width <= width && self.y + self.height <= height
}
}
/// Sprite destination geometry in world units, with positive size and explicit pivot.
/// Flips change texture sampling; they do not move the pivot or geometry.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct SpriteTransform {
/// World position at which the local origin is placed.
pub position: Vec2,
/// Destination width and height in world units, both strictly positive.
pub size: Vec2,
/// Pivot offset from the unrotated destination's top-left, in world units.
/// It may be outside the destination. Use `size * 0.5` for a centered pivot.
pub origin: Vec2,
/// Clockwise rotation in radians, matching [`crate::camera::Camera2D`].
pub rotation: f32,
/// Reverse horizontal source sampling.
pub flip_x: bool,
/// Reverse vertical source sampling.
pub flip_y: bool,
}
impl Default for SpriteTransform {
fn default() -> Self {
Self {
position: Vec2::ZERO,
size: Vec2::ONE,
origin: Vec2::ZERO,
rotation: 0.0,
flip_x: false,
flip_y: false,
}
}
}
impl SpriteTransform {
/// Rejects nonfinite coordinates, nonpositive size, and rotations whose
/// conversion to the backend's degrees would overflow.
pub fn is_valid(self) -> bool {
self.position.is_finite()
&& self.size.is_finite()
&& self.size.min_element() > 0.0
&& self.origin.is_finite()
&& self.rotation.is_finite()
&& self.rotation.to_degrees().is_finite()
}
}
/// One selected sprite-sheet region and its simulation duration.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct SpriteFrame {
/// Region selected while this frame is current.
pub region: SpriteRegion,
/// Time spent on this frame; must be nonzero when constructing a clip.
pub duration: Duration,
}
/// Behavior at the end of a clip.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum PlaybackMode {
/// Wrap to the first frame; never emit a completion event.
Loop,
/// Hold the last frame and emit one completion event per play/reset.
Once,
}
/// Immutable named clip. Share with [`Arc`] between independent players.
#[derive(Debug)]
pub struct AnimationClip {
name: String,
frames: Vec<SpriteFrame>,
ends: Vec<Duration>,
duration: Duration,
mode: PlaybackMode,
}
impl AnimationClip {
/// Validates a nonblank name, at least one frame, positive durations and
/// a representable total duration. Texture bounds are checked when drawn.
pub fn new(
name: impl Into<String>,
frames: Vec<SpriteFrame>,
mode: PlaybackMode,
) -> Result<Self, SpriteError> {
let name = name.into();
if name.trim().is_empty() {
return Err(SpriteError::EmptyName);
}
if frames.is_empty() {
return Err(SpriteError::EmptyClip);
}
let mut duration = Duration::ZERO;
let mut ends = Vec::with_capacity(frames.len());
for frame in &frames {
if frame.duration.is_zero() {
return Err(SpriteError::ZeroDuration);
}
duration = duration
.checked_add(frame.duration)
.ok_or(SpriteError::DurationOverflow)?;
ends.push(duration);
}
Ok(Self {
name,
frames,
ends,
duration,
mode,
})
}
/// Game-defined clip name, preserved verbatim.
pub fn name(&self) -> &str {
&self.name
}
/// Ordered frames and their individual durations.
pub fn frames(&self) -> &[SpriteFrame] {
&self.frames
}
/// Total time for one traversal.
pub fn duration(&self) -> Duration {
self.duration
}
/// Behavior at the clip's end.
pub fn mode(&self) -> PlaybackMode {
self.mode
}
}
/// A one-shot completion returned exactly once by [`AnimationPlayer::advance`].
/// Can be sent to [`crate::events::Events`]; retains the completed clip even
/// if the player immediately switches to another clip.
#[derive(Clone, Debug)]
pub struct AnimationCompleted {
/// Immutable clip that reached its end.
pub clip: Arc<AnimationClip>,
}
/// CPU playback cursor. Drawing/reading a frame never changes playback.
/// Advancement uses integer nanoseconds and binary frame lookup, so large
/// time steps do not iterate over every crossed frame or loop.
#[derive(Clone, Debug)]
pub struct AnimationPlayer {
clip: Arc<AnimationClip>,
elapsed: Duration,
paused: bool,
finished: bool,
}
impl AnimationPlayer {
/// Starts at the first frame, unpaused. Accepts an owned clip or shared `Arc`.
pub fn new(clip: impl Into<Arc<AnimationClip>>) -> Self {
Self {
clip: clip.into(),
elapsed: Duration::ZERO,
paused: false,
finished: false,
}
}
/// Switches/restarts a clip, clearing pause and completion state.
pub fn play(&mut self, clip: impl Into<Arc<AnimationClip>>) {
*self = Self::new(clip);
}
/// Rewinds this clip and rearms its completion event, preserving pause state.
pub fn reset(&mut self) {
self.elapsed = Duration::ZERO;
self.finished = false;
}
/// Stops advancement without changing the current frame.
pub fn pause(&mut self) {
self.paused = true;
}
/// Allows advancement again. A completed one-shot remains completed until reset/play.
pub fn resume(&mut self) {
self.paused = false;
}
/// Whether explicit time advancement is paused.
pub fn is_paused(&self) -> bool {
self.paused
}
/// Whether a one-shot has reached its end.
pub fn is_finished(&self) -> bool {
self.finished
}
/// Current immutable clip.
pub fn clip(&self) -> &Arc<AnimationClip> {
&self.clip
}
/// Time within this traversal, clamped to duration for a finished one-shot.
pub fn elapsed(&self) -> Duration {
self.elapsed
}
/// Current frame index. Exact boundaries select the next frame; a completed
/// one-shot holds the last frame for drawing.
pub fn frame_index(&self) -> usize {
self.clip
.ends
.partition_point(|end| *end <= self.elapsed)
.min(self.clip.frames.len() - 1)
}
/// Current frame, without advancing simulation.
pub fn frame(&self) -> &SpriteFrame {
&self.clip.frames[self.frame_index()]
}
/// Advances by explicitly supplied simulation time. Zero time, paused or
/// completed playback does nothing. Looping wraps including exact boundaries;
/// a one-shot discards excess time and returns one completion on its first end.
/// No allocation occurs, including at completion (the clip's `Arc` is cloned).
pub fn advance(&mut self, dt: Duration) -> Option<AnimationCompleted> {
if self.paused || self.finished || dt.is_zero() {
return None;
}
// Even two Duration::MAX values fit in u128 nanoseconds.
let next = self.elapsed.as_nanos() + dt.as_nanos();
let duration = self.clip.duration.as_nanos();
let next = match self.clip.mode {
PlaybackMode::Loop => next % duration,
PlaybackMode::Once if next >= duration => {
self.elapsed = self.clip.duration;
self.finished = true;
return Some(AnimationCompleted {
clip: Arc::clone(&self.clip),
});
}
PlaybackMode::Once => next,
};
self.elapsed = Duration::new((next / 1_000_000_000) as u64, (next % 1_000_000_000) as u32);
None
}
}
#[cfg(test)]
mod tests;