Skip to main content
Version: 21 Aug 2024

Head Tracking

APIs for the Head Tracking system. More...

Classes

Name
structMLHeadTrackingStaticData
structMLHeadTrackingState
A structure containing information on the current state of the Head Tracking system.
structMLHeadTrackingStateEx
Structure containing information on the current state of the Head Tracking system. This structure must be initialized by calling MLHeadTrackingStateExInit before use.

Types

Name
typedef struct MLHeadTrackingStaticDataMLHeadTrackingStaticData
typedef struct MLHeadTrackingStateMLHeadTrackingState
A structure containing information on the current state of the Head Tracking system.
typedef struct MLHeadTrackingStateExMLHeadTrackingStateEx
Structure containing information on the current state of the Head Tracking system. This structure must be initialized by calling MLHeadTrackingStateExInit before use.

Enums

Name
enumMLHeadTrackingError
{
MLHeadTrackingError_None,
MLHeadTrackingError_NotEnoughFeatures,
MLHeadTrackingError_LowLight,
MLHeadTrackingError_Unknown,
MLHeadTrackingError_Ensure32Bits = 0x7FFFFFFF
}
A set of possible error conditions that can cause Head Tracking to be less than ideal.
enumMLHeadTrackingErrorFlag
{
MLHeadTrackingErrorFlag_None = 0,
MLHeadTrackingErrorFlag_Unknown = 1 << 0,
MLHeadTrackingErrorFlag_NotEnoughFeatures = 1 << 1,
MLHeadTrackingErrorFlag_LowLight = 1 << 2,
MLHeadTrackingErrorFlag_ExcessiveMotion = 1 << 3,
MLHeadTrackingErrorFlag_Ensure32Bits = 0x7FFFFFFF
}
A set of possible error conditions that can cause Head Tracking to be less than ideal.
enumMLHeadTrackingMode
{
MLHeadTrackingMode_6DOF = 0,
MLHeadTrackingMode_Unavailable = 1,
MLHeadTrackingMode_Ensure32Bits = 0x7FFFFFFF
}
A set of possible tracking modes the Head Tracking system can be in.
enumMLHeadTrackingStatus
{
MLHeadTrackingStatus_Invalid = 0,
MLHeadTrackingStatus_Initializing = 1,
MLHeadTrackingStatus_Relocalizing = 2,
MLHeadTrackingStatus_Valid = 100,
MLHeadTrackingStatus_Ensure32Bits = 0x7FFFFFFF
}
A set of possible tracking status for the Head Tracking system.
enumMLHeadTrackingMapEvent
{
MLHeadTrackingMapEvent_Lost = (1 << 0),
MLHeadTrackingMapEvent_Recovered = (1 << 1),
MLHeadTrackingMapEvent_RecoveryFailed = (1 << 2),
MLHeadTrackingMapEvent_NewSession = (1 << 3),
MLHeadTrackingMapEvent_Ensure32Bits = 0x7FFFFFFF
}
Different types of map events that can occur that a developer may have to handle.

Functions

Name
voidMLHeadTrackingStateExInit(MLHeadTrackingStateEx * inout_info)
Initialize default values for a MLHeadTrackingStateEx structure.
MLResultMLHeadTrackingCreate(MLHandle * out_handle)
Creates a Head Tracker.
MLResultMLHeadTrackingDestroy(MLHandle head_tracker)
Destroys a Head Tracker.
MLResultMLHeadTrackingGetStaticData(MLHandle head_tracker, MLHeadTrackingStaticData * out_data)
Returns static information about the Head Tracker.
MLResultMLHeadTrackingGetState(MLHandle head_tracker, MLHeadTrackingState * out_state)
Returns the most recent head tracking state.
MLResultMLHeadTrackingGetStateEx(MLHandle head_tracker, MLHeadTrackingStateEx * out_state)
Returns the most recent head tracking state.
MLResultMLHeadTrackingGetMapEvents(MLHandle head_tracker, uint64_t * out_map_events)
Gets map events.

Detailed Description

APIs for the Head Tracking system.

Warning

THIS API IS DEPRECATED IN FAVOR OF OPENXR APIs: https://registry.khronos.org/OpenXR/specs/1.0/html/xrspec.html

Shared Object:

  • perception.magicleap*

Enums Documentation

MLHeadTrackingError

EnumeratorValueDescription
MLHeadTrackingError_NoneNo error, tracking is nominal.
MLHeadTrackingError_NotEnoughFeaturesThere are not enough features in the environment.
MLHeadTrackingError_LowLightLighting in the environment is not sufficient to track accurately.
MLHeadTrackingError_UnknownHead tracking failed for an unknown reason.
MLHeadTrackingError_Ensure32Bits0x7FFFFFFFEnsure enum is represented as 32 bits.

A set of possible error conditions that can cause Head Tracking to be less than ideal.

Deprecated

Deprecated since 1.2.0. Scheduled for removal. Replaced by MLHeadTrackingErrorFlag.

API Level:

  • 1

MLHeadTrackingErrorFlag

EnumeratorValueDescription
MLHeadTrackingErrorFlag_None0No error, tracking is nominal.
MLHeadTrackingErrorFlag_Unknown1 << 0Head tracking failed for an unknown reason.
MLHeadTrackingErrorFlag_NotEnoughFeatures1 << 1There are not enough features in the environment.
MLHeadTrackingErrorFlag_LowLight1 << 2Lighting in the environment is not sufficient to track accurately.
MLHeadTrackingErrorFlag_ExcessiveMotion1 << 3Head tracking failed due to excessive motion.
MLHeadTrackingErrorFlag_Ensure32Bits0x7FFFFFFFEnsure enum is represented as 32 bits.

A set of possible error conditions that can cause Head Tracking to be less than ideal.

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

API Level:

  • 26

MLHeadTrackingMode

EnumeratorValueDescription
MLHeadTrackingMode_6DOF0Full 6 degrees of freedom tracking (position and orientation).
MLHeadTrackingMode_Unavailable1Head tracking is unavailable.
MLHeadTrackingMode_Ensure32Bits0x7FFFFFFFEnsure enum is represented as 32 bits.

A set of possible tracking modes the Head Tracking system can be in.

Deprecated

Deprecated since 1.2.0. Scheduled for removal. Replaced by MLHeadTrackingStatus.

API Level:

  • 1

MLHeadTrackingStatus

EnumeratorValueDescription
MLHeadTrackingStatus_Invalid0Head tracking is unavailable.
MLHeadTrackingStatus_Initializing1Head tracking is initializing.
MLHeadTrackingStatus_Relocalizing2Head tracking is relocalizing.
MLHeadTrackingStatus_Valid100Valid head tracking data is available.
MLHeadTrackingStatus_Ensure32Bits0x7FFFFFFFEnsure enum is represented as 32 bits.

A set of possible tracking status for the Head Tracking system.

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

API Level:

  • 26

MLHeadTrackingMapEvent

EnumeratorValueDescription
MLHeadTrackingMapEvent_Lost(1 << 0)Map was lost. It could possibly recover.
MLHeadTrackingMapEvent_Recovered(1 << 1)Previous map was recovered.
MLHeadTrackingMapEvent_RecoveryFailed(1 << 2)Failed to recover previous map.
MLHeadTrackingMapEvent_NewSession(1 << 3)New map session created.
MLHeadTrackingMapEvent_Ensure32Bits0x7FFFFFFFEnsure enum is represented as 32 bits.

Different types of map events that can occur that a developer may have to handle.

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

API Level:

  • 2

Types Documentation

MLHeadTrackingStaticData

typedef struct MLHeadTrackingStaticData MLHeadTrackingStaticData;

Static information about a Head Tracker. Populate this structure with MLHeadTrackingGetStaticData().

More Info


MLHeadTrackingState

typedef struct MLHeadTrackingState MLHeadTrackingState;

A structure containing information on the current state of the Head Tracking system.

More Info

Deprecated

Deprecated since 1.2.0. Scheduled for removal. Replaced by MLHeadTrackingStateEx.

API Level:

  • 1

MLHeadTrackingStateEx

typedef struct MLHeadTrackingStateEx MLHeadTrackingStateEx;

Structure containing information on the current state of the Head Tracking system. This structure must be initialized by calling MLHeadTrackingStateExInit before use.

More Info

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

API Level:

  • 26

Functions Documentation

MLHeadTrackingStateExInit

static inline void MLHeadTrackingStateExInit(
MLHeadTrackingStateEx * inout_info
)

Initialize default values for a MLHeadTrackingStateEx structure.

Parameters

MLHeadTrackingStateEx *inout_infoThe object to initialize with default values.

Required Permissions:

  • None
Deprecated

Deprecated since 1.6.0. Scheduled for removal.

API Level:

  • 26

MLHeadTrackingCreate

MLResult MLHeadTrackingCreate(
MLHandle * out_handle
)

Creates a Head Tracker.

Parameters

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

Returns

MLResultMLResult_OkSuccessfully created head tracker.
MLResultMLResult_UnspecifiedFailureFailed to create head tracker due to an unknown error.
MLResultMLResult_PermissionDeniedThe application lacks permission.

Required Permissions:

  • None
Deprecated

Deprecated since 1.6.0. Scheduled for removal.


MLHeadTrackingDestroy

MLResult MLHeadTrackingDestroy(
MLHandle head_tracker
)

Destroys a Head Tracker.

Parameters

MLHandlehead_trackerA handle to a Head Tracker created by MLHeadTrackingCreate().

Returns

MLResultMLResult_OkSuccessfully destroyed head tracker.
MLResultMLResult_UnspecifiedFailureFailed to destroy head tracker due to an unknown error.

Required Permissions:

  • None
Deprecated

Deprecated since 1.6.0. Scheduled for removal.


MLHeadTrackingGetStaticData

MLResult MLHeadTrackingGetStaticData(
MLHandle head_tracker,
MLHeadTrackingStaticData * out_data
)

Returns static information about the Head Tracker.

Parameters

MLHandlehead_trackerA handle to the tracker.
MLHeadTrackingStaticData *out_dataTarget to populate the data about that Head Tracker.

Returns

MLResultMLResult_InvalidParamFailed to receive static data due to an invalid input parameter.
MLResultMLResult_OkSuccessfully received static data.
MLResultMLResult_UnspecifiedFailureFailed to receive static data due to an unknown error.

Required Permissions:

  • None
Deprecated

Deprecated since 1.6.0. Scheduled for removal.


MLHeadTrackingGetState

MLResult MLHeadTrackingGetState(
MLHandle head_tracker,
MLHeadTrackingState * out_state
)

Returns the most recent head tracking state.

Parameters

MLHandlehead_trackerA handle to the tracker.
MLHeadTrackingState *out_statePointer to valid MLHeadTrackingState object to be filled with current state information.

Returns

MLResultMLResult_InvalidParamFailed to return the most recent head tracking state due to an invalid input parameter.
MLResultMLResult_OkSuccessfully returned the most recent head tracking state.
MLResultMLResult_UnspecifiedFailureFailed to return the most recent head tracking state due to an unknown error.

Required Permissions:

  • None
Deprecated

Deprecated since 1.2.0. Scheduled for removal. Replaced by MLHeadTrackingGetStateEx.


MLHeadTrackingGetStateEx

MLResult MLHeadTrackingGetStateEx(
MLHandle head_tracker,
MLHeadTrackingStateEx * out_state
)

Returns the most recent head tracking state.

Parameters

MLHandlehead_trackerA handle to the tracker.
MLHeadTrackingStateEx *out_statePointer to valid MLHeadTrackingStateEx object to be filled with current state information.

Returns

MLResultMLResult_InvalidParamFailed to return the most recent head tracking state due to an invalid input parameter.
MLResultMLResult_OkSuccessfully returned the most recent head tracking state.
MLResultMLResult_UnspecifiedFailureFailed to return the most recent head tracking state due to an unknown error.

Required Permissions:

  • None
Deprecated

Deprecated since 1.6.0. Scheduled for removal.

API Level:

  • 26

MLHeadTrackingGetMapEvents

MLResult MLHeadTrackingGetMapEvents(
MLHandle head_tracker,
uint64_t * out_map_events
)

Gets map events.

Parameters

MLHandlehead_trackerA handle to the tracker.
uint64_t *out_map_eventsPointer to a uint64_t representing a bitmask of MLHeadTrackingMapEvent, allocated by the caller.

Returns

MLResultMLResult_InvalidParamFailed to get map events due to an invalid input parameter.
MLResultMLResult_OkSuccessfully got map events.
MLResultMLResult_UnspecifiedFailureFailed to get map events due to an unknown error.

Required Permissions:

  • None

A developer must be aware of certain events that can occur under degenerative conditions in order to cleanly handle it. The most important event to be aware of is when a map changes.

In the case that a new map session begins, or recovery fails, all formerly cached transform and world reconstruction data (planes, mesh) is invalidated and must be updated.

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

API Level:

  • 2