自定义应用中的 3D 模型

适用的 XR 设备
本指南可帮助您为这些类型的 XR 设备打造体验。
了解 XR 设备类型 →
XR 头戴设备
有线 XR 眼镜
了解 XR 设备类型 →

向应用添加 3D 模型后，您可以通过定义自定义材质属性并向对象应用纹理来提升视觉体验。Jetpack XR 的材质系统基于 glTF™ 2.0 规范，并使用基于物理的渲染 (PBR) 来渲染 3D 模型。这些都是由 Khronos Group 维护的开放式标准。

可以在运行时调整材质属性，以根据用户输入或应用的当前状态动态更改对象的外观。

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

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

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

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

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

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

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

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

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

为 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")
)
MaterialOverride.kt

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

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

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

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

gltfModelEntity.setMaterialOverride(
    material = pbrMaterial,
    nodeName = "Node Name"
)
MaterialOverride.kt

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

gltfModelEntity.clearMaterialOverride(
    nodeName = "Node Name"
)
MaterialOverride.kt

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