Skip to main content
Version: 21 Aug 2024

ml_perception.h

Classes

Name
structMLPerceptionSettings

Types

Name
typedef struct MLPerceptionSettingsMLPerceptionSettings

Functions

Name
MLResultMLPerceptionInitSettings(MLPerceptionSettings * out_settings)
Initializes the perception system with the passed in settings.
MLResultMLPerceptionStartup(MLPerceptionSettings * settings)
Starts the perception system.
MLResultMLPerceptionShutdown()
Shuts down the perception system and cleans up all resources used by it.
MLResultMLPerceptionGetSnapshot(MLSnapshot ** out_snapshot)
Pulls in the latest state of all persistent transforms and all enabled trackers extrapolated to the next frame time.
MLResultMLPerceptionGetPredictedSnapshot(MLTime timestamp, MLSnapshot ** out_snapshot)
Pulls in the state of all persistent transforms and all enabled trackers extrapolated to the provided timestamp.
MLResultMLPerceptionReleaseSnapshot(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_settingsInitializes the perception system with these settings.

Returns

MLResultMLResult_InvalidParamFailed to initialize the perception settings due to an invalid input parameter.
MLResultMLResult_OkSuccessfully initialized the perception settings.
MLResultMLResult_UnspecifiedFailureFailed to initialize the perception settings due to an unknown error.

Required Permissions:

  • None

MLPerceptionStartup

MLResult MLPerceptionStartup(
MLPerceptionSettings * settings
)

Starts the perception system.

Parameters

MLPerceptionSettings *settingsThe perception system starts with these settings.

Returns

MLResultMLResult_OkSuccessfully started perception system.
MLResultMLResult_UnspecifiedFailureFailed 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

MLResultMLResult_OkSuccessfully shut down the perception system.
MLResultMLResult_UnspecifiedFailureFailed 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/21-Aug-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_snapshotPointer to a pointer containing an MLSnapshot on success.

Returns

MLResultMLResult_OkSuccessfully created snapshot.
MLResultMLResult_InvalidParamout_snapshot parameter was not valid (null).
MLResultMLResult_PerceptionSystemNotStartedPerception 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/21-Aug-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

MLTimetimestampTimestamp representing the time for which to predict poses.
MLSnapshot **out_snapshotPointer to a pointer containing an MLSnapshot on success.

Returns

MLResultMLResult_OkSuccessfully created snapshot.
MLResultMLResult_InvalidTimestampTimestamp is either more than 100ms in the future or too old for cached state.
MLResultMLResult_InvalidParamOutput parameter was not valid (null).
MLResultMLResult_PerceptionSystemNotStartedPerception 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/21-Aug-2024/api-ref/api/Modules/group___perception/#mlresult-mlperceptionreleasesnapshot).

API Level:

  • 27

MLPerceptionReleaseSnapshot

MLResult MLPerceptionReleaseSnapshot(
MLSnapshot * snap
)

Releases specified #MLSnapshot object.

Parameters

MLSnapshot *snapPointer to a valid snap object.

Returns

MLResultMLResult_OkSuccessfully released snapshot.
MLResultMLResult_InvalidParamsnapshot parameter was not valid (null).
MLResultMLResult_PerceptionSystemNotStartedPerception System has not been started.

Required Permissions:

  • None

This function should be called exactly once for each call to [MLPerceptionGetSnapshot()](/docs/21-Aug-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