Android XR for OpenXR | Android Developers

Android 開發人員高峰會再度登場，並專為 Android XR 規劃一系列議程。歡迎試用，並提供意見！

Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

XR_ANDROID_global_passthrough_dimming

Name String

XR_ANDROID_global_passthrough_dimming

擴充功能類型

執行個體擴充功能

擴充功能註冊編號

797

修訂版本

批准狀態

未批准

擴充功能和版本依附元件

OpenXR 1.0

上次修改日期

2026-03-10

IP 狀態

沒有已知的智慧財產權聲明。

著作人

Brian Chen, Google
Kyle Chen, Google
Nihav Jain, Google
Spencer Quin, Google

總覽

隨著光學穿透式裝置的推出，應用程式不僅要能調整穿透畫面的亮度，為使用者提供與應用程式情境最佳的融合效果，系統也必須能基於安全考量調亮穿透畫面。

這項擴充功能提供兩個函式，可讓應用程式設定及取得目前的調光等級，以及在調光等級變更時廣播事件。

檢查系統功能

XrSystemGlobalDimmingPropertiesANDROID 結構定義如下：

typedef struct XrSystemGlobalDimmingPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsGlobalDimming;
} XrSystemGlobalDimmingPropertiesANDROID;

成員說明

type 是這個結構的 XrStructureType。
next 是 NULL，或指向結構鏈中下一個結構的指標。核心 OpenXR 或這個擴充功能中未定義這類結構。核心 OpenXR 或這個擴充功能中未定義這類結構。
supportsGlobalDimming 是 XrBool32，表示目前系統是否支援全域調光。

應用程式可以檢查系統是否支援全域調光，方法是在呼叫 xrGetSystemProperties 時，將 XrSystemGlobalDimmingPropertiesANDROID 結構鏈結至 XrSystemProperties。

如果執行階段針對 supportsGlobalDimming 傳回 XR_FALSE，則在呼叫 xrGetGlobalDimmingLevelANDROID 時，執行階段必須傳回 XR_ERROR_FEATURE_UNSUPPORTED。

有效用途 (隱含)

必須先啟用 XR_ANDROID_global_passthrough_dimming 擴充功能，才能使用 XrSystemGlobalDimmingPropertiesANDROID
type「必須」為 XR_TYPE_SYSTEM_GLOBAL_DIMMING_PROPERTIES_ANDROID
next「必須」為 NULL，或指向結構鏈中下一個結構的有效指標

列舉支援的全域調光等級

xrEnumerateSupportedGlobalDimmingLevelsANDROID 結構定義如下：

XrResult xrEnumerateSupportedGlobalDimmingLevelsANDROID(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    supportedGlobalDimmingLevelCapacityInput,
    uint32_t*                                   supportedGlobalDimmingLevelCountOutput,
    float*                                      supportedGlobalDimmingLevels);

成員說明

instance 是擷取 systemId 的執行個體。
systemId 是要列舉支援等級的 XrSystemId。
supportedGlobalDimmingLevelCapacityInput 是 supportedGlobalDimmingLevels 陣列的容量，或 0 表示要求擷取所需容量。
supportedGlobalDimmingLevelCountOutput 是指向寫入 supportedGlobalDimmingLevels 數量的指標，或在 supportedGlobalDimmingLevelCapacityInput 不足時指向所需容量的指標。
supportedGlobalDimmingLevels 是指向支援等級陣列的指標，但如果 supportedGlobalDimmingLevelCapacityInput 為 0，則可以為 NULL。

如果傳回的 supportedGlobalDimmingLevelCountOutput 為 0，則支援 0.0 到 1.0 之間的所有全域調光等級。

xrEnumerateSupportedGlobalDimmingLevelsANDROID 會列舉 XrSystemId 支援的全域調暗等級。支援的層級在 XrInstance 的生命週期內不得變更。傳回的等級清單必須遞增排序。

針對指定的 systemId 和 instance 的生命週期，執行階段必須一律從這個列舉傳回相同的緩衝區內容。

有效用途 (隱含)

必須先啟用 XR_ANDROID_global_passthrough_dimming 擴充功能，才能呼叫 xrEnumerateSupportedGlobalDimmingLevelsANDROID
instance「必須」是有效的 XrInstance 控制代碼
supportedGlobalDimmingLevelCountOutput「必須」是指向 uint32_t 值的指標
如果 supportedGlobalDimmingLevelCapacityInput 不是 0，supportedGlobalDimmingLevels「必須」是指向 supportedGlobalDimmingLevelCapacityInput float 值陣列的指標

傳回代碼

成功

XR_SUCCESS

失敗

XR_ERROR_FUNCTION_UNSUPPORTED
XR_ERROR_HANDLE_INVALID
XR_ERROR_INSTANCE_LOST
XR_ERROR_RUNTIME_FAILURE
XR_ERROR_SIZE_INSUFFICIENT
XR_ERROR_SYSTEM_INVALID
XR_ERROR_VALIDATION_FAILURE

設定全面調暗等級

XrGlobalDimmingFrameEndInfoANDROID 結構定義如下：

typedef struct XrGlobalDimmingFrameEndInfoANDROID {
    XrStructureType    type;
    const void*        next;
    float              globalDimmingLevel;
} XrGlobalDimmingFrameEndInfoANDROID;

參數說明

type 是這個結構的 XrStructureType。
next 是 NULL，或指向結構鏈中下一個結構的指標。核心 OpenXR 或這個擴充功能中未定義這類結構。
globalDimmingLevel 是介於 0.0 (透明) 和 1.0 (不透明) 之間的值。執行階段可能會將這個值對應至最接近的支援全域調光等級。應用程式可以將這個值設為 -1.0，表示偏好目前的調暗程度。

globalDimmingLevel 值會指定光線阻擋百分比，其中 0.0 對應 0% 光線阻擋，1.0 對應 100% 光線阻擋。光線阻擋百分比可表示為：

100% - Light Transmittance%

根據 ISO 8980-3:2022，透光率百分比可以測量為可見光波長 (380 奈米至 780 奈米) 下，透射輻射通量與入射輻射通量的比率。

XrGlobalDimmingFrameEndInfoANDROID 是一種結構，應用程式可以在 XrFrameEndInfo 中鏈結，要求偏好的全域調暗等級。

如果要求的調暗程度與目前不同，執行階段必須採用要求的調暗程度。

執行階段會控制全域調暗程度，且基於安全考量，可能會忽略偏好的全域調暗程度。

有效用途 (隱含)

必須先啟用 XR_ANDROID_global_passthrough_dimming 擴充功能，才能使用 XrGlobalDimmingFrameEndInfoANDROID
type「必須」為 XR_TYPE_GLOBAL_DIMMING_FRAME_END_INFO_ANDROID
next「必須」為 NULL，或指向結構鏈中下一個結構的有效指標

xrGetGlobalDimmingLevelANDROID 函式的定義如下：

XrResult xrGetGlobalDimmingLevelANDROID(
    XrSession                                   session,
    float*                                      dimmingLevel);

參數說明

session 是有效的 XrSession 控制代碼。
dimmingLevel 是指向目前調暗等級的指標。

傳回的 dimmingLevel 必須介於 0.0 和 1.0 之間，其中 0.0 表示完全透明，1.0 表示完全變暗。

如果未設定調暗程度，執行階段必須在啟用穿透模式時將調暗程度設為 0.0，並在停用穿透模式時設為 1.0。

有效用途 (隱含)

必須先啟用 XR_ANDROID_global_passthrough_dimming 擴充功能，才能呼叫 xrGetGlobalDimmingLevelANDROID
session「必須」是有效的 XrSession 控制代碼
dimmingLevel「必須」是指向 float 值的指標

傳回代碼

成功

XR_SUCCESS
XR_SESSION_LOSS_PENDING

失敗

XR_ERROR_FUNCTION_UNSUPPORTED
XR_ERROR_HANDLE_INVALID
XR_ERROR_INSTANCE_LOST
XR_ERROR_RUNTIME_FAILURE
XR_ERROR_SESSION_LOST
XR_ERROR_VALIDATION_FAILURE

調光等級變更事件

XrEventDataGlobalDimmingLevelChangedANDROID 結構定義如下：

typedef struct XrEventDataGlobalDimmingLevelChangedANDROID {
    XrStructureType    type;
    const void*        next;
    XrSession          session;
} XrEventDataGlobalDimmingLevelChangedANDROID;

成員說明

type 是這個結構的 XrStructureType。
next 是 NULL，或指向結構鏈中下一個結構的指標。核心 OpenXR 或這個擴充功能中未定義這類結構。
session 是有效的 XrSession 控制代碼。

應用程式「可以」使用 xrPollEvent 擷取這個事件。當應用程式或裝置上的實體按鈕變更調光等級時，系統會傳送這個事件。

當焦點切換到其他應用程式時，系統不會傳送這個事件。

應用程式應呼叫 xrGetGlobalDimmingLevelANDROID 來回應事件，以取得新的調暗等級，並據此更新 XrGlobalDimmingFrameEndInfoANDROID :: globalDimmingLevel。回應事件可確保應用程式變更偏好的調暗程度時，執行階段會收到信號。

有效用途 (隱含)

必須先啟用 XR_ANDROID_global_passthrough_dimming 擴充功能，才能使用 XrEventDataGlobalDimmingLevelChangedANDROID
type「必須」為 XR_TYPE_EVENT_DATA_GLOBAL_DIMMING_LEVEL_CHANGED_ANDROID
next「必須」為 NULL，或指向結構鏈中下一個結構的有效指標

範例程式碼

檢查系統功能並列舉支援的全域調光等級

以下程式碼範例說明如何檢查是否支援全域調光。

XrInstance instance; // previously initialized
XrSystemId systemId; // previously initialized

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrEnumerateSupportedGlobalDimmingLevelsANDROID xrEnumerateSupportedGlobalDimmingLevelsANDROID;

XrSystemGlobalDimmingPropertiesANDROID dimmingControlSystemProperties { XR_TYPE_SYSTEM_GLOBAL_DIMMING_PROPERTIES_ANDROID };

XrSystemProperties systemProperties; // Chain dimmingControlSystemProperties

// ...
// Run xrGetSystemProperties()
// ...

if (!dimmingControlSystemProperties.supportsGlobalDimming) {
  // The system does not support global dimming
  return;
}

// Enumerate supported levels
uint32_t count = 0;
CHK_XR(xrEnumerateSupportedGlobalDimmingLevelsANDROID(instance, systemId, count, &count, nullptr));

std::vector<float> supportedLevels(count);
CHK_XR(xrEnumerateSupportedGlobalDimmingLevelsANDROID(instance, systemId, count, &count, supportedLevels.data()));

輪詢調光等級變更事件

以下程式碼範例示範如何輪詢調光等級變更事件。

XrEventDataBuffer event{ XR_TYPE_EVENT_DATA_BUFFER };

// ...
// Run xrPollEvent()
// ...

switch (event.type) {
  // This event will not be sent when focused app switches
  case XR_TYPE_EVENT_DATA_GLOBAL_DIMMING_LEVEL_CHANGED_ANDROID:
  {
    const XrEventDataGlobalDimmingLevelChangedANDROID &dimmingLevelChangedEvent =
            *reinterpret_cast<XrEventDataGlobalDimmingLevelChangedANDROID *>(&event);

    // Query new dimming level using xrGetGlobalDimmingLevelANDROID()
  }
}

新指令

xrEnumerateSupportedGlobalDimmingLevelsANDROID
xrGetGlobalDimmingLevelANDROID

新結構

XrEventDataGlobalDimmingLevelChangedANDROID
擴充 XrFrameEndInfo：
- XrGlobalDimmingFrameEndInfoANDROID
擴充 XrSystemProperties：
- XrSystemGlobalDimmingPropertiesANDROID

新列舉常數

XR_ANDROID_GLOBAL_PASSTHROUGH_DIMMING_EXTENSION_NAME
XR_ANDROID_global_passthrough_dimming_SPEC_VERSION
擴充 XrStructureType：
- XR_TYPE_EVENT_DATA_GLOBAL_DIMMING_LEVEL_CHANGED_ANDROID
- XR_TYPE_GLOBAL_DIMMING_FRAME_END_INFO_ANDROID
- XR_TYPE_SYSTEM_GLOBAL_DIMMING_PROPERTIES_ANDROID

問題

版本記錄

修訂版本 1，2025-10-07 (Brian Chen)
- 初始擴充功能說明。