ml_gaze_recognition.h

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.

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.

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:

• 20

---

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:

• 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_state	Sets 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_state	Sets 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_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:

• 20

---

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:

• 20

---

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:

• 20

---

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:

• 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