Name String

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 のビットマスクで、アプリの起動直前にデフォルト環境で使用されている入力モダリティを示します。

有効な使用方法（暗黙的）

  • XrRecommendedSettingsANDROID を使用する前に、XR_ANDROID_recommended_settings 拡張機能を有効にする必要があります。
  • type は XR_TYPE_RECOMMENDED_SETTINGS_ANDROID にする必要があります。
  • next は、NULL または構造体チェーン内の次の構造体への有効なポインタでなければなりません。
  • blendMode は、有効な XrEnvironmentBlendMode 値でなければなりません
  • activeInputModalities は、XrInputModalityFlagBitsANDROID 値の有効な組み合わせでなければなりません。
  • activeInputModalities は 0 にしないでください

サポートされている環境状態の列挙

アプリケーションは、xrEnumerateEnvironmentBlendModes を使用して、システムでサポートされているブレンドモードと入力モダリティの状態を判断できます。また、xrGetSystemProperties を呼び出すときに、XrSystemInputModalityPropertiesANDROID 構造体を使用して XrSystemProperties を拡張することもできます。

XrSystemInputModalityPropertiesANDROID 構造体は次のように定義されます。

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

メンバーの説明

  • type は、この構造の XrStructureType です。
  • next は、NULL または構造体チェーン内の次の構造体へのポインタです。このような構造体は、コア OpenXR またはこの拡張機能では定義されていません。
  • supportedInputModalities は、システムでサポートされている入力モダリティを示す 1 つ以上の 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-03-28（Salar Khan）

    • ANDROIDX に変更し、passthroughOpacity を追加しました。

  • リビジョン 1、2025-02-18（Salar Khan）

    • 初期バージョン。