向应用添加空间环境

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

在 Jetpack XR SDK 中，空间环境是您可以添加到应用中的沉浸式周围环境，用于自定义虚拟场景的背景。只有当应用处于全沉浸空间时，空间环境才会显示。

空间环境概览

SpatialEnvironment 用于管理应用的空间环境 偏好设置。它是独立天空盒图片和 glTF 指定的几何图形的组合。一次只能设置一张天空盒图片和一个 glTF 几何图形文件。

天空盒表示用户在虚拟场景中看到的周围图片，营造出远处背景环境（如天空、山脉或城市景观）的错觉。用户无法与天空盒互动或靠近天空盒。Jetpack XR SDK 支持 OpenEXR 标准中的球形天空盒。除了为应用提供沉浸式 背景之外，EXR 天空盒还为应用加载的 3D 模型提供基于图片的照明 (IBL) 。如需了解详情，请参阅使用 3D 模型 指南。

空间环境还可以包含 glTF标准中的 3D 几何图形内容。以这种方式加载的环境几何图形将自动与现实世界的地面对齐。环境几何图形是一种通过前景和中景元素为环境增添真实感的好方法，这些元素通过视差效果融入天空盒。

在空间环境设计指南中，您可以了解可用于创建空间环境的 不同类型的资源，以及如何 创建安全且令人愉悦的空间环境。

您可以将应用的空间环境设置为以下三种配置之一：

  • 天空盒图片和 glTF 几何图形的组合。
  • 透视表面，其中显示的环境是来自设备外向摄像头的实时馈送。在完全不透明度的情况下，此透视表面会完全遮挡天空盒和几何图形。
  • 混合配置，其中透视表面既不是完全不透明，也不是完全透明。在这种情况下，透视表面会变为半透明，并与后面的天空盒和几何图形进行 Alpha 混合。

空间环境的空间功能

导入和加载空间环境资源

空间环境的 glTF 和 EXR 资源通过使用 Session 类异步加载。

创建 glTF 资源

glTF 资源可以创建为 GltfModel，其中 glTF 从本地文件加载 。GltfModel 可用作空间应用环境的一部分。

val environmentGeometry = GltfModel.create(session, Paths.get("DayGeometry.glb"))

创建基于图片的照明资源

基于图片的照明资源可以创建为 ImageBasedLightingAsset，其中照明从本地文件加载。 ImageBasedLightingAsset 可与 cmgen 结合使用，为您的天空盒创建 IBL 的 ZIP 文件。 如需了解详情，请参阅有关优化环境资源的指南。

val lightingForSkybox = ImageBasedLightingAsset.createFromZip(session, Paths.get("BlueSkyboxLighting.zip"))

为应用设置 SpatialEnvironmentPreference

preferredSpatialEnvironment 属性用于控制应用的首选空间 环境。当此属性用于设置偏好设置时，除非 isPreferredSpatialEnvironmentActive 已为 true，否则不会立即发生更改。一旦设备进入可以更改 XR 背景的状态，并且 SpatialCapabilities.SPATIAL_CAPABILITY_APP_ENVIRONMENT功能可用，系统将自动显示应用的首选空间环境。

将偏好设置设置为 null 将停用应用的首选空间环境，这意味着系统将改为显示默认环境。

如果给定的 SpatialEnvironmentPreference 不为 null，但其所有 属性均为 null，则空间环境将包含黑色天空盒 且不包含几何图形。

如需接收有关 SpatialEnvironment 状态更改的通知，请使用 addOnSpatialEnvironmentChangedListener。

基本用法

此代码段会创建环境几何图形和天空盒资源，然后设置空间环境偏好设置。系统会记住此偏好设置，并在应用能够设置自己的环境时应用该偏好设置。

val spatialEnvironmentPreference =
    SpatialEnvironment.SpatialEnvironmentPreference(lightingForSkybox, environmentGeometry)
session.scene.spatialEnvironment.preferredSpatialEnvironment = spatialEnvironmentPreference
if (session.scene.spatialEnvironment.isPreferredSpatialEnvironmentActive) {
    // The environment was successfully updated and is now visible, and any listeners
    // specified using addOnSpatialEnvironmentChangedListener will be notified.
} else {
    // The passthrough opacity preference was successfully set, but not
    // immediately visible. The passthrough opacity change will be applied
    // when the activity has the SPATIAL_CAPABILITY_APP_ENVIRONMENT capability.
    // Then, any listeners specified using addOnSpatialEnvironmentChangedListener
    // will be notified.
}

高级用法

对于需要对环境进行更精细控制的更高级用例， 您可以加入 SpatialCapabilities 检查，并实现 addOnSpatialEnvironmentChangedListener 以确定何时要设置 空间环境偏好设置。

为应用的空间环境设置 PassthroughOpacityPreference

应用沉浸式虚拟背景的组件之一是透视表面。在这种情况下，显示的背景是来自设备外向摄像头的实时馈送。

setPassthroughOpacityPreference 用于设置应用的首选透视 不透明度。此方法仅设置偏好设置，除非 SpatialCapabilities.SPATIAL_CAPABILITY_PASSTHROUGH_CONTROL 功能 可用，否则不会立即发生更改。一旦设备进入可以更改透视不透明度的状态，并且 SpatialCapabilities.SPATIAL_CAPABILITY_PASSTHROUGH_CONTROL 功能可用，系统将自动应用应用的首选透视不透明度。

透视不透明度偏好设置的值范围为 0.0f（零不透明度，透视表面不可见）到 1.0f（完全不透明，透视表面会隐藏空间环境）。setPassthroughOpacityPreference 参数是可为 null 的浮点数。将值设置为 null 表示应用没有透视不透明度偏好设置，并将透视控制权返回给系统。

基本用法

此代码段会设置透视不透明度偏好设置。系统会记住此偏好设置，并在应用能够设置透视不透明度时应用该偏好设置。

session.scene.spatialEnvironment.preferredPassthroughOpacity = 1.0f
if (session.scene.spatialEnvironment.currentPassthroughOpacity == 1.0f) {
    // The passthrough opacity request succeeded and should be visible now, and any listeners
    // specified using addOnPassthroughOpacityChangedListener will be notified.
} else {
    // The passthrough opacity preference was successfully set, but not
    // immediately visible. The passthrough opacity change will be applied
    // when the activity has the
    // SpatialCapabilities.SPATIAL_CAPABILITY_PASSTHROUGH_CONTROL capability.
    // Then, any listeners specified using addOnPassthroughOpacityChangedListener
    // will be notified.
}

高级用法

对于需要对透视 不透明度进行更精细控制的更高级用例，您可以加入 SpatialCapabilities 检查，并使用 addOnPassthroughOpacityChangedListener 添加监听器 ，以确定何时要设置透视不透明度偏好设置。

素材资源优化

在创建用于设置用户的 SpatialEnvironment 的资源时，请确保您的资源在保持合理文件大小的同时实现高质量分辨率。如需了解详情，请参阅有关优化环境资源的指南。

确定当前的透视不透明度

val currentPassthroughOpacity = session.scene.spatialEnvironment.currentPassthroughOpacity

另请参阅