# ArPlane

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

## Summary

| ### Enumerations ||
|---|---|
| `https://developers.google.com/ar/reference/c/group/ar-plane#arplanetype{ https://developers.google.com/ar/reference/c/group/ar-plane#ar_plane_horizontal_upward_facing = 0, https://developers.google.com/ar/reference/c/group/ar-plane#ar_plane_horizontal_downward_facing = 1, https://developers.google.com/ar/reference/c/group/ar-plane#ar_plane_vertical = 2 }` | enumSimple summary of the normal vector of a plane, for filtering purposes. |

| ### Typedefs ||
|---|---|
| `https://developers.google.com/ar/reference/c/group/ar-plane#arplane` | typedef `struct ArPlane_` A detected planar surface ([reference type, long-lived](https://developers.google.com/ar/reference/c/group/concepts#object-ownership)). |

| ### Functions ||
|---|---|
| `https://developers.google.com/ar/reference/c/group/ar-plane#arplane_acquiresubsumedby(const https://developers.google.com/ar/reference/c/group/ar-session#arsession *session, const https://developers.google.com/ar/reference/c/group/ar-plane#arplane *plane, https://developers.google.com/ar/reference/c/group/ar-plane#arplane **out_subsumed_by)` | `void` Acquires a reference to the plane subsuming this plane. |
| `https://developers.google.com/ar/reference/c/group/ar-plane#arplane_getcenterpose(const https://developers.google.com/ar/reference/c/group/ar-session#arsession *session, const https://developers.google.com/ar/reference/c/group/ar-plane#arplane *plane, https://developers.google.com/ar/reference/c/group/ar-pose#arpose *out_pose)` | `void` Returns the pose of the center position of the plane's bounding rectangle. |
| `https://developers.google.com/ar/reference/c/group/ar-plane#arplane_getextentx(const https://developers.google.com/ar/reference/c/group/ar-session#arsession *session, const https://developers.google.com/ar/reference/c/group/ar-plane#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 `https://developers.google.com/ar/reference/c/group/ar-plane#arplane_getcenterpose`. |
| `https://developers.google.com/ar/reference/c/group/ar-plane#arplane_getextentz(const https://developers.google.com/ar/reference/c/group/ar-session#arsession *session, const https://developers.google.com/ar/reference/c/group/ar-plane#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 `https://developers.google.com/ar/reference/c/group/ar-plane#arplane_getcenterpose`. |
| `https://developers.google.com/ar/reference/c/group/ar-plane#arplane_getpolygon(const https://developers.google.com/ar/reference/c/group/ar-session#arsession *session, const https://developers.google.com/ar/reference/c/group/ar-plane#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, ...]`. |
| `https://developers.google.com/ar/reference/c/group/ar-plane#arplane_getpolygonsize(const https://developers.google.com/ar/reference/c/group/ar-session#arsession *session, const https://developers.google.com/ar/reference/c/group/ar-plane#arplane *plane, int32_t *out_polygon_size)` | `void` Retrieves the number of elements (not vertices) in the boundary polygon. |
| `https://developers.google.com/ar/reference/c/group/ar-plane#arplane_gettype(const https://developers.google.com/ar/reference/c/group/ar-session#arsession *session, const https://developers.google.com/ar/reference/c/group/ar-plane#arplane *plane, https://developers.google.com/ar/reference/c/group/ar-plane#arplanetype *out_plane_type)` | `void` Retrieves the type (orientation) of the plane. |
| `https://developers.google.com/ar/reference/c/group/ar-plane#arplane_isposeinextents(const https://developers.google.com/ar/reference/c/group/ar-session#arsession *session, const https://developers.google.com/ar/reference/c/group/ar-plane#arplane *plane, const https://developers.google.com/ar/reference/c/group/ar-pose#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 `https://developers.google.com/ar/reference/c/group/ar-hit-result#arhitresult`) is in the plane's rectangular extents. |
| `https://developers.google.com/ar/reference/c/group/ar-plane#arplane_isposeinpolygon(const https://developers.google.com/ar/reference/c/group/ar-session#arsession *session, const https://developers.google.com/ar/reference/c/group/ar-plane#arplane *plane, const https://developers.google.com/ar/reference/c/group/ar-pose#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 `https://developers.google.com/ar/reference/c/group/ar-hit-result#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](https://developers.google.com/ar/reference/c/group/concepts#object-ownership)).


- Trackable type: `https://developers.google.com/ar/reference/c/group/ar-trackable#ar_trackable_plane`
- Release with: `https://developers.google.com/ar/reference/c/group/ar-trackable#artrackable_release`

<br />

## 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 `https://developers.google.com/ar/reference/c/group/ar-frame#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 `https://developers.google.com/ar/reference/c/group/ar-pose#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 `https://developers.google.com/ar/reference/c/group/ar-plane#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 `https://developers.google.com/ar/reference/c/group/ar-plane#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 (`https://developers.google.com/ar/reference/c/group/ar-plane#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 `https://developers.google.com/ar/reference/c/group/ar-plane#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 `https://developers.google.com/ar/reference/c/group/ar-plane#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 `https://developers.google.com/ar/reference/c/group/ar-hit-result#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 `https://developers.google.com/ar/reference/c/group/ar-hit-result#arhitresult`) is in the plane's polygon.