ScummVM API documentation
animation_player.h
1/* ScummVM - Graphic Adventure Engine
2 *
3 * ScummVM is the legal property of its developers, whose names
4 * are too numerous to list here. Please refer to the COPYRIGHT
5 * file distributed with this source distribution.
6 *
7 * This program is free software: you can redistribute it and/or modify
8 * it under the terms of the GNU General Public License as published by
9 * the Free Software Foundation, either version 3 of the License, or
10 * (at your option) any later version.
11 *
12 * This program is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 * GNU General Public License for more details.
16 *
17 * You should have received a copy of the GNU General Public License
18 * along with this program. If not, see <http://www.gnu.org/licenses/>.
19 *
20 */
21
22#ifndef HOLLYWOOD_MONSTERS_SCENES_ANIMATION_PLAYER_H
23#define HOLLYWOOD_MONSTERS_SCENES_ANIMATION_PLAYER_H
24
25#include "common/array.h"
26#include "common/types.h"
27
28#include "hollywood/monsters/scenes/animation_events.h"
29
30namespace Hollywood {
31
32// Inclusive playback range. Ordered and repeated playback remap the frame sent
33// to the target while events continue to receive the playback frame.
34struct AnimationFrameRange : AnimationEventSpec<AnimationFrameRange> {
35 AnimationFrameRange(uint newFirstFrame, uint newLastFrame, uint32 newFrameMillis) :
36 firstFrame(newFirstFrame),
37 lastFrame(newLastFrame),
38 frameMillis(newFrameMillis),
39 allowSkip(true),
40 waitAfterFinalFrame(true),
41 frameOrder(nullptr),
42 repeatedFrame(-1),
43 repeatFirstFrame(false),
44 heldFirstPlaybackFrame(0),
45 appendFirstFrame(false),
46 appendedPlaybackFrame(0),
47 appendedTargetFrame(0) {
48 }
49
50 // Plays every descriptor once, beginning at descriptor zero.
51 AnimationFrameRange(uint frameCount, uint32 newFrameMillis) :
52 AnimationFrameRange(0, frameCount - 1, newFrameMillis) {
53 }
54
55 template<uint size>
56 AnimationFrameRange(const byte (&newFrameOrder)[size], uint32 newFrameMillis) :
57 AnimationFrameRange(0, size - 1, newFrameMillis) {
58 frameOrder = newFrameOrder;
59 }
60
61 AnimationFrameRange &unskippable() {
62 allowSkip = false;
63 return *this;
64 }
65
66 AnimationFrameRange &noFinalFrameDelay() {
67 waitAfterFinalFrame = false;
68 return *this;
69 }
70
71 AnimationFrameRange &repeatFrame(byte frame) {
72 frameOrder = nullptr;
73 repeatedFrame = frame;
74 return *this;
75 }
76
77 AnimationFrameRange &holdFirstFrame() {
78 if (!repeatFirstFrame) {
79 heldFirstPlaybackFrame = firstFrame;
80 ++lastFrame;
81 repeatFirstFrame = true;
82 }
83 return *this;
84 }
85
86 AnimationFrameRange &frameRange(uint newFirstFrame, uint newLastFrame) {
87 firstFrame = newFirstFrame;
88 lastFrame = newLastFrame;
89 return *this;
90 }
91
92 AnimationFrameRange &returnToFirstFrame() {
93 if (!appendFirstFrame && firstFrame <= lastFrame && lastFrame < 0xff) {
94 appendedTargetFrame = (byte)firstFrame;
95 appendedPlaybackFrame = ++lastFrame;
96 appendFirstFrame = true;
97 }
98 return *this;
99 }
100
101 byte targetFrame(uint playbackFrame) const {
102 if (appendFirstFrame && playbackFrame == appendedPlaybackFrame)
103 return appendedTargetFrame;
104 if (frameOrder != nullptr)
105 return frameOrder[playbackFrame];
106 if (repeatedFrame >= 0)
107 return (byte)repeatedFrame;
108 if (!repeatFirstFrame || playbackFrame <= heldFirstPlaybackFrame)
109 return (byte)playbackFrame;
110 return (byte)(playbackFrame - 1);
111 }
112
113 uint firstFrame;
114 uint lastFrame;
115 uint32 frameMillis;
116 bool allowSkip;
117 bool waitAfterFinalFrame;
118 const byte *frameOrder;
119 int repeatedFrame;
120 bool repeatFirstFrame;
121 uint heldFirstPlaybackFrame;
122 bool appendFirstFrame;
123 uint appendedPlaybackFrame;
124 byte appendedTargetFrame;
125};
126
135 AnimationTransition(uint newFirstFrame, uint newLastFrame, byte newFinalFrame,
136 uint32 newFrameMillis) :
137 firstFrame(newFirstFrame),
138 lastFrame(newLastFrame),
139 finalFrame(newFinalFrame),
140 frameMillis(newFrameMillis),
141 allowSkip(true) {
142 }
143
144 AnimationTransition &unskippable() {
145 allowSkip = false;
146 return *this;
147 }
148
149 uint firstFrame;
150 uint lastFrame;
151 byte finalFrame;
152 uint32 frameMillis;
153 bool allowSkip;
154};
155
167public:
169
170 virtual bool animationPlaybackShouldStop() const = 0;
171 virtual void presentAnimationFrame() = 0;
172 virtual bool waitForAnimationFrame(uint32 millis, bool allowSkip) = 0;
173 virtual bool consumeAnimationFastForwardRequest() { return false; }
174 virtual void handleAnimationFrameEvent(const AnimationFrameEvent &event, uint frame) {
175 if (event.type == AnimationFrameEvent::kCustomHook)
176 handleAnimationFrameHook(event.hookId, frame);
177 }
178 virtual void handleAnimationFrameHook(byte hookId, uint frame) {
179 (void)hookId;
180 (void)frame;
181 }
182};
183
185private:
186 class FrameValueTarget {
187 public:
188 explicit FrameValueTarget(byte &frame) : _frame(frame) {}
189 void setFrame(byte frame) { _frame = frame; }
190
191 private:
192 byte &_frame;
193 };
194
195public:
197 _delegate(delegate) {
198 }
199
200 bool playAndPresent(byte &targetFrame, const AnimationFrameRange &range) {
201 FrameValueTarget target(targetFrame);
202 return playInternal(target, range, true);
203 }
204
205 bool transitionAndPresent(byte &targetFrame, const AnimationTransition &transitionSpec) {
206 FrameValueTarget target(targetFrame);
207 return transitionInternal(target, transitionSpec, true);
208 }
209
210 template<class FrameTarget>
211 bool play(FrameTarget &target, const AnimationFrameRange &range) {
212 return playInternal(target, range, false);
213 }
214
215 template<class FrameTarget>
216 bool playAndPresent(FrameTarget &target, const AnimationFrameRange &range) {
217 return playInternal(target, range, true);
218 }
219
220 template<class FrameTarget>
221 bool transition(FrameTarget &target, const AnimationTransition &transitionSpec) {
222 return transitionInternal(target, transitionSpec, false);
223 }
224
225 template<class FrameTarget>
226 bool transitionAndPresent(FrameTarget &target, const AnimationTransition &transitionSpec) {
227 return transitionInternal(target, transitionSpec, true);
228 }
229
230private:
231 template<class FrameTarget>
232 bool playInternal(FrameTarget &target, const AnimationFrameRange &range,
233 bool presentBeforeWait) {
234 if (range.firstFrame > 0xff || range.lastFrame > 0xff)
235 return false;
236
237 const int step = range.firstFrame <= range.lastFrame ? 1 : -1;
238 for (int frame = range.firstFrame;; frame += step) {
239 if (_delegate.animationPlaybackShouldStop())
240 return false;
241
242 target.setFrame(range.targetFrame(frame));
243 const Common::Array<AnimationFrameEvent> &events = range._events;
244 for (uint eventIndex = 0; eventIndex < events.size(); ++eventIndex) {
245 if (events[eventIndex].matches(frame))
246 _delegate.handleAnimationFrameEvent(events[eventIndex], frame);
247 }
248 if (presentBeforeWait) {
249 _delegate.presentAnimationFrame();
250 if (_delegate.animationPlaybackShouldStop())
251 return false;
252 }
253 if (frame == (int)range.lastFrame && !range.waitAfterFinalFrame)
254 return true;
255 if (_delegate.waitForAnimationFrame(range.frameMillis, range.allowSkip)) {
256 if (!_delegate.consumeAnimationFastForwardRequest())
257 return false;
258
259 for (int remainingFrame = frame + step;
260 step > 0 ? remainingFrame <= (int)range.lastFrame :
261 remainingFrame >= (int)range.lastFrame;
262 remainingFrame += step) {
263 target.setFrame(range.targetFrame(remainingFrame));
264 for (uint eventIndex = 0; eventIndex < events.size(); ++eventIndex) {
265 if (events[eventIndex].matches(remainingFrame))
266 _delegate.handleAnimationFrameEvent(events[eventIndex], remainingFrame);
267 }
268 }
269 if (frame != (int)range.lastFrame && presentBeforeWait)
270 _delegate.presentAnimationFrame();
271 return !_delegate.animationPlaybackShouldStop();
272 }
273 if (frame == (int)range.lastFrame)
274 return true;
275 }
276 }
277
278 template<class FrameTarget>
279 bool transitionInternal(FrameTarget &target, const AnimationTransition &transitionSpec,
280 bool presentBoundaryFrames) {
281 if (transitionSpec.firstFrame > 0xff || transitionSpec.lastFrame > 0xff ||
282 _delegate.animationPlaybackShouldStop())
283 return false;
284
285 const int step = transitionSpec.firstFrame <= transitionSpec.lastFrame ? 1 : -1;
286 int frame = transitionSpec.firstFrame;
287 target.setFrame((byte)frame);
288 if (presentBoundaryFrames) {
289 _delegate.presentAnimationFrame();
290 if (_delegate.animationPlaybackShouldStop())
291 return false;
292 }
293
294 while (frame != (int)transitionSpec.lastFrame) {
295 if (_delegate.waitForAnimationFrame(transitionSpec.frameMillis, transitionSpec.allowSkip)) {
296 if (!_delegate.consumeAnimationFastForwardRequest())
297 return false;
298 break;
299 }
300 frame += step;
301 target.setFrame((byte)frame);
302 }
303
304 target.setFrame(transitionSpec.finalFrame);
305 if (presentBoundaryFrames) {
306 _delegate.presentAnimationFrame();
307 if (_delegate.animationPlaybackShouldStop())
308 return false;
309 }
310 return true;
311 }
312
314};
315
316} // End of namespace Hollywood
317
318#endif // HOLLYWOOD_MONSTERS_SCENES_ANIMATION_PLAYER_H
Definition: array.h:52
size_type size() const
Definition: array.h:316
Definition: animation_events.h:140
Definition: animation_player.h:166
Definition: animation_player.h:184
Definition: animation_events.h:36
Definition: animation_player.h:34
Definition: animation_player.h:134