向应用添加 3D 模型

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

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

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

如需快速了解受支持的材质，请参阅 Khronos 网站上的 glTF PBR 属性。如需了解如何使用这些属性和其他属性自定义 3D 模型，请参阅 自定义应用中的 3D 模型

将 glTF 文件添加到 assets 文件夹

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

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

使用 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)

使用 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 模型示例

使用 Scene Viewer 加载 3D 模型

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

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

下面是一个使用 Intent 在 Android XR 上的 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 支持多个 glTF 扩展程序，这些扩展程序可扩展 3D 模型的功能。这些功能可通过 GltfModelEntity 和 Scene Viewer 使用。