Scene

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 androidx.xr.runtime.Session is created.

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.

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.

public final lateinit @NonNull Set<@NonNull SpatialCapability> spatialCapabilities

The current Set of SpatialCapability constants available in the Session. The set may 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, or clients can subscribe to changes with addSpatialCapabilitiesChangedListener.

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.

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.

public final void addSpatialCapabilitiesChangedListener(
    @NonNull Consumer<@NonNull Set<@NonNull SpatialCapability>> listener
)

Adds the given Consumer as a listener to be invoked when this androidx.xr.runtime.Session's spatial capabilities change.

public final void addSpatialCapabilitiesChangedListener(
    @NonNull Executor callbackExecutor,
    @NonNull Consumer<@NonNull Set<@NonNull SpatialCapability>> listener
)

Adds the given Consumer as a listener to be invoked when this androidx.xr.runtime.Session's spatial capabilities change.

public final void clearSpatialModeChangedListener()

Releases the listener previously set by setSpatialModeChangedListener and reinstates the default behavior of automatically updating the keyEntity's pose and scale on the main thread executor.

The listener is automatically released at the end of the Scene's lifecycle even if this method is not explicitly called.

public final void clearSpatialVisibilityChangedListener()

Releases the listener previously added by setSpatialVisibilityChangedListener.

The listener is automatically released at the end of the Scene's lifecycle even if this method is not explicitly called.

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 androidx.xr.runtime.Session is created.

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.

public final Entity getKeyEntity()

The primary Entity that acts as a spatial reference for the scene's content.

The default behavior on a spatial mode change uses this Entity to maintain a consistent spatial context for the user. When the scene enters Full Space Mode or is re-centered, the system provides a recommended pose and scale. This ensures continuity of the user's attention across spatial mode changes such as during transitions into Full Space Mode.

Unmovable Entities, such as AnchorEntity or ActivitySpace, cannot be set as the Scene.keyEntity and will throw IllegalArgumentException if set.

This field can be null if no key entity has been set (default), or if the key entity was cleared by setting this value to null. When null, the default listener takes no action during spatial mode changes.

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.

public final @NonNull PanelClippingConfig getPanelClippingConfig()

The current clipping configuration of all panels in the Scene.

Setting this property updates the clipping behavior.

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.

public final @NonNull Set<@NonNull SpatialCapability> getSpatialCapabilities()

The current Set of SpatialCapability constants available in the Session. The set may 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, or clients can subscribe to changes with addSpatialCapabilitiesChangedListener.

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.

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.

public final void removeSpatialCapabilitiesChangedListener(
    @NonNull Consumer<@NonNull Set<@NonNull SpatialCapability>> listener
)

Releases the given Consumer from receiving updates when the androidx.xr.runtime.Session's SpatialCapability change.

The listeners are automatically released at the end of the Scene's lifecycle even if this method is not explicitly called.

public final void requestFullSpaceMode()

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

public final void requestHomeSpaceMode()

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

public final void setKeyEntity(Entity keyEntity)

The primary Entity that acts as a spatial reference for the scene's content.

The default behavior on a spatial mode change uses this Entity to maintain a consistent spatial context for the user. When the scene enters Full Space Mode or is re-centered, the system provides a recommended pose and scale. This ensures continuity of the user's attention across spatial mode changes such as during transitions into Full Space Mode.

Unmovable Entities, such as AnchorEntity or ActivitySpace, cannot be set as the Scene.keyEntity and will throw IllegalArgumentException if set.

This field can be null if no key entity has been set (default), or if the key entity was cleared by setting this value to null. When null, the default listener takes no action during spatial mode changes.

public final void setPanelClippingConfig(@NonNull PanelClippingConfig panelClippingConfig)

The current clipping configuration of all panels in the Scene.

Setting this property updates the clipping behavior.

public final void setSpatialModeChangedListener(
    @NonNull Consumer<@NonNull SpatialModeChangeEvent> listener
)

Sets the listener to be invoked on the main thread executor when the spatial mode for the scene has changed.

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

public final void setSpatialModeChangedListener(
    @NonNull Executor callbackExecutor,
    @NonNull Consumer<@NonNull SpatialModeChangeEvent> listener
)

Sets the listener to be invoked when the spatial mode for the scene has changed.

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.

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

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