檢查空間功能

適用的 XR 裝置
本指南可協助您為這類 XR 裝置打造體驗。
瞭解 XR 裝置類型 →
XR 頭戴式裝置
有線 XR 眼鏡
瞭解 XR 裝置類型 →

空間音訊功能可能因裝置而異，且會隨著使用者與應用程式或系統互動而改變。甚至可以由應用程式本身變更，例如移至主畫面或全螢幕。為避免發生問題，應用程式需要檢查空間功能，判斷目前環境支援哪些 API。

使用 Jetpack Compose for XR 檢查空間功能

適用於 XR 的 Jetpack Compose 會建立 Composition Local，用於檢查空間功能。可用來檢查是否已啟用空間 UI、空間音訊、環境、透視或 3D 內容。

您可以使用 LocalSpatialCapabilities.current 檢查目前是否可使用下列空間功能：

以下範例說明如何檢查是否已啟用空間 UI：

if (LocalSpatialCapabilities.current.isSpatialUiEnabled) {
    Subspace {
        SpatialPanel(
            modifier = SubspaceModifier
                .width(1488.dp)
                .fillMaxHeight()
        ) {
            AppContent()
        }
    }
} else {
    AppContent()
}

使用 SceneCore 檢查空間功能

使用 SceneCore 程式庫時，您必須建立工作階段。建立工作階段後，請使用工作階段 scene 的 spatialCapabilities，查詢目前可用的空間功能。

您也可以選擇訂閱回呼 addSpatialCapabilitiesChangedListener，以便在空間功能變更時收到通知。

// Example 1: check if enabling passthrough mode is allowed
if (xrSession.scene.spatialCapabilities.contains(
        SpatialCapability.PASSTHROUGH_CONTROL
    )
) {
    xrSession.scene.spatialEnvironment.preferredPassthroughOpacity = 1f
}
// Example 2: multiple capability flags can be checked simultaneously:
if (xrSession.scene.spatialCapabilities.contains(SpatialCapability.PASSTHROUGH_CONTROL) &&
    xrSession.scene.spatialCapabilities.contains(SpatialCapability.SPATIAL_3D_CONTENT)
) {
    // ...
}

使用混合模式檢查裝置的顯示功能

在 Android XR 上，XR 頭戴式裝置和有線 XR 眼鏡的硬體功能不盡相同，尤其是顯示類型。您可能需要調整應用程式 UI 和算繪物件的顏色，盡可能提高能見度，這可能會受到裝置採用的顯示類型和偏好混合模式影響。DisplayBlendMode API 提供裝置的混合模式功能，可用於算繪。使用這個 API 決定如何將虛擬內容加入真實世界。

以下列舉幾種混合模式類型：

  • ADDITIVE：系統會加入紅、綠、藍各個元件的像素值，將虛擬內容加入真實世界。系統會忽略 Alpha，黑色像素則會顯示為透明。
  • ALPHA_BLEND：根據 Alpha 元件，透過 Alpha 混合像素值，將虛擬內容加入真實世界。
  • NO_DISPLAY：裝置不支援混合。

使用 Jetpack XR 執行階段程式庫中的 XrDevice.getCurrentDevice(session).getPreferredDisplayBlendMode()，檢查目前使用的混合模式類型，並視需要調整。

另請參閱