SpatialEnvironment

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

public final void addOnPassthroughOpacityChangedListener(
    @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.

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 preferredSpatialEnvironment and the application has the SpatialCapabilities.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.

public final void addOnSpatialEnvironmentChangedListener(
    @NonNull Executor executor,
    @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 preferredSpatialEnvironment and the application has the SpatialCapabilities.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.

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.

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 SpatialCapabilities.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 spatial 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.

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 SpatialCapabilities.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.

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.

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

Remove a listener previously added by addOnPassthroughOpacityChangedListener.

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

Remove a listener previously added by addOnSpatialEnvironmentChangedListener.

public final void setPreferredPassthroughOpacity(float preferredPassthroughOpacity)

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 SpatialCapabilities.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 spatial 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.

public final void setPreferredSpatialEnvironment(
    SpatialEnvironment.SpatialEnvironmentPreference preferredSpatialEnvironment
)

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 SpatialCapabilities.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.