Skip to main content
Version: 20 Mar 2024

Input

APIs for the Input system. More...

Classes

Name
structMLInputControllerTouchpadGesture
structMLInputControllerCallbacksEx
A structure containing callbacks for input controller events.
structMLInputControllerState
A structure containing information about the current state of an input controller.
structMLInputControllerStateEx
A structure containing information about the current state of an input controller.
structMLInputConnectedDevicesList
A structure containing information about the connected devices.
structMLInputPreDefinedPattern
A structure containing information about the Pre-Defined pattern to be played.
structMLInputBuzzCommand
A structure containing information about the Buzz command to be played.
structMLInputCustomHaptics
A structure containing information about the Buzz command and/or pre-defined pattern to be played.
structMLInputCustomHapticsInfo
A structure containing a list of Buzz command and/or pre-defined patterns to be played.
unionMLInputCustomHaptics.MLInputCustomHapticsPattern
structMLInputVoiceAppIntentSlot
A structure containing voice app-intent slot in voice event.
structMLVoiceIntentEvent
A structure containing voice intent event.
structMLVoiceIntentCallbacks
A structure containing callbacks for voice intent events.
structMLVoiceIntentSettings
A structure containing settings for voice app intent.

Types

Name
typedef struct MLInputControllerTouchpadGestureMLInputControllerTouchpadGesture
typedef struct MLInputControllerCallbacksExMLInputControllerCallbacksEx
A structure containing callbacks for input controller events.
typedef struct MLInputControllerStateMLInputControllerState
A structure containing information about the current state of an input controller.
typedef struct MLInputControllerStateExMLInputControllerStateEx
A structure containing information about the current state of an input controller.
typedef struct MLInputConnectedDevicesListMLInputConnectedDevicesList
A structure containing information about the connected devices.
typedef struct MLInputPreDefinedPatternMLInputPreDefinedPattern
A structure containing information about the Pre-Defined pattern to be played.
typedef struct MLInputBuzzCommandMLInputBuzzCommand
A structure containing information about the Buzz command to be played.
typedef struct MLInputCustomHapticsMLInputCustomHaptics
A structure containing information about the Buzz command and/or pre-defined pattern to be played.
typedef struct MLInputCustomHapticsInfoMLInputCustomHapticsInfo
A structure containing a list of Buzz command and/or pre-defined patterns to be played.
typedef struct MLInputVoiceAppIntentSlotMLInputVoiceAppIntentSlot
A structure containing voice app-intent slot in voice event.
typedef struct MLVoiceIntentEventMLVoiceIntentEvent
A structure containing voice intent event.
typedef struct MLVoiceIntentCallbacksMLVoiceIntentCallbacks
A structure containing callbacks for voice intent events.
typedef struct MLVoiceIntentSettingsMLVoiceIntentSettings
A structure containing settings for voice app intent.

Enums

Name
enumAnonymous Enum 13
{
MLResultAPIPrefix_Input = ( 0x21DC << 16)
}
enumMLInputResult
{
MLInputResult_ServiceNotAvailable = MLResultAPIPrefix_Input,
MLInputResult_PermissionDenied,
MLInputResult_DeviceNotFound,
MLInputResult_IllegalState,
MLInputResult_InternalError,
MLInputResult_SpeechDisabled,
MLInputResult_Ensure32Bits = 0x7FFFFFFF
}
Return values for Input API calls.
enumAnonymous Enum 14
{
MLInput_MaxControllers = 1,
MLInput_MaxControllerTouchpadTouches = 2
}
enumMLInputControllerTouchpadGestureState
{
MLInputControllerTouchpadGestureState_End,
MLInputControllerTouchpadGestureState_Continue,
MLInputControllerTouchpadGestureState_Start,
MLInputControllerTouchpadGestureState_Ensure32Bits = 0x7FFFFFFF
}
enumMLInputControllerTouchpadGestureType
{
MLInputControllerTouchpadGestureType_None,
MLInputControllerTouchpadGestureType_Tap,
MLInputControllerTouchpadGestureType_ForceTapDown,
MLInputControllerTouchpadGestureType_ForceTapUp,
MLInputControllerTouchpadGestureType_ForceDwell,
MLInputControllerTouchpadGestureType_SecondForceDown,
MLInputControllerTouchpadGestureType_RadialScroll,
MLInputControllerTouchpadGestureType_Swipe,
MLInputControllerTouchpadGestureType_Count,
MLInputControllerTouchpadGestureType_Ensure32Bits = 0x7FFFFFFF
}
enumMLInputControllerTouchpadGestureDirection
{
MLInputControllerTouchpadGestureDirection_None,
MLInputControllerTouchpadGestureDirection_Up,
MLInputControllerTouchpadGestureDirection_Down,
MLInputControllerTouchpadGestureDirection_Left,
MLInputControllerTouchpadGestureDirection_Right,
MLInputControllerTouchpadGestureDirection_Clockwise,
MLInputControllerTouchpadGestureDirection_CounterClockwise,
MLInputControllerTouchpadGestureDirection_Count,
MLInputControllerTouchpadGestureDirection_Ensure32Bits = 0x7FFFFFFF
}
enumMLInputControllerType
{
MLInputControllerType_None,
MLInputControllerType_Device,
MLInputControllerType_Ensure32Bits = 0x7FFFFFFF
}
enumMLInputControllerButton
{
MLInputControllerButton_None,
MLInputControllerButton_Bumper,
MLInputControllerButton_Menu,
MLInputControllerButton_Count,
MLInputControllerButton_Ensure32Bits = 0x7FFFFFFF
}
enumMLInputControllerTriggerEvent
{
MLInputControllerTriggerEvent_Pull,
MLInputControllerTriggerEvent_Release,
MLInputControllerTriggerEvent_Click,
MLInputControllerTriggerEvent_Hold,
MLInputControllerTriggerEvent_Ensure32Bits = 0x7FFFFFFF
}
enumMLInputPreDefinedPatternType
{
MLInputPreDefinedPatternType_A = 0,
MLInputPreDefinedPatternType_B = 1,
MLInputPreDefinedPatternType_C = 2,
MLInputPreDefinedPatternType_Ensure32Bits = 0x7FFFFFFF
}
enumMLInputCustomHapticsType
{
MLInputCustomHapticsType_None = 0,
MLInputCustomHapticsType_Buzz = 1,
MLInputCustomHapticsType_Predefined = 2,
MLInputCustomHapticsType_Ensure32Bits = 0x7FFFFFFF
}
enumMLInputControllerHand
{
MLInputControllerHand_None = 0,
MLInputControllerHand_Left = 1,
MLInputControllerHand_Right = 2,
MLInputControllerHand_Both = 3,
MLInputControllerHand_Ensure32Bits = 0x7FFFFFFF
}
Hand in which the controller is held.
enumAnonymous Enum 30
{
MLResultAPIPrefix_Voice = ( 0xbe7a << 16)
}
enumMLVoiceResult
{
MLVoiceResult_IntentDisabled = MLResultAPIPrefix_Voice,
MLVoiceResult_Ensure32Bits = 0x7FFFFFFF
}
Return values for Voice API calls.
enumMLVoiceState
{
MLVoiceState_IntentHotwordDetected = 0,
MLVoiceState_IntentSessionEnded = 1,
MLVoiceState_IntentSessionEndedAborted = 2,
MLVoiceState_IntentSessionEndedNoIntent = 3,
MLVoiceState_IntentSessionEndedTimeout = 4,
MLVoiceState_IntentSessionEndedError = 5,
MLVoiceState_IntentReady = 6,
MLVoiceState_IntentNotAvailable = 7,
MLVoiceState_IntentInvalidAppIntent = 8,
MLVoiceState_Ensure32Bits = 0x7FFFFFFF
}
Voice state in voice event.
enumMLVoiceIntentNoIntentReason
{
MLVoiceIntentNoIntentReason_NoReason = 0,
MLVoiceIntentNoIntentReason_Silence = 1,
MLVoiceIntentNoIntentReason_NoMatch = 2,
MLVoiceIntentNoIntentReason_Ensure32Bits = 0x7FFFFFFF
}
No intent reason code in voice event.

Functions

Name
voidMLInputControllerCallbacksExInit(MLInputControllerCallbacksEx * inout_callbacks)
Initializes default values for MLInputControllerCallbacksEx.
voidMLInputControllerStateExInit(MLInputControllerStateEx inout_attr[MLInput_MaxControllers])
Initializes values for MLInputControllerStateEx.
voidMLInputConnectedDevicesListInit(MLInputConnectedDevicesList * inout_devices_list)
Initializes default values for MLInputConnectedDevicesList.
voidMLInputPreDefinedPatternInit(MLInputPreDefinedPattern * inout_pattern)
Initializes default values for MLInputPreDefinedPattern.
voidMLInputBuzzCommandInit(MLInputBuzzCommand * inout_command)
Initializes default values for MLInputBuzzCommand.
voidMLInputCustomHapticsInfoInit(MLInputCustomHapticsInfo * inout_info)
Initializes an array of MLInputCustomHaptics with default values.
const char *MLInputGetResultString(MLResult result)
Returns an ASCII string for MLInputsResult and MLResult codes.
MLResultMLInputCreate(MLHandle * out_handle)
Creates an input tracker.
MLResultMLInputSetControllerCallbacksEx(MLHandle handle, const MLInputControllerCallbacksEx controller_callbacks, void user_data)
Sets the callbacks for controller input events.
MLResultMLInputGetControllerState(MLHandle handle, struct MLInputControllerState out_state[MLInput_MaxControllers])
Returns current state of all possible input controllers.
MLResultMLInputGetControllerStateEx(MLHandle handle, MLInputControllerStateEx out_state[MLInput_MaxControllers])
Returns current state of all possible input controllers.
MLResultMLInputGetConnectedDevices(MLHandle handle, MLInputConnectedDevicesList * inout_devices)
Gets the device IDs of all connected devices.
MLResultMLInputReleaseConnectedDevicesList(MLHandle handle, MLInputConnectedDevicesList * devices)
Releases the contents of MLInputConnectedDevicesList populated by MLInputGetConnectedDevices.
MLResultMLInputStartControllerFeedbackPreDefinedPattern(MLHandle handle, uint8_t controller_id, MLInputPreDefinedPattern * pattern)
Plays the pre-defined pattern.
MLResultMLInputStartControllerFeedbackBuzzCommand(MLHandle handle, uint8_t controller_id, const MLInputBuzzCommand * command)
Plays controller haptic buzz command.
MLResultMLInputCreateCustomHapticsPattern(MLHandle handle, MLInputCustomHapticsInfo info, uint32_t inout_pattern_id)
Creates a custom haptic pattern.
MLResultMLInputStartControllerFeedbackCustomHapticsPattern(MLHandle handle, uint8_t controller_id, uint32_t pattern_id)
Plays the custom haptic pattern created by MLInputCreateCustomHapticsPattern.
MLResultMLInputDeleteCustomHapticsPattern(MLHandle handle, uint32_t pattern_id)
Deletes the custom haptic pattern created by MLInputCreateCustomHapticsPattern.
MLResultMLInputStopControllerFeedback(MLHandle handle, uint8_t controller_id)
Stops the currently playing haptic pattern.
MLResultMLInputDestroy(MLHandle handle)
Destroys an input tracker.
voidMLVoiceIntentCallbacksInit(MLVoiceIntentCallbacks * inout_callbacks)
Initializes default values for MLVoiceIntentCallbacks.
voidMLVoiceIntentSettingsInit(MLVoiceIntentSettings * inout_settings)
Initializes default values for MLVoiceIntentSettings.
MLResultMLVoiceIntentCreate(MLHandle * out_handle)
Creates a voice intent client.
MLResultMLVoiceIntentDestroy(MLHandle handle)
Destroys a voice intent client.
MLResultMLVoiceIntentConfigureSettings(MLHandle handle, const MLVoiceIntentSettings * voice_settings)
Sets the settings for voice intent events.
MLResultMLVoiceIntentSetCallbacks(MLHandle handle, const MLVoiceIntentCallbacks voice_callbacks, void user_data)
Sets the callbacks for voice intent events.
MLResultMLVoiceIntentStartProcessing(MLHandle handle)
Starts voice intent processing.
MLResultMLVoiceIntentStopProcessing(MLHandle handle)
Stops voice intent processing.
MLResultMLVoiceIntentIsEnabled(MLHandle handle, bool * out_is_enabled)
Checks voice intent feature is enabled in the system.
const char *MLVoiceGetResultString(MLResult result)
Returns an ASCII string for MLVoiceResult and MLResult codes.

Detailed Description

APIs for the Input system.

APIs for the voice service system.

Shared Object:

  • input.magicleap*

Shared Object:

  • input.magicleap*

Enums Documentation

Anonymous Enum 13

EnumeratorValueDescription
MLResultAPIPrefix_Input( 0x21DC << 16)Defines the prefix for MLInputResult codes.

MLInputResult

EnumeratorValueDescription
MLInputResult_ServiceNotAvailableMLResultAPIPrefix_Input
MLInputResult_PermissionDeniedOperation failed because a required permission has not been granted. Example: This can happen when the app is not in the foreground.
MLInputResult_DeviceNotFoundOperation failed because a required device was not found.
MLInputResult_IllegalStateOperation failed because the service was in an illegal state. Example: This can occur when the service is still initializing.
MLInputResult_InternalErrorOperation failed because of an internal error.
MLInputResult_SpeechDisabledOperation failed because a required speech feature is disabled in system settings.
MLInputResult_Ensure32Bits0x7FFFFFFFEnsure enum is represented as 32 bits.

Return values for Input API calls.


Anonymous Enum 14

EnumeratorValueDescription
MLInput_MaxControllers1Maximum recognized number of input controllers.
MLInput_MaxControllerTouchpadTouches2Maximum recognized number of controller touchpad touches.

MLInputControllerTouchpadGestureState

EnumeratorValueDescription
MLInputControllerTouchpadGestureState_EndEnd(Default).
MLInputControllerTouchpadGestureState_ContinueContinue.
MLInputControllerTouchpadGestureState_StartStart.
MLInputControllerTouchpadGestureState_Ensure32Bits0x7FFFFFFFEnsure enum is represented as 32 bits.

Touchpad gesture state.


MLInputControllerTouchpadGestureType

EnumeratorValueDescription
MLInputControllerTouchpadGestureType_NoneNone.
MLInputControllerTouchpadGestureType_TapTap. This is a discrete gesture.
MLInputControllerTouchpadGestureType_ForceTapDownForce tap down. This is a discrete gesture.
MLInputControllerTouchpadGestureType_ForceTapUpForce tap up. This is a discrete gesture.
MLInputControllerTouchpadGestureType_ForceDwellForce dwell. This is a discrete gesture.
MLInputControllerTouchpadGestureType_SecondForceDownSecond force down. This is a discrete gesture.
MLInputControllerTouchpadGestureType_RadialScrollRadial scroll. This is a continuous gesture.
MLInputControllerTouchpadGestureType_SwipeSwipe. This is a continuous gesture.
MLInputControllerTouchpadGestureType_CountNumber of gesture types.
MLInputControllerTouchpadGestureType_Ensure32Bits0x7FFFFFFFEnsure enum is represented as 32 bits.

Recognized touchpad gesture types.


MLInputControllerTouchpadGestureDirection

EnumeratorValueDescription
MLInputControllerTouchpadGestureDirection_NoneNone.
MLInputControllerTouchpadGestureDirection_UpUp.
MLInputControllerTouchpadGestureDirection_DownDown.
MLInputControllerTouchpadGestureDirection_LeftLeft.
MLInputControllerTouchpadGestureDirection_RightRight.
MLInputControllerTouchpadGestureDirection_ClockwiseClockwise.
MLInputControllerTouchpadGestureDirection_CounterClockwiseCounter clockwise.
MLInputControllerTouchpadGestureDirection_CountNumber of directions.
MLInputControllerTouchpadGestureDirection_Ensure32Bits0x7FFFFFFFEnsure enum is represented as 32 bits.

Direction of touchpad gesture.


MLInputControllerType

EnumeratorValueDescription
MLInputControllerType_NoneNone.
MLInputControllerType_DeviceDevice.
MLInputControllerType_Ensure32Bits0x7FFFFFFFEnsure enum is represented as 32 bits.

Types of input controllers recognized by Magic Leap platform.


MLInputControllerButton

EnumeratorValueDescription
MLInputControllerButton_None
MLInputControllerButton_BumperBumper.
MLInputControllerButton_MenuMenu.
MLInputControllerButton_CountNumber of buttons.
MLInputControllerButton_Ensure32Bits0x7FFFFFFFEnsure enum is represented as 32 bits.

Buttons on input controllers.


MLInputControllerTriggerEvent

EnumeratorValueDescription
MLInputControllerTriggerEvent_PullThis is used when trigger is pulled down, and the normalized value is > 0.
MLInputControllerTriggerEvent_ReleaseThis is used when trigger is fully released, and the normalized value is 0.
MLInputControllerTriggerEvent_ClickThis is used when trigger is pulled and released within a short duration.
MLInputControllerTriggerEvent_HoldThis is used when trigger is pulled and held for a longer duration.
MLInputControllerTriggerEvent_Ensure32Bits0x7FFFFFFFEnsure enum is represented as 32 bits.

Trigger events types.


MLInputPreDefinedPatternType

EnumeratorValueDescription
MLInputPreDefinedPatternType_A0Pre-defined pattern used for VKB hover.
MLInputPreDefinedPatternType_B1Pre-Defined pattern used for VKB select.
MLInputPreDefinedPatternType_C2Pre-Defined pattern used for homemenu hover.
MLInputPreDefinedPatternType_Ensure32Bits0x7FFFFFFFEnsure enum is represented as 32 bits.

Custom haptics pattern types.


MLInputCustomHapticsType

EnumeratorValueDescription
MLInputCustomHapticsType_None0None.
MLInputCustomHapticsType_Buzz1Pattern is a buzz command.
MLInputCustomHapticsType_Predefined2Pattern is a pre-defined pattern.
MLInputCustomHapticsType_Ensure32Bits0x7FFFFFFFEnsure enum is represented as 32 bits.

Custom haptics pattern types.


MLInputControllerHand

EnumeratorValueDescription
MLInputControllerHand_None0None.
MLInputControllerHand_Left1Left hand.
MLInputControllerHand_Right2Right hand.
MLInputControllerHand_Both3Both hand.
MLInputControllerHand_Ensure32Bits0x7FFFFFFFEnsure enum is represented as 32 bits.

Hand in which the controller is held.

API Level:

  • 21

Anonymous Enum 30

EnumeratorValueDescription
MLResultAPIPrefix_Voice( 0xbe7a << 16)Defines the prefix for MLVoiceResult codes.

MLVoiceResult

EnumeratorValueDescription
MLVoiceResult_IntentDisabledMLResultAPIPrefix_VoiceOperation failed because a required voice intent feature is disabled in system settings.
MLVoiceResult_Ensure32Bits0x7FFFFFFFEnsure enum is represented as 32 bits.

Return values for Voice API calls.

API Level:

  • 20

MLVoiceState

EnumeratorValueDescription
MLVoiceState_IntentHotwordDetected0Intent hotword detected, Automatic Speech Recognition (ASR) session is going to start.
MLVoiceState_IntentSessionEnded1Voice UI is stopped, ASR session is going to stop.
MLVoiceState_IntentSessionEndedAborted2ASR session is stopped due to abort.
MLVoiceState_IntentSessionEndedNoIntent3ASR session is stopped without detecting an intent.
MLVoiceState_IntentSessionEndedTimeout4ASR session is stopped due to timeout.
MLVoiceState_IntentSessionEndedError5ASR session is stopped due to error.
MLVoiceState_IntentReady6Intent mode is started and ready.
MLVoiceState_IntentNotAvailable7Intent mode is stopped and not available.
MLVoiceState_IntentInvalidAppIntent8Invalid app intent, double check content of JSON submitted with MLVoiceIntentConfigureSettings(). Please refer to Voice Intent Development Toolkit from Magic Leap Hub to generate app intent content.
MLVoiceState_Ensure32Bits0x7FFFFFFFEnsure enum is represented as 32 bits.

Voice state in voice event.

API Level:

  • 31

MLVoiceIntentNoIntentReason

EnumeratorValueDescription
MLVoiceIntentNoIntentReason_NoReason0In case of success.
MLVoiceIntentNoIntentReason_Silence1When the MLVoiceState in MLVoiceIntentEvent is either MLVoiceState_IntentSessionEndedTimeout or MLVoiceState_IntentSessionEndedError.
MLVoiceIntentNoIntentReason_NoMatch2When the MLVoiceState in MLVoiceIntentEvent is MLVoiceState_IntentSessionEndedNoIntent.
MLVoiceIntentNoIntentReason_Ensure32Bits0x7FFFFFFFEnsure enum is represented as 32 bits.

No intent reason code in voice event.

API Level:

  • 20

Types Documentation

MLInputControllerTouchpadGesture

typedef struct MLInputControllerTouchpadGesture MLInputControllerTouchpadGesture;

A structure containing information about recognized touchpad gesture.

More Info


MLInputControllerCallbacksEx

typedef struct MLInputControllerCallbacksEx MLInputControllerCallbacksEx;

A structure containing callbacks for input controller events.

The final parameter to all the callbacks is a void *, which will point to whatever payload data the user provides in MLInputSetControllerCallbacksEx. Individual callbacks which are not required by the client can be NULL.

This structure must be initialized by calling MLInputControllerCallbacksExInit() before use.

More Info

API Level:

  • 20

MLInputControllerState

typedef struct MLInputControllerState MLInputControllerState;

A structure containing information about the current state of an input controller.

More Info

Deprecated

Deprecated since 1.1.0. Scheduled for removal.


MLInputControllerStateEx

typedef struct MLInputControllerStateEx MLInputControllerStateEx;

A structure containing information about the current state of an input controller.

More Info

API Level:

  • 21

MLInputConnectedDevicesList

typedef struct MLInputConnectedDevicesList MLInputConnectedDevicesList;

A structure containing information about the connected devices.

More Info

API Level:

  • 20

MLInputPreDefinedPattern

typedef struct MLInputPreDefinedPattern MLInputPreDefinedPattern;

A structure containing information about the Pre-Defined pattern to be played.

When playing haptic pre-defined pattern, needed information is stored in this structure.

More Info

API Level:

  • 20

MLInputBuzzCommand

typedef struct MLInputBuzzCommand MLInputBuzzCommand;

A structure containing information about the Buzz command to be played.

When playing haptic buzz command, needed information is stored in this structure.

More Info

API Level:

  • 20

MLInputCustomHaptics

typedef struct MLInputCustomHaptics MLInputCustomHaptics;

A structure containing information about the Buzz command and/or pre-defined pattern to be played.

A custom haptics pattern can be played by combining Buzz haptic command and/or a pre-defined pattern, this structure will hold info of a pattern to be added to the custom haptics array. A MLInputCustomHapticsType should be set while initializing the struct to indicate whether the to-be set pattern is a buzz command or a pre-defined pattern.

The #duration will set the time for which a pattern is played:

  • If the inherited duration of a pre-defined pattern is greater, then it will be cut short and the next pattern will start playing.
  • If the inherited duration of a pre-defined pattern is smaller, then it will not repeat itself and will wait for the #duration to complete before starting to play the next pattern.
  • Buzz command's duration will supersede the #duration. Above caveat is true in case buzz command's duration is smaller.
  • The last pattern of the array will continue playing even if the inherited duration is longer than #duration unless the pattern is interrupted by another pattern in the pipeline.

More Info


MLInputCustomHapticsInfo

typedef struct MLInputCustomHapticsInfo MLInputCustomHapticsInfo;

A structure containing a list of Buzz command and/or pre-defined patterns to be played.

A custom haptics pattern can be played by combining Buzz haptic command and/or a pre-defined pattern, this structure holds a list of such a combination.

More Info

API Level:

  • 20

MLInputVoiceAppIntentSlot

typedef struct MLInputVoiceAppIntentSlot MLInputVoiceAppIntentSlot;

A structure containing voice app-intent slot in voice event.

More Info

API Level:

  • 24

MLVoiceIntentEvent

typedef struct MLVoiceIntentEvent MLVoiceIntentEvent;

A structure containing voice intent event.

More Info

API Level:

  • 24

MLVoiceIntentCallbacks

typedef struct MLVoiceIntentCallbacks MLVoiceIntentCallbacks;

A structure containing callbacks for voice intent events.

The final parameter to all the callbacks is a void *, which will point to whatever payload data the user provides in MLVoiceIntentSetCallbacks. Individual callbacks which are not required by the client can be NULL.

This structure must be initialized by calling MLVoiceIntentCallbacksInit() before use.

More Info

API Level:

  • 24

MLVoiceIntentSettings

typedef struct MLVoiceIntentSettings MLVoiceIntentSettings;

A structure containing settings for voice app intent.

This structure must be initialized by calling MLVoiceIntentSettingsInit() before use.

More Info

API Level:

  • 20

Functions Documentation

MLInputControllerCallbacksExInit

static inline void MLInputControllerCallbacksExInit(
MLInputControllerCallbacksEx * inout_callbacks
)

Initializes default values for MLInputControllerCallbacksEx.

Parameters

MLInputControllerCallbacksEx *inout_callbacksThe object to initialize with default settings.

API Level:

  • 20

MLInputControllerStateExInit

static inline void MLInputControllerStateExInit(
MLInputControllerStateEx inout_attr[MLInput_MaxControllers]
)

Initializes values for MLInputControllerStateEx.

Parameters

MLInputControllerStateExinout_attrThe object to initialize.

API Level:

  • 21

MLInputConnectedDevicesListInit

static inline void MLInputConnectedDevicesListInit(
MLInputConnectedDevicesList * inout_devices_list
)

Initializes default values for MLInputConnectedDevicesList.

Parameters

MLInputConnectedDevicesList *inout_devices_listThe object to initialize with default settings.

API Level:

  • 20

MLInputPreDefinedPatternInit

static inline void MLInputPreDefinedPatternInit(
MLInputPreDefinedPattern * inout_pattern
)

Initializes default values for MLInputPreDefinedPattern.

Parameters

MLInputPreDefinedPattern *inout_patternThe object to initialize with default settings.

MLInputBuzzCommandInit

static inline void MLInputBuzzCommandInit(
MLInputBuzzCommand * inout_command
)

Initializes default values for MLInputBuzzCommand.

Parameters

MLInputBuzzCommand *inout_commandThe object to initialize with default settings.

MLInputCustomHapticsInfoInit

static inline void MLInputCustomHapticsInfoInit(
MLInputCustomHapticsInfo * inout_info
)

Initializes an array of MLInputCustomHaptics with default values.

Parameters

MLInputCustomHapticsInfo *inout_infoThe object to MLInputCustomHapticsInfo struct to initialize the array elements with default settings.

MLInputGetResultString

const char * MLInputGetResultString(
MLResult result
)

Returns an ASCII string for MLInputsResult and MLResult codes.

Parameters

MLResultresultThe input MLResult enum from MLInput functions.

Required Permissions:

  • None

Return: ASCII string containing readable version of result code.

API Level:

  • 8

MLInputCreate

MLResult MLInputCreate(
MLHandle * out_handle
)

Creates an input tracker.

Parameters

MLHandle *out_handleA handle to the created input tracker. Only valid if the return value is MLResult_Ok.

Returns

MLResultMLResult_InvalidParamFailed to create the input tracker to an invalid input parameter.
MLResultMLResult_OkSuccessfully created the input tracker.
MLResultMLResult_UnspecifiedFailureFailed to create the input tracker due to an unknown error.
MLResultMLInputResult_IllegalStateFailed to create the input tracker due to an unexpected state.

Required Permissions:

  • None

API Level:

  • 20

MLInputSetControllerCallbacksEx

MLResult MLInputSetControllerCallbacksEx(
MLHandle handle,
const MLInputControllerCallbacksEx * controller_callbacks,
void * user_data
)

Sets the callbacks for controller input events.

Parameters

MLHandlehandleHandle to the input tracker.
const MLInputControllerCallbacksEx *controller_callbacksPointer to MLInputControllerCallbacksEx structure (can be NULL).
void *user_dataPointer to user payload data; this will be the first argument passed to all the callback functions (can be NULL).

Returns

MLResultMLResult_InvalidParamFailed to set the callback for controller input events due to an invalid input parameter.
MLResultMLResult_OkSuccessfully set the callback for controller input events.
MLResultMLResult_UnspecifiedFailureFailed to set the callback for the controller input events due to an unknown error.

Required Permissions:

  • None

API Level:

  • 8

MLInputGetControllerState

MLResult MLInputGetControllerState(
MLHandle handle,
struct MLInputControllerState out_state[MLInput_MaxControllers]
)

Returns current state of all possible input controllers.

Parameters

MLHandlehandleHandle to the input tracker.
struct MLInputControllerStateout_stateArray of MLInputControllerState structures that will be populated. The size of this array is at least the size MLInput_MaxControllers.

Returns

MLResultMLResult_InvalidParamFailed to fetch the controller state due to an invalid input parameter.
MLResultMLResult_OkSuccessfully fetched the controller state.
MLResultMLResult_UnspecifiedFailureFailed to fetch the controller state due to an unknown error.

Required Permissions:

  • None
Deprecated

Deprecated since 1.1.0. Scheduled for removal.


MLInputGetControllerStateEx

MLResult MLInputGetControllerStateEx(
MLHandle handle,
MLInputControllerStateEx out_state[MLInput_MaxControllers]
)

Returns current state of all possible input controllers.

Parameters

MLHandlehandleHandle to the input tracker.
MLInputControllerStateExout_stateArray of MLInputControllerStateEx structures that will be populated. The size of this array is at least the size MLInput_MaxControllers.

Returns

MLResultMLResult_InvalidParamFailed to fetch the controller state due to an invalid input parameter.
MLResultMLResult_OkSuccessfully fetched the controller state.
MLResultMLResult_UnspecifiedFailureFailed to fetch the controller state due to an unknown error.

Required Permissions:

  • None

API Level:

  • 21

MLInputGetConnectedDevices

MLResult MLInputGetConnectedDevices(
MLHandle handle,
MLInputConnectedDevicesList * inout_devices
)

Gets the device IDs of all connected devices.

Parameters

MLHandlehandleHandle to the input tracker.
MLInputConnectedDevicesList *inout_devicesPointer to MLInputConnectedDevicesList structure that will be populated. The app should call MLInputReleaseConnectedDevicesList to release the contents after use.

Returns

MLResultMLResult_InvalidParamFailed to get the IDs of all connected devices due to an invalid input parameter.
MLResultMLResult_OkSuccessfully fetched the IDs of the connected devices.
MLResultMLResult_UnspecifiedFailureFailed to get the IDs of all connected devices due to an unknown error.

Required Permissions:

  • None

API Level:

  • 5

MLInputReleaseConnectedDevicesList

MLResult MLInputReleaseConnectedDevicesList(
MLHandle handle,
MLInputConnectedDevicesList * devices
)

Releases the contents of MLInputConnectedDevicesList populated by MLInputGetConnectedDevices.

Parameters

MLHandlehandleHandle to the input tracker.
MLInputConnectedDevicesList *devicesPointer to MLInputConnectedDevicesList struct. Its contents will be released.

Returns

MLResultMLResult_OkSuccessfully released the contents of the device list.
MLResultMLResult_InvalidParamFailed to release the contents of the device list due to an invalid input parameter.
MLResultMLResult_UnspecifiedFailureFailed to release the contents of the device list due to an unknown error.

Required Permissions:

  • None

API Level:

  • 5

MLInputStartControllerFeedbackPreDefinedPattern

MLResult MLInputStartControllerFeedbackPreDefinedPattern(
MLHandle handle,
uint8_t controller_id,
MLInputPreDefinedPattern * pattern
)

Plays the pre-defined pattern.

Parameters

MLHandlehandleHandle to the input tracker.
uint8_tcontroller_idId of the input controller 0 ~ MLInput_MaxControllers.
MLInputPreDefinedPattern *patternA pointer to #MLInputPredefinedPattern structure (can be NULL).

Returns

MLResultMLInputResult_IllegalStateThe service is either not initialized or terminated or the app is not in focus.
MLResultMLResult_DeviceNotFoundThe haptic device could not be found.
MLResultMLResult_InvalidParamFailed to start a pre-defined pattern due to an invalid input parameter.
MLResultMLResult_OkSuccessfully started a pre-defined pattern on the specified controller.
MLResultMLResult_UnspecifiedFailureFailed to start a pre-defined pattern due to an unknown error.

Required Permissions:

  • None

API Level:

  • 20

MLInputStartControllerFeedbackBuzzCommand

MLResult MLInputStartControllerFeedbackBuzzCommand(
MLHandle handle,
uint8_t controller_id,
const MLInputBuzzCommand * command
)

Plays controller haptic buzz command.

Parameters

MLHandlehandleHandle to the input tracker.
uint8_tcontroller_idId of the input controller 0 ~ MLInput_MaxControllers.
const MLInputBuzzCommand *commandA pointer to MLInputBuzzCommand structure (can be NULL).

Returns

MLResultMLInputResult_IllegalStateThe service is either not initialized or terminated or the app is not in focus.
MLResultMLResult_DeviceNotFoundThe haptic device could not be found.
MLResultMLResult_InvalidParamFailed to start the buzz command due to an invalid input parameter.
MLResultMLResult_OkSuccessfully started the buzz command on the specified controller.
MLResultMLResult_UnspecifiedFailureFailed to start the buzz command due to an unknown error.

Required Permissions:

  • None

API Level:

  • 20

MLInputCreateCustomHapticsPattern

MLResult MLInputCreateCustomHapticsPattern(
MLHandle handle,
MLInputCustomHapticsInfo * info,
uint32_t * inout_pattern_id
)

Creates a custom haptic pattern.

Parameters

MLHandlehandleHandle to the input tracker.
MLInputCustomHapticsInfo *infoPointer to MLInputCustomHapticsInfo struct.
uint32_t *inout_pattern_idA pattern Id created by the API, to be used by MLInputStartControllerFeedbackCustomHapticsPattern.

Returns

MLResultMLInputResult_IllegalStateThe service is either not initialized or terminated.
MLResultMLResult_InvalidParamFailed to create a custom haptic pattern due to an invalid input parameter.
MLResultMLResult_OkSuccessfully created a custom haptic pattern.
MLResultMLResult_UnspecifiedFailureFailed to create a custom haptic pattern due to an unknown error.

Required Permissions:

  • None

A custom haptics pattern is defined as a set of either buzz command and/or pre-defined patterns. Each pattern is played for a duration defined as the #duration_ms member of each element of the MLInputCustomHaptics array.

API Level:

  • 20

MLInputStartControllerFeedbackCustomHapticsPattern

MLResult MLInputStartControllerFeedbackCustomHapticsPattern(
MLHandle handle,
uint8_t controller_id,
uint32_t pattern_id
)

Plays the custom haptic pattern created by MLInputCreateCustomHapticsPattern.

Parameters

MLHandlehandleHandle to the input tracker.
uint8_tcontroller_idId of the input controller 0 ~ MLInput_MaxControllers.
uint32_tpattern_idCustom pattern id created by MLInputCreateCustomHapticsPattern.

Returns

MLResultMLInputResult_IllegalStateThe service is either not initialized or terminated or the app is not in focus.
MLResultMLResult_DeviceNotFoundThe haptic device could not be found.
MLResultMLResult_InvalidParamFailed to start the custom haptic pattern due to an invalid input parameter.
MLResultMLResult_OkSuccessfully started the custom haptic pattern on the specified controller.
MLResultMLResult_UnspecifiedFailureFailed to start the custom haptic pattern due to an unknown error.

Required Permissions:

  • None

API Level:

  • 20

MLInputDeleteCustomHapticsPattern

MLResult MLInputDeleteCustomHapticsPattern(
MLHandle handle,
uint32_t pattern_id
)

Deletes the custom haptic pattern created by MLInputCreateCustomHapticsPattern.

Parameters

MLHandlehandleHandle to the input tracker.
uint32_tpattern_idCustom pattern Id created by MLInputCreateCustomHapticsPattern.

Returns

MLResultMLInputResult_IllegalStateThe service is either not initialized or terminated.
MLResultMLResult_InvalidParamFailed to destroy the custom haptic pattern due to an invalid input parameter.
MLResultMLResult_OkSuccessfully destroyed the custom haptic pattern on the specified controller.
MLResultMLResult_UnspecifiedFailureFailed to destroy the custom haptic pattern due to an unknown error.

Required Permissions:

  • None

API Level:

  • 20

MLInputStopControllerFeedback

MLResult MLInputStopControllerFeedback(
MLHandle handle,
uint8_t controller_id
)

Stops the currently playing haptic pattern.

Parameters

MLHandlehandleHandle to the input tracker.
uint8_tcontroller_idId of the input controller 0 ~ MLInput_MaxControllers.

Returns

MLResultMLInputResult_IllegalStateThe service is either not initialized or terminated or the app is not in focus.
MLResultMLResult_DeviceNotFoundThe haptic device could not be found.
MLResultMLResult_InvalidParamFailed to stop the pattern due to an invalid input parameter.
MLResultMLResult_OkSuccessfully stopped the pattern on the specified controller.
MLResultMLResult_UnspecifiedFailureFailed to stop the pattern due to an unknown error.

Required Permissions:

  • None

API Level:

  • 20

MLInputDestroy

MLResult MLInputDestroy(
MLHandle handle
)

Destroys an input tracker.

Parameters

MLHandlehandleMLHandle to the input tracker to destroy.

Returns

MLResultMLResult_InvalidParamFailed to destroy the input tracker due to an invalid input parameter.
MLResultMLResult_OkSuccessfully destroyed the input tracker.
MLResultMLResult_UnspecifiedFailureFailed to destroy the input handler due to an unknown error.
MLResultMLInputResult_IllegalStateFailed to destroy the input handler due to an unexpected state.

Required Permissions:

  • None

MLVoiceIntentCallbacksInit

static inline void MLVoiceIntentCallbacksInit(
MLVoiceIntentCallbacks * inout_callbacks
)

Initializes default values for MLVoiceIntentCallbacks.

Parameters

MLVoiceIntentCallbacks *inout_callbacksThe object to initialize with default settings.

Required Permissions:

  • None

API Level:

  • 24

MLVoiceIntentSettingsInit

static inline void MLVoiceIntentSettingsInit(
MLVoiceIntentSettings * inout_settings
)

Initializes default values for MLVoiceIntentSettings.

Parameters

MLVoiceIntentSettings *inout_settingsThe object to initialize with default settings.

Required Permissions:

  • None

API Level:

  • 20

MLVoiceIntentCreate

MLResult MLVoiceIntentCreate(
MLHandle * out_handle
)

Creates a voice intent client.

Parameters

MLHandle *out_handleA handle to the created voice intent client. Only valid if the return value is MLResult_Ok.

Returns

MLResultMLResult_InvalidParamFailed to create the voice intent client due to an invalid input parameter.
MLResultMLResult_OkSuccessfully created the voice intent client.
MLResultMLResult_PermissionDeniedFailed to create client due to missing permission.

Required Permissions:

  • com.magicleap.permission.VOICE_INPUT (protection level: dangerous)

API Level:

  • 20

MLVoiceIntentDestroy

MLResult MLVoiceIntentDestroy(
MLHandle handle
)

Destroys a voice intent client.

Parameters

MLHandlehandleMLHandle to the voice intent client to destroy.

Returns

MLResultMLResult_InvalidParamFailed to destroy the voice intent client due to an invalid input parameter.
MLResultMLResult_OkSuccessfully destroyed the voice intent client.

Required Permissions:

  • None

MLVoiceIntentConfigureSettings

MLResult MLVoiceIntentConfigureSettings(
MLHandle handle,
const MLVoiceIntentSettings * voice_settings
)

Sets the settings for voice intent events.

Parameters

MLHandlehandleHandle to the voice intent client.
const MLVoiceIntentSettings *voice_settingsPointer to MLVoiceIntentSettings structure.

Returns

MLResultMLResult_InvalidParamFailed to set settings for voice intent events due to an invalid param.
MLResultMLResult_OkSuccessfully set settings for voice intent events.
MLResultMLVoiceResult_IntentDisabledFailed to set the settings because required voice intent feature is disabled.
MLResultMLResult_UnspecifiedFailureThe operation failed with an unspecified error.

Required Permissions:

  • None

App needs to call MLVoiceIntentConfigureSettings at least once before it calls MLVoiceIntentStartProcessing. App can call MLVoiceIntentConfigureSettings anytime it needs to update the voice intents. But such call will trigger updating intent grammar inside speech engine, which may result in a short delay (could be a few seconds depending on the device's workload). So it is not recommended to call the function frequently.

API Level:

  • 20

MLVoiceIntentSetCallbacks

MLResult MLVoiceIntentSetCallbacks(
MLHandle handle,
const MLVoiceIntentCallbacks * voice_callbacks,
void * user_data
)

Sets the callbacks for voice intent events.

Parameters

MLHandlehandleHandle to the voice intent client.
const MLVoiceIntentCallbacks *voice_callbacksPointer to MLVoiceIntentCallbacks structure. Set this to NULL to unregister callbacks.
void *user_dataPointer to user payload data (can be NULL).

Returns

MLResultMLResult_InvalidParamFailed to set callbacks for voice intent events due to an invalid param.
MLResultMLResult_OkSuccessfully set callbacks for voice intent events.
MLResultMLVoiceResult_IntentDisabledFailed to set the callbacks because required voice intent feature is disabled in system settings.
MLResultMLResult_UnspecifiedFailureThe operation failed with an unspecified error.

Required Permissions:

  • None

API Level:

  • 20

MLVoiceIntentStartProcessing

MLResult MLVoiceIntentStartProcessing(
MLHandle handle
)

Starts voice intent processing.

Parameters

MLHandlehandleHandle to the voice intent client.

Returns

MLResultMLResult_InvalidParamFailed to start processing due to an invalid parameter.
MLResultMLResult_OkSuccessfully start intent processing.
MLResultMLVoiceResult_IntentDisabledFailed to start intent processing because required voice intent feature is disabled in system settings.
MLResultMLResult_UnspecifiedFailureThe operation failed with an unspecified error.

Required Permissions:

  • None

This API call affects the system voice service.

NOTE: If your application is processing voice intents make sure to call MLVoiceIntentStopProcessing when application loses focus and MLVoiceIntentStartProcessing when application gains focus to allow for uninterrupted processing of the voice intents.

API Level:

  • 20

MLVoiceIntentStopProcessing

MLResult MLVoiceIntentStopProcessing(
MLHandle handle
)

Stops voice intent processing.

Parameters

MLHandlehandleHandle to the voice intent client.

Returns

MLResultMLResult_InvalidParamFailed to stop processing due to an invalid parameter.
MLResultMLResult_OkSuccessfully stop intent processing.
MLResultMLVoiceResult_IntentDisabledFailed to stop intent processing because required voice intent feature is disabled in system settings.
MLResultMLResult_UnspecifiedFailureThe operation failed with an unspecified error.

Required Permissions:

  • None

This API call affects the system voice service.

NOTE: If your application is processing voice intents make sure to call MLVoiceIntentStopProcessing when application loses focus and MLVoiceIntentStartProcessing when application gains focus to allow for uninterrupted processing of the voice intents.

API Level:

  • 20

MLVoiceIntentIsEnabled

MLResult MLVoiceIntentIsEnabled(
MLHandle handle,
bool * out_is_enabled
)

Checks voice intent feature is enabled in the system.

Parameters

MLHandlehandleHandle to the voice intent client.
bool *out_is_enabledReturns status whether voice intent feature is enabled in system settings.

Returns

MLResultMLResult_InvalidParamFailed to check due to an invalid parameter.
MLResultMLResult_OkThe API call completed successfuly.

Required Permissions:

  • None

API Level:

  • 20

MLVoiceGetResultString

const char * MLVoiceGetResultString(
MLResult result
)

Returns an ASCII string for MLVoiceResult and MLResult codes.

Parameters

MLResultresultThe input MLResult enum from MLVoice functions.

Required Permissions:

  • None

Return: ASCII string containing readable version of result code.

API Level:

  • 31