Version: 12 Dec 2024

ml_head_tracking.h

Classes

	Name
struct	MLHeadTrackingStaticData
struct	MLHeadTrackingState A structure containing information on the current state of the Head Tracking system.
struct	MLHeadTrackingStateEx 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 MLHeadTrackingStaticData	MLHeadTrackingStaticData
typedef struct MLHeadTrackingState	MLHeadTrackingState A structure containing information on the current state of the Head Tracking system.
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.

Enums

	Name
enum	MLHeadTrackingError { 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.
enum	MLHeadTrackingErrorFlag { 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.
enum	MLHeadTrackingMode { MLHeadTrackingMode_6DOF = 0, MLHeadTrackingMode_Unavailable = 1, MLHeadTrackingMode_Ensure32Bits = 0x7FFFFFFF } A set of possible tracking modes the Head Tracking system can be in.
enum	MLHeadTrackingStatus { 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.
enum	MLHeadTrackingMapEvent { 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
void	MLHeadTrackingStateExInit(MLHeadTrackingStateEx * inout_info) Initialize default values for a MLHeadTrackingStateEx structure.
MLResult	MLHeadTrackingCreate(MLHandle * out_handle) Creates a Head Tracker.
MLResult	MLHeadTrackingDestroy(MLHandle head_tracker) Destroys a Head Tracker.
MLResult	MLHeadTrackingGetStaticData(MLHandle head_tracker, MLHeadTrackingStaticData * out_data) Returns static information about the Head Tracker.
MLResult	MLHeadTrackingGetState(MLHandle head_tracker, MLHeadTrackingState * out_state) Returns the most recent head tracking state.
MLResult	MLHeadTrackingGetStateEx(MLHandle head_tracker, MLHeadTrackingStateEx * out_state) Returns the most recent head tracking state.
MLResult	MLHeadTrackingGetMapEvents(MLHandle head_tracker, uint64_t * out_map_events) Gets map events.

Enums Documentation

MLHeadTrackingError

Enumerator	Value	Description
MLHeadTrackingError_None		No error, tracking is nominal.
MLHeadTrackingError_NotEnoughFeatures		There are not enough features in the environment.
MLHeadTrackingError_LowLight		Lighting in the environment is not sufficient to track accurately.
MLHeadTrackingError_Unknown		Head tracking failed for an unknown reason.
MLHeadTrackingError_Ensure32Bits	0x7FFFFFFF	Ensure 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:

MLHeadTrackingErrorFlag

Enumerator	Value	Description
MLHeadTrackingErrorFlag_None	0	No error, tracking is nominal.
MLHeadTrackingErrorFlag_Unknown	1 << 0	Head tracking failed for an unknown reason.
MLHeadTrackingErrorFlag_NotEnoughFeatures	1 << 1	There are not enough features in the environment.
MLHeadTrackingErrorFlag_LowLight	1 << 2	Lighting in the environment is not sufficient to track accurately.
MLHeadTrackingErrorFlag_ExcessiveMotion	1 << 3	Head tracking failed due to excessive motion.
MLHeadTrackingErrorFlag_Ensure32Bits	0x7FFFFFFF	Ensure 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:

MLHeadTrackingMode

Enumerator	Value	Description
MLHeadTrackingMode_6DOF	0	Full 6 degrees of freedom tracking (position and orientation).
MLHeadTrackingMode_Unavailable	1	Head tracking is unavailable.
MLHeadTrackingMode_Ensure32Bits	0x7FFFFFFF	Ensure 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:

MLHeadTrackingStatus

Enumerator	Value	Description
MLHeadTrackingStatus_Invalid	0	Head tracking is unavailable.
MLHeadTrackingStatus_Initializing	1	Head tracking is initializing.
MLHeadTrackingStatus_Relocalizing	2	Head tracking is relocalizing.
MLHeadTrackingStatus_Valid	100	Valid head tracking data is available.
MLHeadTrackingStatus_Ensure32Bits	0x7FFFFFFF	Ensure 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:

MLHeadTrackingMapEvent

Enumerator	Value	Description
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_Ensure32Bits	0x7FFFFFFF	Ensure 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:

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:

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:

Functions Documentation

MLHeadTrackingStateExInit

static inline void MLHeadTrackingStateExInit(
    MLHeadTrackingStateEx * inout_info
)

Initialize default values for a MLHeadTrackingStateEx structure.

Parameters


MLHeadTrackingStateEx *	inout_info	The object to initialize with default values.

Required Permissions:

None

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

API Level:

MLHeadTrackingCreate

MLResult MLHeadTrackingCreate(
    MLHandle * out_handle
)

Creates a Head Tracker.

Parameters


MLHandle *	out_handle	A 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


MLResult	MLResult_Ok	Successfully created head tracker.
MLResult	MLResult_UnspecifiedFailure	Failed to create head tracker due to an unknown error.
MLResult	MLResult_PermissionDenied	The 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


MLHandle	head_tracker	A handle to a Head Tracker created by MLHeadTrackingCreate().

Returns


MLResult	MLResult_Ok	Successfully destroyed head tracker.
MLResult	MLResult_UnspecifiedFailure	Failed 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


MLHandle	head_tracker	A handle to the tracker.
MLHeadTrackingStaticData *	out_data	Target to populate the data about that Head Tracker.

Returns


MLResult	MLResult_InvalidParam	Failed to receive static data due to an invalid input parameter.
MLResult	MLResult_Ok	Successfully received static data.
MLResult	MLResult_UnspecifiedFailure	Failed 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


MLHandle	head_tracker	A handle to the tracker.
MLHeadTrackingState *	out_state	Pointer to valid MLHeadTrackingState object to be filled with current state information.

Returns


MLResult	MLResult_InvalidParam	Failed to return the most recent head tracking state due to an invalid input parameter.
MLResult	MLResult_Ok	Successfully returned the most recent head tracking state.
MLResult	MLResult_UnspecifiedFailure	Failed 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


MLHandle	head_tracker	A handle to the tracker.
MLHeadTrackingStateEx *	out_state	Pointer to valid MLHeadTrackingStateEx object to be filled with current state information.

Returns


MLResult	MLResult_InvalidParam	Failed to return the most recent head tracking state due to an invalid input parameter.
MLResult	MLResult_Ok	Successfully returned the most recent head tracking state.
MLResult	MLResult_UnspecifiedFailure	Failed 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:

MLHeadTrackingGetMapEvents

MLResult MLHeadTrackingGetMapEvents(
    MLHandle head_tracker,
    uint64_t * out_map_events
)

Gets map events.

Parameters


MLHandle	head_tracker	A handle to the tracker.
uint64_t *	out_map_events	Pointer to a uint64_t representing a bitmask of MLHeadTrackingMapEvent, allocated by the caller.

Returns


MLResult	MLResult_InvalidParam	Failed to get map events due to an invalid input parameter.
MLResult	MLResult_Ok	Successfully got map events.
MLResult	MLResult_UnspecifiedFailure	Failed 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:

Source code

// %BANNER_BEGIN%
// ---------------------------------------------------------------------
// %COPYRIGHT_BEGIN%
// Copyright (c) 2017 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 <string.h>

ML_EXTERN_C_BEGIN

typedef ML_DEPRECATED_MSG("Use OpenXR APIs.") struct MLHeadTrackingStaticData {
  MLCoordinateFrameUID coord_frame_head;
} MLHeadTrackingStaticData;

typedef enum MLHeadTrackingError {
  MLHeadTrackingError_None,
  MLHeadTrackingError_NotEnoughFeatures,
  MLHeadTrackingError_LowLight,
  MLHeadTrackingError_Unknown,
  MLHeadTrackingError_Ensure32Bits = 0x7FFFFFFF
} MLHeadTrackingError;

typedef enum MLHeadTrackingErrorFlag {
  MLHeadTrackingErrorFlag_None = 0,
  MLHeadTrackingErrorFlag_Unknown = 1 << 0,
  MLHeadTrackingErrorFlag_NotEnoughFeatures = 1 << 1,
  MLHeadTrackingErrorFlag_LowLight = 1 << 2,
  MLHeadTrackingErrorFlag_ExcessiveMotion = 1 << 3,
  MLHeadTrackingErrorFlag_Ensure32Bits = 0x7FFFFFFF
} MLHeadTrackingErrorFlag;

typedef enum MLHeadTrackingMode {
  MLHeadTrackingMode_6DOF = 0,
  MLHeadTrackingMode_Unavailable = 1,
  MLHeadTrackingMode_Ensure32Bits = 0x7FFFFFFF
} MLHeadTrackingMode;

typedef enum MLHeadTrackingStatus {
  MLHeadTrackingStatus_Invalid = 0,
  MLHeadTrackingStatus_Initializing = 1,
  MLHeadTrackingStatus_Relocalizing = 2,
  MLHeadTrackingStatus_Valid = 100,
  MLHeadTrackingStatus_Ensure32Bits = 0x7FFFFFFF
} MLHeadTrackingStatus;


typedef ML_DEPRECATED_MSG("Use OpenXR APIs.") struct MLHeadTrackingState {
  MLHeadTrackingMode mode;
  float confidence;
  MLHeadTrackingError error;
} MLHeadTrackingState;

typedef ML_DEPRECATED_MSG("Use OpenXR APIs.") struct MLHeadTrackingStateEx {
  uint32_t version;
  MLHeadTrackingStatus status;
  float confidence;
  uint32_t error;
} MLHeadTrackingStateEx;

ML_DEPRECATED_MSG("Use OpenXR APIs.")
ML_STATIC_INLINE void MLHeadTrackingStateExInit(MLHeadTrackingStateEx *inout_info) {
  if (inout_info != NULL) {
    memset(inout_info, 0, sizeof(MLHeadTrackingStateEx));
    inout_info->version = 1;
  }
}

typedef enum MLHeadTrackingMapEvent {
  MLHeadTrackingMapEvent_Lost = (1 << 0),
  MLHeadTrackingMapEvent_Recovered = (1 << 1),
  MLHeadTrackingMapEvent_RecoveryFailed = (1 << 2),
  MLHeadTrackingMapEvent_NewSession = (1 << 3),
  MLHeadTrackingMapEvent_Ensure32Bits = 0x7FFFFFFF
} MLHeadTrackingMapEvent;

ML_DEPRECATED_MSG("Use OpenXR APIs.")
ML_API MLResult ML_CALL MLHeadTrackingCreate(MLHandle *out_handle);

ML_DEPRECATED_MSG("Use OpenXR APIs.")
ML_API MLResult ML_CALL MLHeadTrackingDestroy(MLHandle head_tracker);

ML_DEPRECATED_MSG("Use OpenXR APIs.")
ML_API MLResult ML_CALL MLHeadTrackingGetStaticData(MLHandle head_tracker, MLHeadTrackingStaticData *out_data);

ML_DEPRECATED_MSG("Replaced by MLHeadTrackingGetStateEx.")
ML_API MLResult ML_CALL MLHeadTrackingGetState(MLHandle head_tracker, MLHeadTrackingState *out_state);

ML_DEPRECATED_MSG("Use OpenXR APIs.")
ML_API MLResult ML_CALL MLHeadTrackingGetStateEx(MLHandle head_tracker, MLHeadTrackingStateEx *out_state);


ML_DEPRECATED_MSG("Use OpenXR APIs.")
ML_API MLResult ML_CALL MLHeadTrackingGetMapEvents(MLHandle head_tracker, uint64_t *out_map_events);

ML_EXTERN_C_END

ml_head_tracking.h

Classes​

Types​

Enums​

Functions​

Enums Documentation​

MLHeadTrackingError​

MLHeadTrackingErrorFlag​

MLHeadTrackingMode​

MLHeadTrackingStatus​

MLHeadTrackingMapEvent​

Types Documentation​

MLHeadTrackingStaticData​

MLHeadTrackingState​

MLHeadTrackingStateEx​

Functions Documentation​

MLHeadTrackingStateExInit​

MLHeadTrackingCreate​

MLHeadTrackingDestroy​

MLHeadTrackingGetStaticData​

MLHeadTrackingGetState​

MLHeadTrackingGetStateEx​

MLHeadTrackingGetMapEvents​

Source code​

Classes

Types

Enums

Functions

Enums Documentation

MLHeadTrackingError

MLHeadTrackingErrorFlag

MLHeadTrackingMode

MLHeadTrackingStatus

MLHeadTrackingMapEvent

Types Documentation

MLHeadTrackingStaticData

MLHeadTrackingState

MLHeadTrackingStateEx

Functions Documentation

MLHeadTrackingStateExInit

MLHeadTrackingCreate

MLHeadTrackingDestroy

MLHeadTrackingGetStaticData

MLHeadTrackingGetState

MLHeadTrackingGetStateEx

MLHeadTrackingGetMapEvents

Source code