在應用程式中新增空間環境

在 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"))
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 不是空值，但所有屬性都是空值，則空間環境會包含黑色天空盒，且沒有幾何圖形。

如要接收 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，判斷何時要設定空間環境偏好設定。

為應用程式的空間環境設定 PassthroughOpacityPreference

應用程式沉浸式虛擬背景的其中一個元件是透視表面。在這種情況下，顯示的背景是裝置朝外攝影機的即時影像。

setPassthroughOpacityPreference 用於設定應用程式的偏好透視不透明度。這個方法只會設定偏好設定，除非 SpatialCapabilities.SPATIAL_CAPABILITY_PASSTHROUGH_CONTROL 功能可用，否則不會立即變更。裝置進入可變更透視不透明度的狀態，且 SpatialCapabilities.SPATIAL_CAPABILITY_PASSTHROUGH_CONTROL 功能可用時，系統會自動套用應用程式偏好的透視不透明度。

透視模式不透明度偏好的值介於 0.0f (零不透明度，透視表面不可見) 到 1.0f (完全不透明，透視表面會隱藏空間環境)。setPassthroughOpacityPreference 參數是可為空值的浮點數。將值設為空值表示應用程式沒有透視不透明度偏好設定，並會將透視控制項回傳給系統。

基本用法

這個程式碼片段會設定透視模式的不透明度偏好設定。系統會記住這項偏好設定，並在應用程式具備設定透視不透明度的功能時套用。

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

另請參閱