Version: 20 Mar 2024

ml_controller.h

Classes

	Name
struct	MLControllerConfiguration
struct	MLControllerStream A structure containing information about the tracking-stream of this controller.
struct	MLControllerState A structure containing information about the current state of this controller.
struct	MLControllerStateEx A structure containing information about the current state of this controller.
struct	MLControllerSystemState A structure containing information about the current state of the controller system.
struct	MLControllerSystemStateEx A structure containing information about the current state of the controller system.

Types

	Name
typedef struct MLControllerConfiguration	MLControllerConfiguration
typedef struct MLControllerStream	MLControllerStream A structure containing information about the tracking-stream of this controller.
typedef struct MLControllerState	MLControllerState A structure containing information about the current state of this controller.
typedef struct MLControllerStateEx	MLControllerStateEx A structure containing information about the current state of this controller.
typedef struct MLControllerSystemState	MLControllerSystemState A structure containing information about the current state of the controller system.
typedef struct MLControllerSystemStateEx	MLControllerSystemStateEx A structure containing information about the current state of the controller system.

Enums

	Name
enum	MLControllerMode { 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.
enum	Anonymous Enum 7 { MLController_MaxActive = 1 }
enum	MLControllerCalibAccuracy { MLControllerCalibAccuracy_Bad = 0, MLControllerCalibAccuracy_Low = 1, MLControllerCalibAccuracy_Medium = 2, MLControllerCalibAccuracy_High = 3, MLControllerCalibAccuracy_Ensure32Bits = 0x7FFFFFFF } Calibration Accuracy levels for controller.
enum	MLControllerStatus { MLControllerStatus_NotActive = 0, MLControllerStatus_Active_Rotation_Only = 1, MLControllerStatus_Active = 2, MLControllerStatus_Ensure32Bits = 0x7FFFFFFF } Stream mode for controller stream.

Functions

	Name
void	MLControllerSystemStateExInit(MLControllerSystemStateEx * inout_attr) Initializes values for MLControllerSystemStateEx.
MLResult	MLControllerCreateEx(const MLControllerConfiguration mode, MLHandle out_handle) Creates a controller tracker.
MLResult	MLControllerDestroy(MLHandle tracker) Destroys a controller tracker.
MLResult	MLControllerGetState(MLHandle handle, struct MLControllerSystemState * out_state) Return the most recent controller state.
MLResult	MLControllerGetStateEx(MLHandle handle, MLControllerSystemStateEx * out_state) Return the most recent controller state.

Enums Documentation

MLControllerMode

Enumerator	Value	Description
Deprecated_Mode_0	0
Deprecated_Mode_1	1
MLControllerMode_Fused6Dof	2	High quality 6 degrees of freedom tracking (position and orientation).
MLControllerMode_Count		Count of number of modes.
MLControllerMode_Ensure32Bits	0x7FFFFFFF	Ensure 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

Enumerator	Value	Description
MLController_MaxActive	1	Maximum number of active Controllers.

MLControllerCalibAccuracy

Enumerator	Value	Description
MLControllerCalibAccuracy_Bad	0	CalAccuracy is Bad.
MLControllerCalibAccuracy_Low	1	CalAccuracy is Low.
MLControllerCalibAccuracy_Medium	2	CalAccuracy is Medium.
MLControllerCalibAccuracy_High	3	CalAccuracy is High.
MLControllerCalibAccuracy_Ensure32Bits	0x7FFFFFFF	Ensure enum is represented as 32 bits.

Calibration Accuracy levels for controller.

Deprecated

Deprecated since 1.1.0. Scheduled for removal.

MLControllerStatus

Enumerator	Value	Description
MLControllerStatus_NotActive	0	Controller stream is not active.
MLControllerStatus_Active_Rotation_Only	1	Controller stream is active (rotation only).
MLControllerStatus_Active	2	Controller stream is active (both position and rotation).
MLControllerStatus_Ensure32Bits	0x7FFFFFFF	Ensure enum is represented as 32 bits.

Stream mode for controller stream.

API Level:

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:

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:

Functions Documentation

MLControllerSystemStateExInit

static inline void MLControllerSystemStateExInit(
    MLControllerSystemStateEx * inout_attr
)

Initializes values for MLControllerSystemStateEx.

Parameters


MLControllerSystemStateEx *	inout_attr	The object to initialize.

API Level:

MLControllerCreateEx

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

Creates a controller tracker.

Parameters


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

Returns


MLResult	MLResult_InvalidParam	Failed to create a controller tracker due to an invalid input parameter.
MLResult	MLResult_Ok	Controller Succesfully created a controller tracker.
MLResult	MLResult_PerceptionSystemNotStarted	Perception System has not been started.
MLResult	MLResult_PermissionDenied	Failed to create a controller tracker due to lack of permission.

Required Permissions:

None

API Level:

MLControllerDestroy

MLResult MLControllerDestroy(
    MLHandle tracker
)

Destroys a controller tracker.

Parameters


MLHandle	tracker	MLHandle to the tracker created by MLControllerCreateEx().

Returns


MLResult	MLResult_Ok	Successfully destroyed the controller tracker.
MLResult	MLResult_PerceptionSystemNotStarted	Perception System has not been started.
MLResult	MLResult_UnspecifiedFailure	Failed 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


MLHandle	handle	Handle to the tracker created by MLControllerCreateEx().
struct MLControllerSystemState *	out_state	Pointer to valid MLControllerSystemState object to be filled with current state information.

Returns


MLResult	MLResult_InvalidParam	Failed to get the controller state due to an invalid input parameter.
MLResult	MLResult_Ok	Successfully filled out_state with current state.
MLResult	MLResult_PerceptionSystemNotStarted	Perception 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


MLHandle	handle	Handle to the tracker created by MLControllerCreateEx().
MLControllerSystemStateEx *	out_state	Pointer to valid MLControllerSystemStateEx object to be filled with current state information.

Returns


MLResult	MLResult_InvalidParam	Failed to get the controller state due to an invalid input parameter.
MLResult	MLResult_Ok	Successfully filled out_state with current state.
MLResult	MLResult_PerceptionSystemNotStarted	Perception System has not been started.

Required Permissions:

None

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 <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

ml_controller.h

Classes​

Types​

Enums​

Functions​

Enums Documentation​

MLControllerMode​

Anonymous Enum 7​

MLControllerCalibAccuracy​

MLControllerStatus​

Types Documentation​

MLControllerConfiguration​

MLControllerStream​

MLControllerState​

MLControllerStateEx​

MLControllerSystemState​

MLControllerSystemStateEx​

Functions Documentation​

MLControllerSystemStateExInit​

MLControllerCreateEx​

MLControllerDestroy​

MLControllerGetState​

MLControllerGetStateEx​

Source code​

Classes

Types

Enums

Functions

Enums Documentation

MLControllerMode

Anonymous Enum 7

MLControllerCalibAccuracy

MLControllerStatus

Types Documentation

MLControllerConfiguration

MLControllerStream

MLControllerState

MLControllerStateEx

MLControllerSystemState

MLControllerSystemStateEx

Functions Documentation

MLControllerSystemStateExInit

MLControllerCreateEx

MLControllerDestroy

MLControllerGetState

MLControllerGetStateEx

Source code