Click or drag to resize
DigitalRuneAnimationInstance Class
Represents an instance of an animation timeline.
Inheritance Hierarchy

Namespace: DigitalRune.Animation
Assembly: DigitalRune.Animation (in DigitalRune.Animation.dll) Version: 1.4.0.0 (1.4.1.14427)
Syntax
public class AnimationInstance : IAnimatableObject, 
	INamedObject, IRecyclable

The AnimationInstance type exposes the following members.

Constructors
  NameDescription
Protected methodAnimationInstance
Initializes a new instance of the AnimationInstance class.
Top
Methods
  NameDescription
Public methodStatic memberCreate
Creates an instance of the AnimationInstance class. (This method reuses a previously recycled instance or allocates a new instance if necessary.)
Public methodEquals
Determines whether the specified Object is equal to the current Object.
(Inherited from Object.)
Protected methodFinalize
Allows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection.
(Inherited from Object.)
Public methodGetHashCode
Serves as a hash function for a particular type.
(Inherited from Object.)
Public methodGetType
Gets the Type of the current instance.
(Inherited from Object.)
Public methodInvalidate
Invalidates the current state of the animation.
Protected methodMemberwiseClone
Creates a shallow copy of the current Object.
(Inherited from Object.)
Protected methodOnCompleted
Raises the Completed event.
Public methodRecycle
Recycles this animation instance (including all children).
Public methodToString
Returns a string that represents the current object.
(Inherited from Object.)
Top
Extension Methods
  NameDescription
Public Extension MethodGetAncestors
Gets the ancestors of the AnimationInstance in the animation tree.
(Defined by AnimationHelper.)
Public Extension MethodGetDescendantsOverloaded.
Gets the descendants of the AnimationInstance in the animation tree using a depth-first search.
(Defined by AnimationHelper.)
Public Extension MethodGetDescendants(Boolean)Overloaded.
Gets the descendants of the AnimationInstance in the animation tree using either a depth-first or a breadth-first search.
(Defined by AnimationHelper.)
Public Extension MethodGetLeaves
Gets the leaves of the AnimationInstance in the animation tree.
(Defined by AnimationHelper.)
Public Extension MethodGetRoot
Returns the root instance of an animation tree.
(Defined by AnimationHelper.)
Public Extension MethodGetSelfAndAncestors
Gets the AnimationInstance and its ancestors in the animation tree.
(Defined by AnimationHelper.)
Public Extension MethodGetSubtreeOverloaded.
Gets the subtree (the given AnimationInstance and all of its descendants in the animation tree) using a depth-first search.
(Defined by AnimationHelper.)
Public Extension MethodGetSubtree(Boolean)Overloaded.
Gets the subtree (the given AnimationInstance and all of its descendants in the animation tree) using either a depth-first or a breadth-first search.
(Defined by AnimationHelper.)
Top
Properties
  NameDescription
Public propertyAnimation
Gets the animation timeline that is being played back.
Public propertyAutoRecycleEnabled
Gets or sets a value indicating whether this animation instance should be automatically recycled when it is stopped and removed from the animation system.
Public propertyChildren
Gets the children of this animation instance.
Public propertyIsPaused
Gets a value indicating whether this animation instance is paused.
Public propertyParent
Gets the parent of this animation instance.
Public propertySpeed
Gets or sets the rate at which time progresses.
Public propertyState
Gets the current state of the animation.
Public propertyTime
Gets or sets the current animation time.
Public propertyWeight
Gets or sets the animation weight.
Top
Events
  NameDescription
Public eventCompleted
Occurs when the animation has completed playing. Use with caution - see remarks.
Top
Explicit Interface Implementations
Remarks

Animation instances are used to play back animations. They maintain the runtime-state of an animation.

Animation instances are automatically created and managed by the animation system when a new animation is started using one of the StartAnimation-methods or when an animation controller is created using one of the CreateController-methods (see IAnimationService).

Animation Value: An animation usually produces a value as the output. The base class AnimationInstance manages the timeline of the animation. The derived class AnimationInstanceT manages the animation value. The animation system automatically applies the output values to the properties that are being animated (see IAnimatablePropertyT).

Animation State and Timing: The property State returns the current state of the animation. The animation can be Delayed, Playing, Filling or Stopped. But the state does not indicate whether the animation timing is active. The property IsPaused indicates whether the animation timing is active or paused.

Active animations are managed by the AnimationManager. The animation system automatically advances and updates the animations.

The current state of an animation is computed once per frame (in Update(TimeSpan)) and cached until the next frame. The animation instance does not monitor the animation for changes. I.e. when the animation is modified the animation instance needs to be notified by calling Invalidate. Otherwise, it can return an invalid state in the current frame. For example, an animation instance plays a certain TimelineClip. During playback the user changes the Delay of the animation. Now, when the user reads State in the same frame the instance might return the wrong value. The user needs to call Invalidate to get the correct, up-to-date value. (It is not necessary to call Invalidate if the animations are updated using Update(TimeSpan). Update(TimeSpan) automatically computes the new values.)

Animation Tree: Animation instances can have children. For example, when a TimelineGroup is started it creates a root instance that has several children - one animation instance per animation in the timeline group. A timeline group might contain other timeline groups. The animation instances are organized in a tree structure.

Only the root instance of a tree can be controlled interactively (using an AnimationController).

Speed Ratio: The playback speed of the animation tree can be controlled by changing the property Speed. The speed ratio defines the rate at which time progresses. The default value is 1. A value of, for example, 2 means that the animation runs twice as fast. A value of 0.5 causes the animation to run in slow-motion at half speed.

Note that the only the speed ratio of the root instance in the animation tree can be controlled. (Changing the speed ratio of other nodes in the animation tree has no effect.)

Animation Weights: Each animation instance has a weight (see Weight) that defines the intensity of the animation. It is a factor that is applied to the animation output. The animation weight is in particular relevant when multiple animations should be combined. Each animation combines its output with the output of the previous stage in the animation composition chain. (If the animation is the first animation of a composition chain it combines its value with the base value of the property that is being animated.)

The default value is 1, which means that 100% of the animation is returned overriding any previous stage in an animation composition chain. A value of 0.75 means that result is weighted combination of the previous stage (25%) and the output of the current animation (75%). A value of 0 basically disables the output of the current stage.

Changing the animation weight of an instance affects the entire subtree: The current animation instance and all children. The effective animation weight is the product of all weights from the root instance to the current animation instance.

Secondary Animations: An animation instance itself is an IAnimatableObject, which means that it has properties which can be animated. The properties that can be animated are Speed and Weight. Secondary animation can be used, for example, to fade-in an animation by letting the animation weight go from 0 to 1 over time.

See Also