XR_ANDROID_global_passthrough_dimming

Name String

XR_ANDROID_global_passthrough_dimming

Тип расширения

Расширение экземпляра

Зарегистрированный добавочный номер

797

Revision

1

Статус ратификации

Не ратифицировано

Зависимости расширений и версий

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, указывающий, поддерживает ли текущая система глобальное затемнение.

Приложение может проверить, поддерживает ли система глобальное затемнение, связав структуру XrSystemGlobalDimmingPropertiesANDROID с XrSystemProperties при вызове xrGetSystemProperties .

Если среда выполнения возвращает XR_FALSE для supportsGlobalDimming , то при вызове 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 – указатель на массив поддерживаемых уровней, но может быть NULL, если supportedGlobalDimmingLevelCapacityInput равно 0.

Если возвращенное значение 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, 7 октября 2025 г. (Брайан Чен)

  • Начальное описание расширения.