SpatialEnvironment

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 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 setSpatialEnvironmentPreference and the application has the SpatialCapabilities.SPATIAL_CAPABILITY_APP_ENVIRONMENTS 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 getCurrentPassthroughOpacity(): Float

Gets the current passthrough opacity value visible to the user.

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

fun getPassthroughMode(): SpatialEnvironment.PassthroughMode

Gets the current preference for passthrough mode.

fun getPassthroughOpacity(): Float

Gets the current passthrough opacity. This may be different than the passthrough opacity preference.

fun getPassthroughOpacityPreference(): Float?

Gets the current passthrough opacity preference set through setPassthroughOpacityPreference. Defaults to null if setPassthroughOpacityPreference has not been called.

This value only reflects the application's preference and does not necessarily reflect what the system is currently showing the user. See getCurrentPassthroughOpacity to get the actual visible opacity value.

fun getSpatialEnvironmentPreference(): SpatialEnvironment.SpatialEnvironmentPreference?

Gets the preferred spatial environment for the application.

The returned value is always what was most recently supplied to setSpatialEnvironmentPreference, or null if no preference has been set.

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

fun isSpatialEnvironmentPreferenceActive(): Boolean

Returns true if the environment set by setSpatialEnvironmentPreference is active.

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

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

Remove a listener previously added by addOnPassthroughOpacityChangedListener.

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

Remove a listener previously added by addOnSpatialEnvironmentChangedListener.

fun setGeometry(gltfModel: GltfModel?): Unit

Sets the preferred environmental geometry based on a pre-loaded GltfModel.

Note that this method does not necessarily cause an immediate change, it only sets a preference. Once the device enters a state where the XR background can be changed, the preference will be applied.

Setting the geometry to null will disable the geometry.

fun setPassthrough(passthroughMode: SpatialEnvironment.PassthroughMode): Unit

Sets the preference for passthrough.

Calling with DISABLED is equivalent to calling setPassthroughOpacityPreference(0.0f) and calling with ENABLED is equivalent to calling setPassthroughOpacityPreference(1.0f). Calling with UNINITIALIZED is ignored. See setPassthroughOpacityPreference for more details.

fun setPassthroughOpacity(passthroughOpacity: Float): Unit

Sets the preference for passthrough. This is equivalent to calling setPassthroughOpacityPreference with the given opacity value.

@CanIgnoreReturnValue
fun setPassthroughOpacityPreference(passthroughOpacityPreference: Float?): SpatialEnvironment.SetPassthroughOpacityPreferenceResult

Sets the application's preferred passthrough opacity between 0.0f and 1.0f. Upon construction, the default value is null, which means "no application preference".

Setting the application preference through this method 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 the application's preference and user actions outside the application. Generally, the application's preference will be shown to the user when the application has the SpatialCapabilities.SPATIAL_CAPABILITY_PASSTHROUGH_CONTROL capability. The current value visible to the user can be observed by calling getCurrentPassthroughOpacity or by registering a listener with addOnPassthroughOpacityChangedListener.

fun setSkybox(exrImage: ExrImage?): Unit

Sets the preferred environmental skybox based on a pre-loaded EXR Image.

Note that this method does not necessarily cause an immediate change, it only sets a preference. Once the device enters a state where the XR background can be changed, the preference will be applied.

Setting the skybox to null will disable the skybox.

@CanIgnoreReturnValue
fun setSpatialEnvironmentPreference(
    environmentPreference: SpatialEnvironment.SpatialEnvironmentPreference?
): SpatialEnvironment.SetSpatialEnvironmentPreferenceResult

Sets the preferred spatial environment for the application.

Note that this method only sets a preference and does not cause an immediate change unless isSpatialEnvironmentPreferenceActive is already true. Once the device enters a state where the XR background can be changed and the SpatialCapabilities.SPATIAL_CAPABILITY_APP_ENVIRONMENTS 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 isSpatialEnvironmentPreferenceActive is true.

Changes to the Environment state will be notified via listeners added with addOnSpatialEnvironmentChangedListener.