Open 3D Engine EMotionFX Gem API Reference  24.09
O3DE is an open-source, fully-featured, high-fidelity, modular 3D engine for building games and simulations, available to every industry.
EMotionFX::ActorInstance Class Reference

#include <ActorInstance.h>

Inherits MCore::RefCounted.

Public Types

enum  EBoundsType : AZ::u8 { BOUNDS_NODE_BASED = 0 , BOUNDS_MESH_BASED = 1 , BOUNDS_STATIC_BASED = 5 }
 

Public Member Functions

 AZ_RTTI (EMotionFX::ActorInstance, "{280A0170-EB6A-4E90-B2F1-E18D8EAEFB36}")
 
ActorGetActor () const
 
MCORE_INLINE uint32 GetID () const
 
void SetID (uint32 id)
 
MotionSystemGetMotionSystem () const
 
void SetMotionSystem (MotionSystem *newSystem, bool delCurrentFromMem=true)
 
MCORE_INLINE AnimGraphInstanceGetAnimGraphInstance () const
 
void SetAnimGraphInstance (AnimGraphInstance *instance)
 
MCORE_INLINE TransformDataGetTransformData () const
 
void SetIsEnabled (bool enabled)
 
MCORE_INLINE bool GetIsEnabled () const
 
MCORE_INLINE bool GetIsVisible () const
 
void SetIsVisible (bool isVisible)
 
void RecursiveSetIsVisible (bool isVisible)
 
void RecursiveSetIsVisibleTowardsRoot (bool isVisible)
 
void UpdateSkeletalLODFlags ()
 
size_t CalcNumDisabledNodes (size_t skeletalLODLevel) const
 
size_t CalcNumSkeletalLODLevels () const
 
size_t GetLODLevel () const
 
void SetLODLevel (size_t level)
 
AZ::Entity * GetEntity () const
 
AZ::EntityId GetEntityId () const
 
void SetCustomData (void *customData)
 
void * GetCustomData () const
 
void ApplyMorphSetup ()
 
void UpdateWorldTransform ()
 
void UpdateSkinningMatrices ()
 
void UpdateAttachments ()
 
void UpdateTransformations (float timePassedInSeconds, bool updateJointTransforms=true, bool sampleMotions=true)
 
void UpdateMeshDeformers (float timePassedInSeconds, bool processDisabledDeformers=false)
 
void UpdateMorphMeshDeformers (float timePassedInSeconds, bool processDisabledDeformers=false)
 
void PostPhysicsUpdate (float timePassedInSeconds)
 
void SetupAutoBoundsUpdate (float updateFrequencyInSeconds, EBoundsType boundsType=BOUNDS_NODE_BASED, uint32 itemFrequency=1)
 
bool GetBoundsUpdateEnabled () const
 
float GetBoundsUpdateFrequency () const
 
float GetBoundsUpdatePassedTime () const
 
EBoundsType GetBoundsUpdateType () const
 
float GetExpandBoundsBy () const
 
uint32 GetBoundsUpdateItemFrequency () const
 
void SetBoundsUpdateFrequency (float seconds)
 
void SetBoundsUpdatePassedTime (float seconds)
 
void SetBoundsUpdateType (EBoundsType bType)
 
void SetExpandBoundsBy (float expandBy)
 
void SetBoundsUpdateItemFrequency (uint32 freq)
 
void SetBoundsUpdateEnabled (bool enable)
 
void UpdateBounds (size_t geomLODLevel, EBoundsType boundsType=BOUNDS_NODE_BASED, uint32 itemFrequency=1)
 
void UpdateStaticBasedAabbDimensions ()
 
void SetStaticBasedAabb (const AZ::Aabb &aabb)
 
void GetStaticBasedAabb (AZ::Aabb *outAabb)
 
const AZ::Aabb & GetStaticBasedAabb () const
 
void CalcStaticBasedAabb (AZ::Aabb *outResult)
 
void CalcNodeBasedAabb (AZ::Aabb *outResult, uint32 nodeFrequency=1)
 
void CalcMeshBasedAabb (size_t geomLODLevel, AZ::Aabb *outResult, uint32 vertexFrequency=1)
 
const AZ::Aabb & GetAabb () const
 
void SetAabb (const AZ::Aabb &aabb)
 
MCORE_INLINE void SetLocalSpacePosition (const AZ::Vector3 &position)
 
MCORE_INLINE void SetLocalSpaceRotation (const AZ::Quaternion &rotation)
 
 EMFX_SCALECODE (MCORE_INLINE void SetLocalSpaceScale(const AZ::Vector3 &scale) { m_localTransform.m_scale=scale;} MCORE_INLINE const AZ::Vector3 &GetLocalSpaceScale() const { return m_localTransform.m_scale;}) MCORE_INLINE const AZ
 
MCORE_INLINE const Transform & GetLocalSpaceTransform () const
 
MCORE_INLINE const Transform & GetWorldSpaceTransform () const
 
MCORE_INLINE const Transform & GetWorldSpaceTransformInversed () const
 
bool CheckIfCanHandleAttachment (const ActorInstance *attachmentInstance) const
 
bool RecursiveHasAttachment (const ActorInstance *attachmentInstance) const
 
void AddAttachment (Attachment *attachment)
 
void RemoveAttachment (size_t nr, bool delFromMem=true)
 
void RemoveAllAttachments (bool delFromMem=true)
 
bool RemoveAttachment (ActorInstance *actorInstance, bool delFromMem=true)
 
size_t FindAttachmentNr (ActorInstance *actorInstance)
 
size_t GetNumAttachments () const
 
AttachmentGetAttachment (size_t nr) const
 
bool GetIsAttachment () const
 
ActorInstanceGetAttachedTo () const
 
ActorInstanceFindAttachmentRoot () const
 
AttachmentGetSelfAttachment () const
 
bool GetIsSkinAttachment () const
 
void UpdateDependencies ()
 
void RecursiveAddDependencies (Actor *actor)
 
size_t GetNumDependencies () const
 
Actor::DependencyGetDependency (size_t nr)
 
MorphSetupInstanceGetMorphSetupInstance () const
 
NodeIntersectsCollisionMesh (size_t lodLevel, const MCore::Ray &ray) const
 
NodeIntersectsCollisionMesh (size_t lodLevel, const MCore::Ray &ray, AZ::Vector3 *outIntersect, AZ::Vector3 *outNormal=nullptr, AZ::Vector2 *outUV=nullptr, float *outBaryU=nullptr, float *outBaryV=nullptr, uint32 *outIndices=nullptr) const
 
NodeIntersectsMesh (size_t lodLevel, const MCore::Ray &ray) const
 
NodeIntersectsMesh (size_t lodLevel, const MCore::Ray &ray, AZ::Vector3 *outIntersect, AZ::Vector3 *outNormal=nullptr, AZ::Vector2 *outUV=nullptr, float *outBaryU=nullptr, float *outBaryV=nullptr, uint32 *outStartIndex=nullptr) const
 
void SetRagdoll (Physics::Ragdoll *ragdoll)
 
RagdollInstanceGetRagdollInstance () const
 
void SetParentWorldSpaceTransform (const Transform &transform)
 
const Transform & GetParentWorldSpaceTransform () const
 
void SetRender (bool enabled)
 
bool GetRender () const
 
void SetIsUsedForVisualization (bool enabled)
 
bool GetIsUsedForVisualization () const
 
void SetIsOwnedByRuntime (bool isOwnedByRuntime)
 
bool GetIsOwnedByRuntime () const
 
void EnableNode (uint16 nodeIndex)
 
void DisableNode (uint16 nodeIndex)
 
MCORE_INLINE const AZStd::vector< uint16 > & GetEnabledNodes () const
 
MCORE_INLINE size_t GetNumEnabledNodes () const
 
MCORE_INLINE uint16 GetEnabledNode (size_t index) const
 
void EnableAllNodes ()
 
void DisableAllNodes ()
 
uint32 GetThreadIndex () const
 
void SetThreadIndex (uint32 index)
 
void DrawSkeleton (const Pose &pose, const AZ::Color &color)
 
void ApplyMotionExtractionDelta (const Transform &trajectoryDelta)
 
void ApplyMotionExtractionDelta ()
 
void MotionExtractionCompensate (EMotionExtractionFlags motionExtractionFlags=(EMotionExtractionFlags) 0)
 
void MotionExtractionCompensate (Transform &inOutMotionExtractionNodeTransform, EMotionExtractionFlags motionExtractionFlags=(EMotionExtractionFlags) 0) const
 
void SetMotionExtractionEnabled (bool enabled)
 
bool GetMotionExtractionEnabled () const
 
void SetTrajectoryDeltaTransform (const Transform &transform)
 
const Transform & GetTrajectoryDeltaTransform () const
 
AnimGraphPoseRequestPose (uint32 threadIndex)
 
void FreePose (uint32 threadIndex, AnimGraphPose *pose)
 
void SetMotionSamplingTimer (float timeInSeconds)
 
void SetMotionSamplingRate (float updateRateInSeconds)
 
float GetMotionSamplingTimer () const
 
float GetMotionSamplingRate () const
 
MCORE_INLINE size_t GetNumNodes () const
 
void UpdateVisualizeScale ()
 
float GetVisualizeScale () const
 
void SetVisualizeScale (float factor)
 
MCORE_INLINE void SetLightingChannelMask (uint32_t lightingChannelMask)
 
MCORE_INLINE uint32_t GetLightingChannelMask () const
 
- Public Member Functions inherited from MCore::RefCounted
 RefCounted ()
 
virtual ~RefCounted ()
 
void IncreaseReferenceCount ()
 
void DecreaseReferenceCount ()
 
void Destroy ()
 
uint32 GetReferenceCount () const
 

Static Public Member Functions

static ActorInstanceCreate (Actor *actor, AZ::Entity *entity=nullptr, uint32 threadIndex=0)
 
static void ExpandBounds (AZ::Aabb &aabb, float expandByPercentage)
 
static void ApplyMotionExtractionDelta (Transform &inOutTransform, const Transform &trajectoryDelta)
 
static void MotionExtractionCompensate (Transform &inOutMotionExtractionNodeTransform, const Transform &localSpaceBindPoseTransform, EMotionExtractionFlags motionExtractionFlags=(EMotionExtractionFlags) 0)
 

Friends

class Attachment
 

Additional Inherited Members

- Protected Member Functions inherited from MCore::RefCounted
virtual void Delete ()
 

Detailed Description

The actor instance class. An actor instance represents an animated character in your game. Each actor instance is created from some Actor object, which contains all the hierarchy information and possibly also the transformation and mesh information. Still, each actor instance can be controlled and animated individually.

Member Enumeration Documentation

◆ EBoundsType

The bounding volume generation types.

Enumerator
BOUNDS_NODE_BASED 

Calculate the bounding volumes based on the world space node positions.

BOUNDS_MESH_BASED 

Calculate the bounding volumes based on the world space vertex positions.

BOUNDS_STATIC_BASED 

Calculate the bounding volumes based on an approximate box, based on the mesh bounds, and move this box along with the actor instance position.

Member Function Documentation

◆ AddAttachment()

void EMotionFX::ActorInstance::AddAttachment ( Attachment attachment)

Add an attachment to this actor. Please note that each attachment can only belong to one actor instance.

Parameters
attachmentThe attachment to add.

◆ ApplyMorphSetup()

void EMotionFX::ActorInstance::ApplyMorphSetup ( )

Apply the morph targets transforms additively to the current local transforms as they are stored inside the TransformData object that you retrieve with GetTransformData(). This will not apply any mesh morphs yet, as that is performed by the UpdateMeshDeformers() method.

◆ CalcMeshBasedAabb()

void EMotionFX::ActorInstance::CalcMeshBasedAabb ( size_t  geomLODLevel,
AZ::Aabb *  outResult,
uint32  vertexFrequency = 1 
)

Calculate the axis aligned bounding box based on the world space vertex coordinates of the meshes. If the actor has no meshes, the created box will be invalid.

Parameters
geomLODLevelThe geometry LOD level to calculate the box for.
outResultThe AABB where this method should store the resulting box in.
vertexFrequencyThis includes every "vertexFrequency"-th vertex. So for example a value of 2 would skip every second vertex and so will process half of the vertices. A value of 4 would process only each 4th vertex, etc.

◆ CalcNodeBasedAabb()

void EMotionFX::ActorInstance::CalcNodeBasedAabb ( AZ::Aabb *  outResult,
uint32  nodeFrequency = 1 
)

Calculate the axis aligned bounding box based on the world space positions of the nodes.

Parameters
outResultThe AABB where this method should store the resulting box in.
nodeFrequencyThis will include every "nodeFrequency"-th node. So a value of 1 will include all nodes. A value of 2 would process every second node, meaning that half of the nodes will be skipped. A value of 4 would process every 4th node, etc.

◆ CalcNumDisabledNodes()

size_t EMotionFX::ActorInstance::CalcNumDisabledNodes ( size_t  skeletalLODLevel) const

Calculate the number of disabled nodes for a given skeletal lod level.

Parameters
[in]skeletalLODLevelThe skeletal LOD level to calculate the number of disabled nodes for.
Returns
The number of disabled nodes for the given skeletal LOD level.

◆ CalcNumSkeletalLODLevels()

size_t EMotionFX::ActorInstance::CalcNumSkeletalLODLevels ( ) const

Calculate the number of used skeletal LOD levels. Each actor instance alsways has 32 skeletal LOD levels while in most cases not all of them are actually used. This function determines the number of skeletal LOD levels that actually disable some more nodes relative to the previous LOD level.

Returns
The number of actually used skeletal LOD levels.

◆ CalcStaticBasedAabb()

void EMotionFX::ActorInstance::CalcStaticBasedAabb ( AZ::Aabb *  outResult)

Calculate an axis aligned bounding box that can be used as static AABB. It is static in the way that the volume does not change. It can however be translated as it will move with the character's position. The box will contain the mesh based bounds, and finds the maximum of the width, depth and height, and makes all depth width and height equal to this value. So the box will in most cases be too wide, but this is done on purpose. This can be used when the character is outside of the frustum, but we still update the position. We can then use this box to test for visibility again. If there are no meshes present, a widened node based box will be used instead as basis.

Parameters
outResultThe resulting bounding box, moved along with the actor instance's position.

◆ CheckIfCanHandleAttachment()

bool EMotionFX::ActorInstance::CheckIfCanHandleAttachment ( const ActorInstance attachmentInstance) const

Check if we can safely attach an attachment that uses the specified actor instance. This will check for infinite recursion/circular chains.

Parameters
attachmentInstanceThe actor instance we are trying to attach to this actor instance.
Returns
Returns true when we can safely attach the specified actor instance, otherwise false is returned.

◆ DisableAllNodes()

void EMotionFX::ActorInstance::DisableAllNodes ( )

Disable all nodes inside the actor instance. This means that no nodes will be updated at all (no motion sampling, no transformation calculations and no blending etc). After actor instance creation time it is possible that some nodes are disabled on default. This is controlled by node groups (represented by the NodeGroup class). Each Actor object has a set of node groups. Each group contains a set of nodes which are either enabled or disabled on default. You can use the Actor::GetNodeGroup(...) related methods to get access to the groups and enable or disable the predefined groups of nodes manually.

◆ DisableNode()

void EMotionFX::ActorInstance::DisableNode ( uint16  nodeIndex)

Disable a specific node. This will disable motion sampling, transformation and blending calculations for the given node.

Parameters
nodeIndexThe node number to disable. This must be in range of [0..Actor::GetNumNodes()-1].

◆ EMFX_SCALECODE()

EMotionFX::ActorInstance::EMFX_SCALECODE ( MCORE_INLINE void SetLocalSpaceScale(const AZ::Vector3 &scale) { m_localTransform.m_scale=scale;} MCORE_INLINE const AZ::Vector3 &GetLocalSpaceScale() const { return m_localTransform.m_scale;}  ) const
inline

Get the local space position/translation of this actor instance. This is relative to its parent (if it is attached ot something). Otherwise it is in world space.

Returns
The local space position. Get the local space rotation of this actor instance. This is relative to its parent (if it is attached ot something). Otherwise it is in world space.
The local space rotation.

◆ EnableAllNodes()

void EMotionFX::ActorInstance::EnableAllNodes ( )

Enable all nodes inside the actor instance. This means that all nodes will be processed and will have their motions sampled (unless disabled by LOD), local and world space matrices calculated, etc. After actor instance creation time it is possible that some nodes are disabled on default. This is controlled by node groups (represented by the NodeGroup class). Each Actor object has a set of node groups. Each group contains a set of nodes which are either enabled or disabled on default. You can use the Actor::GetNodeGroup(...) related methods to get access to the groups and enable or disable the predefined groups of nodes manually.

◆ EnableNode()

void EMotionFX::ActorInstance::EnableNode ( uint16  nodeIndex)

Enable a specific node. This will activate motion sampling, transformation and blending calculations for the given node.

Parameters
nodeIndexThe node number to enable. This must be in range of [0..Actor::GetNumNodes()-1].

◆ ExpandBounds()

static void EMotionFX::ActorInstance::ExpandBounds ( AZ::Aabb &  aabb,
float  expandByPercentage 
)
static

Expand a bounding box by a given percentage

Parameters
aabbThe bounding box to expand
expandBoundsByPercentage to expand the bounds by. A value of 0.0 means that the calculated bounding box won't be expanded at all, while .25 means it will become 125% the original size.

◆ FindAttachmentNr()

size_t EMotionFX::ActorInstance::FindAttachmentNr ( ActorInstance actorInstance)

Find the attachment number that uses a given actor instance.

Parameters
actorInstanceThe actor instance that the attachment you search for is using.
Returns
Returns the attachment number, in range of [0..GetNumAttachments()-1], or MCORE_INVALIDINDEX32 when no attachment using the specified actor instance can be found.

◆ FindAttachmentRoot()

ActorInstance* EMotionFX::ActorInstance::FindAttachmentRoot ( ) const

Find the root actor instance. If this actor instance object represents a gun, which is attached to a cowboy, which is attached to a horse, then the attachment root that is returned by this method is the horse.

Returns
The attachment root, or a pointer to itself when this actor instance isn't attached to anything.

◆ GetAabb()

const AZ::Aabb& EMotionFX::ActorInstance::GetAabb ( ) const

Get the axis aligned bounding box. This box will be updated once the UpdateBounds method is called. That method is also called automatically when the bounds auto-update feature is enabled.

Returns
The axis aligned bounding box.

◆ GetActor()

Actor* EMotionFX::ActorInstance::GetActor ( ) const

Get a pointer to the actor from which this is an instance.

Returns
A pointer to the actor from which this is an instance.

◆ GetAnimGraphInstance()

MCORE_INLINE AnimGraphInstance* EMotionFX::ActorInstance::GetAnimGraphInstance ( ) const
inline

Get the anim graph instance. This can return nullptr, in which case the motion system as returned by GetMotionSystem() will be used.

Returns
The anim graph instance.

◆ GetAttachedTo()

ActorInstance* EMotionFX::ActorInstance::GetAttachedTo ( ) const

Get the actor instance where this actor instance is attached to. This will return nullptr in case this actor instance is not an attachment.

Returns
A pointer to the actor instance where this actor instance is attached to.

◆ GetAttachment()

Attachment* EMotionFX::ActorInstance::GetAttachment ( size_t  nr) const

Get a specific attachment.

Parameters
nrThe attachment number, which must be in range of [0..GetNumAttachments()-1].
Returns
A pointer to the attachment.

◆ GetBoundsUpdateEnabled()

bool EMotionFX::ActorInstance::GetBoundsUpdateEnabled ( ) const

Check if the automatic bounds update feature is enabled. It will use the settings as provided to the SetupAutoBoundsUpdate method.

Returns
Returns true when the automatic bounds update feature is enabled, or false when it is disabled.

◆ GetBoundsUpdateFrequency()

float EMotionFX::ActorInstance::GetBoundsUpdateFrequency ( ) const

Get the automatic bounds update time frequency. This specifies the time interval between bounds updates. A value of 0.1 would mean that the bounding volumes will be updated 10 times per second. A value of 0.25 means 4 times per second, etc. A value of 0 can be used to force the updates to happen every frame.

Returns
Returns the automatic bounds update frequency time interval, in seconds.

◆ GetBoundsUpdateItemFrequency()

uint32 EMotionFX::ActorInstance::GetBoundsUpdateItemFrequency ( ) const

Get the bounding volume auto-update item frequency. A value of 1 would mean every node or vertex will be taken into account in the bounds calculation. A value of 2 would mean every second node or vertex would be taken into account. A value of 5 means every 5th node or vertex, etc. Higher values will result in faster bounds updates, but also in possibly less accurate bounds. The value returned will always be equal or greater than one.

Returns
The item frequency, which will be equal or greater than one.

◆ GetBoundsUpdatePassedTime()

float EMotionFX::ActorInstance::GetBoundsUpdatePassedTime ( ) const

Get the time passed since the last automatic bounds update.

Returns
The time passed, in seconds, since the last automatic bounds update.

◆ GetBoundsUpdateType()

EBoundsType EMotionFX::ActorInstance::GetBoundsUpdateType ( ) const

Get the bounding volume auto-update type. This can be either based on the node's world space positions, the mesh vertex world space positions, or the collision mesh vertex world space postitions.

Returns
The bounding volume update type.

◆ GetCustomData()

void* EMotionFX::ActorInstance::GetCustomData ( ) const

Get a pointer to the custom data you stored and linked with this actor instance object. Custom data can for example link a game or engine object with this EMotion FX ActorInstance object. An example is when EMotion FX triggers a motion event. You know the actor that triggered the event, but you don't know directly what game or engine object is linked to this actor. By using the custom data methods GetCustomData and SetCustomData you can set a pointer to your game or engine object in each actor instance. The pointer that you specify will not be deleted when the actor instance is being destructed.

Returns
A void pointer to the custom data you have specified.

◆ GetDependency()

Actor::Dependency* EMotionFX::ActorInstance::GetDependency ( size_t  nr)

Get a given dependency.

Parameters
nrThe dependency number to get, which must be in range of [0..GetNumDependencies()].
Returns
A pointer to the dependency.

◆ GetEnabledNode()

MCORE_INLINE uint16 EMotionFX::ActorInstance::GetEnabledNode ( size_t  index) const
inline

Get the node number of a given enabled node.

Parameters
indexAn index in the array of enabled nodes. This must be in range of [0..GetNumEnabledNodes()-1].
Returns
The node number, which relates to Actor::GetNode( returnValue ).

◆ GetEnabledNodes()

MCORE_INLINE const AZStd::vector<uint16>& EMotionFX::ActorInstance::GetEnabledNodes ( ) const
inline

Get direct access to the array of enabled nodes.

Returns
A read only reference to the array of enabled nodes. The values inside of this array are the node numbers of the enabled nodes.

◆ GetEntity()

AZ::Entity* EMotionFX::ActorInstance::GetEntity ( ) const

Get the entity to which the given actor instance belongs to.

Returns
Entity having an actor component added to it to which this actor instance belongs to. nullptr in case the actor instance is used without the entity component system.

◆ GetEntityId()

AZ::EntityId EMotionFX::ActorInstance::GetEntityId ( ) const

Get the entity id to which the given actor instance belongs to.

Returns
Entity id of the actor instance. EntityId::InvalidEntityId in case the actor instance is used without the entity component system.

◆ GetExpandBoundsBy()

float EMotionFX::ActorInstance::GetExpandBoundsBy ( ) const
inline

Get the normalized percentage that the calculated bounding box is expanded with. This can be used to add a tolerance area to the calculated bounding box to avoid clipping the character too early. A static bounding box together with the expansion is the recommended way for maximum performance.

Returns
A value of 0.0 means that the calculated bounding box won't be expanded at all, while .25 means it will become 125% the original size.

◆ GetID()

MCORE_INLINE uint32 EMotionFX::ActorInstance::GetID ( ) const
inline

Get the unique identification number for the actor instance.

Returns
The unique identification number.

◆ GetIsAttachment()

bool EMotionFX::ActorInstance::GetIsAttachment ( ) const

Check whether this actor instance also is an attachment or not. So if this actor instance is like a cowboy, and the cowboy is attached to a horse, then this will return true. If the cowboy (so this actor instance) would not be attached to anything, it will return false.

Returns
Returns true when this actor instance is also an attachment to some other actor instance. Otherwise false is returned.

◆ GetIsEnabled()

MCORE_INLINE bool EMotionFX::ActorInstance::GetIsEnabled ( ) const
inline

Check whether this actor instance is enabled or not. Disabled actor instances are not updated and processed.

Returns
Returns true when enabled, or false when disabled.

◆ GetIsSkinAttachment()

bool EMotionFX::ActorInstance::GetIsSkinAttachment ( ) const

Check if the actor instance is a skin attachment.

Returns
Returns true when the actor instance itself is a skin attachment, otherwise false is returned.

◆ GetIsVisible()

MCORE_INLINE bool EMotionFX::ActorInstance::GetIsVisible ( ) const
inline

Check the visibility flag. This flag has been set by the user and identifies if this actor instance is visible or not. This is used internally by the schedulers, so that heavy calculations can be skipped on invisible characters.

Returns
Returns true when the actor instance is marked as visible, otherwise false is returned.

◆ GetLODLevel()

size_t EMotionFX::ActorInstance::GetLODLevel ( ) const

Get the current used geometry and skeletal detail level. In total there are 32 possible skeletal LOD levels, where 0 is the highest detail, and 31 the lowest detail. Each detail level can disable specific nodes in the actor. These disabled nodes will not be processed at all by EMotion FX. It is important to know that disabled nodes never should be used inside skinning information or on other places where their transformations are needed.

Returns
The current LOD level.

◆ GetMorphSetupInstance()

MorphSetupInstance* EMotionFX::ActorInstance::GetMorphSetupInstance ( ) const

Get the morph setup instance. This doesn't contain the actual morph targets, but the unique settings per morph target. These unique settings are the weight value per morph target, and a boolean that specifies if the morph target weight should be controlled automatically (extracted from motions) or manually by user specified values. If you want to access the actual morph targets, you have to use the Actor::GetMorphSetup() method. When the morph setup instance object doesn't contain any morph targets, no morphing is used.

Returns
A pointer to the morph setup instance object for this actor instance.

◆ GetMotionSystem()

MotionSystem* EMotionFX::ActorInstance::GetMotionSystem ( ) const

Get the motion system of this actor instance. The motion system handles all the motion management and blending. If you want to play a motion or figure out what motions are currently active, you have to use the motion system class.

Returns
A pointer to the motion system.

◆ GetNumAttachments()

size_t EMotionFX::ActorInstance::GetNumAttachments ( ) const

Get the number of attachments that have been added to this actor instance.

Returns
The number of attachments added to this actor instance.

◆ GetNumDependencies()

size_t EMotionFX::ActorInstance::GetNumDependencies ( ) const

Get the number of dependencies that this actor instance has on other actors.

Returns
The number of dependencies.

◆ GetNumEnabledNodes()

MCORE_INLINE size_t EMotionFX::ActorInstance::GetNumEnabledNodes ( ) const
inline

Get the number of enabled nodes inside this actor instance.

Returns
The number of nodes that have been enabled and are being updated.

◆ GetRender()

bool EMotionFX::ActorInstance::GetRender ( ) const

Check if calls to ActorUpdateCallBack::OnRender() for this actor instance are being made or not.

Returns
Returns true when the ActorUpdateCallBack::OnRender() is being called for this actor instance. False is returned in case this callback won't be executed for this actor instance.

◆ GetSelfAttachment()

Attachment* EMotionFX::ActorInstance::GetSelfAttachment ( ) const

Get the attachment where this actor instance is part of. So if this actor instance is a gun, and the gun is attached to some cowboy actor instance, then the Attachment object that is returned here, is the attachment object for the gun that was added to the cowboy actor instance.

Returns
The attachment where this actor instance takes part of, or nullptr when this actor instance isn't an attachment.

◆ GetTransformData()

MCORE_INLINE TransformData* EMotionFX::ActorInstance::GetTransformData ( ) const
inline

Get the transformation data class for this actor instance. This transformation data class gives you access to all the transforms of the nodes in the actor. So if you wish to get or set any transformations, you can do it with the object returned by this method.

Returns
A pointer to the transformation data object.

◆ IntersectsCollisionMesh() [1/2]

Node* EMotionFX::ActorInstance::IntersectsCollisionMesh ( size_t  lodLevel,
const MCore::Ray ray 
) const

Check for an intersection between the collision mesh of this actor and a given ray. Returns a pointer to the node it detected a collision in case there is a collision with any of the collision meshes of all nodes of this actor. If there is no collision mesh attached to the nodes, no intersection test will be done, and nullptr will be returned.

Parameters
lodLevelThe level of detail to check the collision with.
rayThe ray to check.
Returns
A pointer to the node we detected the first intersection with (doesn't have to be the closest), or nullptr when no intersection found.

◆ IntersectsCollisionMesh() [2/2]

Node* EMotionFX::ActorInstance::IntersectsCollisionMesh ( size_t  lodLevel,
const MCore::Ray ray,
AZ::Vector3 *  outIntersect,
AZ::Vector3 *  outNormal = nullptr,
AZ::Vector2 *  outUV = nullptr,
float *  outBaryU = nullptr,
float *  outBaryV = nullptr,
uint32 *  outIndices = nullptr 
) const

Check for an intersection between the collision mesh of this actor and a given ray, and calculate the closest intersection point. If there is no collision mesh attached to the nodes, no intersection test will be done, and nullptr will be returned. Returns a pointer to the node it detected a collision in case there is a collision with the collision meshes of the actor, 'outIntersect' will contain the closest intersection point in case there is a collision. Use the other Intersects method when you do not need the intersection point (since that one is faster).

Parameters
lodLevelThe level of detail to check the collision with.
rayThe ray to test with.
outIntersectA pointer to the vector to store the intersection point in, in case of a collision (nullptr allowed).
outNormalA pointer to the vector to store the normal at the intersection point, in case of a collision (nullptr allowed).
outUVA pointer to the vector to store the uv coordinate at the intersection point (nullptr allowed).
outBaryUA pointer to a float in which the method will store the barycentric U coordinate, to be used to interpolate values on the triangle (nullptr allowed).
outBaryVA pointer to a float in which the method will store the barycentric V coordinate, to be used to interpolate values on the triangle (nullptr allowed).
outIndicesA pointer to an array of 3 integers, which will contain the 3 vertex indices of the closest intersecting triangle. Even on polygon meshes with polygons of more than 3 vertices three indices are returned. In that case the indices represent a sub-triangle inside the polygon. A value of nullptr is allowed, which will skip storing the resulting triangle indices.
Returns
A pointer to the node we detected the closest intersection with, or nullptr when no intersection found.

◆ IntersectsMesh() [1/2]

Node* EMotionFX::ActorInstance::IntersectsMesh ( size_t  lodLevel,
const MCore::Ray ray 
) const

Check for an intersection between the real mesh (if present) of this actor and a given ray. Returns a pointer to the node it detected a collision in case there is a collision with any of the real meshes of all nodes of this actor. If there is no mesh attached to this node, no intersection test will be performed and nullptr will be returned.

Parameters
lodLevelThe level of detail to check the collision with.
rayThe ray to test with.
Returns
Returns a pointer to itself when an intersection occurred, or nullptr when no intersection found.

◆ IntersectsMesh() [2/2]

Node* EMotionFX::ActorInstance::IntersectsMesh ( size_t  lodLevel,
const MCore::Ray ray,
AZ::Vector3 *  outIntersect,
AZ::Vector3 *  outNormal = nullptr,
AZ::Vector2 *  outUV = nullptr,
float *  outBaryU = nullptr,
float *  outBaryV = nullptr,
uint32 *  outStartIndex = nullptr 
) const

Checks for an intersection between the real mesh (if present) of this actor and a given ray. Returns a pointer to the node it detected a collision in case there is a collision with any of the real meshes of all nodes of this actor, 'outIntersect' will contain the closest intersection point in case there is a collision. Both the intersection point and normal which are returned are in world space. Use the other Intersects method when you do not need the intersection point (since that one is faster). Both the intersection point and normal which are returned are in world space.

Parameters
lodLevelThe level of detail to check the collision with.
rayThe ray to test with.
outIntersectA pointer to the vector to store the intersection point in, in case of a collision (nullptr allowed).
outNormalA pointer to the vector to store the normal at the intersection point, in case of a collision (nullptr allowed).
outUVA pointer to the vector to store the uv coordinate at the intersection point (nullptr allowed).
outBaryUA pointer to a float in which the method will store the barycentric U coordinate, to be used to interpolate values on the triangle (nullptr allowed).
outBaryVA pointer to a float in which the method will store the barycentric V coordinate, to be used to interpolate values on the triangle (nullptr allowed).
outIndicesA pointer to an array of 3 integers, which will contain the 3 vertex indices of the closest intersecting triangle. Even on polygon meshes with polygons of more than 3 vertices three indices are returned. In that case the indices represent a sub-triangle inside the polygon. A value of nullptr is allowed, which will skip storing the resulting triangle indices.
Returns
A pointer to the node we detected the closest intersection with, or nullptr when no intersection found.

◆ MotionExtractionCompensate()

static void EMotionFX::ActorInstance::MotionExtractionCompensate ( Transform &  inOutMotionExtractionNodeTransform,
const Transform &  localSpaceBindPoseTransform,
EMotionExtractionFlags  motionExtractionFlags = (EMotionExtractionFlags) 0 
)
static

Remove the trajectory transform from the input transformation.

Parameters
[out]inOutMotionExtractionNodeTransformLocal space transformation of the motion extraction joint.
[in]localSpaceBindPoseTransformBind pose transform of the motion extraction joint in local space.
[in]motionExtractionFlagsMotion extraction capture options.

◆ RecursiveAddDependencies()

void EMotionFX::ActorInstance::RecursiveAddDependencies ( Actor actor)

Recursively add dependencies for the given actor. This will add all dependencies stored in the specified actor, to this actor instance. Also it will recurse into the dependencies of the dependencies of the given actor.

Parameters
actorThe actor we should recursively copy the dependencies from.

◆ RecursiveHasAttachment()

bool EMotionFX::ActorInstance::RecursiveHasAttachment ( const ActorInstance attachmentInstance) const

Check if this actor instance has a specific attachment that uses a specified actor instance. This function is recursive, so it also checks the attachments of the attachments, etc.

Parameters
attachmentInstanceThe actor instance you want to check with, which represents the attachment.
Returns
Returns true when the specified actor instance is being used as attachment down the hierarchy, otherwise false is returned.

◆ RecursiveSetIsVisible()

void EMotionFX::ActorInstance::RecursiveSetIsVisible ( bool  isVisible)

Specifies if this actor instance is visible or not. This recursively propagates its visibility status to child attachments. So if your horse is visibe then the rider that is attached on top of the horse will also become marked as visible.

Parameters
Specifyif all nodes touched should be marked as visible or not.

◆ RecursiveSetIsVisibleTowardsRoot()

void EMotionFX::ActorInstance::RecursiveSetIsVisibleTowardsRoot ( bool  isVisible)

Recursively set the actor instance visibility flag, upwards in hierarchy, moving from an attachment up to the root actor instance.

Parameters
Specifyif all nodes touched should be marked as visible or not.

◆ RemoveAllAttachments()

void EMotionFX::ActorInstance::RemoveAllAttachments ( bool  delFromMem = true)

Remove all attachments from this actor instance.

Parameters
delFromMemSet this to true when you want the attachments also to be deleted from memory. When you set this to false, it will not be deleted from memory, but only removed from the array of attachments that is stored locally inside this actor instance.

◆ RemoveAttachment() [1/2]

bool EMotionFX::ActorInstance::RemoveAttachment ( ActorInstance actorInstance,
bool  delFromMem = true 
)

Remove an attachment that uses a specified actor instance.

Parameters
actorInstanceThe actor instance that the attachment is using.
delFromMemSet this to true when you want the attachment also to be deleted from memory. When you set this to false, it will not be deleted from memory, but only removed from the array of attachments that is stored locally inside this actor instance.

◆ RemoveAttachment() [2/2]

void EMotionFX::ActorInstance::RemoveAttachment ( size_t  nr,
bool  delFromMem = true 
)

Remove a given attachment.

Parameters
nrThe attachment number, which must be in range of [0..GetNumAttachments()-1].
delFromMemSet this to true when you want the attachment that gets removed also to be deleted from memory. When you set this to false, it will not be deleted from memory, but only removed from the array of attachments that is stored locally inside this actor instance.

◆ SetAabb()

void EMotionFX::ActorInstance::SetAabb ( const AZ::Aabb &  aabb)

Set the axis aligned bounding box. Please beware that this box will get automatically overwritten when automatic bounds update is enabled.

Parameters
aabbThe axis aligned bounding box to store.

◆ SetAnimGraphInstance()

void EMotionFX::ActorInstance::SetAnimGraphInstance ( AnimGraphInstance instance)

Set the anim graph instance. This can be nullptr, in which case the motion system as returned by GetMotionSystem() will be used.

Parameters
instanceThe anim graph instance.

◆ SetBoundsUpdateEnabled()

void EMotionFX::ActorInstance::SetBoundsUpdateEnabled ( bool  enable)

Specify whether you want the auto-bounds update to be enabled or disabled. On default, after creation of the actor instance it is enabled, using node based, with an update frequency of 1 and an update frequency of 0.1 (ten times per second).

Parameters
enableSet to true when you want to enable the bounds automatic update feature, or false when you'd like to disable it.

◆ SetBoundsUpdateFrequency()

void EMotionFX::ActorInstance::SetBoundsUpdateFrequency ( float  seconds)

Set the auto-bounds update time frequency, in seconds. This specifies the time interval between bounds updates. A value of 0.1 would mean that the bounding volumes will be updated 10 times per second. A value of 0.25 means 4 times per second, etc. A value of 0 can be used to force the updates to happen every frame.

Parameters
secondsThe amount of seconds between every bounding volume update.

◆ SetBoundsUpdateItemFrequency()

void EMotionFX::ActorInstance::SetBoundsUpdateItemFrequency ( uint32  freq)

Set the bounding volume auto-update item frequency. A value of 1 would mean every node or vertex will be taken into account in the bounds calculation. A value of 2 would mean every second node or vertex would be taken into account. A value of 5 means every 5th node or vertex, etc. Higher values will result in faster bounds updates, but also in possibly less accurate bounds. The frequency value must always be greater than or equal to one.

Parameters
freqThe item frequency, which has to be 1 or above. Higher values result in faster performance, but lower accuracy.

◆ SetBoundsUpdatePassedTime()

void EMotionFX::ActorInstance::SetBoundsUpdatePassedTime ( float  seconds)

Set the time passed since the last automatic bounds update.

Parameters
secondsThe amount of seconds, since the last automatic update.

◆ SetBoundsUpdateType()

void EMotionFX::ActorInstance::SetBoundsUpdateType ( EBoundsType  bType)

Set the bounding volume auto-update type. This can be either based on the node's world space positions, the mesh vertex world space positions, or the collision mesh vertex world space positions.

Parameters
bTypeThe bounding volume update type.

◆ SetCustomData()

void EMotionFX::ActorInstance::SetCustomData ( void *  customData)

Set a pointer to some custom data you want to store and link with this actor instance object. Custom data can for example link a game or engine object with this EMotion FX ActorInstance object. An example is when EMotion FX triggers a motion event. You know the actor that triggered the event, but you don't know directly what game or engine object is linked to this actor. By using the custom data methods GetCustomData and SetCustomData you can set a pointer to your game or engine object in each actor instance. The pointer that you specify will not be deleted when the actor instance is being destructed.

Parameters
customDataA void pointer to the custom data to link with this actor instance.

◆ SetExpandBoundsBy()

void EMotionFX::ActorInstance::SetExpandBoundsBy ( float  expandBy)
inline

Set the normalized percentage that the calculated bounding box should be expanded with. This can be used to add a tolerance area to the calculated bounding box to avoid clipping the character too early. A static bounding box together with the expansion is the recommended way for maximum performance.

Parameters
[in]expandByA value of 1.0 means that the calculated bounding box won't be expanded at all, while 2.0 means it will be twice the size.

◆ SetID()

void EMotionFX::ActorInstance::SetID ( uint32  id)

Set the unique identification number for the actor instance.

Parameters
[in]idThe unique identification number.

◆ SetIsEnabled()

void EMotionFX::ActorInstance::SetIsEnabled ( bool  enabled)

Enable or disable this actor instance. Disabled actor instances are not processed at all. It will be like they do not exist. On default the actor instance is enabled, after creation. You can disable an actor instance that acts as skin attachment, but is not currently attached. This way the clothing items your character doesn't wear won't take processing power. It is always faster not to have the actor instance created at all in such case though.

Parameters
enabledSpecifies whether this actor instance is enabled or not.

◆ SetIsOwnedByRuntime()

void EMotionFX::ActorInstance::SetIsOwnedByRuntime ( bool  isOwnedByRuntime)

Marks the actor instance as used by the engine runtime, as opposed to the tool suite.

◆ SetIsVisible()

void EMotionFX::ActorInstance::SetIsVisible ( bool  isVisible)

Change the visibility state.

Parameters
isVisibleSet to true when the actor instance is visible, otherwise set it to false.

◆ SetLocalSpacePosition()

MCORE_INLINE void EMotionFX::ActorInstance::SetLocalSpacePosition ( const AZ::Vector3 &  position)
inline

Set the local space position of this actor instance. This is relative to its parent (if it is attached ot something). Otherwise it is in world space.

Parameters
positionThe position/translation to use.

◆ SetLocalSpaceRotation()

MCORE_INLINE void EMotionFX::ActorInstance::SetLocalSpaceRotation ( const AZ::Quaternion &  rotation)
inline

Set the local rotation of this actor instance. This is relative to its parent (if it is attached ot something). Otherwise it is in world space.

Parameters
rotationThe rotation to use.

◆ SetLODLevel()

void EMotionFX::ActorInstance::SetLODLevel ( size_t  level)

Set the current geometry and skeletal detail level, where 0 is the highest detail.

Parameters
levelThe LOD level. Values higher than [GetNumGeometryLODLevels()-1] will be clamped to the maximum LOD.

◆ SetMotionSystem()

void EMotionFX::ActorInstance::SetMotionSystem ( MotionSystem newSystem,
bool  delCurrentFromMem = true 
)

Set the current motion system to use. On default a MotionLayerSystem is set.

Parameters
newSystemThe new motion system to use.
delCurrentFromMemIf set to true, the currently set motion system will be deleted from memory, before setting the new motion system.

◆ SetRender()

void EMotionFX::ActorInstance::SetRender ( bool  enabled)

Set whether calls to ActorUpdateCallBack::OnRender() for this actor instance should be made or not.

Parameters
enabledSet to true when the ActorUpdateCallBack::OnRender() should be called for this actor instance, otherwise set to false.

◆ SetupAutoBoundsUpdate()

void EMotionFX::ActorInstance::SetupAutoBoundsUpdate ( float  updateFrequencyInSeconds,
EBoundsType  boundsType = BOUNDS_NODE_BASED,
uint32  itemFrequency = 1 
)

Setup the automatic update settings of the bounding volume. This allows you to specify at what time interval the bounding volume of the actor instance should be updated and if this update should base its calculations on the nodes, mesh vertices or collision mesh vertices.

Parameters
updateFrequencyInSecondsThe bounds will be updated every "updateFrequencyInSeconds" seconds. A value of 0 would mean every frame and a value of 0.1 would mean 10 times per second.
boundsTypeThe type of bounds calculation. This can be either based on the node's world space positions, the mesh world space positions or the collision mesh world space positions.
itemFrequencyA value of 1 would mean every node or vertex will be taken into account in the bounds calculation. A value of 2 would mean every second node or vertex would be taken into account. A value of 5 means every 5th node or vertex, etc. Higher values will result in faster bounds updates, but also in possibly less accurate bounds. This value must 1 or higher. Zero is not allowed.

◆ UpdateAttachments()

void EMotionFX::ActorInstance::UpdateAttachments ( )

Update all the attachments. This calls the update method for each attachment.

◆ UpdateBounds()

void EMotionFX::ActorInstance::UpdateBounds ( size_t  geomLODLevel,
EBoundsType  boundsType = BOUNDS_NODE_BASED,
uint32  itemFrequency = 1 
)

Update the bounding volumes of the actor.

Parameters
geomLODLevelThe geometry level of detail number to generate the LOD for. Must be in range of 0..GetNumGeometryLODLevels()-1. The same LOD level will be chosen for the attachments when they will be included. If the specified LOD level is lower than the number of attachment LODS, the lowest attachment LOD will be chosen.
boundsTypeThe bounding volume generation method, each having different accuracies and generation speeds.
itemFrequencyDepending on the type of bounds you specify to the boundsType parameter, this specifies how many "vertices or nodes" the updating functions should skip. If you specified a value of 4, and use BOUND_MESH_BASED or collision mesh based, every 4th vertex will be included in the bounds calculation, so only processing 25% of the total number of vertices. The same goes for node based bounds, but then it will process every 4th node. Of course higher values produce less accurate results, but are faster to process.

◆ UpdateDependencies()

void EMotionFX::ActorInstance::UpdateDependencies ( )

Update all dependencies of this actor instance.

◆ UpdateMeshDeformers()

void EMotionFX::ActorInstance::UpdateMeshDeformers ( float  timePassedInSeconds,
bool  processDisabledDeformers = false 
)

Update/Process the mesh deformers. This will apply skinning and morphing deformations to the meshes used by the actor instance. All deformations happen on the CPU. So if you use pure GPU processing, you should not be calling this method. Also invisible actor instances should not update their mesh deformers, as this can be very CPU intensive.

Parameters
timePassedInSecondsThe time passed in seconds, since the last frame or update.
processDisabledDeformersWhen set to true, even mesh deformers that are disabled will even be processed.

◆ UpdateMorphMeshDeformers()

void EMotionFX::ActorInstance::UpdateMorphMeshDeformers ( float  timePassedInSeconds,
bool  processDisabledDeformers = false 
)

Update/Process the morph mesh deformers. This will apply morphing deformations only to the meshes used by the actor instance. All morph deformations happen on the CPU. So if you use pure GPU processing, you should not be calling this method.

Parameters
timePassedInSecondsThe time passed in seconds, since the last frame or update.
processDisabledDeformersWhen set to true, even mesh deformers that are disabled will even be processed.

◆ UpdateSkeletalLODFlags()

void EMotionFX::ActorInstance::UpdateSkeletalLODFlags ( )

Use the skeletal LOD flags from the nodes of the corresponding actor and pass them over to this actor instance. The actor keeps the information about which nodes are enabled at what skeletal LOD and this is the transfer function to actually apply it to the actor instance as each actor instance can be in a different skeletal LOD level.

◆ UpdateSkinningMatrices()

void EMotionFX::ActorInstance::UpdateSkinningMatrices ( )

Update the skinning matrices. This will update the data inside the TransformData class.

◆ UpdateStaticBasedAabbDimensions()

void EMotionFX::ActorInstance::UpdateStaticBasedAabbDimensions ( )

Update the base static axis aligned bounding box shape. This is a quite heavy function in comparision to the CalcStaticBasedAABB. Basically the dimensions of the static based aabb are calculated here. First it will try to generate the aabb from the meshes. If there are no meshes it will use a node based aabb as basis. After that it will find the maximum of the depth, width and height, and makes all dimensions the same as this max value. This function is generally only executed once, when creating the actor instance. The CalcStaticBasedAABB function then simply translates this box along with the actor instance's position.

◆ UpdateTransformations()

void EMotionFX::ActorInstance::UpdateTransformations ( float  timePassedInSeconds,
bool  updateJointTransforms = true,
bool  sampleMotions = true 
)

Update the transformations of this actor instance. This can be the actor instance transform and can also include the joint transforms. This automatically updates all motion timers and anim graph nodes as well.

Parameters
timePassedInSecondsThe time passed in seconds, since the last frame or update.
updateJointTransformsWhen set to true the joint transformations will be calculated by calculating the animation graph output for example.
sampleMotionsWhen set to true motions will be sampled, or whole anim graphs if using those. When updateMatrices is set to false, motions will never be sampled, even if set to true.

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