SessionExt

Added in 1.0.0-alpha02

public final class SessionExt


Summary

Public methods

static final void

Adds the given Consumer as a listener to be invoked when this Session's current SpatialCapabilities change.

static final void
addSpatialCapabilitiesChangedListener(
    @NonNull Session receiver,
    @NonNull Executor callbackExecutor,
    @NonNull Consumer<@NonNull SpatialCapabilities> listener
)

Adds the given Consumer as a listener to be invoked when this Session's current SpatialCapabilities change.

static final @NonNull List<@NonNull T>
<T extends Entity> getEntitiesOfType(
    @NonNull Session receiver,
    @NonNull Class<@NonNull T> type
)

Returns all Entitys of the given type or its subtypes.

static final @NonNull SpatialCapabilities

Returns the current SpatialCapabilities of the Session.

static final void

Releases the given Consumer from receiving updates when the Session's SpatialCapabilities change.

static final @NonNull Bundle

Sets the full space mode flag to the given android.os.Bundle.

static final @NonNull Bundle

Sets the inherit full space mode environvment flag to the given android.os.Bundle.

static final void
setPreferredAspectRatio(
    @NonNull Session receiver,
    @NonNull Activity activity,
    float preferredRatio
)

Sets a preferred main panel aspect ratio for home space mode.

Public methods

addSpatialCapabilitiesChangedListener

public static final void addSpatialCapabilitiesChangedListener(
    @NonNull Session receiver,
    @NonNull Consumer<@NonNull SpatialCapabilities> listener
)

Adds the given Consumer as a listener to be invoked when this Session's current SpatialCapabilities change. Consumer#accept(SpatialCapabilities) will be invoked on the main thread.

addSpatialCapabilitiesChangedListener

public static final void addSpatialCapabilitiesChangedListener(
    @NonNull Session receiver,
    @NonNull Executor callbackExecutor,
    @NonNull Consumer<@NonNull SpatialCapabilities> listener
)

Adds the given Consumer as a listener to be invoked when this Session's current SpatialCapabilities change. Consumer#accept(SpatialCapabilities) will be invoked on the given callbackExecutor, or the main thread if the callbackExecutor is null (default).

getEntitiesOfType

public static final @NonNull List<@NonNull T> <T extends Entity> getEntitiesOfType(
    @NonNull Session receiver,
    @NonNull Class<@NonNull T> type
)

Returns all Entitys of the given type or its subtypes.

Parameters
@NonNull Class<@NonNull T> type

the type of Entity to return.

Returns
@NonNull List<@NonNull T>

a list of all Entitys of the given type.

getSpatialCapabilities

public static final @NonNull SpatialCapabilities getSpatialCapabilities(@NonNull Session receiver)

Returns the current SpatialCapabilities of the Session. The set of capabilities can change within a session. The returned object will not update if the capabilities change; this method should be called again to get the latest set of capabilities.

removeSpatialCapabilitiesChangedListener

public static final void removeSpatialCapabilitiesChangedListener(
    @NonNull Session receiver,
    @NonNull Consumer<@NonNull SpatialCapabilities> listener
)

Releases the given Consumer from receiving updates when the Session's SpatialCapabilities change.

setFullSpaceMode

public static final @NonNull Bundle setFullSpaceMode(@NonNull Session receiver, @NonNull Bundle bundle)

Sets the full space mode flag to the given android.os.Bundle.

The android.os.Bundle then could be used to launch an android.app.Activity with requesting to enter full space mode through android.app.Activity.startActivity. If there's a bundle used for customizing how the android.app.Activity should be started by android.app.ActivityOptions.toBundle or androidx.core.app.ActivityOptionsCompat.toBundle, it's suggested to use the bundle to call this method.

The flag will be ignored when no android.content.Intent.FLAG_ACTIVITY_NEW_TASK is set in the bundle, or it is not started from a focused Activity context.

This flag is also ignored when the android.window.PROPERTY_XR_ACTIVITY_START_MODE property is set to a value other than XR_ACTIVITY_START_MODE_UNDEFINED in the AndroidManifest.xml file for the activity being launched.

Parameters
@NonNull Bundle bundle

the input bundle to set with the full space mode flag.

Returns
@NonNull Bundle

the input bundle with the full space mode flag set.

setFullSpaceModeWithEnvironmentInherited

public static final @NonNull Bundle setFullSpaceModeWithEnvironmentInherited(
    @NonNull Session receiver,
    @NonNull Bundle bundle
)

Sets the inherit full space mode environvment flag to the given android.os.Bundle.

The android.os.Bundle then could be used to launch an android.app.Activity with requesting to enter full space mode while inherit the existing environment through android.app.Activity.startActivity. If there's a bundle used for customizing how the android.app.Activity should be started by android.app.ActivityOptions.toBundle or androidx.core.app.ActivityOptionsCompat.toBundle, it's suggested to use the bundle to call this method.

When launched, the activity will be in full space mode and also inherits the environment from the launching activity. If the inherited environment needs to be animated, the launching activity has to continue updating the environment even after the activity is put into the stopped state.

The flag will be ignored when no android.content.Intent.FLAG_ACTIVITY_NEW_TASK is set in the intent, or it is not started from a focused Activity context.

The flag will also be ignored when there is no environment to inherit or the activity has its own environment set already.

This flag is ignored too when the android.window.PROPERTY_XR_ACTIVITY_START_MODE property is set to a value other than XR_ACTIVITY_START_MODE_UNDEFINED in the AndroidManifest.xml file for the activity being launched.

For security reasons, Z testing for the new activity is disabled, and the activity is always drawn on top of the inherited environment. Because Z testing is disabled, the activity should not spatialize itself.

Parameters
@NonNull Bundle bundle

the input bundle to set with the inherit full space mode environment flag.

Returns
@NonNull Bundle

the input bundle with the inherit full space mode flag set.

setPreferredAspectRatio

public static final void setPreferredAspectRatio(
    @NonNull Session receiver,
    @NonNull Activity activity,
    float preferredRatio
)

Sets a preferred main panel aspect ratio for home space mode.

The ratio is only applied to the activity. If the activity launches another activity in the same task, the ratio is not applied to the new activity. Also, while the activity is in full space mode, the preference is temporarily removed.

If the activity's current aspect ratio differs from the preferredRatio, the panel is automatically resized. This resizing preserves the panel's area. To avoid runtime resizing, consider specifying the desired aspect ratio in your AndroidManifest.xml. This ensures your activity launches with the preferred aspect ratio from the start.

Parameters
@NonNull Activity activity

the activity to set the preference.

float preferredRatio

the aspect ratio determined by taking the panel's width over its height. A value <= 0.0f means there are no preferences.