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

#include <Node.h>

Inherits EMotionFX::BaseObject.

Public Types

enum  { TYPE_ID = 0x00000001 }
 
enum  ENodeFlags : AZ::u8 { FLAG_INCLUDEINBOUNDSCALC = 1 << 0 , FLAG_ATTACHMENT = 1 << 1 , FLAG_CRITICAL = 1 << 2 }
 

Public Member Functions

NodeClone (Skeleton *skeleton) const
 
void SetParentIndex (size_t parentNodeIndex)
 
MCORE_INLINE size_t GetParentIndex () const
 
NodeGetParentNode () const
 
void RecursiveCollectParents (AZStd::vector< size_t > &parents, bool clearParentsArray=true) const
 
void SetName (const char *name)
 
const char * GetName () const
 
const AZStd::string & GetNameString () const
 
void SetSemanticName (const char *name)
 
const char * GetSemanticName () const
 
const AZStd::string & GetSemanticNameString () const
 
MCORE_INLINE uint32 GetID () const
 
MCORE_INLINE uint32 GetSemanticID () const
 
MCORE_INLINE size_t GetNumChildNodes () const
 
size_t GetNumChildNodesRecursive () const
 
MCORE_INLINE size_t GetChildIndex (size_t nr) const
 
MCORE_INLINE bool CheckIfIsChildNode (size_t nodeIndex) const
 
void AddChild (size_t nodeIndex)
 
void SetChild (size_t childNr, size_t childNodeIndex)
 
void SetNumChildNodes (size_t numChildNodes)
 
void PreAllocNumChildNodes (size_t numChildNodes)
 
void RemoveChild (size_t nodeIndex)
 
void RemoveAllChildNodes ()
 
bool GetIsRootNode () const
 
bool GetHasChildNodes () const
 
NodeFindRoot () const
 
void AddAttribute (NodeAttribute *attribute)
 
size_t GetNumAttributes () const
 
NodeAttributeGetAttribute (size_t attributeNr)
 
NodeAttributeGetAttributeByType (uint32 attributeType)
 
size_t FindAttributeNumber (uint32 attributeTypeID) const
 
void RemoveAllAttributes ()
 
void RemoveAttribute (size_t index)
 
void RemoveAttributeByType (uint32 attributeTypeID, size_t occurrence=0)
 
size_t RemoveAllAttributesByType (uint32 attributeTypeID)
 
void SetNodeIndex (size_t index)
 
MCORE_INLINE size_t GetNodeIndex () const
 
void SetSkeletalLODLevelBits (size_t bitValues)
 
void SetSkeletalLODStatus (size_t lodLevel, bool enabled)
 
MCORE_INLINE bool GetSkeletalLODStatus (size_t lodLevel) const
 
MCORE_INLINE bool GetIncludeInBoundsCalc () const
 
void SetIncludeInBoundsCalc (bool includeThisNode)
 
MCORE_INLINE bool GetIsCritical () const
 
void SetIsCritical (bool isCritical)
 
bool GetIsAttachmentNode () const
 
void SetIsAttachmentNode (bool isAttachmentNode)
 
- Public Member Functions inherited from EMotionFX::BaseObject
 BaseObject ()
 
virtual ~BaseObject ()
 
- Public Member Functions inherited from MCore::MemoryObject
 MemoryObject ()
 
virtual ~MemoryObject ()
 
void IncreaseReferenceCount ()
 
void DecreaseReferenceCount ()
 
void Destroy ()
 
uint32 GetReferenceCount () const
 

Static Public Member Functions

static NodeCreate (const char *name, Skeleton *skeleton)
 
static NodeCreate (uint32 nameID, Skeleton *skeleton)
 

Friends

class Actor
 
class SkeletonModel
 

Additional Inherited Members

- Protected Member Functions inherited from EMotionFX::BaseObject
void Delete () override
 
virtual void Delete ()
 

Detailed Description

The node class. A node in EMotion FX is a connection point in the hierarchy of the character. Each node can have one parent, but multiple child nodes. Every node has a transformation describing the orientation of the node, so where it is positioned and how it is scaled and rotated in 3D space. Examples of nodes could be a bone, like an upper arm or lower arm, a finger, a head, a gun, a cigarette, a camera, a light, etc. So basically it can be everything, which can be animated (but it doesn't have to be animated of course).

Member Enumeration Documentation

◆ ENodeFlags

The node flags (options).

Enumerator
FLAG_INCLUDEINBOUNDSCALC 

Specifies whether we have to include this node in the bounds calculation or not (true on default).

FLAG_ATTACHMENT 

Indicates if this node is an attachment node or not (false on default).

FLAG_CRITICAL 

Indicates if this node is a critical node. A critical node is always included the skeleton and cannot be optimized out (false on default).

Member Function Documentation

◆ AddAttribute()

void EMotionFX::Node::AddAttribute ( NodeAttribute attribute)

Add a node attribute to this node.

Parameters
attributeThe attribute to add to the node.

◆ AddChild()

void EMotionFX::Node::AddChild ( size_t  nodeIndex)

Add a child to this node.

Parameters
nodeIndexThe index of the child node to add.

◆ CheckIfIsChildNode()

MCORE_INLINE bool EMotionFX::Node::CheckIfIsChildNode ( size_t  nodeIndex) const
inline

Checks if the given node is a child of this node.

Parameters
nodeIndexThe node to check whether it is a child or not.
Returns
True if the given node is a child, false if not.

◆ Clone()

Node * EMotionFX::Node::Clone ( Skeleton skeleton) const

Clone the node.

Parameters
skeletonThe skeleton that the cloned node will be part of, you still need to manually add it to this skeleton though.
Returns
The cloned node.

◆ Create() [1/2]

static Node * EMotionFX::Node::Create ( const char *  name,
Skeleton skeleton 
)
static

Create method.

Parameters
nameThe name of the node.
skeletonThe skeleton where this node will belong to, you still need to manually add it to the skeleton though.

◆ Create() [2/2]

static Node * EMotionFX::Node::Create ( uint32  nameID,
Skeleton skeleton 
)
static

Create method using a name ID.

Parameters
nameIDThe name ID, generated using the MCore::GetStringIdPool().
skeletonThe skeleton where this node will belong to, you still need to manually add it to the skeleton though.

◆ FindAttributeNumber()

size_t EMotionFX::Node::FindAttributeNumber ( uint32  attributeTypeID) const

Find the node attribute number of a given type. When there are no node attributes, or there is no attribute of the specified type this method will return MCORE_INVALIDINDEX32.

Parameters
attributeTypeIDThe attribute type ID (returned by NodeAttribute::GetType()).
Returns
The first located attribute number which is of the given type, or MCORE_INVALIDINDEX32 when the attribute of this type could not be located.

◆ FindRoot()

Node * EMotionFX::Node::FindRoot ( ) const

Find the root node in the hierarchy.

Returns
A pointer to the root node (can point to itself).

◆ GetAttribute()

NodeAttribute * EMotionFX::Node::GetAttribute ( size_t  attributeNr)

Get a given node attribute. You will need to typecast to the correct type of the attribute yourself. You can get the attribute type by using the NodeAttribute::GetType() method.

Parameters
attributeNrThe attribute number to get from the node. You can find the attribute number when you have the attribute type by using the FindAttributeNumber() method.
Returns
A pointer to the node attribute.
See also
FindNodeAttributeNumber

◆ GetAttributeByType()

NodeAttribute * EMotionFX::Node::GetAttributeByType ( uint32  attributeType)

Get a given node attribute of a given type. The method will return nullptr when no attribute of the specified type could be found.

Returns
A pointer to the node attribute, or nullptr when not found.

◆ GetChildIndex()

MCORE_INLINE size_t EMotionFX::Node::GetChildIndex ( size_t  nr) const
inline

Get a given child's node index.

Parameters
nrThe child number.
Returns
The index of the child node, which is a node number inside the actor.

◆ GetHasChildNodes()

bool EMotionFX::Node::GetHasChildNodes ( ) const

Check if this node has any child nodes.

Returns
Returns true when this node has child nodes, otherwise false is returned.

◆ GetID()

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

Get the unique ID of this node, which has been generated based on the name. You are guaranteed that nodes having the same name have the same ID. This means you can do fast compares between nodes by using the ID instead of a comparison between the node names. However, ever time you run the application, the ID values for given names can be different. So if you run your program, the node with name "Arm" might have an ID of 10. While next time you run the program this node might have an ID of for example 36. Still it is guaranteed that every time you run your program all nodes with the name "Arm" will have the same ID number.

Returns
The node ID number, which can be used for fast compares between nodes.

◆ GetIncludeInBoundsCalc()

MCORE_INLINE bool EMotionFX::Node::GetIncludeInBoundsCalc ( ) const
inline

Check whether this node is included inside the bounding volume calculations or not. Sometimes it is useful to disable some nodes from the bounding volume calculation. Examples of these are nodes that are lights or cameras, or nodes that just always stay at the origin, while your character moves away from the origin without motion based actor repositioning. On default all nodes are included inside the bounding volume calculations.

Returns
Returns true when this node will be included in the bounds calculation, or false when it won't.

◆ GetIsAttachmentNode()

bool EMotionFX::Node::GetIsAttachmentNode ( ) const

Check if the node is an attachment node.

Returns
True if the node is an attachment node, false if not.

◆ GetIsCritical()

MCORE_INLINE bool EMotionFX::Node::GetIsCritical ( ) const
inline

Check whether this node is critcal and should not be optimized out in any situations. Sometimes we perform optimization process on the node. This flag make sure that critical node will always be included in the actor heirarchy.

Returns
Returns true when this node is critical, or false when it won't.

◆ GetIsRootNode()

bool EMotionFX::Node::GetIsRootNode ( ) const

Check if this node is a root node. A node is seen as root node when it has no parent. So if Node::GetParentNode() equals nullptr we are dealing with a root node.

Returns
Returns true when this node is a root node, otherwise false is returned.

◆ GetName()

const char * EMotionFX::Node::GetName ( ) const

Gets the name of the node in form of a C character buffer.

Returns
A pointer to the null terminated buffer, containing the name of the node.

◆ GetNameString()

const AZStd::string & EMotionFX::Node::GetNameString ( ) const

Gets the name of the node in form of String object.

Returns
The string containing the node name.

◆ GetNodeIndex()

MCORE_INLINE size_t EMotionFX::Node::GetNodeIndex ( ) const
inline

Get the node index value. This is the index inside the array of nodes inside the Actor. So Actor::GetNode( nodeIndex ) will return this node.

Returns
The index of the node.

◆ GetNumAttributes()

size_t EMotionFX::Node::GetNumAttributes ( ) const

Get the number of node attributes.

Returns
The number of node attributes for this node.

◆ GetNumChildNodes()

MCORE_INLINE size_t EMotionFX::Node::GetNumChildNodes ( ) const
inline

Get the number of child nodes attached to this node.

Returns
The number of child nodes.

◆ GetNumChildNodesRecursive()

size_t EMotionFX::Node::GetNumChildNodesRecursive ( ) const

Get the number of child nodes down the hierarchy of this node. The current node is not included in the count.

Returns
The total number of nodes down the hierarchy of this node.

◆ GetParentIndex()

MCORE_INLINE size_t EMotionFX::Node::GetParentIndex ( ) const
inline

Get the parent node's index. This is either a valid index, or MCORE_INVALIDINDEX32 in case there is no parent node.

Returns
The index of the parent node, or MCORE_INVALIDINDEX32 in case this node has no parent.

◆ GetParentNode()

Node * EMotionFX::Node::GetParentNode ( ) const

Get the parent node as node pointer.

Returns
Returns the pointer to the parent node, or nullptr in case there is no parent.

◆ GetSemanticID()

MCORE_INLINE uint32 EMotionFX::Node::GetSemanticID ( ) const
inline

Get the semantic name ID. To get the name you can also use GetSemanticName() and GetSemanticNameString().

Returns
The semantic name ID.

◆ GetSemanticName()

const char * EMotionFX::Node::GetSemanticName ( ) const

Gets the semantic name.

Returns
A pointer to the null terminated buffer, containing the semantic name of the node.

◆ GetSemanticNameString()

const AZStd::string & EMotionFX::Node::GetSemanticNameString ( ) const

Gets the semantic name as string.

Returns
The string containing the semantic name.

◆ GetSkeletalLODStatus()

MCORE_INLINE bool EMotionFX::Node::GetSkeletalLODStatus ( size_t  lodLevel) const
inline

Get the skeletal LOD status for this node at a given skeletal LOD.

Parameters
lodLevelThe skeletal LOD level to check.
Returns
Returns true when this node is enabled in the specified LOD level. Otherwise false is returned.

◆ PreAllocNumChildNodes()

void EMotionFX::Node::PreAllocNumChildNodes ( size_t  numChildNodes)

Preallocate the array of child nodes. Unlike SetNumChildNodes, this will NOT grow the child node array as reported by GetNumChildNodes(). However, it internally pre-allocates memory to make the AddChild() calls faster.

Parameters
numChildNodesThe number of child nodes to pre-allocate space for.

◆ RecursiveCollectParents()

void EMotionFX::Node::RecursiveCollectParents ( AZStd::vector< size_t > &  parents,
bool  clearParentsArray = true 
) const

Recursively go through the parents until a root node is reached and store all parents inside an array.

Parameters
parentsThe array to which parent and the parents of the parents of the node will be added.
clearParentsArrayWhen true the given parents array will be cleared before filling it.

◆ RemoveAllAttributes()

void EMotionFX::Node::RemoveAllAttributes ( )

Removes all node attributes from this node. The previously allocated attributes will be deleted from memory automatically.

◆ RemoveAllAttributesByType()

size_t EMotionFX::Node::RemoveAllAttributesByType ( uint32  attributeTypeID)

Removes all node attributes from this node of the given type.

Parameters
attributeTypeIDThe attribute type ID (returned by NodeAttribute::GetType()).
Returns
The number of attributes that have been removed.

◆ RemoveAllChildNodes()

void EMotionFX::Node::RemoveAllChildNodes ( )

Removes all child nodes (not from memory though but just clears the childs pointers in this node). Beware, the child nodes will still point to this node after executing this method! So you have to adjust their parent indices manually.

◆ RemoveAttribute()

void EMotionFX::Node::RemoveAttribute ( size_t  index)

Remove the given node attribute from this node.

Parameters
indexThe index of the node attribute to remove.

◆ RemoveAttributeByType()

void EMotionFX::Node::RemoveAttributeByType ( uint32  attributeTypeID,
size_t  occurrence = 0 
)

Remove the given node attribute from this node which occurs at the given position. If the given occurrence is bigger than the number of actual attributes inside the node no node attribute will be removed.

Parameters
attributeTypeIDThe attribute type ID (returned by NodeAttribute::GetType()).
occurrenceThe number of node attributes which will be skipped until we reached the node to remove.

◆ RemoveChild()

void EMotionFX::Node::RemoveChild ( size_t  nodeIndex)

Removes a given child (does not delete it from memory though). Beware, the child node will still point to this node after executing this method! So you have to adjust the parent pointer of the child node manually.

Parameters
nodeIndexThe index of the child to remove.

◆ SetChild()

void EMotionFX::Node::SetChild ( size_t  childNr,
size_t  childNodeIndex 
)

Set the value for a given child node.

Parameters
childNrThe child number, which must be in range of [0..GetNumChildNodes()-1].
childNodeIndexThe node index for this child.

◆ SetIncludeInBoundsCalc()

void EMotionFX::Node::SetIncludeInBoundsCalc ( bool  includeThisNode)

Specify whether this node should be included inside the bounding volume calculations or not. Sometimes it is useful to disable some nodes from the bounding volume calculation. Examples of these are nodes that are lights or cameras, or nodes that just always stay at the origin, while your character moves away from the origin without motion based actor repositioning. On default all nodes are included inside the bounding volume calculations.

Parameters
includeThisNodeSet to true when you want this node to be included in the bounds calculation, or set to false when it should be excluded.

◆ SetIsAttachmentNode()

void EMotionFX::Node::SetIsAttachmentNode ( bool  isAttachmentNode)

Set if the node is an attachment node.

Returns
True if the node is an attachment node, false if not.

◆ SetIsCritical()

void EMotionFX::Node::SetIsCritical ( bool  isCritical)

Specify whether this node is critcal and should not be optimized out in any situations.

Parameters
isCriticalSet to true when you want this node to be critical.

◆ SetName()

void EMotionFX::Node::SetName ( const char *  name)

Set the node name.

Parameters
nameThe new node name, which should be unique.

◆ SetNodeIndex()

void EMotionFX::Node::SetNodeIndex ( size_t  index)

Set the node index for this node. This has to be the index inside the array of nodes inside the Actor. So Actor::GetNode( nodeIndex ) will return this node.

Parameters
indexThe index to use.

◆ SetNumChildNodes()

void EMotionFX::Node::SetNumChildNodes ( size_t  numChildNodes)

Resize the array of child nodes. This will grow the child node array so that the value returned by GetNumChildNodes() will return the same value as you specify as parameter here.

Parameters
numChildNodesThe number of child nodes to create. Be sure to initialize all of the child nodes using SetChild() though!

◆ SetParentIndex()

void EMotionFX::Node::SetParentIndex ( size_t  parentNodeIndex)

Set the parent node index. When this is set to MCORE_INVALIDINDEX32 then this is considered as no parent. In that case this node is a root node.

Parameters
parentNodeIndexThe node index of the node where to link this node to.

◆ SetSemanticName()

void EMotionFX::Node::SetSemanticName ( const char *  name)

Set the semantic name.

Parameters
nameThe new node name, which should be unique.

◆ SetSkeletalLODLevelBits()

void EMotionFX::Node::SetSkeletalLODLevelBits ( size_t  bitValues)

Set the skeletal LOD status for all LOD levels. Each bit specifies whether this node is active in a given LOD or not. Bit 0 represents LOD 0, bit 1 represents LOD 1, etc.

Parameters
bitValuesThe unsigned 32-bits integer that contains the settings for each LOD.

◆ SetSkeletalLODStatus()

void EMotionFX::Node::SetSkeletalLODStatus ( size_t  lodLevel,
bool  enabled 
)

Set the skeletal LOD status for a given LOD level. This enables or disables the node entirely from all calculations inside EMotion FX. It is important to know that the nodes that you disable should not be used anywhere inside skinning information of meshes or other places where there transformations are needed. There are 32 possible LOD levels. On default all nodes are enabled in a given LOD that hasn't been initialized.

Parameters
lodLevelThe skeletal LOD level to change the settings for. This must be in range of [0..31].
enabledSet to true when you wish the node to be enabled in the given LOD, or false when you wish to disable it in the given LOD.

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