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::NodeGroup Class Reference

#include <NodeGroup.h>

Public Member Functions

AZ_CLASS_ALLOCATOR_DECL NodeGroup (const AZStd::string &groupName={}, size_t numNodes=0, bool enabledOnDefault=true)
 
 NodeGroup (const NodeGroup &aOther)
 
NodeGroupoperator= (const NodeGroup &aOther)
 
void SetName (const AZStd::string &groupName)
 
const char * GetName () const
 
const AZStd::string & GetNameString () const
 
void SetNumNodes (size_t numNodes)
 
size_t GetNumNodes () const
 
void SetNode (size_t index, uint16 nodeIndex)
 
uint16 GetNode (size_t index) const
 
void EnableNodes (ActorInstance *targetActorInstance)
 
void DisableNodes (ActorInstance *targetActorInstance)
 
void AddNode (uint16 nodeIndex)
 
void RemoveNodeByNodeIndex (uint16 nodeIndex)
 
void RemoveNodeByGroupIndex (size_t index)
 
AZStd::vector< uint16 > & GetNodeArray ()
 
bool GetIsEnabledOnDefault () const
 
void SetIsEnabledOnDefault (bool enabledOnDefault)
 

Detailed Description

A node group like the name already says is a group that contains a list of nodes. The group contains a list of node numbers, which index inside the actor where the groups belong to. It is possible to enable and disable individual groups. Disabling a group will skip all calculations done on the nodes that are inside the group. You can enable and disable individual groups per ActorInstance object. Skipped calculations include the calculation of local space matrices, forward kinematics to calculate world space matrices and blending. It is important that you do not use the nodes that are disabled. For example if a given node is disabled and you try to get its transformation, then this transformation might contain incorrect or even uninitialized data.

Member Function Documentation

◆ AddNode()

void EMotionFX::NodeGroup::AddNode ( uint16  nodeIndex)

Add a given node to this group. Please keep in mind that performing an AddNode will result in a reallocation being done. It is much better to use SetNumNodes(...) in combination with SetNode(...) upfront if the total number of nodes is known upfront.

Parameters
nodeIndexThe node index which points inside the Actor object where this group will be added to. This relates to the node returned by Actor::GetNode( nodeIndex ).

◆ DisableNodes()

void EMotionFX::NodeGroup::DisableNodes ( ActorInstance targetActorInstance)

Disable all nodes that remain inside this group, for a given actor instance. The reason why you specify an ActorInstance as parameter is because the node groups are stored inside the Actor objects, while you can enable and disable nodes individually per ActorInstance. Nodes that are enabled will be processed by fully inside the EMotion FX pipeline. This includes things like motion sampling, local space matrix construction, world space transformation calculations and blending operations. Disabled nodes will skip those calculations.

Parameters
targetActorInstanceThe actor instance object in which we will enable all the nodes that are inside this group.

◆ EnableNodes()

void EMotionFX::NodeGroup::EnableNodes ( ActorInstance targetActorInstance)

Enable all nodes that remain inside this group, for a given actor instance. The reason why you specify an ActorInstance as parameter is because the node groups are stored inside the Actor objects, while you can enable and disable nodes individually per ActorInstance. Nodes that are enabled will be processed by fully inside the EMotion FX pipeline. This includes things like motion sampling, local space matrix construction, world space transformation calculations and blending operations. Disabled nodes will skip those calculations.

Parameters
targetActorInstanceThe actor instance object in which we will enable all the nodes that are inside this group.

◆ GetIsEnabledOnDefault()

bool EMotionFX::NodeGroup::GetIsEnabledOnDefault ( ) const

Check whether this group is enabled after actor instance creation time. If the group is enabled, it means that all nodes inside this group will be enabled once an actor instance is created. When this is set to false, all nodes inside the group will be disabled on default. It is possible however that another group enables or disables specific nodes that are also inside this group again, if a node is in multiple groups. &

Returns
Returns true when all nodes inside this group will be in an enabled state when creating a new actor instance using this group. Otherwise false is returned.

◆ GetName()

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

Get the name of the group as null terminated character buffer.

Returns
The name of the group.

◆ GetNameString()

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

Get the name of the group, in form of a AZStd::string object.

Returns
The name as a reference to a AZStd::string object.

◆ GetNode()

uint16 EMotionFX::NodeGroup::GetNode ( size_t  index) const

Get the node index for a given node inside the group.

Parameters
indexThe node number inside this group, which must be in range of [0..GetNumNodes()-1].
Returns
The node number, which points inside the Actor object. Use Actor::GetNode( returnValue ) to get access to the node information.

◆ GetNodeArray()

AZStd::vector< uint16 > & EMotionFX::NodeGroup::GetNodeArray ( )

Get direct access to the array of node indices that are part of this group.

Returns
A reference to the array of nodes inside this group. Please use this with care.

◆ GetNumNodes()

size_t EMotionFX::NodeGroup::GetNumNodes ( ) const

Get the number of nodes that remain inside this group.

Returns
The number of nodes inside this group.

◆ RemoveNodeByGroupIndex()

void EMotionFX::NodeGroup::RemoveNodeByGroupIndex ( size_t  index)

Remove a given node from the group by the array element index. If for example you wish to remove the 3rd node from the group, you can call RemoveNodeByGroupIndex( 2 ). If you wish to remove a node by its node number, then use RemoveNodeByNodeIndex(...) instead.

Parameters
indexThe node index in the group. So for example an index value of 5 will remove the sixth node from the group. The index value must be in range of [0..GetNumNodes() - 1].

◆ RemoveNodeByNodeIndex()

void EMotionFX::NodeGroup::RemoveNodeByNodeIndex ( uint16  nodeIndex)

Remove a given node from the group by its node number (the value returned by GetNode(...). If you wish to remove for example the 3rd node inside this group, then use RemoveNodeByGroupIndex(...) instead. Removing a node index which is not part of this group will do nothing, except that it wastes performance as it will perform a search inside the list of nodes inside this group.

Parameters
nodeIndexThe node number to remove. This value related to Actor::GetNode( nodeIndex ).

◆ SetIsEnabledOnDefault()

void EMotionFX::NodeGroup::SetIsEnabledOnDefault ( bool  enabledOnDefault)

Set whether this group is enabled after actor creation time or not. If the group is enabled, it means that all nodes inside this group will be enabled once an actor instance is created. When this is set to false, all nodes inside the group will be disabled on default. It is possible however that another group enables or disables specific nodes that are also inside this group again, if a node is in multiple groups. &

Returns
Returns true when all nodes inside this group will be in an enabled state when creating a new actor instance using this group. Otherwise false is returned.

◆ SetName()

void EMotionFX::NodeGroup::SetName ( const AZStd::string &  groupName)

Set the name of the group. Please keep in mind that group names must be unique inside the Actor objects. So you should not have two or more groups with the same name.

Parameters
groupNameThe name of the group.

◆ SetNode()

void EMotionFX::NodeGroup::SetNode ( size_t  index,
uint16  nodeIndex 
)

Set the value of a given node.

Parameters
indexThe node number inside this group, which must be in range of [0..GetNumNodes()-1].
nodeIndexThe value for the given node. This is the node index which points inside the Actor object where this group will belong to. To get access to the actual node object use Actor::GetNode( nodeIndex ).

◆ SetNumNodes()

void EMotionFX::NodeGroup::SetNumNodes ( size_t  numNodes)

Set the number of nodes that remain inside this group. This will resize the array of node indices. Don't forget to initialize the node values after increasing the number of nodes though.

Parameters
numNodesThe number of nodes that are inside this group.

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