Version: 20 Mar 2024

ml_world_camera.h

Classes

	Name
struct	MLWorldCameraSettings A structure to encapsulate the camera settings.
struct	MLWorldCameraIntrinsics World camera intrinsic parameters.
struct	MLWorldCameraFrameBuffer A structure to encapsulate per plane info for each camera frame.
struct	MLWorldCameraFrame A structure to encapsulate output data for each camera sensor.
struct	MLWorldCameraData A structure to encapsulate output data for each camera sensor.

Types

	Name
typedef struct MLWorldCameraSettings	MLWorldCameraSettings A structure to encapsulate the camera settings.
typedef struct MLWorldCameraIntrinsics	MLWorldCameraIntrinsics World camera intrinsic parameters.
typedef struct MLWorldCameraFrameBuffer	MLWorldCameraFrameBuffer A structure to encapsulate per plane info for each camera frame.
typedef struct MLWorldCameraFrame	MLWorldCameraFrame A structure to encapsulate output data for each camera sensor.
typedef struct MLWorldCameraData	MLWorldCameraData A structure to encapsulate output data for each camera sensor.

Enums

	Name
enum	Anonymous Enum 32 { MLWorldCameraIntrinsics_MaxRadialDistortionCoefficients = 4, MLWorldCameraIntrinsics_MaxTangentialDistortionCoefficients = 2 }
enum	MLWorldCameraIdentifier { MLWorldCameraIdentifier_None = 0, MLWorldCameraIdentifier_Left = 1 << 0, MLWorldCameraIdentifier_Right = 1 << 1, MLWorldCameraIdentifier_Center = 1 << 2, MLWorldCameraIdentifier_All = MLWorldCameraIdentifier_Left
MLWorldCameraIdentifier_Right
MLWorldCameraIdentifier_Center, MLWorldCameraIdentifier_Ensure32Bits = 0x7FFFFFFF } Camera Identifier.
enum	MLWorldCameraMode { MLWorldCameraMode_Unknown = 0, MLWorldCameraMode_LowExposure = 1 << 0, MLWorldCameraMode_NormalExposure = 1 << 1, MLWorldCameraMode_Ensure32Bits = 0x7FFFFFFF } Enumeration of world camera modes.
enum	MLWorldCameraFrameType { MLWorldCameraFrameType_Unknown = 0, MLWorldCameraFrameType_LowExposure = 1, MLWorldCameraFrameType_NormalExposure = 2, MLWorldCameraFrameType_Ensure32Bits = 0x7FFFFFFF } Enumeration of camera mode used when capturing a frame.

Functions

	Name
void	MLWorldCameraSettingsInit(MLWorldCameraSettings * inout_handle) Initialize the camera settings structure. Shall be called before calling MLWorldCameraConnect().
void	MLWorldCameraDataInit(MLWorldCameraData * inout_world_camera_data) Initialize MLWorldCameraData with version.
MLResult	MLWorldCameraConnect(const MLWorldCameraSettings settings, MLHandle out_handle) Connect to world cameras.
MLResult	MLWorldCameraUpdateSettings(MLHandle handle, const MLWorldCameraSettings * settings) Update the world camera settings.
MLResult	MLWorldCameraGetLatestWorldCameraData(MLHandle handle, uint64_t timeout_ms, MLWorldCameraData ** out_data) Poll for Frames.
MLResult	MLWorldCameraReleaseCameraData(MLHandle handle, MLWorldCameraData * world_camera_data) Releases specified MLWorldCameraData object.
MLResult	MLWorldCameraDisconnect(MLHandle handle) Disconnect from world camera.

Enums Documentation

Anonymous Enum 32

Enumerator	Value	Description
MLWorldCameraIntrinsics_MaxRadialDistortionCoefficients	4	Default radial distortion vector size.
MLWorldCameraIntrinsics_MaxTangentialDistortionCoefficients	2	Default tangential distortion vector size.

MLWorldCameraIdentifier

Enumerator	Value	Description
MLWorldCameraIdentifier_None	0	None.
MLWorldCameraIdentifier_Left	1 << 0	Left World camera.
MLWorldCameraIdentifier_Right	1 << 1	Right World camera.
MLWorldCameraIdentifier_Center	1 << 2	Center World camera.
MLWorldCameraIdentifier_All	MLWorldCameraIdentifier_Left
MLWorldCameraIdentifier_Right
MLWorldCameraIdentifier_Center	All World cameras.
MLWorldCameraIdentifier_Ensure32Bits	0x7FFFFFFF	Ensure enum is represented as 32 bits.

Camera Identifier.

Enumeration of all the available world camera sensors.

MLWorldCameraMode

Enumerator	Value	Description
MLWorldCameraMode_Unknown	0	None.
MLWorldCameraMode_LowExposure	1 << 0	Low exposure mode. This mode is currently only available when the controller is being tracked.
MLWorldCameraMode_NormalExposure	1 << 1	Normal exposure mode.
MLWorldCameraMode_Ensure32Bits	0x7FFFFFFF	Ensure enum is represented as 32 bits.

Enumeration of world camera modes.

MLWorldCameraFrameType

Enumerator	Value	Description
MLWorldCameraFrameType_Unknown	0	None.
MLWorldCameraFrameType_LowExposure	1	Frame captured using MLWorldCameraMode_LowExposure mode.
MLWorldCameraFrameType_NormalExposure	2	Frame captured using MLWorldCameraMode_NormalExposure mode.
MLWorldCameraFrameType_Ensure32Bits	0x7FFFFFFF	Ensure enum is represented as 32 bits.

Enumeration of camera mode used when capturing a frame.

Types Documentation

MLWorldCameraSettings

typedef struct MLWorldCameraSettings MLWorldCameraSettings;

A structure to encapsulate the camera settings.

This structure must be initialized by calling MLWorldCameraSettingsInit before use.

More Info

API Level:

MLWorldCameraIntrinsics

typedef struct MLWorldCameraIntrinsics MLWorldCameraIntrinsics;

World camera intrinsic parameters.

More Info

API Level:

MLWorldCameraFrameBuffer

typedef struct MLWorldCameraFrameBuffer MLWorldCameraFrameBuffer;

A structure to encapsulate per plane info for each camera frame.

More Info

API Level:

MLWorldCameraFrame

typedef struct MLWorldCameraFrame MLWorldCameraFrame;

A structure to encapsulate output data for each camera sensor.

More Info

API Level:

MLWorldCameraData

typedef struct MLWorldCameraData MLWorldCameraData;

A structure to encapsulate output data for each camera sensor.

This structure must be initialized by calling MLWorldCameraDataInit before use.

More Info

API Level:

Functions Documentation

MLWorldCameraSettingsInit

static inline void MLWorldCameraSettingsInit(
    MLWorldCameraSettings * inout_handle
)

Initialize the camera settings structure. Shall be called before calling MLWorldCameraConnect().

Parameters


MLWorldCameraSettings *	inout_handle	MLWorldCameraSettings structure to initialize.

Required Permissions:

None

API Level:

MLWorldCameraDataInit

static inline void MLWorldCameraDataInit(
    MLWorldCameraData * inout_world_camera_data
)

Initialize MLWorldCameraData with version.

Parameters


MLWorldCameraData *	inout_world_camera_data	Set up the version for inout_world_camera_data.

API Level:

MLWorldCameraConnect

MLResult MLWorldCameraConnect(
    const MLWorldCameraSettings * settings,
    MLHandle * out_handle
)

Connect to world cameras.

Parameters


const MLWorldCameraSettings *	settings	A pointer to MLWorldCameraSettings structure.
MLHandle *	out_handle	A pointer to camera handle to be used in later APIs.

Returns


MLResult	MLResult_InvalidParam	One of the parameters is invalid.
MLResult	MLResult_Ok	Connected to camera device(s) successfully.
MLResult	MLResult_PermissionDenied	Necessary permission is missing.
MLResult	MLResult_UnspecifiedFailure	The operation failed with an unspecified error.

Required Permissions:

android.permission.CAMERA (protection level: dangerous)

API Level:

MLWorldCameraUpdateSettings

MLResult MLWorldCameraUpdateSettings(
    MLHandle handle,
    const MLWorldCameraSettings * settings
)

Update the world camera settings.

Parameters


MLHandle	handle	Camera handle obtained from MLWorldCameraConnect.
const MLWorldCameraSettings *	settings	Pointer to MLWorldCameraSettings.

Returns


MLResult	MLResult_InvalidParam	Invalid handle.
MLResult	MLResult_Ok	Settings updated successfully.
MLResult	MLResult_UnspecifiedFailure	Failed due to internal error.

Required Permissions:

None

API Level:

MLWorldCameraGetLatestWorldCameraData

MLResult MLWorldCameraGetLatestWorldCameraData(
    MLHandle handle,
    uint64_t timeout_ms,
    MLWorldCameraData ** out_data
)

Poll for Frames.

Parameters


MLHandle	handle	Camera handle obtained from MLWorldCameraConnect.
uint64_t	timeout_ms	Timeout in milliseconds.
MLWorldCameraData **	out_data	World camera data. Will be set to NULL if no valid data is available at this time.

Returns


MLResult	MLResult_InvalidParam	Invalid handle.
MLResult	MLResult_Ok	World camera data fetched successfully.
MLResult	MLResult_Timeout	Returned because no new frame available at this time.
MLResult	MLResult_UnspecifiedFailure	Failed due to internal error.

Required Permissions:

None

Returns MLWorldCameraData with this latest data when available. The memory is owned by the system. Application should copy the data it needs to cache and release the memory by calling MLWorldCameraReleaseCameraData.

This is a blocking call. API is not thread safe.

If there are no new camera frames within the timeout_ms duration then the API will return MLResult_Timeout.

API Level:

MLWorldCameraReleaseCameraData

MLResult MLWorldCameraReleaseCameraData(
    MLHandle handle,
    MLWorldCameraData * world_camera_data
)

Releases specified MLWorldCameraData object.

Parameters


MLHandle	handle	Camera handle obtained from MLWorldCameraConnect.
MLWorldCameraData *	world_camera_data	Pointer to a valid MLWorldCameraData object.

Returns


MLResult	MLResult_Ok	Successfully released world camera data.
MLResult	MLResult_InvalidParam	world_camera_data parameter was not valid (NULL).
MLResult	MLResult_UnspecifiedFailure	Failed due to internal error.

Required Permissions:

None

This function should be called exactly once for each successfull call to #MLWorldCameraGetLatestCameraData.

MLWorldCameraDisconnect

MLResult MLWorldCameraDisconnect(
    MLHandle handle
)

Disconnect from world camera.

Parameters


MLHandle	handle	Camera handle obtained from MLWorldCameraConnect.

Returns


MLResult	MLResult_InvalidParam	Invalid handle.
MLResult	MLResult_Ok	Disconnected camera successfully.
MLResult	MLResult_UnspecifiedFailure	Failed to disconnect camera.

Required Permissions:

None

This will disconnect from all the world camera currently connected.

API Level:

Source code

// %BANNER_BEGIN%
// ---------------------------------------------------------------------
// %COPYRIGHT_BEGIN%
// Copyright (c) 2022 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_types.h"

#include <string.h>

ML_EXTERN_C_BEGIN

enum {
  MLWorldCameraIntrinsics_MaxRadialDistortionCoefficients = 4,
  MLWorldCameraIntrinsics_MaxTangentialDistortionCoefficients = 2
};

typedef enum MLWorldCameraIdentifier{
  MLWorldCameraIdentifier_None = 0,
  MLWorldCameraIdentifier_Left = 1 << 0,
  MLWorldCameraIdentifier_Right = 1 << 1,
  MLWorldCameraIdentifier_Center = 1 << 2,
  MLWorldCameraIdentifier_All = MLWorldCameraIdentifier_Left |
                                MLWorldCameraIdentifier_Right |
                                MLWorldCameraIdentifier_Center,
  MLWorldCameraIdentifier_Ensure32Bits = 0x7FFFFFFF
} MLWorldCameraIdentifier;

typedef enum MLWorldCameraMode {
  MLWorldCameraMode_Unknown = 0,
  MLWorldCameraMode_LowExposure = 1 << 0,
  MLWorldCameraMode_NormalExposure = 1 << 1,
  MLWorldCameraMode_Ensure32Bits = 0x7FFFFFFF
} MLWorldCameraMode;

typedef enum MLWorldCameraFrameType {
  MLWorldCameraFrameType_Unknown = 0,
  MLWorldCameraFrameType_LowExposure = 1,
  MLWorldCameraFrameType_NormalExposure = 2,
  MLWorldCameraFrameType_Ensure32Bits = 0x7FFFFFFF
} MLWorldCameraFrameType;

typedef struct MLWorldCameraSettings {
  uint32_t version;
  uint32_t mode;
  uint32_t cameras;
} MLWorldCameraSettings;

ML_STATIC_INLINE void MLWorldCameraSettingsInit(MLWorldCameraSettings *inout_handle) {
  if (inout_handle) {
    memset(inout_handle, 0, sizeof(MLWorldCameraSettings));
    inout_handle->version = 1;
    inout_handle->mode = MLWorldCameraMode_NormalExposure;
    inout_handle->cameras = MLWorldCameraIdentifier_All;
  }
}

typedef struct MLWorldCameraIntrinsics {
  uint32_t width;
  uint32_t height;
  MLVec2f focal_length;
  MLVec2f principal_point;
  float fov;
  double radial_distortion[MLWorldCameraIntrinsics_MaxRadialDistortionCoefficients];
  double tangential_distortion[MLWorldCameraIntrinsics_MaxTangentialDistortionCoefficients];
} MLWorldCameraIntrinsics;

typedef struct MLWorldCameraFrameBuffer {
  uint32_t width;
  uint32_t height;
  uint32_t stride;
  uint32_t bytes_per_pixel;
  uint32_t size;
  uint8_t *data;
} MLWorldCameraFrameBuffer;


typedef struct MLWorldCameraFrame {
  MLWorldCameraIdentifier id;
  int64_t frame_number;
  MLTime timestamp;
  MLWorldCameraIntrinsics intrinsics;
  MLTransform camera_pose;
  MLWorldCameraFrameBuffer frame_buffer;
  MLWorldCameraFrameType frame_type;
} MLWorldCameraFrame;


typedef struct MLWorldCameraData {
  uint32_t version;
  uint8_t frame_count;
  MLWorldCameraFrame *frames;
} MLWorldCameraData;

ML_STATIC_INLINE void MLWorldCameraDataInit(MLWorldCameraData *inout_world_camera_data) {
  if (inout_world_camera_data) {
    memset(inout_world_camera_data, 0, sizeof(MLWorldCameraData));
    inout_world_camera_data->version = 1;
  }
}

ML_API MLResult ML_CALL MLWorldCameraConnect(const MLWorldCameraSettings *settings, MLHandle *out_handle);

ML_API MLResult ML_CALL MLWorldCameraUpdateSettings(MLHandle handle, const MLWorldCameraSettings *settings);

ML_API MLResult ML_CALL MLWorldCameraGetLatestWorldCameraData(MLHandle handle, uint64_t timeout_ms, MLWorldCameraData **out_data);

ML_API MLResult ML_CALL MLWorldCameraReleaseCameraData(MLHandle handle, MLWorldCameraData *world_camera_data);

ML_API MLResult ML_CALL MLWorldCameraDisconnect(MLHandle handle);

ML_EXTERN_C_END

ml_world_camera.h

Classes​

Types​

Enums​

Functions​

Enums Documentation​

Anonymous Enum 32​

MLWorldCameraIdentifier​

MLWorldCameraMode​

MLWorldCameraFrameType​

Types Documentation​

MLWorldCameraSettings​

MLWorldCameraIntrinsics​

MLWorldCameraFrameBuffer​

MLWorldCameraFrame​

MLWorldCameraData​

Functions Documentation​

MLWorldCameraSettingsInit​

MLWorldCameraDataInit​

MLWorldCameraConnect​

MLWorldCameraUpdateSettings​

MLWorldCameraGetLatestWorldCameraData​

MLWorldCameraReleaseCameraData​

MLWorldCameraDisconnect​

Source code​

Classes

Types

Enums

Functions

Enums Documentation

Anonymous Enum 32

MLWorldCameraIdentifier

MLWorldCameraMode

MLWorldCameraFrameType

Types Documentation

MLWorldCameraSettings

MLWorldCameraIntrinsics

MLWorldCameraFrameBuffer

MLWorldCameraFrame

MLWorldCameraData

Functions Documentation

MLWorldCameraSettingsInit

MLWorldCameraDataInit

MLWorldCameraConnect

MLWorldCameraUpdateSettings

MLWorldCameraGetLatestWorldCameraData

MLWorldCameraReleaseCameraData

MLWorldCameraDisconnect

Source code