Skip to main content
Version: 21 Aug 2024

ml_eye_tracking.h

Classes

Name
structMLEyeTrackingStaticData
Static information about the eye tracking.
structMLEyeTrackingStateEx
Information about the state of the eye tracking system.

Types

Name
typedef struct MLEyeTrackingStaticDataMLEyeTrackingStaticData
Static information about the eye tracking.
typedef struct MLEyeTrackingStateExMLEyeTrackingStateEx
Information about the state of the eye tracking system.

Enums

Name
enumMLEyeTrackingError
{
MLEyeTrackingError_None,
MLEyeTrackingError_Generic,
MLEyeTrackingError_Ensure32Bits = 0x7FFFFFFF
}

Functions

Name
voidMLEyeTrackingStateInit(MLEyeTrackingStateEx * inout_state)
Initialize MLEyeTrackingStateEx with version.
MLResultMLEyeTrackingCreate(MLHandle * out_handle)
Creates an eye tracker.
MLResultMLEyeTrackingDestroy(MLHandle eye_tracker)
Destroys an eye tracker.
MLResultMLEyeTrackingGetStaticData(MLHandle eye_tracker, MLEyeTrackingStaticData * out_data)
Gets static information about the eye tracker.
MLResultMLEyeTrackingGetStateEx(MLHandle eye_tracker, MLEyeTrackingStateEx * out_state)
Gets information about the user's eyes.

Enums Documentation

MLEyeTrackingError

EnumeratorValueDescription
MLEyeTrackingError_NoneNo error, tracking is nominal.
MLEyeTrackingError_GenericEye Tracker failed.
MLEyeTrackingError_Ensure32Bits0x7FFFFFFFEnsure enum is represented as 32 bits.

A set of possible error codes that the Eye Tracking system can report.


Types Documentation

MLEyeTrackingStaticData

typedef struct MLEyeTrackingStaticData MLEyeTrackingStaticData;

Static information about the eye tracking.

Populate with MLEyeTrackingGetStaticData().

More Info

API Level:

  • 20

MLEyeTrackingStateEx

typedef struct MLEyeTrackingStateEx MLEyeTrackingStateEx;

Information about the state of the eye tracking system.

This structure must be initialized by calling MLEyeTrackingStateInit() before use.

More Info

API Level:

  • 26

Functions Documentation

MLEyeTrackingStateInit

static inline void MLEyeTrackingStateInit(
MLEyeTrackingStateEx * inout_state
)

Initialize MLEyeTrackingStateEx with version.

Parameters

MLEyeTrackingStateEx *inout_stateSet up the version for inout_state and zero all other fields.

API Level:

  • 26

MLEyeTrackingCreate

MLResult MLEyeTrackingCreate(
MLHandle * out_handle
)

Creates an eye tracker.

Parameters

MLHandle *out_handleA pointer to an MLHandle which will contain the handle of the eye tracker. If this operation fails, out_handle will be ML_INVALID_HANDLE.

Returns

MLResultMLResult_InvalidParamFailed to create eye tracker due to an invalid input parameter.
MLResultMLResult_OkSuccessfully created eye tracker.
MLResultMLResult_UnspecifiedFaiureFailed to create eye tracker due to an unknown failure.
MLResultMLResult_PermissionDeniedThe application lacks permission.

Required Permissions:

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

MLEyeTrackingDestroy

MLResult MLEyeTrackingDestroy(
MLHandle eye_tracker
)

Destroys an eye tracker.

Parameters

MLHandleeye_trackerA handle to an Eye Tracker created by MLEyeTrackingCreate().

Returns

MLResultMLResult_OkSuccessfully destroyed eye tracker.
MLResultMLResult_UnspecifiedFaiureFailed to destroy eye tracker due to an unknown failure.

Required Permissions:

  • None

MLEyeTrackingGetStaticData

MLResult MLEyeTrackingGetStaticData(
MLHandle eye_tracker,
MLEyeTrackingStaticData * out_data
)

Gets static information about the eye tracker.

Parameters

MLHandleeye_trackerA handle to an Eye Tracker created by MLEyeTrackingCreate().
MLEyeTrackingStaticData *out_dataTarget to populate the data about the eye tracker.

Returns

MLResultMLResult_InvalidParamThe out_data parameter was not valid (null).
MLResultMLResult_OkEye tracking static data was successfully received.
MLResultMLResult_UnspecifiedFailureFailed to receive eye tracking static data.

Required Permissions:

  • None

API Level:

  • 20

MLEyeTrackingGetStateEx

MLResult MLEyeTrackingGetStateEx(
MLHandle eye_tracker,
MLEyeTrackingStateEx * out_state
)

Gets information about the user's eyes.

Parameters

MLHandleeye_trackerA handle to an Eye Tracker created by MLEyeTrackingCreate().
MLEyeTrackingStateEx *out_stateInformation about the eyes.

Returns

MLResultMLResult_InvalidParamFailed to receive eye tracking state due to an invalid input parameter.
MLResultMLResult_OkSuccessfully received eye tracking state.
MLResultMLResult_UnspecifiedFailureFailed to receive eye tracking state due to an unknown failure.

Required Permissions:

  • None

NOTE: To ensure a clean trace of any eye state, it is important to monitor the confidence value of that eye to reject frames where confidence is 0 (or employ another fallback strategy like propagating the last high confidence value).

API Level:

  • 9

Source code

// %BANNER_BEGIN%
// ---------------------------------------------------------------------
// %COPYRIGHT_BEGIN%
// Copyright (c) 2017 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

typedef enum MLEyeTrackingError {
MLEyeTrackingError_None,
MLEyeTrackingError_Generic,
MLEyeTrackingError_Ensure32Bits = 0x7FFFFFFF
} MLEyeTrackingError;

typedef struct MLEyeTrackingStaticData {
MLCoordinateFrameUID vergence;

MLCoordinateFrameUID left_center;

MLCoordinateFrameUID right_center;
} MLEyeTrackingStaticData;

typedef struct MLEyeTrackingStateEx {
uint32_t version;
float vergence_confidence;
float left_center_confidence;
float right_center_confidence;
bool left_blink;
bool right_blink;
MLEyeTrackingError error;
MLTime timestamp;
float left_eye_openness;
float right_eye_openness;
} MLEyeTrackingStateEx;

ML_STATIC_INLINE void MLEyeTrackingStateInit(MLEyeTrackingStateEx *inout_state) {
if (inout_state) {
memset(inout_state, 0, sizeof(MLEyeTrackingStateEx));
inout_state->version = 2;
inout_state->error = MLEyeTrackingError_None;
}
}

ML_API MLResult ML_CALL MLEyeTrackingCreate(MLHandle *out_handle);

ML_API MLResult ML_CALL MLEyeTrackingDestroy(MLHandle eye_tracker);

ML_API MLResult ML_CALL MLEyeTrackingGetStaticData(MLHandle eye_tracker, MLEyeTrackingStaticData *out_data);

ML_API MLResult ML_CALL MLEyeTrackingGetStateEx(MLHandle eye_tracker, MLEyeTrackingStateEx *out_state);

ML_EXTERN_C_END