Documentation

Attribute animation

Attribute animation is a mechanism to animate the values of an object's attribute. Objects derived from Animatable can use attribute animation, this includes the Node class and all Component and UIElement subclasses.

These are two ways to use attribute animation. Either the user can create attribute animation with code, and then apply it to object's attribute. Here is a simple code for light color animation:

SharedPtr<ValueAnimation> colorAnimation(new ValueAnimation(context_));
colorAnimation->SetKeyFrame(0.0f, Color::WHITE);
colorAnimation->SetKeyFrame(2.0f, Color::YELLOW);
colorAnimation->SetKeyFrame(4.0f, Color::WHITE);
light->SetAttributeAnimation("Color", colorAnimation, WM_LOOP);

In the above code, we first create an ValueAnimation object call colorAnimation, and set three key frame values to it, then assign it to light's color attribute. (Note here: in order to make animation look correct, the last key frame must equal to the first key frame for loop mode).

Another way is to load an attribute animation resource, here is a simple example:

ValueAnimation* colorAnimation = cache->GetResource<ValueAnimation>("Scene/LightColorAnimation.xml");
light->SetAttributeAnimation("Color", colorAnimation, WM_LOOP);

Attribute animation supports three different wrap modes:

  • WM_LOOP: Loop mode, when the animation arrives to end, it will loop from beginning.
  • WM_ONCE: Play once mode, when the animation is finished, it will be removed from the object.
  • WM_CLAMP: Clamp mode, when the animation is finished, it will keep the last key frame's value.

The playback speed (default 1 or "original speed") of an animation, as well as the animation's wrap mode can be adjusted on the fly.

The ObjectAnimation class can be used to group together multiple value animations that affect different attributes. For example when the user wants to apply position and color animation for a light, the following code can be used. Note that the object animation is attached to the light's scene node, so a special syntax is needed to refer to the light component's attribute.

// Create light animation
SharedPtr<ObjectAnimation> lightAnimation(new ObjectAnimation(context_));
// Create light position animation
SharedPtr<ValueAnimation> positionAnimation(new ValueAnimation(context_));
// Use spline interpolation method
positionAnimation->SetInterpolationMethod(IM_SPLINE);
// Set spline tension
positionAnimation->SetSplineTension(0.7f);
positionAnimation->SetKeyFrame(0.0f, Vector3(-30.0f, 5.0f, -30.0f));
positionAnimation->SetKeyFrame(1.0f, Vector3( 30.0f, 5.0f, -30.0f));
positionAnimation->SetKeyFrame(2.0f, Vector3( 30.0f, 5.0f, 30.0f));
positionAnimation->SetKeyFrame(3.0f, Vector3(-30.0f, 5.0f, 30.0f));
positionAnimation->SetKeyFrame(4.0f, Vector3(-30.0f, 5.0f, -30.0f));
// Set position animation
lightAnimation->AddAttributeAnimation("Position", positionAnimation);
// Create light color animation
SharedPtr<ValueAnimation> colorAnimation(new ValueAnimation(context_));
colorAnimation->SetKeyFrame(0.0f, Color::WHITE);
colorAnimation->SetKeyFrame(1.0f, Color::RED);
colorAnimation->SetKeyFrame(2.0f, Color::YELLOW);
colorAnimation->SetKeyFrame(3.0f, Color::GREEN);
colorAnimation->SetKeyFrame(4.0f, Color::WHITE);
// Set Light component's color animation
lightAnimation->AddAttributeAnimation("@Light/Color", colorAnimation);
// Apply light animation to light node
lightNode->SetObjectAnimation(lightAnimation);

Object animations can also be loaded from file, like:

ObjectAnimation * lightAnimation = cache->GetResource<ObjectAnimation>("Scene/LightAnimation.xml");
lightNode->SetObjectAnimation (lightAnimation);

Attribute animation uses either linear or spline interpolation for floating point types (like float, Vector2, Vector3 etc), and no interpolation for integer and non-numeric types (like int, bool).

Attribute animation classes

  • Animatable: Base class for animatable objects, which can assign animations on its individual attributes (ValueAnimation), or an animation which affects several attributes (ObjectAnimation).
  • ValueAnimation: Includes key frame values for a single attribute
  • ObjectAnimation: Includes one or more attribute animations and their wrap modes and speeds for an Animatable object.
  • ValueAnimationInfo: Base class for runtime instances of an attribute animation, which includes the referred animation, wrap mode, speed and time position.