Version: 12 Dec 2024

ml_space.h

Classes

	Name
struct	MLSpaceManagerSettings A structure containing settings for the space manager. This structure must be initialized by calling MLSpaceManagerSettingsInit before use.
struct	MLSpace A structure containing information about a Magic Leap Space. This structure must be initialized by calling MLSpaceInit before use.
struct	MLSpaceList A structure containing list of MLSpace. This structure must be initialized by calling MLSpaceListInit before use.
struct	MLSpaceQueryFilter A collection of filters for Magic Leap Spaces. This structure must be initialized by calling MLSpaceQueryFilterInit before use. There is no support for filters at this time.
struct	MLSpaceLocalizationInfo A collection of parameters to be used for localization request. This structure must be initialized by calling MLSpaceLocalizationInfoInit before use.
struct	MLSpaceLocalizationResult A structure containing information about the device's localization state. This structure must be initialized by calling MLSpaceLocalizationResultInit before use.
struct	MLSpaceCallbacks A structure containing callbacks for events related to the Space.
struct	MLSpaceImportInfo A structure containing information needed to import Magic Leap Space. This structure must be initialized by calling MLSpaceImportInfoInit before use.
struct	MLSpaceImportOutData A structure containing information about the imported Space.
struct	MLSpaceExportInfo A structure containing information about the Space export settings. This structure must be initialized by calling MLSpaceExportInfoInit before use.
struct	MLSpaceExportOutData A structure containing information about the exported Space.

Types

	Name
typedef struct MLSpaceManagerSettings	MLSpaceManagerSettings A structure containing settings for the space manager. This structure must be initialized by calling MLSpaceManagerSettingsInit before use.
typedef struct MLSpace	MLSpace A structure containing information about a Magic Leap Space. This structure must be initialized by calling MLSpaceInit before use.
typedef struct MLSpaceList	MLSpaceList A structure containing list of MLSpace. This structure must be initialized by calling MLSpaceListInit before use.
typedef struct MLSpaceQueryFilter	MLSpaceQueryFilter A collection of filters for Magic Leap Spaces. This structure must be initialized by calling MLSpaceQueryFilterInit before use. There is no support for filters at this time.
typedef struct MLSpaceLocalizationInfo	MLSpaceLocalizationInfo A collection of parameters to be used for localization request. This structure must be initialized by calling MLSpaceLocalizationInfoInit before use.
typedef struct MLSpaceLocalizationResult	MLSpaceLocalizationResult A structure containing information about the device's localization state. This structure must be initialized by calling MLSpaceLocalizationResultInit before use.
typedef struct MLSpaceCallbacks	MLSpaceCallbacks A structure containing callbacks for events related to the Space.
typedef struct MLSpaceImportInfo	MLSpaceImportInfo A structure containing information needed to import Magic Leap Space. This structure must be initialized by calling MLSpaceImportInfoInit before use.
typedef struct MLSpaceImportOutData	MLSpaceImportOutData A structure containing information about the imported Space.
typedef struct MLSpaceExportInfo	MLSpaceExportInfo A structure containing information about the Space export settings. This structure must be initialized by calling MLSpaceExportInfoInit before use.
typedef struct MLSpaceExportOutData	MLSpaceExportOutData A structure containing information about the exported Space.

Enums

	Name
enum	Anonymous Enum 28 { MLResultAPIPrefix_Space = ( 0x10cc << 16), MLSpace_MaxSpaceNameLength = 64 }
enum	MLSpaceResult { MLSpaceResult_ServerError = MLResultAPIPrefix_Space, MLSpaceResult_ServiceUnavailable, MLSpaceResult_UnavailableSpace, MLSpaceResult_IncompatibleSpace, MLSpaceResult_SpaceAlreadyExists, MLSpaceResult_Ensure32Bits = 0x7FFFFFFF } Magic Leap Space specific return codes.
enum	MLSpaceType { MLSpaceType_OnDevice = 0, MLSpaceType_ARCloud = 1, MLSpaceType_Ensure32Bits = 0x7FFFFFFF } Space type. Indicates the type of the Space.
enum	MLSpaceLocalizationStatus { MLSpaceLocalizationStatus_NotLocalized = 0, MLSpaceLocalizationStatus_Localized = 1, MLSpaceLocalizationStatus_LocalizationPending = 2, MLSpaceLocalizationStatus_SleepingBeforeRetry = 3, MLSpaceLocalizationStatus_Ensure32Bits = 0x7FFFFFFF } The current localization status.
enum	MLSpaceLocalizationConfidence { MLSpaceLocalizationConfidence_Poor = 0, MLSpaceLocalizationConfidence_Fair = 1, MLSpaceLocalizationConfidence_Good = 2, MLSpaceLocalizationConfidence_Excellent = 3, MLSpaceLocalizationConfidence_Ensure32Bits = 0x7FFFFFFF } The confidence of the current localization.
enum	MLSpaceLocalizationErrorFlag { MLSpaceLocalizationErrorFlag_None = 0, MLSpaceLocalizationErrorFlag_Unknown = 1 << 0, MLSpaceLocalizationErrorFlag_OutOfMappedArea = 1 << 1, MLSpaceLocalizationErrorFlag_LowFeatureCount = 1 << 2, MLSpaceLocalizationErrorFlag_ExcessiveMotion = 1 << 3, MLSpaceLocalizationErrorFlag_LowLight = 1 << 4, MLSpaceLocalizationErrorFlag_HeadposeFailure = 1 << 5, MLSpaceLocalizationErrorFlag_AlgorithmFailure = 1 << 6, MLSpaceLocalizationErrorFlag_Ensure32Bits = 0x7FFFFFFF } A set of possible reasons that a localization attempt may be unsuccessful.

Functions

	Name
void	MLSpaceManagerSettingsInit(MLSpaceManagerSettings * inout_info) Initializes default values for MLSpaceManagerSettings.
void	MLSpaceInit(MLSpace * inout_info) Initializes default values for MLSpace.
void	MLSpaceListInit(MLSpaceList * inout_info) Initializes default values for MLSpaceList.
void	MLSpaceQueryFilterInit(MLSpaceQueryFilter * inout_query_filter) Initializes the default values for a query filter.
void	MLSpaceLocalizationInfoInit(MLSpaceLocalizationInfo * inout_info) Initializes the default values for localization info.
void	MLSpaceLocalizationResultInit(MLSpaceLocalizationResult * inout_info) Initialize default values for MLSpaceLocalizationResult.
void	MLSpaceCallbacksInit(MLSpaceCallbacks * inout_callbacks) Initialize defaults for MLSpaceCallbacks.
void	MLSpaceImportInfoInit(MLSpaceImportInfo * inout_info) Initialize default values for MLSpaceImportInfo.
void	MLSpaceExportInfoInit(MLSpaceExportInfo * inout_info) Initialize default values for MLSpaceExportInfo.
const char *	MLSpaceGetResultString(MLResult result) Returns an ASCII string for MLSpaceResult and MLResult codes.
MLResult	MLSpaceManagerCreate(const MLSpaceManagerSettings settings, MLHandle out_handle) Creates a Magic Leap Space manager handle.
MLResult	MLSpaceSetCallbacks(MLHandle handle, const MLSpaceCallbacks callbacks, void user_data) Set the callbacks for events related to the Magic Leap Space.
MLResult	MLSpaceGetSpaceList(MLHandle handle, const MLSpaceQueryFilter query_filter, MLSpaceList out_space_list) Get the list of available spaces.
MLResult	MLSpaceReleaseSpaceList(MLHandle handle, MLSpaceList * space_list) Release the list of available spaces.
MLResult	MLSpaceRequestLocalization(MLHandle handle, const MLSpaceLocalizationInfo * localization_info) Send a request to localize to a given Magic Leap Space.
MLResult	MLSpaceGetLocalizationResult(MLHandle handle, MLSpaceLocalizationResult * out_localization_result) Get the localization results.
MLResult	MLSpaceManagerDestroy(MLHandle handle) Destroys a Space manager handle.
MLResult	MLSpaceImportSpace(const MLSpaceImportInfo import_info, MLSpaceImportOutData out_data) Import a Magic Leap Space.
MLResult	MLSpaceExportSpace(const MLSpaceExportInfo export_info, MLSpaceExportOutData out_data) Export an on device Magic Leap Space.
MLResult	MLSpaceReleaseExportData(MLSpaceExportOutData * space_data) Release resources acquired in MLSpaceExportSpace.

Enums Documentation

Anonymous Enum 28

Enumerator	Value	Description
MLResultAPIPrefix_Space	( 0x10cc << 16)	Defines the prefix for MLSpaceResult codes.
MLSpace_MaxSpaceNameLength	64	Maximum size for the name of a Magic Leap Space.

MLSpaceResult

Enumerator	Value	Description
MLSpaceResult_ServerError	MLResultAPIPrefix_Space	There was an error communicating with the server.
MLSpaceResult_ServiceUnavailable		The operation failed because the underlying service is not yet available, retry later.
MLSpaceResult_UnavailableSpace		Space is not available. This can happen when the selected space is in AR Cloud but the device is configured for On Device spaces or vice-versa.
MLSpaceResult_IncompatibleSpace		Space is not compatible with the current OS version. This can happen when a space exported from an older version of the OS is imported to a device running a newer version of the OS. Refer to the documentation at the top of this header for more notes on Space compatibility.
MLSpaceResult_SpaceAlreadyExists		The operation failed because the Space being imported already exists in the device.
MLSpaceResult_Ensure32Bits	0x7FFFFFFF	Ensure enum is represented as 32 bits.

Magic Leap Space specific return codes.

API Level:

MLSpaceType

Enumerator	Value	Description
MLSpaceType_OnDevice	0	On device space.
MLSpaceType_ARCloud	1	AR Cloud based space.
MLSpaceType_Ensure32Bits	0x7FFFFFFF	Ensure enum is represented as 32 bits.

Space type. Indicates the type of the Space.

API Level:

MLSpaceLocalizationStatus

Enumerator	Value	Description
MLSpaceLocalizationStatus_NotLocalized	0	The device is currently not localized.
MLSpaceLocalizationStatus_Localized	1	The device has localized successfully.
MLSpaceLocalizationStatus_LocalizationPending	2	Localization attempt is currently in progress.
MLSpaceLocalizationStatus_SleepingBeforeRetry	3	The device will attempt to localize after sleep duration is complete.
MLSpaceLocalizationStatus_Ensure32Bits	0x7FFFFFFF	Ensure enum is represented as 32 bits.

The current localization status.

API Level:

MLSpaceLocalizationConfidence

Enumerator	Value	Description
MLSpaceLocalizationConfidence_Poor	0	Localization confidence is very poor and should be reattempted.
MLSpaceLocalizationConfidence_Fair	1	The confidence is low, current environmental conditions may adversely affect localization.
MLSpaceLocalizationConfidence_Good	2	The confidence is high, persistent content should be stable.
MLSpaceLocalizationConfidence_Excellent	3	This is a very high-confidence localization, persistent content will be very stable.
MLSpaceLocalizationConfidence_Ensure32Bits	0x7FFFFFFF	Ensure enum is represented as 32 bits.

The confidence of the current localization.

API Level:

MLSpaceLocalizationErrorFlag

Enumerator	Value	Description
MLSpaceLocalizationErrorFlag_None	0	No error, localization was successful.
MLSpaceLocalizationErrorFlag_Unknown	1 << 0	Localization failed for an unknown reason.
MLSpaceLocalizationErrorFlag_OutOfMappedArea	1 << 1	Localization failed becuase the user is outside of the mapped area.
MLSpaceLocalizationErrorFlag_LowFeatureCount	1 << 2	There are not enough features in the environment to successfully localize.
MLSpaceLocalizationErrorFlag_ExcessiveMotion	1 << 3	Localization failed due to excessive motion.
MLSpaceLocalizationErrorFlag_LowLight	1 << 4	Localization failed because the lighting levels are too low in the environment.
MLSpaceLocalizationErrorFlag_HeadposeFailure	1 << 5	A headpose failure caused localization to be unsuccessful.
MLSpaceLocalizationErrorFlag_AlgorithmFailure	1 << 6	There was an internal algorithm failure that prevented localization.
MLSpaceLocalizationErrorFlag_Ensure32Bits	0x7FFFFFFF	Ensure enum is represented as 32 bits.

A set of possible reasons that a localization attempt may be unsuccessful.

API Level:

Types Documentation

MLSpaceManagerSettings

typedef struct MLSpaceManagerSettings MLSpaceManagerSettings;

A structure containing settings for the space manager. This structure must be initialized by calling MLSpaceManagerSettingsInit before use.

More Info

API Level:

MLSpace

typedef struct MLSpace MLSpace;

A structure containing information about a Magic Leap Space. This structure must be initialized by calling MLSpaceInit before use.

More Info

API Level:

MLSpaceList

typedef struct MLSpaceList MLSpaceList;

A structure containing list of MLSpace. This structure must be initialized by calling MLSpaceListInit before use.

More Info

API Level:

MLSpaceQueryFilter

typedef struct MLSpaceQueryFilter MLSpaceQueryFilter;

A collection of filters for Magic Leap Spaces. This structure must be initialized by calling MLSpaceQueryFilterInit before use. There is no support for filters at this time.

More Info

API Level:

MLSpaceLocalizationInfo

typedef struct MLSpaceLocalizationInfo MLSpaceLocalizationInfo;

A collection of parameters to be used for localization request. This structure must be initialized by calling MLSpaceLocalizationInfoInit before use.

More Info

API Level:

MLSpaceLocalizationResult

typedef struct MLSpaceLocalizationResult MLSpaceLocalizationResult;

A structure containing information about the device's localization state. This structure must be initialized by calling MLSpaceLocalizationResultInit before use.

More Info

API Level:

MLSpaceCallbacks

typedef struct MLSpaceCallbacks MLSpaceCallbacks;

A structure containing callbacks for events related to the Space.

This structure must be initialized by calling MLSpaceCallbacksInit before use. Application can unregister (stop receiving callbacks) at any time by setting the corresponding callback to NULL.

More Info

API Level:

MLSpaceImportInfo

typedef struct MLSpaceImportInfo MLSpaceImportInfo;

A structure containing information needed to import Magic Leap Space. This structure must be initialized by calling MLSpaceImportInfoInit before use.

More Info

API Level:

MLSpaceImportOutData

typedef struct MLSpaceImportOutData MLSpaceImportOutData;

A structure containing information about the imported Space.

More Info

API Level:

MLSpaceExportInfo

typedef struct MLSpaceExportInfo MLSpaceExportInfo;

A structure containing information about the Space export settings. This structure must be initialized by calling MLSpaceExportInfoInit before use.

More Info

API Level:

MLSpaceExportOutData

typedef struct MLSpaceExportOutData MLSpaceExportOutData;

A structure containing information about the exported Space.

More Info

API Level:

Functions Documentation

MLSpaceManagerSettingsInit

static inline void MLSpaceManagerSettingsInit(
    MLSpaceManagerSettings * inout_info
)

Initializes default values for MLSpaceManagerSettings.

Parameters


MLSpaceManagerSettings *	inout_info	The object to initialize with default values.

Required Permissions:

None

API Level:

MLSpaceInit

static inline void MLSpaceInit(
    MLSpace * inout_info
)

Initializes default values for MLSpace.

Parameters


MLSpace *	inout_info	The object to initialize with default values.

Required Permissions:

None

API Level:

MLSpaceListInit

static inline void MLSpaceListInit(
    MLSpaceList * inout_info
)

Initializes default values for MLSpaceList.

Parameters


MLSpaceList *	inout_info	The object to initialize with default values.

Required Permissions:

None

API Level:

MLSpaceQueryFilterInit

static inline void MLSpaceQueryFilterInit(
    MLSpaceQueryFilter * inout_query_filter
)

Initializes the default values for a query filter.

Parameters


MLSpaceQueryFilter *	inout_query_filter	The filter to initialize.

Required Permissions:

None

API Level:

MLSpaceLocalizationInfoInit

static inline void MLSpaceLocalizationInfoInit(
    MLSpaceLocalizationInfo * inout_info
)

Initializes the default values for localization info.

Parameters


MLSpaceLocalizationInfo *	inout_info	The object to initialize with default values.

Required Permissions:

None

API Level:

MLSpaceLocalizationResultInit

static inline void MLSpaceLocalizationResultInit(
    MLSpaceLocalizationResult * inout_info
)

Initialize default values for MLSpaceLocalizationResult.

Parameters


MLSpaceLocalizationResult *	inout_info	The localization result to initialize.

Required Permissions:

None

API Level:

MLSpaceCallbacksInit

static inline void MLSpaceCallbacksInit(
    MLSpaceCallbacks * inout_callbacks
)

Initialize defaults for MLSpaceCallbacks.

Parameters


MLSpaceCallbacks *	inout_callbacks	The callback structure to initialize.

Required Permissions:

None

API Level:

MLSpaceImportInfoInit

static inline void MLSpaceImportInfoInit(
    MLSpaceImportInfo * inout_info
)

Initialize default values for MLSpaceImportInfo.

Parameters


MLSpaceImportInfo *	inout_info	The object to initialize with default values.

Required Permissions:

None

API Level:

MLSpaceExportInfoInit

static inline void MLSpaceExportInfoInit(
    MLSpaceExportInfo * inout_info
)

Initialize default values for MLSpaceExportInfo.

Parameters


MLSpaceExportInfo *	inout_info	The object to initialize with default values.

Required Permissions:

None

API Level:

MLSpaceGetResultString

const char * MLSpaceGetResultString(
    MLResult result
)

Returns an ASCII string for MLSpaceResult and MLResult codes.

Parameters


MLResult	result	The input MLResult enum from MLSpace functions.

Required Permissions:

None

Return: ASCII string containing readable version of result code.

API Level:

MLSpaceManagerCreate

MLResult MLSpaceManagerCreate(
    const MLSpaceManagerSettings * settings,
    MLHandle * out_handle
)

Creates a Magic Leap Space manager handle.

Parameters


const MLSpaceManagerSettings *	settings	Settings that configures the space manager.
MLHandle *	out_handle	The handle to be created.

Returns


MLResult	MLResult_ClientLimitExceeded	Failed due to an existing manager.
MLResult	MLResult_InvalidParam	One or more input parameters are not valid.
MLResult	MLResult_Ok	Space manager handle was successfully created.
MLResult	MLResult_PermissionDenied	Necessary permission is missing.
MLResult	MLResult_UnspecifiedFailure	Operation failed for unknown reason.

Required Permissions:

com.magicleap.permission.SPACE_MANAGER (protection level: normal)

Application can create only one Magic Leap Space manager handle. Multiple calls to create a manager handle will result in a failure. The handle is valid for the lifecycle of the application.

API Level:

MLSpaceSetCallbacks

MLResult MLSpaceSetCallbacks(
    MLHandle handle,
    const MLSpaceCallbacks * callbacks,
    void * user_data
)

Set the callbacks for events related to the Magic Leap Space.

Parameters


MLHandle	handle	Space manager handle created by MLSpaceManagerCreate.
const MLSpaceCallbacks *	callbacks	Pointer to the MLSpaceCallbacks structure containing the callbacks.
void *	user_data	Pointer that will be returned in the callback.

Returns


MLResult	MLResult_InvalidParam	One or more input parameters are not valid.
MLResult	MLResult_Ok	The callbacks were registered successfully.
MLResult	MLResult_UnspecifiedFailure	Operation failed for unknown reason.

API Level:

MLSpaceGetSpaceList

MLResult MLSpaceGetSpaceList(
    MLHandle handle,
    const MLSpaceQueryFilter * query_filter,
    MLSpaceList * out_space_list
)

Get the list of available spaces.

Parameters


MLHandle	handle	Space manager handle created by MLSpaceManagerCreate.
const MLSpaceQueryFilter *	query_filter	The filter structure for the query.
MLSpaceList *	out_space_list	List of Spaces currently available to the device.

Returns


MLResult	MLResult_InvalidParam	One or more input parameters are not valid.
MLResult	MLResult_Ok	List of spaces retrieved successfully.
MLResult	MLResult_Unauthenticated	Invalid authentication credentials for this operation.
MLResult	MLResult_UnspecifiedFailure	Operation failed for unknown reason.
MLResult	MLSpaceResult_ServerError	Operation failed due to server side error.
MLResult	MLSpaceResult_ServiceUnavailable	Operation failed because service is not ready.

Required Permissions:

None

The list of spaces returned will depend on the current device mapping mode. Only the Spaces associated with the current mapping mode will be returned by this call. Device mapping mode can be changed via the system application(s).

The list memory is owned by the library, call MLSpaceReleaseSpaceList to release the memory. Each get MLSpaceGetSpaceList should have a corresponding MLSpaceReleaseSpaceList.

API Level:

MLSpaceReleaseSpaceList

MLResult MLSpaceReleaseSpaceList(
    MLHandle handle,
    MLSpaceList * space_list
)

Release the list of available spaces.

Parameters


MLHandle	handle	Space manager handle created by MLSpaceManagerCreate.
MLSpaceList *	space_list	List Magic Leap Spaces that needs to be released.

Returns


MLResult	MLResult_InvalidParam	One or more input parameters are not valid.
MLResult	MLResult_Ok	List resources was successfully released.
MLResult	MLResult_UnspecifiedFailure	Operation failed for unknown reason.

Required Permissions:

None

API Level:

MLSpaceRequestLocalization

MLResult MLSpaceRequestLocalization(
    MLHandle handle,
    const MLSpaceLocalizationInfo * localization_info
)

Send a request to localize to a given Magic Leap Space.

Parameters


MLHandle	handle	Space manager handle created by MLSpaceManagerCreate.
const MLSpaceLocalizationInfo *	localization_info	Magic Leap Space to localize into.

Returns


MLResult	MLResult_InvalidParam	One or more input parameters are not valid.
MLResult	MLResult_Ok	Localization request was submitted successfully.
MLResult	MLResult_Unauthenticated	Invalid authentication credentials for this operation.
MLResult	MLResult_UnspecifiedFailure	Operation failed for unknown reason.
MLResult	MLSpaceResult_UnavailableSpace	Operation failed due an unavailable Space.
MLResult	MLSpaceResult_ServerError	Operation failed due to server side error.
MLResult	MLSpaceResult_ServiceUnavailable	Operation failed because service is not ready.

Required Permissions:

None

This is an asynchronous request. Use MLSpaceGetLocalizationResult to get the results of the localization or use MLSpaceCallbacks to listen to on_localization_changed events.

A new request for localization will override all the past requests for localization that are yet to be completed.

API Level:

MLSpaceGetLocalizationResult

MLResult MLSpaceGetLocalizationResult(
    MLHandle handle,
    MLSpaceLocalizationResult * out_localization_result
)

Get the localization results.

Parameters


MLHandle	handle	Space manager handle created by MLSpaceManagerCreate.
MLSpaceLocalizationResult *	out_localization_result	Contains the result of the localization request.

Returns


MLResult	MLResult_InvalidParam	One or more input parameters are not valid.
MLResult	MLResult_Ok	Localization result was retrieved successfully.
MLResult	MLResult_Unauthenticated	Invalid authentication credentials for this operation.
MLResult	MLResult_UnspecifiedFailure	Operation failed for unknown reason.

Required Permissions:

None

Returns the results of the most recent localization request.

API Level:

MLSpaceManagerDestroy

MLResult MLSpaceManagerDestroy(
    MLHandle handle
)

Destroys a Space manager handle.

Parameters


MLHandle	handle	The handle to be destroyed.

Returns


MLResult	MLResult_InvalidParam	One or more input parameters are not valid.
MLResult	MLResult_Ok	Space manager handle was successfully destroyed.

Required Permissions:

None

API Level:

MLSpaceImportSpace

MLResult MLSpaceImportSpace(
    const MLSpaceImportInfo * import_info,
    MLSpaceImportOutData * out_data
)

Import a Magic Leap Space.

Parameters


const MLSpaceImportInfo *	import_info	Information need to import the space.
MLSpaceImportOutData *	out_data	Information about the imported space.

Returns


MLResult	MLResult_InvalidParam	One or more input parameters are not valid.
MLResult	MLResult_PermissionDenied	Necessary permission is missing.
MLResult	MLResult_UnspecifiedFailure	Operation failed for unknown reason.
MLResult	MLSpaceResult_IncompatibleSpace	Operation failed due an incompatible Space.
MLResult	MLSpaceResult_SpaceAlreadyExists	Operation failed because Space being imported already exists.

Required Permissions:

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

The MLSpaceImportInfo memory is owned by the app and the app should make sure to release the memory once the API call has returned.

API Level:

MLSpaceExportSpace

MLResult MLSpaceExportSpace(
    const MLSpaceExportInfo * export_info,
    MLSpaceExportOutData * out_data
)

Export an on device Magic Leap Space.

Parameters


const MLSpaceExportInfo *	export_info	Information needed to export the space.
MLSpaceExportOutData *	out_data	Exported space data.

Returns


MLResult	MLResult_InvalidParam	One or more input parameters are not valid.
MLResult	MLResult_PermissionDenied	Necessary permission is missing.
MLResult	MLResult_UnspecifiedFailure	Operation failed for unknown reason.
MLResult	MLSpaceResult_UnavailableSpace	Operation failed due an unavailable Space.

Required Permissions:

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

The MLSpaceExportOutData is owned by the library, call MLSpaceReleaseExportData to release the memory. Each MLSpaceExportSpace call should have a corresponding MLSpaceReleaseExportData.

API Level:

MLSpaceReleaseExportData

MLResult MLSpaceReleaseExportData(
    MLSpaceExportOutData * space_data
)

Release resources acquired in MLSpaceExportSpace.

Parameters


MLSpaceExportOutData *	space_data	MLSpaceExportOutData that needs to be released.

Returns


MLResult	MLResult_InvalidParam	One or more input parameters are not valid.
MLResult	MLResult_Ok	List resources was successfully released.
MLResult	MLResult_UnspecifiedFailure	Operation failed for unknown reason.

Required Permissions:

None

API Level:

Source code

// %BANNER_BEGIN%
// ---------------------------------------------------------------------
// %COPYRIGHT_BEGIN%
// Copyright (c) 2023 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 "ml_api.h"
#include "ml_types.h"

#include <string.h>

ML_EXTERN_C_BEGIN

enum {
  MLResultAPIPrefix_Space = MLRESULT_PREFIX(0x10cc),
  MLSpace_MaxSpaceNameLength = 64,
};

typedef enum MLSpaceResult {
  MLSpaceResult_ServerError = MLResultAPIPrefix_Space,
  MLSpaceResult_ServiceUnavailable,
  MLSpaceResult_UnavailableSpace,
  MLSpaceResult_IncompatibleSpace,
  MLSpaceResult_SpaceAlreadyExists,
  MLSpaceResult_Ensure32Bits = 0x7FFFFFFF
} MLSpaceResult;

typedef enum MLSpaceType {
  MLSpaceType_OnDevice = 0,
  MLSpaceType_ARCloud = 1,
  MLSpaceType_Ensure32Bits = 0x7FFFFFFF
} MLSpaceType;

typedef enum MLSpaceLocalizationStatus {
  MLSpaceLocalizationStatus_NotLocalized = 0,
  MLSpaceLocalizationStatus_Localized = 1,
  MLSpaceLocalizationStatus_LocalizationPending = 2,
  MLSpaceLocalizationStatus_SleepingBeforeRetry = 3,
  MLSpaceLocalizationStatus_Ensure32Bits = 0x7FFFFFFF
} MLSpaceLocalizationStatus;

typedef enum MLSpaceLocalizationConfidence {
  MLSpaceLocalizationConfidence_Poor = 0,
  MLSpaceLocalizationConfidence_Fair = 1,
  MLSpaceLocalizationConfidence_Good = 2,
  MLSpaceLocalizationConfidence_Excellent = 3,
  MLSpaceLocalizationConfidence_Ensure32Bits = 0x7FFFFFFF
} MLSpaceLocalizationConfidence;

typedef enum MLSpaceLocalizationErrorFlag {
  MLSpaceLocalizationErrorFlag_None = 0,
  MLSpaceLocalizationErrorFlag_Unknown = 1 << 0,
  MLSpaceLocalizationErrorFlag_OutOfMappedArea = 1 << 1,
  MLSpaceLocalizationErrorFlag_LowFeatureCount = 1 << 2,
  MLSpaceLocalizationErrorFlag_ExcessiveMotion = 1 << 3,
  MLSpaceLocalizationErrorFlag_LowLight = 1 << 4,
  MLSpaceLocalizationErrorFlag_HeadposeFailure = 1 << 5,
  MLSpaceLocalizationErrorFlag_AlgorithmFailure = 1 << 6,
  MLSpaceLocalizationErrorFlag_Ensure32Bits = 0x7FFFFFFF
} MLSpaceLocalizationErrorFlag;

typedef struct MLSpaceManagerSettings {
  uint32_t version;
} MLSpaceManagerSettings;

ML_STATIC_INLINE void MLSpaceManagerSettingsInit(MLSpaceManagerSettings *inout_info) {
  if (inout_info) {
    memset(inout_info, 0, sizeof(MLSpaceManagerSettings));
    inout_info->version = 1u;
  }
}

typedef struct MLSpace {
  uint32_t version;
  char space_name[MLSpace_MaxSpaceNameLength];
  MLUUID space_id;
  MLSpaceType space_type;
} MLSpace;

ML_STATIC_INLINE void MLSpaceInit(MLSpace *inout_info) {
  if (inout_info) {
    memset(inout_info, 0, sizeof(MLSpace));
    inout_info->version = 1u;
  }
}


typedef struct MLSpaceList {
  uint32_t version;
  uint32_t space_count;
  MLSpace *spaces;
} MLSpaceList;

ML_STATIC_INLINE void MLSpaceListInit(MLSpaceList *inout_info) {
  if (inout_info) {
    memset(inout_info, 0, sizeof(MLSpaceList));
    inout_info->version = 1u;
  }
}

typedef struct MLSpaceQueryFilter {
  uint32_t version;
} MLSpaceQueryFilter;

ML_STATIC_INLINE void MLSpaceQueryFilterInit(MLSpaceQueryFilter *inout_query_filter) {
  if (inout_query_filter != NULL) {
    memset(inout_query_filter, 0, sizeof(MLSpaceQueryFilter));
    inout_query_filter->version = 1;
  }
}

typedef struct MLSpaceLocalizationInfo {
  uint32_t version;
  MLUUID space_id;
} MLSpaceLocalizationInfo ;

ML_STATIC_INLINE void MLSpaceLocalizationInfoInit(MLSpaceLocalizationInfo *inout_info) {
  if (inout_info != NULL) {
    memset(inout_info, 0, sizeof(MLSpaceLocalizationInfo));
    inout_info->version = 1;
  }
}

typedef struct MLSpaceLocalizationResult {
  uint32_t version;
  MLSpaceLocalizationStatus localization_status;
  MLSpace space;
  MLCoordinateFrameUID target_space_origin;
  MLSpaceLocalizationConfidence localization_confidence;
  uint32_t error;
} MLSpaceLocalizationResult;

ML_STATIC_INLINE void MLSpaceLocalizationResultInit(MLSpaceLocalizationResult *inout_info) {
  if (inout_info != NULL) {
    memset(inout_info, 0, sizeof(MLSpaceLocalizationResult));
    inout_info->version = 3;
  }
}

typedef struct MLSpaceCallbacks {
  uint32_t version;
  void (*on_localization_changed)(const MLSpaceLocalizationResult *localization_result, void *user_data);
 } MLSpaceCallbacks;

ML_STATIC_INLINE void MLSpaceCallbacksInit(MLSpaceCallbacks *inout_callbacks) {
  if (inout_callbacks != NULL) {
    inout_callbacks->version = 1;
    inout_callbacks->on_localization_changed = NULL;
  }
}

typedef struct MLSpaceImportInfo {
  uint32_t version;
  uint64_t size;
  const char* data;
} MLSpaceImportInfo;

ML_STATIC_INLINE void MLSpaceImportInfoInit(MLSpaceImportInfo *inout_info) {
  if (inout_info != NULL) {
    memset(inout_info, 0, sizeof(MLSpaceImportInfo));
    inout_info->version = 1;
  }
}

typedef struct MLSpaceImportOutData {
  MLUUID space_id;
} MLSpaceImportOutData;



typedef struct MLSpaceExportInfo {
  uint32_t version;
  MLUUID space_id;
} MLSpaceExportInfo;

ML_STATIC_INLINE void MLSpaceExportInfoInit(MLSpaceExportInfo *inout_info) {
  if (inout_info != NULL) {
    memset(inout_info, 0, sizeof(MLSpaceExportInfo));
    inout_info->version = 1;
  }
}

typedef struct MLSpaceExportOutData {
  uint64_t size;
  const char* data;
} MLSpaceExportOutData;


ML_API const char *ML_CALL MLSpaceGetResultString(MLResult result);



ML_API MLResult ML_CALL MLSpaceManagerCreate(const MLSpaceManagerSettings* settings, MLHandle* out_handle);

ML_API MLResult ML_CALL MLSpaceSetCallbacks(MLHandle handle, const MLSpaceCallbacks *callbacks, void* user_data);

ML_API MLResult ML_CALL MLSpaceGetSpaceList(MLHandle handle, const MLSpaceQueryFilter* query_filter, MLSpaceList* out_space_list);

ML_API MLResult ML_CALL MLSpaceReleaseSpaceList(MLHandle handle, MLSpaceList* space_list);

ML_API MLResult ML_CALL MLSpaceRequestLocalization(MLHandle handle, const MLSpaceLocalizationInfo* localization_info);

ML_API MLResult ML_CALL MLSpaceGetLocalizationResult(MLHandle handle, MLSpaceLocalizationResult* out_localization_result);

ML_API MLResult ML_CALL MLSpaceManagerDestroy(MLHandle handle);

ML_API MLResult ML_CALL MLSpaceImportSpace(const MLSpaceImportInfo* import_info, MLSpaceImportOutData* out_data);


ML_API MLResult ML_CALL MLSpaceExportSpace(const MLSpaceExportInfo* export_info, MLSpaceExportOutData* out_data);

ML_API MLResult ML_CALL MLSpaceReleaseExportData(MLSpaceExportOutData* space_data);

ML_EXTERN_C_END

ml_space.h

Classes​

Types​

Enums​

Functions​

Enums Documentation​

Anonymous Enum 28​

MLSpaceResult​

MLSpaceType​

MLSpaceLocalizationStatus​

MLSpaceLocalizationConfidence​

MLSpaceLocalizationErrorFlag​

Types Documentation​

MLSpaceManagerSettings​

MLSpace​

MLSpaceList​

MLSpaceQueryFilter​

MLSpaceLocalizationInfo​

MLSpaceLocalizationResult​

MLSpaceCallbacks​

MLSpaceImportInfo​

MLSpaceImportOutData​

MLSpaceExportInfo​

MLSpaceExportOutData​

Functions Documentation​

MLSpaceManagerSettingsInit​

MLSpaceInit​

MLSpaceListInit​

MLSpaceQueryFilterInit​

MLSpaceLocalizationInfoInit​

MLSpaceLocalizationResultInit​

MLSpaceCallbacksInit​

MLSpaceImportInfoInit​

MLSpaceExportInfoInit​

MLSpaceGetResultString​

MLSpaceManagerCreate​

MLSpaceSetCallbacks​

MLSpaceGetSpaceList​

MLSpaceReleaseSpaceList​

MLSpaceRequestLocalization​

MLSpaceGetLocalizationResult​

MLSpaceManagerDestroy​

MLSpaceImportSpace​

MLSpaceExportSpace​

MLSpaceReleaseExportData​

Source code​

Classes

Types

Enums

Functions

Enums Documentation

Anonymous Enum 28

MLSpaceResult

MLSpaceType

MLSpaceLocalizationStatus

MLSpaceLocalizationConfidence

MLSpaceLocalizationErrorFlag

Types Documentation

MLSpaceManagerSettings

MLSpace

MLSpaceList

MLSpaceQueryFilter

MLSpaceLocalizationInfo

MLSpaceLocalizationResult

MLSpaceCallbacks

MLSpaceImportInfo

MLSpaceImportOutData

MLSpaceExportInfo

MLSpaceExportOutData

Functions Documentation

MLSpaceManagerSettingsInit

MLSpaceInit

MLSpaceListInit

MLSpaceQueryFilterInit

MLSpaceLocalizationInfoInit

MLSpaceLocalizationResultInit

MLSpaceCallbacksInit

MLSpaceImportInfoInit

MLSpaceExportInfoInit

MLSpaceGetResultString

MLSpaceManagerCreate

MLSpaceSetCallbacks

MLSpaceGetSpaceList

MLSpaceReleaseSpaceList

MLSpaceRequestLocalization

MLSpaceGetLocalizationResult

MLSpaceManagerDestroy

MLSpaceImportSpace

MLSpaceExportSpace

MLSpaceReleaseExportData

Source code