Name String

XR_ANDROID_recommended_settings

擴充功能類型

執行個體擴充功能

擴充功能註冊編號

455

修訂版本

1

批准狀態

未批准

擴充功能和版本依附元件

OpenXR 1.0

上次修改日期

2026-03-16

著作人

Google 的 Spencer Quin
Google 的 Jared Finder
Google 的 Kevin Moule
Google 的 Nihav Jain
Google 的 Levana Chen
Google 的 Alvin Shi
Google 的 Salar Khan

總覽

使用者的預設環境可以處於多種狀態，具體取決於混合模式和輸入模式的組合。這項擴充功能會根據使用者在啟動應用程式前的預設環境狀態，提供建議設定，確保轉換過程順暢。

結構體和列舉

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-03-16 (Salar Khan)

    • 升級為公開、將輸入模態設為標記位元，並將擴充功能名稱變更為 XR_ANDROID_recommended_settings。

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

    • 變更為 ANDROIDX，並加入 passthroughOpacity。

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

    • 初始版本。