Version: 20 Mar 2024

Gaze Recognition

APIs for the Gaze Recognition system. More...

Classes

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

Types

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

Enums

	Name
enum	MLGazeRecognitionError { MLGazeRecognitionError_None, MLGazeRecognitionError_Generic, MLGazeRecognitionError_Ensure32Bits = 0x7FFFFFFF } A set of possible error codes that the Gaze Recognition system can report.
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 } A set of mutually-exclusive behaviors that the Gaze Recognition system can report.

Name

enum

MLGazeRecognitionError
{
MLGazeRecognitionError_None,
MLGazeRecognitionError_Generic,
MLGazeRecognitionError_Ensure32Bits = 0x7FFFFFFF
}
A set of possible error codes that the Gaze Recognition system can report.

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
}
A set of mutually-exclusive behaviors that the Gaze Recognition system can report.

Functions

	Name
void	MLGazeRecognitionStaticDataInit(MLGazeRecognitionStaticData * inout_state) Initialize MLGazeRecognitionStaticData with version.
void	MLGazeRecognitionStateInit(MLGazeRecognitionState * inout_state) Initialize MLGazeRecognitionState with version.
MLResult	MLGazeRecognitionCreate(MLHandle * out_handle) Create Gaze Recognition.
MLResult	MLGazeRecognitionDestroy(MLHandle handle) Destroy Gaze Recognition.
MLResult	MLGazeRecognitionGetStaticData(MLHandle handle, MLGazeRecognitionStaticData * out_data) Get static information about Gaze Recognition.
MLResult	MLGazeRecognitionGetState(MLHandle handle, MLGazeRecognitionState * out_state) Get information about the user's gaze.

Attributes

	Name
uint32_t	version
float	eye_height_max
float	eye_width_max
MLCoordinateFrameUID	vergence
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

Detailed Description

APIs for the Gaze Recognition system.

Shared Object:

perception.magicleap*

Enums Documentation

MLGazeRecognitionError

Enumerator	Value	Description
MLGazeRecognitionError_None		No error, tracking is nominal.
MLGazeRecognitionError_Generic		Gaze Recognition system failed.
MLGazeRecognitionError_Ensure32Bits	0x7FFFFFFF	Ensure enum is represented as 32 bits.

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

API Level:

MLGazeRecognitionBehavior

Enumerator	Value	Description
MLGazeRecognition_Unknown	0	Unknown.
MLGazeRecognition_EyesClosed	1	Both eyes closed.
MLGazeRecognition_Blink	2	Blink detected. Both eyes open, close, and open.
MLGazeRecognition_Fixation	3	User is fixating, eye position is stable.
MLGazeRecognition_Pursuit	4	User is pursuing, eye velocity is low but nonzero.
MLGazeRecognition_Saccade	5	User is making a saccade, eye velocity is high.
MLGazeRecognition_BlinkLeft	6	Left eye blink, right eye open.
MLGazeRecognition_BlinkRight	7	Right eye blink, left eye open.
MLGazeRecognition_Ensure32Bits	0x7FFFFFFF

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

API Level:

Types Documentation

MLGazeRecognitionStaticData

typedef struct MLGazeRecognitionStaticData MLGazeRecognitionStaticData;

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

More Info

API Level:

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:

Functions Documentation

MLGazeRecognitionStaticDataInit

static inline void MLGazeRecognitionStaticDataInit(
    MLGazeRecognitionStaticData * inout_state
)

Initialize MLGazeRecognitionStaticData with version.

Parameters


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

Required Permissions:

None

API Level:

MLGazeRecognitionStateInit

static inline void MLGazeRecognitionStateInit(
    MLGazeRecognitionState * inout_state
)

Initialize MLGazeRecognitionState with version.

Parameters


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

Required Permissions:

None

API Level:

MLGazeRecognitionCreate

MLResult MLGazeRecognitionCreate(
    MLHandle * out_handle
)

Create Gaze Recognition.

Parameters


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

Returns


MLResult	MLResult_InvalidParam	The out_handle parameter was not valid (null).
MLResult	MLResult_Ok	Gaze Recognition was successfully created.
MLResult	MLResult_PerceptionSystemNotStarted	Perception System has not been started.
MLResult	MLResult_PermissionDenied	The application lacks permission.
MLResult	MLResult_UnspecifiedFaiure	Gaze Recognition was not created successfully.

Required Permissions:

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

API Level:

MLGazeRecognitionDestroy

MLResult MLGazeRecognitionDestroy(
    MLHandle handle
)

Destroy Gaze Recognition.

Parameters


MLHandle	handle	A handle to Gaze Recognition created by MLGazeRecognitionCreate().

Returns


MLResult	MLResult_InvalidParam	The Gaze Recognition handle was not valid.
MLResult	MLResult_Ok	The Gaze Recognition was successfully destroyed.
MLResult	MLResult_PerceptionSystemNotStarted	Perception System has not been started.
MLResult	MLResult_UnspecifiedFailure	The Gaze Recognition was not successfully destroyed.

Required Permissions:

None

API Level:

MLGazeRecognitionGetStaticData

MLResult MLGazeRecognitionGetStaticData(
    MLHandle handle,
    MLGazeRecognitionStaticData * out_data
)

Get static information about Gaze Recognition.

Parameters


MLHandle	handle	A handle to Gaze Recognition created by MLGazeRecognitionCreate().
MLGazeRecognitionStaticData *	out_data	Target to populate the data about Gaze Recognition.

Returns


MLResult	MLResult_InvalidParam	The out_data parameter was not valid (null).
MLResult	MLResult_Ok	Gaze Recognition static data was successfully received.
MLResult	MLResult_PerceptionSystemNotStarted	Perception System has not been started.
MLResult	MLResult_UnspecifiedFailure	Failed to receive Gaze Recognition static data.

Required Permissions:

None

API Level:

MLGazeRecognitionGetState

MLResult MLGazeRecognitionGetState(
    MLHandle handle,
    MLGazeRecognitionState * out_state
)

Get information about the user's gaze.

Parameters


MLHandle	handle	A handle to Gaze Recognition created by MLGazeRecognitionCreate().
MLGazeRecognitionState *	out_state	Information about the gaze.

Returns


MLResult	MLResult_InvalidParam	The out_state parameter was not valid (null).
MLResult	MLResult_Ok	gaze Recognition state was successfully received.
MLResult	MLResult_PerceptionSystemNotStarted	Perception System has not been started.
MLResult	MLResult_UnspecifiedFailure	Failed to receive gaze Recognition state data.

Required Permissions:

None

API Level:

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;

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

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

behavior

MLGazeRecognitionBehavior behavior;

Type	Description
MLGazeRecognitionBehavior	A 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.

Gaze Recognition

Classes​

Types​

Enums​

Functions​

Attributes​

Detailed Description​

Enums Documentation​

MLGazeRecognitionError​

MLGazeRecognitionBehavior​

Types Documentation​

MLGazeRecognitionStaticData​

MLGazeRecognitionState​

Functions Documentation​

MLGazeRecognitionStaticDataInit​

MLGazeRecognitionStateInit​

MLGazeRecognitionCreate​

MLGazeRecognitionDestroy​

MLGazeRecognitionGetStaticData​

MLGazeRecognitionGetState​

Attributes Documentation​

version​

eye_height_max​

eye_width_max​

vergence​

version​

timestamp​

error​

behavior​

eye_left​

eye_right​

onset_s​

duration_s​

velocity_degps​

amplitude_deg​

direction_radial​

Classes

Types

Enums

Functions

Attributes

Detailed Description

Enums Documentation

MLGazeRecognitionError

MLGazeRecognitionBehavior

Types Documentation

MLGazeRecognitionStaticData

MLGazeRecognitionState

Functions Documentation

MLGazeRecognitionStaticDataInit

MLGazeRecognitionStateInit

MLGazeRecognitionCreate

MLGazeRecognitionDestroy

MLGazeRecognitionGetStaticData

MLGazeRecognitionGetState

Attributes Documentation

version

eye_height_max

eye_width_max

vergence

version

timestamp

error

behavior

eye_left

eye_right

onset_s

duration_s

velocity_degps

amplitude_deg

direction_radial