public interface IAnimationValueTraits<T>

Public Interface IAnimationValueTraits(Of T)

generic<typename T>
public interface class IAnimationValueTraits

Type Parameters

The IAnimationValueTraits<(Of <(<'T>)>)> describe the operations that can be performed on a certain type of animation value. This abstraction is necessary in order to treat different types of animations with the same code.

The interface IAnimationValueTraits<(Of <(<'T>)>)> and its implementing classes are used only internally in DigitalRune Animation. It is safe to ignore these types. (The following information is only relevant for users who plan to implement new types of animation values and want to reuse the existing animation classes.)

Reference Types vs. Value Types: Animation values can be reference types as well as value types, which makes the task a little complicated. Most method parameters need to be passed by reference to efficiently handle both cases.

Create, Recycle and Copy: The methods Create(T%, T%) and Recycle(T%) can be used to create and recycle animation values. (Create(T%, T%) returns a previously recycled instance, if any is available. It is recommended to recycle and reuse animation values if they allocate memory on the managed heap.)

Set and Reset: The method Set(T%, IAnimatableProperty<(Of <<'(T>)>>)) is called when the animation system sets an animation value to an IAnimatableProperty<(Of <(<'T>)>)>; Reset(IAnimatableProperty<(Of <<'(T>)>>)) is called when all animations are removed from an IAnimatableProperty<(Of <(<'T>)>)>.

The method Copy(T%, T%) copies that data of one animation value to another.

Add, Identity, Invert and Multiply: In order to handle all types of animation with the same code we need to apply some math: The animation values form an algebraic group. The group has a group operation (see Add(T%, T%, T%)) that represents the application of an animation value to a given value, an identity element (see SetIdentity(T%)) and a function that computes the inverse of an animation value (see Invert(T%, T%)). For efficiency, there is also a function Multiply(T%, Int32, T%) that computes the repeated application of the same value. For example, if + represents the group operation then Multiply(x,3) = x + x + x.

Group Operation: The group operation depends on the type of animation value. Here are some examples: If the animation value is a real number the group operation is a simple addition. The group operation of a n-dimensional vector is a vector addition. If the animation value is a unit quaternion that represents a rotation, the group operation is a quaternion product (because two quaternions are combined using the quaternion product). Etc.

Note that, in general the group operations are not a commutative, meaning that the order of the operands is important! For example, the quaternion product is not commutative.

Identity Element: Every group has an identity element regarding the group operation. For example, the identity element of a scalar addition is 0. The identity of the vector addition is the zero vector. The identity of the quaternion product is the identity quaternion. Etc.

Inverse: Every value of the group has an inverse. For example, the inverse element of a real number r is -r. The inverse of an n-dimensional vector v is -v. The inverse of a unit quaternion q is q^-1. Etc.

Interpolation: Another important part of animation is interpolation ("animation blending"). The interpolation of animation values is in most cases a weighted combination of the animation values. Animation values need to support two types of interpolation:

• Interpolation of two values - Animations can be concatenated by adding them to animation composition chains. The output of one stage in the composition chain is blended with the output of the previous stage. The interpolation of two animation values is implemented by Interpolate(T%, T%, Single, T%).
• Interpolation of n values - Animations can be combined using a BlendGroup. The values of all animations in the blend group are blended together. A group can contain more than two animations. The blending of n animation values is implemented by BeginBlend(T%), BlendNext(T%, T%, Single), and EndBlend(T%). (The blend operation is split into 3 operations which need to be called successively. BlendNext(T%, T%, Single) needs to be called for each animation value.)

Optimizations: In order to improve performance - in particular on the Xbox 360 - most parameters are passed by reference. All operation happen in-place, i.e. no new objects are allocated.