# SpatialEnvironment

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

*** ** * ** ***


```
class SpatialEnvironment
```

<br />

*** ** * ** ***

The SpatialEnvironment is used to manage the XR background and passthrough. There is a single instance of this class managed by each `https://developer.android.com/reference/kotlin/androidx/xr/runtime/Session` and it is accessible through Session.scene.

The SpatialEnvironment is a composite of geometry specified by [glTF](https://www.khronos.org/gltf/) along with image-based lighting. Applications are encouraged to supply glTFs with a skybox texture baked-in for ground and horizon visibility. The image-based lighting contributes to the overall illumination and reflections within the scene.

The XR background can be set to display one of three configurations:

1. A combination of image based lighting and glTF geometry which should contain a skybox texture.

2. A Passthrough surface, where the XR background is a live feed from the device's outward facing cameras. At full opacity, this surface completely occludes the geometry.

3. A mixed configuration where the passthrough surface is not at full opacity nor is it at zero opacity. The passthrough surface becomes semi-transparent and alpha blends with the geometry behind it.

Note that methods in this class do not necessarily take effect immediately. Rather, they set a preference that will be applied when the device enters a state where the XR background can be changed.

## Summary

| ### Nested types |
|---|
| `class https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SpatialEnvironment.SpatialEnvironmentPreference` Represents the preferred spatial environment for the application. |

| ### Constants |
|---|---|
| `const https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html` | `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SpatialEnvironment#NO_PASSTHROUGH_OPACITY_PREFERENCE()` Passed into `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SpatialEnvironment#preferredPassthroughOpacity()` to clear the application's passthrough opacity preference and to let the system manage passthrough opacity. |

| ### Public functions |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SpatialEnvironment#addPassthroughOpacityChangedListener(java.util.function.Consumer)(listener: https://developer.android.com/reference/java/util/function/Consumer.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html>)` Notifies an application when the user visible passthrough state changes, such as when the application enters or exits passthrough or when the passthrough opacity changes. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SpatialEnvironment#addPassthroughOpacityChangedListener(java.util.concurrent.Executor,java.util.function.Consumer)( executor: https://developer.android.com/reference/java/util/concurrent/Executor.html, listener: https://developer.android.com/reference/java/util/function/Consumer.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html> )` Notifies an application when the user visible passthrough state changes, such as when the application enters or exits passthrough or when the passthrough opacity changes. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SpatialEnvironment#addSpatialEnvironmentChangedListener(java.util.function.Consumer)(listener: https://developer.android.com/reference/java/util/function/Consumer.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html>)` Notifies an application whether the preferred spatial environment for the application is active. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SpatialEnvironment#addSpatialEnvironmentChangedListener(java.util.concurrent.Executor,java.util.function.Consumer)( executor: https://developer.android.com/reference/java/util/concurrent/Executor.html, listener: https://developer.android.com/reference/java/util/function/Consumer.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html> )` Notifies an application whether the preferred spatial environment for the application is active. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SpatialEnvironment#removePassthroughOpacityChangedListener(java.util.function.Consumer)(listener: https://developer.android.com/reference/java/util/function/Consumer.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html>)` Remove a listener previously added by `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SpatialEnvironment#addPassthroughOpacityChangedListener(java.util.function.Consumer)`. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SpatialEnvironment#removeSpatialEnvironmentChangedListener(java.util.function.Consumer)(listener: https://developer.android.com/reference/java/util/function/Consumer.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html>)` Remove a listener previously added by `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SpatialEnvironment#addSpatialEnvironmentChangedListener(java.util.function.Consumer)`. |

| ### Public properties |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html` | `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SpatialEnvironment#currentPassthroughOpacity()` Gets the current passthrough opacity value visible to the user. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SpatialEnvironment#isPreferredSpatialEnvironmentActive()` Checks if the application's preferred spatial environment set through `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SpatialEnvironment#preferredSpatialEnvironment()` is active. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html` | `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SpatialEnvironment#preferredPassthroughOpacity()` The application's preferred passthrough opacity. |
| `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SpatialEnvironment.SpatialEnvironmentPreference?` | `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SpatialEnvironment#preferredSpatialEnvironment()` The preferred spatial environment for the application. |

## Constants

### NO_PASSTHROUGH_OPACITY_PREFERENCE

```
const val NO_PASSTHROUGH_OPACITY_PREFERENCE: Float
```

Passed into `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SpatialEnvironment#preferredPassthroughOpacity()` to clear the application's passthrough opacity preference and to let the system manage passthrough opacity.

## Public functions

### addPassthroughOpacityChangedListener

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

```
fun addPassthroughOpacityChangedListener(listener: Consumer<Float>): Unit
```

Notifies an application when the user visible passthrough state changes, such as when the application enters or exits passthrough or when the passthrough opacity changes.

This `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SpatialEnvironment#addPassthroughOpacityChangedListener(java.util.function.Consumer)` will be called on the Application's main thread.

| Parameters |
|---|---|
| `listener: https://developer.android.com/reference/java/util/function/Consumer.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html>` | The Consumer to be added to listen for passthrough opacity changes. |

### addPassthroughOpacityChangedListener

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

```
fun addPassthroughOpacityChangedListener(
    executor: Executor,
    listener: Consumer<Float>
): Unit
```

Notifies an application when the user visible passthrough state changes, such as when the application enters or exits passthrough or when the passthrough opacity changes.

This listener will be invoked on the given `https://developer.android.com/reference/java/util/concurrent/Executor.html`.

| Parameters |
|---|---|
| `executor: https://developer.android.com/reference/java/util/concurrent/Executor.html` | The `https://developer.android.com/reference/java/util/concurrent/Executor.html` to invoke the listener on. |
| `listener: https://developer.android.com/reference/java/util/function/Consumer.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html>` | The Consumer to be added to listen for passthrough opacity changes. |

### addSpatialEnvironmentChangedListener

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

```
fun addSpatialEnvironmentChangedListener(listener: Consumer<Boolean>): Unit
```

Notifies an application whether the preferred spatial environment for the application is active.

The environment will try to transition to the application environment when a non-null preference is set through `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SpatialEnvironment#preferredSpatialEnvironment()` and the application has the `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SpatialCapability#APP_ENVIRONMENT()` capability. The environment preferences will otherwise not be active.

The listener consumes a boolean value that is true if the environment preference is active when the listener is notified.

This listener will be invoked on the Application's main thread.

| Parameters |
|---|---|
| `listener: https://developer.android.com/reference/java/util/function/Consumer.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html>` | The Consumer to be added to listen for spatial environment changes. |

### addSpatialEnvironmentChangedListener

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

```
fun addSpatialEnvironmentChangedListener(
    executor: Executor,
    listener: Consumer<Boolean>
): Unit
```

Notifies an application whether the preferred spatial environment for the application is active.

The environment will try to transition to the application environment when a non-null preference is set through `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SpatialEnvironment#preferredSpatialEnvironment()` and the application has the `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SpatialCapability#APP_ENVIRONMENT()` capability. The environment preferences will otherwise not be active.

The listener consumes a boolean value that is true if the environment preference is active when the listener is notified.

This listener will be invoked on the given `https://developer.android.com/reference/java/util/concurrent/Executor.html`.

| Parameters |
|---|---|
| `executor: https://developer.android.com/reference/java/util/concurrent/Executor.html` | The `https://developer.android.com/reference/java/util/concurrent/Executor.html` to invoke the listener on. |
| `listener: https://developer.android.com/reference/java/util/function/Consumer.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html>` | The Consumer to be added to listen for spatial environment changes. |

### removePassthroughOpacityChangedListener

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

```
fun removePassthroughOpacityChangedListener(listener: Consumer<Float>): Unit
```

Remove a listener previously added by `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SpatialEnvironment#addPassthroughOpacityChangedListener(java.util.function.Consumer)`.

Remaining listeners are automatically removed when the SpatialEnvironment is destroyed.

| Parameters |
|---|---|
| `listener: https://developer.android.com/reference/java/util/function/Consumer.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html>` | The previously-added Consumer listener to be removed. |

### removeSpatialEnvironmentChangedListener

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

```
fun removeSpatialEnvironmentChangedListener(listener: Consumer<Boolean>): Unit
```

Remove a listener previously added by `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SpatialEnvironment#addSpatialEnvironmentChangedListener(java.util.function.Consumer)`.

Remaining listeners are automatically removed when the SpatialEnvironment is destroyed.

| Parameters |
|---|---|
| `listener: https://developer.android.com/reference/java/util/function/Consumer.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html>` | The previously-added Consumer listener to be removed. |

## Public properties

### currentPassthroughOpacity

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

```
val currentPassthroughOpacity: Float
```

Gets the current passthrough opacity value visible to the user.

Unlike the application's opacity preference returned by `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SpatialEnvironment#preferredPassthroughOpacity()`, this value can be overwritten by the system, and is not directly under the application's control.

| Returns |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html` | The current passthrough opacity value between 0.0f and 1.0f. A value of 0.0f means no passthrough is shown, and a value of 1.0f means the passthrough completely obscures the spatial environment geometry and skybox. |

### isPreferredSpatialEnvironmentActive

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

```
val isPreferredSpatialEnvironmentActive: Boolean
```

Checks if the application's preferred spatial environment set through `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SpatialEnvironment#preferredSpatialEnvironment()` is active.

Spatial environment preference set through `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SpatialEnvironment#preferredSpatialEnvironment()` are shown when this is true, but passthrough or other objects in the scene could partially or totally occlude them. When this is false, the default system environment will be active instead.

| Returns |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | True if the environment set by `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SpatialEnvironment#preferredSpatialEnvironment()` is active. |

### preferredPassthroughOpacity

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

```
var preferredPassthroughOpacity: Float
```

The application's preferred passthrough opacity.

Upon construction, the default value is `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SpatialEnvironment#NO_PASSTHROUGH_OPACITY_PREFERENCE()`, which means "no application preference". The application's preferred passthrough opacity can be set between 0.0f and 1.0f.

Setting the application preference does not guarantee that the value will be immediately applied and visible to the user. The actual passthrough opacity value is controlled by the system in response to a combination of this preference and user actions outside the application. Generally, this preference is honored when the application has the `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SpatialCapability#PASSTHROUGH_CONTROL()` capability.

The value should be between 0.0f (passthrough disabled) and 1.0f (passthrough fully obscures the spatial environment). Values within 0.01f of 0.0 or 1.0 are snapped to those values. Values outside 0.0f, 1.0f are clamped. Other values result in semi-transparent passthrough that is alpha blended with the preferred application spatial environment. Passthrough is disabled for semi-transparent passthrough values when there is no `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SpatialEnvironment#preferredSpatialEnvironment()` and there is no active system passthrough. This prevents semi-transparent passthrough values from affecting the default system environment.

Setting this property to NO_PASSTHROUGH_OPACITY_PREFERENCE clears the application's preference, allowing the system to manage passthrough opacity.

The actual value visible to the user can be observed by calling `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SpatialEnvironment#currentPassthroughOpacity()` or by registering a listener with `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SpatialEnvironment#addPassthroughOpacityChangedListener(java.util.function.Consumer)`.

### preferredSpatialEnvironment

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

```
var preferredSpatialEnvironment: SpatialEnvironment.SpatialEnvironmentPreference?
```

The preferred spatial environment for the application.

If no preference has ever been set by the application, this will be null.

Setting this property only sets the preference and does not cause an immediate change unless `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SpatialEnvironment#isPreferredSpatialEnvironmentActive()` is already true. Once the device enters a state where the XR background can be changed and the `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SpatialCapability#APP_ENVIRONMENT()` capability is available, the preferred spatial environment for the application will be automatically displayed.

Setting the preference to null will disable the preferred spatial environment for the application, meaning the default system environment will be displayed instead.

If the given `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SpatialEnvironment.SpatialEnvironmentPreference` is not null, but all of its properties are null, then the spatial environment will consist of a black void.

See `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SpatialEnvironment#isPreferredSpatialEnvironmentActive()` or the `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/SpatialEnvironment#addSpatialEnvironmentChangedListener(java.util.function.Consumer)` listeners to know when this preference becomes active.