Skip to main content
Version: 21 Aug 2024

ml_facial_expression.h

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.

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

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