Add 3D models to your app

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 an 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 simple, 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.

There are two primary ways for apps built with the Jetpack XR SDK to load 3D models.

Place a 3D model into the ActivitySpace

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

To load the glTF model, call createGltfResourceAsync.

// load the gltf file
val gltfModel = xrSession.createGltfResourceAsync("models/saturn_rings.glb").await()

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.

We need to add the glTF into the ActivitySpace. Call createGltfEntity 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.

// check for spatial capabilities
if (xrSession.getSpatialCapabilities().hasCapability(SpatialCapabilities.SPATIAL_CAPABILITY_3D_CONTENT)){
  // create the gltf entity using the gltf file from the previous snippet
   val gltfEntity = xrSession.createGltfEntity(gltfModel)
}

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

Example of the loaded 3d model

Place a 3D model into a Compose Volume

While you will still need to load the glTF into memory using createGltfResourceAsync, you can place 3D models into a Volume if you are creating your UI with Jetpack Compose for XR. Refer to Use a Volume to place a 3D object in your layout.

Animate 3D models

As part of the glTF specification, 3D models can have animations embedded. Skeletal (rigged), rigid, morph target (blend shapes) animations are all supported in the Jetpack XR SDK. Material animations created with the KHR_animation_pointer glTF extension are also supported.

To play an animation, call startAnimation and specify the name of the animation. You can optionally specify whether or not the animation should loop indefinitely.

//start a looping walk animation for a model
gltfEntity.startAnimation(loop = true, animationName = "Walk")

Calling startAnimation a second time, the current animation will stop and the new animation will start.

You can query the current state of the animation through getAnimationState().

If the animation name specified when calling startAnimation() doesn't exist, the call silently fails, any running animations stop, and getAnimationState() returns STOPPED.

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 via 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 THREED_MODEL_URL = "https://raw.githubusercontent.com/KhronosGroup/glTF-Sample-Models/master/2.0/FlightHelmet/glTF/FlightHelmet.gltf"
val MIME_TYPE = "model/gltf-binary"
val sceneViewerIntent = Intent(Intent.ACTION_VIEW)
val intentUri =
  Uri.parse("https://arvr.google.com/scene-viewer/1.2")
     .buildUpon()
     .appendQueryParameter("file", THREED_MODEL_URL)
     .build()
sceneViewerIntent.setDataAndType(intentUri, MIME_TYPE)
startActivity(sceneViewerIntent)

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 GltfEntity and Scene Viewer.