رشته نام

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 و گسترش دادن XrSystemProperties با ساختار XrSystemInputModalityPropertiesANDROID هنگام فراخوانی xrGetSystemProperties، تعیین کند که کدام حالت‌های ترکیب و حالت‌های ورودی توسط سیستم پشتیبانی می‌شوند.

ساختار 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);

شرح پارامترها

  • ‫instance یک دسته XrInstance است که قبلاً با xrCreateInstance ایجاد شده است.
  • ‫systemId یک XrSystemId است که قبلاً از xrGetSystem واکشی شده است.
  • ‫output اشاره‌گری به ساختار XrRecommendedSettingsANDROID است که با وضعیت محیط پیش‌فرض برونداد می‌شود.

استفاده معتبر (ضمنی)

کدهای برگشتی

موفقیت‌آمیز بود

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

فرمان‌های جدید

سازه‌های جدید

Enums جدید

ماسک‌های بیتی جدید

ثابت‌های شمارشی جدید

  • 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

مشکلات

سابقه نسخه

  • نسخه ۳،‏ ۲۰۲۶/۰۳/۱۶ (Salar Khan)

    • به عمومی ارتقا یافت، بیت‌های پرچم حالت‌های ورودی ساخته شد، و نام افزونه به XR_ANDROID_recommended_settings تغییر کرد.

  • بازبینی ۲، ۲۰۲۵-۰۳-۲۸ (Salar Khan)

    • به ANDROIDX تغییر کرد و passthroughOpacity اضافه شد.

  • بازبینی ۱، ‎۲۰۲۵-۰۲-۱۸ (سالار خان)

    • نسخه اولیه.