Name String

XR_ANDROID_recommended_settings

نوع الإضافة

إضافة مثيل

رقم الإضافة المسجَّل

455

المراجعة

1

حالة التصديق

لم تتم المصادقة عليها

الاعتماد على الإضافات والإصدارات

OpenXR 1.0

تاريخ آخر تعديل

2026-03-16

المساهمون

سبنسر كوين، Google
جاريد فايندر، Google
كيفن مول، Google
نيهاف جاين، Google
ليفانا تشن، Google
ألفين شي، Google
سالار خان، 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_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 يشير إلى معدّل شفافية البيئة التلقائية قبل تشغيل التطبيق مباشرةً. يجب أن يضبط وقت التشغيل هذه القيمة على (1.0 - dimming_value) لأجهزة OST.
  • ‫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 التي يتم إخراجها مع حالة البيئة التلقائية.

الاستخدام الصالح (ضمني)

رموز الإرجاع

Success

  • 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، بتاريخ ‎16-03-2026 (سالار خان)

    • تمت ترقية هذه الفئة إلى فئة علنية، وتم إنشاء وحدات بت لعلامات أساليب الإدخال، وتم تغيير اسم الإضافة إلى XR_ANDROID_recommended_settings .

  • المراجعة 2، بتاريخ 28 مارس 2025 (سالار خان)

    • تم التغيير إلى ANDROIDX وتضمين passthroughOpacity.

  • المراجعة 1، في ‎18-02-2025 (سالار خان)

    • الإصدار الأولي