Version: 20 Mar 2024

ml_snapshot.h

Classes

	Name
struct	MLTransformDerivatives Velocity and acceleration derivatives for a related transform.
struct	MLSnapshotStaticData Static information about the snapshot system.

Types

	Name
typedef struct MLTransformDerivatives	MLTransformDerivatives Velocity and acceleration derivatives for a related transform.
typedef struct MLSnapshotStaticData	MLSnapshotStaticData Static information about the snapshot system.
typedef struct MLSnapshot	MLSnapshot

Enums

	Name
enum	Anonymous Enum 27 { MLResultAPIPrefix_Snapshot = ( 0x87b8 << 16) }
enum	MLSnapshotResult { MLSnapshotResult_DerivativesNotCalculated = MLResultAPIPrefix_Snapshot, MLSnapshotResult_Ensure32Bits = 0x7FFFFFFF }

Functions

	Name
void	MLTransformDerivativesInit(MLTransformDerivatives * inout_data) Intializes the default values for MLTransformDerivatives.
void	MLSnapshotStaticDataInit(MLSnapshotStaticData * inout_data) Intializes the default values for MLSnapshotStaticData.
MLResult	MLSnapshotGetStaticData(MLSnapshotStaticData * out_static_data) Get the static data pertaining to the snapshot system.
MLResult	MLSnapshotGetTransform(const MLSnapshot snapshot, const MLCoordinateFrameUID id, MLTransform * out_transform) Get transform between world origin and the coordinate frame "id.
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.
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.
const char *	MLSnapshotGetResultString(MLResult result_code) Returns an ASCII string representation for each result code.

Enums Documentation

Anonymous Enum 27

Enumerator	Value	Description
MLResultAPIPrefix_Snapshot	( 0x87b8 << 16)	Defines the prefix for MLSnapshotResult codes.

MLSnapshotResult

Enumerator	Value	Description
MLSnapshotResult_DerivativesNotCalculated	MLResultAPIPrefix_Snapshot	Derivatives not calculated for requested coordinate frame.
MLSnapshotResult_Ensure32Bits	0x7FFFFFFF	Ensure 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:

MLSnapshotStaticData

typedef struct MLSnapshotStaticData MLSnapshotStaticData;

Static information about the snapshot system.

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

More Info

API Level:

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_data	The object that will be initialized with default values.

API Level:

MLSnapshotStaticDataInit

static inline void MLSnapshotStaticDataInit(
    MLSnapshotStaticData * inout_data
)

Intializes the default values for MLSnapshotStaticData.

Parameters


MLSnapshotStaticData *	inout_data	The object that will be initialized with default values.

API Level:

MLSnapshotGetStaticData

MLResult MLSnapshotGetStaticData(
    MLSnapshotStaticData * out_static_data
)

Get the static data pertaining to the snapshot system.

Parameters


MLSnapshotStaticData *	out_static_data	Target to populate the data about snapshot system.

Returns


MLResult	MLResult_InvalidParam	Failed to obtain static data due to invalid parameter.
MLResult	MLResult_Ok	Obtained static data successfully.
MLResult	MLResult_UnspecifiedFailure	Failed to obtain static data due to internal error.

Required Permissions:

None

API Level:

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 *	snapshot	A snapshot of tracker state. Can be obtained with MLPerceptionGetSnapshot().
const MLCoordinateFrameUID *	id	Look up the transform between the current origin and this coordinate frame id.
MLTransform *	out_transform	Valid pointer to a MLTransform. To be filled out with requested transform data.

Returns


MLResult	MLResult_InvalidParam	Failed to obtain transform due to invalid parameter.
MLResult	MLResult_Ok	Obtained transform successfully.
MLResult	MLResult_PoseNotFound	Coordinate Frame is valid, but not found in the current pose snapshot.
MLResult	MLResult_UnspecifiedFailure	Failed 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 *	snapshot	A snapshot of tracker state. Can be obtained with MLPerceptionGetSnapshot().
const MLCoordinateFrameUID *	id	Look up the transform between the current origin and this coordinate frame id.
MLTransform *	out_transform	Valid pointer to a MLTransform. To be filled out with requested transform data.
MLTransformDerivatives *	out_derivatives	Valid pointer to a MLTransformDerivatives. To be filled out with the derivatives of the transform if available.

Returns


MLResult	MLResult_InvalidParam	Failed to obtain transform due to invalid parameter.
MLResult	MLResult_Ok	Obtained transform successfully.
MLResult	MLResult_PoseNotFound	Coordinate Frame is valid, but not found in the current pose snapshot.
MLResult	MLResult_UnspecifiedFailure	Failed to obtain transform due to internal error.
MLResult	MLSnapshotResult_DerivativesNotCalculated	Derivatives are not available for the requested coordinate Frame.

Required Permissions:

None

API Level:

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 *	snapshot	A snapshot of tracker state. Can be obtained with MLPerceptionGetSnapshot().
const MLCoordinateFrameUID *	base_id	The coordinate frame in which to locate 'id'.
const MLCoordinateFrameUID *	id	The coordinate frame which needs to be located in the base_id coordinate frame.
MLPose *	out_pose	Valid pointer to a MLPose. To be filled out with requested pose data.

Returns


MLResult	MLResult_InvalidParam	Failed to obtain transform due to invalid parameter.
MLResult	MLResult_Ok	Obtained transform successfully.
MLResult	MLResult_PoseNotFound	Coordinate Frame is valid, but not found in the current pose snapshot.
MLResult	MLResult_UnspecifiedFailure	Failed 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:

MLSnapshotGetResultString

const char * MLSnapshotGetResultString(
    MLResult result_code
)

Returns an ASCII string representation for each result code.

Parameters


MLResult	result_code	MLResult 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

ml_snapshot.h

Classes​

Types​

Enums​

Functions​

Enums Documentation​

Anonymous Enum 27​

MLSnapshotResult​

Types Documentation​

MLTransformDerivatives​

MLSnapshotStaticData​

MLSnapshot​

Functions Documentation​

MLTransformDerivativesInit​

MLSnapshotStaticDataInit​

MLSnapshotGetStaticData​

MLSnapshotGetTransform​

MLSnapshotGetTransformWithDerivatives​

MLSnapshotGetPoseInBase​

MLSnapshotGetResultString​

Source code​

Classes

Types

Enums

Functions

Enums Documentation

Anonymous Enum 27

MLSnapshotResult

Types Documentation

MLTransformDerivatives

MLSnapshotStaticData

MLSnapshot

Functions Documentation

MLTransformDerivativesInit

MLSnapshotStaticDataInit

MLSnapshotGetStaticData

MLSnapshotGetTransform

MLSnapshotGetTransformWithDerivatives

MLSnapshotGetPoseInBase

MLSnapshotGetResultString

Source code