XR_ANDROID_global_passthrough_dimming

名称字符串

XR_ANDROID_global_passthrough_dimming

扩展程序类型

实例扩展程序

已注册的扩展程序编号

797

修订版本

1

批准状态

未批准

扩展程序和版本依赖项

OpenXR 1.0

上次修改日期

2026-03-10

IP 状态

没有已知的 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 月 7 日 (Brian Chen)

  • 初始扩展程序说明。