Add 3D models to your app

Applicable XR devices
This guidance helps you build experiences for these types of XR devices.
Learn about XR device types →
XR Headsets
Wired XR Glasses
Learn about XR device types →

When working with 3D models, the Jetpack XR SDK supports the glTF 2.0 open standard. When Android XR renders apps built with the Jetpack XR SDK, 3D models will be rendered with physically based rendering(PBR) techniques specified in the glTF 2.0 standard (along with supported extensions). Most digital content creation (dcc) tools, such as Autodesk Maya, Maxon ZBrush, Blender and Spline can export 3D models into the glTF format (.gltf or .glb files).

If a SpatialEnvironment skybox has been specified by the user or by your app, 3D models will be lit with lighting information provided by the environment skybox. Reflective materials and specular highlights will also reflect the environment skybox. If passthrough has been enabled, then the lighting, reflections and specular highlights will be based on a bright room with a single directional light.

For a quick overview of the supported materials, refer to the glTF PBR Properties on the Khronos site. To learn how to customize your 3D models with these properties and others, see Customize 3D models in your app

Add a glTF file to your assets folder

Once you have your glTF file, the next step is to add it to the assets directory in Android Studio. We recommend creating a models directory to better organize your asset types.

Example of adding assets to the /models directory

Add a 3D object using SpatialGltfModel

Android XR supports the glTF format for 3D models, typically saved as .glb files. To add these objects to your layout, use the SpatialGltfModel composable. This API simplifies the process of loading assets and managing their state.

To display a model, first define its source and state using rememberSpatialGltfModelState. You can load models from your app's assets folder, a URI, or raw data.

val modelState = rememberSpatialGltfModelState(
    source = SpatialGltfModelSource.fromPath(
        Paths.get("models/model_name.glb")
    )
)

Once the state is defined, use the SpatialGltfModel composable to render it within a subspace.

SpatialGltfModel(state = modelState, modifier = SubspaceModifier)

Place a 3D model using a Compose SceneCoreEntity

To place a 3D model using SceneCoreEntity, you first need to load the glTF into memory using GltfModel.create(). You can then place a 3D model into a SceneCoreEntity to bridge SceneCore components with Compose for XR layouts. Refer to Use a SceneCoreEntity to place a 3D object in your layout.

Place a 3D model using Jetpack Scenecore

To load the glTF model, call GltfModel.create().

val gltfModel = GltfModel.create(session, Paths.get("models", "saturn_rings.glb"))

At this point, the model is loaded into memory, but it's not being rendered yet. If you have many 3D models to load or your model is large, it's a good idea to load them asynchronously ahead of time. This way, users don't have to wait for your models to be loaded into memory.

Add the glTF to the ActivitySpace. Call GltfModelEntity.create to create an entity and place it into the ActivitySpace. As best practice, you should check that the app is in a state which allows for spatial capabilities.

if (session.scene.spatialCapabilities.contains(SpatialCapability.SPATIAL_3D_CONTENT)) {
    val gltfEntity = GltfModelEntity.create(session, gltfModel)
}

You should now see the loaded 3D model when you run your app.

Example of the loaded 3d model

Load a 3D model using Scene Viewer

If you're looking for the simplest way to load a 3D model with basic interaction capabilities, you may opt to use Scene Viewer as you would on mobile. A key difference between the Scene Viewer on Android XR and on mobile is that Scene Viewer only supports the file URI parameter pointing to the glTF file and all other parameters are ignored.

Scene Viewer is a separate app that is invoked using an intent and runs in Full Space Mode. As a result, when you invoke it, your app will no longer be visible and Scene Viewer will have focus. Any environments you may have changed will be reset to the user's system preferences.

Here's an example of using an Intent to view a glTF file in Scene Viewer on Android XR:

val url =
    "https://raw.githubusercontent.com/KhronosGroup/glTF-Sample-Models/master/2.0/Avocado/glTF/Avocado.gltf"
val sceneViewerIntent = Intent(Intent.ACTION_VIEW)
val intentUri =
    Uri.parse("https://arvr.google.com/scene-viewer/1.2")
        .buildUpon()
        .appendQueryParameter("file", url)
        .build()
sceneViewerIntent.setData(intentUri)
try {
    startActivity(sceneViewerIntent)
} catch (e: ActivityNotFoundException) {
    // There is no activity that could handle the intent.
}

For more information on the interactivity options for Scene Viewer, refer to our 3D model design documentation.

glTF extensions

Jetpack XR SDK supports several gfTF extensions that expand the capabilities of 3D models. These capabilities are available through both the GltfModelEntity and Scene Viewer.