Class for animating sprites. More...

#include <Animator.h>

Public Types
enum	Event { Event::AnimationPlay, Event::AnimationStart, Event::AnimationPause, Event::AnimationResume, Event::AnimationStop, Event::AnimationComplete, Event::AnimationRepeat, Event::AnimationRestart, Event::AnimationSwitch }
	Animation events (Triggered by the current animation) More...

using	Ptr = std::shared_ptr< Animator >

using	Animations = std::initializer_list< Animation::Ptr >
	Alias. More...

Public Member Functions
	Animator ()
	Default constructor. More...

	Animator (Sprite &target)
	Constructor. More...

	Animator (const Animator &other)
	Construct animator from an existing animator. More...

Animator &	operator= (Animator)
	Copy assignment operator. More...

Animation::Ptr	createAnimation (const std::string &name, const SpriteSheet &spriteSheet, Time duration=Time::Zero)
	Create an animation in the animator. More...

void	setTarget (Sprite &target)
	Set the target to be animated. More...

void	setTimescale (float timescale)
	Set the timescale factor. More...

float	getTimescale () const
	Get the timescale factor of the current animation. More...

bool	addAnimation (Animation::Ptr animation)
	Add an animation to the animator. More...

void	addAnimation (Animations animations)
	Add multiple animations at the same time to the animator. More...

Animation::Ptr	getAnimation (const std::string &name) const
	Get an animation in the animator. More...

Animation::Ptr	getCurrentAnimation () const
	Get the current animation. More...

bool	removeAnimation (const std::string &name)
	Remove an animation from the animator. More...

void	removeAll ()
	Remove all animations from the animator. More...

bool	hasAnimation (const Animation::Ptr &animation) const
	Check whether or not an animation exists in the animator. More...

bool	hasAnimation (const std::string &name) const
	Check whether or not an animation exists in the animator. More...

void	chainAnimation (Animation::Ptr animation)
	Chain an animation to the current animation. More...

void	chainAnimation (const std::string &name)
	Chain an animation to play after the current animation. More...

bool	removeChain (const std::string &name)
	Remove an animation from a chain. More...

void	clearAllChains ()
	Remove all the animations chained to the current animation. More...

bool	switchAnimation (const std::string &name, bool ignorePlaying=false)
	Change the current animation. More...

void	startAnimation (const std::string &name, bool unchain=false)
	Play an animation immediately. More...

void	play ()
	Play the current animation if any. More...

void	pause ()
	Pause the current animation. More...

void	resume ()
	Resume a paused animation. More...

void	stop ()
	Stop the current animation. More...

void	restart ()
	Restart the current animation from the beginning. More...

void	complete ()
	Finish the current animation. More...

bool	isAnimationPlaying () const
	Check whether or not the current animation is playing. More...

bool	isAnimationPaused () const
	Check whether or not the current animation is paused. More...

bool	hasAnimationStarted () const
	Check if the current animation has started. More...

void	update (Time deltaTime)
	Update the current animation. More...

int	on (Event event, Callback< Animation::Ptr > callback)
	Subscribe a callback to an animation event. More...

int	on (Event event, Callback<> callback)

int	on (Event event, const std::string &name, Callback< Animation::Ptr > callback)
	Subscribe a callback to a specific animation event. More...

int	on (Event event, const std::string &name, Callback<> callback)

bool	unsubscribe (Event event, int id)
	Remove a callback from an animation event. More...

bool	unsubscribe (Event event, const std::string &name, int id)
	Remove a callback from a specific animation. More...

Detailed Description

Class for animating sprites.

This class takes an Animation object and animates a sprite with the properties of the animation object. The animator can store multiple animations but only one can be played at a time. This class is usually not instantiated directly, all animatable entities internally have an animator

Definition at line 51 of file Animator.h.

Member Typedef Documentation

◆ Animations

using ime::Animator::Animations = std::initializer_list<Animation::Ptr>

Alias.

Definition at line 54 of file Animator.h.

Member Enumeration Documentation

◆ Event

enum ime::Animator::Event

strong

Animation events (Triggered by the current animation)

Enumerator
AnimationPlay	An animation is started playing.
AnimationStart	An animation is started animating (Fires after the start delay has expired)
AnimationPause	An animation is paused.
AnimationResume	An animation is resumed.
AnimationStop	An animation is stopped.
AnimationComplete	An animation is completed.
AnimationRepeat	An animation is repeating.
AnimationRestart	An animation is restarted from the beginning.
AnimationSwitch	An animation was changed while another was playing.

Definition at line 59 of file Animator.h.

Constructor & Destructor Documentation

◆ Animator() [1/3]

ime::Animator::Animator ( )

Default constructor.

Warning: When this constructor is used, you must call setTarget before using the animator, otherwise undefined behavior

See also: Animator(Sprite&); setTarget

◆ Animator() [2/3]

ime::Animator::Animator ( Sprite & target )

explicit

Constructor.

Parameters

target Sprite to animate

You don't have to call setTarget when this constructor is used

See also: Animator

◆ Animator() [3/3]

ime::Animator::Animator ( const Animator & other )

Construct animator from an existing animator.

Parameters

other The animator to construct this animator from

Warning: The target of other will not be copied because an animation target can only be owned by one animator. Therefore, the target to be animated will be null after construction. This means that you have to initialize the target yourself by calling setTarget function

See also: setTarget

Member Function Documentation

◆ addAnimation() [1/2]

bool ime::Animator::addAnimation ( Animation::Ptr animation )

Add an animation to the animator.

Parameters

animation Animation to be added

Returns: True if the animation was added or false if an animation with the same name as the specified animation already exists

◆ addAnimation() [2/2]

void ime::Animator::addAnimation ( Animations animations )

Add multiple animations at the same time to the animator.

Parameters

animations Animations to be added

Note: If an animation with the same name as one of the animations to be added already exist in the animator, then that animation will be skipped

See also: addAnimation

◆ chainAnimation() [1/2]

void ime::Animator::chainAnimation ( Animation::Ptr animation )

Chain an animation to the current animation.

Parameters

animation The animation to be chained

A chained animation is an animation that plays immediately after, the current animation finishes. If there is no current animation then this animation will be set as the current animation and played. If the current animation is chained to another animation then then the given animation will be chained to that animation

◆ chainAnimation() [2/2]

void ime::Animator::chainAnimation ( const std::string & name )

Chain an animation to play after the current animation.

Parameters

name	Name of the animation to be chained

A chained animation is an animation that plays immediately after, the current animation finishes. If there is no current animation then this animation will be set as the current animation and played. If the current animation is chained to another animation then then the given animation will be chained to that animation

◆ clearAllChains()

void ime::Animator::clearAllChains ( )

Remove all the animations chained to the current animation.

◆ complete()

void ime::Animator::complete ( )

Finish the current animation.

This function will force the current animation to complete and any chained animations will start playing

This function will dispatch an Event::AnimationComplete event

◆ createAnimation()

Animation::Ptr ime::Animator::createAnimation	(	const std::string &	name,
		const SpriteSheet &	spriteSheet,
		Time	duration = `Time::Zero`
	)

Create an animation in the animator.

Parameters

name	Name of the animation
spriteSheet	The spritesheet containing the animation frames
duration	The duration of the animation

Returns: The create animation or a nullptr if an animation with the same name already exists

The animation will be created and added to the Animator and a pointer to it will be returned. Therefore calling addAnimation with the returned pointer will always fail since it already exist in the animator

All the frame data used by the animation will be extracted from the spritesheet. As a result, the spritesheet must already be constructed before passed it as an argument. Passing an uncreated SpriteSheet is undefined behavior

By default the duration is derived from the frame rate. If the duration is specified then the frame rate will be overridden and derived from the given duration

◆ getAnimation()

Animation::Ptr ime::Animator::getAnimation ( const std::string & name ) const

Get an animation in the animator.

Parameters

name	The name of the animation to retrieve

Returns: Pointer to the requested animation if it exists, otherwise a nullptr

◆ getCurrentAnimation()

Animation::Ptr ime::Animator::getCurrentAnimation ( ) const

Get the current animation.

Returns: Pointer to the current animation if there is one, otherwise a nullptr

◆ getTimescale()

float ime::Animator::getTimescale ( ) const

Get the timescale factor of the current animation.

Returns: The timescale of the current animation

See also: setTimescale

◆ hasAnimation() [1/2]

bool ime::Animator::hasAnimation ( const Animation::Ptr & animation ) const

Check whether or not an animation exists in the animator.

Parameters

animation Animation to be checked

Returns: True if the animation exists, otherwise false

◆ hasAnimation() [2/2]

bool ime::Animator::hasAnimation ( const std::string & name ) const

Check whether or not an animation exists in the animator.

Parameters

name	Name of the animation to be checked

Returns: True if the animation exists, otherwise false

◆ hasAnimationStarted()

bool ime::Animator::hasAnimationStarted ( ) const

Check if the current animation has started.

Returns: True if the animation has started otherwise false

This function returns false if either the current animation is not playing or the animation is playing but it is still waiting for the start delay to expire

◆ isAnimationPaused()

bool ime::Animator::isAnimationPaused ( ) const

Check whether or not the current animation is paused.

Returns: True if the animation is paused, otherwise false

This function returns false if there is no current animation or the animation is playing or is stopped

◆ isAnimationPlaying()

bool ime::Animator::isAnimationPlaying ( ) const

Check whether or not the current animation is playing.

Returns: True if an animation is playing, otherwise false

This function will return false if there is no current animation or the animation is paused or stopped

◆ on() [1/2]

int ime::Animator::on	(	Event	event,
		Callback< Animation::Ptr >	callback
	)

Subscribe a callback to an animation event.

Parameters

event	Name of the event to subscribe a callback to
callback	Function to be executed when the event is fired

Returns: The callbacks identification number

The callback id must be remembered if the callback must be removed from the event at a later time

The callback function is optionally passed the animation that triggered the event

See also: unsubscribe

◆ on() [2/2]

int ime::Animator::on	(	Event	event,
		const std::string &	name,
		Callback< Animation::Ptr >	callback
	)

Subscribe a callback to a specific animation event.

Parameters

event	The event to subscribe a callback to
name	The name of the animation to subscribe callback to
callback	The Function to be executed when the event is fired

Returns: The callback identification number

This function subscribes a callback to events triggered by a specific animation only. The callback will not be invoked for events triggered by animations whose name do not match name.

To unsubscribe callbacks registered with this function, use the unsubscribe function that removes only callbacks that were subscribed to events triggered by specific animation objects

Note: The callback id must be remembered if the callback must be removed from the event at a later time

The callback function is optionally passed the animation that triggered the event which in this case its always the animation with the name

See also: unsubscribe(Event, const std::string, Callback)

◆ operator=()

Animator& ime::Animator::operator= ( Animator )

Copy assignment operator.

◆ pause()

void ime::Animator::pause ( )

Pause the current animation.

This function will dispatch an Event::AnimationPause event if the current animation was playing

◆ play()

void ime::Animator::play ( )

Play the current animation if any.

This function will start playing the current animation if it was pending a start. If the animation is paused, you have to call resume to play it

See also: pause and resume

◆ removeAll()

void ime::Animator::removeAll ( )

Remove all animations from the animator.

◆ removeAnimation()

bool ime::Animator::removeAnimation ( const std::string & name )

Remove an animation from the animator.

Parameters

name	Name of the animation to be removed

Returns: True if the animation was removed or false if it does not exist in the animator

◆ removeChain()

bool ime::Animator::removeChain ( const std::string & name )

Remove an animation from a chain.

Parameters

name	Name of the animation to be removed

Returns: True if the animation was removed or false if the is there is no such chain

◆ restart()

void ime::Animator::restart ( )

Restart the current animation from the beginning.

This function will dispatch an Event::AnimationRestart event

◆ resume()

void ime::Animator::resume ( )

Resume a paused animation.

This function will dispatch an Event::AnimationResume event if the current animation was paused

◆ setTarget()

void ime::Animator::setTarget ( Sprite & target )

Set the target to be animated.

Parameters

target The target for the animations

Warning: This function does not enforce the one animator per target rule. This means that if you call this function on multiple animator instances with the same argument, then target will be animated by multiple animators at once and the result may not be what you expect

◆ setTimescale()

void ime::Animator::setTimescale ( float timescale )

Set the timescale factor.

Parameters

timescale The new timescale factor

The timescale factor control the speed of the current animation For example, a timescale of 2 will make the animation twice as fast whilst a timescale of 0.5 will slow down the animation

The timescale will be set to 1 if timescale is negative.

By default the timescale is 1

◆ startAnimation()

void ime::Animator::startAnimation	(	const std::string &	name,
		bool	unchain = `false`
	)

Play an animation immediately.

Parameters

name	Name of the animation to play
unchain	True to clear all chained animations, or false to chained pending chains to the specified animation

This function will stop the current animation if there is any and immediately play the specified animation. If the specified animation does not exist in the animator the current animation will continue playing

By default, animations that were pending to be chained to the previous animation will be chained to the specified animation

To switch the animation without playing it, use the switchAnimation function

See also: switchAnimation

◆ stop()

void ime::Animator::stop ( )

Stop the current animation.

This function will dispatch an Event::AnimationStop event if the current animation was playing. The event is dispatched whether or not the current animation was started or waiting for a delay to expire

◆ switchAnimation()

bool ime::Animator::switchAnimation	(	const std::string &	name,
		bool	ignorePlaying = `false`
	)

Change the current animation.

Parameters

name	Name of the new animation
ignorePlaying	True to ignore switch if an animation is currently playing otherwise false to switch anyway

Returns: True if the animation was switched, of false if it does not exist

This function does not start the animation, it only sets the current animation to the given animation such that when play() is called, the given animation is played.

By default the animation will be switched whether or not there is an active animation

To switch and immediately play an animation use the playAnimation function

See also: playAnimation

◆ unsubscribe() [1/2]

bool ime::Animator::unsubscribe	(	Event	event,
		const std::string &	name,
		int	id
	)

Remove a callback from a specific animation.

Parameters

event	Th event to remove callback from
name	The name of the animation to remove the callback from
id	The identification number of the callback

Returns: True if the callback was removed or false if the given event does not have a callback associated with the given id

Note that this function removes only callbacks that were subscribed to animation events triggered by a specific animation. In other words, it is only applicable to callbacks that were registered using the on(Event, const std::string&, Callback) function. For other callbacks, unsubscribe using the unsubscribe(Event, int) function

See also: on(Event, const std::string&, Callback)

◆ unsubscribe() [2/2]

bool ime::Animator::unsubscribe	(	Event	event,
		int	id
	)

Remove a callback from an animation event.

Parameters

event	The event to remove the callback from
id	Identification number of the callback

Returns: True if the callback was removed or false if the given event does not have a callback associated with the given id

See also: on

◆ update()

void ime::Animator::update ( Time deltaTime )

Update the current animation.

Parameters

deltaTime Time passed since last animation update

The documentation for this class was generated from the following file:

Animator.h

Public Types

Public Member Functions

Detailed Description

Member Typedef Documentation

◆ Animations

Member Enumeration Documentation

◆ Event

Constructor & Destructor Documentation

◆ Animator() [1/3]

◆ Animator() [2/3]

◆ Animator() [3/3]

Member Function Documentation

◆ addAnimation() [1/2]

◆ addAnimation() [2/2]

◆ chainAnimation() [1/2]

◆ chainAnimation() [2/2]

◆ clearAllChains()

◆ complete()

◆ createAnimation()

◆ getAnimation()

◆ getCurrentAnimation()

◆ getTimescale()

◆ hasAnimation() [1/2]

◆ hasAnimation() [2/2]

◆ hasAnimationStarted()

◆ isAnimationPaused()

◆ isAnimationPlaying()

◆ on() [1/2]

◆ on() [2/2]

◆ operator=()

◆ pause()

◆ play()

◆ removeAll()

◆ removeAnimation()

◆ removeChain()

◆ restart()

◆ resume()

◆ setTarget()

◆ setTimescale()

◆ startAnimation()

◆ stop()

◆ switchAnimation()

◆ unsubscribe() [1/2]

◆ unsubscribe() [2/2]

◆ update()