#####################################
Blending Skeletal Animations Together
#####################################

The skeletal animation blender is the object that allows to build complex animation blend trees. Its goal is to mix several skeletal animation controllers together to produce smooth transitions between them or to merge partial skeletal animations.

Properties of the Skeletal Animation Blender
============================================

This object implements both interfaces: ``RED::ISkeletalAnimationController`` and ``RED::ISkeletalAnimationBlender``.

The blender contains a list of ``RED::ISkeletalAnimationController`` child objects. Because the blender also implements this interface, it can be added to the children list of other blenders allowing to build animation trees.

The ``RED::ISkeletalAnimationBlender`` interface provides functions to:

    * Manage the list of children: ``RED::ISkeletalAnimationBlender::AddController``, ``RED::ISkeletalAnimationBlender::RemoveController``;
    * Blend between them: ``RED::ISkeletalAnimationBlender::BlendTo``. This function make the transition between a currently played animation and another.

The ``RED::ISkeletalAnimationController`` objects hold all the parameters needed by the blender to apply its rules:

    * Blend weight (``RED::ISkeletalAnimationController::GetBlendWeight``) is the importance of the animation amongst all the others (sum must be 1 inside a blender);
    * Fade parameters (``RED::ISkeletalAnimationController::SetFadeParameters``) are the targeted blend weight and a duration to reach this weight;
    * Group (``RED::ISkeletalAnimationController::SetGroup``) allows to blend animations by group.

.. figure:: bk_skeletal_animation_blender01.png
    :align: center
    
    **An example of animation tree**

In the previous figure, we can imagine a character animation blend tree where the animations of the group 1 are body animations like idle and walk and animations of the group 2 are head animations. The group 1 controllers have filtered-out the head bones whereas the group 2 controllers have filtered-out the body bones.

Like every ``RED::ISkeletalAnimationController`` object, the blender needs to be updated at each frame by calling its ``RED::ISkeletalAnimationController::Update`` function. One important point: it handles the update of its children, so no need for the user to call the children update functions. **Only the animation tree root blender update needs to be done**.

The ``RED::ISkeletalAnimationController::SetIsAppliedToSkeleton`` method specifies if the result of the animation evaluation must be applied to the associated skinned mesh or not. Generally, in a blend tree, only the root blender result must be applied to the skeleton, all the children should set this option to false.

The skeletal animation blender is created by the factory with the ``RED::Factory::CreateSkeletalAnimationBlender`` function and deleted with ``RED::Factory::DeleteInstance``.

.. include:: /tasks/ta_ca/ta_ca_animation/tk_creating_skeletal_animation_blender.rst

.. include:: /tasks/ta_ca/ta_ca_animation/tk_doing_smooth_transitions_between_skeletal_animations.rst

.. include:: /tasks/ta_ca/ta_ca_animation/tk_merging_skeletal_animations.rst

Additive Animations
===================

The ``RED::ISkeletalAnimationController`` animations can be flagged to be additive (``RED::ISkeletalAnimationController::SetAdditive``). 

Additive animations are not blended like other animations, they are not cross-faded. Instead, as indicated by its name, they are added to the currently played animations. They are very useful to add small variations.

The blend weight of additive animation is used to control the amount of the additive animation we want to add: 0 being not added, 1 being totally added.
