自定义应用中的 3D 模型

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

向应用添加 3D 模型后，您可以通过自定义该模型来提升视觉和互动体验。例如，您可以播放和控制嵌入式 glTF 动画、定义自定义材质属性（例如基色或金属粗糙度），以及将自定义纹理应用到 3D 模型。借助这些功能，您可以在运行时动态更改对象的外观和行为。

为 3D 模型添加动画效果

根据 glTF 规范，3D 模型可以嵌入动画。 Jetpack XR SDK 支持骨骼（绑定）动画、刚性动画和变形目标（混合形状）动画。系统还支持使用 KHR_animation_pointer glTF 扩展程序创建的 Material 动画。

如需播放动画，请从 animations 列表中指定特定轨道的名称。调用 GltfAnimation.start() 开始播放。您可以选择使用 GltfAnimationStartOptions 指定速度、搜索时间以及动画是否应循环播放。

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

您还可以使用 pause()、resume() 和 stop() 动画，以及使用 seekTo() 跳转到动画轨道中的特定时间。如需查询动画的当前状态，请使用 GltfAnimation.AnimationState。

自定义 3D 模型的材质属性

Jetpack XR 的材质系统基于 glTF™ 2.0 规范，3D 模型使用基于物理的渲染 (PBR) 进行渲染。您可以在运行时调整材质属性，以根据用户输入或应用的当前状态动态更改对象的外观。

Material 用于定义对象表面的一组视觉属性，并确定该表面在场景中与光的互动方式。

在 Jetpack XR 中，KhronosPbrMaterial 和 KhronosUnlitMaterial 类用于创建和操纵这些材质。顾名思义，KhronosUnlitMaterials 不发光，不受场景光照的影响。KhronosPbrMaterial 可让您自定义更多属性，例如光泽颜色、对象的金属感或粗糙度，以及对象是否发光。

如需详细了解 Android XR 中支持的各项属性和可自定义的参数，请参阅我们的参考文档。如需更好地了解这些属性，请参阅 Khronos 词汇表。

更改 3D 模型上的基本颜色的示例

如需自定义 3D 模型的材质属性，请先使用 KhronosPbrMaterial 创建新材质。您需要为要实现的视觉效果设置适当的 AlphaMode：

val pbrMaterial = KhronosPbrMaterial.create(
    session = xrSession,
    alphaMode = AlphaMode.OPAQUE
)

接下来，定义要修改的属性。在此示例中，我们使用 setBaseColorFactor 更改基色。此方法需要一个 Vector4，其中 x、y、z 和 w 组件分别对应于 RGBA（红色、绿色、蓝色和 Alpha）值：

pbrMaterial.setBaseColorFactor(
    Vector4(
        x = 0.5f,
        y = 0.0f,
        z = 0.5f,
        w = 1.0f
    )
)

为 3D 模型创建自定义纹理

Texture 是一种图片素材资源，您可以将其应用于 3D 模型的表面，以提供颜色、细节或其他表面信息。借助 Jetpack XR Texture API，您可以从应用的 /assets/ 文件夹异步加载 PNG 文件等图片数据。

加载纹理时，您可以指定 TextureSampler，用于控制纹理的渲染方式。采样器用于定义过滤属性（用于在纹理显示得比其原始尺寸小或大时）和封装模式（用于处理标准 [0, 1] 范围之外的坐标）。Texture 对象本身只是数据；必须将其分配给 Material 才能对 3D 模型产生视觉效果。

更改 3D 模型纹理的示例

如需创建自定义纹理，您首先需要将图片文件保存到 /assets/ 文件夹。最佳实践是，您可能还需要在该文件夹中创建一个 textures 子目录。

将文件保存在相应目录中后，使用 Texture API 创建纹理。您还可以在此处应用可选的 TextureSampler（如果需要）：

val texture = Texture.create(
    session = xrSession,
    path = Path("textures/texture_file.png")
)

接下来，定义纹理类型并设置相应的参数。在此示例中，我们应用了遮挡纹理并设置了强度：

pbrMaterial.setOcclusionTexture(
    texture = texture,
    strength = 1.0f
)

为 3D 对象应用材质和纹理

如需应用新材质或纹理，请替换 glTF 节点上特定节点的现有材质。为此，请对 GltfModelNode 调用 setMaterialOverride：

gltfModelNode.setMaterialOverride(
    material = pbrMaterial
)

如需移除新创建的材质，请在之前被替换的 GltfModelNode 节点上调用 clearMaterialOverride。这会将 3D 模型恢复为默认状态：

gltfModelNode.clearMaterialOverride()

glTF 和 glTF 徽标是 Khronos Group Inc. 的商标。