template<UnsignedInt dimensions, class T>
Magnum::SceneGraph::Animable class

Animable.

Contents

Adds animation feature to object. Each Animable is part of some AnimableGroup, which takes care of running the animations.

Usage

First thing is to add Animable feature to some object and implement animationStep(). You can do it conveniently using multiple inheritance (see Object features for introduction). Override animationStep() to implement your animation, the function provides both absolute animation time and time delta. Example:

typedef SceneGraph::Object<SceneGraph::MatrixTransformation3D> Object3D;
typedef SceneGraph::Scene<SceneGraph::MatrixTransformation3D> Scene3D;

class AnimableObject: public Object3D, SceneGraph::Animable3D {
    public:
        AnimableObject(Object3D* parent = nullptr, SceneGraph::AnimableGroup3D* group = nullptr): Object3D{parent}, SceneGraph::Animable3D{*this, group} {
            setDuration(10.0f);
            // ...
        }

    private:
        void animationStep(Float time, Float delta) override {
            rotateX(15.0_degf*delta); // rotate at 15 degrees per second
        }
}

Similarly to Drawable feature, there is no way to just animate all the objects in the scene. You need to create animable group and use it to control given set of animations. You can also use AnimableGroup::add() and AnimableGroup::remove() instead of passing the group in the constructor. The animation is initially in stopped state and without repeat, see setState(), setRepeated() and setRepeatCount() for more information.

Scene3D scene;
SceneGraph::AnimableGroup3D animables;

(new AnimableObject(&scene, &animables))
    ->setState(SceneGraph::AnimationState::Running);
// ...

Animation step is performed by calling AnimableGroup::step() in your draw event implementation. The function expects absolute time from relative to some fixed point in the past and time delta (i.e. duration of the frame). You can use Timeline for that, see its documentation for more information.

Timeline timeline;
timeline.start();

void MyApplication::drawEvent() {
    animables.step(timeline.lastFrameTime(), timeline.lastFrameDuration());

    // ...

    timeline.nextFrame();
}

Using multiple animable groups to improve performance

AnimableGroup is optimized for case when no animation is running — it just puts itself to rest and waits until some animation changes its state to AnimationState::Running again. If you put animations which are not pernamently running into separate group, they will not be traversed every time the AnimableGroup::step() gets called, saving precious frame time.

Explicit template specializations

The following specializations are explicitly compiled into SceneGraph library. For other specializations (e.g. using Double type) you have to use Animable.hpp implementation file to avoid linker errors. See also Template headers and implementation files for more information.

Base classes

template<UnsignedInt dimensions, class Derived, class T>
class AbstractGroupedFeature
Base for grouped features.

Constructors, destructors, conversion operators

Animable(AbstractObject<dimensions, T>& object, AnimableGroup<dimensions, T>* group = nullptr) explicit
Constructor.

Public functions

auto duration() const -> Float
Animation duration.
auto state() const -> AnimationState
Animation state.
auto setState(AnimationState state) -> Animable<dimensions, T>&
Set animation state.
auto isRepeated() const -> bool
Whether the animation is repeated.
auto setRepeated(bool repeated) -> Animable<dimensions, T>&
Enable/disable repeated animation.
auto repeatCount() const -> UnsignedShort
Repeat count.
auto setRepeatCount(UnsignedShort count) -> Animable<dimensions, T>&
Set repeat count.
auto animables() -> AnimableGroup<dimensions, T>*
Group containing this animable.
auto animables() const -> const AnimableGroup<dimensions, T>*

Protected functions

auto setDuration(Float duration) -> Animable<dimensions, T>&
Set animation duration.
void animationStep(Float time, Float delta) pure virtual
Perform animation step.
void animationStarted() virtual
Action on animation start.
void animationPaused() virtual
Action on animation pause.
void animationResumed() virtual
Action on animation resume.
void animationStopped() virtual
Action on animation stop.

Function documentation

template<UnsignedInt dimensions, class T>
Magnum::SceneGraph::Animable<dimensions, T>::Animable(AbstractObject<dimensions, T>& object, AnimableGroup<dimensions, T>* group = nullptr) explicit

Constructor.

Parameters
object Object this animable belongs to
group Group this animable belongs to

Creates stopped non-repeating animation with infinite duration, adds the feature to the object and also to group, if specified.

template<UnsignedInt dimensions, class T>
Animable<dimensions, T>& Magnum::SceneGraph::Animable<dimensions, T>::setState(AnimationState state)

Set animation state.

Returns Reference to self (for method chaining)

Note that changing state from AnimationState::Stopped to AnimationState::Paused is ignored and animation remains in AnimationState::Stopped state. See also animationStep() for more information.

template<UnsignedInt dimensions, class T>
bool Magnum::SceneGraph::Animable<dimensions, T>::isRepeated() const

Whether the animation is repeated.

template<UnsignedInt dimensions, class T>
Animable<dimensions, T>& Magnum::SceneGraph::Animable<dimensions, T>::setRepeated(bool repeated)

Enable/disable repeated animation.

Returns Reference to self (for method chaining)

Default is false.

template<UnsignedInt dimensions, class T>
UnsignedShort Magnum::SceneGraph::Animable<dimensions, T>::repeatCount() const

Repeat count.

template<UnsignedInt dimensions, class T>
Animable<dimensions, T>& Magnum::SceneGraph::Animable<dimensions, T>::setRepeatCount(UnsignedShort count)

Set repeat count.

Returns Reference to self (for method chaining)

Has effect only if repeated animation is enabled. 0 means infinitely repeated animation. Default is 0.

template<UnsignedInt dimensions, class T>
AnimableGroup<dimensions, T>* Magnum::SceneGraph::Animable<dimensions, T>::animables()

Group containing this animable.

If the animable doesn't belong to any group, returns nullptr.

template<UnsignedInt dimensions, class T>
const AnimableGroup<dimensions, T>* Magnum::SceneGraph::Animable<dimensions, T>::animables() const

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

template<UnsignedInt dimensions, class T>
Animable<dimensions, T>& Magnum::SceneGraph::Animable<dimensions, T>::setDuration(Float duration) protected

Set animation duration.

Returns Reference to self (for method chaining)

Sets duration of the animation cycle in seconds. Set to 0.0f for infinite non-repeating animation. Default is 0.0f.

template<UnsignedInt dimensions, class T>
void Magnum::SceneGraph::Animable<dimensions, T>::animationStep(Float time, Float delta) pure virtual protected

Perform animation step.

Parameters
time Time from start of the animation
delta Time delta for current frame

This function is periodically called from AnimableGroup::step() if the animation state is set to AnimationState::Running. After animation duration is exceeded and repeat is not enabled or repeat count is exceeded, the animation state is set to AnimationState::Stopped.

If the animation is resumed from AnimationState::Paused, this function is called with time continuing from the point when it was paused. If the animation is resumed from AnimationState::Stopped, time starts with zero.

template<UnsignedInt dimensions, class T>
void Magnum::SceneGraph::Animable<dimensions, T>::animationStarted() virtual protected

Action on animation start.

Called from AnimableGroup::step() when state is changed from AnimationState::Stopped to AnimationState::Running and before first animationStep() is called.

Default implementation does nothing.

template<UnsignedInt dimensions, class T>
void Magnum::SceneGraph::Animable<dimensions, T>::animationPaused() virtual protected

Action on animation pause.

Called from AnimableGroup::step() when state changes from AnimationState::Running to AnimationState::Paused and after last animationStep() is called.

Default implementation does nothing.

template<UnsignedInt dimensions, class T>
void Magnum::SceneGraph::Animable<dimensions, T>::animationResumed() virtual protected

Action on animation resume.

Called from AnimableGroup::step() when state changes from AnimationState::Paused to AnimationState::Running and before first animationStep() is called.

Default implementation does nothing.

template<UnsignedInt dimensions, class T>
void Magnum::SceneGraph::Animable<dimensions, T>::animationStopped() virtual protected

Action on animation stop.

Called from AnimableGroup::step() when state changes from either AnimationState::Running or AnimationState::Paused to AnimationState::Stopped and after last animationStep() is called.

You may want to use this function to properly finish the animation in case the framerate is not high enough to have animationStep() called enough times. Default implementation does nothing.