Planes

APIs for the Planes system. More...

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.

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

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:

• 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_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:

• 2

---

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:

• 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

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:

• 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

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:

• 2

---