JxrPlatformAdapter.SpatialEnvironment

public interface JxrPlatformAdapter.SpatialEnvironment

Interface for updating the background image/geometry and passthrough settings.

The application can set either / both a skybox and a glTF for geometry, then toggle their visibility by enabling or disabling passthrough. The skybox and geometry will be remembered across passthrough mode changes.

Summary

Nested types

Result values for calls to SpatialEnvironment.setPassthroughOpacityPreference

Result values for calls to SpatialEnvironment.setSpatialEnvironmentPreference

A class that represents the user's preferred spatial environment.

Public methods
abstract void

Notifies an application when the passthrough state changes, such as when the application enters or exits passthrough or when the passthrough opacity changes.
abstract void

Notifies an application whether or not the preferred spatial environment for the application is active.
abstract float

Gets the current passthrough opacity value between 0 and 1 where 0.0f means no passthrough, and 1.0f means full passthrough.
abstract @Nullable Float

Gets the last passthrough opacity requested through [setPassthroughOpacityPreference].
abstract @Nullable JxrPlatformAdapter.SpatialEnvironment.SpatialEnvironmentPreference

Gets the preferred spatial environment for the application.
abstract boolean

Returns true if the environment set by [setSpatialEnvironmentPreference] is active.
abstract void

Remove a listener previously added by [addOnPassthroughOpacityChangedListener].
abstract void

Remove a listener previously added by [addOnSpatialEnvironmentChangedListener].
abstract @NonNull JxrPlatformAdapter.SpatialEnvironment.SetPassthroughOpacityPreferenceResult
@CanIgnoreReturnValue
setPassthroughOpacityPreference(
    @Nullable Float passthroughOpacityPreference
)

Sets the preference for passthrough state by requesting a change in passthrough opacity.
abstract @NonNull JxrPlatformAdapter.SpatialEnvironment.SetSpatialEnvironmentPreferenceResult

Sets the preferred spatial environment for the application.

Public methods

addOnPassthroughOpacityChangedListener

Added in 1.0.0-alpha01
abstract void addOnPassthroughOpacityChangedListener(
    @NonNull Consumer<Float> listener
)

Notifies an application when the 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 UI thread.

addOnSpatialEnvironmentChangedListener

Added in 1.0.0-alpha01
abstract void addOnSpatialEnvironmentChangedListener(
    @NonNull Consumer<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 UI thread.

getCurrentPassthroughOpacity

Added in 1.0.0-alpha01
abstract float getCurrentPassthroughOpacity()

Gets the current passthrough opacity value between 0 and 1 where 0.0f means no passthrough, and 1.0f means full passthrough.

This value can be overwritten by user-enabled or system-enabled passthrough and will not always match the opacity value returned by [getPassthroughOpacityPreference].

getPassthroughOpacityPreference

Added in 1.0.0-alpha01
abstract @Nullable Float getPassthroughOpacityPreference()

Gets the last passthrough opacity requested through [setPassthroughOpacityPreference].

This may be different from the actual current state returned by [getCurrentPassthroughOpacity], but it should be applied as soon as the [SpatialCapabilities.SPATIAL_CAPABILITY_PASSTHROUGH_CONTROL] capability is gained. Defaults to null, if [setPassthroughOpacityPreference] was never called.

If set to null, the passthrough opacity will default to the user preference managed through the system.

getSpatialEnvironmentPreference

Added in 1.0.0-alpha01
abstract @Nullable JxrPlatformAdapter.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 [OnSpatialEnvironmentChangedListener] events to know when this preference becomes active.

isSpatialEnvironmentPreferenceActive

Added in 1.0.0-alpha01
abstract 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.

removeOnPassthroughOpacityChangedListener

Added in 1.0.0-alpha01
abstract void removeOnPassthroughOpacityChangedListener(
    @NonNull Consumer<Float> listener
)

Remove a listener previously added by [addOnPassthroughOpacityChangedListener].

removeOnSpatialEnvironmentChangedListener

Added in 1.0.0-alpha01
abstract void removeOnSpatialEnvironmentChangedListener(
    @NonNull Consumer<Boolean> listener
)

Remove a listener previously added by [addOnSpatialEnvironmentChangedListener].

setPassthroughOpacityPreference

Added in 1.0.0-alpha01
@CanIgnoreReturnValue
abstract @NonNull JxrPlatformAdapter.SpatialEnvironment.SetPassthroughOpacityPreferenceResult setPassthroughOpacityPreference(
    @Nullable Float passthroughOpacityPreference
)

Sets the preference for passthrough state by requesting a change in passthrough opacity.

Passthrough visibility cannot be set directly to on/off modes. Instead, a desired passthrough opacity value between 0.0f and 1.0f can be requested which will dictate which mode is used. A passthrough opacity within 0.01f of 0.0f will disable passthrough, and will be returned as 0.0f by [getPassthroughOpacityPreference]. An opacity value within 0.01f of 1.0f will enable full passthrough and it will be returned as 1.0f by [getPassthroughOpacityPreference]. Any other value in the range will result in a semi-transparent passthrough.

Requesting to set passthrough opacity to a value that is not in the range of 0.0f to 1.0f will result in the value getting clamped to 0.0f or 1.0f depending on which one is closer.

If the value is set to null, the opacity will be managed by the system.

Requests to change opacity are only immediately attempted to be honored if the activity has the [SpatialCapabilities.SPATIAL_CAPABILITY_PASSTHROUGH_CONTROL] capability. When the request is honored, this returns [SetPassthroughOpacityPreferenceChangeApplied]. When the activity does not have the capability to control the passthrough state, this returns [SetPassthroughOpacityPreferenceChangePending] to indicate that the application passthrough opacity preference has been set and is pending to be automatically applied when the app regains capabilities to control passthrough state.

When passthrough state changes, whether due to this request succeeding or due to any other system or user initiated change, [OnPassthroughOpacityChangedListener] will be notified.

setSpatialEnvironmentPreference

Added in 1.0.0-alpha01
@CanIgnoreReturnValue
abstract @NonNull JxrPlatformAdapter.SpatialEnvironment.SetSpatialEnvironmentPreferenceResult setSpatialEnvironmentPreference(
    @Nullable JxrPlatformAdapter.SpatialEnvironment.SpatialEnvironmentPreference preference
)

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 the [OnSpatialEnvironmentChangedListener].