Facial Expression

APIs for facial expression. More...

Classes

	Name
struct	MLFacialExpressionEyeData A structure containing information about facial expressions. This structure must be initialized by calling MLFacialExpressionEyeDataInit before use.
struct	MLFacialExpressionSettings A structure containing settings for the facial expressions. This structure must be initialized by calling MLFacialExpressionSettingsInit before use.

Types

	Name
typedef struct MLFacialExpressionEyeData	MLFacialExpressionEyeData A structure containing information about facial expressions. This structure must be initialized by calling MLFacialExpressionEyeDataInit before use.
typedef struct MLFacialExpressionSettings	MLFacialExpressionSettings A structure containing settings for the facial expressions. This structure must be initialized by calling MLFacialExpressionSettingsInit before use.

Enums

	Name
enum	Anonymous Enum 9 { MLResultAPIPrefix_FacialExpression = ( 0x18cd << 16) }
enum	MLFacialExpressionResult { MLFacialExpressionResult_HeadsetFitIssue = MLResultAPIPrefix_FacialExpression, MLFacialExpressionResult_EyeExpressionDisabled, MLFacialExpressionResult_Ensure32Bits = 0x7FFFFFFF } Facial expression specific return codes.
enum	MLFacialExpressionEyeExpressionType { MLFacialExpressionEyeExpressionType_Blink_Left = 0, MLFacialExpressionEyeExpressionType_Blink_Right = 1, MLFacialExpressionEyeExpressionType_Lid_Tightener_Left = 2, MLFacialExpressionEyeExpressionType_Lid_Tightener_Right = 3, MLFacialExpressionEyeExpressionType_Eye_Openness_Left = 4, MLFacialExpressionEyeExpressionType_Eye_Openness_Right = 5, MLFacialExpressionEyeExpressionType_Cheek_Raiser_Left = 6, MLFacialExpressionEyeExpressionType_Cheek_Raiser_Right = 7, MLFacialExpressionEyeExpressionType_Brow_Lowerer_Left = 8, MLFacialExpressionEyeExpressionType_Brow_Lowerer_Right = 9, MLFacialExpressionEyeExpressionType_Brow_Raiser_Left = 10, MLFacialExpressionEyeExpressionType_Brow_Raiser_Right = 11, MLFacialExpressionEyeExpressionType_Count = 12, MLFacialExpressionEyeExpressionType_Ensure32Bits = 0x7FFFFFFF } Available facial expressions.

Functions

	Name
void	MLFacialExpressionEyeDataInit(MLFacialExpressionEyeData * inout_eye_data) Initializes default values for MLFacialExpressionEyeData.
void	MLFacialExpressionSettingsInit(MLFacialExpressionSettings * inout_settings) Initializes default values for MLFacialExpressionSettings.
const char *	MLFacialExpressionGetResultString(MLResult result) Returns an ASCII string for MLFacialExpressionResult and MLResult codes.
MLResult	MLFacialExpressionCreateClient(const MLFacialExpressionSettings settings, MLHandle out_handle) Creates a Facial expression client handle.
MLResult	MLFacialExpressionUpdateSettings(MLHandle handle, const MLFacialExpressionSettings * settings) Update the Facial expression system with new settings.
MLResult	MLFacialExpressionGetEyeData(MLHandle handle, MLFacialExpressionEyeData * out_eye_data) Get facial expressions data.
MLResult	MLFacialExpressionDestroyClient(MLHandle handle) Destroy client handle and free client resources.

Detailed Description

APIs for facial expression.

Avatar animation is the primary purpose for the API. Currently the API will produce symmetrical eye expression data (e.g. blinks). In the subsequent OS releases asymmetrical eye expressions like winks will be supported.

Shared Object:

• perception.magicleap*

---

Enums Documentation

Anonymous Enum 9

Enumerator	Value	Description
MLResultAPIPrefix_FacialExpression	( 0x18cd << 16)	Defines the prefix for MLFacialExpressionResult codes.

---

MLFacialExpressionResult

Enumerator	Value	Description
MLFacialExpressionResult_HeadsetFitIssue	MLResultAPIPrefix_FacialExpression	Unable to detect the eyes, check MLHeadsetFitStatus.
MLFacialExpressionResult_EyeExpressionDisabled		Operation failed because enable_eye_expression in MLFacialExpressionSettings is disabled.
MLFacialExpressionResult_Ensure32Bits	0x7FFFFFFF	Ensure enum is represented as 32 bits.

Facial expression specific return codes.

API Level:

• 29

---

MLFacialExpressionEyeExpressionType

Enumerator	Value	Description
MLFacialExpressionEyeExpressionType_Blink_Left	0	Blinking the left eye.
MLFacialExpressionEyeExpressionType_Blink_Right	1	Blinking the right eye.
MLFacialExpressionEyeExpressionType_Lid_Tightener_Left	2	Lower Lid upward movement of the left eye.
MLFacialExpressionEyeExpressionType_Lid_Tightener_Right	3	Lower Lid upward movement of the right eye.
MLFacialExpressionEyeExpressionType_Eye_Openness_Left	4	Upper lid upward movement of the left eye.
MLFacialExpressionEyeExpressionType_Eye_Openness_Right	5	Upper lid upward movement of the right eye.
MLFacialExpressionEyeExpressionType_Cheek_Raiser_Left	6	Upward cheek movement, left.
MLFacialExpressionEyeExpressionType_Cheek_Raiser_Right	7	Upward cheek movement, right.
MLFacialExpressionEyeExpressionType_Brow_Lowerer_Left	8	Downward brow movement, left.
MLFacialExpressionEyeExpressionType_Brow_Lowerer_Right	9	Downward brow movement, right.
MLFacialExpressionEyeExpressionType_Brow_Raiser_Left	10	Upward brow movement, left side.
MLFacialExpressionEyeExpressionType_Brow_Raiser_Right	11	Upward brow movement, right side.
MLFacialExpressionEyeExpressionType_Count	12	Number of eye expression types.
MLFacialExpressionEyeExpressionType_Ensure32Bits	0x7FFFFFFF	Ensure enum is represented as 32 bits.

Available facial expressions.

API Level:

• 29

---

Types Documentation

MLFacialExpressionEyeData

typedef struct MLFacialExpressionEyeData MLFacialExpressionEyeData;

A structure containing information about facial expressions. This structure must be initialized by calling MLFacialExpressionEyeDataInit before use.

More Info

API Level:

• 29

---

MLFacialExpressionSettings

typedef struct MLFacialExpressionSettings MLFacialExpressionSettings;

A structure containing settings for the facial expressions. This structure must be initialized by calling MLFacialExpressionSettingsInit before use.

More Info

API Level:

• 29

---

Functions Documentation

MLFacialExpressionEyeDataInit

static inline void MLFacialExpressionEyeDataInit(
    MLFacialExpressionEyeData * inout_eye_data
)

Initializes default values for MLFacialExpressionEyeData.

Parameters

MLFacialExpressionEyeData *	inout_eye_data	The object to initialize with default values.

Required Permissions:

• None

API Level:

• 29

---

MLFacialExpressionSettingsInit

static inline void MLFacialExpressionSettingsInit(
    MLFacialExpressionSettings * inout_settings
)

Initializes default values for MLFacialExpressionSettings.

Parameters

MLFacialExpressionSettings *	inout_settings	The object to initialize with default values.

Required Permissions:

• None

API Level:

• 29

---

MLFacialExpressionGetResultString

const char * MLFacialExpressionGetResultString(
    MLResult result
)

Returns an ASCII string for MLFacialExpressionResult and MLResult codes.

Parameters

MLResult	result	The input MLResult enum from MLFacialExpression functions.

Required Permissions:

• None

Return: ASCII string containing readable version of result code.

API Level:

• 29

---

MLFacialExpressionCreateClient

MLResult MLFacialExpressionCreateClient(
    const MLFacialExpressionSettings * settings,
    MLHandle * out_handle
)

Creates a Facial expression client handle.

Parameters

const MLFacialExpressionSettings *	settings	Settings that configures the facial expressions system.
MLHandle *	out_handle	The handle to be created.

Returns

MLResult	MLResult_InvalidParam	One or more input parameters are not valid.
MLResult	MLResult_Ok	Facial expression client was created successfully.
MLResult	MLResult_PerceptionSystemNotStarted	Perception System has not been started.
MLResult	MLResult_PermissionDenied	Necessary permission is missing.
MLResult	MLResult_UnspecifiedFailure	Operation failed for unknown reason.

Required Permissions:

• com.magicleap.permission.FACIAL_EXPRESSION (protection level: dangerous)

Although multiple client handles can be created they all represent the same facial expressions backend system.

API Level:

• 29

---

MLFacialExpressionUpdateSettings

MLResult MLFacialExpressionUpdateSettings(
    MLHandle handle,
    const MLFacialExpressionSettings * settings
)

Update the Facial expression system with new settings.

Parameters

MLHandle	handle	Facial expression client handle created by MLFacialExpressionCreateClient.
const MLFacialExpressionSettings *	settings	New Facial expression settings.

Returns

MLResult	MLResult_InvalidParam	One or more input parameters are not valid.
MLResult	MLResult_Ok	Facial expression settings was updated successfully.
MLResult	MLResult_PerceptionSystemNotStarted	Perception System has not been started.
MLResult	MLResult_UnspecifiedFailure	Operation failed for unknown reason.

Required Permissions:

• None

API Level:

• 29

---

MLFacialExpressionGetEyeData

MLResult MLFacialExpressionGetEyeData(
    MLHandle handle,
    MLFacialExpressionEyeData * out_eye_data
)

Get facial expressions data.

Parameters

MLHandle	handle	Facial expression client handle created by MLFacialExpressionCreateClient.
MLFacialExpressionEyeData *	out_eye_data	Eye expressions data.

Returns

MLResult	MLResult_InvalidParam	One or more input parameters are not valid.
MLResult	MLResult_Ok	Facial expression data was retrieved successfully.
MLResult	MLResult_PerceptionSystemNotStarted	Perception System has not been started.
MLResult	MLResult_UnspecifiedFailure	Operation failed for unknown reason.
MLResult	MLFacialExpressionResult_HeadsetFitIssue	Operation failed because unable to detect the eyes, check MLHeadsetFitStatus.

Required Permissions:

• None

API Level:

• 29

---

MLFacialExpressionDestroyClient

MLResult MLFacialExpressionDestroyClient(
    MLHandle handle
)

Destroy client handle and free client resources.

Parameters

MLHandle	handle	Facial expression client handle created by MLFacialExpressionCreateClient.

Returns

MLResult	MLResult_InvalidParam	One or more input parameters are not valid.
MLResult	MLResult_Ok	Client handle was successfully destroyed.
MLResult	MLResult_PerceptionSystemNotStarted	Perception System has not been started.
MLResult	MLResult_UnspecifiedFailure	Operation failed for unknown reason.

Required Permissions:

• None

API Level:

• 29

---