מחרוזת שם

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.
  • 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 חדשים

מסכות סיביות חדשות

קבועי 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

בעיות

היסטוריית גרסאות

  • גרסה 3, 16 במרץ 2026 (סאלאר חאן)

    • הועלה לציבורי, הפך את אופני הקלט לסיביות דגל ושינה את שם התוסף ל-XR_ANDROID_recommended_settings .

  • גרסה 2, 28 במרץ 2025 (סאלאר חאן)

    • שינוי ל-ANDROIDX ו-passthroughOpacity כלול.

  • גרסה 1, 18.02.2025 (סאלאר חאן)

    • הגרסה הראשונית.