Scene

fun addSpatialCapabilitiesChangedListener(
    listener: Consumer<Set<SpatialCapability>>
): Unit

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

fun addSpatialCapabilitiesChangedListener(
    callbackExecutor: Executor,
    listener: Consumer<Set<SpatialCapability>>
): Unit

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

fun addSpatialVisibilityChangedListener(
    listener: Consumer<SpatialVisibility>
): Unit

Adds a 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 AnchorSpaces 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.

fun addSpatialVisibilityChangedListener(
    callbackExecutor: Executor,
    listener: Consumer<SpatialVisibility>
): Unit

Adds a listener to be invoked when the spatial visibility of the rendered content of the entire scene (all entities, including children of AnchorSpaces 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.

fun clearSpaceChangedListener(): Unit

Releases the listener previously set by setSpaceChangedListener 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.

fun <T : Entity> getEntitiesOfType(type: Class<T>): List<T>

Returns all entities of the given type or its subtypes.

fun removeSpatialCapabilitiesChangedListener(
    listener: Consumer<Set<SpatialCapability>>
): Unit

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.

fun removeSpatialVisibilityChangedListener(
    listener: Consumer<SpatialVisibility>
): Unit

Releases the listener previously added by addSpatialVisibilityChangedListener.

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

fun requestFullSpace(): Unit

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

fun requestHomeSpace(): Unit

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

fun setSpaceChangedListener(listener: Consumer<SpaceChangeEvent>): Unit

Sets the listener to be invoked on the main thread executor when the space for the Scene has changed, such as from Home Space to Full Space.

Because the listener will typically update the keyEntity's pose and/or scale, there can only be one listener set at a time. If a new listener is set, the previous listener will be released.

fun setSpaceChangedListener(
    callbackExecutor: Executor,
    listener: Consumer<SpaceChangeEvent>
): Unit

Sets the listener to be invoked when the space has changed, such as from Home Space to Full Space.

The listener is invoked on the provided Executor.

Because the listener will typically update the keyEntity's pose and/or scale, there can only be one listener set at a time. If a new listener is set, the previous listener will be released.

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

var keyEntity: Entity?

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

This entity is used to maintain visual continuity during spatial mode transitions. When entering Full Space Mode or re-centering the scene, the system provides a recommended pose and scale. SceneCore's default mode change handler applies those to the entity designated as keyEntity to help preserve the user's spatial context across these mode transitions.

Starting with Spatial API v2, setting keyEntity allows SceneCore to share the entity's pose with the system as a spatial continuity hint. The system uses this hint to maintain visual consistency when the current activity transitions to the Home Space or when a new activity is launched.

Spaces, such as AnchorSpace or ActivitySpace, cannot be set as the Scene.keyEntity and will throw IllegalArgumentException if set.

By default, this is set to mainPanelEntity. This field can be null if the key entity was cleared by setting this value to null. When null, the default listener takes no action during spatial mode changes.

When a new non-null Entity is assigned as keyEntity, the spaceChangedListener is immediately invoked with the last known recommended pose and scale values if the following conditions are met:

1. The previous value of keyEntity was null.

2. There are cached pose and scale values, provided by the system earlier.

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

var panelClippingConfig: PanelClippingConfig

The current clipping configuration of all panels in the Scene.

Setting this property updates the clipping behavior.

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

lateinit val spatialCapabilities: Set<SpatialCapability>

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.

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

val virtualPixelDensity: PixelDensity

Provides access to the PixelDensity standards for this scene.

This specific density represents the default number of virtual pixels that correspond to one physical meter in ActivitySpace.

Since the spatial coordinate system is emulated, these pixels represent content units (texture resolution) used to define entities such as PanelEntity, rather than physical display pixels.

It is a static hardware constant and ignores user-level display preference overrides (system density changes).