Public Member Functions | Protected Member Functions

KFbxAnimEvaluator Class Reference

This reference page is linked to from the following overview topics: 2012.1, FBX SDK 2011, FBX Scenes, Transformation Data, Migrating to the new data structures for animation, Writing and using your own evaluator.


Search for all occurrences

Detailed Description

The principal interface for animation evaluators.

The animation evaluator is used to compute node transforms and property values at specific times during an animation. Evaluators simplify the process of computing transform matrices by taking into account all of the parameters, such as pre- and post-rotations. This class is abstract so that SDK users can implement their own evaluator if needed. The default evaluator used by the FBX SDK is a KFbxAnimEvalClassic. The default evaluator can be queried with the function KFbxScene::GetEvaluator(), and can be changed using KFbxScene::SetEvaluator().

When working with scene nodes, the evaluator will always return an affine transform matrix that contains the translation, rotation and scale of that node.

When working with object properties, the evaluator will always return a structure that can contain as many components as the property can have. For example, an RGB color property would return a structure containing 3 channels. The class KFbxAnimCurveNode is used as a data container to store those values, because it can handle as many channels as needed, even if the property is not a real curve node .

Below is a typical usage of the evaluator class to retrieve the global transform matrix of each node in a scene:

 //Here we assume the user already imported a scene...
 for( int i = 0, c = MyScene->GetMemberCount(KFbxNode::ClassId); i < c; ++i )
 {
     KFbxNode* CurrentNode = MyScene->GetMember(KFbxNode::ClassId, i);
     KFbxXMatrix& NodeGlobalTransform = MyScene->GetEvaluator()->GetNodeGlobalTransform(CurrentNode);
 }

 //There is an equivalent call to retrieve a node's global transform, which is exactly the same as calling Scene->GetEvaluator() :
 KFbxXMatrix& NodeGlobalTransform = CurrentNode->EvaluateGlobalTransform();

Another typical usage of the evaluator class, but this time to retrieve the value of an animated color property on a material:

 //Assuming the user imported a scene with objects and materials...
 KFbxAnimCurveNode& Color = MyScene->GetEvaluator()->GetPropertyValue(MyMaterial->GetDiffuseColor());

 //The first parameter represent the index of the component for the property.
 //The second parameter value of GetChannelValue is the default value in case the component is not animated.
 float Red = Color.GetChannelValue<float>(0, 0.0f);
 float Green = Color.GetChannelValue<float>(1, 0.0f);
 float Blue = Color.GetChannelValue<float>(2, 0.0f);
Note:
Note that all the methods to retrieve global/local matrices as well as property values returns references. This is important for performance purposes, to prevent an extra memory copy.
See also:
KFbxScene, KFbxAnimEvalClassic, KFbxAnimCurveNode
Examples:

Transformations/main.cxx.

Definition at line 93 of file kfbxanimevaluator.h.

#include <kfbxanimevaluator.h>

Inheritance diagram for KFbxAnimEvaluator:
Inheritance graph
[legend]

List of all members.

Public Member Functions

void  SetContext (KFbxAnimStack *pAnimStack)
  Set the evaluator context, which represent which animation stack should be evaluated.
KFbxAnimStack GetContext ()
  Get the current evaluator context.
KFbxXMatrix GetNodeGlobalTransform (KFbxNode *pNode, KTime pTime=KTIME_INFINITE, KFbxNode::EPivotSet pPivotSet=KFbxNode::eSOURCE_SET, bool pApplyTarget=false, bool pForceEval=false)
  Returns a node's global transformation matrix at the specified time.
KFbxXMatrix GetNodeLocalTransform (KFbxNode *pNode, KTime pTime=KTIME_INFINITE, KFbxNode::EPivotSet pPivotSet=KFbxNode::eSOURCE_SET, bool pApplyTarget=false, bool pForceEval=false)
  Returns a node's local transformation matrix at the specified time.
KFbxVector4 GetNodeLocalTranslation (KFbxNode *pNode, KTime pTime=KTIME_INFINITE, KFbxNode::EPivotSet pPivotSet=KFbxNode::eSOURCE_SET, bool pApplyTarget=false, bool pForceEval=false)
  Returns the value of a node's LclTranslation property at the specified time.
KFbxVector4 GetNodeLocalRotation (KFbxNode *pNode, KTime pTime=KTIME_INFINITE, KFbxNode::EPivotSet pPivotSet=KFbxNode::eSOURCE_SET, bool pApplyTarget=false, bool pForceEval=false)
  Returns the value of a node's LclRotation property at the specified time.
KFbxVector4 GetNodeLocalScaling (KFbxNode *pNode, KTime pTime=KTIME_INFINITE, KFbxNode::EPivotSet pPivotSet=KFbxNode::eSOURCE_SET, bool pApplyTarget=false, bool pForceEval=false)
  Returns the value of a node's LclScaling property at the specified time.
KFbxAnimCurveNode GetPropertyValue (KFbxProperty &pProperty, KTime pTime, bool pForceEval=false)
  Get a property's value at the specified time.
KTime  ValidateTime (KTime pTime)
  Validate if the given time value is within animation stack time span range.
KFbxXMatrix GetNodeGlobalTransformFast (KFbxNode *pNode, int &pDirectIndex, KTime pTime=KTIME_INFINITE, KFbxNode::EPivotSet pPivotSet=KFbxNode::eSOURCE_SET, bool pApplyTarget=false, bool pForceEval=false)
  A faster version of GetNodeGlobalTransform aimed at real-time applications.
KFbxXMatrix GetNodeLocalTransformFast (KFbxNode *pNode, int &pDirectIndex, KTime pTime=KTIME_INFINITE, KFbxNode::EPivotSet pPivotSet=KFbxNode::eSOURCE_SET, bool pApplyTarget=false, bool pForceEval=false)
  A faster version of GetNodeLocalTransform aimed at real-time applications.
KFbxVector4 GetNodeLocalTranslationFast (KFbxNode *pNode, int &pDirectIndex, KTime pTime=KTIME_INFINITE, KFbxNode::EPivotSet pPivotSet=KFbxNode::eSOURCE_SET, bool pApplyTarget=false, bool pForceEval=false)
  A faster version of GetNodeLocalTranslation aimed at real-time applications.
KFbxVector4 GetNodeLocalRotationFast (KFbxNode *pNode, int &pDirectIndex, KTime pTime=KTIME_INFINITE, KFbxNode::EPivotSet pPivotSet=KFbxNode::eSOURCE_SET, bool pApplyTarget=false, bool pForceEval=false)
  A faster version of GetNodeLocalRotation aimed at real-time applications.
KFbxVector4 GetNodeLocalScalingFast (KFbxNode *pNode, int &pDirectIndex, KTime pTime=KTIME_INFINITE, KFbxNode::EPivotSet pPivotSet=KFbxNode::eSOURCE_SET, bool pApplyTarget=false, bool pForceEval=false)
  A faster version of GetNodeLocalScaling aimed at real-time applications.
KFbxAnimCurveNode GetPropertyValueFast (KFbxProperty &pProperty, int &pDirectIndex, KTime pTime=KTIME_INFINITE, bool pForceEval=false)
  A faster version of GetPropertyValue aimed at real-time applications.
void  ResetEvaluationState ()
  Completely reset the evaluation state cache by deleting all entries.
void  InvalidateNode (KFbxNode *pNode)
  Clears the specified node evaluation state cache, so the next time the evaluation is called for this node it get refreshed.
void  InvalidateProperty (KFbxProperty &pProperty)
  Clears the specified property evaluation state cache, so the next time the evaluation is called for this property it get refreshed.

Protected Member Functions

virtual void  EvaluateNodeTransform (KFbxNodeEvalState *pResult, KFbxNode *pNode, KTime pTime, KFbxAnimStack *pStack, KFbxNode::EPivotSet pPivotSet, bool pApplyTarget)=0
virtual void  EvaluatePropertyValue (KFbxAnimCurveNode *pResult, KFbxProperty &pProperty, KTime pTime, KFbxAnimStack *pStack)=0
  KFbxAnimEvaluator (KFbxSdkManager &pManager, char const *pName)
virtual void  Destruct (bool pRecursive, bool pDependents)
KFbxAnimEvalState GetEvalState (KTime pTime)
KFbxNodeEvalState GetNodeEvalState (KFbxNode *pNode, int &pDirectIndex, KTime pTime, KFbxNode::EPivotSet pPivotSet, bool pApplyTarget, bool pForceEval)

Constructor & Destructor Documentation

KFbxAnimEvaluator ( KFbxSdkManager pManager,
char const *  pName 
) [protected]

Member Function Documentation

void SetContext ( KFbxAnimStack pAnimStack )

Set the evaluator context, which represent which animation stack should be evaluated.

When no context is specified, the FBX SDK will try to automatically pick the first animation stack available in the scene and set it as the current context. If no animation stack are available, the evaluator will not be able to evaluate the scene's animation. Only one context can be evaluated at a time per evaluator.

Parameters:
pAnimStack The animation stack to evaluate when using this evaluator.
Remarks:
When changing the current context, the evaluator will automatically clear any animation evaluation cache present in memory.
See also:
KFbxAnimStack
Examples:
Animation/main.cxx, and ViewScene/main.cxx.
KFbxAnimStack* GetContext ( )

Get the current evaluator context.

Returns:
The current animation stack used by the evaluator.
Remarks:
When no context is specified, the FBX SDK will try to automatically pick the first animation stack available in the scene and set it as the current context.
KFbxXMatrix& GetNodeGlobalTransform ( KFbxNode pNode,
KTime  pTime = KTIME_INFINITE,
KFbxNode::EPivotSet  pPivotSet = KFbxNode::eSOURCE_SET,
bool  pApplyTarget = false,
bool  pForceEval = false 
)

Returns a node's global transformation matrix at the specified time.

The node's translation, rotation and scaling limits are taken into consideration.

Parameters:
pNode The node to evaluate.
pTime The time used for evaluate. If KTIME_INFINITE is used, this returns the default value, without animation curves evaluation.
pPivotSet The pivot set to take into account
pApplyTarget Applies the necessary transform to align into the target node
pForceEval Force the evaluator to refresh the evaluation state cache even if its already up-to-date.
Returns:
The resulting global transform of the specified node at the specified time.
Examples:
Transformations/main.cxx.
KFbxXMatrix& GetNodeLocalTransform ( KFbxNode pNode,
KTime  pTime = KTIME_INFINITE,
KFbxNode::EPivotSet  pPivotSet = KFbxNode::eSOURCE_SET,
bool  pApplyTarget = false,
bool  pForceEval = false 
)

Returns a node's local transformation matrix at the specified time.

The node's translation, rotation and scaling limits are taken into consideration.

Parameters:
pNode The node to evaluate.
pTime The time used for evaluate. If KTIME_INFINITE is used, this returns the default value, without animation curves evaluation.
pPivotSet The pivot set to take into account
pApplyTarget Applies the necessary transform to align into the target node
pForceEval Force the evaluator to refresh the evaluation state cache even if its already up-to-date.
Returns:
The resulting local transform of the specified node for the specified time.
Remarks:
The local transform matrix is calculated in this way: ParentGlobal.Inverse * Global, all transforms such as pre/post rotation are taken into consideration. This will return a different value than LclTranslation, LclRotation and LclScaling at the specified time. To evaluate these properties separately without taking pre/post rotation, pivots and offsets into consideration, please use GetNodeLocalTranslation(), GetNodeLocalRotation() and GetNodeLocalScaling().
Examples:
Transformations/main.cxx.
KFbxVector4& GetNodeLocalTranslation ( KFbxNode pNode,
KTime  pTime = KTIME_INFINITE,
KFbxNode::EPivotSet  pPivotSet = KFbxNode::eSOURCE_SET,
bool  pApplyTarget = false,
bool  pForceEval = false 
)

Returns the value of a node's LclTranslation property at the specified time.

No pivot, offsets, or any other transform is taken into consideration. The translation limit is applied.

Parameters:
pNode The transform node to evaluate.
pTime The time used for evaluate. If KTIME_INFINITE is used, this returns the default value, without animation curves evaluation.
pPivotSet The pivot set to take into account
pApplyTarget Applies the necessary transform to align into the target node
pForceEval Force the evaluator to refresh the evaluation state cache even if its already up-to-date.
Returns:
The resulting value of LclTranslation property of the specified node at the specified time.
KFbxVector4& GetNodeLocalRotation ( KFbxNode pNode,
KTime  pTime = KTIME_INFINITE,
KFbxNode::EPivotSet  pPivotSet = KFbxNode::eSOURCE_SET,
bool  pApplyTarget = false,
bool  pForceEval = false 
)

Returns the value of a node's LclRotation property at the specified time.

No pre/post rotation, rotation pivot, rotation offset or any other transform is taken into consideration. The rotation limit is applied.

Parameters:
pNode The transform node to evaluate.
pTime The time used for evaluate. If KTIME_INFINITE is used, this returns the default value, without animation curves evaluation.
pPivotSet The pivot set to take into account
pApplyTarget Applies the necessary transform to align into the target node
pForceEval Force the evaluator to refresh the evaluation state cache even if its already up-to-date.
Returns:
The resulting value of LclRotation property of the specified node at the specified time.
KFbxVector4& GetNodeLocalScaling ( KFbxNode pNode,
KTime  pTime = KTIME_INFINITE,
KFbxNode::EPivotSet  pPivotSet = KFbxNode::eSOURCE_SET,
bool  pApplyTarget = false,
bool  pForceEval = false 
)

Returns the value of a node's LclScaling property at the specified time.

No scaling pivot, scaling offset or any other transform is taken into consideration. The scaling limit is applied.

Parameters:
pNode The transform node to evaluate.
pTime The time used for evaluate. If KTIME_INFINITE is used, this returns the default value, without animation curves evaluation.
pPivotSet The pivot set to take into account
pApplyTarget Applies the necessary transform to align into the target node
pForceEval Force the evaluator to refresh the evaluation state cache even if its already up-to-date.
Returns:
The resulting value of LclScaling property of the specified node at the specified time.
KFbxAnimCurveNode& GetPropertyValue ( KFbxProperty pProperty,
KTime  pTime,
bool  pForceEval = false 
)

Get a property's value at the specified time.

Parameters:
pProperty The property to evaluate.
pTime The time used for evaluate.
pForceEval Force the evaluator to refresh the evaluation state cache even if its already up-to-date.
Returns:
The property value at the specified time stored in a curve node structure for easier access of complex types.
Examples:
Animation/main.cxx.
KTime ValidateTime ( KTime  pTime )

Validate if the given time value is within animation stack time span range.

Parameters:
pTime The time value to validate.
Returns:
The new validated time, clamped by the animation stack time span range.
Remarks:
If no animation stack are found, time zero is returned. This function is not used by the evaluator itself.
KFbxXMatrix& GetNodeGlobalTransformFast ( KFbxNode pNode,
int &  pDirectIndex,
KTime  pTime = KTIME_INFINITE,
KFbxNode::EPivotSet  pPivotSet = KFbxNode::eSOURCE_SET,
bool  pApplyTarget = false,
bool  pForceEval = false 
)

A faster version of GetNodeGlobalTransform aimed at real-time applications.

The optimization is achieved by providing an integer storage address that can be re-used for much faster access to the evaluation state cache result slot.

Parameters:
pNode The transform node to evaluate.
pDirectIndex The index used to retrieve the information in the evaluation state. The first time you evaluate a specific node, it must be set to -1. Then the returned index can be used for a quicker access to the evaluation state array by eliminating the search.
pTime The time used for evaluate. If KTIME_INFINITE is used, this returns the default value, without animation curves evaluation.
pPivotSet The pivot set to take into account.
pApplyTarget Applies the necessary transform to align into the target node.
pForceEval Force the evaluator to refresh the evaluation state cache even if its already up-to-date.
Returns:
The resulting global transform of the specified node at the specified time.
Remarks:
If the scene change in the application, all direct indexes must be updated, and the evaluation state cache must be invalidated. The translation, rotation and scaling limits are taken into consideration.
KFbxXMatrix& GetNodeLocalTransformFast ( KFbxNode pNode,
int &  pDirectIndex,
KTime  pTime = KTIME_INFINITE,
KFbxNode::EPivotSet  pPivotSet = KFbxNode::eSOURCE_SET,
bool  pApplyTarget = false,
bool  pForceEval = false 
)

A faster version of GetNodeLocalTransform aimed at real-time applications.

The optimization is achieved by providing an integer storage address that can be re-used for much faster access to the evaluation state cache result slot.

Parameters:
pNode The transform node to evaluate.
pDirectIndex The index used to retrieve the information in the evaluation state. The first time you evaluate a specific node, it must be set to -1. Then the returned index can be used for a quicker access to the evaluation state array by eliminating the search.
pTime The time used for evaluate. If KTIME_INFINITE is used, this returns the default value, without animation curves evaluation.
pPivotSet The pivot set to take into account.
pApplyTarget Applies the necessary transform to align into the target node.
pForceEval Force the evaluator to refresh the evaluation state cache even if its already up-to-date.
Returns:
The resulting local transform of the specified node for the specified time.
Remarks:
If the scene change in the application, all direct indexes must be updated, and the evaluation state cache must be invalidated. translation, rotation and scaling limits are taken into consideration. The local transform matrix is calculated in this way: ParentGlobal.Inverse * Global, all transforms such as pre/post rotation are taken into consideration. So to get TRS from returned matrix, it may different with values of LclTranslation, LclRotaion and LclScaling at specified time. To get values of properties LclTranslation, LclRotaion and LclScaling at the specified time, please use GetNodeLocalTranslationFast(), GetNodeLocalRotationFast() and GetNodeLocalScalingFast().
KFbxVector4& GetNodeLocalTranslationFast ( KFbxNode pNode,
int &  pDirectIndex,
KTime  pTime = KTIME_INFINITE,
KFbxNode::EPivotSet  pPivotSet = KFbxNode::eSOURCE_SET,
bool  pApplyTarget = false,
bool  pForceEval = false 
)

A faster version of GetNodeLocalTranslation aimed at real-time applications.

The optimization is achieved by providing an integer storage address that can be re-used for much faster access to the evaluation state cache result slot.

Parameters:
pNode The transform node to evaluate.
pDirectIndex The index used to retrieve the information in the evaluation state. The first time you evaluate a specific node, it must be set to -1. Then the returned index can be used for a quicker access to the evaluation state array by eliminating the search.
pTime The time used for evaluate.If KTIME_INFINITE is used, this returns the default value, without animation curves evaluation.
pPivotSet The pivot set to take into account.
pApplyTarget Applies the necessary transform to align into the target node
pForceEval Force the evaluator to refresh the evaluation state cache even if its already up-to-date.
Returns:
The resulting value of LclTranslation property of the specified node at the specified time.
Remarks:
If the scene change in the application, all direct indexes must be updated, and the evaluation state cache must be invalidated. Also, the translation limit is taken into consideration.
KFbxVector4& GetNodeLocalRotationFast ( KFbxNode pNode,
int &  pDirectIndex,
KTime  pTime = KTIME_INFINITE,
KFbxNode::EPivotSet  pPivotSet = KFbxNode::eSOURCE_SET,
bool  pApplyTarget = false,
bool  pForceEval = false 
)

A faster version of GetNodeLocalRotation aimed at real-time applications.

The optimization is achieved by providing an integer storage address that can be re-used for much faster access to the evaluation state cache result slot.

Parameters:
pNode The transform node to evaluate.
pDirectIndex The index used to retrieve the information in the evaluation state. The first time you evaluate a specific node, it must be set to -1. Then the returned index can be used for a quicker access to the evaluation state array by eliminating the search.
pTime The time used for evaluate.If KTIME_INFINITE is used, this returns the default value, without animation curves evaluation.
pPivotSet The pivot set to take into account.
pApplyTarget Applies the necessary transform to align into the target node.
pForceEval Force the evaluator to refresh the evaluation state cache even if its already up-to-date.
Returns:
The resulting local rotation of the specified node at the specified time.
Remarks:
Only calculate value of LclRotation property, no pre/post rotation, rotation pivot, rotation offset or any other transform are taken into account. If the scene change in the application, all direct indexes must be updated, and the evaluation state cache must be invalidated. Also, the rotation limit is taken into consideration.
KFbxVector4& GetNodeLocalScalingFast ( KFbxNode pNode,
int &  pDirectIndex,
KTime  pTime = KTIME_INFINITE,
KFbxNode::EPivotSet  pPivotSet = KFbxNode::eSOURCE_SET,
bool  pApplyTarget = false,
bool  pForceEval = false 
)

A faster version of GetNodeLocalScaling aimed at real-time applications.

The optimization is achieved by providing an integer storage address that can be re-used for much faster access to the evaluation state cache result slot.

Parameters:
pNode The transform node to evaluate.
pDirectIndex The index used to retrieve the information in the evaluation state. The first time you evaluate a specific node, it must be set to -1. Then the returned index can be used for a quicker access to the evaluation state array by eliminating the search.
pTime The time used for evaluate.If KTIME_INFINITE is used, this returns the default value, without animation curves evaluation.
pPivotSet The pivot set to take into account.
pApplyTarget Applies the necessary transform to align into the target node.
pForceEval Force the evaluator to refresh the evaluation state cache even if its already up-to-date.
Returns:
The resulting local scaling of the specified node at the specified time.
Remarks:
Only calculate value of LclScaling property, no scaling pivot, scaling offset or any other transform are taken into account. If the scene change in the application, all direct indexes must be updated, and the evaluation state cache must be invalidated. Also, the scaling limit is taken into consideration.
KFbxAnimCurveNode& GetPropertyValueFast ( KFbxProperty pProperty,
int &  pDirectIndex,
KTime  pTime = KTIME_INFINITE,
bool  pForceEval = false 
)

A faster version of GetPropertyValue aimed at real-time applications.

The optimization is achieved by providing an integer storage address that can be re-used for much faster access to the evaluation state cache result slot.

Parameters:
pProperty The property to evaluate.
pDirectIndex The index used to retrieve the information in the evaluation state. The first time you evaluate a specific property, it must be set to -1. Then the returned index can be used for a quicker access to the evaluation state array.
pTime The time used for evaluate.If KTIME_INFINITE is used, this returns the default value, without animation curves evaluation.
pForceEval Force the evaluator to refresh the evaluation state cache even if its already up-to-date.
Returns:
The property value at the specified time stored in a curve node structure for easier access of complex types.
Remarks:
If the scene change in the application, all direct indexes must be updated, and the evaluation state cache must be invalidated.
void ResetEvaluationState ( )

Completely reset the evaluation state cache by deleting all entries.

This reset also happens when changing the current context. This function is very useful in case the scene structure change, as noted in the remarks of fast functions.

void InvalidateNode ( KFbxNode pNode )

Clears the specified node evaluation state cache, so the next time the evaluation is called for this node it get refreshed.

Parameters:
pNode The node that needs to be re-evaluated in next evaluation.
void InvalidateProperty ( KFbxProperty pProperty )

Clears the specified property evaluation state cache, so the next time the evaluation is called for this property it get refreshed.

Parameters:
pProperty The property that needs to be re-evaluated in next evaluation.
virtual void EvaluateNodeTransform ( KFbxNodeEvalState pResult,
KFbxNode pNode,
KTime  pTime,
KFbxAnimStack pStack,
KFbxNode::EPivotSet  pPivotSet,
bool  pApplyTarget 
) [protected, pure virtual]
virtual void EvaluatePropertyValue ( KFbxAnimCurveNode pResult,
KFbxProperty pProperty,
KTime  pTime,
KFbxAnimStack pStack 
) [protected, pure virtual]
virtual void Destruct ( bool  pRecursive,
bool  pDependents 
) [protected, virtual]
KFbxAnimEvalState* GetEvalState ( KTime  pTime ) [protected]
KFbxNodeEvalState* GetNodeEvalState ( KFbxNode pNode,
int &  pDirectIndex,
KTime  pTime,
KFbxNode::EPivotSet  pPivotSet,
bool  pApplyTarget,
bool  pForceEval 
) [protected]

The documentation for this class was generated from the following file:

KFbxAnimEvaluator KFbxAnimEvaluator KFbxAnimEvaluator KFbxAnimEvaluator KFbxAnimEvaluator KFbxAnimEvaluator KFbxAnimEvaluator KFbxAnimEvaluator KFbxAnimEvaluator KFbxAnimEvaluator
KFbxAnimEvaluator KFbxAnimEvaluator KFbxAnimEvaluator KFbxAnimEvaluator KFbxAnimEvaluator KFbxAnimEvaluator KFbxAnimEvaluator KFbxAnimEvaluator KFbxAnimEvaluator KFbxAnimEvaluator