Skip to main content
Version: 21 Aug 2024

ml_occlusion.h

Classes

Name
structMLOcclusionSettings
Mesh Settings for the underlying system.
structMLOcclusionMesh
Structure for occlusion mesh data.
structMLOcclusionMeshQuery
Structure for occlusion mesh query.

Types

Name
typedef struct MLOcclusionSettingsMLOcclusionSettings
Mesh Settings for the underlying system.
typedef struct MLOcclusionMeshMLOcclusionMesh
Structure for occlusion mesh data.
typedef struct MLOcclusionMeshQueryMLOcclusionMeshQuery
Structure for occlusion mesh query.

Functions

Name
voidMLOcclusionSettingsInit(MLOcclusionSettings * inout_settings)
Initialize the occlusion settings with system defaults.
voidMLOcclusionMeshInit(MLOcclusionMesh * inout_mesh)
Initialize the occlusion mesh with system defaults.
voidMLOcclusionMeshQueryInit(MLOcclusionMeshQuery * inout_mesh_query)
Initialize the occlusion mesh query with system defaults.
MLResultMLOcclusionCreateClient(const MLOcclusionSettings settings, MLHandle out_client_handle)
Create the occlusion client.
MLResultMLOcclusionDestroyClient(MLHandle client_handle)
Free the client resources.
MLResultMLOcclusionUpdateSettings(MLHandle handle, const MLOcclusionSettings * settings)
Update the occlusion settings at runtime.
MLResultMLOcclusionGetLatestMesh(MLHandle handle, const MLOcclusionMeshQuery mesh_query, MLOcclusionMesh out_mesh_data)
Get the latest occlusion mesh.
MLResultMLOcclusionReleaseMesh(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_settingsThe 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_meshThe 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_queryThe 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 *settingsThe initial settings to be used for occlusion.
MLHandle *out_client_handleThe handle to the created client.

Returns

MLResultMLResult_InvalidParamOcclusion client was not created due to an invalid parameter.
MLResultMLResult_OkOcclusion client was created successfully.
MLResultMLResult_PerceptionSystemNotStartedPerception System has not been started.
MLResultMLResult_PermissionDeniedMissing required permission(s).
MLResultMLResult_UnspecifiedFailureOcclusion 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

MLHandleclient_handleThe client to destroy.

Returns

MLResultMLResult_InvalidParamOcclusion client was not destroyed due to an invalid parameter.
MLResultMLResult_OkOcclusion client was destroyed successfully.
MLResultMLResult_PerceptionSystemNotStartedPerception 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

MLHandlehandleThe handle to the created client.
const MLOcclusionSettings *settingsThe updated settings to be used for occlusion.

Returns

MLResultMLResult_InvalidParamSettings were not updated due to an invalid parameter.
MLResultMLResult_OkSettings were updated successfully.
MLResultMLResult_PerceptionSystemNotStartedPerception 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

MLHandlehandleThe handle to the created client.
const MLOcclusionMeshQuery *mesh_queryThe pointer to intialized MLOcclusionMeshQuery struct.
MLOcclusionMesh *out_mesh_dataThe pointer to intialized MLOcclusionMesh struct.

Returns

MLResultMLResult_IllegalStateCurrent mesh must be released before acquiring the next one.
MLResultMLResult_InvalidParamMesh data was not returned due to an invalid parameter.
MLResultMLResult_OkMesh data was returned successfully.
MLResultMLResult_PerceptionSystemNotStartedPerception 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

MLHandlehandleThe handle to the created client.
MLOcclusionMesh *mesh_dataPointer to a filled MLOcclusionMesh struct.

Returns

MLResultMLResult_InvalidParamOne of the parameters is invalid.
MLResultMLResult_OkSuccessfully released mesh data.
MLResultMLResult_UnspecifiedFailureFailed 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