{ } { }

Jetpack SceneCore

Build and manipulate the Android XR scene graph with 3D content.
Latest Update Stable Release Release Candidate Beta Release Alpha Release
February 12, 2025 - - - 1.0.0-alpha02

Declaring dependencies

To add a dependency on XR SceneCore, you must add the Google Maven repository to your project. Read Google's Maven repository for more information.

Add the dependencies for the artifacts you need in the build.gradle file for your app or module:

Groovy

dependencies {
    implementation "androidx.xr.scenecore:scenecore:1.0.0-alpha02"
    // Required for Java
    implementation "com.google.guava:listenablefuture:1.0"
    // Required for Kotlin
    implementation "org.jetbrains.kotlinx:kotlinx-coroutines-guava:1.9.0"

    // Use to write unit tests
    testImplementation "androidx.xr.scenecore:scenecore-testing:1.0.0-alpha02"
}

Kotlin

dependencies {
    implementation("androidx.xr.scenecore:scenecore:1.0.0-alpha02")
    // Required for Java
    implementation("com.google.guava:listenablefuture:1.0")
    // Required for Kotlin
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-guava:1.9.0")

    // Use to write unit tests
    testImplementation("androidx.xr.scenecore:scenecore-testing:1.0.0-alpha02")
}

For more information about dependencies, see Add build dependencies.

Feedback

Your feedback helps make Jetpack better. Let us know if you discover new issues or have ideas for improving this library. Please take a look at the existing issues in this library before you create a new one. You can add your vote to an existing issue by clicking the star button.

Create a new issue

See the Issue Tracker documentation for more information.

Version 1.0

Version 1.0.0-alpha02

February 12, 2025

androidx.xr.scenecore:scenecore:1.0.0-alpha02 and androidx.xr.scenecore:scenecore-testing:1.0.0-alpha02 are released. Version 1.0.0-alpha02 contains these commits.

Upcoming breaking change affecting apps built before 1.0.0-alpha02

  • Factory methods have been moved from the Session class to a companion method on each respective type:
    • Session.createActivityPanelEntity(Dimensions, String, Activity, Pose) has been deleted and replaced with ActivityPanelEntity.create(Session, Dimensions, String, Pose)
    • Session.createAnchorEntity(Anchor) has been deleted and replaced with AnchorEntity.create(Session, Anchor)
    • Session.createAnchorEntity(Dimensions, Int, Int, Duration) has been deleted and replaced with AnchorEntity.create(Session, Dimensions, Int, Int, Duration)
    • Session.createEntity(String, Pose) has been deleted and replaced with ContentlessEntity.create(Session, String, Pose)
    • Session.createExrImageResource(String) has been deleted and replaced with ExrImage.create(Session, String)
    • Session.createGltfEntity(GltfModel, Pose) has been deleted and replaced with GltfModelEntity.create(Session, GltfModel, Pose)
    • Session.createGltfModelResource(String) has been deleted and replaced with GltfModel.create(Session, String)
    • Session.createInteractableComponent(Executor, InputEventListener) has been deleted and replaced with InteractableComponent.create(Session, Executor, InputEventListener)
    • Session.createMovableComponent(Boolean, Boolean, Set<AnchorPlacement>, Boolean) has been deleted and replaced with MovableComponent.create(Session, Boolean, Boolean, Set<AnchorPlacement>, Boolean)
    • Session.createPanelEntity(View, Dimensions, Dimensions, String, Pose) has been deleted and replaced with PanelEntity.create(Session, View, Dimensions, Dimensions, String, Pose)
    • Session.createResizableComponent(Dimensions, Dimensions) has been deleted and replaced with ResizableComponent.create(Session, Dimensions, Dimensions)
    • Session.createStereoSurfaceEntity(Int, Dimensions, Pose) has been deleted and replaced with StereoSurface.create(Session, Int, Dimensions, Pose)
  • The following deprecated methods were removed:
    • Session.canEmbedActivityPanel(Activity) has been deleted. Use getSpatialCapabilities.hasCapabilility(SPATIAL_CAPABILITY_EMBED_ACTIVITY) instead.
    • Session.hasSpatialCapability(Int) has been deleted. It has been replaced in favor of using getSpatialCapabilities().hasCapability() as a more compartmentalized way to check for the presence of spatial capabilities since getSpatialCapabilities() returns a SpatialCapabilities object.
    • Session.requestFullSpaceMode() has been deleted and replaced with SpatialEnvironment.requestFullSpaceMode()
    • Session.requestHomeSpaceMode() has been deleted and replaced with SpatialEnvironment.requestHomeSpaceMode()
  • Session.setFullSpaceMode(Bundle) and Session.setFullSpaceModeWithEnvironmentInherited(Bundle) have been moved to extension functions. Developer files will need to add the new imports for access:
    • import androidx.xr.scenecore.setFullSpaceMode
    • import androidx.xr.scenecore.setFullSpaceModeWithEnvironmentInherited
  • Session.setPreferredAspectRatio(Activity, Float) has been moved to an extension function. Developer files will need to add the new import for access:
    • import androidx.xr.scenecore.setPreferredAspectRatio
  • Session.getEntitiesOfType(Class<out T>) and Session.getEntityForRtEntity(RtEntity) have been moved to extension functions. Developer files will need to add the new imports for access:
    • import androidx.xr.scenecore.getEntitiesOfType
    • import androidx.xr.scenecore.getEntityForRtEntity
  • Session.unpersistAnchor(Anchor) has been deleted
  • Session.createPersistedAnchorEntity(UUID) has been deleted

Known issues

  • PanelEntity.setCornerRadius() and ActivityPanelEntity.setCornerRadius() may not take effect until the panel is next moved, this can be mitigated by moving the panel to its current position
  • When BoundsChanged is called on the ActivitySpace, some ActivityPoses may not have been correctly updated. It will be updated on the following OnSpaceUpdated call on the ActivitySpace

Breaking & behavioral changes

  • PanelEntity and ActivityPanelEntity will have a default corner radius of 32dp or smaller if the panel has a width or height smaller than 32dp

New APIs and capabilities

  • Introduces StereoSurface.CanvasShape, which allows for the creation of Spherical and Hemispherical canvases for rendering immersive media.
  • StereoSurfaceEntity.create() now accepts a CanvasShape parameter. (This parameter is currently ignored, but will be used in a future release)
  • StereoSurfaceEntity.create() no longer takes a Dimensions parameter. Applications should control the size of the canvas through setting the CanvasShape
  • StereoSurfaceEntity has a CanvasShape member which can be set dynamically.
  • StereoSurfaceEntity.dimensions is now a read-only property; applications should set the CanvasShape to change dimensions.
  • StereoSurfaceEntity now allows the StereoMode to be re-set after construction.

Other changes

  • Reduced compile-time minSDK to 24. All Jetpack XR APIs continue to require API 34 at runtime.
  • SceneCore's Session factory (Session.create) no longer launches an intent to acquire the SCENE_UNDERSTANDING permission. Instead, the client application must explicitly request the permissions from the user, before attempting to create the anchors. Anchor creation will fail if the permission is not granted by the user.

Bug fixes

  • getActivitySpacePose() has been fixed to account for the ActivitySpace scale by returning translation values in scaled meters rather than always returning non-scaled meters. transformPoseTo now also uses the right units to compute coordinate changes when the ActivitySpace is involved in the source or destination.
  • The skybox will now be set to an all-black skybox whenever a null skybox preference is passed using setSpatialEnvironmentPreference(new SpatialEnvironmentPreference(null, geom)). To revert to the system default skybox and geometry, use setSpatialEnvironmentPreference(null).

Version 1.0.0-alpha01

December 12, 2024

androidx.xr.scenecore:scenecore-* 1.0.0-alpha01 is released.

Features of Initial Release Initial developer release of Jetpack SceneCore, a 3D scene graph library for creating and manipulating immersive scenes and environments. This library allows you to place and arrange 3D models and content panels relative to each other and your virtual or real-world environments.

  • SpatialEnvironment: Create fully immersive experiences with a skybox image and/or 3D model geometry as the backdrop for your XR scene of your environment. Or enable passthrough, so your virtual scene can integrate with the user’s real-world environment.
  • PanelEntity: Add 2D content to your 3D scenes by embedding standard Android layouts and Activities into spatialized panels that can float or be anchored to real-world surfaces.
  • GltfModelEntity: Place, animate, and interact with 3D models in your scene. SceneCore supports the glTF file format for ease of integration with existing models.
  • SpatialAudio: Add ambient and point audio sources into your 3D scene for fully immersive, spatialized sound.
  • StereoSurfaceEntity: SceneCore supports left/right eye routing of content rendered onto an Android Surface. This can be used to render stereoscopic content in a side-by-side or top-bottom format, such as stereo photos, 3D video, or other dynamically rendered UIs. Applications should use MediaPlayer or ExoPlayer for video decoding.
  • Component System: SceneCore offers a robust and flexible component system for adding capabilities to your XR content, including affordances for users to move, resize, and interact with models and panels.
  • Anchor: With passthrough enabled, you can attach panels and models to actual surfaces, giving users seamless integration of virtual content in their real-world environment.
  • User Pose: Access the user’s location in the virtual scene, to orient your content around the user’s position.
  • SpatialCapabilities: Build fully adaptive apps that take advantage of spatialized capabilities when available, such as 3D positioning of UI content. Not only that, but your app can monitor for changes to capabilities while the app is executing, to modify the experience based on how the user is using their Android XR device.

Known Issues

  • Currently a minSDK of 30 is required to use Jetpack SceneCore. As a workaround add the following manifest entry <uses-sdk tools:overrideLibrary="androidx.xr.scenecore, androidx.xr.compose"/> to be able to build and run with a minSDK of 23.
  • Session can become invalid in various situations that automatically recreate the Activity, including resizing a main panel, connecting peripherals, and changing between light and dark mode. If you encounter session invalidation issues, workarounds include making you main panel non-resizable, using a dynamic panel entity, disabling activity recreation for specific config changes or disabling light/dark mode theme changes.
  • Movable and Resizable components are not supported on GltfEntity.
  • Entity.getSize() is not supported on GltfEntity.
  • Jetpack XR apps required to request android.permission.SCENE_UNDERSTANDING permission in AndroidManifest.
  • Creating a session is only supported on an Android XR device. At this time, if you create a Session and try to use it on a non Android XR device, you'll get a RuntimeException.
  • Setting the skybox to null via `SpatialEnvironment.setSpatialEnvironmentPreference() does not result in a solid black skybox as documented. It may result in the system default skybox or no change to the current skybox.
  • SceneCore clients should add implementation(“com.google.guava:listenablefuture-1.0”) to their Gradle configuration for their app’s dependencies. In a future release, scenecore will include this library as an api dependency so clients will not need to explicitly declare it.
  • SceneCore erroneously includes com.google.guava:guava-31.1-android and com.google.protobuf:protobuf-javalite as transitive dependencies. If this results in duplicate class errors in your build, these two dependencies can be safely excluded.
  • If your app uses SceneCore and enables ProGuard, it will crash when you create a Session. As a workaround, disable ProGuard. See this guide for more information on how to enable ProGuard.