Version: 12 Dec 2024

ml_eye_camera.h

Classes

	Name
struct	MLEyeCameraSettings A structure to encapsulate the camera settings.
struct	MLEyeCameraFrameBuffer A structure to encapsulate per plane info for each camera frame.
struct	MLEyeCameraFrame A structure to encapsulate output data for each camera sensor.
struct	MLEyeCameraData A structure to encapsulate all the eye camera data.

Types

	Name
typedef struct MLEyeCameraSettings	MLEyeCameraSettings A structure to encapsulate the camera settings.
typedef struct MLEyeCameraFrameBuffer	MLEyeCameraFrameBuffer A structure to encapsulate per plane info for each camera frame.
typedef struct MLEyeCameraFrame	MLEyeCameraFrame A structure to encapsulate output data for each camera sensor.
typedef struct MLEyeCameraData	MLEyeCameraData A structure to encapsulate all the eye camera data.

Enums

	Name
enum	MLEyeCameraIdentifier { MLEyeCameraIdentifier_None = 0, MLEyeCameraIdentifier_LeftTemple = 1 << 0, MLEyeCameraIdentifier_LeftNasal = 1 << 1, MLEyeCameraIdentifier_RightNasal = 1 << 2, MLEyeCameraIdentifier_RightTemple = 1 << 3, MLEyeCameraIdentifier_All = MLEyeCameraIdentifier_LeftTemple
MLEyeCameraIdentifier_LeftNasal
MLEyeCameraIdentifier_RightNasal
MLEyeCameraIdentifier_RightTemple, MLEyeCameraIdentifier_Ensure32Bits = 0x7FFFFFFF } Camera Identifier.

Functions

	Name
void	MLEyeCameraSettingsInit(MLEyeCameraSettings * inout_settings) Initialize the camera settings structure. Shall be called before calling MLEyeCameraConnect().
void	MLEyeCameraDataInit(MLEyeCameraData * inout_eye_camera_data) Initialize MLEyeCameraData with version.
MLResult	MLEyeCameraConnect(const MLEyeCameraSettings settings, MLHandle out_handle) Connect to eye cameras.
MLResult	MLEyeCameraUpdateSettings(MLHandle handle, const MLEyeCameraSettings * settings) Update the eye camera settings.
MLResult	MLEyeCameraGetLatestCameraData(MLHandle handle, uint64_t timeout_ms, MLEyeCameraData * out_data) Poll for Frames.
MLResult	MLEyeCameraReleaseCameraData(MLHandle handle, MLEyeCameraData * eye_camera_data) Releases specified MLEyeCameraData object.
MLResult	MLEyeCameraDisconnect(MLHandle handle) Disconnect from eye camera(s).

Enums Documentation

MLEyeCameraIdentifier

Enumerator	Value	Description
MLEyeCameraIdentifier_None	0	None.
MLEyeCameraIdentifier_LeftTemple	1 << 0	Left temple eye camera.
MLEyeCameraIdentifier_LeftNasal	1 << 1	Left nasal eye camera.
MLEyeCameraIdentifier_RightNasal	1 << 2	Right nasal eye camera.
MLEyeCameraIdentifier_RightTemple	1 << 3	Right temple eye camera.
MLEyeCameraIdentifier_All	MLEyeCameraIdentifier_LeftTemple
MLEyeCameraIdentifier_LeftNasal
MLEyeCameraIdentifier_RightNasal
MLEyeCameraIdentifier_RightTemple	All Eye cameras.
MLEyeCameraIdentifier_Ensure32Bits	0x7FFFFFFF	Ensure enum is represented as 32 bits.

Camera Identifier.

Enumeration of all the available eye camera sensors.

Types Documentation

MLEyeCameraSettings

typedef struct MLEyeCameraSettings MLEyeCameraSettings;

A structure to encapsulate the camera settings.

This structure must be initialized by calling MLEyeCameraSettingsInit before use.

More Info

API Level:

MLEyeCameraFrameBuffer

typedef struct MLEyeCameraFrameBuffer MLEyeCameraFrameBuffer;

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

More Info

API Level:

MLEyeCameraFrame

typedef struct MLEyeCameraFrame MLEyeCameraFrame;

A structure to encapsulate output data for each camera sensor.

More Info

API Level:

MLEyeCameraData

typedef struct MLEyeCameraData MLEyeCameraData;

A structure to encapsulate all the eye camera data.

This structure must be initialized by calling MLEyeCameraDataInit before use.

More Info

API Level:

Functions Documentation

MLEyeCameraSettingsInit

static inline void MLEyeCameraSettingsInit(
    MLEyeCameraSettings * inout_settings
)

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

Parameters


MLEyeCameraSettings *	inout_settings	MLEyeCameraSettings structure to initialize.

Required Permissions:

None

API Level:

MLEyeCameraDataInit

static inline void MLEyeCameraDataInit(
    MLEyeCameraData * inout_eye_camera_data
)

Initialize MLEyeCameraData with version.

Parameters


MLEyeCameraData *	inout_eye_camera_data	Set up the version for inout_eye_camera_data.

API Level:

MLEyeCameraConnect

MLResult MLEyeCameraConnect(
    const MLEyeCameraSettings * settings,
    MLHandle * out_handle
)

Connect to eye cameras.

Parameters


const MLEyeCameraSettings *	settings	A pointer to MLEyeCameraSettings 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:

com.magicleap.permission.EYE_CAMERA (protection level: dangerous)

API Level:

MLEyeCameraUpdateSettings

MLResult MLEyeCameraUpdateSettings(
    MLHandle handle,
    const MLEyeCameraSettings * settings
)

Update the eye camera settings.

Parameters


MLHandle	handle	Camera handle obtained from MLEyeCameraConnect.
const MLEyeCameraSettings *	settings	Pointer to MLEyeCameraSettings.

Returns


MLResult	MLResult_InvalidParam	One of the parameters is invalid.
MLResult	MLResult_Ok	Settings updated successfully.
MLResult	MLResult_UnspecifiedFailure	Failed due to internal error.

Required Permissions:

None

API Level:

MLEyeCameraGetLatestCameraData

MLResult MLEyeCameraGetLatestCameraData(
    MLHandle handle,
    uint64_t timeout_ms,
    MLEyeCameraData * out_data
)

Poll for Frames.

Parameters


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

Returns


MLResult	MLResult_InvalidParam	One of the parameters is invalid.
MLResult	MLResult_Ok	Camera frames 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 MLEyeCameraData 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 MLEyeCameraReleaseCameraData.

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:

MLEyeCameraReleaseCameraData

MLResult MLEyeCameraReleaseCameraData(
    MLHandle handle,
    MLEyeCameraData * eye_camera_data
)

Releases specified MLEyeCameraData object.

Parameters


MLHandle	handle	Camera handle obtained from MLEyeCameraConnect.
MLEyeCameraData *	eye_camera_data	Pointer to a valid MLEyeCameraData object.

Returns


MLResult	MLResult_InvalidParam	One of the parameters is invalid.
MLResult	MLResult_Ok	Successfully released eye camera data.
MLResult	MLResult_UnspecifiedFailure	Failed due to internal error.

Required Permissions:

None

This function should be called exactly once for each call to MLEyeCameraGetLatestCameraData.

API Level:

MLEyeCameraDisconnect

MLResult MLEyeCameraDisconnect(
    MLHandle handle
)

Disconnect from eye camera(s).

Parameters


MLHandle	handle	Camera handle obtained from MLEyeCameraConnect.

Returns


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

Required Permissions:

None

This will disconnect from all the eye camera(s) 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

typedef enum MLEyeCameraIdentifier{
  MLEyeCameraIdentifier_None = 0,
  MLEyeCameraIdentifier_LeftTemple = 1 << 0,
  MLEyeCameraIdentifier_LeftNasal = 1 << 1,
  MLEyeCameraIdentifier_RightNasal = 1 << 2,
  MLEyeCameraIdentifier_RightTemple = 1 << 3,
  MLEyeCameraIdentifier_All = MLEyeCameraIdentifier_LeftTemple |
                              MLEyeCameraIdentifier_LeftNasal  |
                              MLEyeCameraIdentifier_RightNasal |
                              MLEyeCameraIdentifier_RightTemple,
  MLEyeCameraIdentifier_Ensure32Bits = 0x7FFFFFFF
} MLEyeCameraIdentifier;

typedef struct MLEyeCameraSettings {
  uint32_t version;
  uint32_t cameras;
} MLEyeCameraSettings;

ML_STATIC_INLINE void MLEyeCameraSettingsInit(MLEyeCameraSettings *inout_settings) {
  if (inout_settings) {
    memset(inout_settings, 0, sizeof(MLEyeCameraSettings));
    inout_settings->version = 1;
    inout_settings->cameras = MLEyeCameraIdentifier_All;
  }
}

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

typedef struct MLEyeCameraFrame {
  MLEyeCameraIdentifier camera_id;
  int64_t frame_number;
  MLTime timestamp;
  MLEyeCameraFrameBuffer frame_buffer;
} MLEyeCameraFrame;

typedef struct MLEyeCameraData {
  uint32_t version;
  uint8_t frame_count;
  MLEyeCameraFrame *frames;
} MLEyeCameraData;

ML_STATIC_INLINE void MLEyeCameraDataInit(MLEyeCameraData *inout_eye_camera_data) {
  if (inout_eye_camera_data) {
    memset(inout_eye_camera_data, 0, sizeof(MLEyeCameraData));
    inout_eye_camera_data->version = 1;
  }
}

ML_API MLResult ML_CALL MLEyeCameraConnect(const MLEyeCameraSettings *settings, MLHandle *out_handle);


ML_API MLResult ML_CALL MLEyeCameraUpdateSettings(MLHandle handle, const MLEyeCameraSettings *settings);

ML_API MLResult ML_CALL MLEyeCameraGetLatestCameraData(MLHandle handle, uint64_t timeout_ms, MLEyeCameraData *out_data);

ML_API MLResult ML_CALL MLEyeCameraReleaseCameraData(MLHandle handle, MLEyeCameraData *eye_camera_data);

ML_API MLResult ML_CALL MLEyeCameraDisconnect(MLHandle handle);

ML_EXTERN_C_END

ml_eye_camera.h

Classes​

Types​

Enums​

Functions​

Enums Documentation​

MLEyeCameraIdentifier​

Types Documentation​

MLEyeCameraSettings​

MLEyeCameraFrameBuffer​

MLEyeCameraFrame​

MLEyeCameraData​

Functions Documentation​

MLEyeCameraSettingsInit​

MLEyeCameraDataInit​

MLEyeCameraConnect​

MLEyeCameraUpdateSettings​

MLEyeCameraGetLatestCameraData​

MLEyeCameraReleaseCameraData​

MLEyeCameraDisconnect​

Source code​

Classes

Types

Enums

Functions

Enums Documentation

MLEyeCameraIdentifier

Types Documentation

MLEyeCameraSettings

MLEyeCameraFrameBuffer

MLEyeCameraFrame

MLEyeCameraData

Functions Documentation

MLEyeCameraSettingsInit

MLEyeCameraDataInit

MLEyeCameraConnect

MLEyeCameraUpdateSettings

MLEyeCameraGetLatestCameraData

MLEyeCameraReleaseCameraData

MLEyeCameraDisconnect

Source code