JxrPlatformAdapter.SpatialEnvironment

fun addOnPassthroughOpacityChangedListener(listener: Consumer<Float!>): Unit

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.

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

fun getCurrentPassthroughOpacity(): Float

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

fun getPassthroughOpacityPreference(): Float?

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.

fun getSpatialEnvironmentPreference(): JxrPlatformAdapter.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 [OnSpatialEnvironmentChangedListener] events 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].

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

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.

@CanIgnoreReturnValue
fun setSpatialEnvironmentPreference(
    preference: JxrPlatformAdapter.SpatialEnvironment.SpatialEnvironmentPreference?
): JxrPlatformAdapter.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 the [OnSpatialEnvironmentChangedListener].