Skip to main content
Version: 21 Aug 2024

ml_snapshot.h

Classes

Name
structMLTransformDerivatives
Velocity and acceleration derivatives for a related transform.
structMLSnapshotStaticData
Static information about the snapshot system.

Types

Name
typedef struct MLTransformDerivativesMLTransformDerivatives
Velocity and acceleration derivatives for a related transform.
typedef struct MLSnapshotStaticDataMLSnapshotStaticData
Static information about the snapshot system.
typedef struct MLSnapshotMLSnapshot

Enums

Name
enumAnonymous Enum 27
{
MLResultAPIPrefix_Snapshot = ( 0x87b8 << 16)
}
enumMLSnapshotResult
{
MLSnapshotResult_DerivativesNotCalculated = MLResultAPIPrefix_Snapshot,
MLSnapshotResult_Ensure32Bits = 0x7FFFFFFF
}

Functions

Name
voidMLTransformDerivativesInit(MLTransformDerivatives * inout_data)
Intializes the default values for MLTransformDerivatives.
voidMLSnapshotStaticDataInit(MLSnapshotStaticData * inout_data)
Intializes the default values for MLSnapshotStaticData.
MLResultMLSnapshotGetStaticData(MLSnapshotStaticData * out_static_data)
Get the static data pertaining to the snapshot system.
MLResultMLSnapshotGetTransform(const MLSnapshot snapshot, const MLCoordinateFrameUID id, MLTransform * out_transform)
Get transform between world origin and the coordinate frame "id.
MLResultMLSnapshotGetTransformWithDerivatives(const MLSnapshot snapshot, const MLCoordinateFrameUID id, MLTransform out_transform, MLTransformDerivatives out_derivatives)
Get transform between world origin and the coordinate frame "id as well as any derivatives that have been calculated.
MLResultMLSnapshotGetPoseInBase(const MLSnapshot snapshot, const MLCoordinateFrameUID base_id, const MLCoordinateFrameUID id, MLPose out_pose)
Get transform between coordinate frame 'base_id' and the coordinate frame "id as well as any derivatives that have been calculated.
const char *MLSnapshotGetResultString(MLResult result_code)
Returns an ASCII string representation for each result code.

Enums Documentation

Anonymous Enum 27

EnumeratorValueDescription
MLResultAPIPrefix_Snapshot( 0x87b8 << 16)Defines the prefix for MLSnapshotResult codes.

MLSnapshotResult

EnumeratorValueDescription
MLSnapshotResult_DerivativesNotCalculatedMLResultAPIPrefix_SnapshotDerivatives not calculated for requested coordinate frame.
MLSnapshotResult_Ensure32Bits0x7FFFFFFFEnsure enum is represented as 32 bits.

Return values for Snapshot API calls.


Types Documentation

MLTransformDerivatives

typedef struct MLTransformDerivatives MLTransformDerivatives;

Velocity and acceleration derivatives for a related transform.

More Info

API Level:

  • 8

MLSnapshotStaticData

typedef struct MLSnapshotStaticData MLSnapshotStaticData;

Static information about the snapshot system.

Initalize this structure with MLSnapshotStaticDataInit and populate with MLSnapshotGetStaticData().

More Info

API Level:

  • 30

MLSnapshot

typedef struct MLSnapshot MLSnapshot;

Opaque snapshot of system state.

More Info


Functions Documentation

MLTransformDerivativesInit

static inline void MLTransformDerivativesInit(
MLTransformDerivatives * inout_data
)

Intializes the default values for MLTransformDerivatives.

Parameters

MLTransformDerivatives *inout_dataThe object that will be initialized with default values.

API Level:

  • 8

MLSnapshotStaticDataInit

static inline void MLSnapshotStaticDataInit(
MLSnapshotStaticData * inout_data
)

Intializes the default values for MLSnapshotStaticData.

Parameters

MLSnapshotStaticData *inout_dataThe object that will be initialized with default values.

API Level:

  • 30

MLSnapshotGetStaticData

MLResult MLSnapshotGetStaticData(
MLSnapshotStaticData * out_static_data
)

Get the static data pertaining to the snapshot system.

Parameters

MLSnapshotStaticData *out_static_dataTarget to populate the data about snapshot system.

Returns

MLResultMLResult_InvalidParamFailed to obtain static data due to invalid parameter.
MLResultMLResult_OkObtained static data successfully.
MLResultMLResult_UnspecifiedFailureFailed to obtain static data due to internal error.

Required Permissions:

  • None

API Level:

  • 30

MLSnapshotGetTransform

MLResult MLSnapshotGetTransform(
const MLSnapshot * snapshot,
const MLCoordinateFrameUID * id,
MLTransform * out_transform
)

Get transform between world origin and the coordinate frame "id.

Parameters

const MLSnapshot *snapshotA snapshot of tracker state. Can be obtained with MLPerceptionGetSnapshot().
const MLCoordinateFrameUID *idLook up the transform between the current origin and this coordinate frame id.
MLTransform *out_transformValid pointer to a MLTransform. To be filled out with requested transform data.

Returns

MLResultMLResult_InvalidParamFailed to obtain transform due to invalid parameter.
MLResultMLResult_OkObtained transform successfully.
MLResultMLResult_PoseNotFoundCoordinate Frame is valid, but not found in the current pose snapshot.
MLResultMLResult_UnspecifiedFailureFailed to obtain transform due to internal error.

Required Permissions:

  • None

MLSnapshotGetTransformWithDerivatives

MLResult MLSnapshotGetTransformWithDerivatives(
const MLSnapshot * snapshot,
const MLCoordinateFrameUID * id,
MLTransform * out_transform,
MLTransformDerivatives * out_derivatives
)

Get transform between world origin and the coordinate frame "id as well as any derivatives that have been calculated.

Parameters

const MLSnapshot *snapshotA snapshot of tracker state. Can be obtained with MLPerceptionGetSnapshot().
const MLCoordinateFrameUID *idLook up the transform between the current origin and this coordinate frame id.
MLTransform *out_transformValid pointer to a MLTransform. To be filled out with requested transform data.
MLTransformDerivatives *out_derivativesValid pointer to a MLTransformDerivatives. To be filled out with the derivatives of the transform if available.

Returns

MLResultMLResult_InvalidParamFailed to obtain transform due to invalid parameter.
MLResultMLResult_OkObtained transform successfully.
MLResultMLResult_PoseNotFoundCoordinate Frame is valid, but not found in the current pose snapshot.
MLResultMLResult_UnspecifiedFailureFailed to obtain transform due to internal error.
MLResultMLSnapshotResult_DerivativesNotCalculatedDerivatives are not available for the requested coordinate Frame.

Required Permissions:

  • None

API Level:

  • 8

MLSnapshotGetPoseInBase

MLResult MLSnapshotGetPoseInBase(
const MLSnapshot * snapshot,
const MLCoordinateFrameUID * base_id,
const MLCoordinateFrameUID * id,
MLPose * out_pose
)

Get transform between coordinate frame 'base_id' and the coordinate frame "id as well as any derivatives that have been calculated.

Parameters

const MLSnapshot *snapshotA snapshot of tracker state. Can be obtained with MLPerceptionGetSnapshot().
const MLCoordinateFrameUID *base_idThe coordinate frame in which to locate 'id'.
const MLCoordinateFrameUID *idThe coordinate frame which needs to be located in the base_id coordinate frame.
MLPose *out_poseValid pointer to a MLPose. To be filled out with requested pose data.

Returns

MLResultMLResult_InvalidParamFailed to obtain transform due to invalid parameter.
MLResultMLResult_OkObtained transform successfully.
MLResultMLResult_PoseNotFoundCoordinate Frame is valid, but not found in the current pose snapshot.
MLResultMLResult_UnspecifiedFailureFailed to obtain transform due to internal error.

Required Permissions:

  • None
// Get the CFUID for World Origin
MLSnapshotStaticData snapshot_static_data = {};
MLSnapshotStaticDataInit(&snapshot_static_data);
MLSnapshotGetStaticData(&snapshot_static_data);

// Get the CFUID for Headset Origin
MLHeadTrackingStaticData head_static_data_ = {};
MLHeadTrackingGetStaticData(head_tracker_, &head_static_data_);

// Get the CFUID for left eye
MLEyeTrackingStaticData eye_static_data_ = {};
MLEyeTrackingGetStaticData(eye_tracker_, &eye_static_data_);

MLPose left_eye_center = {};
MLSnapshot *snapshot = nullptr;
bool gaze_in_device_coordinate_frame = true;
MLPerceptionGetSnapshot(&snapshot);
if(gaze_in_device_coordinate_frame) { // Left eye gaze in device coordinate frame.
MLSnapshotGetPoseInBase(snapshot, &head_static_data_.coord_frame_head, &eye_static_data_.left_center, &left_eye_center);
}
else { // Left eye gaze in world origin coordinate frame.
MLSnapshotGetPoseInBase(snapshot, &snapshot_static_data.coord_world_origin, &eye_static_data_.left_center, &left_eye_center);
}
MLPerceptionReleaseSnapshot(snapshot);

API Level:

  • 30

MLSnapshotGetResultString

const char * MLSnapshotGetResultString(
MLResult result_code
)

Returns an ASCII string representation for each result code.

Parameters

MLResultresult_codeMLResult type to be converted to string.

Required Permissions:

  • None

This call returns strings for all of the global MLResult and MLSnapshotResult codes.

Return: ASCII string containing readable version of the result 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 "ml_api.h"
#include "ml_coordinate_frame_uid.h"
#include "ml_types.h"

#include <string.h>

ML_EXTERN_C_BEGIN

enum {
MLResultAPIPrefix_Snapshot = MLRESULT_PREFIX(0x87b8)
};

typedef enum MLSnapshotResult {
MLSnapshotResult_DerivativesNotCalculated = MLResultAPIPrefix_Snapshot,
MLSnapshotResult_Ensure32Bits = 0x7FFFFFFF
} MLSnapshotResult;

typedef struct MLTransformDerivatives {
uint32_t version;
MLVec3f linear_velocity_m_s;
MLVec3f linear_acceleration_m_s2;
MLVec3f angular_velocity_r_s;
MLVec3f angular_acceleration_r_s2;
} MLTransformDerivatives;

ML_STATIC_INLINE void MLTransformDerivativesInit(MLTransformDerivatives *inout_data) {
if (inout_data) {
inout_data->version = 1u;
inout_data->linear_velocity_m_s.x = 0.f;
inout_data->linear_velocity_m_s.y = 0.f;
inout_data->linear_velocity_m_s.z = 0.f;
inout_data->linear_acceleration_m_s2.x = 0.f;
inout_data->linear_acceleration_m_s2.y = 0.f;
inout_data->linear_acceleration_m_s2.z = 0.f;
inout_data->angular_velocity_r_s.x = 0.f;
inout_data->angular_velocity_r_s.y = 0.f;
inout_data->angular_velocity_r_s.z = 0.f;
inout_data->angular_acceleration_r_s2.x = 0.f;
inout_data->angular_acceleration_r_s2.y = 0.f;
inout_data->angular_acceleration_r_s2.z = 0.f;
}
}

typedef struct MLSnapshotStaticData {
uint32_t version;
MLCoordinateFrameUID coord_world_origin;
} MLSnapshotStaticData;

ML_STATIC_INLINE void MLSnapshotStaticDataInit(MLSnapshotStaticData *inout_data) {
if (inout_data) {
memset(inout_data, 0, sizeof(MLSnapshotStaticData));
inout_data->version = 1u;
}
}

ML_API MLResult ML_CALL MLSnapshotGetStaticData(MLSnapshotStaticData *out_static_data);

typedef struct MLSnapshot MLSnapshot;

ML_API MLResult ML_CALL MLSnapshotGetTransform(const MLSnapshot *snapshot, const MLCoordinateFrameUID *id, MLTransform *out_transform);

ML_API MLResult ML_CALL MLSnapshotGetTransformWithDerivatives(const MLSnapshot *snapshot, const MLCoordinateFrameUID *id,
MLTransform *out_transform, MLTransformDerivatives *out_derivatives);

ML_API MLResult ML_CALL MLSnapshotGetPoseInBase(const MLSnapshot *snapshot, const MLCoordinateFrameUID *base_id, const MLCoordinateFrameUID *id, MLPose *out_pose);

ML_API const char* ML_CALL MLSnapshotGetResultString(MLResult result_code);

ML_EXTERN_C_END