Строка имени

XR_ANDROID_recommended_settings

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

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

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

455

Пересмотр

1

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

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

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

OpenXR 1.0

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

2026-03-16

Авторы

Спенсер Куин, Google
Джаред Финдер, Google
Кевин Моул, Google
Нихав Джайн, Google
Левана Чен, Google
Элвин Ши, Google
Салар Хан, 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 и указывает значение прозрачности среды по умолчанию непосредственно перед запуском приложения. Для устройств OST среда выполнения должна установить это значение равным (1.0 - dimming_value).
  • 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.03.2026 (Салар Хан)

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

  • Редакция 2, 28.03.2025 (Салар Хан)

    • Переключитесь на ANDROIDX и включите параметр passthroughOpacity.

  • Редакция 1, 18.02.2025 (Салар Хан)

    • Начальная версия.