CAnimation Class Reference

Description

Animation clips, skeletal and blend shape animation, animation playback, blending and other features.

Wraps Animation as a Component.

Inherits Component.

Methods

 CAnimation (const HSceneObject &parent)
 
void setDefaultClip (const HAnimationClip &clip)
 Sets the default clip to play as soon as the component is enabled. More...
 
void setWrapMode (AnimWrapMode wrapMode)
 Changes the wrap mode for all active animations. More...
 
void setSpeed (float speed)
 Changes the speed for all animations. More...
 
void play (const HAnimationClip &clip)
 Plays the specified animation clip. More...
 
void blendAdditive (const HAnimationClip &clip, float weight, float fadeLength=0.0f, UINT32 layer=0)
 Plays the specified animation clip on top of the animation currently playing in the main layer. More...
 
void blend1D (const Blend1DInfo &info, float t)
 Blend multiple animation clips between each other using linear interpolation. More...
 
void blend2D (const Blend2DInfo &info, const Vector2 &t)
 Blend four animation clips between each other using bilinear interpolation. More...
 
void crossFade (const HAnimationClip &clip, float fadeLength)
 Fades the specified animation clip in, while fading other playing animation out, over the specified time period. More...
 
void sample (const HAnimationClip &clip, float time)
 Samples an animation clip at the specified time, displaying only that particular frame without further playback. More...
 
void stop (UINT32 layer)
 Stops playing all animations on the provided layer. More...
 
void stopAll ()
 Stops playing all animations. More...
 
bool isPlaying () const
 Checks if any animation clips are currently playing. More...
 
bool getState (const HAnimationClip &clip, AnimationClipState &state)
 Retrieves detailed information about a currently playing animation clip. More...
 
void setState (const HAnimationClip &clip, AnimationClipState state)
 Changes the state of a playing animation clip. More...
 
void setMorphChannelWeight (UINT32 idx, float weight)
 Changes a weight of a single morph channel, determining how much of it to apply on top of the base mesh. More...
 
void setBounds (const AABox &bounds)
 Sets bounds that will be used for animation and mesh culling. More...
 
const AABoxgetBounds () const
 Gets animation bounds. More...
 
void setUseBounds (bool enable)
 Determines should animation bounds be used for visibility determination (culling). More...
 
bool getUseBounds () const
 Checks whether animation bounds are enabled. More...
 
void setEnableCull (bool enable)
 Enables or disables culling of the animation when out of view. More...
 
bool getEnableCull () const
 Checks whether the animation will be evaluated when it is out of view. More...
 
RTTITypeBasegetRTTI () const override
 Returns an interface you can use to access class' Run Time Type Information. More...
 
Internal
SPtr< Animation_getInternal () const
 Returns the Animation implementation wrapped by this component. More...
 
void _addBone (const HBone &bone)
 Registers a new bone component, creating a new transform mapping from the bone name to the scene object the component is attached to.
 
void _removeBone (const HBone &bone)
 Unregisters a bone component, removing the bone -> scene object mapping. More...
 
void _notifyBoneChanged (const HBone &bone)
 Called whenever the bone name the Bone component points to changes. More...
 
void _registerRenderable (const HRenderable &renderable)
 Registers a Renderable component with the animation, should be called whenever a Renderable component is added to the same scene object as this component.
 
void _unregisterRenderable ()
 Removes renderable from the animation component. More...
 
void _updateBounds (bool updateRenderable=true)
 Re-applies the bounds to the internal animation object, and the relevant renderable object if one exists. More...
 
- Methods inherited from Component
HSceneObject sceneObject () const
 Returns the SceneObject this Component is assigned to. More...
 
HSceneObject SO () const
 Returns the SceneObject this Component is assigned to. More...
 
HComponent getHandle () const
 Returns a handle to this object. More...
 
virtual void update ()
 Called once per frame. More...
 
virtual bool calculateBounds (Bounds &bounds)
 Calculates bounds of the visible contents represented by this component (for example a mesh for Renderable). More...
 
virtual bool typeEquals (const Component &other)
 Checks if this and the provided component represent the same type. More...
 
void destroy (bool immediate=false)
 Removes the component from parent SceneObject and deletes it. More...
 
RTTITypeBasegetRTTI () const override
 Returns an interface you can use to access class' Run Time Type Information. More...
 
virtual void _instantiate ()
 Construct any resources the component needs before use. More...
 
void setNotifyFlags (TransformChangedFlags flags)
 Sets new flags that determine when is onTransformChanged called. More...
 
TransformChangedFlags _getNotifyFlags () const
 Gets the currently assigned notify flags. More...
 
- Methods inherited from GameObject
UINT64 getInstanceId () const
 Returns the unique instance ID of the GameObject. More...
 
UINT32 getLinkId () const
 Returns an ID that identifies a link between this object and its equivalent in the linked prefab. More...
 
const StringgetName () const
 Gets the name of the object. More...
 
void setName (const String &name)
 Sets the name of the object. More...
 
void _setIsDestroyed ()
 Marks the object as destroyed. More...
 
bool _getIsDestroyed () const
 Checks if the object has been destroyed. More...
 
void _setLinkId (UINT32 id)
 Changes the prefab link ID for this object. More...
 
virtual void _setInstanceData (GameObjectInstanceDataPtr &other)
 Replaces the instance data with another objects instance data. More...
 
virtual GameObjectInstanceDataPtr _getInstanceData () const
 Returns instance data that identifies this GameObject and is used for referencing by game object handles. More...
 
- Methods inherited from IReflectable
bool isDerivedFrom (RTTITypeBase *base)
 Returns true if current RTTI class is derived from base (Or if it is the same type as base). More...
 
UINT32 getTypeId () const
 Returns an unique type identifier of the class. More...
 
const StringgetTypeName () const
 Returns the type name of the class. More...
 

Static methods

static RTTITypeBasegetRTTIStatic ()
 
- Static methods inherited from Component
static RTTITypeBasegetRTTIStatic ()
 
- Static methods inherited from GameObject
static RTTITypeBasegetRTTIStatic ()
 
- Static methods inherited from IReflectable
static Vector< RTTITypeBase * > & getDerivedClasses ()
 Returns all classes deriving directly from IReflectable. More...
 
static SPtr< IReflectablecreateInstanceFromTypeId (UINT32 rttiTypeId)
 Creates an empty instance of a class from a type identifier. More...
 
static void _registerDerivedClass (RTTITypeBase *derivedClass)
 Called by each type deriving from IReflectable, on program load. More...
 
static RTTITypeBase_getRTTIfromTypeId (UINT32 rttiTypeId)
 Returns class' RTTI type from type id. More...
 
static bool _isTypeIdDuplicate (UINT32 typeId)
 Checks if the provided type id is unique. More...
 
static void _checkForCircularReferences ()
 Iterates over all RTTI types and reports any circular references (for example one type having a field referencing another type, and that type having a field referencing the first type). More...
 
static RTTITypeBasegetRTTIStatic ()
 Returns an interface you can use to access class' Run Time Type Information. More...
 

Fields

Event< void(const HAnimationClip &, const String &)> onEventTriggered
 Triggered whenever an animation event is reached. More...
 

Method documentation

SPtr<Animation> _getInternal ( ) const

Returns the Animation implementation wrapped by this component.

void _notifyBoneChanged ( const HBone bone)

Called whenever the bone name the Bone component points to changes.

void _removeBone ( const HBone bone)

Unregisters a bone component, removing the bone -> scene object mapping.

void _unregisterRenderable ( )

Removes renderable from the animation component.

Should be called when a Renderable component is removed from this scene object.

void _updateBounds ( bool  updateRenderable = true)

Re-applies the bounds to the internal animation object, and the relevant renderable object if one exists.

void blend1D ( const Blend1DInfo info,
float  t 
)

Blend multiple animation clips between each other using linear interpolation.

Unlike normal animations these animations are not advanced with the progress of time, and is instead expected the user manually changes the t parameter.

Parameters
[in]infoInformation about the clips to blend. Clip positions must be sorted from lowest to highest.
[in]tParameter that controls the blending. Range depends on the positions of the provided animation clips.
void blend2D ( const Blend2DInfo info,
const Vector2 t 
)

Blend four animation clips between each other using bilinear interpolation.

Unlike normal animations these animations are not advanced with the progress of time, and is instead expected the user manually changes the t parameter.

Parameters
[in]infoInformation about the clips to blend.
[in]tParameter that controls the blending, in range [(0, 0), (1, 1)]. t = (0, 0) means top left animation has full influence, t = (1, 0) means top right animation has full influence, t = (0, 1) means bottom left animation has full influence, t = (1, 1) means bottom right animation has full influence.
void blendAdditive ( const HAnimationClip clip,
float  weight,
float  fadeLength = 0.0f,
UINT32  layer = 0 
)

Plays the specified animation clip on top of the animation currently playing in the main layer.

Multiple such clips can be playing at once, as long as you ensure each is given its own layer. Each animation can also have a weight that determines how much it influences the main animation.

Parameters
[in]clipClip to additively blend. Must contain additive animation curves.
[in]weightDetermines how much of an effect will the blended animation have on the final output. In range [0, 1].
[in]fadeLengthApplies the blend over a specified time period, increasing the weight as the time passes. Set to zero to blend immediately. In seconds.
[in]layerLayer to play the clip in. Multiple additive clips can be playing at once in separate layers and each layer has its own weight.
void crossFade ( const HAnimationClip clip,
float  fadeLength 
)

Fades the specified animation clip in, while fading other playing animation out, over the specified time period.

Parameters
[in]clipClip to fade in.
[in]fadeLengthDetermines the time period over which the fade occurs. In seconds.
void destroyInternal ( )
protected

Destroys the internal Animation representation.

void eventTriggered ( const HAnimationClip clip,
const String name 
)
protected

Callback triggered whenever an animation event is triggered.

Vector<HBone> findChildBones ( )
protected

Searches child scene objects for Bone components and returns any found ones.

const AABox& getBounds ( ) const

Gets animation bounds.

See also
setBounds.
bool getEnableCull ( ) const

Checks whether the animation will be evaluated when it is out of view.

RTTITypeBase* getRTTI ( ) const
overridevirtual

Returns an interface you can use to access class' Run Time Type Information.

Note
You must derive your own version of RTTITypeBase, in which you may encapsulate all reflection specific operations.

Reimplemented from GameObject.

bool getState ( const HAnimationClip clip,
AnimationClipState state 
)

Retrieves detailed information about a currently playing animation clip.

Parameters
[in]clipClip to retrieve the information for.
[out]stateAnimation clip state containing the requested information. Only valid if the method returns true.
Returns
True if the state was found (animation clip is playing), false otherwise.
bool getUseBounds ( ) const

Checks whether animation bounds are enabled.

See also
setUseBounds.
bool isPlaying ( ) const

Checks if any animation clips are currently playing.

void onDestroyed ( )
overrideprotectedvirtual

Called once just before the component is destroyed.

Called regardless of the state the component is in.

Reimplemented from Component.

void onDisabled ( )
overrideprotectedvirtual

Called every time a component is placed into the Stopped state.

This includes component destruction if component wasn't already in Stopped state during destruction. When called during destruction it is called before onDestroyed.

Reimplemented from Component.

void onEnabled ( )
overrideprotectedvirtual

Called every time a component leaves the Stopped state.

This includes component creation if requirements for leaving the Stopped state are met. When called during creation it is called after onInitialized.

Reimplemented from Component.

void onInitialized ( )
overrideprotectedvirtual

Called once when the component first leaves the Stopped state.

This includes component creation if requirements for leaving Stopped state are met, in which case it is called after onCreated.

Reimplemented from Component.

void onTransformChanged ( TransformChangedFlags  flags)
overrideprotectedvirtual

Called when the component's parent scene object has changed.

Not called if the component is in Stopped state. Also only called if necessary notify flags are set via _setNotifyFlags().

Reimplemented from Component.

void play ( const HAnimationClip clip)

Plays the specified animation clip.

Parameters
[in]clipClip to play.
void restoreInternal ( )
protected

Creates the internal representation of the Animation and restores the values saved by the Component.

void sample ( const HAnimationClip clip,
float  time 
)

Samples an animation clip at the specified time, displaying only that particular frame without further playback.

Parameters
[in]clipAnimation clip to sample.
[in]timeTime to sample the clip at.
void setBoneMappings ( )
protected

Finds any scene objects that are mapped to bone transforms.

Such object's transforms will be affected by skeleton bone animation.

void setBounds ( const AABox bounds)

Sets bounds that will be used for animation and mesh culling.

Only relevant if setUseBounds() is set to true.

void setDefaultClip ( const HAnimationClip clip)

Sets the default clip to play as soon as the component is enabled.

If more control over playing clips is needed use the play(), blend() and crossFade() methods to queue clips for playback manually, and setState() method for modify their states individually.

void setEnableCull ( bool  enable)

Enables or disables culling of the animation when out of view.

Culled animation will not be evaluated.

void setMorphChannelWeight ( UINT32  idx,
float  weight 
)

Changes a weight of a single morph channel, determining how much of it to apply on top of the base mesh.

Parameters
idxIndex of the morph channel to modify. This must match the channels contained in the object provided to setMorphShapes().
weightWeight that determines how much of the channel to apply to the mesh, in range [0, 1].
void setSpeed ( float  speed)

Changes the speed for all animations.

The default value is 1.0f. Use negative values to play-back in reverse.

void setState ( const HAnimationClip clip,
AnimationClipState  state 
)

Changes the state of a playing animation clip.

If animation clip is not currently playing the playback is started for the clip.

Parameters
[in]clipClip to change the state for.
[in]stateNew state of the animation (e.g. changing the time for seeking).
void setUseBounds ( bool  enable)

Determines should animation bounds be used for visibility determination (culling).

If false the bounds of the mesh attached to the relevant CRenderable component will be used instead.

void setWrapMode ( AnimWrapMode  wrapMode)

Changes the wrap mode for all active animations.

Wrap mode determines what happens when animation reaches the first or last frame.

See also
AnimWrapMode
void stop ( UINT32  layer)

Stops playing all animations on the provided layer.

Specify -1 to stop animation on the main layer (non-additive animations).

void stopAll ( )

Stops playing all animations.

Member Data Documentation

Event<void(const HAnimationClip&, const String&)> onEventTriggered

Triggered whenever an animation event is reached.