Head Tracking
APIs for the Head Tracking system. More...
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
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. |
Detailed Description
APIs for the Head Tracking system.
Shared Object:
- perception.magicleap*
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 since 1.2.0. Scheduled for removal. Replaced by MLHeadTrackingErrorFlag.
API Level:
- 1
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.
API Level:
- 26
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 since 1.2.0. Scheduled for removal. Replaced by MLHeadTrackingStatus.
API Level:
- 1
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.
API Level:
- 26
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.
API Level:
- 2
Types Documentation
MLHeadTrackingStaticData
typedef struct MLHeadTrackingStaticData MLHeadTrackingStaticData;
Static information about a Head Tracker. Populate this structure with MLHeadTrackingGetStaticData().
MLHeadTrackingState
typedef struct MLHeadTrackingState MLHeadTrackingState;
A structure containing information on the current state of the Head Tracking system.
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.
API Level:
- 26
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
API Level:
- 26
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
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
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
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 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
API Level:
- 26
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.
API Level:
- 2