Magnum::Trade::AnimationData class
#include <Magnum/Trade/AnimationData.h>

Animation clip data.

Provides access to animation data and track properties of given clip. Populated instances of this class are returned from AbstractImporter::animation() and can be passed to AbstractSceneConverter::add(const AnimationData&, Containers::StringView). Like with other Trade types, the internal representation is fixed upon construction and allows only optional in-place modification of the data itself, but not of the overall structure.

Typical usage is feeding all the tracks directly to Animation::Player. For every track, you need to query its concrete type and then feed the resulting Animation::TrackView of correct type to Animation::Player::add(), for example.

Note that this class owns the animation track data and the tracks are only views on it. In order to be able to destroy the AnimationData instance and keep using the animations later, you need to take ownership of the data using release().

In the following snippet all animated positions are stored in an array. The array is then updated during calls to Animation::Player::advance().

Containers::Optional<Trade::AnimationData> data = importer->animation(id);

Animation::Player<Float> player;
Containers::Array<Vector3> positions; /* Translations for all objects */
for(UnsignedInt i = 0; i != data->trackCount(); ++i) {
    if(data->trackTargetName(i) == Trade::AnimationTrackTarget::Translation3D) {
        CORRADE_INTERNAL_ASSERT(data->trackType(i) ==
            Trade::AnimationTrackType::Vector3);
        player.add(data->track<Vector3>(i), positions[data->trackTarget(i)]);
    }

    // similarly for rotation / scaling ...
}

Containers::Array<char> animationData = data->release(); /* Take ownership */

It's also possible to directly update object transformations using callbacks, among other things. See documentation of the Animation::Player class for more information.

Mutable data access

The interfaces implicitly provide const views on the contained keyframe data through the data() and track() accessors. This is done because in general case the data can also refer to a memory-mapped file or constant memory. In cases when it's desirable to modify the data in-place, there's the mutableData() and mutableTrack() set of functions. To use these, you need to check that the data are mutable using dataFlags() first. The following snippet inverts the Y coordinate of a translation animation:

for(UnsignedInt i = 0; i != data.trackCount(); ++i) {
    if(data.trackTargetName(i) != Trade::AnimationTrackTarget::Translation3D)
        continue;
    /* Check prerequisites */
    if(!(data.dataFlags() & Trade::DataFlag::Mutable) ||
       data.trackType(i) != Trade::AnimationTrackType::Vector2)
        Fatal{} << "Oops";

    MeshTools::transformVectorsInPlace(Matrix4::scaling(Vector3::yScale(-1.0f)),
        data.mutableTrack<Vector3>(i).values());
}

Constructors, destructors, conversion operators

AnimationData(Containers::Array<char>&& data, Containers::Array<AnimationTrackData>&& tracks, const void* importerState = nullptr) explicit noexcept
Construct an animation data.
AnimationData(Containers::Array<char>&& data, std::initializer_list<AnimationTrackData> tracks, const void* importerState = nullptr) explicit new in 2020.06
AnimationData(DataFlags dataFlags, Containers::ArrayView<const void> data, Containers::Array<AnimationTrackData>&& tracks, const void* importerState = nullptr) explicit noexcept new in 2020.06
Construct a non-owned animation data.
AnimationData(DataFlags dataFlags, Containers::ArrayView<const void> data, std::initializer_list<AnimationTrackData> tracks, const void* importerState = nullptr) explicit new in 2020.06
AnimationData(Containers::Array<char>&& data, Containers::Array<AnimationTrackData>&& tracks, const Range1D& duration, const void* importerState = nullptr) explicit noexcept
Construct an animation data with explicit duration.
AnimationData(Containers::Array<char>&& data, std::initializer_list<AnimationTrackData> tracks, const Range1D& duration, const void* importerState = nullptr) explicit new in 2020.06
AnimationData(DataFlags dataFlags, Containers::ArrayView<const void> data, Containers::Array<AnimationTrackData>&& tracks, const Range1D& duration, const void* importerState = nullptr) explicit noexcept new in 2020.06
Construct a non-owned animation data with explicit duration.
AnimationData(DataFlags dataFlags, Containers::ArrayView<const void> data, std::initializer_list<AnimationTrackData> tracks, const Range1D& duration, const void* importerState = nullptr) explicit new in 2020.06
AnimationData(const AnimationData&) deleted
Copying is not allowed.
AnimationData(AnimationData&&) noexcept
Move constructor.

Public functions

auto operator=(const AnimationData&) -> AnimationData& deleted
Copying is not allowed.
auto operator=(AnimationData&&) -> AnimationData& noexcept
Move assignment.
auto dataFlags() const -> DataFlags new in 2020.06
Data flags.
auto data() const & -> Containers::ArrayView<const char>
Raw data.
auto data() const && -> Containers::ArrayView<const char> deleted
Taking a view to a r-value instance is not allowed.
auto mutableData() & -> Containers::ArrayView<char> new in 2020.06
Mutable raw data.
auto mutableData() && -> Containers::ArrayView<char> deleted new in 2020.06
Taking a view to a r-value instance is not allowed.
auto duration() const -> Range1D
Duration.
auto trackCount() const -> UnsignedInt
Track count.
auto trackType(UnsignedInt id) const -> AnimationTrackType
Track value type.
auto trackResultType(UnsignedInt id) const -> AnimationTrackType
Track result type.
auto trackTargetName(UnsignedInt id) const -> AnimationTrackTarget
Track target name.
auto trackTargetType(UnsignedInt id) const -> AnimationTrackTarget deprecated in Git master
Track target name.
auto trackTarget(UnsignedInt id) const -> UnsignedLong
Track target ID.
auto track(UnsignedInt id) const -> Animation::TrackViewStorage<const Float>
Track data storage.
auto mutableTrack(UnsignedInt id) -> Animation::TrackViewStorage<Float> new in 2020.06
Mutable track data storage.
template<class V, class R = Animation::ResultOf<V>>
auto track(UnsignedInt id) const -> Animation::TrackView<const Float, const V, R>
Track data.
template<class V, class R = Animation::ResultOf<V>>
auto mutableTrack(UnsignedInt id) -> Animation::TrackView<Float, V, R> new in 2020.06
Mutable track data.
auto release() -> Containers::Array<char>
Release data storage.
auto importerState() const -> const void*
Importer-specific state.

Function documentation

Magnum::Trade::AnimationData::AnimationData(Containers::Array<char>&& data, Containers::Array<AnimationTrackData>&& tracks, const void* importerState = nullptr) explicit noexcept

Construct an animation data.

Parameters
data Buffer containing all keyframe data for this animation clip
tracks Track data
importerState Importer-specific state

Each item of track should have an Animation::TrackView instance pointing its key/value views to data. The duration() is automatically calculated from durations of all tracks.

The dataFlags() are implicitly set to a combination of DataFlag::Owned and DataFlag::Mutable. For non-owned data use the AnimationData(DataFlags, Containers::ArrayView<const void>, Containers::Array<AnimationTrackData>&&, const void*) constructor instead.

Magnum::Trade::AnimationData::AnimationData(Containers::Array<char>&& data, std::initializer_list<AnimationTrackData> tracks, const void* importerState = nullptr) explicit new in 2020.06

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Magnum::Trade::AnimationData::AnimationData(DataFlags dataFlags, Containers::ArrayView<const void> data, Containers::Array<AnimationTrackData>&& tracks, const void* importerState = nullptr) explicit noexcept new in 2020.06

Construct a non-owned animation data.

Parameters
dataFlags Data flags
data View on a buffer containing all keyframe data for this animation clip
tracks Track data
importerState Importer-specific state

Compared to AnimationData(Containers::Array<char>&&, Containers::Array<AnimationTrackData>&&, const void*) creates an instance that doesn't own the passed data. The dataFlags parameter can contain DataFlag::Mutable to indicate the external data can be modified, and is expected to not have DataFlag::Owned set.

Magnum::Trade::AnimationData::AnimationData(DataFlags dataFlags, Containers::ArrayView<const void> data, std::initializer_list<AnimationTrackData> tracks, const void* importerState = nullptr) explicit new in 2020.06

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Magnum::Trade::AnimationData::AnimationData(Containers::Array<char>&& data, Containers::Array<AnimationTrackData>&& tracks, const Range1D& duration, const void* importerState = nullptr) explicit noexcept

Construct an animation data with explicit duration.

Parameters
data Buffer containing all keyframe data for this animation clip
tracks Track data
duration Animation track duration
importerState Importer-specific state

Each item of track should have an Animation::TrackView instance pointing its key/value views to data.

The dataFlags() are implicitly set to a combination of DataFlag::Owned and DataFlag::Mutable. For non-owned data use the AnimationData(DataFlags, Containers::ArrayView<const void>, Containers::Array<AnimationTrackData>&&, const Range1D&, const void*) constructor instead.

Magnum::Trade::AnimationData::AnimationData(Containers::Array<char>&& data, std::initializer_list<AnimationTrackData> tracks, const Range1D& duration, const void* importerState = nullptr) explicit new in 2020.06

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Magnum::Trade::AnimationData::AnimationData(DataFlags dataFlags, Containers::ArrayView<const void> data, Containers::Array<AnimationTrackData>&& tracks, const Range1D& duration, const void* importerState = nullptr) explicit noexcept new in 2020.06

Construct a non-owned animation data with explicit duration.

Parameters
dataFlags Data flags
data View on a buffer containing all keyframe data for this animation clip
tracks Track data
duration Animation track duration
importerState Importer-specific state

Compared to AnimationData(Containers::Array<char>&&, Containers::Array<AnimationTrackData>&&, const Range1D&, const void*) creates an instance that doesn't own the passed data. The dataFlags parameter can contain DataFlag::Mutable to indicate the external data can be modified, and is expected to not have DataFlag::Owned set.

Magnum::Trade::AnimationData::AnimationData(DataFlags dataFlags, Containers::ArrayView<const void> data, std::initializer_list<AnimationTrackData> tracks, const Range1D& duration, const void* importerState = nullptr) explicit new in 2020.06

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

DataFlags Magnum::Trade::AnimationData::dataFlags() const new in 2020.06

Data flags.

Containers::ArrayView<const char> Magnum::Trade::AnimationData::data() const &

Raw data.

Contains data for all tracks contained in this clip.

Containers::ArrayView<char> Magnum::Trade::AnimationData::mutableData() & new in 2020.06

Mutable raw data.

Like data(), but returns a non-const view. Expects that the animation is mutable.

AnimationTrackType Magnum::Trade::AnimationData::trackType(UnsignedInt id) const

Track value type.

Parameters
id Track index

Data types are usually closely related to trackTargetName(), see AnimationTrackTarget documentation for more information.

AnimationTrackType Magnum::Trade::AnimationData::trackResultType(UnsignedInt id) const

Track result type.

Parameters
id Track index

In case track values are packed, track result type is different from trackType(). Data types are usually closely related to trackTargetName(), see AnimationTrackTarget documentation for more information.

AnimationTrackTarget Magnum::Trade::AnimationData::trackTargetName(UnsignedInt id) const

Track target name.

Parameters
id Track index

Particular animation targets usually correspond to a common trackType(), see AnimationTrackTarget documentation for more information.

AnimationTrackTarget Magnum::Trade::AnimationData::trackTargetType(UnsignedInt id) const

Track target name.

Animation::TrackViewStorage<const Float> Magnum::Trade::AnimationData::track(UnsignedInt id) const

Track data storage.

Returns the untyped base of a Animation::TrackView, which allows access only to some track properties. Use the templated and checked version below to access a concrete Animation::TrackView type.

Animation::TrackViewStorage<Float> Magnum::Trade::AnimationData::mutableTrack(UnsignedInt id) new in 2020.06

Mutable track data storage.

Like track(), but returns a mutable view. Expects that the animation is mutable.

template<class V, class R = Animation::ResultOf<V>>
Animation::TrackView<const Float, const V, R> Magnum::Trade::AnimationData::track(UnsignedInt id) const

Track data.

Template parameters
V Track value type
R Track result type

Expects that requested types are correct for given trackType() and trackResultType(). Note that the returned view is onto data(), meaning you either need to ensure that the AnimationData instance stays in scope for as long as you use the view or you need to release the data array using release() and manage its lifetime yourself.

template<class V, class R = Animation::ResultOf<V>>
Animation::TrackView<Float, V, R> Magnum::Trade::AnimationData::mutableTrack(UnsignedInt id) new in 2020.06

Mutable track data.

Like track(), but returns a mutable view. Expects that the animation is mutable.

Containers::Array<char> Magnum::Trade::AnimationData::release()

Release data storage.

Releases the ownership of the data array and resets internal state to default. The animation then behaves like it's empty. Note that the returned array has a custom no-op deleter when the data are not owned by the animation, and while the returned array type is mutable, the actual memory might be not.

const void* Magnum::Trade::AnimationData::importerState() const

Importer-specific state.

See AbstractImporter::importerState() for more information.

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

Animation interpolator function for given interpolation behavior.

To be used from importer plugins — wrapper around Animation::interpolatorFor(), guaranteeing that the returned function pointer is not instantiated inside the plugin binary to avoid dangling function pointers on plugin unload.