檢查空間功能

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

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

使用適用於 XR 的 Jetpack Compose 檢查空間功能

適用於 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()
}
SpatialCapabilities.kt

使用 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)
) {
    // ...
}
SpatialCapabilities.kt

使用混合模式檢查裝置的螢幕功能

在 Android XR 中，XR 頭戴式裝置和有線 XR 眼鏡的硬體功能各不相同，尤其是螢幕類型。您可能需要調整應用程式 UI 和算繪物件的顏色，盡量提高可見度，這可能會受到顯示器類型和裝置偏好的混合模式影響。DisplayBlendMode API 提供裝置的混和模式功能，用於算繪。使用這個 API 判斷虛擬內容的加入方式。

以下列舉幾種需要注意的混合模式類型：

  • ADDITIVE：將紅色、綠色和藍色元件的像素值相加，即可將虛擬內容加入現實世界。系統會忽略 Alpha 值，並將黑色像素顯示為透明。
  • ALPHA_BLEND：虛擬內容會根據 Alpha 元件，透過 Alpha 混合像素值新增至現實世界。
  • NO_DISPLAY：裝置不支援混合功能。

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

另請參閱