A SpriteSheet/frame based animation. More...
#include <Animation.h>
Public Types | |
| enum class | Direction { Forward , Reverse , Alternate_Forward , Alternate_Reverse } |
| The playing direction of the animation. More... | |
| using | Ptr = std::shared_ptr< Animation > |
| Shared animation pointer. More... | |
Public Member Functions | |
| Animation (const std::string &name, const SpriteSheet &spriteSheet, const Time &duration=Time::Zero) | |
| Constructor. More... | |
| const SpriteSheet & | getSpriteSheet () const |
| Get the spritesheet used to construct the animation. More... | |
| void | setRepeatCount (int count) |
| Set the repetition count of the animation. More... | |
| int | getRepeatCount () const |
| Get the number of times the animation repeats before completing. More... | |
| bool | isRepeating () const |
| Check if the animation is repeating or not. More... | |
| void | setLoop (bool loop) |
| Set whether or not the animation should repeat indefinitely. More... | |
| bool | isLooped () const |
| Check if the animation is looped or not. More... | |
| void | setDuration (const Time &duration) |
| Set the duration of the animation. More... | |
| const Time & | getDuration () const |
| Get the duration of the animation. More... | |
| void | setPlaybackSpeed (float speed) |
| Set the speed factor of the animation. More... | |
| float | getPlaybackSpeed () const |
| Get the speed factor. More... | |
| void | setFrameRate (unsigned int frameRate) |
| Set the frame rate playback of the animation. More... | |
| unsigned int | getFrameRate () const |
| Get the animations playback frame rate. More... | |
| void | setDirection (Direction direction) |
| Set the direction in which the animation should be played. More... | |
| Direction | getDirection () const |
| Get the animations playing direction. More... | |
| const std::string & | getName () const |
| Get the name of the animation. More... | |
| void | setStartDelay (const Time &delay, bool oneTime=false) |
| Set the time to wait before that animation is started. More... | |
| const Time & | getStartDelay () const |
| Get the time waited before the animation is played. More... | |
| bool | isStartDelayedOnce () const |
| Check whether or not the animation is start delayed once. More... | |
| bool | isStartDelayed () const |
| Check whether or not the animation is played after a delay. More... | |
| void | showTargetOnStart (bool show) |
| Set whether or not the target is shown when the animation starts. More... | |
| bool | isTargetShownOnStart () const |
| Check whether or not the target is shown when the animation starts. More... | |
| void | hideTargetOnCompletion (bool hide) |
| Set whether or not the target is hidden when the animation completes. More... | |
| bool | isTargetHiddenOnCompletion () const |
| Check whether or not the target is hidden when the animation completes. More... | |
| void | setCurrentFrameResetOnInterrupt (bool reset) |
| Set whether or not the current animation frame is reset to the first frame when the animation is stopped before completing. More... | |
| bool | isCurrentFrameResetOnInterrupt () const |
| Check if the current frame is reset or not when animation is interrupted. More... | |
| void | addFrames (const Index &startPos, unsigned int numOfFrames, FrameArrangement arrangement=FrameArrangement::Horizontal) |
| Add frames from the spritesheet to the animation. More... | |
| void | addFrame (const Index &frame) |
| Add an animation frame to the end of the animation. More... | |
| void | insertFrameAt (unsigned int index, const Index &frameIndex) |
| Insert an animation frame within the current animation sequence. More... | |
| AnimationFrame * | getFirstFrame () |
| Get the first frame of the animation. More... | |
| const AnimationFrame * | getFirstFrame () const |
| AnimationFrame * | getLastFrame () |
| Get the last frame of the animation. More... | |
| const AnimationFrame * | getLastFrame () const |
| AnimationFrame * | getFrameAt (unsigned int index) |
| Get the frame at an index. More... | |
| const AnimationFrame * | getFrameAt (unsigned int index) const |
| AnimationFrame * | getFrame (const std::string &name) |
| Get the frame with a given name. More... | |
| const AnimationFrame * | getFrame (const std::string &name) const |
| const std::vector< AnimationFrame > & | getAllFrames () const |
| Get all the frames in the animation. More... | |
| unsigned int | getFrameCount () const |
| Get the total number of frames in the animation sequence. More... | |
| const Time & | getFrameTime () const |
| Get the time spent on each frame in the animation sequence. More... | |
| bool | hasFrameAtIndex (unsigned int index) const |
| Check if the animation has a frame at an index. More... | |
| void | removeFirstFrame () |
| Remove the first frame from the animation sequence. More... | |
| void | removeLastFrame () |
| Remove the last frame from the animation. More... | |
| void | removeFrameAt (unsigned int index) |
| Remove an animation frame withing the animation sequence. More... | |
| void | removeAll () |
| Remove all of the animation frames. More... | |
| void | finishOnFrame (int index) |
| Set the frame the animation should finish on. More... | |
| void | finishOnFirstFrame () |
| Set the animation to finish on the first frame. More... | |
| void | finishOnLastFrame () |
| Set the animation to finish on the last frame. More... | |
| unsigned int | getCompletionFrameIndex () const |
| Get the index of the completion frame. More... | |
| AnimationFrame * | getCurrentFrame () |
| Get the current frame. More... | |
| const AnimationFrame * | getCurrentFrame () const |
| AnimationFrame * | getNextFrame () |
| Get the frame that comes after the current frame. More... | |
| const AnimationFrame * | getNextFrame () const |
| AnimationFrame * | getPreviousFrame () |
| Get the frame that comes before the current frame. More... | |
| const AnimationFrame * | getPreviousFrame () const |
| float | getProgress () const |
| Get the completion progress of the animation in the range [0, 1]. More... | |
| void | suspendedEventListener (int id, bool suspend) |
| Prevent further executions of an event listener. More... | |
| bool | isEventListenerSuspended (int id) const |
| Check if an event listener is suspended or not. More... | |
| bool | removeEventListener (int id) |
| Remove an event listener from an event. More... | |
| int | onFrameSwitch (const Callback< AnimationFrame * > &callback, bool oneTime=false) |
| Add a callback to a frame switch event. More... | |
| int | onStart (const Callback< Animation * > &callback, bool oneTime=false) |
| Add an event listener to a start event. More... | |
| int | onPlay (const Callback< Animation * > &callback, bool oneTime=false) |
| Add an event listener to a play event. More... | |
| int | onPause (const Callback< Animation * > &callback, bool oneTime=false) |
| Add an event listener to a pause event. More... | |
| int | onResume (const Callback< Animation * > &callback, bool oneTime=false) |
| Add an event listener to a resume event. More... | |
| int | onRestart (const Callback< Animation * > &callback, bool oneTime=false) |
| Add an event listener to a restart event. More... | |
| int | onStop (const Callback< Animation * > &callback, bool oneTime=false) |
| Add an event listener to a stop event. More... | |
| int | onRepeat (const Callback< Animation * > &callback, bool oneTime=false) |
| Add an event listener to a repeat event. More... | |
| int | onComplete (const Callback< Animation * > &callback, bool oneTime=false) |
| Add an event listener to a complete event. More... | |
| void | emit (const std::string &event) |
| void | setCurrentFrameIndex (unsigned int index) |
Static Public Member Functions | |
| static Animation::Ptr | create (const std::string &name, const SpriteSheet &spriteSheet, const Time &duration=Time::Zero) |
| Create a new Animation object. More... | |
A SpriteSheet/frame based animation.
An ime::Animation specifies how a ime::Sprite object is animated.
In order to play the animation it must be added to a ime::Animator
Definition at line 51 of file Animation.h.
| using ime::Animation::Ptr = std::shared_ptr<Animation> |
Shared animation pointer.
Definition at line 53 of file Animation.h.
|
strong |
The playing direction of the animation.
Definition at line 58 of file Animation.h.
| ime::Animation::Animation | ( | const std::string & | name, |
| const SpriteSheet & | spriteSheet, | ||
| const Time & | duration = Time::Zero |
||
| ) |
Constructor.
| name | The name of the animation |
| spriteSheet | The spritesheet containing the animation frames |
| duration | The duration of the animation before it completes or loops around |
If the duration argument is unspecified (i.e left as ime::Time::Zero), then it will be derived from the frame rate. If the duration is specified then the frame rate will be overridden and derived from the given duration
| void ime::Animation::addFrame | ( | const Index & | frame | ) |
Add an animation frame to the end of the animation.
| frame | Index of the frame to be added from the spritesheet |
This function allows the animation to be created from frames that are not contiguously arranged on the spritesheet. If frame is out of the spritesheet bounds, then this function has no effect
| void ime::Animation::addFrames | ( | const Index & | startPos, |
| unsigned int | numOfFrames, | ||
| FrameArrangement | arrangement = FrameArrangement::Horizontal |
||
| ) |
Add frames from the spritesheet to the animation.
| startPos | Position of the first frame on the spritesheet |
| numOfFrames | Number of frames to add to the animation |
| arrangement | How the frames are arranged on the spritesheet |
| InvalidArgumentException | If startPos or numFrames is invalid |
Note that if arrangement is left unspecified, this function assumes that the animation frames are contiguously arranged horizontally on the spritesheet
|
static |
Create a new Animation object.
| name | The name of the animation |
| spriteSheet | The spritesheet containing the animation frames |
| duration | The duration of the animation before it completes or loops around |
If the duration argument is unspecified (i.e left as ime::Time::Zero), then it will be derived from the frame rate. If the duration is specified then the frame rate will be overridden and derived from the given duration
| void ime::Animation::finishOnFirstFrame | ( | ) |
Set the animation to finish on the first frame.
By default, the animation finishes on the last frame
| void ime::Animation::finishOnFrame | ( | int | index | ) |
Set the frame the animation should finish on.
| index | The index of the frame the animation should finish on |
Note that index will be ignored if it is higher than the number frames in the animation sequence and the default behavior will take place when the animation finishes. When set to a negative value, the animation will end on the last frame, otherwise it will end of the frame specified by index
By default, the animation finishes on the last frame
| void ime::Animation::finishOnLastFrame | ( | ) |
Set the animation to finish on the last frame.
By default, the animation finishes on the last frame
| const std::vector< AnimationFrame > & ime::Animation::getAllFrames | ( | ) | const |
Get all the frames in the animation.
| unsigned int ime::Animation::getCompletionFrameIndex | ( | ) | const |
Get the index of the completion frame.
| AnimationFrame * ime::Animation::getCurrentFrame | ( | ) |
Get the current frame.
| Direction ime::Animation::getDirection | ( | ) | const |
| const Time & ime::Animation::getDuration | ( | ) | const |
| AnimationFrame * ime::Animation::getFirstFrame | ( | ) |
Get the first frame of the animation.
| AnimationFrame * ime::Animation::getFrame | ( | const std::string & | name | ) |
Get the frame with a given name.
| name | The name of the frame |
| AnimationFrame * ime::Animation::getFrameAt | ( | unsigned int | index | ) |
Get the frame at an index.
| index | The index to get the frame of |
| unsigned int ime::Animation::getFrameCount | ( | ) | const |
Get the total number of frames in the animation sequence.
| unsigned int ime::Animation::getFrameRate | ( | ) | const |
Get the animations playback frame rate.
| const Time & ime::Animation::getFrameTime | ( | ) | const |
Get the time spent on each frame in the animation sequence.
| AnimationFrame * ime::Animation::getLastFrame | ( | ) |
Get the last frame of the animation.
| const std::string & ime::Animation::getName | ( | ) | const |
Get the name of the animation.
| AnimationFrame * ime::Animation::getNextFrame | ( | ) |
Get the frame that comes after the current frame.
| float ime::Animation::getPlaybackSpeed | ( | ) | const |
| AnimationFrame * ime::Animation::getPreviousFrame | ( | ) |
Get the frame that comes before the current frame.
| float ime::Animation::getProgress | ( | ) | const |
Get the completion progress of the animation in the range [0, 1].
| int ime::Animation::getRepeatCount | ( | ) | const |
Get the number of times the animation repeats before completing.
The returned value of this function implies the following:
-1 = The animation repeats forever and never completes 0 = The animation does not repeat x = The animation repeats x times, where x is some positive number
| const SpriteSheet & ime::Animation::getSpriteSheet | ( | ) | const |
Get the spritesheet used to construct the animation.
| const Time & ime::Animation::getStartDelay | ( | ) | const |
Get the time waited before the animation is played.
| bool ime::Animation::hasFrameAtIndex | ( | unsigned int | index | ) | const |
Check if the animation has a frame at an index.
| index | Index to be checked |
| void ime::Animation::hideTargetOnCompletion | ( | bool | hide | ) |
Set whether or not the target is hidden when the animation completes.
| hide | True to hide the target or false to leave the targets visibility state unmodified |
By default the targets visibility state is unmodified. This means that if the target was shown when the animation completed, then it will remain shown and if the target was hidden, it will remain hidden
| void ime::Animation::insertFrameAt | ( | unsigned int | index, |
| const Index & | frameIndex | ||
| ) |
Insert an animation frame within the current animation sequence.
| frameIndex | The index of the frame to insert from the spritesheet |
| index | The index where the frame should be inserted |
If index is negative or higher than the current number of frames, then the frame will be added at the end of the sequence instead. In addition, if frameIndex is out of the spritesheet bounds, then this function has no effect
| bool ime::Animation::isCurrentFrameResetOnInterrupt | ( | ) | const |
Check if the current frame is reset or not when animation is interrupted.
| bool ime::Animation::isEventListenerSuspended | ( | int | id | ) | const |
Check if an event listener is suspended or not.
| id | The identification number of the listener to be checked |
This function also returns false if the specified event listener does not exist
| bool ime::Animation::isLooped | ( | ) | const |
Check if the animation is looped or not.
| bool ime::Animation::isRepeating | ( | ) | const |
Check if the animation is repeating or not.
| bool ime::Animation::isStartDelayed | ( | ) | const |
Check whether or not the animation is played after a delay.
| bool ime::Animation::isStartDelayedOnce | ( | ) | const |
Check whether or not the animation is start delayed once.
| bool ime::Animation::isTargetHiddenOnCompletion | ( | ) | const |
Check whether or not the target is hidden when the animation completes.
| bool ime::Animation::isTargetShownOnStart | ( | ) | const |
Check whether or not the target is shown when the animation starts.
Add an event listener to a complete event.
| callback | The function to be executed when the animation completes |
| oneTime | True to execute the callback one-time or false to execute it every time the event is triggered |
You can add as many event listeners as you like to this event
| int ime::Animation::onFrameSwitch | ( | const Callback< AnimationFrame * > & | callback, |
| bool | oneTime = false |
||
| ) |
Add a callback to a frame switch event.
| callback | The function to be called when the animations current frame changes |
| oneTime | True to execute the callback one-time or false to execute it every time the event is triggered |
The callback is passed a pointer to the new animation frame on invocation. You can add as many event listeners as you like to this event
Add an event listener to a pause event.
| callback | The function to be executed when the animation is paused |
| oneTime | True to execute the callback one-time or false to execute it every time the event is triggered |
The callback is passed a pointer to the animation on invocation. You can add as many event listeners as you like to this event
Add an event listener to a play event.
| callback | The function to be executed when the animation starts animating |
| oneTime | True to execute the callback one-time or false to execute it every time the event is triggered |
This event is emitted after the start delay expires. At this point the animation starts to animate. To perform an action before the start delay executes, use onStart().
The callback is passed a pointer to the animation on invocation. You can add as many event listeners as you like to this event
Add an event listener to a repeat event.
| callback | The function to be executed when the animation is repeated |
| oneTime | True to execute the callback one-time or false to execute it every time the event is triggered |
You can add as many event listeners as you like to this event
Add an event listener to a restart event.
| callback | The function to be executed when the animation is restarted |
| oneTime | True to execute the callback one-time or false to execute it every time the event is triggered |
The callback is passed a pointer to the animation on invocation. You can add as many event listeners as you like to this event
Add an event listener to a resume event.
| callback | The function to be executed when the animation is resumed from a paused state |
| oneTime | True to execute the callback one-time or false to execute it every time the event is triggered |
The callback is passed a pointer to the animation on invocation. You can add as many event listeners as you like to this event
Add an event listener to a start event.
| callback | The function to be executed when the animation starts |
| oneTime | True to execute the callback one-time or false to execute it every time the event is triggered |
This event is emitted before the start delay timer executes. To perform an action after the start delay timer expires, use onPlay().
The callback is passed a pointer to the animation on invocation. You can add as many event listeners as you like to this event
Add an event listener to a stop event.
| callback | The function to be executed when the animation is stopped from a playing or paused state |
| oneTime | True to execute the callback one-time or false to execute it every time the event is triggered |
The callback is passed a pointer to the animation on invocation. You can add as many event listeners as you like to this event
| void ime::Animation::removeAll | ( | ) |
Remove all of the animation frames.
| bool ime::Animation::removeEventListener | ( | int | id | ) |
Remove an event listener from an event.
| id | The unique identification number of the event listener |
| void ime::Animation::removeFirstFrame | ( | ) |
Remove the first frame from the animation sequence.
The function has no effect if the animation has no frames
| void ime::Animation::removeFrameAt | ( | unsigned int | index | ) |
Remove an animation frame withing the animation sequence.
| index | The index of the animation frame to be removed |
The function has no effect if the animation has no frames
| void ime::Animation::removeLastFrame | ( | ) |
Remove the last frame from the animation.
The function has no effect if the animation has no frames
| void ime::Animation::setCurrentFrameResetOnInterrupt | ( | bool | reset | ) |
Set whether or not the current animation frame is reset to the first frame when the animation is stopped before completing.
| reset | True to reset the frame or false to leave it as is |
By default, the current frame is reset to the first frame
| void ime::Animation::setDirection | ( | Direction | direction | ) |
Set the direction in which the animation should be played.
| direction | The animations direction of play |
By default the direction of play is ime::Animation::Direction::Forward
| void ime::Animation::setDuration | ( | const Time & | duration | ) |
Set the duration of the animation.
| duration | The new duration of the animation |
By default, the duration is determined by the frame rate. When the duration is explicitly set, the frame rate is overridden and derived from the given duration. Therefore you only need to set either the frame rate or the duration
Note that if the specified duration is less than or equal to ime::Time::Zero, then the duration will be set to the default one. In addition, if the specified duration results in a frame time of more than 1 second, the frame rate will be set to zero.
| void ime::Animation::setFrameRate | ( | unsigned int | frameRate | ) |
Set the frame rate playback of the animation.
| frameRate | The frame rate to be set |
When the frame rate is explicitly set, the duration of the animation is overridden and derived from the given frame rate. Therefore you only need to set either the duration or the frame rate. In addition. you should note that if the frame rate is less than or equal to zero then it will be set to the default frame rate
By default, the frame rate is 24 frames per second
| void ime::Animation::setLoop | ( | bool | loop | ) |
Set whether or not the animation should repeat indefinitely.
| loop | True to loop animation, otherwise false |
This function is a simplification of setRepeatCount(). When the loop argument is true, the repeat count will be set to -1 and when it is false, the repeat count will be set to zero
| void ime::Animation::setPlaybackSpeed | ( | float | speed | ) |
Set the speed factor of the animation.
| speed | The new speed factor |
The speed factor controls the playback speed of the animation. For example, a speed of 2.0f will make the animation play at 2x its normal speed, a speed of 0.5f will make the animation play at half its normal speed and a speed of 0.0f will freeze the animation in time.
Note that a negative or zero playback speed value will be ignored
By default the speed is 1.0f (normal speed)
| void ime::Animation::setRepeatCount | ( | int | count | ) |
Set the repetition count of the animation.
| count | The number of times to repeat the animation |
Set count to '-1' to repeat the animation forever or set it to some positive number x, where x is the number of times to repeat the animation before it completes or set it to '0' to disable repetition if the animation is currently repeating.
Note that if count is set to a negative value that is not '-1', then the repeat count will be set to '0', meaning that the animation will not repeat
By default, the animation does not repeat
| void ime::Animation::setStartDelay | ( | const Time & | delay, |
| bool | oneTime = false |
||
| ) |
Set the time to wait before that animation is started.
| delay | The time to wait before the animation is played |
| oneTime | True to apply the start delay only when the animation is played for the first time or false (default) to apply the start delay every time the animation starts from the beginning |
Note that oneTime parameter only applies if the animation is repeating (see setRepeat()). For non-repeating animations, the start delay will always be applied if it's set
By default, the animation plays immediately
| void ime::Animation::showTargetOnStart | ( | bool | show | ) |
Set whether or not the target is shown when the animation starts.
| show | True to show the target or false to leave the targets visibility state unmodified |
By default, the target is shown when the animation starts. This means that if the target was hidden prior (explicitly, or via an animation finish event) then its visible property will be set to true when the animation starts playing
| void ime::Animation::suspendedEventListener | ( | int | id, |
| bool | suspend | ||
| ) |
Prevent further executions of an event listener.
| id | The event listeners unique identification number |
| suspend | True to suspend or false to unsuspend |
When suspended an event listener will be ignored when the event its listening to is fired. Execution will resume once it is unsuspended