ScummVM API documentation
animation_channels.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_CHANNELS_H
23#define HOLLYWOOD_MONSTERS_SCENES_ANIMATION_CHANNELS_H
24
25#include "common/array.h"
26#include "common/random.h"
27#include "common/types.h"
28
29#include "hollywood/monsters/scenes/animation_layers.h"
30
31namespace Hollywood {
32
33// Tracks frame timing for scene-local loops without owning any drawing state.
36 frameIndex(0),
37 timerAccumulator(0),
38 frameMillis(0) {
39 }
40
41 void reset(byte initialFrame, uint32 millis) {
42 frameIndex = initialFrame;
43 timerAccumulator = 0;
44 frameMillis = millis;
45 }
46
47 void resetTimer() {
48 timerAccumulator = 0;
49 }
50
51 void addDelta(uint32 delta) {
52 timerAccumulator += delta;
53 }
54
55 bool consumeFrame() {
56 if (frameMillis == 0 || timerAccumulator < frameMillis)
57 return false;
58
59 timerAccumulator -= frameMillis;
60 return true;
61 }
62
63 uint consumeFrames(uint32 delta) {
64 addDelta(delta);
65
66 uint frameCount = 0;
67 while (consumeFrame())
68 ++frameCount;
69 return frameCount;
70 }
71
72 byte frameIndex;
73 uint32 timerAccumulator;
74 uint32 frameMillis;
75};
76
89public:
90 static constexpr uint kInvalidTrack = 0xffffffff;
91
93 _layers(layers) {
94 }
95
96 uint addLoop(uint layerId, uint32 frameMillis,
97 uint16 frameCount, bool active = true) {
98 if (!_layers.hasLayer(layerId) || frameCount == 0 || frameCount > 0x100)
99 return kInvalidTrack;
100 return addTrack(kCycle, layerId, frameMillis, 0,
101 (byte)(frameCount - 1), false, active);
102 }
103
104 uint addRange(uint layerId, uint32 frameMillis,
105 byte firstFrame, byte lastFrame, bool active = true) {
106 if (!_layers.hasLayer(layerId) || firstFrame > lastFrame)
107 return kInvalidTrack;
108 return addTrack(kCycle, layerId, frameMillis, firstFrame,
109 lastFrame, false, active);
110 }
111
112 // Cycles the logical entries in the layer's configured frame map.
113 uint addFrameMap(uint layerId, uint32 frameMillis,
114 bool active = true) {
115 if (!_layers.hasLayer(layerId))
116 return kInvalidTrack;
117 const ResourceSpriteLayer &layer = _layers.layer(layerId);
118 if (layer.frameMap == nullptr || layer.frameMapSize == 0 || layer.frameMapSize > 0x100)
119 return kInvalidTrack;
120 return addTrack(kCycle, layerId, frameMillis, 0,
121 (byte)(layer.frameMapSize - 1), false, active);
122 }
123
124 uint addPingPong(uint layerId, uint32 frameMillis,
125 byte firstFrame, byte lastFrame, bool active = true) {
126 if (!_layers.hasLayer(layerId) || firstFrame > lastFrame)
127 return kInvalidTrack;
128 return addTrack(kPingPong, layerId, frameMillis, firstFrame,
129 lastFrame, false, active);
130 }
131
132 uint addStableRandom(ResourceSpriteLayer &layer, uint32 frameMillis, byte firstFrame,
133 byte lastFrame, bool avoidRepeats, bool active = true) {
134 if (firstFrame > lastFrame)
135 return kInvalidTrack;
136 return addTrack(kRandom, layer, frameMillis, firstFrame, lastFrame,
137 avoidRepeats, active);
138 }
139
140 uint addRandom(uint layerId, uint32 frameMillis,
141 byte firstFrame, byte lastFrame, bool avoidRepeats, bool active = true) {
142 if (!_layers.hasLayer(layerId) || firstFrame > lastFrame)
143 return kInvalidTrack;
144 return addTrack(kRandom, layerId, frameMillis, firstFrame,
145 lastFrame, avoidRepeats, active);
146 }
147
148 bool hasTrack(uint id) const {
149 return id < _tracks.size();
150 }
151
152 void setActive(uint id, bool active) {
153 if (hasTrack(id))
154 _tracks[id].active = active;
155 }
156
157 bool isActive(uint id) const {
158 return hasTrack(id) && _tracks[id].active;
159 }
160
161 void reset(uint id) {
162 if (hasTrack(id)) {
163 Track &track = _tracks[id];
164 track.reset(targetLayer(track));
165 }
166 }
167
168 void resetToFrame(uint id, byte frame) {
169 if (hasTrack(id) && frame >= _tracks[id].firstFrame && frame <= _tracks[id].lastFrame) {
170 Track &track = _tracks[id];
171 track.reset(targetLayer(track), frame);
172 }
173 }
174
175 // Changes the bounds without resetting the timer or live layer state.
176 void setRange(uint id, byte firstFrame, byte lastFrame) {
177 if (!hasTrack(id) || firstFrame > lastFrame)
178 return;
179
180 Track &track = _tracks[id];
181 track.firstFrame = firstFrame;
182 track.lastFrame = lastFrame;
183 }
184
185 void resetTimer(uint id) {
186 if (hasTrack(id))
187 _tracks[id].channel.resetTimer();
188 }
189
190 // Switches cadence and clears accumulated time without changing the layer.
191 void resetTimer(uint id, uint32 frameMillis) {
192 if (!hasTrack(id) || frameMillis == 0)
193 return;
194 _tracks[id].channel.frameMillis = frameMillis;
195 _tracks[id].channel.resetTimer();
196 }
197
198 // Makes the track advance on its next update, even if that update has no delta.
199 void prime(uint id) {
200 if (hasTrack(id))
201 _tracks[id].channel.timerAccumulator = _tracks[id].channel.frameMillis;
202 }
203
204 bool advance(uint32 delta, Common::RandomSource &random) {
205 bool changed = false;
206 for (uint i = 0; i < _tracks.size(); ++i)
207 changed = advance(i, delta, random) || changed;
208 return changed;
209 }
210
211 bool advance(uint id, uint32 delta, Common::RandomSource &random) {
212 if (!hasTrack(id) || !_tracks[id].active)
213 return false;
214
215 Track &track = _tracks[id];
216 ResourceSpriteLayer *target = targetLayer(track);
217 if (target == nullptr) {
218 track.channel.resetTimer();
219 return false;
220 }
221 const uint frames = track.channel.consumeFrames(delta);
222 for (uint frame = 0; frame < frames; ++frame)
223 track.advanceFrame(*target, random);
224 return frames != 0;
225 }
226
227private:
228 enum Mode {
229 kCycle,
230 kPingPong,
231 kRandom
232 };
233
234 struct Track {
235 Track() :
236 mode(kCycle),
237 stableLayer(nullptr),
238 layerId(SceneLayerStack::kInvalidLayer),
239 channel(),
240 firstFrame(0),
241 lastFrame(0),
242 forward(true),
243 avoidRepeats(false),
244 active(false) {
245 }
246
247 void reset(ResourceSpriteLayer *target) {
248 reset(target, firstFrame);
249 }
250
251 void reset(ResourceSpriteLayer *target, byte frame) {
252 forward = true;
253 channel.reset(frame, channel.frameMillis);
254 if (target != nullptr)
255 target->reset(frame);
256 }
257
258 void setFrame(ResourceSpriteLayer &target, byte frame) {
259 channel.frameIndex = frame;
260 target.setFrame(frame);
261 }
262
263 void advanceFrame(ResourceSpriteLayer &target, Common::RandomSource &random) {
264 byte frame = target.frameIndex;
265 switch (mode) {
266 case kCycle:
267 setFrame(target, frame >= firstFrame && frame < lastFrame ? frame + 1 : firstFrame);
268 break;
269 case kPingPong:
270 if (firstFrame == lastFrame) {
271 setFrame(target, firstFrame);
272 } else if (forward) {
273 if (frame >= lastFrame) {
274 forward = false;
275 setFrame(target, lastFrame - 1);
276 } else {
277 setFrame(target, frame + 1);
278 }
279 } else if (frame <= firstFrame) {
280 forward = true;
281 setFrame(target, firstFrame + 1);
282 } else {
283 setFrame(target, frame - 1);
284 }
285 break;
286 case kRandom: {
287 const uint count = (uint)lastFrame - firstFrame + 1;
288 byte nextFrame = frame;
289 const uint maxAttempts = avoidRepeats && count > 1 ? 8 : 1;
290 for (uint attempt = 0; attempt < maxAttempts && nextFrame == frame; ++attempt)
291 nextFrame = firstFrame + (byte)random.getRandomNumber(count - 1);
292 if (avoidRepeats && count > 1 && nextFrame == frame) {
293 nextFrame = frame >= firstFrame && frame <= lastFrame ?
294 firstFrame + (byte)((frame - firstFrame + 1) % count) : firstFrame;
295 }
296 setFrame(target, nextFrame);
297 break;
298 }
299 }
300 }
301
302 Mode mode;
303 ResourceSpriteLayer *stableLayer;
304 uint layerId;
305 TimedAnimationChannel channel;
306 byte firstFrame;
307 byte lastFrame;
308 bool forward;
309 bool avoidRepeats;
310 bool active;
311 };
312
313 uint addTrack(Mode mode, ResourceSpriteLayer &layer, uint32 frameMillis,
314 byte firstFrame, byte lastFrame, bool avoidRepeats, bool active) {
315 return addTrack(mode, &layer, SceneLayerStack::kInvalidLayer,
316 frameMillis, firstFrame, lastFrame, avoidRepeats, active);
317 }
318
319 uint addTrack(Mode mode, uint layerId, uint32 frameMillis,
320 byte firstFrame, byte lastFrame, bool avoidRepeats, bool active) {
321 return addTrack(mode, nullptr, layerId, frameMillis, firstFrame,
322 lastFrame, avoidRepeats, active);
323 }
324
325 uint addTrack(Mode mode, ResourceSpriteLayer *stableLayer, uint layerId,
326 uint32 frameMillis, byte firstFrame, byte lastFrame,
327 bool avoidRepeats, bool active) {
328 if (frameMillis == 0)
329 return kInvalidTrack;
330
331 Track track;
332 track.mode = mode;
333 track.stableLayer = stableLayer;
334 track.layerId = layerId;
335 track.channel.frameMillis = frameMillis;
336 track.firstFrame = firstFrame;
337 track.lastFrame = lastFrame;
338 track.avoidRepeats = avoidRepeats;
339 track.active = active;
340 track.reset(targetLayer(track));
341 _tracks.push_back(track);
342 return _tracks.size() - 1;
343 }
344
345 ResourceSpriteLayer *targetLayer(Track &track) {
346 if (track.layerId != SceneLayerStack::kInvalidLayer)
347 return _layers.hasLayer(track.layerId) ? &_layers.layer(track.layerId) : nullptr;
348 return track.stableLayer;
349 }
350
351 SceneLayerStack &_layers;
352 Common::Array<Track> _tracks;
353};
354
355// Alternates random motion between two four-frame sprite groups. Each phase
356// lasts 10-34 ticks; the caller owns cadence and copies the resulting frames.
358 enum FirstPhaseTarget {
359 kFirstFrame,
360 kSecondFrame
361 };
362
364 firstFrame(0),
365 secondFrame(0),
366 _firstBaseFrame(0),
367 _secondBaseFrame(0),
368 _firstPhaseAnimatesFirst(true),
369 _secondPhase(false),
370 _ticksRemaining(0) {
371 }
372
373 void configure(byte firstBaseFrame, byte secondBaseFrame,
374 FirstPhaseTarget firstPhaseTarget) {
375 _firstBaseFrame = firstBaseFrame;
376 _secondBaseFrame = secondBaseFrame;
377 _firstPhaseAnimatesFirst = firstPhaseTarget == kFirstFrame;
378 reset(false, kMinimumTicks);
379 }
380
381 void reset(bool secondPhase, byte ticksRemaining) {
382 _secondPhase = secondPhase;
383 _ticksRemaining = ticksRemaining;
384 firstFrame = _firstBaseFrame;
385 secondFrame = _secondBaseFrame;
386 }
387
388 byte randomPhaseTicks(Common::RandomSource &random) const {
389 return kMinimumTicks + (byte)random.getRandomNumber(kAdditionalTicksMax);
390 }
391
392 void advance(Common::RandomSource &random) {
393 if (_ticksRemaining == 0) {
394 _secondPhase = !_secondPhase;
395 if (animatesFirstFrame())
396 firstFrame = _firstBaseFrame;
397 else
398 secondFrame = _secondBaseFrame;
399 _ticksRemaining = randomPhaseTicks(random);
400 return;
401 }
402
403 --_ticksRemaining;
404 if (animatesFirstFrame())
405 firstFrame = _firstBaseFrame + (byte)random.getRandomNumber(kFrameOffsetMax);
406 else
407 secondFrame = _secondBaseFrame + (byte)random.getRandomNumber(kFrameOffsetMax);
408 }
409
410 byte firstFrame;
411 byte secondFrame;
412
413private:
414 enum {
415 kFrameOffsetMax = 3,
416 kMinimumTicks = 10,
417 kAdditionalTicksMax = 0x18
418 };
419
420 bool animatesFirstFrame() const {
421 return _secondPhase ? !_firstPhaseAnimatesFirst : _firstPhaseAnimatesFirst;
422 }
423
424 byte _firstBaseFrame;
425 byte _secondBaseFrame;
426 bool _firstPhaseAnimatesFirst;
427 bool _secondPhase;
428 byte _ticksRemaining;
429};
430
431// Common idle pattern: base frame, optional short twitch, optional longer sequence.
433 enum Event {
434 kNoEvent,
435 kShortStarted,
436 kLongStarted,
437 kLongFinished
438 };
439
441 channel(),
442 state(0),
443 idleFrame(0),
444 shortFrame(0),
445 longFirstFrame(0),
446 longLastFrame(0),
447 shortRandomMax(0),
448 longRandomMax(0),
449 returnToIdleAfterLongSequence(true) {
450 }
451
452 void configure(uint32 frameMillis, byte idle, byte shortStart, byte longStart, byte longEnd,
453 byte shortRandom, byte longRandom) {
454 idleFrame = idle;
455 shortFrame = shortStart;
456 longFirstFrame = longStart;
457 longLastFrame = longEnd;
458 shortRandomMax = shortRandom;
459 longRandomMax = longRandom;
460 returnToIdleAfterLongSequence = true;
461 channel.reset(idleFrame, frameMillis);
462 state = 0;
463 }
464
465 void reset() {
466 channel.frameIndex = idleFrame;
467 channel.resetTimer();
468 state = 0;
469 }
470
471 void setStateAndFrame(byte newState, byte newFrame) {
472 state = newState;
473 channel.frameIndex = newFrame;
474 }
475
476 void setFrame(byte newFrame) {
477 channel.frameIndex = newFrame;
478 }
479
480 Event advanceTick(Common::RandomSource &random, bool canStartSequence = true) {
481 if (state == 0) {
482 if (canStartSequence && longRandomMax != 0 && random.getRandomNumber(longRandomMax) == 0) {
483 setStateAndFrame(2, longFirstFrame);
484 return kLongStarted;
485 }
486 if (canStartSequence && shortRandomMax != 0 && random.getRandomNumber(shortRandomMax) == 0) {
487 setStateAndFrame(1, shortFrame);
488 return kShortStarted;
489 }
490 } else if (state == 1) {
491 reset();
492 } else if (state == 2) {
493 if (channel.frameIndex == longLastFrame) {
494 if (returnToIdleAfterLongSequence)
495 reset();
496 return kLongFinished;
497 }
498 ++channel.frameIndex;
499 }
500
501 return kNoEvent;
502 }
503
504 void advance(Common::RandomSource &random, uint32 delta, bool canStartSequence = true) {
505 const uint frameCount = channel.consumeFrames(delta);
506 for (uint frame = 0; frame < frameCount; ++frame)
507 advanceTick(random, canStartSequence);
508 }
509
510 TimedAnimationChannel channel;
511 byte state;
512 byte idleFrame;
513 byte shortFrame;
514 byte longFirstFrame;
515 byte longLastFrame;
516 byte shortRandomMax;
517 byte longRandomMax;
518 bool returnToIdleAfterLongSequence;
519};
520
521} // End of namespace Hollywood
522
523#endif
size_type size() const
Definition: array.h:316
void push_back(const T &element)
Definition: array.h:181
Definition: random.h:44
Definition: animation_channels.h:88
Definition: animation_layers.h:109
Definition: animation_channels.h:357
Definition: animation_channels.h:432
Definition: animation_layers.h:33
Definition: animation_channels.h:34