Version: 20 Mar 2024

ml_api.h

Classes

	Name
struct	MLVersion

Types

	Name
typedef uint64_t	MLHandle Integer handle type used to reference many things returned by the API, instead of returning pointers directly. Use MLHandleIsValid() to check if a handle is valid or not.
typedef struct MLVersion	MLVersion
typedef int32_t	MLResult

Enums

	Name
enum	Anonymous Enum 0 { ML_INVALID_HANDLE = 0xFFFFFFFFFFFFFFFF }
enum	Anonymous Enum 1 { MLVersion_BuildIdMaxLength = 128 }
enum	Anonymous Enum 2 { MLResultAPIPrefix_Global = ( 0 << 16) }
enum	MLResultGlobal { MLResult_Ok = MLResultAPIPrefix_Global, MLResult_Pending, MLResult_Timeout, MLResult_Locked, MLResult_UnspecifiedFailure, MLResult_InvalidParam, MLResult_AllocFailed, MLResult_PermissionDenied, MLResult_NotImplemented, MLResult_ClientLimitExceeded, MLResult_PoseNotFound, MLResult_IncompatibleSKU, MLResult_PerceptionSystemNotStarted, MLResult_IllegalState, MLResult_LicenseError, MLResult_InvalidTimestamp, MLResult_Unauthenticated, MLResult_Ensure32Bits = 0x7FFFFFFF }

Functions

	Name
const char *	MLGetResultString(MLResult result_code) Returns an ASCII string for MLResultGlobal codes.
const char *	MLGlobalGetResultString(MLResult result_code) Returns an ASCII string for MLResult codes.
bool	MLHandleIsValid(MLHandle handle) Check if a handle is valid.
const char *	MLGetVersionName() Get SDK version as c-style string.
MLVersion	MLGetVersion() Get SDK version as a struct with major, minor, revision, and build_id.

Defines

	Name
	ML_API
	ML_CALL
	ML_DEPRECATED_MSG(msg)
	ML_DEPRECATED
	ML_STATIC_INLINE
	ML_EXTERN_C_BEGIN
	ML_EXTERN_C_END
	MLRESULT_PREFIX(val)

Enums Documentation

Anonymous Enum 0

Enumerator	Value	Description
ML_INVALID_HANDLE	0xFFFFFFFFFFFFFFFF	Value of an invalid handle. To test if a handle is invalid use MLHandleIsValid().

Anonymous Enum 1

Enumerator	Value	Description
MLVersion_BuildIdMaxLength	128	Maximum character length of MLVersion build ID.

Anonymous Enum 2

Enumerator	Value	Description
MLResultAPIPrefix_Global	( 0 << 16)	Defines the prefix for global MLResult codes.

MLResultGlobal

Enumerator	Value	Description
MLResult_Ok	MLResultAPIPrefix_Global	Operation completed successfully.
MLResult_Pending		Asynchronous operation has not completed.
MLResult_Timeout		Operation has timed out.
MLResult_Locked		Request to lock a shared resource that is already locked.
MLResult_UnspecifiedFailure		Operation failed due to an unspecified internal error.
MLResult_InvalidParam		Operation failed due to an invalid parameter being supplied.
MLResult_AllocFailed		Operation failed because memory failed to be allocated.
MLResult_PermissionDenied		Operation failed because a required permission has not been granted.
MLResult_NotImplemented		Operation failed because it is not currently implemented.
MLResult_ClientLimitExceeded		Operation failed because the client count exceeded the number of clients available.
MLResult_PoseNotFound		Operation failed because the requested pose is not available.
MLResult_IncompatibleSKU		Operation failed because feature isn't supported on current device version.
MLResult_PerceptionSystemNotStarted		Operation failed because the Perception System was not started.
MLResult_IllegalState		Operation failed because it has been invoked at the wrong time.
MLResult_LicenseError		Operation failed because of missing/incompatible license.
MLResult_InvalidTimestamp		Operation failed because the timestamp parameter was outside the expected range.
MLResult_Unauthenticated		Operation failed because the user authentication did not pass.
MLResult_Ensure32Bits	0x7FFFFFFF	Ensure enum is represented as 32 bits.

Global MLResult codes that any API can optionally return.

Types Documentation

MLHandle

typedef uint64_t MLHandle;

Integer handle type used to reference many things returned by the API, instead of returning pointers directly. Use MLHandleIsValid() to check if a handle is valid or not.

MLVersion

typedef struct MLVersion MLVersion;

SDK version: '[major].[minor].[revision].[build_id]'.

More Info

MLResult

typedef int32_t MLResult;

MLResult type that all functions in the APIs return.

Functions Documentation

MLGetResultString

static inline const char * MLGetResultString(
    MLResult result_code
)

Returns an ASCII string for MLResultGlobal codes.

Parameters


MLResult	result_code	The input MLResult enum from ML API functions.

Required Permissions:

None

Return: ASCII string containing readable version of result code.

MLGlobalGetResultString

const char * MLGlobalGetResultString(
    MLResult result_code
)

Returns an ASCII string for MLResult codes.

Parameters


MLResult	result_code	The input MLResult enum from ML API functions.

Required Permissions:

None

Return: ASCII string containing readable version of result code.

API Level:

MLHandleIsValid

static inline bool MLHandleIsValid(
    MLHandle handle
)

Check if a handle is valid.

Parameters


MLHandle	handle	The handle to check.

Required Permissions:

None

Return: true if the handle is valid.

MLGetVersionName

static inline const char * MLGetVersionName()

Get SDK version as c-style string.

Required Permissions:

None

Return: SDK version as c-style string.

MLGetVersion

static inline MLVersion MLGetVersion()

Get SDK version as a struct with major, minor, revision, and build_id.

Required Permissions:

None

Return: SDK version as a struct.

Macros Documentation

ML_API

#define ML_API 

ML_CALL

#define ML_CALL 

ML_DEPRECATED_MSG

#define ML_DEPRECATED_MSG(
    msg
)
__attribute__((deprecated(msg)))

Parameters


	msg

ML_DEPRECATED

#define ML_DEPRECATED __attribute__((deprecated))

ML_STATIC_INLINE

#define ML_STATIC_INLINE static inline

ML_EXTERN_C_BEGIN

#define ML_EXTERN_C_BEGIN 

ML_EXTERN_C_END

#define ML_EXTERN_C_END 

MLRESULT_PREFIX

#define MLRESULT_PREFIX(
    val
)
(val << 16)

Parameters


	val

Macro to set a the prefix bytes of an API specific MLResult code.

Source code

// %BANNER_BEGIN%
// ---------------------------------------------------------------------
// %COPYRIGHT_BEGIN%
// Copyright (c) 2017 Magic Leap, Inc. All Rights Reserved.
// Use of this file is governed by the Software License Agreement,
// located here: https://www.magicleap.com/software-license-agreement-ml2
// Terms and conditions applicable to third-party materials accompanying
// this distribution may also be found in the top-level NOTICE file
// appearing herein.
// %COPYRIGHT_END%
// ---------------------------------------------------------------------
// %BANNER_END%

#pragma once

#include <stdint.h>
#include <stdbool.h>
#include <stddef.h>

#if defined(_MSC_VER) && _MSC_VER
#ifdef ML_EXPORT
#define ML_API __declspec(dllexport)
#else
#define ML_API __declspec(dllimport)
#endif
#define ML_CALL __cdecl
#if defined(ML_NO_DEPRECATION_WARNING)
#define ML_DEPRECATED_MSG(msg)
#define ML_DEPRECATED
#if !defined(ML_NO_DEPRECATION_DISABLED_MSG)
#pragma message("Magic Leap C SDK - API deprecation warnings are disabled.")
#endif
#else
#define ML_DEPRECATED_MSG(msg) __declspec(deprecated(msg))
#define ML_DEPRECATED __declspec(deprecated)
#endif
#define ML_STATIC_INLINE __inline
#else
#define ML_API
#define ML_CALL
#if defined(ML_NO_DEPRECATION_WARNING)
#define ML_DEPRECATED_MSG(msg)
#define ML_DEPRECATED
#if !defined(ML_NO_DEPRECATION_DISABLED_MSG)
#pragma message("Magic Leap C SDK - API deprecation warnings are disabled.")
#endif
#else
#define ML_DEPRECATED_MSG(msg) __attribute__((deprecated(msg)))
#define ML_DEPRECATED __attribute__((deprecated))
#endif
#define ML_STATIC_INLINE static inline
#endif

#ifdef __cplusplus
#define ML_EXTERN_C_BEGIN extern "C" {
#define ML_EXTERN_C_END }
#else
#define ML_EXTERN_C_BEGIN
#define ML_EXTERN_C_END
#endif

#include "ml_coordinate_frame_uid.h"
#include "ml_version.h"

ML_EXTERN_C_BEGIN

typedef uint64_t MLHandle;

enum {
  ML_INVALID_HANDLE = 0xFFFFFFFFFFFFFFFF
};

enum {
  MLVersion_BuildIdMaxLength = 128
};

typedef struct MLVersion {
  uint32_t major;
  uint32_t minor;
  uint32_t revision;
  char build_id[MLVersion_BuildIdMaxLength];
} MLVersion;

#define MLRESULT_PREFIX(val) (val << 16)

enum {
  MLResultAPIPrefix_Global = MLRESULT_PREFIX(0),
};

typedef enum MLResultGlobal {
  MLResult_Ok = MLResultAPIPrefix_Global,
  MLResult_Pending,
  MLResult_Timeout,
  MLResult_Locked,
  MLResult_UnspecifiedFailure,
  MLResult_InvalidParam,
  MLResult_AllocFailed,
  MLResult_PermissionDenied,
  MLResult_NotImplemented,
  MLResult_ClientLimitExceeded,
  MLResult_PoseNotFound,
  MLResult_IncompatibleSKU,
  MLResult_PerceptionSystemNotStarted,
  MLResult_IllegalState,
  MLResult_LicenseError,
  MLResult_InvalidTimestamp,
  MLResult_Unauthenticated,
  MLResult_Ensure32Bits = 0x7FFFFFFF
} MLResultGlobal;

typedef int32_t MLResult;

ML_STATIC_INLINE const char* ML_CALL MLGetResultString(MLResult result_code) {
  switch (result_code) {
    case MLResult_Ok: return "MLResult_Ok";
    case MLResult_Pending: return "MLResult_Pending";
    case MLResult_Timeout: return "MLResult_Timeout";
    case MLResult_Locked: return "MLResult_Locked";
    case MLResult_UnspecifiedFailure: return "MLResult_UnspecifiedFailure";
    case MLResult_InvalidParam: return "MLResult_InvalidParam";
    case MLResult_AllocFailed: return "MLResult_AllocFailed";
    case MLResult_PermissionDenied: return "MLResult_PermissionDenied";
    case MLResult_NotImplemented: return "MLResult_NotImplemented";
    case MLResult_ClientLimitExceeded: return "MLResult_ClientLimitExceeded";
    case MLResult_IncompatibleSKU: return "MLResult_IncompatibleSKU";
    case MLResult_PoseNotFound: return "MLResult_PoseNotFound";
    case MLResult_PerceptionSystemNotStarted: return "MLResult_PerceptionSystemNotStarted";
    case MLResult_IllegalState: return "MLResult_IllegalState";
    case MLResult_LicenseError: return "MLResult_LicenseError";
    case MLResult_InvalidTimestamp: return "MLResult_InvalidTimestamp";
    case MLResult_Unauthenticated: return "MLResult_Unauthenticated";
    default: return "Unknown";
  }
}

ML_API  const char* ML_CALL MLGlobalGetResultString(MLResult result_code);

ML_STATIC_INLINE bool MLHandleIsValid(MLHandle handle) {
  return handle != ML_INVALID_HANDLE;
}

ML_STATIC_INLINE const char *ML_CALL MLGetVersionName() {
  return MLSDK_VERSION_NAME;
}

ML_STATIC_INLINE MLVersion MLGetVersion() {
  MLVersion version = {MLSDK_VERSION_MAJOR,
                       MLSDK_VERSION_MINOR,
                       MLSDK_VERSION_REVISION,
                       MLSDK_VERSION_BUILD_ID};
  return version;
}

ML_EXTERN_C_END

ml_api.h

Classes​

Types​

Enums​

Functions​

Defines​

Enums Documentation​

Anonymous Enum 0​

Anonymous Enum 1​

Anonymous Enum 2​

MLResultGlobal​

Types Documentation​

MLHandle​

MLVersion​

MLResult​

Functions Documentation​

MLGetResultString​

MLGlobalGetResultString​

MLHandleIsValid​

MLGetVersionName​

MLGetVersion​

Macros Documentation​

ML_API​

ML_CALL​

ML_DEPRECATED_MSG​

ML_DEPRECATED​

ML_STATIC_INLINE​

ML_EXTERN_C_BEGIN​

ML_EXTERN_C_END​

MLRESULT_PREFIX​

Source code​

Classes

Types

Enums

Functions

Defines

Enums Documentation

Anonymous Enum 0

Anonymous Enum 1

Anonymous Enum 2

MLResultGlobal

Types Documentation

MLHandle

MLVersion

MLResult

Functions Documentation

MLGetResultString

MLGlobalGetResultString

MLHandleIsValid

MLGetVersionName

MLGetVersion

Macros Documentation

ML_API

ML_CALL

ML_DEPRECATED_MSG

ML_DEPRECATED

ML_STATIC_INLINE

ML_EXTERN_C_BEGIN

ML_EXTERN_C_END

MLRESULT_PREFIX

Source code