ml_occlusion.h

Classes

	Name
struct	MLOcclusionSettings Mesh Settings for the underlying system.
struct	MLOcclusionMesh Structure for occlusion mesh data.
struct	MLOcclusionMeshQuery Structure for occlusion mesh query.

Types

	Name
typedef struct MLOcclusionSettings	MLOcclusionSettings Mesh Settings for the underlying system.
typedef struct MLOcclusionMesh	MLOcclusionMesh Structure for occlusion mesh data.
typedef struct MLOcclusionMeshQuery	MLOcclusionMeshQuery Structure for occlusion mesh query.

Functions

	Name
void	MLOcclusionSettingsInit(MLOcclusionSettings * inout_settings) Initialize the occlusion settings with system defaults.
void	MLOcclusionMeshInit(MLOcclusionMesh * inout_mesh) Initialize the occlusion mesh with system defaults.
void	MLOcclusionMeshQueryInit(MLOcclusionMeshQuery * inout_mesh_query) Initialize the occlusion mesh query with system defaults.
MLResult	MLOcclusionCreateClient(const MLOcclusionSettings settings, MLHandle out_client_handle) Create the occlusion client.
MLResult	MLOcclusionDestroyClient(MLHandle client_handle) Free the client resources.
MLResult	MLOcclusionUpdateSettings(MLHandle handle, const MLOcclusionSettings * settings) Update the occlusion settings at runtime.
MLResult	MLOcclusionGetLatestMesh(MLHandle handle, const MLOcclusionMeshQuery mesh_query, MLOcclusionMesh out_mesh_data) Get the latest occlusion mesh.
MLResult	MLOcclusionReleaseMesh(MLHandle handle, MLOcclusionMesh * mesh_data) Releases specified MLOcclusionMesh object.

Types Documentation

MLOcclusionSettings

typedef struct MLOcclusionSettings MLOcclusionSettings;

Mesh Settings for the underlying system.

More Info

API Level:

• 28

---

MLOcclusionMesh

typedef struct MLOcclusionMesh MLOcclusionMesh;

Structure for occlusion mesh data.

More Info

API Level:

• 28

---

MLOcclusionMeshQuery

typedef struct MLOcclusionMeshQuery MLOcclusionMeshQuery;

Structure for occlusion mesh query.

More Info

API Level:

• 28

---

Functions Documentation

MLOcclusionSettingsInit

static inline void MLOcclusionSettingsInit(
    MLOcclusionSettings * inout_settings
)

Initialize the occlusion settings with system defaults.

Parameters

MLOcclusionSettings *	inout_settings	The initial settings to be used for occlusion.

Required Permissions:

• None

API Level:

• 28

---

MLOcclusionMeshInit

static inline void MLOcclusionMeshInit(
    MLOcclusionMesh * inout_mesh
)

Initialize the occlusion mesh with system defaults.

Parameters

MLOcclusionMesh *	inout_mesh	The initial mesh structure.

Required Permissions:

• None

API Level:

• 28

---

MLOcclusionMeshQueryInit

static inline void MLOcclusionMeshQueryInit(
    MLOcclusionMeshQuery * inout_mesh_query
)

Initialize the occlusion mesh query with system defaults.

Parameters

MLOcclusionMeshQuery *	inout_mesh_query	The initial mesh query structure.

Required Permissions:

• None

API Level:

• 28

---

MLOcclusionCreateClient

MLResult MLOcclusionCreateClient(
    const MLOcclusionSettings * settings,
    MLHandle * out_client_handle
)

Create the occlusion client.

Parameters

const MLOcclusionSettings *	settings	The initial settings to be used for occlusion.
MLHandle *	out_client_handle	The handle to the created client.

Returns

MLResult	MLResult_InvalidParam	Occlusion client was not created due to an invalid parameter.
MLResult	MLResult_Ok	Occlusion client was created successfully.
MLResult	MLResult_PerceptionSystemNotStarted	Perception System has not been started.
MLResult	MLResult_PermissionDenied	Missing required permission(s).
MLResult	MLResult_UnspecifiedFailure	Occlusion client was not created due to an unknown error.

Required Permissions:

• com.magicleap.permission.SPATIAL_MAPPING (protection level: dangerous)

API Level:

• 28

---

MLOcclusionDestroyClient

MLResult MLOcclusionDestroyClient(
    MLHandle client_handle
)

Free the client resources.

Parameters

MLHandle	client_handle	The client to destroy.

Returns

MLResult	MLResult_InvalidParam	Occlusion client was not destroyed due to an invalid parameter.
MLResult	MLResult_Ok	Occlusion client was destroyed successfully.
MLResult	MLResult_PerceptionSystemNotStarted	Perception System has not been started.

Required Permissions:

• None

API Level:

• 28

---

MLOcclusionUpdateSettings

MLResult MLOcclusionUpdateSettings(
    MLHandle handle,
    const MLOcclusionSettings * settings
)

Update the occlusion settings at runtime.

Parameters

MLHandle	handle	The handle to the created client.
const MLOcclusionSettings *	settings	The updated settings to be used for occlusion.

Returns

MLResult	MLResult_InvalidParam	Settings were not updated due to an invalid parameter.
MLResult	MLResult_Ok	Settings were updated successfully.
MLResult	MLResult_PerceptionSystemNotStarted	Perception System has not been started.

Required Permissions:

• None

API Level:

• 28

---

MLOcclusionGetLatestMesh

MLResult MLOcclusionGetLatestMesh(
    MLHandle handle,
    const MLOcclusionMeshQuery * mesh_query,
    MLOcclusionMesh * out_mesh_data
)

Get the latest occlusion mesh.

Parameters

MLHandle	handle	The handle to the created client.
const MLOcclusionMeshQuery *	mesh_query	The pointer to intialized MLOcclusionMeshQuery struct.
MLOcclusionMesh *	out_mesh_data	The pointer to intialized MLOcclusionMesh struct.

Returns

MLResult	MLResult_IllegalState	Current mesh must be released before acquiring the next one.
MLResult	MLResult_InvalidParam	Mesh data was not returned due to an invalid parameter.
MLResult	MLResult_Ok	Mesh data was returned successfully.
MLResult	MLResult_PerceptionSystemNotStarted	Perception System has not been started.

Required Permissions:

• None

Returns MLOcclusionMesh with its latest data. When doing consecutive calls and there was no mesh update, the same data will be returned. The memory is owned by the system. Application should copy the data it needs to cache.

Every call to MLOcclusionGetLatestMesh() must be followed by a matching call to MLOcclusionReleaseMesh(), otherwise this method will return an error.

API Level:

• 28

---

MLOcclusionReleaseMesh

MLResult MLOcclusionReleaseMesh(
    MLHandle handle,
    MLOcclusionMesh * mesh_data
)

Releases specified MLOcclusionMesh object.

Parameters

MLHandle	handle	The handle to the created client.
MLOcclusionMesh *	mesh_data	Pointer to a filled MLOcclusionMesh struct.

Returns

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

Required Permissions:

• None

This function should be called exactly once for each call to MLOcclusionGetLatestMesh(). After a successful call, the contents of #mesh_data are no longer valid and should not be used.

API Level:

• 28

---

Source code

// %BANNER_BEGIN%
// ---------------------------------------------------------------------
// %COPYRIGHT_BEGIN%
// Copyright (c) 2023 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 struct MLOcclusionSettings {
  uint32_t version;
  float min_distance;
  float max_distance;
} MLOcclusionSettings;

ML_STATIC_INLINE void MLOcclusionSettingsInit(MLOcclusionSettings *inout_settings) {
  if (inout_settings) {
    memset(inout_settings, 0, sizeof(MLOcclusionSettings));
    inout_settings->version = 1;
    inout_settings->min_distance = 0.3f;
    inout_settings->max_distance = 5.f;
  }
}

typedef struct MLOcclusionMesh {
  uint32_t version;
  MLTime timestamp;
  uint32_t index_count;
  uint32_t vertex_count;
  MLVec3f *vertex;
  uint32_t *index;
} MLOcclusionMesh;

ML_STATIC_INLINE void MLOcclusionMeshInit(MLOcclusionMesh *inout_mesh) {
  if (inout_mesh) {
    memset(inout_mesh, 0, sizeof(MLOcclusionMesh));
    inout_mesh->version = 1;
  }
}

typedef struct MLOcclusionMeshQuery {
  uint32_t version;
} MLOcclusionMeshQuery;

ML_STATIC_INLINE void MLOcclusionMeshQueryInit(MLOcclusionMeshQuery *inout_mesh_query) {
  if (inout_mesh_query) {
    memset(inout_mesh_query, 0, sizeof(MLOcclusionMeshQuery));
    inout_mesh_query->version = 1;
  }
}

ML_API MLResult ML_CALL MLOcclusionCreateClient(const MLOcclusionSettings *settings, MLHandle *out_client_handle);

ML_API MLResult ML_CALL MLOcclusionDestroyClient(MLHandle client_handle);

ML_API MLResult ML_CALL MLOcclusionUpdateSettings(MLHandle handle, const MLOcclusionSettings *settings);

ML_API MLResult ML_CALL MLOcclusionGetLatestMesh(MLHandle handle, const MLOcclusionMeshQuery* mesh_query, MLOcclusionMesh *out_mesh_data);

ML_API MLResult ML_CALL MLOcclusionReleaseMesh(MLHandle handle, MLOcclusionMesh *mesh_data);

ML_EXTERN_C_END