#include <animated.hpp>

Classes
struct	frame

Public Types
typedef std::pair< std::chrono::milliseconds, T >	frame_description

typedef std::vector< frame_description >	anim_description

Public Member Functions
	animated (const std::chrono::milliseconds &start_time=std::chrono::milliseconds{0})
	Creates an animation with no frames; add_frame() populates it afterward. More...

	animated (const anim_description &cfg, const std::chrono::milliseconds &start_time=std::chrono::milliseconds{0}, bool force_change=false)
	Creates an animation with its frame list already built from cfg. More...

virtual	~animated ()=default

void	add_frame (const std::chrono::milliseconds &duration, const T &value, bool force_change=false)
	Appends a frame, starting where the previous one ends (or at start_time, if first). More...

void	start_animation (const std::chrono::milliseconds &start_time_offset, bool cycles=false)
	Anchors the timeline to the current tick, then begins playback. More...

void	pause_animation ()
	Freezes the timeline in place. More...

void	resume_animation ()
	Shifts the timeline forward by the time spent paused, then continues playback. More...

void	advance_to_current_frame ()
	Moves current_frame_index_ forward to match the current tick, one frame at a time (or in whole cycles, if far enough behind). More...

bool	need_update () const
	True once the current tick has reached the current frame's end, meaning advance_to_current_frame() has a new frame to move to. More...

bool	animation_finished () const
	True if playback has run past the last frame, is not yet started, or has no frames. More...

bool	cycles () const
	True if the animation loops back to the first frame instead of stopping at the last. More...

std::chrono::milliseconds	get_elapsed_time () const
	Time since playback began, per get_playback_tick(). More...

void	apply_time_offset (const std::chrono::milliseconds &time)
	Shifts the timeline so the current tick corresponds to the given animation time, then restarts frame tracking from the beginning to resync. More...

void	set_duration_limit (const std::chrono::milliseconds &time)

std::chrono::milliseconds	get_animation_duration () const
	get_end_time() minus get_begin_time(): how long one pass through all frames takes. More...

std::chrono::milliseconds	get_begin_time () const
	Animation-time offset of the first frame's start. More...

std::chrono::milliseconds	get_end_time () const
	Animation-time offset where the last frame ends. More...

void	set_begin_time (const std::chrono::milliseconds &new_begin_time)
	Rebases the timeline onto a new begin time, offsetting every frame's start_time_ by the difference so their durations and order are unchanged. More...

std::chrono::milliseconds	get_current_frame_begin_time () const
	Animation-time offset where the current frame starts. More...

std::chrono::milliseconds	get_current_frame_end_time () const
	Animation-time offset where the current frame ends. More...

std::chrono::milliseconds	get_time_in_current_frame () const
	How far into its own duration the current frame is, clamped to [0, duration]. More...

const T &	get_current_frame () const

const T &	get_first_frame () const

const T &	get_frame (std::size_t n) const

const T &	get_last_frame () const

std::size_t	get_frames_count () const

void	force_change ()
	Clears the flag returned by is_static(). More...

bool	is_static () const
	True when the single-unchanging-frame optimization is enabled: need_update() will always report false, since there is never a different frame to advance to. More...

void	set_uses_acceleration (bool uses_accel)
	Selects which of the two global timelines get_current_animation_tick() reads for this animation: accelerated if true, normal if false. More...

bool	uses_acceleration () const
	Which timeline this animation currently reads; see set_uses_acceleration(). More...

Static Public Attributes
static const T	void_value_

Protected Member Functions
void	remove_frames_until (const std::chrono::milliseconds &starting_time)
	Drops whole frames from the front while their end time is still before starting_time, then advances the begin time by their durations. More...

void	set_end_time (const std::chrono::milliseconds &ending_time)
	Reduces or extends the frame list so get_end_time() becomes ending_time: drops frames after the cut and shortens the one it falls in, extends the last frame if ending_time is later, or (if ending_time is before the current begin time) collapses to a zero-length first frame. More...

Private Member Functions
std::chrono::steady_clock::time_point	get_playback_tick () const
	The tick get_elapsed_time() and get_time_in_current_frame() treat as "now": frozen at pause_tick_ while paused_, otherwise the live tick from get_current_animation_tick(). More...

Private Attributes
std::chrono::milliseconds	starting_frame_time_

std::chrono::milliseconds	max_animation_time_

std::vector< frame >	frames_

std::size_t	current_frame_index_

bool	started_

bool	paused_

bool	finished_

bool	cycles_

bool	uses_acceleration_

std::chrono::steady_clock::time_point	animation_start_tick_

std::chrono::steady_clock::time_point	next_frame_tick_

std::chrono::steady_clock::time_point	pause_tick_

bool	is_static_

Friends
class	unit_animation

Detailed Description

template<typename T>
class animated< T >

Definition at line 48 of file animated.hpp.

Member Typedef Documentation

◆ anim_description

template<typename T >

typedef std::vector<frame_description> animated< T >::anim_description

Definition at line 52 of file animated.hpp.

◆ frame_description

template<typename T >

typedef std::pair<std::chrono::milliseconds, T> animated< T >::frame_description

Definition at line 51 of file animated.hpp.

Constructor & Destructor Documentation

◆ animated() [1/2]

template<typename T >

animated< T >::animated ( const std::chrono::milliseconds & start_time = std::chrono::milliseconds{0} )

Creates an animation with no frames; add_frame() populates it afterward.

Parameters

start_time Logical start time of the animation timeline (default 0ms)

◆ animated() [2/2]

template<typename T >

animated< T >::animated	(	const anim_description &	cfg,
		const std::chrono::milliseconds &	start_time = `std::chrono::milliseconds{0}`,
		bool	force_change = `false`
	)

explicit

Creates an animation with its frame list already built from cfg.

Parameters

cfg	Sequence of (duration, value) pairs to build the frame list from
start_time	Logical start time of the animation timeline
force_change	See add_frame(). Applies to the whole sequence built from cfg.

◆ ~animated()

template<typename T >

virtual animated< T >::~animated ( )

virtualdefault

Member Function Documentation

◆ add_frame()

template<typename T >

void animated< T >::add_frame	(	const std::chrono::milliseconds &	duration,
		const T &	value,
		bool	force_change = `false`
	)

Appends a frame, starting where the previous one ends (or at start_time, if first).

Parameters

duration	How long this frame should be displayed
value	The data/state for this frame
force_change	Forces is_static() false even if this is the only frame added so far; use when the frame's own value can change over time despite the frame count.

Referenced by unit_animation::add_frame(), terrain_builder::load_images(), terrain_builder::rebuild_terrain(), display::reinit_flags_for_team(), and unit_animation::start_animation().

◆ advance_to_current_frame()

template<typename T >

void animated< T >::advance_to_current_frame ( )

Moves current_frame_index_ forward to match the current tick, one frame at a time (or in whole cycles, if far enough behind).

Marks the animation finished() if it runs out of frames without cycles().

Referenced by unit_animation::try_advance_to_current_frame(), and terrain_builder::update_animation().

◆ animation_finished()

template<typename T >

bool animated< T >::animation_finished ( ) const

True if playback has run past the last frame, is not yet started, or has no frames.

Always true for a cycling animation, since it never runs out.

Referenced by unit_animation::animation_finished().

◆ apply_time_offset()

template<typename T >

void animated< T >::apply_time_offset ( const std::chrono::milliseconds & time )

Shifts the timeline so the current tick corresponds to the given animation time, then restarts frame tracking from the beginning to resync.

Used to desynchronize otherwise-identical animations for visual variety.

Parameters

time	e.g. 300ms starts the animation as if it had been playing for 300ms already

◆ cycles()

template<typename T >

bool animated< T >::cycles ( ) const

inline

True if the animation loops back to the first frame instead of stopping at the last.

Definition at line 112 of file animated.hpp.

References animated< T >::cycles_.

◆ force_change()

template<typename T >

void animated< T >::force_change ( )

inline

Clears the flag returned by is_static().

Needed because is_static_ is set purely from frame count: a single frame can still change visually over time through means this class doesn't track (e.g. unit_frame's interpolated offset/alpha/image parameters), in which case the owner must call this to keep need_update() reporting true.

Definition at line 174 of file animated.hpp.

References animated< T >::is_static_.

◆ get_animation_duration()

template<typename T >

std::chrono::milliseconds animated< T >::get_animation_duration ( ) const

get_end_time() minus get_begin_time(): how long one pass through all frames takes.

Referenced by terrain_builder::tile::rebuild_cache().

◆ get_begin_time()

template<typename T >

std::chrono::milliseconds animated< T >::get_begin_time ( ) const

Animation-time offset of the first frame's start.

Default 0ms; see set_begin_time().

Referenced by unit_animation::get_begin_time().

◆ get_current_frame()

template<typename T >

const T& animated< T >::get_current_frame ( ) const

◆ get_current_frame_begin_time()

template<typename T >

std::chrono::milliseconds animated< T >::get_current_frame_begin_time ( ) const

Animation-time offset where the current frame starts.

Referenced by unit_animation::get_current_frame_begin_time().

◆ get_current_frame_end_time()

template<typename T >

std::chrono::milliseconds animated< T >::get_current_frame_end_time ( ) const

Animation-time offset where the current frame ends.

◆ get_elapsed_time()

template<typename T >

std::chrono::milliseconds animated< T >::get_elapsed_time ( ) const

Time since playback began, per get_playback_tick().

0 if not started. Capped at the limit set by set_duration_limit(), if any.

Referenced by unit_animation::get_elapsed_time().

◆ get_end_time()

template<typename T >

std::chrono::milliseconds animated< T >::get_end_time ( ) const

Animation-time offset where the last frame ends.

For 3 seconds of frames starting at 500ms (see get_begin_time()), this returns 3500ms.

Referenced by unit_animation::get_end_time().

◆ get_first_frame()

template<typename T >

const T& animated< T >::get_first_frame ( ) const

◆ get_frame()

template<typename T >

const T& animated< T >::get_frame ( std::size_t n ) const

Referenced by terrain_builder::tile::rebuild_cache().

◆ get_frames_count()

template<typename T >

std::size_t animated< T >::get_frames_count ( ) const

Referenced by terrain_builder::load_images(), and terrain_builder::tile::rebuild_cache().

◆ get_last_frame()

template<typename T >

const T& animated< T >::get_last_frame ( ) const

Referenced by unit_animation::get_last_frame().

◆ get_playback_tick()

template<typename T >

std::chrono::steady_clock::time_point animated< T >::get_playback_tick ( ) const

private

The tick get_elapsed_time() and get_time_in_current_frame() treat as "now": frozen at pause_tick_ while paused_, otherwise the live tick from get_current_animation_tick().

Playback bookkeeping (start/pause/resume/advance) reads get_current_animation_tick() directly instead, since it needs the live clock even while paused_.

◆ get_time_in_current_frame()

template<typename T >

std::chrono::milliseconds animated< T >::get_time_in_current_frame ( ) const

How far into its own duration the current frame is, clamped to [0, duration].

◆ is_static()

template<typename T >

bool animated< T >::is_static ( ) const

inline

True when the single-unchanging-frame optimization is enabled: need_update() will always report false, since there is never a different frame to advance to.

Set from add_frame()/the constructor when the animation has exactly one frame, unless force_change requests otherwise; cleared permanently by add_frame() past the first frame, or by force_change().

Definition at line 181 of file animated.hpp.

References animated< T >::is_static_.

◆ need_update()

template<typename T >

bool animated< T >::need_update ( ) const

True once the current tick has reached the current frame's end, meaning advance_to_current_frame() has a new frame to move to.

Referenced by terrain_builder::update_animation().

◆ pause_animation()

template<typename T >

void animated< T >::pause_animation ( )

Freezes the timeline in place.

Playback continues from the same point via resume_animation().

Referenced by unit_animation::pause_animation().

◆ remove_frames_until()

template<typename T >

void animated< T >::remove_frames_until ( const std::chrono::milliseconds & starting_time )

protected

Drops whole frames from the front while their end time is still before starting_time, then advances the begin time by their durations.

May overshoot starting_time if it falls inside a remaining frame, rather than split that frame.

Parameters

starting_time Animation time the new begin time should reach

◆ resume_animation()

template<typename T >

void animated< T >::resume_animation ( )

Shifts the timeline forward by the time spent paused, then continues playback.

Referenced by unit_animation::resume_animation().

◆ set_begin_time()

template<typename T >

void animated< T >::set_begin_time ( const std::chrono::milliseconds & new_begin_time )

Rebases the timeline onto a new begin time, offsetting every frame's start_time_ by the difference so their durations and order are unchanged.

◆ set_duration_limit()

template<typename T >

void animated< T >::set_duration_limit ( const std::chrono::milliseconds & time )

Parameters

time	Elapsed time past which animation_finished() reports true regardless of actual progress (0 = no limit). Does not affect frame playback, only that query.

Referenced by unit_animation::set_duration_limit().

◆ set_end_time()

template<typename T >

void animated< T >::set_end_time ( const std::chrono::milliseconds & ending_time )

protected

Reduces or extends the frame list so get_end_time() becomes ending_time: drops frames after the cut and shortens the one it falls in, extends the last frame if ending_time is later, or (if ending_time is before the current begin time) collapses to a zero-length first frame.

Parameters

ending_time Animation time the new end time should reach

◆ set_uses_acceleration()

template<typename T >

void animated< T >::set_uses_acceleration ( bool uses_accel )

inline

Selects which of the two global timelines get_current_animation_tick() reads for this animation: accelerated if true, normal if false.

Definition at line 185 of file animated.hpp.

References animated< T >::uses_acceleration_.

Referenced by unit_animation::start_animation().

◆ start_animation()

template<typename T >

void animated< T >::start_animation	(	const std::chrono::milliseconds &	start_time_offset,
		bool	cycles = `false`
	)

Anchors the timeline to the current tick, then begins playback.

Parameters

start_time_offset	How far into the animation to start (0 = from beginning)
cycles	If true, loop back to the first frame on reaching the end; if false, stop there

Referenced by halo::halo_impl::effect::effect(), terrain_builder::load_images(), terrain_builder::rebuild_terrain(), and unit_animation::particle::start_animation().

◆ uses_acceleration()

template<typename T >

bool animated< T >::uses_acceleration ( ) const

inline

Which timeline this animation currently reads; see set_uses_acceleration().

Definition at line 188 of file animated.hpp.

References animated< T >::uses_acceleration_.

Friends And Related Function Documentation

◆ unit_animation

template<typename T >

friend class unit_animation

friend

Definition at line 193 of file animated.hpp.

Member Data Documentation

◆ animation_start_tick_

template<typename T >

std::chrono::steady_clock::time_point animated< T >::animation_start_tick_

private

Definition at line 240 of file animated.hpp.

◆ current_frame_index_

template<typename T >

std::size_t animated< T >::current_frame_index_

private

Definition at line 229 of file animated.hpp.

◆ cycles_

template<typename T >

bool animated< T >::cycles_

private

Definition at line 235 of file animated.hpp.

Referenced by animated< T >::cycles().

◆ finished_

template<typename T >

bool animated< T >::finished_

private

Definition at line 234 of file animated.hpp.

◆ frames_

template<typename T >

std::vector<frame> animated< T >::frames_

private

Definition at line 228 of file animated.hpp.

◆ is_static_

template<typename T >

bool animated< T >::is_static_

private

Definition at line 245 of file animated.hpp.

Referenced by animated< T >::force_change(), and animated< T >::is_static().

◆ max_animation_time_

template<typename T >

std::chrono::milliseconds animated< T >::max_animation_time_

private

Definition at line 225 of file animated.hpp.

◆ next_frame_tick_

template<typename T >

std::chrono::steady_clock::time_point animated< T >::next_frame_tick_

private

Definition at line 241 of file animated.hpp.

◆ pause_tick_

template<typename T >

std::chrono::steady_clock::time_point animated< T >::pause_tick_

private

Definition at line 242 of file animated.hpp.

◆ paused_

template<typename T >

bool animated< T >::paused_

private

Definition at line 233 of file animated.hpp.

◆ started_

template<typename T >

bool animated< T >::started_

private

Definition at line 232 of file animated.hpp.

◆ starting_frame_time_

template<typename T >

std::chrono::milliseconds animated< T >::starting_frame_time_

private

Definition at line 224 of file animated.hpp.

◆ uses_acceleration_

template<typename T >

bool animated< T >::uses_acceleration_

private

Definition at line 236 of file animated.hpp.

Referenced by animated< T >::set_uses_acceleration(), and animated< T >::uses_acceleration().

◆ void_value_

template<typename T >

const T animated< T >::void_value_

static

Definition at line 190 of file animated.hpp.

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

animated.hpp

Classes

Public Types

Public Member Functions

Static Public Attributes

Protected Member Functions

Private Member Functions

Private Attributes

Friends

Detailed Description

template<typename T> class animated< T >

Member Typedef Documentation

◆ anim_description

◆ frame_description

Constructor & Destructor Documentation

◆ animated() [1/2]

◆ animated() [2/2]

◆ ~animated()

Member Function Documentation

◆ add_frame()

◆ advance_to_current_frame()

◆ animation_finished()

◆ apply_time_offset()

◆ cycles()

◆ force_change()

◆ get_animation_duration()

◆ get_begin_time()

◆ get_current_frame()

◆ get_current_frame_begin_time()

◆ get_current_frame_end_time()

◆ get_elapsed_time()

◆ get_end_time()

◆ get_first_frame()

◆ get_frame()

◆ get_frames_count()

◆ get_last_frame()

◆ get_playback_tick()

◆ get_time_in_current_frame()

◆ is_static()

◆ need_update()

◆ pause_animation()

◆ remove_frames_until()

◆ resume_animation()

◆ set_begin_time()

◆ set_duration_limit()

◆ set_end_time()

◆ set_uses_acceleration()

◆ start_animation()

◆ uses_acceleration()

Friends And Related Function Documentation

◆ unit_animation

Member Data Documentation

◆ animation_start_tick_

◆ current_frame_index_

◆ cycles_

◆ finished_

◆ frames_

◆ is_static_

◆ max_animation_time_

◆ next_frame_tick_

◆ pause_tick_

◆ paused_

◆ started_

◆ starting_frame_time_

◆ uses_acceleration_

◆ void_value_

template<typename T>
class animated< T >