Version: 14 Oct 2024

ml_planes.h

Classes

	Name
struct	MLPlane
struct	MLPolygon Coplanar connected line segments representing the outer boundary of a polygon, an _n_-sided polygon where _n_ is the number of vertices.
struct	MLPlaneBoundary Type used to represent a region boundary on a 2D plane.
struct	MLPlaneBoundaries Type to represent multiple regions on a 2D plane.
struct	MLPlaneBoundariesList Type to represent polygons of all returned planes.
struct	MLPlanesQuery Type used to represent a plane query.

Types

	Name
typedef struct MLPlane	MLPlane
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.
typedef struct MLPlaneBoundary	MLPlaneBoundary Type used to represent a region boundary on a 2D plane.
typedef struct MLPlaneBoundaries	MLPlaneBoundaries Type to represent multiple regions on a 2D plane.
typedef struct MLPlaneBoundariesList	MLPlaneBoundariesList Type to represent polygons of all returned planes.
typedef struct MLPlanesQuery	MLPlanesQuery Type used to represent a plane query.

Enums

	Name
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 }

Functions

	Name
void	MLPlaneBoundariesListInit(MLPlaneBoundariesList * inout_boundaries_list) Initializes an MLPlaneBoundariesList structure.
MLResult	MLPlanesCreate(MLHandle * out_handle) Creates a planes tracker.
MLResult	MLPlanesDestroy(MLHandle planes_tracker) Destroys a planes tracker.
MLResult	MLPlanesQueryBegin(MLHandle planes_tracker, const MLPlanesQuery query, MLHandle out_handle) Initiates a plane query.
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.
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.

Enums Documentation

MLPlanesQueryFlags

Enumerator	Value	Description
MLPlanesQueryFlag_Vertical	1 << 0	Include planes whose normal is perpendicular to gravity.
MLPlanesQueryFlag_Horizontal	1 << 1	Include planes whose normal is parallel to gravity.
MLPlanesQueryFlag_Arbitrary	1 << 2	Include planes with arbitrary normals.
MLPlanesQueryFlag_AllOrientations	MLPlanesQueryFlag_Vertical
MLPlanesQueryFlag_Horizontal
MLPlanesQueryFlag_Arbitrary	Include all plane orientations.
MLPlanesQueryFlag_OrientToGravity	1 << 3	For non-horizontal planes, setting this flag will result in the top of the plane rectangle being perpendicular to gravity.
MLPlanesQueryFlag_Inner	1 << 4	If this flag is set, inner planes will be returned; if it is not set, outer planes will be returned.
MLPlanesQueryFlag_Semantic_Ceiling	1 << 6	Include planes semantically tagged as ceiling.
MLPlanesQueryFlag_Semantic_Floor	1 << 7	Include planes semantically tagged as floor.
MLPlanesQueryFlag_Semantic_Wall	1 << 8	Include planes semantically tagged as wall.
MLPlanesQueryFlag_Semantic_All	MLPlanesQueryFlag_Semantic_Ceiling
MLPlanesQueryFlag_Semantic_Floor
MLPlanesQueryFlag_Semantic_Wall	Include all planes that are semantically tagged.
MLPlanesQueryFlag_Polygons	1 << 9	Include 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_Ensure32Bits	0x7FFFFFFF	Ensure 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:

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:

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:

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:

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:

Functions Documentation

MLPlaneBoundariesListInit

static inline void MLPlaneBoundariesListInit(
    MLPlaneBoundariesList * inout_boundaries_list
)

Initializes an MLPlaneBoundariesList structure.

Parameters


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

Required Permissions:

None

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

API Level:

MLPlanesCreate

MLResult MLPlanesCreate(
    MLHandle * out_handle
)

Creates a planes tracker.

Parameters


MLHandle *	out_handle	A 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


MLResult	MLResult_InvalidParam	Failed to create planes tracker due to an invalid input parameter.
MLResult	MLResult_Ok	Successfully created planes tracker.
MLResult	MLResult_PerceptionSystemNotStarted	Perception System has not been started.
MLResult	MLResult_PermissionDenied	The application lacks permission.
MLResult	MLResult_UnspecifiedFailure	Failed 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


MLHandle	planes_tracker	MLHandle to planes tracker to destroy.

Returns


MLResult	MLResult_Ok	Successfully destroyed planes tracker.
MLResult	MLResult_PerceptionSystemNotStarted	Perception 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


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

Returns


MLResult	MLResult_InvalidParam	Failed to initiate plane query due to an invalid input parameter.
MLResult	MLResult_Ok	Successfully initiated plane query.
MLResult	MLResult_PerceptionSystemNotStarted	Perception 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:

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


MLHandle	planes_tracker	Handle produced by MLPlanesCreate().
MLHandle	planes_query	Handle produced by MLPlanesQueryBegin().
MLPlane *	out_results	An array of MLPlane structures.
uint32_t *	out_num_results	The count of results pointed to by out_results.
MLPlaneBoundariesList *	out_boundaries	A 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


MLResult	MLResult_Ok	Successfully completed query.
MLResult	MLResult_Pending	Query completion is pending. This is not a failure.
MLResult	MLResult_PerceptionSystemNotStarted	Perception System has not been started.
MLResult	MLResult_Timeout	Query timed out due to unknown reason. Make a new query.
MLResult	MLResult_UnspecifiedFailure	Failed to complete query due to an unknown error.

Required Permissions:

None

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

API Level:

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


MLHandle	planes_tracker	Handle produced by MLPlanesCreate().
MLPlaneBoundariesList *	plane_boundaries	Polygons pointer to the #MLPlaneBoundariessList.

Returns


MLResult	MLResult_InvalidParam	Failed to release memory due to an invalid input parameter.
MLResult	MLResult_Ok	Successfully released memory.
MLResult	MLResult_PerceptionSystemNotStarted	Perception System has not been started.

Required Permissions:

None

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

API Level:

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

ml_planes.h

Classes​

Types​

Enums​

Functions​

Enums Documentation​

MLPlanesQueryFlags​

Types Documentation​

MLPlane​

MLPolygon​

MLPlaneBoundary​

MLPlaneBoundaries​

MLPlaneBoundariesList​

MLPlanesQuery​

Functions Documentation​

MLPlaneBoundariesListInit​

MLPlanesCreate​

MLPlanesDestroy​

MLPlanesQueryBegin​

MLPlanesQueryGetResultsWithBoundaries​

MLPlanesReleaseBoundariesList​

Source code​

Classes

Types

Enums

Functions

Enums Documentation

MLPlanesQueryFlags

Types Documentation

MLPlane

MLPolygon

MLPlaneBoundary

MLPlaneBoundaries

MLPlaneBoundariesList

MLPlanesQuery

Functions Documentation

MLPlaneBoundariesListInit

MLPlanesCreate

MLPlanesDestroy

MLPlanesQueryBegin

MLPlanesQueryGetResultsWithBoundaries

MLPlanesReleaseBoundariesList

Source code