SpatialEnvironment
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 androidx.xr.runtime.Session and it is accessible through Session.scene.
The SpatialEnvironment is a composite of a glTF-specified geometry 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:
-
A combination of image based lighting and glTF geometry which should contain a skybox texture.
-
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.
-
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 |
|---|
public final class SpatialEnvironment.SpatialEnvironmentPreferenceRepresents the preferred spatial environment for the application. |
Constants |
|
|---|---|
static final float |
Passed into |
Public methods |
|
|---|---|
final void |
addPassthroughOpacityChangedListener(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 |
addPassthroughOpacityChangedListener(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 |
addSpatialEnvironmentChangedListener(Notifies an application whether the preferred spatial environment for the application is active. |
final void |
addSpatialEnvironmentChangedListener(Notifies an application whether the preferred spatial environment for the application is active. |
final float |
Gets the current passthrough opacity value visible to the user. |
final float |
The application's preferred passthrough opacity. |
final SpatialEnvironment.SpatialEnvironmentPreference |
The preferred spatial environment for the application. |
final boolean |
Checks if the application's preferred spatial environment set through |
final void |
removePassthroughOpacityChangedListener(Remove a listener previously added by |
final void |
removeSpatialEnvironmentChangedListener(Remove a listener previously added by |
final void |
setPreferredPassthroughOpacity(float value)The application's preferred passthrough opacity. |
final void |
The preferred spatial environment for the application. |
Constants
NO_PASSTHROUGH_OPACITY_PREFERENCE
public static final float NO_PASSTHROUGH_OPACITY_PREFERENCE
Passed into preferredPassthroughOpacity to clear the application's passthrough opacity preference and to let the system manage passthrough opacity.
Public methods
addPassthroughOpacityChangedListener
public final void addPassthroughOpacityChangedListener(
@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.
addPassthroughOpacityChangedListener
public final void addPassthroughOpacityChangedListener(
@NonNull Executor executor,
@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 invoked on the given Executor.
addSpatialEnvironmentChangedListener
public final void addSpatialEnvironmentChangedListener(
@NonNull Consumer<@NonNull Boolean> listener
)
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 preferredSpatialEnvironment and the application has the 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.
addSpatialEnvironmentChangedListener
public final void addSpatialEnvironmentChangedListener(
@NonNull Executor executor,
@NonNull Consumer<@NonNull Boolean> listener
)
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 preferredSpatialEnvironment and the application has the 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 Executor.
getCurrentPassthroughOpacity
public final float getCurrentPassthroughOpacity()
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.
| 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. |
getPreferredPassthroughOpacity
public final float getPreferredPassthroughOpacity()
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.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 addPassthroughOpacityChangedListener.
getPreferredSpatialEnvironment
public final SpatialEnvironment.SpatialEnvironmentPreference getPreferredSpatialEnvironment()
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.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 void.
See isPreferredSpatialEnvironmentActive or the addSpatialEnvironmentChangedListener listeners to know when this preference becomes active.
isPreferredSpatialEnvironmentActive
public final boolean isPreferredSpatialEnvironmentActive()
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.
| Returns | |
|---|---|
boolean |
True if the environment set by |
removePassthroughOpacityChangedListener
public final void removePassthroughOpacityChangedListener(
@NonNull Consumer<@NonNull Float> listener
)
Remove a listener previously added by addPassthroughOpacityChangedListener.
Remaining listeners are automatically removed when the SpatialEnvironment is destroyed.
removeSpatialEnvironmentChangedListener
public final void removeSpatialEnvironmentChangedListener(
@NonNull Consumer<@NonNull Boolean> listener
)
Remove a listener previously added by addSpatialEnvironmentChangedListener.
Remaining listeners are automatically removed when the SpatialEnvironment is destroyed.
setPreferredPassthroughOpacity
public final void setPreferredPassthroughOpacity(float value)
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.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 addPassthroughOpacityChangedListener.
setPreferredSpatialEnvironment
public final void setPreferredSpatialEnvironment(
SpatialEnvironment.SpatialEnvironmentPreference value
)
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.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 void.
See isPreferredSpatialEnvironmentActive or the addSpatialEnvironmentChangedListener listeners to know when this preference becomes active.