Name String

XR_ANDROID_recommended_settings

Uzantı Türü

Örnek uzantısı

Kayıtlı Dahili Numara

455

Düzeltme

1

Onay Durumu

Onaylanmadı

Uzantı ve Sürüm Bağımlılıkları

OpenXR 1.0

Son Değiştirilme Tarihi

2026-03-16

Katkıda bulunanlar

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

Genel Bakış

Kullanıcının varsayılan ortamı, karışım modu ve giriş yönteminin bir kombinasyonu kullanılarak çeşitli durumlarda olabilir. Bu uzantı, sorunsuz bir geçiş sağlamak için kullanıcıya, uygulama başlatılmadan önce kullanıcının varsayılan ortamının durumuna karşılık gelen önerilen ayarları sağlar.

Yapılar ve Enum Veri Türleri

XrInputModalityFlagsANDROID bitleri, kullanımda olabilecek farklı giriş yöntemlerini tanımlar.

typedef XrFlags64 XrInputModalityFlagsANDROID;

XrInputModalityFlagsANDROID için geçerli bitler, XrInputModalityFlagBitsANDROID tarafından tanımlanır ve şu şekilde belirtilir:

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

İşaret Açıklamaları

  • XR_INPUT_MODALITY_HEAD_BIT_ANDROID: Baş takibi kullanan bir giriş yöntemini gösterir.
  • XR_INPUT_MODALITY_CONTROLLER_BIT_ANDROID: Herhangi bir XR kumanda girişini kullanan bir giriş yöntemini belirtir.
  • XR_INPUT_MODALITY_HANDS_BIT_ANDROID: El takibini kullanan bir giriş yöntemini belirtir.
  • XR_INPUT_MODALITY_MOUSE_BIT_ANDROID: Fare girişlerini kullanan bir giriş yöntemini belirtir.
  • XR_INPUT_MODALITY_GAZE_AND_GESTURE_BIT_ANDROID: Göz takibi ve el takibini birleştiren bir giriş yöntemini belirtir.

XrRecommendedSettingsANDROID yapısı şu şekilde tanımlanır:

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

Üye Açıklamaları

  • type, bu yapının XrStructureType değeridir.
  • next, NULL veya bir yapı zincirindeki sonraki yapıya işaret eden bir göstergedir. Temel OpenXR'da veya bu uzantıda bu tür yapılar tanımlanmamıştır.
  • blendMode, uygulama başlatılmadan hemen önce varsayılan ortamın karışım modunu gösteren bir XrEnvironmentBlendMode'dur.
  • passthroughOpacity, uygulama başlatılmadan hemen önce varsayılan ortamın geçiş opaklığını gösteren bir float değeridir. Çalışma zamanı, OST cihazları için bu değeri (1,0 - dimming_value) olarak ayarlamalıdır.
  • activeInputModalities, uygulama başlatılmadan hemen önce varsayılan ortamda kullanılan giriş yöntemlerini gösteren bir XrInputModalityFlagsANDROID bit maskesidir.

Geçerli Kullanım (Dolaylı)

Desteklenen ortam durumlarını listeleme

Uygulamalar, xrEnumerateEnvironmentBlendModes ile sistem tarafından desteklenen karışım modunu ve giriş yöntemi durumlarını belirleyebilir. Ayrıca xrGetSystemProperties çağrılırken XrSystemProperties, XrSystemInputModalityPropertiesANDROID yapısıyla genişletilebilir.

XrSystemInputModalityPropertiesANDROID yapısı şu şekilde tanımlanır:

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

Üye Açıklamaları

  • type, bu yapının XrStructureType değeridir.
  • next, NULL veya bir yapı zincirindeki sonraki yapıya işaret eden bir göstergedir. Temel OpenXR'da veya bu uzantıda bu tür yapılar tanımlanmamıştır.
  • supportedInputModalities, sistem tarafından desteklenen giriş yöntemlerini belirten bir veya daha fazla XrInputModalityFlagsANDROID'dir.

Geçerli Kullanım (Dolaylı)

Önerilen ayarları alma (lansman öncesi varsayılan ortam durumu)

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

Parametre Açıklamaları

Geçerli Kullanım (Dolaylı)

Dönüş Kodları

Başarılı

  • XR_SUCCESS

Hata

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SYSTEM_INVALID

Önerilen ayarlar için örnek kod

Aşağıdaki örnek kodda, desteklenen giriş modalitelerinin nasıl alınacağı, önerilen ayarların nasıl alınacağı ve bildirilen ayarların sistem tarafından desteklendiğinin nasıl onaylanacağı gösterilmektedir.

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

Yeni Komutlar

Yeni Yapılar

Yeni Enum Veri Türleri

Yeni Bit Maskeleri

Yeni Enum Sabitleri

  • XR_ANDROID_RECOMMENDED_SETTINGS_EXTENSION_NAME
  • XR_ANDROID_recommended_settings_SPEC_VERSION

  • XrStructureType'ı genişletme:

    • XR_TYPE_RECOMMENDED_SETTINGS_ANDROID
    • XR_TYPE_SYSTEM_INPUT_MODALITY_PROPERTIES_ANDROID

Sorunlar

Sürüm Geçmişi

  • 3. düzeltme, 16.03.2026 (Salar Khan)

    • Herkese açık olarak tanıtıldı, giriş modaliteleri işaret bitleri yapıldı ve uzantı adı XR_ANDROID_recommended_settings olarak değiştirildi.

  • Düzeltme 2, 28.03.2025 (Salar Khan)

    • ANDROIDX olarak değiştirildi ve passthroughOpacity eklendi.

  • Düzeltme 1, 18.02.2025 (Salar Khan)

    • İlk sürüm.