Version: 21 Aug 2024

Input

APIs for the Input system. More...

Classes

	Name
struct	MLInputControllerTouchpadGesture
struct	MLInputControllerCallbacksEx A structure containing callbacks for input controller events.
struct	MLInputControllerState A structure containing information about the current state of an input controller.
struct	MLInputControllerStateEx A structure containing information about the current state of an input controller.
struct	MLInputConnectedDevicesList A structure containing information about the connected devices.
struct	MLInputPreDefinedPattern A structure containing information about the Pre-Defined pattern to be played.
struct	MLInputBuzzCommand A structure containing information about the Buzz command to be played.
struct	MLInputCustomHaptics A structure containing information about the Buzz command and/or pre-defined pattern to be played.
struct	MLInputCustomHapticsInfo A structure containing a list of Buzz command and/or pre-defined patterns to be played.
union	MLInputCustomHaptics.MLInputCustomHapticsPattern
struct	MLInputVoiceAppIntentSlot A structure containing voice app-intent slot in voice event.
struct	MLVoiceIntentEvent A structure containing voice intent event.
struct	MLVoiceIntentCallbacks A structure containing callbacks for voice intent events.
struct	MLVoiceIntentSettings A structure containing settings for voice app intent.

Types

	Name
typedef struct MLInputControllerTouchpadGesture	MLInputControllerTouchpadGesture
typedef struct MLInputControllerCallbacksEx	MLInputControllerCallbacksEx A structure containing callbacks for input controller events.
typedef struct MLInputControllerState	MLInputControllerState A structure containing information about the current state of an input controller.
typedef struct MLInputControllerStateEx	MLInputControllerStateEx A structure containing information about the current state of an input controller.
typedef struct MLInputConnectedDevicesList	MLInputConnectedDevicesList A structure containing information about the connected devices.
typedef struct MLInputPreDefinedPattern	MLInputPreDefinedPattern A structure containing information about the Pre-Defined pattern to be played.
typedef struct MLInputBuzzCommand	MLInputBuzzCommand A structure containing information about the Buzz command to be played.
typedef struct MLInputCustomHaptics	MLInputCustomHaptics A structure containing information about the Buzz command and/or pre-defined pattern to be played.
typedef struct MLInputCustomHapticsInfo	MLInputCustomHapticsInfo A structure containing a list of Buzz command and/or pre-defined patterns to be played.
typedef struct MLInputVoiceAppIntentSlot	MLInputVoiceAppIntentSlot A structure containing voice app-intent slot in voice event.
typedef struct MLVoiceIntentEvent	MLVoiceIntentEvent A structure containing voice intent event.
typedef struct MLVoiceIntentCallbacks	MLVoiceIntentCallbacks A structure containing callbacks for voice intent events.
typedef struct MLVoiceIntentSettings	MLVoiceIntentSettings A structure containing settings for voice app intent.

Enums

	Name
enum	Anonymous Enum 13 { MLResultAPIPrefix_Input = ( 0x21DC << 16) }
enum	MLInputResult { MLInputResult_ServiceNotAvailable = MLResultAPIPrefix_Input, MLInputResult_PermissionDenied, MLInputResult_DeviceNotFound, MLInputResult_IllegalState, MLInputResult_InternalError, MLInputResult_SpeechDisabled, MLInputResult_Ensure32Bits = 0x7FFFFFFF } Return values for Input API calls.
enum	Anonymous Enum 14 { MLInput_MaxControllers = 1, MLInput_MaxControllerTouchpadTouches = 2 }
enum	MLInputControllerTouchpadGestureState { MLInputControllerTouchpadGestureState_End, MLInputControllerTouchpadGestureState_Continue, MLInputControllerTouchpadGestureState_Start, MLInputControllerTouchpadGestureState_Ensure32Bits = 0x7FFFFFFF }
enum	MLInputControllerTouchpadGestureType { MLInputControllerTouchpadGestureType_None, MLInputControllerTouchpadGestureType_Tap, MLInputControllerTouchpadGestureType_ForceTapDown, MLInputControllerTouchpadGestureType_ForceTapUp, MLInputControllerTouchpadGestureType_ForceDwell, MLInputControllerTouchpadGestureType_SecondForceDown, MLInputControllerTouchpadGestureType_RadialScroll, MLInputControllerTouchpadGestureType_Swipe, MLInputControllerTouchpadGestureType_Count, MLInputControllerTouchpadGestureType_Ensure32Bits = 0x7FFFFFFF }
enum	MLInputControllerTouchpadGestureDirection { MLInputControllerTouchpadGestureDirection_None, MLInputControllerTouchpadGestureDirection_Up, MLInputControllerTouchpadGestureDirection_Down, MLInputControllerTouchpadGestureDirection_Left, MLInputControllerTouchpadGestureDirection_Right, MLInputControllerTouchpadGestureDirection_Clockwise, MLInputControllerTouchpadGestureDirection_CounterClockwise, MLInputControllerTouchpadGestureDirection_Count, MLInputControllerTouchpadGestureDirection_Ensure32Bits = 0x7FFFFFFF }
enum	MLInputControllerType { MLInputControllerType_None, MLInputControllerType_Device, MLInputControllerType_Ensure32Bits = 0x7FFFFFFF }
enum	MLInputControllerButton { MLInputControllerButton_None, MLInputControllerButton_Bumper, MLInputControllerButton_Menu, MLInputControllerButton_Count, MLInputControllerButton_Ensure32Bits = 0x7FFFFFFF }
enum	MLInputControllerTriggerEvent { MLInputControllerTriggerEvent_Pull, MLInputControllerTriggerEvent_Release, MLInputControllerTriggerEvent_Click, MLInputControllerTriggerEvent_Hold, MLInputControllerTriggerEvent_Ensure32Bits = 0x7FFFFFFF }
enum	MLInputPreDefinedPatternType { MLInputPreDefinedPatternType_A = 0, MLInputPreDefinedPatternType_B = 1, MLInputPreDefinedPatternType_C = 2, MLInputPreDefinedPatternType_Ensure32Bits = 0x7FFFFFFF }
enum	MLInputCustomHapticsType { MLInputCustomHapticsType_None = 0, MLInputCustomHapticsType_Buzz = 1, MLInputCustomHapticsType_Predefined = 2, MLInputCustomHapticsType_Ensure32Bits = 0x7FFFFFFF }
enum	MLInputControllerHand { MLInputControllerHand_None = 0, MLInputControllerHand_Left = 1, MLInputControllerHand_Right = 2, MLInputControllerHand_Both = 3, MLInputControllerHand_Ensure32Bits = 0x7FFFFFFF } Hand in which the controller is held.
enum	Anonymous Enum 30 { MLResultAPIPrefix_Voice = ( 0xbe7a << 16) }
enum	MLVoiceResult { MLVoiceResult_IntentDisabled = MLResultAPIPrefix_Voice, MLVoiceResult_Ensure32Bits = 0x7FFFFFFF } Return values for Voice API calls.
enum	MLVoiceState { 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.
enum	MLVoiceIntentNoIntentReason { MLVoiceIntentNoIntentReason_NoReason = 0, MLVoiceIntentNoIntentReason_Silence = 1, MLVoiceIntentNoIntentReason_NoMatch = 2, MLVoiceIntentNoIntentReason_Ensure32Bits = 0x7FFFFFFF } No intent reason code in voice event.

Functions

	Name
void	MLInputControllerCallbacksExInit(MLInputControllerCallbacksEx * inout_callbacks) Initializes default values for MLInputControllerCallbacksEx.
void	MLInputControllerStateExInit(MLInputControllerStateEx inout_attr[MLInput_MaxControllers]) Initializes values for MLInputControllerStateEx.
void	MLInputConnectedDevicesListInit(MLInputConnectedDevicesList * inout_devices_list) Initializes default values for MLInputConnectedDevicesList.
void	MLInputPreDefinedPatternInit(MLInputPreDefinedPattern * inout_pattern) Initializes default values for MLInputPreDefinedPattern.
void	MLInputBuzzCommandInit(MLInputBuzzCommand * inout_command) Initializes default values for MLInputBuzzCommand.
void	MLInputCustomHapticsInfoInit(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.
MLResult	MLInputCreate(MLHandle * out_handle) Creates an input tracker.
MLResult	MLInputSetControllerCallbacksEx(MLHandle handle, const MLInputControllerCallbacksEx controller_callbacks, void user_data) Sets the callbacks for controller input events.
MLResult	MLInputGetControllerState(MLHandle handle, struct MLInputControllerState out_state[MLInput_MaxControllers]) Returns current state of all possible input controllers.
MLResult	MLInputGetControllerStateEx(MLHandle handle, MLInputControllerStateEx out_state[MLInput_MaxControllers]) Returns current state of all possible input controllers.
MLResult	MLInputGetConnectedDevices(MLHandle handle, MLInputConnectedDevicesList * inout_devices) Gets the device IDs of all connected devices.
MLResult	MLInputReleaseConnectedDevicesList(MLHandle handle, MLInputConnectedDevicesList * devices) Releases the contents of MLInputConnectedDevicesList populated by MLInputGetConnectedDevices.
MLResult	MLInputStartControllerFeedbackPreDefinedPattern(MLHandle handle, uint8_t controller_id, MLInputPreDefinedPattern * pattern) Plays the pre-defined pattern.
MLResult	MLInputStartControllerFeedbackBuzzCommand(MLHandle handle, uint8_t controller_id, const MLInputBuzzCommand * command) Plays controller haptic buzz command.
MLResult	MLInputCreateCustomHapticsPattern(MLHandle handle, MLInputCustomHapticsInfo info, uint32_t inout_pattern_id) Creates a custom haptic pattern.
MLResult	MLInputStartControllerFeedbackCustomHapticsPattern(MLHandle handle, uint8_t controller_id, uint32_t pattern_id) Plays the custom haptic pattern created by MLInputCreateCustomHapticsPattern.
MLResult	MLInputDeleteCustomHapticsPattern(MLHandle handle, uint32_t pattern_id) Deletes the custom haptic pattern created by MLInputCreateCustomHapticsPattern.
MLResult	MLInputStopControllerFeedback(MLHandle handle, uint8_t controller_id) Stops the currently playing haptic pattern.
MLResult	MLInputDestroy(MLHandle handle) Destroys an input tracker.
void	MLVoiceIntentCallbacksInit(MLVoiceIntentCallbacks * inout_callbacks) Initializes default values for MLVoiceIntentCallbacks.
void	MLVoiceIntentSettingsInit(MLVoiceIntentSettings * inout_settings) Initializes default values for MLVoiceIntentSettings.
MLResult	MLVoiceIntentCreate(MLHandle * out_handle) Creates a voice intent client.
MLResult	MLVoiceIntentDestroy(MLHandle handle) Destroys a voice intent client.
MLResult	MLVoiceIntentConfigureSettings(MLHandle handle, const MLVoiceIntentSettings * voice_settings) Sets the settings for voice intent events.
MLResult	MLVoiceIntentSetCallbacks(MLHandle handle, const MLVoiceIntentCallbacks voice_callbacks, void user_data) Sets the callbacks for voice intent events.
MLResult	MLVoiceIntentStartProcessing(MLHandle handle) Starts voice intent processing.
MLResult	MLVoiceIntentStopProcessing(MLHandle handle) Stops voice intent processing.
MLResult	MLVoiceIntentIsEnabled(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

Enumerator	Value	Description
MLResultAPIPrefix_Input	( 0x21DC << 16)	Defines the prefix for MLInputResult codes.

MLInputResult

Enumerator	Value	Description
MLInputResult_ServiceNotAvailable	MLResultAPIPrefix_Input
MLInputResult_PermissionDenied		Operation failed because a required permission has not been granted. Example: This can happen when the app is not in the foreground.
MLInputResult_DeviceNotFound		Operation failed because a required device was not found.
MLInputResult_IllegalState		Operation failed because the service was in an illegal state. Example: This can occur when the service is still initializing.
MLInputResult_InternalError		Operation failed because of an internal error.
MLInputResult_SpeechDisabled		Operation failed because a required speech feature is disabled in system settings.
MLInputResult_Ensure32Bits	0x7FFFFFFF	Ensure enum is represented as 32 bits.

Return values for Input API calls.

Anonymous Enum 14

Enumerator	Value	Description
MLInput_MaxControllers	1	Maximum recognized number of input controllers.
MLInput_MaxControllerTouchpadTouches	2	Maximum recognized number of controller touchpad touches.

MLInputControllerTouchpadGestureState

Enumerator	Value	Description
MLInputControllerTouchpadGestureState_End		End(Default).
MLInputControllerTouchpadGestureState_Continue		Continue.
MLInputControllerTouchpadGestureState_Start		Start.
MLInputControllerTouchpadGestureState_Ensure32Bits	0x7FFFFFFF	Ensure enum is represented as 32 bits.

Touchpad gesture state.

MLInputControllerTouchpadGestureType

Enumerator	Value	Description
MLInputControllerTouchpadGestureType_None		None.
MLInputControllerTouchpadGestureType_Tap		Tap. This is a discrete gesture.
MLInputControllerTouchpadGestureType_ForceTapDown		Force tap down. This is a discrete gesture.
MLInputControllerTouchpadGestureType_ForceTapUp		Force tap up. This is a discrete gesture.
MLInputControllerTouchpadGestureType_ForceDwell		Force dwell. This is a discrete gesture.
MLInputControllerTouchpadGestureType_SecondForceDown		Second force down. This is a discrete gesture.
MLInputControllerTouchpadGestureType_RadialScroll		Radial scroll. This is a continuous gesture.
MLInputControllerTouchpadGestureType_Swipe		Swipe. This is a continuous gesture.
MLInputControllerTouchpadGestureType_Count		Number of gesture types.
MLInputControllerTouchpadGestureType_Ensure32Bits	0x7FFFFFFF	Ensure enum is represented as 32 bits.

Recognized touchpad gesture types.

MLInputControllerTouchpadGestureDirection

Enumerator	Value	Description
MLInputControllerTouchpadGestureDirection_None		None.
MLInputControllerTouchpadGestureDirection_Up		Up.
MLInputControllerTouchpadGestureDirection_Down		Down.
MLInputControllerTouchpadGestureDirection_Left		Left.
MLInputControllerTouchpadGestureDirection_Right		Right.
MLInputControllerTouchpadGestureDirection_Clockwise		Clockwise.
MLInputControllerTouchpadGestureDirection_CounterClockwise		Counter clockwise.
MLInputControllerTouchpadGestureDirection_Count		Number of directions.
MLInputControllerTouchpadGestureDirection_Ensure32Bits	0x7FFFFFFF	Ensure enum is represented as 32 bits.

Direction of touchpad gesture.

MLInputControllerType

Enumerator	Value	Description
MLInputControllerType_None		None.
MLInputControllerType_Device		Device.
MLInputControllerType_Ensure32Bits	0x7FFFFFFF	Ensure enum is represented as 32 bits.

Types of input controllers recognized by Magic Leap platform.

MLInputControllerButton

Enumerator	Value	Description
MLInputControllerButton_None
MLInputControllerButton_Bumper		Bumper.
MLInputControllerButton_Menu		Menu.
MLInputControllerButton_Count		Number of buttons.
MLInputControllerButton_Ensure32Bits	0x7FFFFFFF	Ensure enum is represented as 32 bits.

Buttons on input controllers.

MLInputControllerTriggerEvent

Enumerator	Value	Description
MLInputControllerTriggerEvent_Pull		This is used when trigger is pulled down, and the normalized value is > 0.
MLInputControllerTriggerEvent_Release		This is used when trigger is fully released, and the normalized value is 0.
MLInputControllerTriggerEvent_Click		This is used when trigger is pulled and released within a short duration.
MLInputControllerTriggerEvent_Hold		This is used when trigger is pulled and held for a longer duration.
MLInputControllerTriggerEvent_Ensure32Bits	0x7FFFFFFF	Ensure enum is represented as 32 bits.

Trigger events types.

MLInputPreDefinedPatternType

Enumerator	Value	Description
MLInputPreDefinedPatternType_A	0	Pre-defined pattern used for VKB hover.
MLInputPreDefinedPatternType_B	1	Pre-Defined pattern used for VKB select.
MLInputPreDefinedPatternType_C	2	Pre-Defined pattern used for homemenu hover.
MLInputPreDefinedPatternType_Ensure32Bits	0x7FFFFFFF	Ensure enum is represented as 32 bits.

Custom haptics pattern types.

MLInputCustomHapticsType

Enumerator	Value	Description
MLInputCustomHapticsType_None	0	None.
MLInputCustomHapticsType_Buzz	1	Pattern is a buzz command.
MLInputCustomHapticsType_Predefined	2	Pattern is a pre-defined pattern.
MLInputCustomHapticsType_Ensure32Bits	0x7FFFFFFF	Ensure enum is represented as 32 bits.

Custom haptics pattern types.

MLInputControllerHand

Enumerator	Value	Description
MLInputControllerHand_None	0	None.
MLInputControllerHand_Left	1	Left hand.
MLInputControllerHand_Right	2	Right hand.
MLInputControllerHand_Both	3	Both hand.
MLInputControllerHand_Ensure32Bits	0x7FFFFFFF	Ensure enum is represented as 32 bits.

Hand in which the controller is held.

API Level:

Anonymous Enum 30

Enumerator	Value	Description
MLResultAPIPrefix_Voice	( 0xbe7a << 16)	Defines the prefix for MLVoiceResult codes.

MLVoiceResult

Enumerator	Value	Description
MLVoiceResult_IntentDisabled	MLResultAPIPrefix_Voice	Operation failed because a required voice intent feature is disabled in system settings.
MLVoiceResult_Ensure32Bits	0x7FFFFFFF	Ensure enum is represented as 32 bits.

Return values for Voice API calls.

API Level:

MLVoiceState

Enumerator	Value	Description
MLVoiceState_IntentHotwordDetected	0	Intent hotword detected, Automatic Speech Recognition (ASR) session is going to start.
MLVoiceState_IntentSessionEnded	1	Voice UI is stopped, ASR session is going to stop.
MLVoiceState_IntentSessionEndedAborted	2	ASR session is stopped due to abort.
MLVoiceState_IntentSessionEndedNoIntent	3	ASR session is stopped without detecting an intent.
MLVoiceState_IntentSessionEndedTimeout	4	ASR session is stopped due to timeout.
MLVoiceState_IntentSessionEndedError	5	ASR session is stopped due to error.
MLVoiceState_IntentReady	6	Intent mode is started and ready.
MLVoiceState_IntentNotAvailable	7	Intent mode is stopped and not available.
MLVoiceState_IntentInvalidAppIntent	8	Invalid 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_Ensure32Bits	0x7FFFFFFF	Ensure enum is represented as 32 bits.

Voice state in voice event.

API Level:

MLVoiceIntentNoIntentReason

Enumerator	Value	Description
MLVoiceIntentNoIntentReason_NoReason	0	In case of success.
MLVoiceIntentNoIntentReason_Silence	1	When the MLVoiceState in MLVoiceIntentEvent is either MLVoiceState_IntentSessionEndedTimeout or MLVoiceState_IntentSessionEndedError.
MLVoiceIntentNoIntentReason_NoMatch	2	When the MLVoiceState in MLVoiceIntentEvent is MLVoiceState_IntentSessionEndedNoIntent.
MLVoiceIntentNoIntentReason_Ensure32Bits	0x7FFFFFFF	Ensure enum is represented as 32 bits.

No intent reason code in voice event.

API Level:

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:

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:

MLInputConnectedDevicesList

typedef struct MLInputConnectedDevicesList MLInputConnectedDevicesList;

A structure containing information about the connected devices.

More Info

API Level:

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:

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:

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:

MLInputVoiceAppIntentSlot

typedef struct MLInputVoiceAppIntentSlot MLInputVoiceAppIntentSlot;

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

More Info

API Level:

MLVoiceIntentEvent

typedef struct MLVoiceIntentEvent MLVoiceIntentEvent;

A structure containing voice intent event.

More Info

API Level:

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:

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:

Functions Documentation

MLInputControllerCallbacksExInit

static inline void MLInputControllerCallbacksExInit(
    MLInputControllerCallbacksEx * inout_callbacks
)

Initializes default values for MLInputControllerCallbacksEx.

Parameters


MLInputControllerCallbacksEx *	inout_callbacks	The object to initialize with default settings.

API Level:

MLInputControllerStateExInit

static inline void MLInputControllerStateExInit(
    MLInputControllerStateEx inout_attr[MLInput_MaxControllers]
)

Initializes values for MLInputControllerStateEx.

Parameters


MLInputControllerStateEx	inout_attr	The object to initialize.

API Level:

MLInputConnectedDevicesListInit

static inline void MLInputConnectedDevicesListInit(
    MLInputConnectedDevicesList * inout_devices_list
)

Initializes default values for MLInputConnectedDevicesList.

Parameters


MLInputConnectedDevicesList *	inout_devices_list	The object to initialize with default settings.

API Level:

MLInputPreDefinedPatternInit

static inline void MLInputPreDefinedPatternInit(
    MLInputPreDefinedPattern * inout_pattern
)

Initializes default values for MLInputPreDefinedPattern.

Parameters


MLInputPreDefinedPattern *	inout_pattern	The object to initialize with default settings.

MLInputBuzzCommandInit

static inline void MLInputBuzzCommandInit(
    MLInputBuzzCommand * inout_command
)

Initializes default values for MLInputBuzzCommand.

Parameters


MLInputBuzzCommand *	inout_command	The 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_info	The 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


MLResult	result	The input MLResult enum from MLInput functions.

Required Permissions:

None

Return: ASCII string containing readable version of result code.

API Level:

MLInputCreate

MLResult MLInputCreate(
    MLHandle * out_handle
)

Creates an input tracker.

Parameters


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

Returns


MLResult	MLResult_InvalidParam	Failed to create the input tracker to an invalid input parameter.
MLResult	MLResult_Ok	Successfully created the input tracker.
MLResult	MLResult_UnspecifiedFailure	Failed to create the input tracker due to an unknown error.
MLResult	MLInputResult_IllegalState	Failed to create the input tracker due to an unexpected state.

Required Permissions:

None

API Level:

MLInputSetControllerCallbacksEx

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

Sets the callbacks for controller input events.

Parameters


MLHandle	handle	Handle to the input tracker.
const MLInputControllerCallbacksEx *	controller_callbacks	Pointer to MLInputControllerCallbacksEx structure (can be NULL).
void *	user_data	Pointer to user payload data; this will be the first argument passed to all the callback functions (can be NULL).

Returns


MLResult	MLResult_InvalidParam	Failed to set the callback for controller input events due to an invalid input parameter.
MLResult	MLResult_Ok	Successfully set the callback for controller input events.
MLResult	MLResult_UnspecifiedFailure	Failed to set the callback for the controller input events due to an unknown error.

Required Permissions:

None

API Level:

MLInputGetControllerState

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

Returns current state of all possible input controllers.

Parameters


MLHandle	handle	Handle to the input tracker.
struct MLInputControllerState	out_state	Array of MLInputControllerState structures that will be populated. The size of this array is at least the size MLInput_MaxControllers.

Returns


MLResult	MLResult_InvalidParam	Failed to fetch the controller state due to an invalid input parameter.
MLResult	MLResult_Ok	Successfully fetched the controller state.
MLResult	MLResult_UnspecifiedFailure	Failed 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


MLHandle	handle	Handle to the input tracker.
MLInputControllerStateEx	out_state	Array of MLInputControllerStateEx structures that will be populated. The size of this array is at least the size MLInput_MaxControllers.

Returns


MLResult	MLResult_InvalidParam	Failed to fetch the controller state due to an invalid input parameter.
MLResult	MLResult_Ok	Successfully fetched the controller state.
MLResult	MLResult_UnspecifiedFailure	Failed to fetch the controller state due to an unknown error.

Required Permissions:

None

API Level:

MLInputGetConnectedDevices

MLResult MLInputGetConnectedDevices(
    MLHandle handle,
    MLInputConnectedDevicesList * inout_devices
)

Gets the device IDs of all connected devices.

Parameters


MLHandle	handle	Handle to the input tracker.
MLInputConnectedDevicesList *	inout_devices	Pointer to MLInputConnectedDevicesList structure that will be populated. The app should call MLInputReleaseConnectedDevicesList to release the contents after use.

Returns


MLResult	MLResult_InvalidParam	Failed to get the IDs of all connected devices due to an invalid input parameter.
MLResult	MLResult_Ok	Successfully fetched the IDs of the connected devices.
MLResult	MLResult_UnspecifiedFailure	Failed to get the IDs of all connected devices due to an unknown error.

Required Permissions:

None

API Level:

MLInputReleaseConnectedDevicesList

MLResult MLInputReleaseConnectedDevicesList(
    MLHandle handle,
    MLInputConnectedDevicesList * devices
)

Releases the contents of MLInputConnectedDevicesList populated by MLInputGetConnectedDevices.

Parameters


MLHandle	handle	Handle to the input tracker.
MLInputConnectedDevicesList *	devices	Pointer to MLInputConnectedDevicesList struct. Its contents will be released.

Returns


MLResult	MLResult_Ok	Successfully released the contents of the device list.
MLResult	MLResult_InvalidParam	Failed to release the contents of the device list due to an invalid input parameter.
MLResult	MLResult_UnspecifiedFailure	Failed to release the contents of the device list due to an unknown error.

Required Permissions:

None

API Level:

MLInputStartControllerFeedbackPreDefinedPattern

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

Plays the pre-defined pattern.

Parameters


MLHandle	handle	Handle to the input tracker.
uint8_t	controller_id	Id of the input controller 0 ~ MLInput_MaxControllers.
MLInputPreDefinedPattern *	pattern	A pointer to #MLInputPredefinedPattern structure (can be NULL).

Returns


MLResult	MLInputResult_IllegalState	The service is either not initialized or terminated or the app is not in focus.
MLResult	MLResult_DeviceNotFound	The haptic device could not be found.
MLResult	MLResult_InvalidParam	Failed to start a pre-defined pattern due to an invalid input parameter.
MLResult	MLResult_Ok	Successfully started a pre-defined pattern on the specified controller.
MLResult	MLResult_UnspecifiedFailure	Failed to start a pre-defined pattern due to an unknown error.

Required Permissions:

None

API Level:

MLInputStartControllerFeedbackBuzzCommand

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

Plays controller haptic buzz command.

Parameters


MLHandle	handle	Handle to the input tracker.
uint8_t	controller_id	Id of the input controller 0 ~ MLInput_MaxControllers.
const MLInputBuzzCommand *	command	A pointer to MLInputBuzzCommand structure (can be NULL).

Returns


MLResult	MLInputResult_IllegalState	The service is either not initialized or terminated or the app is not in focus.
MLResult	MLResult_DeviceNotFound	The haptic device could not be found.
MLResult	MLResult_InvalidParam	Failed to start the buzz command due to an invalid input parameter.
MLResult	MLResult_Ok	Successfully started the buzz command on the specified controller.
MLResult	MLResult_UnspecifiedFailure	Failed to start the buzz command due to an unknown error.

Required Permissions:

None

API Level:

MLInputCreateCustomHapticsPattern

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

Creates a custom haptic pattern.

Parameters


MLHandle	handle	Handle to the input tracker.
MLInputCustomHapticsInfo *	info	Pointer to MLInputCustomHapticsInfo struct.
uint32_t *	inout_pattern_id	A pattern Id created by the API, to be used by MLInputStartControllerFeedbackCustomHapticsPattern.

Returns


MLResult	MLInputResult_IllegalState	The service is either not initialized or terminated.
MLResult	MLResult_InvalidParam	Failed to create a custom haptic pattern due to an invalid input parameter.
MLResult	MLResult_Ok	Successfully created a custom haptic pattern.
MLResult	MLResult_UnspecifiedFailure	Failed 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:

MLInputStartControllerFeedbackCustomHapticsPattern

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

Plays the custom haptic pattern created by MLInputCreateCustomHapticsPattern.

Parameters


MLHandle	handle	Handle to the input tracker.
uint8_t	controller_id	Id of the input controller 0 ~ MLInput_MaxControllers.
uint32_t	pattern_id	Custom pattern id created by MLInputCreateCustomHapticsPattern.

Returns


MLResult	MLInputResult_IllegalState	The service is either not initialized or terminated or the app is not in focus.
MLResult	MLResult_DeviceNotFound	The haptic device could not be found.
MLResult	MLResult_InvalidParam	Failed to start the custom haptic pattern due to an invalid input parameter.
MLResult	MLResult_Ok	Successfully started the custom haptic pattern on the specified controller.
MLResult	MLResult_UnspecifiedFailure	Failed to start the custom haptic pattern due to an unknown error.

Required Permissions:

None

API Level:

MLInputDeleteCustomHapticsPattern

MLResult MLInputDeleteCustomHapticsPattern(
    MLHandle handle,
    uint32_t pattern_id
)

Deletes the custom haptic pattern created by MLInputCreateCustomHapticsPattern.

Parameters


MLHandle	handle	Handle to the input tracker.
uint32_t	pattern_id	Custom pattern Id created by MLInputCreateCustomHapticsPattern.

Returns


MLResult	MLInputResult_IllegalState	The service is either not initialized or terminated.
MLResult	MLResult_InvalidParam	Failed to destroy the custom haptic pattern due to an invalid input parameter.
MLResult	MLResult_Ok	Successfully destroyed the custom haptic pattern on the specified controller.
MLResult	MLResult_UnspecifiedFailure	Failed to destroy the custom haptic pattern due to an unknown error.

Required Permissions:

None

API Level:

MLInputStopControllerFeedback

MLResult MLInputStopControllerFeedback(
    MLHandle handle,
    uint8_t controller_id
)

Stops the currently playing haptic pattern.

Parameters


MLHandle	handle	Handle to the input tracker.
uint8_t	controller_id	Id of the input controller 0 ~ MLInput_MaxControllers.

Returns


MLResult	MLInputResult_IllegalState	The service is either not initialized or terminated or the app is not in focus.
MLResult	MLResult_DeviceNotFound	The haptic device could not be found.
MLResult	MLResult_InvalidParam	Failed to stop the pattern due to an invalid input parameter.
MLResult	MLResult_Ok	Successfully stopped the pattern on the specified controller.
MLResult	MLResult_UnspecifiedFailure	Failed to stop the pattern due to an unknown error.

Required Permissions:

None

API Level:

MLInputDestroy

MLResult MLInputDestroy(
    MLHandle handle
)

Destroys an input tracker.

Parameters


MLHandle	handle	MLHandle to the input tracker to destroy.

Returns


MLResult	MLResult_InvalidParam	Failed to destroy the input tracker due to an invalid input parameter.
MLResult	MLResult_Ok	Successfully destroyed the input tracker.
MLResult	MLResult_UnspecifiedFailure	Failed to destroy the input handler due to an unknown error.
MLResult	MLInputResult_IllegalState	Failed 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_callbacks	The object to initialize with default settings.

Required Permissions:

None

API Level:

MLVoiceIntentSettingsInit

static inline void MLVoiceIntentSettingsInit(
    MLVoiceIntentSettings * inout_settings
)

Initializes default values for MLVoiceIntentSettings.

Parameters


MLVoiceIntentSettings *	inout_settings	The object to initialize with default settings.

Required Permissions:

None

API Level:

MLVoiceIntentCreate

MLResult MLVoiceIntentCreate(
    MLHandle * out_handle
)

Creates a voice intent client.

Parameters


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

Returns


MLResult	MLResult_InvalidParam	Failed to create the voice intent client due to an invalid input parameter.
MLResult	MLResult_Ok	Successfully created the voice intent client.
MLResult	MLResult_PermissionDenied	Failed to create client due to missing permission.

Required Permissions:

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

API Level:

MLVoiceIntentDestroy

MLResult MLVoiceIntentDestroy(
    MLHandle handle
)

Destroys a voice intent client.

Parameters


MLHandle	handle	MLHandle to the voice intent client to destroy.

Returns


MLResult	MLResult_InvalidParam	Failed to destroy the voice intent client due to an invalid input parameter.
MLResult	MLResult_Ok	Successfully 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


MLHandle	handle	Handle to the voice intent client.
const MLVoiceIntentSettings *	voice_settings	Pointer to MLVoiceIntentSettings structure.

Returns


MLResult	MLResult_InvalidParam	Failed to set settings for voice intent events due to an invalid param.
MLResult	MLResult_Ok	Successfully set settings for voice intent events.
MLResult	MLVoiceResult_IntentDisabled	Failed to set the settings because required voice intent feature is disabled.
MLResult	MLResult_UnspecifiedFailure	The 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:

MLVoiceIntentSetCallbacks

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

Sets the callbacks for voice intent events.

Parameters


MLHandle	handle	Handle to the voice intent client.
const MLVoiceIntentCallbacks *	voice_callbacks	Pointer to MLVoiceIntentCallbacks structure. Set this to NULL to unregister callbacks.
void *	user_data	Pointer to user payload data (can be NULL).

Returns


MLResult	MLResult_InvalidParam	Failed to set callbacks for voice intent events due to an invalid param.
MLResult	MLResult_Ok	Successfully set callbacks for voice intent events.
MLResult	MLVoiceResult_IntentDisabled	Failed to set the callbacks because required voice intent feature is disabled in system settings.
MLResult	MLResult_UnspecifiedFailure	The operation failed with an unspecified error.

Required Permissions:

None

API Level:

MLVoiceIntentStartProcessing

MLResult MLVoiceIntentStartProcessing(
    MLHandle handle
)

Starts voice intent processing.

Parameters


MLHandle	handle	Handle to the voice intent client.

Returns


MLResult	MLResult_InvalidParam	Failed to start processing due to an invalid parameter.
MLResult	MLResult_Ok	Successfully start intent processing.
MLResult	MLVoiceResult_IntentDisabled	Failed to start intent processing because required voice intent feature is disabled in system settings.
MLResult	MLResult_UnspecifiedFailure	The 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:

MLVoiceIntentStopProcessing

MLResult MLVoiceIntentStopProcessing(
    MLHandle handle
)

Stops voice intent processing.

Parameters


MLHandle	handle	Handle to the voice intent client.

Returns


MLResult	MLResult_InvalidParam	Failed to stop processing due to an invalid parameter.
MLResult	MLResult_Ok	Successfully stop intent processing.
MLResult	MLVoiceResult_IntentDisabled	Failed to stop intent processing because required voice intent feature is disabled in system settings.
MLResult	MLResult_UnspecifiedFailure	The operation failed with an unspecified error.

Required Permissions:

None

This API call affects the system voice service.

API Level:

MLVoiceIntentIsEnabled

MLResult MLVoiceIntentIsEnabled(
    MLHandle handle,
    bool * out_is_enabled
)

Checks voice intent feature is enabled in the system.

Parameters


MLHandle	handle	Handle to the voice intent client.
bool *	out_is_enabled	Returns status whether voice intent feature is enabled in system settings.

Returns


MLResult	MLResult_InvalidParam	Failed to check due to an invalid parameter.
MLResult	MLResult_Ok	The API call completed successfuly.

Required Permissions:

None

API Level:

MLVoiceGetResultString

const char * MLVoiceGetResultString(
    MLResult result
)

Returns an ASCII string for MLVoiceResult and MLResult codes.

Parameters


MLResult	result	The input MLResult enum from MLVoice functions.

Required Permissions:

None

Return: ASCII string containing readable version of result code.

API Level:

Input

Classes​

Types​

Enums​

Functions​

Detailed Description​

Enums Documentation​

Anonymous Enum 13​

MLInputResult​

Anonymous Enum 14​

MLInputControllerTouchpadGestureState​

MLInputControllerTouchpadGestureType​

MLInputControllerTouchpadGestureDirection​

MLInputControllerType​

MLInputControllerButton​

MLInputControllerTriggerEvent​

MLInputPreDefinedPatternType​

MLInputCustomHapticsType​

MLInputControllerHand​

Anonymous Enum 30​

MLVoiceResult​

MLVoiceState​

MLVoiceIntentNoIntentReason​

Types Documentation​

MLInputControllerTouchpadGesture​

MLInputControllerCallbacksEx​

MLInputControllerState​

MLInputControllerStateEx​

MLInputConnectedDevicesList​

MLInputPreDefinedPattern​

MLInputBuzzCommand​

MLInputCustomHaptics​

MLInputCustomHapticsInfo​

MLInputVoiceAppIntentSlot​

MLVoiceIntentEvent​

MLVoiceIntentCallbacks​

MLVoiceIntentSettings​

Functions Documentation​

MLInputControllerCallbacksExInit​

MLInputControllerStateExInit​

MLInputConnectedDevicesListInit​

MLInputPreDefinedPatternInit​

MLInputBuzzCommandInit​

MLInputCustomHapticsInfoInit​

MLInputGetResultString​

MLInputCreate​

MLInputSetControllerCallbacksEx​

MLInputGetControllerState​

MLInputGetControllerStateEx​

MLInputGetConnectedDevices​

MLInputReleaseConnectedDevicesList​

MLInputStartControllerFeedbackPreDefinedPattern​

MLInputStartControllerFeedbackBuzzCommand​

MLInputCreateCustomHapticsPattern​

MLInputStartControllerFeedbackCustomHapticsPattern​

MLInputDeleteCustomHapticsPattern​

MLInputStopControllerFeedback​

MLInputDestroy​

MLVoiceIntentCallbacksInit​

MLVoiceIntentSettingsInit​

MLVoiceIntentCreate​

MLVoiceIntentDestroy​

MLVoiceIntentConfigureSettings​

MLVoiceIntentSetCallbacks​

MLVoiceIntentStartProcessing​

MLVoiceIntentStopProcessing​

MLVoiceIntentIsEnabled​

MLVoiceGetResultString​

Classes

Types

Enums

Functions

Detailed Description

Enums Documentation

Anonymous Enum 13

MLInputResult

Anonymous Enum 14

MLInputControllerTouchpadGestureState

MLInputControllerTouchpadGestureType

MLInputControllerTouchpadGestureDirection

MLInputControllerType

MLInputControllerButton

MLInputControllerTriggerEvent

MLInputPreDefinedPatternType

MLInputCustomHapticsType

MLInputControllerHand

Anonymous Enum 30

MLVoiceResult

MLVoiceState

MLVoiceIntentNoIntentReason

Types Documentation

MLInputControllerTouchpadGesture

MLInputControllerCallbacksEx

MLInputControllerState

MLInputControllerStateEx

MLInputConnectedDevicesList

MLInputPreDefinedPattern

MLInputBuzzCommand

MLInputCustomHaptics

MLInputCustomHapticsInfo

MLInputVoiceAppIntentSlot

MLVoiceIntentEvent

MLVoiceIntentCallbacks

MLVoiceIntentSettings

Functions Documentation

MLInputControllerCallbacksExInit

MLInputControllerStateExInit

MLInputConnectedDevicesListInit

MLInputPreDefinedPatternInit

MLInputBuzzCommandInit

MLInputCustomHapticsInfoInit

MLInputGetResultString

MLInputCreate

MLInputSetControllerCallbacksEx

MLInputGetControllerState

MLInputGetControllerStateEx

MLInputGetConnectedDevices

MLInputReleaseConnectedDevicesList

MLInputStartControllerFeedbackPreDefinedPattern

MLInputStartControllerFeedbackBuzzCommand

MLInputCreateCustomHapticsPattern

MLInputStartControllerFeedbackCustomHapticsPattern

MLInputDeleteCustomHapticsPattern

MLInputStopControllerFeedback

MLInputDestroy

MLVoiceIntentCallbacksInit

MLVoiceIntentSettingsInit

MLVoiceIntentCreate

MLVoiceIntentDestroy

MLVoiceIntentConfigureSettings

MLVoiceIntentSetCallbacks

MLVoiceIntentStartProcessing

MLVoiceIntentStopProcessing

MLVoiceIntentIsEnabled

MLVoiceGetResultString