String Nama

XR_ANDROID_recommended_settings

Jenis Ekstensi

Ekstensi instance

Nomor Ekstensi Terdaftar

455

Revisi

1

Status Ratifikasi

Belum diratifikasi

Dependensi Ekstensi dan Versi

OpenXR 1.0

Tanggal Terakhir Diubah

2026-03-16

Kontributor

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

Ringkasan

Lingkungan default pengguna dapat berada dalam berbagai status menggunakan kombinasi mode penggabungan dan modalitas input. Ekstensi ini memberikan setelan yang direkomendasikan untuk pengguna, yang sesuai dengan status lingkungan default pengguna sebelum peluncuran aplikasi, untuk memastikan transisi yang lancar.

Struct dan Enum

Bit XrInputModalityFlagsANDROID mengidentifikasi berbagai modalitas input yang mungkin sedang digunakan.

typedef XrFlags64 XrInputModalityFlagsANDROID;

Bit yang valid untuk XrInputModalityFlagsANDROID ditentukan oleh XrInputModalityFlagBitsANDROID , yang ditentukan sebagai:

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

Deskripsi Flag

  • XR_INPUT_MODALITY_HEAD_BIT_ANDROID — Menunjukkan modalitas input yang menggunakan pelacakan gerak kepala.
  • XR_INPUT_MODALITY_CONTROLLER_BIT_ANDROID — Menunjukkan modalitas input yang menggunakan input pengontrol XR apa pun.
  • XR_INPUT_MODALITY_HANDS_BIT_ANDROID — Menunjukkan modalitas input yang menggunakan pelacakan gerak tangan.
  • XR_INPUT_MODALITY_MOUSE_BIT_ANDROID — Menunjukkan modalitas input yang menggunakan input mouse.
  • XR_INPUT_MODALITY_GAZE_AND_GESTURE_BIT_ANDROID — Menunjukkan modalitas input yang menggabungkan pelacakan gerak mata dan pelacakan gerak tangan.

Struktur XrRecommendedSettingsANDROID didefinisikan sebagai:

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

Deskripsi Anggota

  • type adalah XrStructureType dari struktur ini.
  • next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur. Tidak ada struktur seperti itu yang ditentukan dalam OpenXR inti atau ekstensi ini.
  • blendMode adalah XrEnvironmentBlendMode yang menunjukkan mode penggabungan lingkungan default tepat sebelum peluncuran aplikasi.
  • passthroughOpacity adalah float yang menunjukkan opasitas passthrough lingkungan default tepat sebelum peluncuran aplikasi. Runtime harus menetapkan nilai ini ke (1.0 - dimming_value) untuk perangkat OST.
  • activeInputModalities adalah bitmask XrInputModalityFlagsANDROID yang menunjukkan modalitas input yang digunakan dalam lingkungan default tepat sebelum peluncuran aplikasi.

Penggunaan yang Valid (Implisit)

Menghitung status lingkungan yang didukung

Aplikasi dapat menentukan status mode penggabungan dan modalitas input yang didukung oleh sistem dengan xrEnumerateEnvironmentBlendModes dan memperluas XrSystemProperties dengan struktur XrSystemInputModalityPropertiesANDROID saat memanggil xrGetSystemProperties .

Struktur XrSystemInputModalityPropertiesANDROID didefinisikan sebagai:

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

Deskripsi Anggota

  • type adalah XrStructureType dari struktur ini.
  • next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur. Tidak ada struktur seperti itu yang ditentukan dalam OpenXR inti atau ekstensi ini.
  • supportedInputModalities adalah satu atau beberapa XrInputModalityFlagsANDROID yang menunjukkan modalitas input yang didukung oleh sistem.

Penggunaan yang Valid (Implisit)

Mendapatkan setelan yang direkomendasikan (status lingkungan default prapeluncuran)

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

Deskripsi Parameter

Penggunaan yang Valid (Implisit)

Kode Status

Berhasil

  • XR_SUCCESS

Kegagalan

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SYSTEM_INVALID

Contoh kode untuk setelan yang direkomendasikan

Kode contoh berikut menunjukkan cara mendapatkan modalitas input yang didukung, mendapatkan setelan yang direkomendasikan, dan menegaskan bahwa setelan yang dilaporkan didukung oleh sistem.

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

Perintah Baru

Struktur Baru

Enum Baru

Bitmask Baru

Konstanta Enum Baru

  • XR_ANDROID_RECOMMENDED_SETTINGS_EXTENSION_NAME
  • XR_ANDROID_recommended_settings_SPEC_VERSION

  • Memperluas XrStructureType :

    • XR_TYPE_RECOMMENDED_SETTINGS_ANDROID
    • XR_TYPE_SYSTEM_INPUT_MODALITY_PROPERTIES_ANDROID

Masalah

Histori Versi

  • Revisi 3, 16-03-2026 (Salar Khan)

    • Dipromosikan ke publik, membuat bit flag modalitas input, dan mengubah nama ekstensi menjadi XR_ANDROID_recommended_settings .

  • Revisi 2, 28-03-2025 (Salar Khan)

    • Ubah ke ANDROIDX dan sertakan passthroughOpacity.

  • Revisi 1, 18-02-2025 (Salar Khan)

    • Versi awal.