向应用添加空间环境

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

空间环境概览

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

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

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

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

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

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

空间环境的空间功能

导入和加载空间环境资源

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

创建 glTF 资源

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

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

创建 EXR 映像资源

EXR 图片资源可以创建为 ExrImage，其中 EXR 从本地文件加载。ExrImage 可与 cmgen 搭配使用，以创建天空盒的 IBL ZIP 文件。如需了解详情，请参阅有关优化环境资源的指南。

val lightingForSkybox = ExrImage.createFromZip(session, Paths.get("BlueSkyboxLighting.zip"))
Environments.kt

为应用设置 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.
}
Environments.kt

高级用法

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

为应用的 3D 环境设置 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.
}
Environments.kt

高级用法

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

资源优化

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

确定当前透视不透明度

val currentPassthroughOpacity = session.scene.spatialEnvironment.currentPassthroughOpacity
Environments.kt

另请参阅