Thanks for tuning in to Google I/O! Watch AR content on-demand.

ArPlane

Describes the current best knowledge of a real-world planar surface.

Summary

Enumerations
`ArPlaneType{ AR_PLANE_HORIZONTAL_UPWARD_FACING = 0, AR_PLANE_HORIZONTAL_DOWNWARD_FACING = 1, AR_PLANE_VERTICAL = 2 }`	enum Simple summary of the normal vector of a plane, for filtering purposes.

Typedefs
`ArPlane`	typedef `struct ArPlane_` A detected planar surface (reference type, long-lived).

Functions
`ArPlane_acquireSubsumedBy(const ArSession session, const ArPlane plane, ArPlane **out_subsumed_by)`	`void` Acquires a reference to the plane subsuming this plane.
`ArPlane_getCenterPose(const ArSession session, const ArPlane plane, ArPose *out_pose)`	`void` Returns the pose of the center position of the plane's bounding rectangle.
`ArPlane_getExtentX(const ArSession session, const ArPlane plane, float *out_extent_x)`	`void` Retrieves the length of this plane's bounding rectangle measured along the local X-axis of the coordinate space defined by the output of `ArPlane_getCenterPose`.
`ArPlane_getExtentZ(const ArSession session, const ArPlane plane, float *out_extent_z)`	`void` Retrieves the length of this plane's bounding rectangle measured along the local Z-axis of the coordinate space defined by the output of `ArPlane_getCenterPose`.
`ArPlane_getPolygon(const ArSession session, const ArPlane plane, float *out_polygon_xz)`	`void` Returns the 2D vertices of a convex polygon approximating the detected plane, in the form `[x1, z1, x2, z2, ...]`.
`ArPlane_getPolygonSize(const ArSession session, const ArPlane plane, int32_t *out_polygon_size)`	`void` Retrieves the number of elements (not vertices) in the boundary polygon.
`ArPlane_getType(const ArSession session, const ArPlane plane, ArPlaneType *out_plane_type)`	`void` Retrieves the type (orientation) of the plane.
`ArPlane_isPoseInExtents(const ArSession session, const ArPlane plane, const ArPose pose, int32_t out_pose_in_extents)`	`void` Sets `*out_pose_in_extents` to non-zero if the given pose (usually obtained from an `ArHitResult`) is in the plane's rectangular extents.
`ArPlane_isPoseInPolygon(const ArSession session, const ArPlane plane, const ArPose pose, int32_t out_pose_in_polygon)`	`void` Sets `*out_pose_in_extents` to non-zero if the given pose (usually obtained from an `ArHitResult`) is in the plane's polygon.

Enumerations

ArPlaneType

 ArPlaneType

Simple summary of the normal vector of a plane, for filtering purposes.

Properties
`AR_PLANE_HORIZONTAL_DOWNWARD_FACING`	A horizontal plane facing downward (for example a ceiling).
`AR_PLANE_HORIZONTAL_UPWARD_FACING`	A horizontal plane facing upward (for example a floor or tabletop).
`AR_PLANE_VERTICAL`	A vertical plane (for example a wall).

Typedefs

ArPlane

struct ArPlane_ ArPlane

A detected planar surface (reference type, long-lived).

Trackable type: AR_TRACKABLE_PLANE
Release with: ArTrackable_release

Functions

ArPlane_acquireSubsumedBy

void ArPlane_acquireSubsumedBy(
  const ArSession *session,
  const ArPlane *plane,
  ArPlane **out_subsumed_by
)

Acquires a reference to the plane subsuming this plane.

Two or more planes may be automatically merged into a single parent plane, resulting in this function acquiring the parent plane when called with each child plane. A subsumed plane becomes identical to the parent plane, and will continue behaving as if it were independently tracked, for example being included in the output of ArFrame_getUpdatedTrackables.

In cases where a subsuming plane is itself subsumed, this function will always return the topmost non-subsumed plane.

Note: this function will set *out_subsumed_by to NULL if the plane is not subsumed.

ArPlane_getCenterPose

void ArPlane_getCenterPose(
  const ArSession *session,
  const ArPlane *plane,
  ArPose *out_pose
)

Returns the pose of the center position of the plane's bounding rectangle.

The pose's transformed +Y axis will be a normal vector pointing out of plane. The transformed +X and +Z axes represent right and up relative to the plane.

Details

Parameters

`session`	The ARCore session.
`plane`	The plane for which to retrieve center pose.
`out_pose`	An already-allocated `ArPose` object into which the pose will be stored.

ArPlane_getExtentX

void ArPlane_getExtentX(
  const ArSession *session,
  const ArPlane *plane,
  float *out_extent_x
)

Retrieves the length of this plane's bounding rectangle measured along the local X-axis of the coordinate space defined by the output of ArPlane_getCenterPose.

ArPlane_getExtentZ

void ArPlane_getExtentZ(
  const ArSession *session,
  const ArPlane *plane,
  float *out_extent_z
)

Retrieves the length of this plane's bounding rectangle measured along the local Z-axis of the coordinate space defined by the output of ArPlane_getCenterPose.

ArPlane_getPolygon

void ArPlane_getPolygon(
  const ArSession *session,
  const ArPlane *plane,
  float *out_polygon_xz
)

Returns the 2D vertices of a convex polygon approximating the detected plane, in the form [x1, z1, x2, z2, ...].

These x and z values are in the plane's local X-Z plane (y=0) and must be transformed by the pose (ArPlane_getCenterPose) to get the boundary in world coordinates.

Details

Parameters

`session`	The ARCore session.
`plane`	The plane to retrieve the polygon from.
`out_polygon_xz`	A pointer to an array of floats. The length of this array must be at least that reported by `ArPlane_getPolygonSize`.

ArPlane_getPolygonSize

void ArPlane_getPolygonSize(
  const ArSession *session,
  const ArPlane *plane,
  int32_t *out_polygon_size
)

Retrieves the number of elements (not vertices) in the boundary polygon.

The number of vertices is half this size.

ArPlane_getType

void ArPlane_getType(
  const ArSession *session,
  const ArPlane *plane,
  ArPlaneType *out_plane_type
)

Retrieves the type (orientation) of the plane.

See ArPlaneType.

ArPlane_isPoseInExtents

void ArPlane_isPoseInExtents(
  const ArSession *session,
  const ArPlane *plane,
  const ArPose *pose,
  int32_t *out_pose_in_extents
)

Sets *out_pose_in_extents to non-zero if the given pose (usually obtained from an ArHitResult) is in the plane's rectangular extents.

ArPlane_isPoseInPolygon

void ArPlane_isPoseInPolygon(
  const ArSession *session,
  const ArPlane *plane,
  const ArPose *pose,
  int32_t *out_pose_in_polygon
)

Sets *out_pose_in_extents to non-zero if the given pose (usually obtained from an ArHitResult) is in the plane's polygon.