向应用添加 3D 模型

适用的 XR 设备
本指南可帮助您为以下类型的 XR 设备打造优质体验。
了解 XR 设备类型 →
扩展现实头戴设备
有线扩展现实眼镜
了解 XR 设备类型 →

使用 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 属性。如需了解如何使用这些属性和其他属性自定义 3D 模型，请参阅在应用中自定义 3D 模型

将 glTF 文件添加到素材资源文件夹

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

向 /models 目录添加素材资源的示例

使用 SpatialGltfModel 添加 3D 对象

Android XR 支持 3D 模型的 glTF 格式，通常保存为 .glb 文件。如需将这些对象添加到布局中，请使用 SpatialGltfModel。SpatialGltfModel 是一种子空间可组合项，可让您向空间布局中添加 glTF 格式的 3D 模型。此 API 简化了加载资源和管理其状态的过程。

如需显示模型，请先使用 rememberSpatialGltfModelState 定义其来源和状态。您可以从应用的 assets 文件夹、URI 或 raw data 加载模型。

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

定义状态后，使用 SpatialGltfModel 可组合项在子空间中呈现该状态：

SpatialGltfModel(state = modelState, modifier = SubspaceModifier)

代码要点

  • 异步加载：模型会异步加载。在初始组合期间，其固有大小可能为零；模型准备就绪后，布局会重新测量。
  • 控制状态：使用 SpatialGltfModelState.status 查询加载状态或控制动画。
  • 大小和缩放：默认情况下，布局大小与素材资源的边界框一致。您可以使用 SubspaceModifier.size 替换此设置，以统一缩放模型，使其适应指定的边界。

使用 Compose SceneCoreEntity 放置 3D 模型

如需使用 SceneCoreEntity 放置 3D 模型，您首先需要使用 GltfModel.create() 将 glTF 加载到内存中。然后，您可以将 3D 模型放入 SceneCoreEntity 中，以便将 SceneCore 组件与 Compose for XR 布局桥接。请参阅使用 SceneCoreEntity 在布局中放置 3D 对象。

使用 Jetpack Scenecore 放置 3D 模型

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

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

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

将 glTF 添加到 ActivitySpace。调用 GltfModelEntity.create 创建一个实体并将其放入 ActivitySpace 中。最佳实践是，您应检查应用是否处于允许使用空间功能的状态。

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

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

已加载的 3D 模型示例

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

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

Scene Viewer 是一个单独的应用，通过 intent 调用并在全沉浸空间模式下运行。因此，当您调用它时，您的应用将不再可见，并且 Scene Viewer 将获得焦点。您可能已更改的所有环境都将重置为用户的系统偏好设置。

以下示例展示了如何使用 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.
}

如需详细了解场景查看器的互动选项，请参阅我们的 3D 模型设计文档。

glTF 扩展

Jetpack XR SDK 支持多种 glTF 扩展，可扩展 3D 模型的功能。这些功能可通过 GltfModelEntity 和 Scene Viewer 使用。