رشته نام

XR_ANDROID_recommended_settings

نوع افزونه

افزونه نمونه

شماره داخلی ثبت شده

۴۵۵

بازنگری

۱

وضعیت تصویب

تصویب نشده

وابستگی‌های افزونه و نسخه

اوپن‌ایکس‌آر ۱.۰

آخرین تاریخ اصلاح

۲۰۲۶-۰۳-۱۶

مشارکت‌کنندگان

اسپنسر کوئین، گوگل
جارد فایندر، گوگل
کوین مول، گوگل
نیهاو جین، گوگل
لوانا چن، گوگل
آلوین شی، گوگل
سالار خان، گوگل

نمای کلی

محیط پیش‌فرض کاربر می‌تواند با استفاده از ترکیبی از حالت ترکیبی و روش ورودی، در حالت‌های مختلفی باشد. این افزونه تنظیمات پیشنهادی را برای کاربر ارائه می‌دهد که مطابق با وضعیت محیط پیش‌فرض کاربر قبل از اجرای برنامه است تا انتقال روان تضمین شود.

ساختارها و Enumها

بیت‌های 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 است که میزان شفافیت محیط پیش‌فرض passthrough را درست قبل از اجرای برنامه نشان می‌دهد. زمان اجرا باید این مقدار را برای دستگاه‌های OST روی (1.0 - dimming_value) تنظیم کند.
  • activeInputModalities یک ماسک بیتی از XrInputModalityFlagsANDROID است که روش‌های ورودی مورد استفاده در محیط پیش‌فرض درست قبل از اجرای برنامه را نشان می‌دهد.

کاربرد معتبر (ضمنی)

شمارش حالت‌های محیطی پشتیبانی‌شده

یک برنامه می‌تواند با استفاده از xrEnumerateEnvironmentBlendModes و با استفاده از ساختار 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);
}

دستورات جدید

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

Enum های جدید

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

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

  • 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

مسائل

تاریخچه نسخه

  • نسخه ۳، ۲۰۲۶-۰۳-۱۶ (سالار خان)

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

  • نسخه ۲، ۲۰۲۵-۰۳-۲۸ (سالار خان)

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

  • نسخه ۱، ۲۰۲۵-۰۲-۱۸ (سالار خان)

    • نسخه اولیه.