Class Animation

Class Documentation

class Animation

A named collection of animation channels.

An Animation owns its Channel objects and is the only way to create them, assigning each a unique Id. Channels can be looked up by index, by name, or by id, reordered, and removed. The animation also carries an overall time range (start_time() / end_time()) used for sampling.

Public Functions

Animation() = default

Constructs an unnamed animation.

inline explicit Animation(const std::string &name)

Constructs an animation with the given name.

inline const std::string &name() const

The animation’s name.

inline void set_name(const std::string &name)

Renames the animation.

Channel &create_channel(const std::string &channel_name)

Creates a new channel named channel_name and returns it.

Channel &create_channel(const std::string &channel_name, size_t index)

Creates a new channel and inserts it at index.

Throws:

std::out_of_range – if index is greater than the channel count.

Channel &copy_channel(const Channel &source_channel, const std::string &new_name = "")

Creates a deep copy of source_channel within this animation.

Parameters:

  • source_channel – The channel to copy keyframes from.

  • new_name – Name for the copy; if empty, the source name plus “_copy”.

Returns:

The newly created channel (with its own unique id).

Animation copy() const

Returns a deep copy of this animation (channels get fresh ids).

Animation copy(const std::string &new_name) const

Returns a deep copy of this animation with a new name.

const Channel &channel(size_t index) const

Returns the channel at index.

Throws:

std::out_of_range – if out of range.

const Channel &operator[](size_t index) const

Indexed access.

Throws:

std::out_of_range – if out of range.

Channel &channel(size_t index)

Returns the channel at index.

Throws:

std::out_of_range – if out of range.

Channel &operator[](size_t index)

Indexed access.

Throws:

std::out_of_range – if out of range.

Channel &channel(const std::string &channel_name)

Returns the first channel named channel_name.

Throws:

std::out_of_range – if none matches.

Channel &operator[](const std::string &channel_name)

Name lookup.

Throws:

std::out_of_range – if none matches.

Channel &channel(Id channel_id)

Returns the channel with channel_id.

Throws:

std::out_of_range – if none matches.

Channel &operator[](Id channel_id)

Id lookup.

Throws:

std::out_of_range – if none matches.

const Channel &channel(const std::string &channel_name) const

Returns the first channel named channel_name.

Throws:

std::out_of_range – if none matches.

const Channel &operator[](const std::string &channel_name) const

Name lookup.

Throws:

std::out_of_range – if none matches.

const Channel &channel(Id channel_id) const

Returns the channel with channel_id.

Throws:

std::out_of_range – if none matches.

const Channel &operator[](Id channel_id) const

Id lookup.

Throws:

std::out_of_range – if none matches.

inline size_t size() const

Number of channels.

inline size_t num_channels() const

Number of channels (alias for size()).

bool has_channel(const std::string &channel_name) const

True if a channel named channel_name exists.

inline bool empty() const

True if the animation has no channels.

void reorder_channel(size_t from_index, size_t to_index)

Moves the channel at from_index to to_index.

Throws:

std::out_of_range – if either index is out of range.

void reorder_channel(const std::string &channel_name, size_t to_index)

Moves the channel named channel_name to to_index.

Throws:

std::out_of_range – if the name is not found or to_index is out of range.

void reorder_channel(Id channel_id, size_t to_index)

Moves the channel with channel_id to to_index.

Throws:

std::out_of_range – if the id is not found or to_index is out of range.

void sort_channels()

Sorts the channels by name, ascending.

The sort is stable, so channels sharing a name keep their relative order. Only the index order changes: ids, names and keyframes are untouched, and because the channels themselves are not moved, references and pointers obtained before the sort — including those from channel(Id) — stay valid.

void sort_channels(const std::function<bool(const Channel&, const Channel&)> &comparator)

Sorts the channels using a custom ordering.

See also

sort_channels()

Parameters:

comparator – A strict weak ordering; returns true when the first channel should be placed before the second.

void clear()

Removes all channels.

void remove_channel(size_t index)

Removes the channel at index.

Throws:

std::out_of_range – if out of range.

void remove_channel(const std::string &channel_name)

Removes the first channel named channel_name.

Throws:

std::out_of_range – if none matches.

void remove_channel(Id channel_id)

Removes the channel with channel_id.

Throws:

std::out_of_range – if none matches.

std::vector<std::string> channel_names() const

The names of all channels, in order.

const std::vector<std::unique_ptr<Channel>> &channels()

Direct access to the owned channel vector.

const std::vector<std::unique_ptr<Channel>> &channels() const

Direct read access to the owned channel vector.

inline double start_time() const

The animation’s start time.

void set_start_time(double start_time)

Sets the start time (clamped so it does not exceed the end time).

inline double end_time() const

The animation’s end time.

void set_end_time(double end_time)

Sets the end time (clamped so it is not below the start time).

double length() const

The animation’s duration (end_time() - start_time()).

void set_length(double length)

Sets the duration by moving the end time relative to the start.

Throws:

std::invalid_argument – if length is negative.

size_t num_samples(double sample_rate, RangeEnd range_end = RangeEnd::Exclusive) const

Number of samples spanning the animation at sample_rate.

The span is half-open by default, matching Channel::evaluate_range_by_rate(): the result is length() * sample_rate rounded up, so 4 seconds at 30 Hz gives 120 rather than 121. Pass RangeEnd::Inclusive to count the closing sample. An animation with no channels gives 0; one with no length gives 1. Matches Channel::num_samples() in convention, return type and default.

Parameters:

  • sample_rate – Samples per unit time; must be positive.

  • range_end – Whether the end time is counted; half-open by default.

Throws:

std::invalid_argument – if sample_rate is not positive.

Returns:

Sample count (0 when there are no channels).

SampleTimes sample_times(int num_samples, RangeEnd range_end = RangeEnd::Exclusive) const

Times spanning the animation, for num_samples samples.

The range runs from start_time() to end_time(), so every channel baked over that range with the same count shares these times: they describe the animation’s time base rather than any one channel’s. Nothing is allocated.

Throws:

std::invalid_argument – if num_samples is negative.

SampleTimes sample_times_by_rate(double sample_rate, RangeEnd range_end = RangeEnd::Exclusive) const

Times spanning the animation at sample_rate.

Its size() is what num_samples() reports for the same arguments, so an animation with no channels gives no times. Nothing is allocated.

Throws:

std::invalid_argument – if sample_rate is not positive.

bool operator==(const Animation &other) const

Equality across name, time range and channels.

bool operator!=(const Animation &other) const

Negation of operator==.