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::MorphTarget Class Referenceabstract

#include <MorphTarget.h>

Inherits EMotionFX::BaseObject.

Inherited by EMotionFX::MorphTargetStandard.

Public Types

enum  EPhonemeSet {
  PHONEMESET_NONE = 0 , PHONEMESET_NEUTRAL_POSE = 1 << 0 , PHONEMESET_M_B_P_X = 1 << 1 , PHONEMESET_AA_AO_OW = 1 << 2 ,
  PHONEMESET_IH_AE_AH_EY_AY_H = 1 << 3 , PHONEMESET_AW = 1 << 4 , PHONEMESET_N_NG_CH_J_DH_D_G_T_K_Z_ZH_TH_S_SH = 1 << 5 , PHONEMESET_IY_EH_Y = 1 << 6 ,
  PHONEMESET_UW_UH_OY = 1 << 7 , PHONEMESET_F_V = 1 << 8 , PHONEMESET_L_EL = 1 << 9 , PHONEMESET_W = 1 << 10 ,
  PHONEMESET_R_ER = 1 << 11
}
 

Public Member Functions

virtual void ApplyTransformation (ActorInstance *actorInstance, size_t nodeIndex, AZ::Vector3 &position, AZ::Quaternion &rotation, AZ::Vector3 &scale, float weight)=0
 
MCORE_INLINE uint32 GetID () const
 
const char * GetName () const
 
const AZStd::string & GetNameString () const
 
void SetRangeMin (float rangeMin)
 
void SetRangeMax (float rangeMax)
 
float GetRangeMin () const
 
float GetRangeMax () const
 
virtual uint32 GetType () const =0
 
void SetName (const char *name)
 
void SetPhonemeSets (EPhonemeSet phonemeSets)
 
EPhonemeSet GetPhonemeSets () const
 
void EnablePhonemeSet (EPhonemeSet set, bool enabled)
 
bool GetIsPhonemeSetEnabled (EPhonemeSet set) const
 
virtual void InitFromPose (bool captureTransforms, Actor *neutralPose, Actor *targetPose)=0
 
virtual bool Influences (size_t nodeIndex) const =0
 
float CalcRangedWeight (float weight) const
 
float CalcZeroInfluenceWeight () const
 
float CalcNormalizedWeight (float rangedWeight) const
 
bool GetIsPhoneme () const
 
virtual void Apply (ActorInstance *actorInstance, float weight)=0
 
virtual MorphTargetClone () const =0
 
void CopyBaseClassMemberValues (MorphTarget *target) const
 
virtual void Scale (float scaleFactor)=0
 
- 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 EPhonemeSet FindPhonemeSet (const AZStd::string &phonemeName)
 
static AZStd::string GetPhonemeSetString (const EPhonemeSet phonemeSet)
 
static uint32 GetNumAvailablePhonemeSets ()
 

Protected Member Functions

 MorphTarget (const char *name)
 
- Protected Member Functions inherited from EMotionFX::BaseObject
void Delete () override
 
virtual void Delete ()
 

Protected Attributes

uint32 m_nameId
 
float m_rangeMin
 
float m_rangeMax
 
EPhonemeSet m_phonemeSets
 

Detailed Description

The morph target base class. Morph targets apply additive modifications to nodes or meshes or anything else.

Member Enumeration Documentation

◆ EPhonemeSet

The phoneme sets, used for lip-sync. If you modify this enum, be sure to also modify the value returned by: MorphTarget::GetNumAvailablePhonemeSets().

Constructor & Destructor Documentation

◆ MorphTarget()

EMotionFX::MorphTarget::MorphTarget ( const char *  name)
protected

The constructor.

Parameters
nameThe unique name of the morph target.

Member Function Documentation

◆ Apply()

virtual void EMotionFX::MorphTarget::Apply ( ActorInstance actorInstance,
float  weight 
)
pure virtual

Apply the relative deformations for this morph target to the given actor instance.

Parameters
actorInstanceThe actor instance to apply the deformations on.
weightThe absolute weight of the morph target.

Implemented in EMotionFX::MorphTargetStandard.

◆ ApplyTransformation()

virtual void EMotionFX::MorphTarget::ApplyTransformation ( ActorInstance actorInstance,
size_t  nodeIndex,
AZ::Vector3 &  position,
AZ::Quaternion &  rotation,
AZ::Vector3 &  scale,
float  weight 
)
pure virtual

Apply a transformation to the given position, rotation and scale, on such a way that this morph target adjusts the given transformation data. On this way we can accumulate the effects of different morph targets to the same node.

Parameters
actorInstanceThe actor instance to apply the transform to.
nodeIndexThe node where the given transform info belongs to, so the node which we are adjusting. However the node itself will not be modified by this method.
positionThis must contain the initial position, and will be modified inside this method as well.
rotationThis must contain the initial rotation, and will be modified inside this method as well.
scaleThis must contain the initial scale, and will be modified inside this method as well.
weightThe absolute weight value.

Implemented in EMotionFX::MorphTargetStandard.

◆ CalcNormalizedWeight()

float EMotionFX::MorphTarget::CalcNormalizedWeight ( float  rangedWeight) const

Calculate a normalized weight, in range of [0..1], based on the current weight, and the currently setup min and max range of the morph target.

Parameters
rangedWeightThe weight, which is in range of [minRange..maxRange].
Returns
The weight value in range of [0..1].

◆ CalcRangedWeight()

float EMotionFX::MorphTarget::CalcRangedWeight ( float  weight) const

Calculate the range based weight value from a normalized weight value given by a facial animation key frame.

Parameters
weightThe normalized weight value, which must be in range of [0..1].
Returns
The weight value to be used in calculations. The returned value will be in range of [GetRangeMin()..GetRangeMax()]

◆ CalcZeroInfluenceWeight()

float EMotionFX::MorphTarget::CalcZeroInfluenceWeight ( ) const

Calculates the normalized weight value that is in range of [0..1], on which this morph target would have no influence. A normalized weight of zero doesn't mean that this morph target has no influence. It is possible that the minimum range value of the slider is for example -1, while the maximum range would be 1. In that case a weight value of 0, would mean a un-normalized (ranged) weight of -1. The normalized weight that has a ranged (unnormalized) weight of zero would be 0.5 in this case. This method calculates the normalized weight value that is in range of [0..1] which would result in a ranged (un-normalized) weight of zero.

Returns
The normalized weight value that will result in a ranged weight of zero, which would mean no influence.

◆ Clone()

virtual MorphTarget * EMotionFX::MorphTarget::Clone ( ) const
pure virtual

Creates an exact clone of this morph target.

Returns
Returns a pointer to an exact clone of this morph target.

Implemented in EMotionFX::MorphTargetStandard.

◆ CopyBaseClassMemberValues()

void EMotionFX::MorphTarget::CopyBaseClassMemberValues ( MorphTarget target) const

Copy the morph target base class members over to another morph target. This can be used when implementing your own Clone method for your own morph target.

Parameters
targetThe morph target to copy the data from.

◆ EnablePhonemeSet()

void EMotionFX::MorphTarget::EnablePhonemeSet ( EPhonemeSet  set,
bool  enabled 
)

Link or unlink this morph target with a given phoneme set.

Parameters
setThe phoneme set to link or unlink this morph target with.
enabledSet to true to link it with the given set, or false to unlink it.

◆ FindPhonemeSet()

static EPhonemeSet EMotionFX::MorphTarget::FindPhonemeSet ( const AZStd::string &  phonemeName)
static

Convert the given phoneme name to a phoneme set. Searches all phoneme sets and checks if the passed phoneme name is part of a phoneme set.

Parameters
phonemeNameThe name of the phoneme (e.g. "UW", TH", "EY").
Returns
The corresponding phoneme set. If the phoneme set has not been found or if it is empty the PHONEMESET_NEUTRAL_POSE value will be returned.

◆ GetID()

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

Get the unique ID of this morph target. Just like in the Node class, the ID is generated based on the name (a string). Every string containing the same text will have the same ID. With this we can reduce from expensive name compares to simple integer compares.

Returns
The unique ID of the morph target.

◆ GetIsPhoneme()

bool EMotionFX::MorphTarget::GetIsPhoneme ( ) const

Check if this morph target acts as phoneme or not. A morph target is marked as phoneme if the phoneme set is set to something different than PHONEMESET_NONE. On default, after constructing the morph target, the value is set to PHONEMESET_NONE, which means that on default the morph target is not a phoneme.

Returns
Returns true if this morph target represents a phoneme, false is returned in the other case.

◆ GetIsPhonemeSetEnabled()

bool EMotionFX::MorphTarget::GetIsPhonemeSetEnabled ( EPhonemeSet  set) const

Check if this morph target represents a given phoneme set or not.

Returns
Returns true when this morph target represents the specified phoneme set. Otherwise false is returned.

◆ GetName()

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

Get the unique name of the morph target.

Returns
The name of the morph target.

◆ GetNameString()

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

Get the unique name of the morph target, in form of a AZStd::string object.

Returns
The name of the morph target.

◆ GetNumAvailablePhonemeSets()

static uint32 EMotionFX::MorphTarget::GetNumAvailablePhonemeSets ( )
static

Get the number of available phoneme sets inside the enum EPhonemeSet. The PHONEMESET_NONE enum value is not included in this amount.

Returns
Amount of available phoneme sets.

◆ GetPhonemeSets()

EPhonemeSet EMotionFX::MorphTarget::GetPhonemeSets ( ) const

Get the phoneme sets. This is used for lipsync generation. It allows us to link the visual representation of a phoneme with one detected in the audio file/stream.

Returns
The phoneme sets represented by this morph target.

◆ GetPhonemeSetString()

static AZStd::string EMotionFX::MorphTarget::GetPhonemeSetString ( const EPhonemeSet  phonemeSet)
static

Get the name of a phoneme set from the given phoneme set type. This is used to get phoneme morph targets names. NOTE: If this morph target represents multiple phoneme sets, it will be separated with a comma character. An example of a returned string: "PHONEMESET_L_EL,PHONEMESET_W".

Parameters
phonemeSetThe phoneme set value.
Returns
String describing the given phoneme set.

◆ GetRangeMax()

float EMotionFX::MorphTarget::GetRangeMax ( ) const

Get the maximum weight range value of this morph target. On default this value is one. For more information about what exactly this 'range' is, see the method SetRangeMin().

Returns
The maximum weight range value.
See also
SetRangeMin

◆ GetRangeMin()

float EMotionFX::MorphTarget::GetRangeMin ( ) const

Get the minimum weight range value of this morph target. On default this value is zero. For more information about what exactly this 'range' is, see the method SetRangeMin().

Returns
The minumim weight range value.
See also
SetRangeMin

◆ GetType()

virtual uint32 EMotionFX::MorphTarget::GetType ( ) const
pure virtual

Get the type of morph target. You can have different types of morph targets, such as morph targets which work with bones, or which work with morphing or other techniques.

Returns
The unique type ID of the morph target.

Implemented in EMotionFX::MorphTargetStandard.

◆ Influences()

virtual bool EMotionFX::MorphTarget::Influences ( size_t  nodeIndex) const
pure virtual

Checks if this morph target would influence a given node.

Parameters
nodeIndexThe node number to perform the check on.
Returns
Returns true if the given node will be modified by this morph target, otherwise false is returned.

Implemented in EMotionFX::MorphTargetStandard.

◆ InitFromPose()

virtual void EMotionFX::MorphTarget::InitFromPose ( bool  captureTransforms,
Actor neutralPose,
Actor targetPose 
)
pure virtual

Initializes this expresion part from a given actor representing the pose. The morph target will filter out all data which is changed compared to the base pose and store this information on a specific way so it can be used to accumulate multiple morph targets together and apply them to the actor to which this morph target is attached to.

Parameters
captureTransformsSet this to true if you want this morph target to capture rigid transformations (changes in pos/rot/scale).
neutralPoseThe actor that contains the neutral pose.
targetPoseThe actor representing the pose of the character when the weight value would equal 1.

Implemented in EMotionFX::MorphTargetStandard.

◆ Scale()

virtual void EMotionFX::MorphTarget::Scale ( float  scaleFactor)
pure virtual

Scale all transform and positional data. This is a very slow operation and is used to convert between different unit systems (cm, meters, etc).

Parameters
scaleFactorThe scale factor to scale the current data by.

Implemented in EMotionFX::MorphTargetStandard.

◆ SetName()

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

Change the name of the morph target. This will also automatically update the ID, which is returned by GetID().

Parameters
nameThe new name of the morph target.

◆ SetPhonemeSets()

void EMotionFX::MorphTarget::SetPhonemeSets ( EPhonemeSet  phonemeSets)

Set the phoneme sets. This is used for lipsync generation. It allows us to link the visual representation of a phoneme with one detected in the audio file/stream.

Parameters
phonemeSetsThe phoneme sets that this phoneme represents. This can be a combination of any of the phoneme sets in the enum.

◆ SetRangeMax()

void EMotionFX::MorphTarget::SetRangeMax ( float  rangeMax)

Set the maximum weight range value of this morph target. On default this value is one. For more information about what exactly this 'range' is, see the method SetRangeMin().

Parameters
rangeMaxThe maximum weight value.
See also
SetRangeMin

◆ SetRangeMin()

void EMotionFX::MorphTarget::SetRangeMin ( float  rangeMin)

Set the minimum weight range value of this morph target. On default this value is zero. The equations used are: new = current + delta * weight. Delta is the difference between the original pose and the pose passed to InitFromPose or the extended constructor. This means that normally the value for weight has a range of [0..1]. However, this can be changed. The range is used inside LM Studio only.

Parameters
rangeMinThe minimum weight value.

Member Data Documentation

◆ m_nameId

uint32 EMotionFX::MorphTarget::m_nameId
protected

The unique ID of the morph target, calculated from the name.

◆ m_phonemeSets

EPhonemeSet EMotionFX::MorphTarget::m_phonemeSets
protected

The phoneme sets in case this morph target is used as a phoneme.

◆ m_rangeMax

float EMotionFX::MorphTarget::m_rangeMax
protected

The maximum range of the weight.

◆ m_rangeMin

float EMotionFX::MorphTarget::m_rangeMin
protected

The minimum range of the weight.


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