Name String

XR_ANDROID_recommended_settings

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

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

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

455

Revision

1

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

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

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

OpenXR 1.0

Дата последнего изменения

2026-03-16

Авторы

Спенсер Куин (Spencer Quin), Google
Джаред Финдер (Jared Finder), Google
Кевин Моул (Kevin Moule), Google
Нихав Джайн (Nihav Jain), Google
Леван Чен (Levana Chen), Google
Элвин Ши (Alvin Shi), Google
Салар Хан (Salar Khan), Google

Обзор

Среда пользователя по умолчанию может находиться в различных состояниях, которые определяются сочетанием режима смешивания и модальности ввода. Это расширение предоставляет рекомендуемые настройки для пользователя, которые соответствуют состоянию среды пользователя по умолчанию перед запуском приложения, чтобы обеспечить плавный переход.

Структуры и перечисления

Биты XrInputModalityFlagsANDROID определяют разные режимы ввода, которые могут использоваться.

typedef XrFlags64 XrInputModalityFlagsANDROID;

Допустимые биты для XrInputModalityFlagsANDROID определяются XrInputModalityFlagBitsANDROID , который указывается как:

// Flag bits for XrInputModalityFlagsANDROID
static const XrInputModalityFlagsANDROID XR_INPUT_MODALITY_HEAD_BIT_ANDROID = 0x00000001;
static const XrInputModalityFlagsANDROID XR_INPUT_MODALITY_CONTROLLER_BIT_ANDROID = 0x00000002;
static const XrInputModalityFlagsANDROID XR_INPUT_MODALITY_HANDS_BIT_ANDROID = 0x00000004;
static const XrInputModalityFlagsANDROID XR_INPUT_MODALITY_MOUSE_BIT_ANDROID = 0x00000008;
static const XrInputModalityFlagsANDROID XR_INPUT_MODALITY_GAZE_AND_GESTURE_BIT_ANDROID = 0x00000010;

Описания флагов

  • XR_INPUT_MODALITY_HEAD_BIT_ANDROID – указывает на режим ввода, в котором используется отслеживание движения головы.
  • XR_INPUT_MODALITY_CONTROLLER_BIT_ANDROID – указывает на модальность ввода, в которой используются любые входные данные контроллера XR.
  • XR_INPUT_MODALITY_HANDS_BIT_ANDROID – указывает на режим ввода, в котором используется отслеживание рук.
  • XR_INPUT_MODALITY_MOUSE_BIT_ANDROID – указывает на то, что используется управление мышью.
  • XR_INPUT_MODALITY_GAZE_AND_GESTURE_BIT_ANDROID – режим ввода, в котором сочетается отслеживание взгляда и отслеживание рук.

Структура XrRecommendedSettingsANDROID определяется следующим образом:

typedef struct XrRecommendedSettingsANDROID {
    XrStructureType                type;
    void*                          next;
    XrEnvironmentBlendMode         blendMode;
    float                          passthroughOpacity;
    XrInputModalityFlagsANDROID    activeInputModalities;
} XrRecommendedSettingsANDROID;

Описания участников

  • type – это XrStructureType этой структуры.
  • next – это NULL или указатель на следующую структуру в цепочке. Такие структуры не определены в ядре OpenXR или этом расширении.
  • blendMode – это XrEnvironmentBlendMode, указывающий режим смешивания среды по умолчанию непосредственно перед запуском приложения.
  • passthroughOpacity – это float, указывающее на прозрачность сквозной передачи среды по умолчанию непосредственно перед запуском приложения. Среда выполнения должна задать для этого параметра значение (1.0 - dimming_value) для устройств OST.
  • activeInputModalities – это битовая маска XrInputModalityFlagsANDROID, указывающая на модальности ввода, используемые в среде по умолчанию непосредственно перед запуском приложения.

Допустимое использование (неявное)

Перечисление поддерживаемых состояний среды

Приложение может определить, какие режимы смешивания и состояния модальности ввода поддерживаются системой, с помощью xrEnumerateEnvironmentBlendModes и расширения XrSystemProperties со структурой XrSystemInputModalityPropertiesANDROID при вызове xrGetSystemProperties .

Структура XrSystemInputModalityPropertiesANDROID определяется следующим образом:

typedef struct XrSystemInputModalityPropertiesANDROID {
    XrStructureType                type;
    void*                          next;
    XrInputModalityFlagsANDROID    supportedInputModalities;
} XrSystemInputModalityPropertiesANDROID;

Описания участников

  • type – это XrStructureType этой структуры.
  • next – это NULL или указатель на следующую структуру в цепочке. Такие структуры не определены в ядре OpenXR или этом расширении.
  • supportedInputModalities – один или несколько флагов XrInputModalityFlagsANDROID, указывающих на поддерживаемые системой способы ввода.

Допустимое использование (неявное)

Как получить рекомендуемые настройки (состояние среды по умолчанию перед запуском)

XrResult xrGetRecommendedSettingsANDROID(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    XrRecommendedSettingsANDROID*               output);

Описание параметров

  • instance – дескриптор XrInstance, ранее созданный с помощью xrCreateInstance .
  • systemId – это XrSystemId, ранее полученный из xrGetSystem .
  • output – указатель на структуру XrRecommendedSettingsANDROID, которая выводится с состоянием среды по умолчанию.

Допустимое использование (неявное)

  • Расширение XR_ANDROID_recommended_settings должно быть включено до вызова xrGetRecommendedSettingsANDROID.
  • instance должен быть действительным дескриптором XrInstance.
  • output должен быть указателем на структуру XrRecommendedSettingsANDROID.

Коды возврата

Выполнено

  • XR_SUCCESS

Сбой

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SYSTEM_INVALID

Пример кода для рекомендуемых настроек

В примере кода ниже показано, как получить поддерживаемые модальности ввода, получить рекомендуемые настройки и подтвердить, что указанные настройки поддерживаются системой.

XrInstance instance;  // Created at app startup
XrSystemId systemId;  // previously initialized from xrGetSystem
XrViewConfigurationType viewType;  // previously initialized to select desired view configuration

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrGetRecommendedSettingsANDROID xrGetRecommendedSettingsANDROID; // previously initialized

XrSystemInputModalityPropertiesANDROID props = {
  .type = XR_TYPE_SYSTEM_INPUT_MODALITY_PROPERTIES_ANDROID
};
XrSystemProperties base = {
  .type = XR_TYPE_SYSTEM_PROPERTIES,
  .next = &props
};
CHK_XR(xrGetSystemProperties(instance, systemId, &base));

uint32_t blendModeCount = 0;
CHK_XR(
 xrEnumerateEnvironmentBlendModes(instance, systemId, viewType, 0, &blendModeCount, nullptr));
std::vector<XrEnvironmentBlendMode> supportedBlendModes(blendModeCount);
CHK_XR(
  xrEnumerateEnvironmentBlendModes(
    instance, systemId, viewType, blendModeCount, &blendModeCount, supportedBlendModes.data()));

XrRecommendedSettingsANDROID output = {
  .type = XR_TYPE_RECOMMENDED_SETTINGS_ANDROID
};

XrResult result = xrGetRecommendedSettingsANDROID(instance, systemId, &output);

if (result == XR_SUCCESS) {
  // We now know the current state of the default environment as recommended settings

  bool correctBlendMode = false;
  for(XrEnvironmentBlendMode blendMode : supportedBlendModes) {
    if (blendMode == output.blendMode) {
      correctBlendMode = true;
      break;
    }
  }
  assert(correctBlendMode);
  assert((~props.supportedInputModalities & output.activeInputModalities) == 0);
}

Новые команды

Новые структуры

Новые перечисления

Новые битовые маски

Новые константы перечисления

  • XR_ANDROID_RECOMMENDED_SETTINGS_EXTENSION_NAME
  • XR_ANDROID_recommended_settings_SPEC_VERSION

  • Расширение XrStructureType :

    • XR_TYPE_RECOMMENDED_SETTINGS_ANDROID
    • XR_TYPE_SYSTEM_INPUT_MODALITY_PROPERTIES_ANDROID

Проблемы

История версий

  • Версия 3, 16 марта 2026 г. (Салар Хан)

    • Расширение стало общедоступным, модальности ввода стали битами флагов, а название расширения изменено на XR_ANDROID_recommended_settings .

  • Версия 2, 28 марта 2025 г. (Салар Хан)

    • Измените на ANDROIDX и добавьте passthroughOpacity.

  • Версия 1, 18 февраля 2025 г. (Салар Хан)

    • Создана исходная версия.