ml_facial_expression.h

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.

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

---

Source code

// %BANNER_BEGIN%
// ---------------------------------------------------------------------
// %COPYRIGHT_BEGIN%
// Copyright (c) 2023 Magic Leap, Inc. All Rights Reserved.
// Use of this file is governed by the Software License Agreement,
// located here: https://www.magicleap.com/software-license-agreement-ml2
// Terms and conditions applicable to third-party materials accompanying
// this distribution may also be found in the top-level NOTICE file
// appearing herein.
// %COPYRIGHT_END%
// ---------------------------------------------------------------------
// %BANNER_END%

#pragma once

#include "ml_api.h"
#include "ml_types.h"

#include <string.h>

ML_EXTERN_C_BEGIN

enum {
  MLResultAPIPrefix_FacialExpression = MLRESULT_PREFIX(0x18cd),
};
typedef enum MLFacialExpressionResult {
  MLFacialExpressionResult_HeadsetFitIssue = MLResultAPIPrefix_FacialExpression,
  MLFacialExpressionResult_EyeExpressionDisabled,
  MLFacialExpressionResult_Ensure32Bits = 0x7FFFFFFF
} MLFacialExpressionResult;

typedef 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
} MLFacialExpressionEyeExpressionType;

typedef struct MLFacialExpressionEyeData {
  uint32_t version;
  MLTime timestamp;
  float eye_expression_weights[MLFacialExpressionEyeExpressionType_Count];
} MLFacialExpressionEyeData;

ML_STATIC_INLINE void MLFacialExpressionEyeDataInit(MLFacialExpressionEyeData *inout_eye_data) {
  if (inout_eye_data) {
    memset(inout_eye_data, 0, sizeof(MLFacialExpressionEyeData));
    inout_eye_data->version = 1u;
  }
}

typedef struct MLFacialExpressionSettings {
  uint32_t version;
  bool enable_eye_expression;
} MLFacialExpressionSettings;

ML_STATIC_INLINE void MLFacialExpressionSettingsInit(MLFacialExpressionSettings *inout_settings) {
  if (inout_settings) {
    memset(inout_settings, 0, sizeof(MLFacialExpressionSettings));
    inout_settings->version = 1u;
    inout_settings->enable_eye_expression = true;
  }
}

ML_API const char *ML_CALL MLFacialExpressionGetResultString(MLResult result);

ML_API MLResult ML_CALL MLFacialExpressionCreateClient(const MLFacialExpressionSettings *settings, MLHandle *out_handle);

ML_API MLResult ML_CALL MLFacialExpressionUpdateSettings(MLHandle handle, const MLFacialExpressionSettings *settings);

ML_API MLResult ML_CALL MLFacialExpressionGetEyeData(MLHandle handle, MLFacialExpressionEyeData *out_eye_data);

ML_API MLResult ML_CALL MLFacialExpressionDestroyClient(MLHandle handle);

ML_EXTERN_C_END