Skip to main content
Version: 21 Aug 2024

ml_gaze_recognition.h

Classes

Name
structMLGazeRecognitionStaticData
Static information about the Gaze Recognition system. Populate with MLGazeRecognitionGetStaticData().
structMLGazeRecognitionState
Information about the state of the Gaze Recognition system. This structure must be initialized by calling MLGazeRecognitionStateInit() before use.

Types

Name
typedef struct MLGazeRecognitionStaticDataMLGazeRecognitionStaticData
Static information about the Gaze Recognition system. Populate with MLGazeRecognitionGetStaticData().
typedef struct MLGazeRecognitionStateMLGazeRecognitionState
Information about the state of the Gaze Recognition system. This structure must be initialized by calling MLGazeRecognitionStateInit() before use.

Enums

Name
enumMLGazeRecognitionError
{
MLGazeRecognitionError_None,
MLGazeRecognitionError_Generic,
MLGazeRecognitionError_Ensure32Bits = 0x7FFFFFFF
}
A set of possible error codes that the Gaze Recognition system can report.
enumMLGazeRecognitionBehavior
{
MLGazeRecognition_Unknown = 0,
MLGazeRecognition_EyesClosed = 1,
MLGazeRecognition_Blink = 2,
MLGazeRecognition_Fixation = 3,
MLGazeRecognition_Pursuit = 4,
MLGazeRecognition_Saccade = 5,
MLGazeRecognition_BlinkLeft = 6,
MLGazeRecognition_BlinkRight = 7,
MLGazeRecognition_Ensure32Bits = 0x7FFFFFFF
}
A set of mutually-exclusive behaviors that the Gaze Recognition system can report.

Functions

Name
voidMLGazeRecognitionStaticDataInit(MLGazeRecognitionStaticData * inout_state)
Initialize MLGazeRecognitionStaticData with version.
voidMLGazeRecognitionStateInit(MLGazeRecognitionState * inout_state)
Initialize MLGazeRecognitionState with version.
MLResultMLGazeRecognitionCreate(MLHandle * out_handle)
Create Gaze Recognition.
MLResultMLGazeRecognitionDestroy(MLHandle handle)
Destroy Gaze Recognition.
MLResultMLGazeRecognitionGetStaticData(MLHandle handle, MLGazeRecognitionStaticData * out_data)
Get static information about Gaze Recognition.
MLResultMLGazeRecognitionGetState(MLHandle handle, MLGazeRecognitionState * out_state)
Get information about the user's gaze.

Enums Documentation

MLGazeRecognitionError

EnumeratorValueDescription
MLGazeRecognitionError_NoneNo error, tracking is nominal.
MLGazeRecognitionError_GenericGaze Recognition system failed.
MLGazeRecognitionError_Ensure32Bits0x7FFFFFFFEnsure enum is represented as 32 bits.

A set of possible error codes that the Gaze Recognition system can report.

API Level:

  • 20

MLGazeRecognitionBehavior

EnumeratorValueDescription
MLGazeRecognition_Unknown0Unknown.
MLGazeRecognition_EyesClosed1Both eyes closed.
MLGazeRecognition_Blink2Blink detected. Both eyes open, close, and open.
MLGazeRecognition_Fixation3User is fixating, eye position is stable.
MLGazeRecognition_Pursuit4User is pursuing, eye velocity is low but nonzero.
MLGazeRecognition_Saccade5User is making a saccade, eye velocity is high.
MLGazeRecognition_BlinkLeft6Left eye blink, right eye open.
MLGazeRecognition_BlinkRight7Right eye blink, left eye open.
MLGazeRecognition_Ensure32Bits0x7FFFFFFF

A set of mutually-exclusive behaviors that the Gaze Recognition system can report.

API Level:

  • 24

Types Documentation

MLGazeRecognitionStaticData

typedef struct MLGazeRecognitionStaticData MLGazeRecognitionStaticData;

Static information about the Gaze Recognition system. Populate with MLGazeRecognitionGetStaticData().

More Info

API Level:

  • 27

MLGazeRecognitionState

typedef struct MLGazeRecognitionState MLGazeRecognitionState;

Information about the state of the Gaze Recognition system. This structure must be initialized by calling MLGazeRecognitionStateInit() before use.

More Info

API Level:

  • 20

Functions Documentation

MLGazeRecognitionStaticDataInit

static inline void MLGazeRecognitionStaticDataInit(
MLGazeRecognitionStaticData * inout_state
)

Initialize MLGazeRecognitionStaticData with version.

Parameters

MLGazeRecognitionStaticData *inout_stateSets up the version for inout_state and nulls pointer for the MLCoordinateFrameUID.

Required Permissions:

  • None

API Level:

  • 27

MLGazeRecognitionStateInit

static inline void MLGazeRecognitionStateInit(
MLGazeRecognitionState * inout_state
)

Initialize MLGazeRecognitionState with version.

Parameters

MLGazeRecognitionState *inout_stateSets up the version for inout_state and zeros all the fields.

Required Permissions:

  • None

API Level:

  • 20

MLGazeRecognitionCreate

MLResult MLGazeRecognitionCreate(
MLHandle * out_handle
)

Create Gaze Recognition.

Parameters

MLHandle *out_handleA pointer to an MLHandle which will contain a handle to Gaze Recognition. If this operation fails, out_handle will be ML_INVALID_HANDLE.

Returns

MLResultMLResult_InvalidParamThe out_handle parameter was not valid (null).
MLResultMLResult_OkGaze Recognition was successfully created.
MLResultMLResult_PerceptionSystemNotStartedPerception System has not been started.
MLResultMLResult_PermissionDeniedThe application lacks permission.
MLResultMLResult_UnspecifiedFaiureGaze Recognition was not created successfully.

Required Permissions:

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

API Level:

  • 20

MLGazeRecognitionDestroy

MLResult MLGazeRecognitionDestroy(
MLHandle handle
)

Destroy Gaze Recognition.

Parameters

MLHandlehandleA handle to Gaze Recognition created by MLGazeRecognitionCreate().

Returns

MLResultMLResult_InvalidParamThe Gaze Recognition handle was not valid.
MLResultMLResult_OkThe Gaze Recognition was successfully destroyed.
MLResultMLResult_PerceptionSystemNotStartedPerception System has not been started.
MLResultMLResult_UnspecifiedFailureThe Gaze Recognition was not successfully destroyed.

Required Permissions:

  • None

API Level:

  • 20

MLGazeRecognitionGetStaticData

MLResult MLGazeRecognitionGetStaticData(
MLHandle handle,
MLGazeRecognitionStaticData * out_data
)

Get static information about Gaze Recognition.

Parameters

MLHandlehandleA handle to Gaze Recognition created by MLGazeRecognitionCreate().
MLGazeRecognitionStaticData *out_dataTarget to populate the data about Gaze Recognition.

Returns

MLResultMLResult_InvalidParamThe out_data parameter was not valid (null).
MLResultMLResult_OkGaze Recognition static data was successfully received.
MLResultMLResult_PerceptionSystemNotStartedPerception System has not been started.
MLResultMLResult_UnspecifiedFailureFailed to receive Gaze Recognition static data.

Required Permissions:

  • None

API Level:

  • 20

MLGazeRecognitionGetState

MLResult MLGazeRecognitionGetState(
MLHandle handle,
MLGazeRecognitionState * out_state
)

Get information about the user's gaze.

Parameters

MLHandlehandleA handle to Gaze Recognition created by MLGazeRecognitionCreate().
MLGazeRecognitionState *out_stateInformation about the gaze.

Returns

MLResultMLResult_InvalidParamThe out_state parameter was not valid (null).
MLResultMLResult_Okgaze Recognition state was successfully received.
MLResultMLResult_PerceptionSystemNotStartedPerception System has not been started.
MLResultMLResult_UnspecifiedFailureFailed to receive gaze Recognition state data.

Required Permissions:

  • None

API Level:

  • 20

Source code

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

ML_EXTERN_C_BEGIN

typedef enum MLGazeRecognitionError {
MLGazeRecognitionError_None,
MLGazeRecognitionError_Generic,
MLGazeRecognitionError_Ensure32Bits = 0x7FFFFFFF
} MLGazeRecognitionError;

typedef enum MLGazeRecognitionBehavior {
MLGazeRecognition_Unknown = 0,
MLGazeRecognition_EyesClosed = 1,
MLGazeRecognition_Blink = 2,
MLGazeRecognition_Fixation = 3,
MLGazeRecognition_Pursuit = 4,
MLGazeRecognition_Saccade = 5,
MLGazeRecognition_BlinkLeft = 6,
MLGazeRecognition_BlinkRight = 7,
MLGazeRecognition_Ensure32Bits = 0x7FFFFFFF
} MLGazeRecognitionBehavior;

typedef struct MLGazeRecognitionStaticData {
uint32_t version;
float eye_height_max;
float eye_width_max;
MLCoordinateFrameUID vergence;
} MLGazeRecognitionStaticData;

ML_STATIC_INLINE void MLGazeRecognitionStaticDataInit(MLGazeRecognitionStaticData *inout_state) {
if (inout_state) {
inout_state->version = 2u;
}
}

typedef struct MLGazeRecognitionState {
uint32_t version;
MLTime timestamp;
MLGazeRecognitionError error;
MLGazeRecognitionBehavior behavior;
MLVec2f eye_left;
MLVec2f eye_right;
float onset_s;
float duration_s;
float velocity_degps;
float amplitude_deg;
float direction_radial;
} MLGazeRecognitionState;

ML_STATIC_INLINE void MLGazeRecognitionStateInit(MLGazeRecognitionState *inout_state) {
if (inout_state) {
inout_state->version = 1u;
inout_state->timestamp = 0;
inout_state->error = MLGazeRecognitionError_None;
inout_state->behavior = MLGazeRecognition_Unknown;
inout_state->eye_left.x = 0.0f;
inout_state->eye_left.y = 0.0f;
inout_state->eye_right.x = 0.0f;
inout_state->eye_right.y = 0.0f;
inout_state->onset_s = 0.0f;
inout_state->duration_s = 0.0f;
inout_state->velocity_degps = 0.0f;
inout_state->amplitude_deg = 0.0f;
inout_state->direction_radial = 0.0f;
}
}

ML_API MLResult ML_CALL MLGazeRecognitionCreate(MLHandle *out_handle);

ML_API MLResult ML_CALL MLGazeRecognitionDestroy(MLHandle handle);

ML_API MLResult ML_CALL MLGazeRecognitionGetStaticData(MLHandle handle,
MLGazeRecognitionStaticData *out_data);

ML_API MLResult ML_CALL MLGazeRecognitionGetState(MLHandle handle,
MLGazeRecognitionState *out_state);

ML_EXTERN_C_END