Skip to main content
Version: 21 Aug 2024

Facial Expression

APIs for facial expression. More...

Classes

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

Types

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

Enums

Name
enumAnonymous Enum 9
{
MLResultAPIPrefix_FacialExpression = ( 0x18cd << 16)
}
enumMLFacialExpressionResult
{
MLFacialExpressionResult_HeadsetFitIssue = MLResultAPIPrefix_FacialExpression,
MLFacialExpressionResult_EyeExpressionDisabled,
MLFacialExpressionResult_Ensure32Bits = 0x7FFFFFFF
}
Facial expression specific return codes.
enumMLFacialExpressionEyeExpressionType
{
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
voidMLFacialExpressionEyeDataInit(MLFacialExpressionEyeData * inout_eye_data)
Initializes default values for MLFacialExpressionEyeData.
voidMLFacialExpressionSettingsInit(MLFacialExpressionSettings * inout_settings)
Initializes default values for MLFacialExpressionSettings.
const char *MLFacialExpressionGetResultString(MLResult result)
Returns an ASCII string for MLFacialExpressionResult and MLResult codes.
MLResultMLFacialExpressionCreateClient(const MLFacialExpressionSettings settings, MLHandle out_handle)
Creates a Facial expression client handle.
MLResultMLFacialExpressionUpdateSettings(MLHandle handle, const MLFacialExpressionSettings * settings)
Update the Facial expression system with new settings.
MLResultMLFacialExpressionGetEyeData(MLHandle handle, MLFacialExpressionEyeData * out_eye_data)
Get facial expressions data.
MLResultMLFacialExpressionDestroyClient(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

EnumeratorValueDescription
MLResultAPIPrefix_FacialExpression( 0x18cd << 16)Defines the prefix for MLFacialExpressionResult codes.

MLFacialExpressionResult

EnumeratorValueDescription
MLFacialExpressionResult_HeadsetFitIssueMLResultAPIPrefix_FacialExpressionUnable to detect the eyes, check MLHeadsetFitStatus.
MLFacialExpressionResult_EyeExpressionDisabledOperation failed because enable_eye_expression in MLFacialExpressionSettings is disabled.
MLFacialExpressionResult_Ensure32Bits0x7FFFFFFFEnsure enum is represented as 32 bits.

Facial expression specific return codes.

API Level:

  • 29

MLFacialExpressionEyeExpressionType

EnumeratorValueDescription
MLFacialExpressionEyeExpressionType_Blink_Left0Blinking the left eye.
MLFacialExpressionEyeExpressionType_Blink_Right1Blinking the right eye.
MLFacialExpressionEyeExpressionType_Lid_Tightener_Left2Lower Lid upward movement of the left eye.
MLFacialExpressionEyeExpressionType_Lid_Tightener_Right3Lower Lid upward movement of the right eye.
MLFacialExpressionEyeExpressionType_Eye_Openness_Left4Upper lid upward movement of the left eye.
MLFacialExpressionEyeExpressionType_Eye_Openness_Right5Upper lid upward movement of the right eye.
MLFacialExpressionEyeExpressionType_Cheek_Raiser_Left6Upward cheek movement, left.
MLFacialExpressionEyeExpressionType_Cheek_Raiser_Right7Upward cheek movement, right.
MLFacialExpressionEyeExpressionType_Brow_Lowerer_Left8Downward brow movement, left.
MLFacialExpressionEyeExpressionType_Brow_Lowerer_Right9Downward brow movement, right.
MLFacialExpressionEyeExpressionType_Brow_Raiser_Left10Upward brow movement, left side.
MLFacialExpressionEyeExpressionType_Brow_Raiser_Right11Upward brow movement, right side.
MLFacialExpressionEyeExpressionType_Count12Number of eye expression types.
MLFacialExpressionEyeExpressionType_Ensure32Bits0x7FFFFFFFEnsure 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_dataThe 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_settingsThe 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

MLResultresultThe 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 *settingsSettings that configures the facial expressions system.
MLHandle *out_handleThe handle to be created.

Returns

MLResultMLResult_InvalidParamOne or more input parameters are not valid.
MLResultMLResult_OkFacial expression client was created successfully.
MLResultMLResult_PerceptionSystemNotStartedPerception System has not been started.
MLResultMLResult_PermissionDeniedNecessary permission is missing.
MLResultMLResult_UnspecifiedFailureOperation 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

MLHandlehandleFacial expression client handle created by MLFacialExpressionCreateClient.
const MLFacialExpressionSettings *settingsNew Facial expression settings.

Returns

MLResultMLResult_InvalidParamOne or more input parameters are not valid.
MLResultMLResult_OkFacial expression settings was updated successfully.
MLResultMLResult_PerceptionSystemNotStartedPerception System has not been started.
MLResultMLResult_UnspecifiedFailureOperation failed for unknown reason.

Required Permissions:

  • None

API Level:

  • 29

MLFacialExpressionGetEyeData

MLResult MLFacialExpressionGetEyeData(
MLHandle handle,
MLFacialExpressionEyeData * out_eye_data
)

Get facial expressions data.

Parameters

MLHandlehandleFacial expression client handle created by MLFacialExpressionCreateClient.
MLFacialExpressionEyeData *out_eye_dataEye expressions data.

Returns

MLResultMLResult_InvalidParamOne or more input parameters are not valid.
MLResultMLResult_OkFacial expression data was retrieved successfully.
MLResultMLResult_PerceptionSystemNotStartedPerception System has not been started.
MLResultMLResult_UnspecifiedFailureOperation failed for unknown reason.
MLResultMLFacialExpressionResult_HeadsetFitIssueOperation 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

MLHandlehandleFacial expression client handle created by MLFacialExpressionCreateClient.

Returns

MLResultMLResult_InvalidParamOne or more input parameters are not valid.
MLResultMLResult_OkClient handle was successfully destroyed.
MLResultMLResult_PerceptionSystemNotStartedPerception System has not been started.
MLResultMLResult_UnspecifiedFailureOperation failed for unknown reason.

Required Permissions:

  • None

API Level:

  • 29