Magnum::Animation namespace

Keyframe-based animation.

Contents

This library is built as part of Magnum by default. To use it, you need to find Magnum package and link to Magnum::Magnum target. See Downloading and building, Usage with CMake and Keyframe-based animation for more information.

Classes

template<class T, class K = T>
class Player
Animation player.
template<class K, class V, class R = ResultOf<V>>
class Track
Animation track.
template<class K, class V, class R = ResultOf<V>>
class TrackView
Animation track view.
template<class K>
class TrackViewStorage
Type-erased track view storage.

Enums

enum class Interpolation: UnsignedByte { Constant, Linear, Spline, Custom }
Animation interpolation.
enum class Extrapolation: UnsignedByte { Extrapolated, Constant, DefaultConstructed }
Animation extrapolation behavior.
enum class State: UnsignedByte { Playing, Paused, Stopped }
Player state.

Typedefs

template<class V>
using ResultOf = typename Implementation::ResultTraits<V>::Type
Animation result type for given value type.

Functions

auto operator<<(Debug& debug, Interpolation value) -> Debug&
Debug output operator.
template<class V, class R = ResultOf<V>>
auto interpolatorFor(Interpolation interpolation) -> auto
Interpolator function for given type.
auto operator<<(Debug& debug, Extrapolation value) -> Debug&
Debug output operator.
template<class K, class V, class R = ResultOf<V>>
auto interpolate(const Containers::StridedArrayView<const K>& keys, const Containers::StridedArrayView<const V>& values, Extrapolation before, Extrapolation after, R(*)(const V&, const V&, Float) interpolator, K frame, std::size_t& hint) -> R
Interpolate animation value.
template<class K, class V, class R = ResultOf<V>>
auto interpolateStrict(const Containers::StridedArrayView<const K>& keys, const Containers::StridedArrayView<const V>& values, R(*)(const V&, const V&, Float) interpolator, K frame, std::size_t& hint) -> R
Interpolate animation value with strict constraints.
auto operator<<(Debug& debug, State value) -> Debug&
Debug output operator.

Enum documentation

enum class Magnum::Animation::Interpolation: UnsignedByte

Animation interpolation.

Describes the general desired way to interpolate animation keyframes. The concrete choice of interpolator function is in user's hands.

Enumerators
Constant

Constant interpolation.

Linear

Linear interpolation.

Spline

Spline interpolation.

Custom

Custom interpolation. An user-supplied interpolation function should be used.

enum class Magnum::Animation::Extrapolation: UnsignedByte

Animation extrapolation behavior.

Describes what value is returned for frames outside of keyframe range for given track (frame lower than first keyframe or frame larger or equal to last keyframe).

Enumerators
Extrapolated

Values of first two / last two keyframes are extrapolated. In case there is only one keyframe, it's passed to both inputs of the interpolator. Implicit behavior in interpolateStrict().

Constant

Value of first/last keyframe is used. In other words, for the first keyframe the interpolator is called with first two keyframes and interpolation factor set to 0.0f; for the last keyframe the interpolator is called with last two keyframes and interpolation factor set to 1.0f. In case there is only one keyframe, it's passed to both inputs of the interpolator.

DefaultConstructed

Default-constructed value is returned.

enum class Magnum::Animation::State: UnsignedByte

Player state.

Enumerators
Playing

The animation clip is currently playing. Setting the state to State::Playing does nothing.

Paused

The animation clip is currently paused. Setting the state to State::Playing starts playing from where it left, setting the state to State::Stopped stops the animation, setting the state to State::Paused does nothing.

Stopped

The animation clip is currently stopped. Setting the state to State::Playing starts playing from the beginning, attempting to set the state to State::Paused will retain the State::Stopped state, setting the state to State::Stopped does nothing.

Typedef documentation

template<class V>
using Magnum::Animation::ResultOf = typename Implementation::ResultTraits<V>::Type

Animation result type for given value type.

Result of interpolating two V values (for example interpolating two Color3 values gives back a Color3 again, but interpolating a CubicHermite2D spline results in Vector2).

Function documentation

Debug& Magnum::Animation::operator<<(Debug& debug, Interpolation value)

Debug output operator.

template<class V, class R = ResultOf<V>>
auto Magnum::Animation::interpolatorFor(Interpolation interpolation)

Interpolator function for given type.

Template parameters
V Value type
R Result type

Expects that interpolation is not Interpolation::Custom. Favors output correctness over performance, supply custom interpolator functions for faster but potentially less correct results.

InterpolationValue typeResult typeInterpolator
Constantany VVMath::select()
ConstantMath::CubicHermite<T>TMath::select()
LinearboolboolMath::select()
LinearMath::BoolVectorMath::BoolVectorMath::select()
Linearany scalar VVMath::lerp()
Linearany vector VVMath::lerp()
LinearMath::ComplexMath::ComplexMath::slerp()
LinearMath::QuaternionMath::QuaternionMath::slerpShortestPath()
LinearMath::DualQuaternionMath::DualQuaternionMath::sclerpShortestPath()
LinearMath::CubicHermite<T>TMath::lerp()
LinearMath::CubicHermiteComplexMath::ComplexMath::lerp()
LinearMath::CubicHermiteQuaternionMath::QuaternionMath::lerp()
SplineMath::CubicHermite<T>TMath::splerp()
SplineMath::CubicHermiteComplexMath::ComplexMath::splerp()
SplineMath::CubicHermiteQuaternionMath::QuaternionMath::splerp()

Debug& Magnum::Animation::operator<<(Debug& debug, Extrapolation value)

Debug output operator.

template<class K, class V, class R = ResultOf<V>>
R Magnum::Animation::interpolate(const Containers::StridedArrayView<const K>& keys, const Containers::StridedArrayView<const V>& values, Extrapolation before, Extrapolation after, R(*)(const V&, const V&, Float) interpolator, K frame, std::size_t& hint)

Interpolate animation value.

Template parameters
K Key type
V Value type
R Result type
Parameters
keys Keys
values Values
before Extrapolation mode before first keyframe
after Extrapolation mode after last keyframe
interpolator Interpolator function
frame Frame at which to interpolate
hint Hint for keyframe search

Does a linear search over the keyframes until it finds last keyframe which is not larger than frame. Once the keyframe is found, reference to it and the immediately following keyframe is passed to interpolator along with calculated interpolation factor, returning the interpolated value.

  • In case the first keyframe is already larger than frame or frame is larger or equal to the last keyframe, either the first two or last two keyframes are used and value is extrapolated according to before / after.
  • In case only one keyframe is present, its value is used for both sides of the interpolator.
  • In case no keyframes are present, default-constructed value is returned.

The hint parameter hints where to start the linear search and is updated with keyframe index matching frame. If frame is earlier than hint, the search is restarted from the beginning.

Used internally from Track::at() / TrackView::at(), see Track documentation for more information.

template<class K, class V, class R = ResultOf<V>>
R Magnum::Animation::interpolateStrict(const Containers::StridedArrayView<const K>& keys, const Containers::StridedArrayView<const V>& values, R(*)(const V&, const V&, Float) interpolator, K frame, std::size_t& hint)

Interpolate animation value with strict constraints.

Does a linear search over the keyframes until it finds last keyframe which is not larger than frame. Once the keyframe is found, reference to it and the immediately following keyframe is passed to interpolator along with calculated interpolation factor, returning the interpolated value. The hint parameter hints where to start the linear search and is updated with keyframe index matching frame. If frame is earlier than hint, the search is restarted from the beginning.

This is a stricter but more performant version of interpolate() with implicit Extrapolation::Extrapolated behavior. Expects that there are always at least two keyframes.

Used internally from Track::atStrict() / TrackView::atStrict(), see Track documentation for more information.

Debug& Magnum::Animation::operator<<(Debug& debug, State value)

Debug output operator.