将 3D 模型添加到您的应用

在使用 3D 模型时，Jetpack XR SDK 支持 glTF 2.0 开放标准。当 Android XR 渲染使用 Jetpack XR SDK 构建的应用时，3D 模型将使用 glTF 2.0 标准中指定的基于物理的渲染 (PBR) 技术（以及支持的扩展）进行渲染。大多数数字内容创作 (DCC) 工具，例如 Autodesk Maya、Maxon ZBrush、Blender 和 Spline 都可以将 3D 模型导出为 glTF 格式（.gltf 或 .glb 文件）。

如果用户或您的应用指定了 SpatialEnvironment 天空盒，3D 模型将根据环境天空盒提供的照明信息进行光照。反射材质和镜面高光也将反映环境天空盒。如果已启用直通，则光照、反射和镜面高光将基于带有单个定向光的简单明亮房间。

有关支持材质的快速概览，请参阅 Khronos 网站上的 glTF PBR 属性。

使用 Jetpack XR SDK 构建的应用加载 3D 模型主要有两种方式。

将 3D 模型放入 ActivitySpace

获取 glTF 文件后，下一步是将其添加到 Android Studio 中的资产目录。我们建议创建一个 models 目录，以便更好地组织您的资产类型。

Example of adding assets to the /models directory

要加载 glTF 模型，请调用 GltfModel.create()。

val gltfModel = GltfModel.create(session, "models/saturn_rings.glb").await()
GltfEntity.kt

此时，模型已加载到内存中，但尚未渲染。如果您要加载许多 3D 模型或模型较大，最好提前异步加载它们。这样，用户就不必等待您的模型加载到内存中。

我们需要将 glTF 添加到 ActivitySpace 中。调用 GltfModelEntity.create 来创建一个实体并将其放置到 ActivitySpace 中。作为最佳实践，您应该检查应用是否处于允许空间能力的状态。

if (session.scene.spatialCapabilities
    .hasCapability(SpatialCapabilities.SPATIAL_CAPABILITY_3D_CONTENT)
) {
    val gltfEntity = GltfModelEntity.create(session, gltfModel)
}
GltfEntity.kt

现在，当您运行应用时，应该会看到加载的 3D 模型。

Example of the loaded 3d model

将 3D 模型放入 Compose Volume

虽然您仍然需要使用 GltfModel.create() 将 glTF 加载到内存中，但如果您正在使用 Jetpack Compose for XR 创建 UI，则可以将 3D 模型放入 Volume 中。请参阅使用 Volume 将 3D 对象放入布局中。

3D 模型动画

作为 glTF 规范的一部分，3D 模型可以嵌入动画。Jetpack XR SDK 支持骨骼（绑定）、刚体、变形目标（混合形状）动画。使用 KHR_animation_pointer glTF 扩展创建的材质动画也受支持。

要播放动画，请调用 startAnimation() 并指定动画名称。您可以选择性地指定动画是否应无限循环。

gltfEntity.startAnimation(loop = true, animationName = "Walk")
GltfEntity.kt

第二次调用 startAnimation 时，当前动画将停止，新动画将开始。

您可以通过 getAnimationState() 查询动画的当前状态。

如果在调用 startAnimation() 时指定的动画名称不存在，则调用会静默失败，任何正在运行的动画都会停止，并且 getAnimationState() 将返回 STOPPED。

使用场景查看器加载 3D 模型

如果您正在寻找加载具有基本交互功能的 3D 模型的最简单方法，您可以选择像在移动设备上一样使用场景查看器。Android XR 上的场景查看器与移动设备上的场景查看器之间的一个主要区别是，场景查看器仅支持指向 glTF 文件的文件 URI 参数，所有其他参数都将被忽略。

场景查看器是一个单独的应用，它使用 intent 调用并在 Full Space 模式下运行。因此，当您调用它时，您的应用将不再可见，场景查看器将获得焦点。您可能更改的任何环境都将重置为用户的系统偏好设置。

以下是一个使用 Intent 在 Android XR 上通过场景查看器查看 glTF 文件的示例：

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.
}
GltfEntity.kt

有关场景查看器交互选项的更多信息，请参阅我们的3D 模型设计文档。

glTF 扩展

Jetpack XR SDK 支持多个 glTF 扩展，这些扩展扩展了 3D 模型的功能。这些功能通过 GltfEntity 和场景查看器均可用。