# Plane

Artifact: [androidx.xr.arcore:arcore](https://developer.android.com/jetpack/androidx/releases/xr-arcore) [View Source](https://cs.android.com/search?q=file:androidx/xr/arcore/Plane.kt+class:androidx.xr.arcore.Plane) Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/xr-arcore#1.0.0)

*** ** * ** ***


```
class Plane : Anchorable<Plane.State>
```

<br />

*** ** * ** ***

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

## Summary

| ### Nested types |
|---|
| `class https://developer.android.com/reference/kotlin/androidx/xr/arcore/Plane.State : https://developer.android.com/reference/kotlin/androidx/xr/arcore/Trackable.State` The representation of the current state of a `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Plane`. |

| ### Public companion functions |
|---|---|
| `https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-state-flow/index.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-collection/index.html<https://developer.android.com/reference/kotlin/androidx/xr/arcore/Plane>>` | `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Plane#subscribe(androidx.xr.runtime.Session)(session: https://developer.android.com/reference/kotlin/androidx/xr/runtime/Session)` Emits the planes that are currently being tracked in the `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Plane.Companion#subscribe(androidx.xr.runtime.Session)`. |

| ### Public functions |
|---|---|
| `open https://developer.android.com/reference/kotlin/androidx/xr/arcore/AnchorResult` | `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Plane#createAnchor(androidx.xr.runtime.math.Pose)(pose: https://developer.android.com/reference/kotlin/androidx/xr/runtime/math/Pose)` Creates an `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Anchor` attached to this trackable. |
| `open https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Plane#toString()()` Returns a string representation of `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Plane` for debugging. |

| ### Public properties |
|---|---|
| `open https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-state-flow/index.html<https://developer.android.com/reference/kotlin/androidx/xr/arcore/Plane.State>` | `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Plane#state()` the current `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Plane.State` of the plane |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/PlaneType` | `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Plane#type()` the `https://developer.android.com/reference/kotlin/androidx/xr/arcore/PlaneType` of the plane |

## Public companion functions

### subscribe

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/xr-arcore#1.0.0)

```
fun subscribe(session: Session): StateFlow<Collection<Plane>>
```

Emits the planes that are currently being tracked in the `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Plane.Companion#subscribe(androidx.xr.runtime.Session)`.

Only `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Plane`s that are `https://developer.android.com/reference/kotlin/androidx/xr/arcore/TrackingState#TRACKING()` will be emitted in the `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-collection/index.html`. Instances of the same `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Plane` will remain between subsequent emits to the `https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-state-flow/index.html` as long as they remain tracking.

```kotlin
import androidx.lifecycle.Lifecycle
import androidx.lifecycle.repeatOnLifecycle
import androidx.xr.arcore.Plane
import androidx.xr.arcore.TrackingState
import androidx.xr.runtime.math.Pose
import androidx.xr.scenecore.scene

// Use a coroutine to listen to changes to the set of detected planes.
yourCoroutineScope.launch {
    val activePlanes = mutableMapOf<Plane, Job>()

    lifecycle.repeatOnLifecycle(Lifecycle.State.RESUMED) {
        val supervisor = SupervisorJob()
        val supervisorScope = CoroutineScope(yourCoroutineScope.coroutineContext + supervisor)
        try {
            Plane.subscribe(session).collect { planes ->
                // The list of detected planes has changed.
                for (plane in planes) {

                    // If a plane doesn't exist in our set of active planes, set up a
                    // coroutine to respond to its state changes.
                    if (!activePlanes.contains(plane)) {
                        val job = supervisorScope.launch {
                            plane.state.collect {
                                // if the plane is not currently reporting as tracked, then
                                // we don't want to render it.
                                if (it.trackingState != TrackingState.TRACKING) return@collect

                                // Transform the pose from its original coordinate space to
                                // one suitable for rendering to the display.
                                val pose =
                                    it.centerPose.let { p ->
                                        session.scene.perceptionSpace.transformPoseTo(
                                            p,
                                            session.scene.activitySpace,
                                        )
                                    }

                                // This function is where you'll actually render the plane
                                // to the display.
                                renderFunction(pose, it.extents, it.vertices, it.label)
                            }
                        }
                        activePlanes[plane] = job
                    }

                    // Likewise, if a plane exists in the `activePlanes` map, but not in our
                    // `planes` list, it needs to be removed, and its corresponding job
                    // canceled.
                    for (plane in activePlanes.keys.toList()) {
                        if (planes.none { it == plane }) {
                            activePlanes.remove(plane)?.cancel()
                        }
                    }
                }
            }
        } finally {
            // cancel any coroutines still running.
            supervisor.cancel()
            activePlanes.clear()
        }
    }
}
```

| Parameters |
|---|---|
| `session: https://developer.android.com/reference/kotlin/androidx/xr/runtime/Session` | the `https://developer.android.com/reference/kotlin/androidx/xr/runtime/Session` to track planes from |

| Throws |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-state-exception/index.html` | if `https://developer.android.com/reference/kotlin/androidx/xr/runtime/Session#config()` is set to `https://developer.android.com/reference/kotlin/androidx/xr/runtime/PlaneTrackingMode#DISABLED()` |

## Public functions

### createAnchor

```
open fun createAnchor(pose: Pose): AnchorResult
```

Creates an `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Anchor` attached to this trackable.

| Parameters |
|---|---|
| `pose: https://developer.android.com/reference/kotlin/androidx/xr/runtime/math/Pose` | the initial `https://developer.android.com/reference/kotlin/androidx/xr/runtime/math/Pose` of the `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Anchor` |

| Throws |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-state-exception/index.html` | if `https://developer.android.com/reference/kotlin/androidx/xr/runtime/Session#config()` is set to `https://developer.android.com/reference/kotlin/androidx/xr/runtime/PlaneTrackingMode#DISABLED()` |

### toString

```
open fun toString(): String
```

Returns a string representation of `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Plane` for debugging.

Note: Not intended for production use.

## Public properties

### state

```
open val state: StateFlow<Plane.State>
```

the current `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Plane.State` of the plane

### type

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/xr-arcore#1.0.0)

```
val type: PlaneType
```

the `https://developer.android.com/reference/kotlin/androidx/xr/arcore/PlaneType` of the plane