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 MainPanelEntity

A spatialized MainPanelEntity associated with the "main window" for the Activity.
final lateinit @NonNull PerceptionSpace

The PerceptionSpace represents the origin of the space in which ARCore for Jetpack XR provides tracking info.
final lateinit @NonNull SpatialEnvironment

The SpatialEnvironment for this scene.
final lateinit @NonNull SpatialUser

The SpatialUser represents the user within the XR scene, providing access to tracking information for the user's head and eyes.

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.
final @NonNull Bundle

Configures a Bundle to request that a new Activity be launched directly into Full Space Mode.
final @NonNull Bundle

Configures a Bundle to request that a new Activity be launched directly into Full Space Mode while inheriting the environment from the launching activity.
final @NonNull List<@NonNull T>
<T extends Entity> getEntitiesOfType(@NonNull Class<@NonNull T> type)

Returns all entities of the given type or its subtypes.
final @NonNull MainPanelEntity

A spatialized MainPanelEntity associated with the "main window" for the Activity.
final @NonNull PanelClippingConfig

The current clipping configuration of all panels in the Scene.
final @NonNull PerceptionSpace

The PerceptionSpace represents the origin of the space in which ARCore for Jetpack XR provides tracking info.
final @NonNull SpatialCapabilities

Returns the current SpatialCapabilities of the Session.
final @NonNull SpatialEnvironment

The SpatialEnvironment for this scene.
final @NonNull SpatialUser

The SpatialUser represents the user within the XR scene, providing access to tracking information for the user's head and eyes.
final void

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

If the Activity has focus, causes the Activity to be placed in Full Space Mode.
final void

If the Activity has focus, causes the Activity to be placed in Home Space Mode.
final void

The current clipping configuration of all panels in the Scene.
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 AnchorEntitys and ActivitySpace) changes within the user's field of view.
final void
setSpatialVisibilityChangedListener(
    @NonNull Executor callbackExecutor,
    @NonNull Consumer<@NonNull Integer> listener
)

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

Public fields

mainPanelEntity

Added in 1.0.0-alpha05
public final lateinit @NonNull MainPanelEntity mainPanelEntity

A spatialized MainPanelEntity associated with the "main window" for the Activity. When in Home Space Mode, this is the application's "main window".

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

perceptionSpace

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

The PerceptionSpace represents the origin of the space in which ARCore for Jetpack XR 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.

spatialEnvironment

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

The SpatialEnvironment for this scene.

This object provides APIs to manage the XR background and passthrough settings. Use it to set a custom skybox, define the 3D geometry of the environment, and control the opacity of the camera passthrough feed.

See also
SpatialEnvironment

spatialUser

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

The SpatialUser represents the user within the XR scene, providing access to tracking information for the user's head and eyes.

Use it to get the following:

  • Head Pose: Access SpatialUser.head to get the position and orientation of the user's head in the scene.

  • Camera Views: Access SpatialUser.cameraViews to get the pose and field of view for each of the user's camera views.

Note: Accessing properties on SpatialUser requires head tracking to be enabled in the session androidx.xr.runtime.Session.config.

See also
SpatialUser
Head
CameraView

Public constructors

Scene

Added in 1.0.0-alpha05
public Scene()

Public methods

addSpatialCapabilitiesChangedListener

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

Parameters
@NonNull Consumer<@NonNull SpatialCapabilities> listener

The Consumer to be invoked asynchronously on the main thread executor whenever the SpatialCapabilities changes.

addSpatialCapabilitiesChangedListener

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

Parameters
@NonNull Executor callbackExecutor

The Executor to run the listener on.
@NonNull Consumer<@NonNull SpatialCapabilities> listener

The Consumer to be invoked asynchronously on the given callbackExecutor whenever the SpatialCapabilities changes.

clearSpatialVisibilityChangedListener

Added in 1.0.0-alpha05
public final void clearSpatialVisibilityChangedListener()

Releases the listener previously added by setSpatialVisibilityChangedListener.

configureBundleForFullSpaceModeLaunch

Added in 1.0.0-alpha05
public final @NonNull Bundle configureBundleForFullSpaceModeLaunch(@NonNull Bundle bundle)

Configures a Bundle to request that a new Activity be launched directly into Full Space Mode.

The configured bundle can be used to launch an Activity directly into Full Space Mode through Activity.startActivity. If there's a bundle used for customizing how the 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 androidx.xr.runtime.manifest.PROPERTY_XR_ACTIVITY_START_MODE property is set to a value other than androidx.xr.runtime.manifest.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.

configureBundleForFullSpaceModeLaunchWithEnvironmentInherited

Added in 1.0.0-alpha05
public final @NonNull Bundle configureBundleForFullSpaceModeLaunchWithEnvironmentInherited(
    @NonNull Bundle bundle
)

Configures a Bundle to request that a new Activity be launched directly into Full Space Mode while inheriting the environment from the launching activity.

The configured bundle can be used to launch an Activity directly into Full Space Mode while inherit the existing environment through Activity.startActivity. If there's a bundle used for customizing how the 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 will inherit 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 when the activity has its own environment set already.

This flag is also ignored when the androidx.xr.runtime.manifest.PROPERTY_XR_ACTIVITY_START_MODE property is set to a value other than androidx.xr.runtime.manifest.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 configure with the inherit Full Space Mode environment flag.
Returns
@NonNull Bundle

the input bundle with the inherit Full Space Mode flag set.

getEntitiesOfType

Added in 1.0.0-alpha05
public final @NonNull List<@NonNull T> <T extends Entity> getEntitiesOfType(@NonNull Class<@NonNull T> type)

Returns all entities 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 entities of the given type.

getMainPanelEntity

Added in 1.0.0-alpha05
public final @NonNull MainPanelEntity getMainPanelEntity()

A spatialized MainPanelEntity associated with the "main window" for the Activity. When in Home Space Mode, this is the application's "main window".

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

getPanelClippingConfig

Added in 1.0.0-alpha05
public final @NonNull PanelClippingConfig getPanelClippingConfig()

The current clipping configuration of all panels in the Scene.

Setting this property updates the clipping behavior.

See also
PanelClippingConfig

getPerceptionSpace

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

The PerceptionSpace represents the origin of the space in which ARCore for Jetpack XR 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-alpha05
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-alpha05
public final @NonNull SpatialEnvironment getSpatialEnvironment()

The SpatialEnvironment for this scene.

This object provides APIs to manage the XR background and passthrough settings. Use it to set a custom skybox, define the 3D geometry of the environment, and control the opacity of the camera passthrough feed.

See also
SpatialEnvironment

getSpatialUser

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

The SpatialUser represents the user within the XR scene, providing access to tracking information for the user's head and eyes.

Use it to get the following:

  • Head Pose: Access SpatialUser.head to get the position and orientation of the user's head in the scene.

  • Camera Views: Access SpatialUser.cameraViews to get the pose and field of view for each of the user's camera views.

Note: Accessing properties on SpatialUser requires head tracking to be enabled in the session androidx.xr.runtime.Session.config.

See also
SpatialUser
Head
CameraView

removeSpatialCapabilitiesChangedListener

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

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

Parameters
@NonNull Consumer<@NonNull SpatialCapabilities> listener

The Consumer to be removed. It will no longer receive change events.

requestFullSpaceMode

Added in 1.0.0-alpha05
public final void requestFullSpaceMode()

If the Activity has focus, causes the Activity to be placed in Full Space Mode. Otherwise, this call does nothing.

requestHomeSpaceMode

Added in 1.0.0-alpha05
public final void requestHomeSpaceMode()

If the Activity has focus, causes the Activity to be placed in Home Space Mode. Otherwise, this call does nothing.

setPanelClippingConfig

Added in 1.0.0-alpha05
public final void setPanelClippingConfig(@NonNull PanelClippingConfig panelClippingConfig)

The current clipping configuration of all panels in the Scene.

Setting this property updates the clipping behavior.

See also
PanelClippingConfig

setSpatialVisibilityChangedListener

Added in 1.0.0-alpha05
public final void setSpatialVisibilityChangedListener(
    @NonNull Consumer<@NonNull Integer> 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 AnchorEntitys and ActivitySpace) changes within the user's field of view. In Home Space Mode, the listener continues to monitor the spatial visibility of the application's main panel.

This API only checks if the bounding box of all rendered content (even if partially transparent) is within the user's field of view. Content not rendered due to full transparency (alpha=0) or being hidden is not considered. If the entities in the scene or any of their ancestors are hidden using Entity.setEnabled (enabled=false) or if the entities are turned fully transparent using Entity.setAlpha (alpha=0.0), then the SpatialVisibility checks will return SpatialVisibility.SPATIAL_VISIBILITY_OUTSIDE_FIELD_OF_VIEW.

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 Integer> listener

The Consumer to be invoked asynchronously on the main thread whenever the SpatialVisibility of the renderable content changes.

setSpatialVisibilityChangedListener

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

Sets the listener to be invoked when the spatial visibility of the rendered content of the entire scene (all entities, including children of AnchorEntitys and ActivitySpace) changes within the user's field of view. In Home Space Mode, the listener continues to monitor the spatial visibility of the application's main panel.

This API only checks if the bounding box of all rendered content (even if partially transparent) is within the user's field of view. Content not rendered due to full transparency (alpha=0) or being hidden is not considered. If the entities in the scene or any of their ancestors are hidden using Entity.setEnabled (enabled=false) or if the entities are turned fully transparent using Entity.setAlpha (alpha=0.0), then the SpatialVisibility checks will return SpatialVisibility.SPATIAL_VISIBILITY_OUTSIDE_FIELD_OF_VIEW.

The listener is invoked on the provided Executor.

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 Integer> listener

The Consumer to be invoked asynchronously on the given callbackExecutor whenever the SpatialVisibility of the renderable content changes.