向应用添加 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 属性。

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

将 3D 模型放置到 ActivitySpace 中

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

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

如需加载 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 模型示例

使用 SpatialGltfModel 添加 3D 对象

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

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

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

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

SpatialGltfModel(state = modelState, modifier = SubspaceModifier)

将 3D 模型放置到 Compose SceneCoreEntity 中

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

使用 Scene Viewer 加载 3D 模型

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

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

以下示例展示了如何在 Android XR 上使用 Intent 在 Scene Viewer 中查看 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.
}

如需详细了解 Scene Viewer 的互动选项，请参阅我们的 3D 模型设计文档。

glTF 扩展

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