SpatialEnvironment

const val NO_PASSTHROUGH_OPACITY_PREFERENCE: Float

Passed into preferredPassthroughOpacity to clear the application's passthrough opacity preference and to let the system manage passthrough opacity.

fun addOnPassthroughOpacityChangedListener(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 called on the Application's main thread.

fun addOnPassthroughOpacityChangedListener(
    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 Executor.

fun addOnSpatialEnvironmentChangedListener(listener: Consumer<Boolean>): Unit

Notifies an application whether or not 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 preferredSpatialEnvironment and the application has the SpatialCapability.SPATIAL_CAPABILITY_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.

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

Notifies an application whether or not 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 preferredSpatialEnvironment and the application has the SpatialCapability.SPATIAL_CAPABILITY_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 Executor.

fun removeOnPassthroughOpacityChangedListener(listener: Consumer<Float>): Unit

Remove a listener previously added by addOnPassthroughOpacityChangedListener.

Remaining listeners are automatically removed when the SpatialEnvironment is destroyed.

fun removeOnSpatialEnvironmentChangedListener(listener: Consumer<Boolean>): Unit

Remove a listener previously added by addOnSpatialEnvironmentChangedListener.

Remaining listeners are automatically removed when the SpatialEnvironment is destroyed.

val currentPassthroughOpacity: Float

Gets the current passthrough opacity value visible to the user.

Unlike the application's opacity preference returned by preferredPassthroughOpacity, this value can be overwritten by the system, and is not directly under the application's control.

val isPreferredSpatialEnvironmentActive: Boolean

Checks if the application's preferred spatial environment set through preferredSpatialEnvironment is active.

Spatial environment preference set through 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.

var preferredPassthroughOpacity: Float

The application's preferred passthrough opacity.

Upon construction, the default value is 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 SpatialCapability.SPATIAL_CAPABILITY_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 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 currentPassthroughOpacity or by registering a listener with addOnPassthroughOpacityChangedListener.

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 isPreferredSpatialEnvironmentActive is already true. Once the device enters a state where the XR background can be changed and the SpatialCapability.SPATIAL_CAPABILITY_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 SpatialEnvironmentPreference is not null, but all of its properties are null, then the spatial environment will consist of a black skybox and no geometry.

See isPreferredSpatialEnvironmentActive or the addOnSpatialEnvironmentChangedListener listeners to know when this preference becomes active.