Skip to main content
Version: 20 Mar 2024

Planes

APIs for the Planes system. More...

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.

Detailed Description

APIs for the Planes system.

Warning

THIS API IS DEPRECATED IN FAVOR OF OPENXR XR_EXT_plane_detection EXTENSION: https://registry.khronos.org/OpenXR/specs/1.0/html/xrspec.html#XR_EXT_plane_detection

Shared Object:

  • perception.magicleap*

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