SpatialEnvironment

Artifact: androidx.xr.scenecore:scenecore

View Source

Added in 1.0.0-alpha01

---

Kotlin |Java

public final class SpatialEnvironment

---

The SpatialEnvironment is used to manage the XR background and passthrough. There is a single instance of this class managed by each SceneCore Session (which is bound to an Activity.)

The SpatialEnvironment is a composite of a stand-alone skybox, and glTF-specified geometry. A single skybox and a single glTF can be set at the same time. Applications are encouraged to supply glTFs for ground and horizon visibility.

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

1. A combination of a skybox and glTF geometry.

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 skybox and 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 skybox and 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
public final class SpatialEnvironment.PassthroughMode This class is deprecated. Use isSpatialEnvironmentPreferenceActive() instead.
public final class SpatialEnvironment.SetPassthroughOpacityPreferenceChangeApplied extends SpatialEnvironment.SetPassthroughOpacityPreferenceResult The call to setPassthroughOpacityPreference succeeded and should now be visible.
public final class SpatialEnvironment.SetPassthroughOpacityPreferenceChangePending extends SpatialEnvironment.SetPassthroughOpacityPreferenceResult The call to setPassthroughOpacityPreference successfully applied the preference, but it is not immediately visible due to requesting a state change while the activity does not have the SpatialCapabilities.SPATIAL_CAPABILITY_PASSTHROUGH_CONTROL capability to control the app passthrough state.
public sealed class SpatialEnvironment.SetPassthroughOpacityPreferenceResult Result values for calls to setPassthroughOpacityPreference
public final class SpatialEnvironment.SetSpatialEnvironmentPreferenceChangeApplied extends SpatialEnvironment.SetSpatialEnvironmentPreferenceResult The call to setSpatialEnvironmentPreference succeeded and should now be visible.
public final class SpatialEnvironment.SetSpatialEnvironmentPreferenceChangePending extends SpatialEnvironment.SetSpatialEnvironmentPreferenceResult The call to setSpatialEnvironmentPreference successfully applied the preference, but it is not immediately visible due to requesting a state change while the activity does not have the SpatialCapabilities.SPATIAL_CAPABILITY_APP_ENVIRONMENTS capability to control the app environment state.
public sealed class SpatialEnvironment.SetSpatialEnvironmentPreferenceResult Result values for calls to SpatialEnvironment.setSpatialEnvironmentPreference
public final class SpatialEnvironment.SpatialEnvironmentPreference Represents the preferred spatial environment for the application.

Public constructors
SpatialEnvironment(@NonNull JxrPlatformAdapter runtime)

Public methods
final void	addOnPassthroughOpacityChangedListener(     @NonNull Consumer<@NonNull Float> listener ) 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.
final void	addOnSpatialEnvironmentChangedListener(     @NonNull Consumer<@NonNull Boolean> listener ) Notifies an application whether or not the preferred spatial environment for the application is active.
final float	getCurrentPassthroughOpacity() Gets the current passthrough opacity value visible to the user.
final @NonNull SpatialEnvironment.PassthroughMode	getPassthroughMode() This method is deprecated. Use getCurrentPassthroughOpacity instead.
final float	getPassthroughOpacity() This method is deprecated. Use getCurrentPassthroughOpacity instead.
final Float	getPassthroughOpacityPreference() Gets the current passthrough opacity preference set through setPassthroughOpacityPreference.
final SpatialEnvironment.SpatialEnvironmentPreference	getSpatialEnvironmentPreference() Gets the preferred spatial environment for the application.
final boolean	isSpatialEnvironmentPreferenceActive() Returns true if the environment set by setSpatialEnvironmentPreference is active.
final void	removeOnPassthroughOpacityChangedListener(     @NonNull Consumer<@NonNull Float> listener ) Remove a listener previously added by addOnPassthroughOpacityChangedListener.
final void	removeOnSpatialEnvironmentChangedListener(     @NonNull Consumer<@NonNull Boolean> listener ) Remove a listener previously added by addOnSpatialEnvironmentChangedListener.
final void	setGeometry(GltfModel gltfModel) This method is deprecated. Use setSpatialEnvironmentPreference() instead.
final void	setPassthrough(     @NonNull SpatialEnvironment.PassthroughMode passthroughMode ) This method is deprecated. Use setPassthroughOpacityPreference instead.
final void	setPassthroughOpacity(float passthroughOpacity) This method is deprecated. Use setPassthroughOpacityPreference instead.
final @NonNull SpatialEnvironment.SetPassthroughOpacityPreferenceResult	@CanIgnoreReturnValue setPassthroughOpacityPreference(Float passthroughOpacityPreference) Sets the application's preferred passthrough opacity between 0.0f and 1.0f.
final void	setSkybox(ExrImage exrImage) This method is deprecated. Use setSpatialEnvironmentPreference() instead.
final @NonNull SpatialEnvironment.SetSpatialEnvironmentPreferenceResult	@CanIgnoreReturnValue setSpatialEnvironmentPreference(     SpatialEnvironment.SpatialEnvironmentPreference environmentPreference ) Sets the preferred spatial environment for the application.

Public constructors

SpatialEnvironment

Added in 1.0.0-alpha01

public SpatialEnvironment(@NonNull JxrPlatformAdapter runtime)

Public methods

addOnPassthroughOpacityChangedListener

Added in 1.0.0-alpha01

public final void addOnPassthroughOpacityChangedListener(
    @NonNull Consumer<@NonNull Float> listener
)

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.

Parameters
@NonNull Consumer<@NonNull Float> listener	The Consumer to be added to listen for passthrough opacity changes.

addOnSpatialEnvironmentChangedListener

Added in 1.0.0-alpha01

public final void addOnSpatialEnvironmentChangedListener(
    @NonNull Consumer<@NonNull Boolean> listener
)

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.

Parameters
@NonNull Consumer<@NonNull Boolean> listener	The Consumer to be added to listen for spatial environment changes.

getCurrentPassthroughOpacity

Added in 1.0.0-alpha01

public final float getCurrentPassthroughOpacity()

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.

Returns
float	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.

getPassthroughMode

Added in 1.0.0-alpha01

Deprecated in 1.0.0-alpha01

public final @NonNull SpatialEnvironment.PassthroughMode getPassthroughMode()

This method is deprecated.
Use getCurrentPassthroughOpacity instead.

Gets the current preference for passthrough mode.

getPassthroughOpacity

Added in 1.0.0-alpha01

Deprecated in 1.0.0-alpha01

public final float getPassthroughOpacity()

This method is deprecated.
Use getCurrentPassthroughOpacity instead.

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

getPassthroughOpacityPreference

Added in 1.0.0-alpha01

public final Float getPassthroughOpacityPreference()

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.

Returns
Float	The last passthrough opacity value between 0.0f and 1.0f requested through setPassthroughOpacityPreference. If null, no application preference is set and the passthrough opacity will be fully managed through the system.

getSpatialEnvironmentPreference

Added in 1.0.0-alpha01

public final SpatialEnvironment.SpatialEnvironmentPreference getSpatialEnvironmentPreference()

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.

Returns
SpatialEnvironment.SpatialEnvironmentPreference	The most recent spatial environment preference supplied to setSpatialEnvironmentPreference. If null, the default system environment will be displayed instead.

isSpatialEnvironmentPreferenceActive

Added in 1.0.0-alpha01

public final boolean isSpatialEnvironmentPreferenceActive()

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.

Returns
boolean	True if the environment set by setSpatialEnvironmentPreference is active.

removeOnPassthroughOpacityChangedListener

Added in 1.0.0-alpha01

public final void removeOnPassthroughOpacityChangedListener(
    @NonNull Consumer<@NonNull Float> listener
)

Remove a listener previously added by addOnPassthroughOpacityChangedListener.

Parameters
@NonNull Consumer<@NonNull Float> listener	The previously-added Consumer listener to be removed.

removeOnSpatialEnvironmentChangedListener

Added in 1.0.0-alpha01

public final void removeOnSpatialEnvironmentChangedListener(
    @NonNull Consumer<@NonNull Boolean> listener
)

Remove a listener previously added by addOnSpatialEnvironmentChangedListener.

Parameters
@NonNull Consumer<@NonNull Boolean> listener	The previously-added Consumer listener to be removed.

setGeometry

Added in 1.0.0-alpha01

Deprecated in 1.0.0-alpha01

public final void setGeometry(GltfModel gltfModel)

This method is deprecated.
Use setSpatialEnvironmentPreference() instead.

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.

setPassthrough

Added in 1.0.0-alpha01

Deprecated in 1.0.0-alpha01

public final void setPassthrough(
    @NonNull SpatialEnvironment.PassthroughMode passthroughMode
)

This method is deprecated.
Use setPassthroughOpacityPreference instead.

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.

setPassthroughOpacity

Added in 1.0.0-alpha01

Deprecated in 1.0.0-alpha01

public final void setPassthroughOpacity(float passthroughOpacity)

This method is deprecated.
Use setPassthroughOpacityPreference instead.

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

setPassthroughOpacityPreference

Added in 1.0.0-alpha01

@CanIgnoreReturnValue
public final @NonNull SpatialEnvironment.SetPassthroughOpacityPreferenceResult setPassthroughOpacityPreference(Float passthroughOpacityPreference)

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.

Parameters

Float passthroughOpacityPreference

The application's passthrough opacity preference between 0.0f (disabled with no passthrough) and 1.0f (fully enabled passthrough hides the spatial environment). Values within 0.01f of 0.0 or 1.0 will be snapped to those values. Other values result in semi-transparent passthrough alpha blended with the spatial environment. Values outside 0.0f, 1.0f are clamped. If null, the system will manage the passthrough opacity.

Returns
@NonNull SpatialEnvironment.SetPassthroughOpacityPreferenceResult	The result of the call to set the passthrough opacity preference. If the preference was successfully set and applied, the result will be SetPassthroughOpacityPreferenceChangeApplied. If the preference was set, but it cannot be currently applied, the result will be SetPassthroughOpacityPreferenceChangePending.

setSkybox

Added in 1.0.0-alpha01

Deprecated in 1.0.0-alpha01

public final void setSkybox(ExrImage exrImage)

This method is deprecated.
Use setSpatialEnvironmentPreference() instead.

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.

setSpatialEnvironmentPreference

Added in 1.0.0-alpha01

@CanIgnoreReturnValue
public final @NonNull SpatialEnvironment.SetSpatialEnvironmentPreferenceResult setSpatialEnvironmentPreference(
    SpatialEnvironment.SpatialEnvironmentPreference environmentPreference
)

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.

Parameters
SpatialEnvironment.SpatialEnvironmentPreference environmentPreference	The preferred spatial environment for the application. If null, then there is no preference, and the default system environment will be displayed instead.

Returns
@NonNull SpatialEnvironment.SetSpatialEnvironmentPreferenceResult	The result of the call to set the spatial environment preference. If the preference was successfully set and applied, the result will be SetSpatialEnvironmentPreferenceChangeApplied. If the preference was set, but it cannot be currently applied, the result will be SetSpatialEnvironmentPreferenceChangePending.