Skip to main content
Version: 21 Aug 2024

ml_planes.h

Classes

Name
structMLPlane
structMLPolygon
Coplanar connected line segments representing the outer boundary of a polygon, an _n_-sided polygon where _n_ is the number of vertices.
structMLPlaneBoundary
Type used to represent a region boundary on a 2D plane.
structMLPlaneBoundaries
Type to represent multiple regions on a 2D plane.
structMLPlaneBoundariesList
Type to represent polygons of all returned planes.
structMLPlanesQuery
Type used to represent a plane query.

Types

Name
typedef struct MLPlaneMLPlane
typedef struct MLPolygonMLPolygon
Coplanar connected line segments representing the outer boundary of a polygon, an _n_-sided polygon where _n_ is the number of vertices.
typedef struct MLPlaneBoundaryMLPlaneBoundary
Type used to represent a region boundary on a 2D plane.
typedef struct MLPlaneBoundariesMLPlaneBoundaries
Type to represent multiple regions on a 2D plane.
typedef struct MLPlaneBoundariesListMLPlaneBoundariesList
Type to represent polygons of all returned planes.
typedef struct MLPlanesQueryMLPlanesQuery
Type used to represent a plane query.

Enums

Name
enumMLPlanesQueryFlags
{
MLPlanesQueryFlag_Vertical = 1 << 0,
MLPlanesQueryFlag_Horizontal = 1 << 1,
MLPlanesQueryFlag_Arbitrary = 1 << 2,
MLPlanesQueryFlag_AllOrientations = MLPlanesQueryFlag_Vertical
MLPlanesQueryFlag_Horizontal
MLPlanesQueryFlag_Arbitrary,
MLPlanesQueryFlag_OrientToGravity = 1 << 3,
MLPlanesQueryFlag_Inner = 1 << 4,
MLPlanesQueryFlag_Semantic_Ceiling = 1 << 6,
MLPlanesQueryFlag_Semantic_Floor = 1 << 7,
MLPlanesQueryFlag_Semantic_Wall = 1 << 8,
MLPlanesQueryFlag_Semantic_All = MLPlanesQueryFlag_Semantic_Ceiling
MLPlanesQueryFlag_Semantic_Floor
MLPlanesQueryFlag_Semantic_Wall,
MLPlanesQueryFlag_Polygons = 1 << 9,
MLPlanesQueryFlags_Ensure32Bits = 0x7FFFFFFF
}

Functions

Name
voidMLPlaneBoundariesListInit(MLPlaneBoundariesList * inout_boundaries_list)
Initializes an MLPlaneBoundariesList structure.
MLResultMLPlanesCreate(MLHandle * out_handle)
Creates a planes tracker.
MLResultMLPlanesDestroy(MLHandle planes_tracker)
Destroys a planes tracker.
MLResultMLPlanesQueryBegin(MLHandle planes_tracker, const MLPlanesQuery query, MLHandle out_handle)
Initiates a plane query.
MLResultMLPlanesQueryGetResultsWithBoundaries(MLHandle planes_tracker, MLHandle planes_query, MLPlane out_results, uint32_t out_num_results, MLPlaneBoundariesList * out_boundaries)
Gets the result of a plane query with boundaries on each plane. After this function has returned successfully, the handle is invalid and should be discarded. Also check MLPlanesQueryFlag_Polygons description for this API's further behavior.
MLResultMLPlanesReleaseBoundariesList(MLHandle planes_tracker, MLPlaneBoundariesList * plane_boundaries)
Releases the polygons data owned by the MLPlaneBoundariesList. Also, check MLPlanesQueryFlag_Polygons description for this API's further behavior.

Enums Documentation

MLPlanesQueryFlags

EnumeratorValueDescription
MLPlanesQueryFlag_Vertical1 << 0Include planes whose normal is perpendicular to gravity.
MLPlanesQueryFlag_Horizontal1 << 1Include planes whose normal is parallel to gravity.
MLPlanesQueryFlag_Arbitrary1 << 2Include planes with arbitrary normals.
MLPlanesQueryFlag_AllOrientationsMLPlanesQueryFlag_Vertical
MLPlanesQueryFlag_Horizontal
MLPlanesQueryFlag_ArbitraryInclude all plane orientations.
MLPlanesQueryFlag_OrientToGravity1 << 3For non-horizontal planes, setting this flag will result in the top of the plane rectangle being perpendicular to gravity.
MLPlanesQueryFlag_Inner1 << 4If this flag is set, inner planes will be returned; if it is not set, outer planes will be returned.
MLPlanesQueryFlag_Semantic_Ceiling1 << 6Include planes semantically tagged as ceiling.
MLPlanesQueryFlag_Semantic_Floor1 << 7Include planes semantically tagged as floor.
MLPlanesQueryFlag_Semantic_Wall1 << 8Include planes semantically tagged as wall.
MLPlanesQueryFlag_Semantic_AllMLPlanesQueryFlag_Semantic_Ceiling
MLPlanesQueryFlag_Semantic_Floor
MLPlanesQueryFlag_Semantic_WallInclude all planes that are semantically tagged.
MLPlanesQueryFlag_Polygons1 << 9Include polygonal planes. When this flag is set: MLPlanesQueryGetResultsWithBoundaries returns polygons along with other applicable rectangular planes. MLPlanesReleaseBoundariesList MUST be called before the next call to MLPlanesQueryGetResultsWithBoundaries, otherwise UnspecifiedFailure will be returned.When this flag is not set: MLPlanesQueryGetResultsWithBoundaries returns just rectangular planes. No need to call MLPlanesReleaseBoundariesList.
MLPlanesQueryFlags_Ensure32Bits0x7FFFFFFFEnsure enum is represented as 32 bits.

Control flags for plane queries.


Types Documentation

MLPlane

typedef struct MLPlane MLPlane;

A plane with width and height.

More Info


MLPolygon

typedef struct MLPolygon MLPolygon;

Coplanar connected line segments representing the outer boundary of a polygon, an _n_-sided polygon where _n_ is the number of vertices.

More Info

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

API Level:

  • 2

MLPlaneBoundary

typedef struct MLPlaneBoundary MLPlaneBoundary;

Type used to represent a region boundary on a 2D plane.

More Info

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

API Level:

  • 2

MLPlaneBoundaries

typedef struct MLPlaneBoundaries MLPlaneBoundaries;

Type to represent multiple regions on a 2D plane.

More Info

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

API Level:

  • 2

MLPlaneBoundariesList

typedef struct MLPlaneBoundariesList MLPlaneBoundariesList;

Type to represent polygons of all returned planes.

More Info

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

API Level:

  • 2

MLPlanesQuery

typedef struct MLPlanesQuery MLPlanesQuery;

Type used to represent a plane query.

More Info

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

API Level:

  • 20

Functions Documentation

MLPlaneBoundariesListInit

static inline void MLPlaneBoundariesListInit(
MLPlaneBoundariesList * inout_boundaries_list
)

Initializes an MLPlaneBoundariesList structure.

Parameters

MLPlaneBoundariesList *inout_boundaries_listPointer to a MLPlaneBoundariesList structure which is initialize with default values.

Required Permissions:

  • None
Deprecated

Deprecated since 1.6.0. Scheduled for removal.

API Level:

  • 2

MLPlanesCreate

MLResult MLPlanesCreate(
MLHandle * out_handle
)

Creates a planes tracker.

Parameters

MLHandle *out_handleA pointer to an MLHandle which will contain the handle to the planes tracker. If this operation fails, out_handle will be ML_INVALID_HANDLE.

Returns

MLResultMLResult_InvalidParamFailed to create planes tracker due to an invalid input parameter.
MLResultMLResult_OkSuccessfully created planes tracker.
MLResultMLResult_PerceptionSystemNotStartedPerception System has not been started.
MLResultMLResult_PermissionDeniedThe application lacks permission.
MLResultMLResult_UnspecifiedFailureFailed to create planes tracker due to an unknown reason.

Required Permissions:

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

Deprecated since 1.6.0. Scheduled for removal.


MLPlanesDestroy

MLResult MLPlanesDestroy(
MLHandle planes_tracker
)

Destroys a planes tracker.

Parameters

MLHandleplanes_trackerMLHandle to planes tracker to destroy.

Returns

MLResultMLResult_OkSuccessfully destroyed planes tracker.
MLResultMLResult_PerceptionSystemNotStartedPerception System has not been started.

Required Permissions:

  • None
Deprecated

Deprecated since 1.6.0. Scheduled for removal.


MLPlanesQueryBegin

MLResult MLPlanesQueryBegin(
MLHandle planes_tracker,
const MLPlanesQuery * query,
MLHandle * out_handle
)

Initiates a plane query.

Parameters

MLHandleplanes_trackerHandle produced by MLPlanesCreate().
const MLPlanesQuery *queryPointer to MLPlanesQuery structure containing query parameters.
MLHandle *out_handleA pointer to an MLHandle which will contain the handle to the query. If this operation fails, out_handle will be ML_INVALID_HANDLE.

Returns

MLResultMLResult_InvalidParamFailed to initiate plane query due to an invalid input parameter.
MLResultMLResult_OkSuccessfully initiated plane query.
MLResultMLResult_PerceptionSystemNotStartedPerception System has not been started.

Required Permissions:

  • None

One of the following flags must be set for the query to be considered valid:

  • MLPlanesQueryFlag_Vertical flag.
  • MLPlanesQueryFlag_Horizontal flag.
  • MLPlanesQueryFlag_Arbitrary flag.
  • MLPlanesQueryFlag_Semantic_Ceiling flag.
  • MLPlanesQueryFlag_Semantic_Floor flag.
  • MLPlanesQueryFlag_Semantic_Wall flag.
Deprecated

Deprecated since 1.6.0. Scheduled for removal.

API Level:

  • 20

MLPlanesQueryGetResultsWithBoundaries

MLResult MLPlanesQueryGetResultsWithBoundaries(
MLHandle planes_tracker,
MLHandle planes_query,
MLPlane * out_results,
uint32_t * out_num_results,
MLPlaneBoundariesList * out_boundaries
)

Gets the result of a plane query with boundaries on each plane. After this function has returned successfully, the handle is invalid and should be discarded. Also check MLPlanesQueryFlag_Polygons description for this API's further behavior.

Parameters

MLHandleplanes_trackerHandle produced by MLPlanesCreate().
MLHandleplanes_queryHandle produced by MLPlanesQueryBegin().
MLPlane *out_resultsAn array of MLPlane structures.
uint32_t *out_num_resultsThe count of results pointed to by out_results.
MLPlaneBoundariesList *out_boundariesA pointer to MLPlaneBoundariesList for the returned polygons. If out_boundaries is NULL, the function call will not return any polygons, otherwise *out_boundaries must be zero initialized.

Returns

MLResultMLResult_OkSuccessfully completed query.
MLResultMLResult_PendingQuery completion is pending. This is not a failure.
MLResultMLResult_PerceptionSystemNotStartedPerception System has not been started.
MLResultMLResult_TimeoutQuery timed out due to unknown reason. Make a new query.
MLResultMLResult_UnspecifiedFailureFailed to complete query due to an unknown error.

Required Permissions:

  • None
Deprecated

Deprecated since 1.6.0. Scheduled for removal.

API Level:

  • 2

MLPlanesReleaseBoundariesList

MLResult MLPlanesReleaseBoundariesList(
MLHandle planes_tracker,
MLPlaneBoundariesList * plane_boundaries
)

Releases the polygons data owned by the MLPlaneBoundariesList. Also, check MLPlanesQueryFlag_Polygons description for this API's further behavior.

Parameters

MLHandleplanes_trackerHandle produced by MLPlanesCreate().
MLPlaneBoundariesList *plane_boundariesPolygons pointer to the #MLPlaneBoundariessList.

Returns

MLResultMLResult_InvalidParamFailed to release memory due to an invalid input parameter.
MLResultMLResult_OkSuccessfully released memory.
MLResultMLResult_PerceptionSystemNotStartedPerception System has not been started.

Required Permissions:

  • None
Deprecated

Deprecated since 1.6.0. Scheduled for removal.

API Level:

  • 2

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_types.h"

ML_EXTERN_C_BEGIN

typedef enum MLPlanesQueryFlags {
MLPlanesQueryFlag_Vertical = 1 << 0,
MLPlanesQueryFlag_Horizontal = 1 << 1,
MLPlanesQueryFlag_Arbitrary = 1 << 2,
MLPlanesQueryFlag_AllOrientations = MLPlanesQueryFlag_Vertical |
MLPlanesQueryFlag_Horizontal |
MLPlanesQueryFlag_Arbitrary,
MLPlanesQueryFlag_OrientToGravity = 1 << 3,
MLPlanesQueryFlag_Inner = 1 << 4,
MLPlanesQueryFlag_Semantic_Ceiling = 1 << 6,
MLPlanesQueryFlag_Semantic_Floor = 1 << 7,
MLPlanesQueryFlag_Semantic_Wall = 1 << 8,
MLPlanesQueryFlag_Semantic_All = MLPlanesQueryFlag_Semantic_Ceiling |
MLPlanesQueryFlag_Semantic_Floor |
MLPlanesQueryFlag_Semantic_Wall,
MLPlanesQueryFlag_Polygons = 1 << 9,
MLPlanesQueryFlags_Ensure32Bits = 0x7FFFFFFF
} MLPlanesQueryFlags;

typedef ML_DEPRECATED_MSG("Use XR_EXT_plane_detection OpenXR extention.") struct MLPlane {
MLVec3f position;
MLQuaternionf rotation;
float width;
float height;
uint32_t flags;
MLHandle id;
} MLPlane;

typedef ML_DEPRECATED_MSG("Use XR_EXT_plane_detection OpenXR extention.") struct MLPolygon {
MLVec3f *vertices;
uint32_t vertices_count;
} MLPolygon;

typedef ML_DEPRECATED_MSG("Use XR_EXT_plane_detection OpenXR extention.") struct MLPlaneBoundary {
MLPolygon *polygon;
MLPolygon *holes;
uint32_t holes_count;
} MLPlaneBoundary;

typedef ML_DEPRECATED_MSG("Use XR_EXT_plane_detection OpenXR extention.") struct MLPlaneBoundaries {
MLHandle id;
MLPlaneBoundary *boundaries;
uint32_t boundaries_count;
} MLPlaneBoundaries;

typedef ML_DEPRECATED_MSG("Use XR_EXT_plane_detection OpenXR extention.") struct MLPlaneBoundariesList {
uint32_t version;
MLPlaneBoundaries *plane_boundaries;
uint32_t plane_boundaries_count;
} MLPlaneBoundariesList;

ML_DEPRECATED_MSG("Use XR_EXT_plane_detection OpenXR extention.")
ML_STATIC_INLINE void MLPlaneBoundariesListInit(MLPlaneBoundariesList *inout_boundaries_list) {
inout_boundaries_list->version = 1;
inout_boundaries_list->plane_boundaries = NULL;
inout_boundaries_list->plane_boundaries_count = 0u;
}

typedef ML_DEPRECATED_MSG("Use XR_EXT_plane_detection OpenXR extention.") struct MLPlanesQuery {
uint32_t flags;
MLVec3f bounds_center;
MLQuaternionf bounds_rotation;
MLVec3f bounds_extents;
uint32_t max_results;
float min_plane_area;
} MLPlanesQuery;

ML_DEPRECATED_MSG("Use XR_EXT_plane_detection OpenXR extention.")
ML_API MLResult ML_CALL MLPlanesCreate(MLHandle *out_handle);

ML_DEPRECATED_MSG("Use XR_EXT_plane_detection OpenXR extention.")
ML_API MLResult ML_CALL MLPlanesDestroy(MLHandle planes_tracker);

ML_DEPRECATED_MSG("Use XR_EXT_plane_detection OpenXR extention.")
ML_API MLResult ML_CALL MLPlanesQueryBegin(MLHandle planes_tracker, const MLPlanesQuery *query, MLHandle *out_handle);

ML_DEPRECATED_MSG("Use XR_EXT_plane_detection OpenXR extention.")
ML_API MLResult ML_CALL MLPlanesQueryGetResultsWithBoundaries(MLHandle planes_tracker, MLHandle planes_query, MLPlane *out_results, uint32_t *out_num_results, MLPlaneBoundariesList *out_boundaries);

ML_DEPRECATED_MSG("Use XR_EXT_plane_detection OpenXR extention.")
ML_API MLResult ML_CALL MLPlanesReleaseBoundariesList(MLHandle planes_tracker, MLPlaneBoundariesList *plane_boundaries);

ML_EXTERN_C_END