ISkeletalAnimationController

Detailed Description

class ISkeletalAnimationController : public RED::IREDObject

Skeletal animation controller interface.

@related Loading and Playing Skeletal Animations, class RED::ISkeletalAnimationBlender, class RED::IAnimationClipController, function RED::Factory::CreateSkeletalAnimationClipController, function RED::Factory::CreateSkeletalAnimationBlender

This interface provides functions to control a skeleton animation. It also provides several parameters used by the RED::ISkeletalAnimationBlender object

  • group;
  • fade parameters;
  • blend weight;
  • additive option;

The bone filtering functions prevents the animation of some bones in the skeletons if desired.

Skeletal animation controllers are created with RED::Factory::CreateSkeletalAnimationClipController and RED::Factory::CreateSkeletalAnimationBlender.

Public Functions

SET_CID(CID_class_REDISkeletalAnimationController)
virtual RED_RC AddSkinnedMesh(RED::Object *iSkinnedMesh) = 0

Associates a skinned mesh to this controller.

This function does nothing if the controller already contains the given skinned mesh.

This function returns RED_BAD_PARAM if iSkinnedMesh does not share the same skeleton with the meshes already registered.

Parameters:iSkinnedMesh – Skinned mesh as a RED::IMeshShape.
Returns:RED_OK if the operation has succeeded,

RED_BAD_PARAM if iSkinnedMesh can’t be added to the controller,

RED_FAIL otherwise
virtual RED_RC RemoveSkinnedMesh(RED::Object *iSkinnedMesh) = 0

Removes a skinned mesh from this controller.

This function does nothing if the controller does not contain the given skinned mesh.

Parameters:iSkinnedMesh – Skinned mesh to remove as a RED::IMeshShape.
Returns:RED_OK if the operation has succeeded,

RED_FAIL otherwise
virtual RED_RC ClearSkinnedMeshes() = 0

Removes all the skinned meshes from this controller.

Returns:RED_OK if the operation has succeeded,

RED_FAIL otherwise
virtual RED_RC GetSkinnedMeshesCount(unsigned int &oSkinnedMeshesCount) const = 0

Returns the number of skinned meshes associated to this controller.

Parameters:oSkinnedMeshesCount – Returned number of skinned meshes.
Returns:RED_OK if the operation has succeeded,

RED_FAIL otherwise
virtual RED_RC GetSkinnedMesh(RED::Object *&oSkinnedMesh, unsigned int iSkinnedMeshIndex) const = 0

Returns the skinned mesh associated to this controller.

Parameters:
  • oSkinnedMesh – Returned skinned mesh as a RED::IMeshShape.
  • iSkinnedMeshIndex – index of the skinned mesh to retrieve.
Returns:

RED_OK if the operation has succeeded,

RED_BAD_PARAM if iSkinnedMeshIndex is incorrect,

RED_FAIL otherwise

virtual RED_RC GetBonesCount(unsigned int &oCount) const = 0

Returns the number of bones in the animated skeleton.

Parameters:oCount – Returned number of bones.
Returns:RED_OK if the operation has succeeded,

RED_FAIL otherwise
virtual void SetGroup(unsigned int iGroup) = 0

Sets the controller group.

In a RED::ISkeletalAnimationBlender, animation controllers can be grouped. A group defines a skeleton part. All the controllers in the same group are faded out after a call to RED::ISkeletalAnimationBlender::BlendTo whereas other groups are not faded.

Parameters:iGroup – the controller group.
virtual unsigned int GetGroup() const = 0

Gets the controller group.

See RED::ISkeletalAnimationController::SetGroup for details about groups.

Returns:the controller group.
virtual void SetFadeParameters(double iDuration, double iWeight) = 0

Sets the fading parameters.

The fade parameters control the fade-in and fade-out of the animation. After calling this function and RED::ISkeletalAnimationController::Update the animation weight will vary to iWeight in a iDuration period.

Parameters:
  • iDuration – the fade duration.
  • iWeight – the fade target animation weight.
virtual bool IsAdditive() const = 0

Tells if the animation is additive or not.

Used in a RED::ISkeletalAnimationBlender, an animation can be additive. If so, it will be added to other animations during the blending instead of classicaly interpolated.

Returns:true if the animation is additive, false otherwise.
virtual void SetAdditive(bool iAdditive) = 0

Sets the animation additive.

See RED::ISkeletalAnimationController::IsAdditive for informations about additive animations.

Parameters:iAdditive – true to set the animation additive, false otherwise.
virtual void SetIsAppliedToSkeleton(bool iIsApplied) = 0

Applies the animation directly to a skeleton.

If applied to the skeleton, the animation results are applied to the bones of the skeleton. If not, the animation results are stored internally to be used elsewhere.

Parameters:iIsApplied – true to apply the animation to the skeleton, false otherwise.
virtual RED_RC SetRootMotionPolicy(RED::ROOT_MOTION_COMPONENT iRootComponent, RED::ROOT_MOTION_POLICY iPolicy, bool iExtract) = 0

Sets the root motion policies for the root bone transforms.

For each component of the root bone, this function sets the policy to apply:

The iExtract parameter tells if the root bone component must be applied to the associated skinned meshes or not. If not, the user can retrieve the extracted root transform with the RED::ISkeletalAnimationController::GetRootMotionMatrix function (and optionnaly apply it to any parent shape of the mesh).

Parameters:
  • iRootComponent – The component of the root bone on which we set the policy.
  • iPolicy – The policy to apply.
  • iExtract – true to extract the root bone component, false to apply it to the mesh.
Returns:

RED_OK when the operation succeeded,

RED_BAD_PARAM if the method received an invalid parameter,

RED_FAIL otherwise.

virtual void GetRootMotionMatrix(const RED::Matrix *&oMatrix) const = 0

Returns the extracted root motion matrix.

If the RED::ISkeletalAnimationController::SetRootMotionPolicy function had been called with the option to extract the root motion, the user can retrieve it via this function.

Parameters:oMatrix – The output extracted root motion transform.
virtual double GetBlendWeight() const = 0

Returns the animation blend weight.

The blend weight is the amount of this animation used in the RED::ISkeletalAnimationBlender. The blend weight value must range from 0 to 1.

Returns:the animation blend weight.
virtual void SetBlendWeight(double iBlendWeight) = 0

Sets the animation blend weight.

The blend weight is the amount of this animation used in the RED::ISkeletalAnimationBlender. The blend weight value must range from 0 to 1.

Parameters:iBlendWeight – The animation blend weight.
virtual RED_RC GetBoneTransform(const RED::AnimationData *&oTransform, unsigned int iBoneIndex) const = 0

Returns the animation bone transforms.

Parameters:
  • oTransform – Returned animation bone transform.
  • iBoneIndex – Bone index to get the transform.
Returns:

RED_OK if the operation has succeeded,

RED_BAD_PARAM if iBoneIndex is incorrect,

RED_FAIL otherwise

virtual RED_RC SetBoneFilter(int iBoneIndex, bool iFilter, bool iFilterChildrenTree) = 0

Filters a bone and its hierarchy from the animation.

When a bone is filtered, it is not influenced by the animation controller. Filtering bones is generally used to animate skeleton parts separately. Each part influenced by a different animation controller.

Parameters:
  • iBoneIndex – Bone index to filter.
  • iFilter – true to exclude the bone from the animation, false otherwise.
  • iFilterChildrenTree – If true, applies iFilter to the bone children and propagates it to the tree.
Returns:

RED_OK if the operation has succeeded,

RED_BAD_PARAM if iBoneIndex is incorrect,

RED_WORKFLOW_ERROR if the controller doesn’t contain any mesh,

RED_FAIL otherwise
virtual bool IsBoneAnimated(int iBoneIndex) const = 0

Tests if a bone is filtered or not.

See RED::ISkeletalAnimationController::SetBoneFilter for details about bone filtering.

Parameters:iBoneIndex – Bone index to test filtering.
Returns:true if the bone is filtered, false if not.
virtual RED_RC Update(double iDeltaTime, const RED::State &iState) = 0

Updates the animation controller.

This method must be called at each frame to update the animation.

Parameters:
  • iDeltaTime – Time elapsed since last frame.
  • iState – The current transaction parameter.
Returns:

RED_OK if the operation has succeeded,

RED_FAIL otherwise