Skip to main content
Version: 22 May 2023

Gaze Recognition

APIs for the Gaze Recognition system. More...

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.

Attributes

Name
uint32_tversion
floateye_height_max
floateye_width_max
MLCoordinateFrameUIDvergence
uint32_tversion
MLTimetimestamp
MLGazeRecognitionErrorerror
MLGazeRecognitionBehaviorbehavior
MLVec2feye_left
MLVec2feye_right
floatonset_s
floatduration_s
floatvelocity_degps
floatamplitude_deg
floatdirection_radial

Detailed Description

APIs for the Gaze Recognition system.

Shared Object:

  • perception.magicleap*

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

Attributes Documentation

version

uint32_t version;

Version of this structure.


eye_height_max

float eye_height_max;

The maximum value for the height of the eye_left and eye_right vector.


eye_width_max

float eye_width_max;

The maximum value for the width of the eye_left and eye_right vector.


vergence

MLCoordinateFrameUID vergence;

Location of the 3D vergence point, intersection of 3D gaze vectors.


version

uint32_t version;

Version of this structure.


timestamp

MLTime timestamp;

The timestamp accociated with all data fields in this struct.


error

MLGazeRecognitionError error;
TypeDescription
MLGazeRecognitionErrorA set of possible error codes that the Gaze Recognition system can report.

Represents what gaze Recognition error (if any) is present.


behavior

MLGazeRecognitionBehavior behavior;
TypeDescription
MLGazeRecognitionBehaviorA set of mutually-exclusive behaviors that the Gaze Recognition system can report.

Represents what known gaze Recognition behavior is present.


eye_left

MLVec2f eye_left;

A vector for eye-in-skull position of left eye, even if right eye is closed.


eye_right

MLVec2f eye_right;

A vector for eye-in-skull position of right eye, even if left eye is closed.


onset_s

float onset_s;

Metadata field for onset of the current behavior, in seconds. Onset applies to all behaviors and marks the time when the current behavior began.


duration_s

float duration_s;

Metadata field for duration of the current behavior, in seconds. Duration applies to all gaze types.


velocity_degps

float velocity_degps;

Metadata field for velocity of the current movement, in degrees per second. Velocity field applies to saccades and pursuit, otherwise NaN.


amplitude_deg

float amplitude_deg;

Metadata field for amplitude of the current movement, which is eye-position displacement in degrees of visual angle. Amplitude applies to saccades and pursuit, otherwise NaN.


direction_radial

float direction_radial;

Metadata field for direction of the current movement, in radial degrees (0-360). Direction field applies to saccades and pursuit, otherwise NaN.