Skip to main content
Version: 21 Aug 2024

ml_controller.h

Classes

Name
structMLControllerConfiguration
structMLControllerStream
A structure containing information about the tracking-stream of this controller.
structMLControllerState
A structure containing information about the current state of this controller.
structMLControllerStateEx
A structure containing information about the current state of this controller.
structMLControllerSystemState
A structure containing information about the current state of the controller system.
structMLControllerSystemStateEx
A structure containing information about the current state of the controller system.

Types

Name
typedef struct MLControllerConfigurationMLControllerConfiguration
typedef struct MLControllerStreamMLControllerStream
A structure containing information about the tracking-stream of this controller.
typedef struct MLControllerStateMLControllerState
A structure containing information about the current state of this controller.
typedef struct MLControllerStateExMLControllerStateEx
A structure containing information about the current state of this controller.
typedef struct MLControllerSystemStateMLControllerSystemState
A structure containing information about the current state of the controller system.
typedef struct MLControllerSystemStateExMLControllerSystemStateEx
A structure containing information about the current state of the controller system.

Enums

Name
enumMLControllerMode
{
Deprecated_Mode_0 = 0,
Deprecated_Mode_1 = 1,
MLControllerMode_Fused6Dof = 2,
MLControllerMode_Count,
MLControllerMode_Ensure32Bits = 0x7FFFFFFF
}
A set of possible tracking modes for the Controller system.
enumAnonymous Enum 7
{
MLController_MaxActive = 1
}
enumMLControllerCalibAccuracy
{
MLControllerCalibAccuracy_Bad = 0,
MLControllerCalibAccuracy_Low = 1,
MLControllerCalibAccuracy_Medium = 2,
MLControllerCalibAccuracy_High = 3,
MLControllerCalibAccuracy_Ensure32Bits = 0x7FFFFFFF
}
Calibration Accuracy levels for controller.
enumMLControllerStatus
{
MLControllerStatus_NotActive = 0,
MLControllerStatus_Active_Rotation_Only = 1,
MLControllerStatus_Active = 2,
MLControllerStatus_Ensure32Bits = 0x7FFFFFFF
}
Stream mode for controller stream.

Functions

Name
voidMLControllerSystemStateExInit(MLControllerSystemStateEx * inout_attr)
Initializes values for MLControllerSystemStateEx.
MLResultMLControllerCreateEx(const MLControllerConfiguration mode, MLHandle out_handle)
Creates a controller tracker.
MLResultMLControllerDestroy(MLHandle tracker)
Destroys a controller tracker.
MLResultMLControllerGetState(MLHandle handle, struct MLControllerSystemState * out_state)
Return the most recent controller state.
MLResultMLControllerGetStateEx(MLHandle handle, MLControllerSystemStateEx * out_state)
Return the most recent controller state.

Enums Documentation

MLControllerMode

EnumeratorValueDescription
Deprecated_Mode_00
Deprecated_Mode_11
MLControllerMode_Fused6Dof2High quality 6 degrees of freedom tracking (position and orientation).
MLControllerMode_CountCount of number of modes.
MLControllerMode_Ensure32Bits0x7FFFFFFFEnsure enum is represented as 32 bits.

A set of possible tracking modes for the Controller system.

Deprecated

Deprecated since 1.1.0. Scheduled for removal.


Anonymous Enum 7

EnumeratorValueDescription
MLController_MaxActive1Maximum number of active Controllers.

MLControllerCalibAccuracy

EnumeratorValueDescription
MLControllerCalibAccuracy_Bad0CalAccuracy is Bad.
MLControllerCalibAccuracy_Low1CalAccuracy is Low.
MLControllerCalibAccuracy_Medium2CalAccuracy is Medium.
MLControllerCalibAccuracy_High3CalAccuracy is High.
MLControllerCalibAccuracy_Ensure32Bits0x7FFFFFFFEnsure enum is represented as 32 bits.

Calibration Accuracy levels for controller.

Deprecated

Deprecated since 1.1.0. Scheduled for removal.


MLControllerStatus

EnumeratorValueDescription
MLControllerStatus_NotActive0Controller stream is not active.
MLControllerStatus_Active_Rotation_Only1Controller stream is active (rotation only).
MLControllerStatus_Active2Controller stream is active (both position and rotation).
MLControllerStatus_Ensure32Bits0x7FFFFFFFEnsure enum is represented as 32 bits.

Stream mode for controller stream.

API Level:

  • 21

Types Documentation

MLControllerConfiguration

typedef struct MLControllerConfiguration MLControllerConfiguration;

A structure to configure controller's tracking-modes.

More Info


MLControllerStream

typedef struct MLControllerStream MLControllerStream;

A structure containing information about the tracking-stream of this controller.

More Info

Deprecated

Deprecated since 1.1.0. Scheduled for removal.


MLControllerState

typedef struct MLControllerState MLControllerState;

A structure containing information about the current state of this controller.

More Info

Deprecated

Deprecated since 1.1.0. Scheduled for removal.


MLControllerStateEx

typedef struct MLControllerStateEx MLControllerStateEx;

A structure containing information about the current state of this controller.

More Info

API Level:

  • 21

MLControllerSystemState

typedef struct MLControllerSystemState MLControllerSystemState;

A structure containing information about the current state of the controller system.

More Info

Deprecated

Deprecated since 1.1.0. Scheduled for removal.


MLControllerSystemStateEx

typedef struct MLControllerSystemStateEx MLControllerSystemStateEx;

A structure containing information about the current state of the controller system.

More Info

API Level:

  • 21

Functions Documentation

MLControllerSystemStateExInit

static inline void MLControllerSystemStateExInit(
MLControllerSystemStateEx * inout_attr
)

Initializes values for MLControllerSystemStateEx.

Parameters

MLControllerSystemStateEx *inout_attrThe object to initialize.

API Level:

  • 21

MLControllerCreateEx

MLResult MLControllerCreateEx(
const MLControllerConfiguration * mode,
MLHandle * out_handle
)

Creates a controller tracker.

Parameters

const MLControllerConfiguration *modeA pointer to MLControllerConfiguration struct which contains the tracking modes to use for this session.
MLHandle *out_handleA pointer to an MLHandle which will the handle to the controller tracker. If this operation fails, out_handle will be ML_INVALID_HANDLE.

Returns

MLResultMLResult_InvalidParamFailed to create a controller tracker due to an invalid input parameter.
MLResultMLResult_OkController Succesfully created a controller tracker.
MLResultMLResult_PerceptionSystemNotStartedPerception System has not been started.
MLResultMLResult_PermissionDeniedFailed to create a controller tracker due to lack of permission.

Required Permissions:

  • None

API Level:

  • 4

MLControllerDestroy

MLResult MLControllerDestroy(
MLHandle tracker
)

Destroys a controller tracker.

Parameters

MLHandletrackerMLHandle to the tracker created by MLControllerCreateEx().

Returns

MLResultMLResult_OkSuccessfully destroyed the controller tracker.
MLResultMLResult_PerceptionSystemNotStartedPerception System has not been started.
MLResultMLResult_UnspecifiedFailureFailed to destroy the controller tracker due to an unknown error.

Required Permissions:

  • None

MLControllerGetState

MLResult MLControllerGetState(
MLHandle handle,
struct MLControllerSystemState * out_state
)

Return the most recent controller state.

Parameters

MLHandlehandleHandle to the tracker created by MLControllerCreateEx().
struct MLControllerSystemState *out_statePointer to valid MLControllerSystemState object to be filled with current state information.

Returns

MLResultMLResult_InvalidParamFailed to get the controller state due to an invalid input parameter.
MLResultMLResult_OkSuccessfully filled out_state with current state.
MLResultMLResult_PerceptionSystemNotStartedPerception System has not been started.

Required Permissions:

  • None
Deprecated

Deprecated since 1.1.0. Scheduled for removal.


MLControllerGetStateEx

MLResult MLControllerGetStateEx(
MLHandle handle,
MLControllerSystemStateEx * out_state
)

Return the most recent controller state.

Parameters

MLHandlehandleHandle to the tracker created by MLControllerCreateEx().
MLControllerSystemStateEx *out_statePointer to valid MLControllerSystemStateEx object to be filled with current state information.

Returns

MLResultMLResult_InvalidParamFailed to get the controller state due to an invalid input parameter.
MLResultMLResult_OkSuccessfully filled out_state with current state.
MLResultMLResult_PerceptionSystemNotStartedPerception System has not been started.

Required Permissions:

  • None

API Level:

  • 21

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 <string.h>

#include "ml_api.h"
#include "ml_coordinate_frame_uid.h"

ML_EXTERN_C_BEGIN

typedef enum MLControllerMode {
Deprecated_Mode_0 = 0,
Deprecated_Mode_1 = 1,
MLControllerMode_Fused6Dof = 2,
MLControllerMode_Count,
MLControllerMode_Ensure32Bits = 0x7FFFFFFF
} MLControllerMode;

typedef struct MLControllerConfiguration {
bool deprecated_mode_0;
bool deprecated_mode_1;
bool enable_fused6dof;
} MLControllerConfiguration;

enum {
MLController_MaxActive = 1
};

typedef enum MLControllerCalibAccuracy {
MLControllerCalibAccuracy_Bad = 0,
MLControllerCalibAccuracy_Low = 1,
MLControllerCalibAccuracy_Medium = 2,
MLControllerCalibAccuracy_High = 3,
MLControllerCalibAccuracy_Ensure32Bits = 0x7FFFFFFF
} MLControllerCalibAccuracy;

typedef enum MLControllerStatus {
MLControllerStatus_NotActive = 0,
MLControllerStatus_Active_Rotation_Only = 1,
MLControllerStatus_Active = 2,
MLControllerStatus_Ensure32Bits = 0x7FFFFFFF
} MLControllerStatus;

typedef ML_DEPRECATED_MSG("Replaced by MLControllerStateEx.") struct MLControllerStream {
MLCoordinateFrameUID coord_frame_controller;
bool is_active;
MLControllerMode mode;
} MLControllerStream;

typedef ML_DEPRECATED_MSG("Replaced by MLControllerStateEx.") struct MLControllerState {
uint8_t controller_id;
struct MLControllerStream stream[MLControllerMode_Count];
MLControllerCalibAccuracy accuracy;
} MLControllerState;

typedef struct MLControllerStateEx {
uint8_t controller_id;
MLCoordinateFrameUID coord_frame_controller;
MLCoordinateFrameUID raw_coord_frame_controller;
MLControllerStatus status;
} MLControllerStateEx;

typedef ML_DEPRECATED_MSG("Replaced by MLControllerSystemStateEx.") struct MLControllerSystemState {
struct MLControllerState controller_state[MLController_MaxActive];
MLControllerCalibAccuracy lightwear_accuracy;
} MLControllerSystemState;

typedef struct MLControllerSystemStateEx {
uint32_t version;
MLControllerStateEx controller_state[MLController_MaxActive];
} MLControllerSystemStateEx;

ML_STATIC_INLINE void MLControllerSystemStateExInit(MLControllerSystemStateEx *inout_attr) {
if (NULL != inout_attr) {
memset(inout_attr, 0, sizeof(MLControllerSystemStateEx));
inout_attr->version = 1u;
}
}

ML_API MLResult ML_CALL MLControllerCreateEx(const MLControllerConfiguration *mode, MLHandle *out_handle);

ML_API MLResult ML_CALL MLControllerDestroy(MLHandle tracker);

ML_DEPRECATED_MSG("Replaced by MLControllerGetStateEx.")
ML_API MLResult ML_CALL MLControllerGetState(MLHandle handle, struct MLControllerSystemState *out_state);

ML_API MLResult ML_CALL MLControllerGetStateEx(MLHandle handle, MLControllerSystemStateEx *out_state);

ML_EXTERN_C_END