Magnum::Animation namespace

Keyframe-based animation.

This library is built as part of Magnum by default. To use this library with CMake, find the Magnum package and link to the Magnum::Magnum target:

find_package(Magnum REQUIRED)

# ...
target_link_libraries(your-app PRIVATE Magnum::Magnum)

See Downloading and building, Usage with CMake and Keyframe-based animation for more information.

Classes

template<class T>
struct BasicEasing new in Git master
Easing functions.
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

using Easing = BasicEasing<Float>
Float easing functions.
using Easingd = BasicEasing<Double> new in Git master
Double easing functions.
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::StridedArrayView1D<const K>& keys, const Containers::StridedArrayView1D<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::StridedArrayView1D<const K>& keys, const Containers::StridedArrayView1D<const V>& values, R(*)(const V&, const V&, Float) interpolator, K frame, std::size_t& hint) -> R
Interpolate animation value with strict constraints.
template<class V, ResultOf<V>(*)(const V&, const V&, Float) interpolator, Float(*)(Float) easer>
auto ease() -> auto constexpr
Combine easing function and an interpolator.
template<class V, ResultOf<V>(*)(const V&, const V&, Float) interpolator, Float(*)(Float) easer>
auto easeClamped() -> auto constexpr
Combine easing function and an interpolator.
template<class T, class V, ResultOf<V>(*)(const V&, const V&, Float) interpolator, V(*)(const T&) unpacker>
auto unpack() -> auto constexpr
Combine unpacking function and an interpolator.
template<class T, class V, ResultOf<V>(*)(const V&, const V&, Float) interpolator, V(*)(const T&) unpacker, Float(*)(Float) easer>
auto unpackEase() -> auto constexpr
Combine unpacking and easing functions with an interpolator.
template<class T, class V, ResultOf<V>(*)(const V&, const V&, Float) interpolator, V(*)(const T&) unpacker, Float(*)(Float) easer>
auto unpackEaseClamped() -> auto constexpr
Combine easing function and an interpolator.
auto operator<<(Debug& debug, State value) -> Debug&
Debug output operator.

Enum documentation

enum class Magnum::Animation::Interpolation: UnsignedByte
#include <Magnum/Animation/Interpolation.h>

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
#include <Magnum/Animation/Interpolation.h>

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
#include <Magnum/Animation/Player.h>

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

typedef BasicEasing<Float> Magnum::Animation::Easing
#include <Magnum/Animation/Easing.h>

Float easing functions.

typedef BasicEasing<Double> Magnum::Animation::Easingd new in Git master
#include <Magnum/Animation/Easing.h>

Double easing functions.

#include <Magnum/Animation/Interpolation.h>
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)
#include <Magnum/Animation/Interpolation.h>

Debug output operator.

#include <Magnum/Animation/Interpolation.h>
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::BitVectorMath::BitVectorMath::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)
#include <Magnum/Animation/Interpolation.h>

Debug output operator.

#include <Magnum/Animation/Interpolation.h>
template<class K, class V, class R = ResultOf<V>>
R Magnum::Animation::interpolate(const Containers::StridedArrayView1D<const K>& keys, const Containers::StridedArrayView1D<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.

#include <Magnum/Animation/Interpolation.h>
template<class K, class V, class R = ResultOf<V>>
R Magnum::Animation::interpolateStrict(const Containers::StridedArrayView1D<const K>& keys, const Containers::StridedArrayView1D<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.

#include <Magnum/Animation/Interpolation.h>
template<class V, ResultOf<V>(*)(const V&, const V&, Float) interpolator, Float(*)(Float) easer>
auto Magnum::Animation::ease() constexpr

Combine easing function and an interpolator.

Useful to create a new function out of one of the interpolators from Transformation interpolation and an easing function from Easing. For example, the following two expressions give the same result:

auto lerpBounceIn =
    Animation::ease<Vector3, Math::lerp, Animation::Easing::bounceIn>();

Vector3 result1 = Math::lerp(a, b, Animation::Easing::bounceIn(t));
Vector3 result2 = lerpBounceIn (a, b, t);

#include <Magnum/Animation/Interpolation.h>
template<class V, ResultOf<V>(*)(const V&, const V&, Float) interpolator, Float(*)(Float) easer>
auto Magnum::Animation::easeClamped() constexpr

Combine easing function and an interpolator.

In addition to ease() clamps value coming to easer to range $ [0 ; 1] $ . Useful when extrapolating using Easing functions that have bad behavior outside of this range.

#include <Magnum/Animation/Interpolation.h>
template<class T, class V, ResultOf<V>(*)(const V&, const V&, Float) interpolator, V(*)(const T&) unpacker>
auto Magnum::Animation::unpack() constexpr

Combine unpacking function and an interpolator.

Similar to ease(), but for adding an unpacker function to interpolator inputs instead of modifying the interpolator phase. The following two expressions give the same result:

UnsignedShort a = …, b = …;
auto lerpPacked =
    Animation::unpack<UnsignedShort, Float, Math::lerp, Math::unpack<Float>>();

Float result1 = Math::lerp(Math::unpack<Float>(a), Math::unpack<Float>(b), t);
Float result2 = lerpPacked(a, b, t);

#include <Magnum/Animation/Interpolation.h>
template<class T, class V, ResultOf<V>(*)(const V&, const V&, Float) interpolator, V(*)(const T&) unpacker, Float(*)(Float) easer>
auto Magnum::Animation::unpackEase() constexpr

Combine unpacking and easing functions with an interpolator.

Combination of ease() and unpack(), creating a function that first unpack the interpolator inputs, then modifies the interpolator phase and finally passes that to the interpolator function. The following two expressions give the same result:

UnsignedShort a = …, b = …;
auto lerpPackedBounceIn = Animation::unpackEase<UnsignedShort, Float,
    Math::lerp, Math::unpack<Float>, Animation::Easing::bounceIn>();

Float result1 = Math::lerp(Math::unpack<Float>(a), Math::unpack<Float>(b),
    Animation::Easing::bounceIn(t));
Float result2 = lerpPackedBounceIn(a, b, t);

#include <Magnum/Animation/Interpolation.h>
template<class T, class V, ResultOf<V>(*)(const V&, const V&, Float) interpolator, V(*)(const T&) unpacker, Float(*)(Float) easer>
auto Magnum::Animation::unpackEaseClamped() constexpr

Combine easing function and an interpolator.

In addition to unpackEase() clamps value coming to easer to range $ [0 ; 1] $ . Useful when extrapolating with Easing functions that have bad behavior outside of this range.

Debug& Magnum::Animation::operator<<(Debug& debug, State value)
#include <Magnum/Animation/Player.h>

Debug output operator.