为您的应用添加空间环境

在 Jetpack XR SDK 中，空间环境是可添加到应用中以自定义虚拟场景背景的沉浸式环境。空间环境仅在应用处于“全空间”模式时可见。

空间环境概览

A SpatialEnvironment 用于管理应用的空间环境偏好设置。它由独立的背景图（skybox）图像和 glTF 指定的几何图形组成。一次只能设置一个背景图图像和一个 glTF 几何图形文件。

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

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

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

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

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

空间环境的空间功能

导入和加载空间环境资源

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

创建 glTF 资源

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

val environmentGeometryFuture = GltfModel.create(session, "DayGeometry.glb")
val environmentGeometry = environmentGeometryFuture.await()
Environments.kt

创建 EXR 图像资源

EXR 图像资源可以创建为 ExrImage，其中 EXR 从本地文件加载。ExrImage 可以与 cmgen 结合使用，为您的背景图创建 IBL 的 ZIP 文件。如需了解详情，请参阅我们的环境资源优化指南。

val lightingForSkybox = ExrImage.create(session, "BlueSkyboxLighting.zip")
Environments.kt

为您的应用设置 SpatialEnvironmentPreference

setSpatialEnvironmentPreference 用于设置应用的偏好空间环境。此方法仅设置偏好，不会立即引起更改，除非 isSpatialEnvironmentPreferenceActive 已经为 true。一旦设备进入 XR 背景可以更改的状态，并且 SpatialCapabilities.SPATIAL_CAPABILITY_APP_ENVIRONMENT 功能可用，应用程序的偏好空间环境将自动显示。

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

如果给定的 SpatialEnvironmentPreference 不为 null，但其所有属性都为 null，则空间环境将由黑色背景图和无几何图形组成。

要收到 SpatialEnvironment 状态变化的通知，请使用 addOnSpatialEnvironmentChangedListener。

基本用法

此代码片段创建环境几何图形和背景图资源，然后设置空间环境偏好。此偏好将被记住，并在应用具有设置自身环境的能力时应用。

val spatialEnvironmentPreference =
    SpatialEnvironment.SpatialEnvironmentPreference(lightingForSkybox, environmentGeometry)
val preferenceResult =
    session.scene.spatialEnvironment.setSpatialEnvironmentPreference(spatialEnvironmentPreference)
if (preferenceResult == SpatialEnvironment.SetSpatialEnvironmentPreferenceChangeApplied()) {
    // The environment was successfully updated and is now visible, and any listeners
    // specified using addOnSpatialEnvironmentChangedListener will be notified.
} else if (preferenceResult == SpatialEnvironment.SetSpatialEnvironmentPreferenceChangePending()) {
    // The environment is in the process of being updated. Once visible, any listeners
    // specified using addOnSpatialEnvironmentChangedListener will be notified.
}
Environments.kt

高级用法

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

为应用的 spatial environment 设置 PassthroughOpacityPreference

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

setPassthroughOpacityPreference 用于设置应用的偏好透视不透明度。此方法仅设置偏好，不会立即引起更改，除非 SpatialCapabilities.SPATIAL_CAPABILITY_PASSTHROUGH_CONTROL 功能可用。一旦设备进入透视不透明度可以更改的状态，并且 SpatialCapabilities.SPATIAL_CAPABILITY_PASSTHROUGH_CONTROL 功能可用，应用程序的偏好透视不透明度将自动应用。

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

基本用法

此代码片段设置了透视不透明度偏好。此偏好将被记住，并在应用具有设置透视不透明度的能力时应用。

val preferenceResult = session.scene.spatialEnvironment.setPassthroughOpacityPreference(1.0f)
if (preferenceResult == SpatialEnvironment.SetPassthroughOpacityPreferenceChangeApplied()) {
    // The passthrough opacity request succeeded and should be visible now, and any listeners
    // specified using addOnPassthroughOpacityChangedListener will be notified
} else if (preferenceResult == SpatialEnvironment.SetPassthroughOpacityPreferenceChangePending()) {
    // 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.getCurrentPassthroughOpacity()
Environments.kt

另请参阅