名称字符串

XR_ANDROID_recommended_settings

扩展程序类型

实例扩展程序

已注册的扩展程序编号

455

修订版本

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，表示应用启动前默认环境的透视不透明度。对于 OST 设备，运行时必须将此值设置为 (1.0 - dimming_value)。
  • activeInputModalities 是 XrInputModalityFlagsANDROID 的位掩码，用于指示应用启动前在默认环境中使用的输入模态。

有效用法（隐式）

枚举支持的环境状态

应用可以通过 xrEnumerateEnvironmentBlendModes 确定系统支持哪些混合模式和输入模态状态，并在调用 xrGetSystemProperties 时使用 XrSystemInputModalityPropertiesANDROID 结构扩展 XrSystemProperties。

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);

参数说明

有效用法（隐式）

返回代码

成功

  • 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，2026 年 3 月 16 日 (Salar Khan)

    • 已升级为公开，将输入模态设为标志位，并将扩展名称更改为 XR_ANDROID_recommended_settings。

  • 修订版 2，2025 年 3 月 28 日 (Salar Khan)

    • 更改为 ANDROIDX 并添加了 passthroughOpacity。

  • 修订版 1，2025-02-18 (Salar Khan)

    • 初始版本。