public final class Scene


Scene is the primary interface to SceneCore functionality for the application. Each spatialized Activity must create and hold an instance of a Scene.

Once created, the application can use the Scene object to create spatialized entities, such as Widget panels and geometric models, set the background environment, and anchor content to the real world.

Summary

Public fields

final lateinit @NonNull ActivitySpace

The ActivitySpace is a special entity that represents the space in which the application is launched.

final lateinit @NonNull Entity
final lateinit @NonNull PanelEntity

A spatialized PanelEntity associated with the "main window" for the Activity.

final lateinit @NonNull PerceptionSpace

The PerceptionSpace represents the origin of the space in which the ARCore for XR API provides tracking info.

final lateinit @NonNull SpatialCapabilities

Returns the current SpatialCapabilities of the Session.

final lateinit @NonNull SpatialEnvironment
final lateinit @NonNull SpatialUser

The SpatialUser contains information about the user.

Public constructors

Public methods

final void

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

final void

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

final void

Releases the listener previously added by setSpatialVisibilityChangedListener.

void

Closes the SessionConnector.

final @NonNull ActivitySpace

The ActivitySpace is a special entity that represents the space in which the application is launched.

final @NonNull Entity
final @NonNull List<@NonNull T>
<T extends Entity> getEntitiesOfType(@NonNull Class<@NonNull T> type)

Returns all Entitys of the given type or its subtypes.

final @NonNull PanelEntity

A spatialized PanelEntity associated with the "main window" for the Activity.

final @NonNull PerceptionSpace

The PerceptionSpace represents the origin of the space in which the ARCore for XR API provides tracking info.

final @NonNull SpatialCapabilities

Returns the current SpatialCapabilities of the Session.

final @NonNull SpatialEnvironment
final @NonNull SpatialUser

The SpatialUser contains information about the user.

void
initialize(
    @NonNull LifecycleManager lifecycleManager,
    @NonNull JxrPlatformAdapter platformAdapter
)

Initializes the SessionConnector.

final void

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

final void

The ActivitySpace is a special entity that represents the space in which the application is launched.

final void
setActivitySpaceRoot(@NonNull Entity activitySpaceRoot)
final @NonNull Bundle

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

final @NonNull Bundle

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

final void

A spatialized PanelEntity associated with the "main window" for the Activity.

final void

The PerceptionSpace represents the origin of the space in which the ARCore for XR API provides tracking info.

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

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

final void

Returns the current SpatialCapabilities of the Session.

final void
final void

The SpatialUser contains information about the user.

final void

Sets the listener to be invoked on the main thread executor when the spatial visibility of the rendered content of the entire scene (all entities, including children of anchors and activitySpace) changes within the user's field of view.

final void

Sets the listener to be invoked when the spatial visibility of the rendered content of the entire scene (all entities, including children of anchors and activitySpace) changes within the user's field of view.

Public fields

activitySpace

Added in 1.0.0-alpha04
public final lateinit @NonNull ActivitySpace activitySpace

The ActivitySpace is a special entity that represents the space in which the application is launched. It is the default parent of all entities in the scene.

The ActivitySpace is created automatically when the Session is created.

activitySpaceRoot

Added in 1.0.0-alpha04
public final lateinit @NonNull Entity activitySpaceRoot

mainPanelEntity

Added in 1.0.0-alpha04
public final lateinit @NonNull PanelEntity mainPanelEntity

A spatialized PanelEntity associated with the "main window" for the Activity. When in HomeSpace mode, this is the application's "main window".

If called multiple times, this will return the same PanelEntity.

perceptionSpace

Added in 1.0.0-alpha04
public final lateinit @NonNull PerceptionSpace perceptionSpace

The PerceptionSpace represents the origin of the space in which the ARCore for XR API provides tracking info. The transformations provided by the PerceptionSpace are only valid for the call frame, as the transformation can be changed by the system at any time.

spatialCapabilities

Added in 1.0.0-alpha04
public final lateinit @NonNull SpatialCapabilities spatialCapabilities

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.

spatialEnvironment

Added in 1.0.0-alpha04
public final lateinit @NonNull SpatialEnvironment spatialEnvironment

spatialUser

Added in 1.0.0-alpha04
public final lateinit @NonNull SpatialUser spatialUser

The SpatialUser contains information about the user.

Public constructors

Scene

Added in 1.0.0-alpha04
public Scene()

Public methods

addSpatialCapabilitiesChangedListener

Added in 1.0.0-alpha04
public final void addSpatialCapabilitiesChangedListener(
    @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

Added in 1.0.0-alpha04
public final void addSpatialCapabilitiesChangedListener(
    @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).

clearSpatialVisibilityChangedListener

Added in 1.0.0-alpha04
public final void clearSpatialVisibilityChangedListener()

Releases the listener previously added by setSpatialVisibilityChangedListener.

close

Added in 1.0.0-alpha04
public void close()

Closes the SessionConnector. Called when the Session is destroyed.

getActivitySpace

Added in 1.0.0-alpha04
public final @NonNull ActivitySpace getActivitySpace()

The ActivitySpace is a special entity that represents the space in which the application is launched. It is the default parent of all entities in the scene.

The ActivitySpace is created automatically when the Session is created.

getActivitySpaceRoot

Added in 1.0.0-alpha04
public final @NonNull Entity getActivitySpaceRoot()

getEntitiesOfType

Added in 1.0.0-alpha04
public final @NonNull List<@NonNull T> <T extends Entity> getEntitiesOfType(@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.

getMainPanelEntity

Added in 1.0.0-alpha04
public final @NonNull PanelEntity getMainPanelEntity()

A spatialized PanelEntity associated with the "main window" for the Activity. When in HomeSpace mode, this is the application's "main window".

If called multiple times, this will return the same PanelEntity.

getPerceptionSpace

Added in 1.0.0-alpha04
public final @NonNull PerceptionSpace getPerceptionSpace()

The PerceptionSpace represents the origin of the space in which the ARCore for XR API provides tracking info. The transformations provided by the PerceptionSpace are only valid for the call frame, as the transformation can be changed by the system at any time.

getSpatialCapabilities

Added in 1.0.0-alpha04
public final @NonNull SpatialCapabilities getSpatialCapabilities()

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.

getSpatialEnvironment

Added in 1.0.0-alpha04
public final @NonNull SpatialEnvironment getSpatialEnvironment()

getSpatialUser

Added in 1.0.0-alpha04
public final @NonNull SpatialUser getSpatialUser()

The SpatialUser contains information about the user.

initialize

Added in 1.0.0-alpha04
public void initialize(
    @NonNull LifecycleManager lifecycleManager,
    @NonNull JxrPlatformAdapter platformAdapter
)

Initializes the SessionConnector.

removeSpatialCapabilitiesChangedListener

Added in 1.0.0-alpha04
public final void removeSpatialCapabilitiesChangedListener(
    @NonNull Consumer<@NonNull SpatialCapabilities> listener
)

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

setActivitySpace

Added in 1.0.0-alpha04
public final void setActivitySpace(@NonNull ActivitySpace activitySpace)

The ActivitySpace is a special entity that represents the space in which the application is launched. It is the default parent of all entities in the scene.

The ActivitySpace is created automatically when the Session is created.

setActivitySpaceRoot

Added in 1.0.0-alpha04
public final void setActivitySpaceRoot(@NonNull Entity activitySpaceRoot)

setFullSpaceMode

Added in 1.0.0-alpha04
public final @NonNull Bundle setFullSpaceMode(@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

Added in 1.0.0-alpha04
public final @NonNull Bundle setFullSpaceModeWithEnvironmentInherited(@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.

setMainPanelEntity

Added in 1.0.0-alpha04
public final void setMainPanelEntity(@NonNull PanelEntity mainPanelEntity)

A spatialized PanelEntity associated with the "main window" for the Activity. When in HomeSpace mode, this is the application's "main window".

If called multiple times, this will return the same PanelEntity.

setPerceptionSpace

Added in 1.0.0-alpha04
public final void setPerceptionSpace(@NonNull PerceptionSpace perceptionSpace)

The PerceptionSpace represents the origin of the space in which the ARCore for XR API provides tracking info. The transformations provided by the PerceptionSpace are only valid for the call frame, as the transformation can be changed by the system at any time.

setPreferredAspectRatio

Added in 1.0.0-alpha04
public final void setPreferredAspectRatio(@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.

setSpatialCapabilities

Added in 1.0.0-alpha04
public final void setSpatialCapabilities(@NonNull SpatialCapabilities spatialCapabilities)

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.

setSpatialEnvironment

Added in 1.0.0-alpha04
public final void setSpatialEnvironment(@NonNull SpatialEnvironment spatialEnvironment)

setSpatialUser

Added in 1.0.0-alpha04
public final void setSpatialUser(@NonNull SpatialUser spatialUser)

The SpatialUser contains information about the user.

setSpatialVisibilityChangedListener

Added in 1.0.0-alpha04
public final void setSpatialVisibilityChangedListener(
    @NonNull Consumer<@NonNull SpatialVisibility> listener
)

Sets the listener to be invoked on the main thread executor when the spatial visibility of the rendered content of the entire scene (all entities, including children of anchors and activitySpace) changes within the user's field of view.

This API only checks if the bounds of the renderable content are within the user's field of view. It does not check if the rendered content is visible to the user. For example, if the user is looking straight ahead, and there's only a single invisible child entity (alpha = 0) in front of the user, this API will return SpatialVisibility.WITHIN_FOV even though the user cannot see anything.

There can only be one listener set at a time. If a new listener is set, the previous listener will be released.

Parameters
@NonNull Consumer<@NonNull SpatialVisibility> listener

The Consumer to be invoked asynchronously on the main thread whenever the spatial visibility of the renderable content changes. The parameter passed to the Consumer’s accept method is the new value for SpatialVisibility.

setSpatialVisibilityChangedListener

Added in 1.0.0-alpha04
public final void setSpatialVisibilityChangedListener(
    @NonNull Executor callbackExecutor,
    @NonNull Consumer<@NonNull SpatialVisibility> listener
)

Sets the listener to be invoked when the spatial visibility of the rendered content of the entire scene (all entities, including children of anchors and activitySpace) changes within the user's field of view.

This API only checks if the bounds of the renderable content are within the user's field of view. It does not check if the rendered content is visible to the user. For example, if the user is looking straight ahead, and there's only a single invisible child entity (alpha = 0) in front of the user, this API will return SpatialVisibility.WITHIN_FOV even though the user cannot see anything.

The listener is invoked on the provided executor. If the app intends to modify the UI elements/views during the callback, the app should provide the thread executor that is appropriate for the UI operations. For example, if the app is using the main thread to render the UI, the app should provide the main thread (Looper.getMainLooper()) executor. If the app is using a separate thread to render the UI, the app should provide the executor for that thread.

There can only be one listener set at a time. If a new listener is set, the previous listener will be released.

Parameters
@NonNull Executor callbackExecutor

The executor to run the listener on.

@NonNull Consumer<@NonNull SpatialVisibility> listener

The Consumer to be invoked asynchronously on the given callbackExecutor whenever the spatial visibility of the renderable content changes. The parameter passed to the Consumer’s accept method is the new value for SpatialVisibility.