# Tutorial for Animation Manipulation

# Configuring and Loading an Animation

#### <a class="anchor" id="bkmrk--1"></a>Candera Animation Concept

The following key concepts are required to run animations in a [Candera](http://dev.doc.cgistudio.at/APILINK/namespace_candera.html "[DataBinding_RefTypeSample]") application:

<div class="contents" id="bkmrk-candera%3A%3Aanimation%3A%3A"><div class="contents"><div class="textblock">- [Candera::Animation::AnimationPlayer](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_animation_1_1_animation_player.html "AnimationPlayer is an AnimationPlayerBase that animates AnimationBlendedProperties.") provides the control interfaces (use [Candera::Animation::AnimationGroupPlayer](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_animation_1_1_animation_group_player.html "AnimationGroupPlayer is an AnimationPlayerBase that controls a hierarchy of AnimationPlayerBase compo...") for animation groups)
- [Candera::Animation::AnimationTimeDispatcher](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_animation_1_1_animation_time_dispatcher.html "Dispatches world time (as received from an application) to a collection of AnmationPlayers.") dispatches the current world time to animations; animations can also query the current world time from the dispatcher
- [Candera::Animation::AnimationKeyframeSequence](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_animation_1_1_animation_keyframe_sequence.html "A KeyframeSequence that provides interpolation between keyframes.") configures proper animation values for each time point of an animation.
- [Candera::Animation::InterpolationStrategy](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_animation_1_1_interpolation_strategy.html "InterpolationStrategy provides an interface for calculating the interpolated value of a KeyframeSeque...") specifies for a key frame sequence, how values between several key frames shall be calculated.
- [Candera::Animation::AnimationPropertySetter](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_animation_1_1_animation_property_setter.html "Base class for all animation property setters.") applies animation values to animated properties

</div></div></div>In SceneComposer, animations can be configured in the AnimationDesign view:

<div class="contents" id="bkmrk-create-a-new-animati"><div class="contents"><div class="textblock">- Create a new animation - <span style="color: rgb(230, 126, 35);">[New Animation](https://doc316en.candera.eu/books/animation-design/page/new-animation)</span> in SceneComposer User Manual
- Select a node property to animate - <span style="color: rgb(230, 126, 35);">[Add Animated Property](https://doc316en.candera.eu/books/animation-design/page/add-animated-property)</span> in SceneComposer User Manual
- Specify the key frame sequence including property values and interpolation strategy - <span style="color: rgb(230, 126, 35);">[Animation Values](https://doc316en.candera.eu/books/animation-design/page/animation-values-keyframes)</span> in SceneComposer User Manual

</div></div></div>It is also possible to import an animation to SceneComposer from a content generation tool via FBX format - <span style="color: rgb(230, 126, 35);">[How to Import Resources](https://doc316en.candera.eu/books/import-of-resources/page/how-to-import-resources)</span> in SceneComposer User Manual

#### <a class="anchor" id="bkmrk--2"></a>

#### <a class="anchor" id="bkmrk--3"></a>Configuring Animation Player

In the Player or in an application, the animation can be retrieved from the generated asset by specifying its [Candera](http://dev.doc.cgistudio.at/APILINK/namespace_candera.html "[DataBinding_RefTypeSample]") name (e.g. *MyModule#Animations#Animation*).

```
    AssetProvider* assetProvider = GetAssetProvider();
    m_animPlayer = assetProvider->GetAnimation(m_animName);
```

<div class="contents" id="bkmrk-in-scenecomposer-the"><div class="contents"><div class="contents"><div class="textblock"><div class="fragment">  
</div><dl class="note"><dt></dt><dd><p class="callout info">In SceneComposer the animation can be retrieved from AssetProvider only if it was previously loaded in the scene. A better way to access it directly is to define it as a widget property.</p>

</dd></dl><div class="fragment">  
</div></div></div></div></div>```
                // Define Animation property
                CdaProperty(Animation,Candera::Animation::AnimationPlayer::SharedPointer, GetAnimation, SetAnimation)
                    CdaDescription("Animation")
                <a class="code" href="http://dev.doc.cgistudio.at/APILINK/group___meta_info.html#ga119bef57449bd05d8b3c40d7d514e375">CdaPropertyEnd</a>()
                // End Define Animation property
```

Next, as already explained in <span style="color: rgb(230, 126, 35);">[Initializing AssetLoader and Animations](https://doc316en.candera.eu/link/418#bkmrk-initializing-assetlo-0)</span>, an instance of [Candera::Animation::AnimationTimeDispatcher](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_animation_1_1_animation_time_dispatcher.html "Dispatches world time (as received from an application) to a collection of AnmationPlayers.") is needed to provide current world time to animations.

For this, the new animation player must be added to the [Candera::Animation::AnimationTimeDispatcher](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_animation_1_1_animation_time_dispatcher.html "Dispatches world time (as received from an application) to a collection of AnmationPlayers.") instance maintained by the application.

```
        // Add player to time dispatcher

        Animation::AnimationTimeDispatcher::SharedPointer timeDispatcher = GetAnimationTimeDispatcher();
        if (timeDispatcher == 0) {
            return;
        }
        static_cast<void>(timeDispatcher->AddPlayer(m_animPlayer));

        // End Add player to time dispatcher
```

Now the animation player is ready to be used.

# Controlling Animations

#### <a class="anchor" id="bkmrk-"></a>Controlling Animation Flow

This section describes the control flow interfaces of [Candera::Animation::AnimationPlayer](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_animation_1_1_animation_player.html "AnimationPlayer is an AnimationPlayerBase that animates AnimationBlendedProperties.").

<div class="contents" id="bkmrk-candera%3A%3Aanimation%3A%3A"><div class="contents"><div class="textblock">- [Candera::Animation::AnimationPlayer::Start](http://dev.doc.cgistudio.at/APILINK/group___animation_base.html#gaf6c1aa4792f932b8816153d67ed1d9cc) starts the animation
- [Candera::Animation::AnimationPlayer::Stop](http://dev.doc.cgistudio.at/APILINK/group___animation_base.html#ga259f65e1d7740d9adbfb09a7812c5423) stops the animation
- [Candera::Animation::AnimationPlayer::Finish](http://dev.doc.cgistudio.at/APILINK/group___animation_base.html#ga1d6f1d3611d64e2d39193d6a0e08e133) finishes the animation within the specified time
- [Candera::Animation::AnimationPlayer::Pause](http://dev.doc.cgistudio.at/APILINK/group___animation_base.html#ga12a9f0d140cc0c2c5e3153d17aa0cf28) pauses the animation
- [Candera::Animation::AnimationPlayer::Resume](http://dev.doc.cgistudio.at/APILINK/group___animation_base.html#gaa458d6b67c60cc33fa87b5f4112653f7) resumes the animation
- [Candera::Animation::AnimationPlayer::SetRepeatMode](http://dev.doc.cgistudio.at/APILINK/group___animation_base.html#gadd1ac5b4292294ae2df6089aca10fbc5) sets the repeat mode, for possible modes see [Candera::Animation::AnimationPlayer::RepeatMode](http://dev.doc.cgistudio.at/APILINK/group___animation_base.html#ga074a17359b4b4a429aac5f4f9478c535)
- [Candera::Animation::AnimationPlayer::SetDirection](http://dev.doc.cgistudio.at/APILINK/group___animation_base.html#gaffbd9a4e36d4d55ddd30f7177ff94b10) sets the direction, for possible directions see [Candera::Animation::AnimationPlayer::PlayDirection](http://dev.doc.cgistudio.at/APILINK/group___animation_base.html#ga29bc1135b9602fedae7f45669c928211)

</div></div></div>#### <a class="anchor" id="bkmrk--0"></a>Animation Speed, Repeats, Time Modulation

This section specifies more interfaces to set animation player properties relevant for timing and execution flow.

<div class="contents" id="bkmrk-candera%3A%3Aanimation%3A%3A-0"><div class="textblock">- [Candera::Animation::AnimationPlayer::SetSpeedFactor](http://dev.doc.cgistudio.at/APILINK/group___animation_base.html#gac9cb929cc2c199830abb28fe48074012) increases / decreases animation speed
- [Candera::Animation::AnimationPlayer::SetRepeatCount](http://dev.doc.cgistudio.at/APILINK/group___animation_base.html#ga5caca783e5ade40bfefb67b74fbdb6da) modifies repeat count
- [Candera::Animation::AnimationPlayer::SetSequenceDurationMs](http://dev.doc.cgistudio.at/APILINK/group___animation_base.html#ga0f0e0e34252b34219601bb3c8aca64cb) modifies animation duration in milliseconds
- [Candera::Animation::AnimationPlayer::SetSequenceStartTimeMs](http://dev.doc.cgistudio.at/APILINK/group___animation_base.html#ga71179ea9ba32db4895bd4d87667a465a) adds a start delay in milliseconds

</div></div>

# Using Animation Callback Functions

#### <a class="anchor" id="bkmrk-"></a>Animation Event Listener

If an application shall be notified about events of the triggered animation, a listener needs to be implemented. The class [Candera::Animation::AnimationPlayerListener](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_animation_1_1_animation_player_listener.html "An AnimationPlayerListener defines several hooks for the AnimationPlayer. In order to register an Ani...") allows to listen to a versatile set of animation events like:

<div class="contents" id="bkmrk-onstartantimation%2C-o"><div class="contents"><div class="textblock">- OnStartAntimation,
- OnResumeAnimation,
- OnPauseAnimation,
- OnDirectionChange,
- OnStopAnimation,
- OnFinishAnimation,
- OnPastEnd.

</div></div></div>#### <a class="anchor" id="bkmrk--0"></a>Implement AnimationPlayerListener Functions

In order to register an AnimationPlayerListener to an AnimationPlayer simply derive from [Candera::Animation::AnimationPlayerListener](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_animation_1_1_animation_player_listener.html "An AnimationPlayerListener defines several hooks for the AnimationPlayer. In order to register an Ani...") and override pure virtual functions with custom code.

In the example below the 3D application derives from AnimationPlayerListener and overrides the listener's functions.

```
class AnimationPlayerWidget : public CgiWidget3D, public Candera::Animation::AnimationPlayerListener

```

```
        virtual void OnPastEnd(<a class="code" href="http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_animation_1_1_animation_player_base.html" title="AnimationPlayerBase is a base class for all AnimationPlayers that use an AnimationTimeDispatcher to c...">Candera::Animation::AnimationPlayerBase</a>* animationPlayer, Candera::Int32 completedIterationsCount);
        virtual void OnStartAnimation(<a class="code" href="http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_animation_1_1_animation_player_base.html" title="AnimationPlayerBase is a base class for all AnimationPlayers that use an AnimationTimeDispatcher to c...">Candera::Animation::AnimationPlayerBase</a>* animationPlayer);
        virtual void OnStopAnimation(<a class="code" href="http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_animation_1_1_animation_player_base.html" title="AnimationPlayerBase is a base class for all AnimationPlayers that use an AnimationTimeDispatcher to c...">Candera::Animation::AnimationPlayerBase</a>* animationPlayer);
        virtual void OnFinishAnimation(<a class="code" href="http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_animation_1_1_animation_player_base.html" title="AnimationPlayerBase is a base class for all AnimationPlayers that use an AnimationTimeDispatcher to c...">Candera::Animation::AnimationPlayerBase</a>* animationPlayer);
        virtual void OnResumeAnimation(<a class="code" href="http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_animation_1_1_animation_player_base.html" title="AnimationPlayerBase is a base class for all AnimationPlayers that use an AnimationTimeDispatcher to c...">Candera::Animation::AnimationPlayerBase</a>* animationPlayer);
        virtual void OnPauseAnimation(<a class="code" href="http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_animation_1_1_animation_player_base.html" title="AnimationPlayerBase is a base class for all AnimationPlayers that use an AnimationTimeDispatcher to c...">Candera::Animation::AnimationPlayerBase</a>* animationPlayer);

```

Use [Candera::Animation::AnimationPlayerBase::AddAnimationPlayerListener](http://dev.doc.cgistudio.at/APILINK/group___animation_base.html#ga6ff976e80e9312aa89fe5a9d6a16f033) and [Candera::Animation::AnimationPlayerBase::RemoveAnimationPlayerListener](http://dev.doc.cgistudio.at/APILINK/group___animation_base.html#gacfcf00e1b85c190893a61dbda34761ec) for registering or removing a listener.

```
        static_cast<void>(m_animPlayer->AddAnimationPlayerListener(this));

```

```
        static_cast<void>(m_animPlayer->RemoveAnimationPlayerListener(this));

```

Now the application is notified about all animation listener events it has implemented. For example when implementing the [Candera::Animation::AnimationPlayerListener::OnStartAnimation](http://dev.doc.cgistudio.at/APILINK/group___animation_base.html#ga229c09eb5a45b0ab000d4153543b3d5a), the application is notified about all started animations.

```
void AnimationPlayerWidget::OnStartAnimation(Animation::AnimationPlayerBase* /* animationPlayer */)
{
    // do something when an animation has started
}
```

# Manipulating Animation Keyframe Sequences

This method allows to modify specific keyframes of a previously initialized keyframe sequence.

#### <a class="anchor" id="bkmrk-"></a>Define Keyframe Values

Size of array must be equal with the number of values that are already assigned to each keyframe (numberOfComponents).

```
    Float keyFrameManipulationValues[3] =
    {
        1.0, 1.0, 11.0
    };
```

#### <a class="anchor" id="bkmrk--0"></a>Set Keyframe Values

Values will be attached to one keyframe.

```
    m_keyframeSequence->SetKeyframeValues(1, keyFrameManipulationValues[0]);
```

<div class="contents" id="bkmrk-see-also%3A-candera%3A%3Aa"><div class="textblock"><div class="fragment">  
</div><dl class="see"><dt>**See also:**</dt><dd>[Candera::Animation::AnimationKeyframeSequence::SetKeyframeValues](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_animation_1_1_keyframe_sequence.html#a3ec0e1bb8dd3aca71a782e0d5b54a6cc)</dd></dl></div></div>