ml_perception.h

Classes

	Name
struct	MLPerceptionSettings

Types

	Name
typedef struct MLPerceptionSettings	MLPerceptionSettings

Functions

	Name
MLResult	MLPerceptionInitSettings(MLPerceptionSettings * out_settings) Initializes the perception system with the passed in settings.
MLResult	MLPerceptionStartup(MLPerceptionSettings * settings) Starts the perception system.
MLResult	MLPerceptionShutdown() Shuts down the perception system and cleans up all resources used by it.
MLResult	MLPerceptionGetSnapshot(MLSnapshot ** out_snapshot) Pulls in the latest state of all persistent transforms and all enabled trackers extrapolated to the next frame time.
MLResult	MLPerceptionGetPredictedSnapshot(MLTime timestamp, MLSnapshot ** out_snapshot) Pulls in the state of all persistent transforms and all enabled trackers extrapolated to the provided timestamp.
MLResult	MLPerceptionReleaseSnapshot(MLSnapshot * snap) Releases specified #MLSnapshot object.

Types Documentation

MLPerceptionSettings

typedef struct MLPerceptionSettings MLPerceptionSettings;

Settings for initializing the perception system.

More Info

---

Functions Documentation

MLPerceptionInitSettings

MLResult MLPerceptionInitSettings(
    MLPerceptionSettings * out_settings
)

Initializes the perception system with the passed in settings.

Parameters

MLPerceptionSettings *	out_settings	Initializes the perception system with these settings.

Returns

MLResult	MLResult_InvalidParam	Failed to initialize the perception settings due to an invalid input parameter.
MLResult	MLResult_Ok	Successfully initialized the perception settings.
MLResult	MLResult_UnspecifiedFailure	Failed to initialize the perception settings due to an unknown error.

Required Permissions:

• None

---

MLPerceptionStartup

MLResult MLPerceptionStartup(
    MLPerceptionSettings * settings
)

Starts the perception system.

Parameters

MLPerceptionSettings *	settings	The perception system starts with these settings.

Returns

MLResult	MLResult_Ok	Successfully started perception system.
MLResult	MLResult_UnspecifiedFailure	Failed to start perception system due to an unknown failure.

Required Permissions:

• None

This function should be called before any perception functions are called.

---

MLPerceptionShutdown

MLResult MLPerceptionShutdown()

Shuts down the perception system and cleans up all resources used by it.

Returns

MLResult	MLResult_Ok	Successfully shut down the perception system.
MLResult	MLResult_UnspecifiedFailure	Failed to shut down the perception system because of an uknown failure.

Required Permissions:

• None

This function should be called prior to exiting the program if a call to [MLPerceptionStartup()](/docs/12-Dec-2024/api-ref/api/Modules/group___perception/#mlresult-mlperceptionstartup) was called.

---

MLPerceptionGetSnapshot

MLResult MLPerceptionGetSnapshot(
    MLSnapshot ** out_snapshot
)

Pulls in the latest state of all persistent transforms and all enabled trackers extrapolated to the next frame time.

Parameters

MLSnapshot **	out_snapshot	Pointer to a pointer containing an MLSnapshot on success.

Returns

MLResult	MLResult_Ok	Successfully created snapshot.
MLResult	MLResult_InvalidParam	out_snapshot parameter was not valid (null).
MLResult	MLResult_PerceptionSystemNotStarted	Perception System has not been started.

Required Permissions:

• None

Returns a MLSnapshot with this latest state. This snap should be used for the duration of the frame being constructed and then released with a call to [MLPerceptionReleaseSnapshot()](/docs/12-Dec-2024/api-ref/api/Modules/group___perception/#mlresult-mlperceptionreleasesnapshot).

---

MLPerceptionGetPredictedSnapshot

MLResult MLPerceptionGetPredictedSnapshot(
    MLTime timestamp,
    MLSnapshot ** out_snapshot
)

Pulls in the state of all persistent transforms and all enabled trackers extrapolated to the provided timestamp.

Parameters

MLTime	timestamp	Timestamp representing the time for which to predict poses.
MLSnapshot **	out_snapshot	Pointer to a pointer containing an MLSnapshot on success.

Returns

MLResult	MLResult_Ok	Successfully created snapshot.
MLResult	MLResult_InvalidTimestamp	Timestamp is either more than 100ms in the future or too old for cached state.
MLResult	MLResult_InvalidParam	Output parameter was not valid (null).
MLResult	MLResult_PerceptionSystemNotStarted	Perception System has not been started.

Required Permissions:

• None

This timestamp typically comes from out_frame_info.predicted_display_time out parameter from the MLGraphicsBeginFrameEx function.

Returns a MLSnapshot with this latest state. This snap should be used for the duration of the frame being constructed and then released with a call to [MLPerceptionReleaseSnapshot()](/docs/12-Dec-2024/api-ref/api/Modules/group___perception/#mlresult-mlperceptionreleasesnapshot).

API Level:

• 27

---

MLPerceptionReleaseSnapshot

MLResult MLPerceptionReleaseSnapshot(
    MLSnapshot * snap
)

Releases specified #MLSnapshot object.

Parameters

MLSnapshot *	snap	Pointer to a valid snap object.

Returns

MLResult	MLResult_Ok	Successfully released snapshot.
MLResult	MLResult_InvalidParam	snapshot parameter was not valid (null).
MLResult	MLResult_PerceptionSystemNotStarted	Perception System has not been started.

Required Permissions:

• None

This function should be called exactly once for each call to [MLPerceptionGetSnapshot()](/docs/12-Dec-2024/api-ref/api/Modules/group___perception/#mlresult-mlperceptiongetsnapshot).

---

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 "ml_api.h"
#include "ml_snapshot.h"

ML_EXTERN_C_BEGIN

typedef struct MLPerceptionSettings {
  uint16_t override_port;
} MLPerceptionSettings;

ML_API MLResult ML_CALL MLPerceptionInitSettings(MLPerceptionSettings *out_settings);

ML_API MLResult ML_CALL MLPerceptionStartup(MLPerceptionSettings *settings);

ML_API MLResult ML_CALL MLPerceptionShutdown();

ML_API MLResult ML_CALL MLPerceptionGetSnapshot(MLSnapshot **out_snapshot);

ML_API MLResult ML_CALL MLPerceptionGetPredictedSnapshot(MLTime timestamp, MLSnapshot **out_snapshot);

ML_API MLResult ML_CALL MLPerceptionReleaseSnapshot(MLSnapshot *snap);

ML_EXTERN_C_END