XR_ANDROID_global_passthrough_dimming

מחרוזת שם

XR_ANDROID_global_passthrough_dimming

סוג התוסף

תוסף למכונה

מספר השלוחה הרשום

797

גרסה

1

סטטוס האישור

לא אושר

תלויות של תוספים וגרסאות

OpenXR 1.0

תאריך השינוי האחרון

2026-03-10

סטטוס IP

אין תלונות ידועות על הפרת קניין רוחני.

שותפים ביצירת התוכן

בריאן צ'ן, Google
קייל צ'ן, Google
ניהב ג'יין, Google
ספנסר קווין, Google

סקירה כללית

ככל שמוצגים מכשירים אופטיים שקופים, חשוב לא רק לאפשר לאפליקציות להתאים את הכהות של המעבר כדי לספק למשתמש את השילוב הטוב ביותר עם ההקשר של האפליקציה, אלא גם לאפשר למערכת להבהיר את המעבר מטעמי בטיחות.

התוסף הזה מספק שתי פונקציות לאפליקציות כדי להגדיר ולקבל את רמת העמעום הנוכחית, וגם אירוע לשידור כשמשתנה רמת העמעום.

בדיקת יכולות המערכת

המבנה של XrSystemGlobalDimmingPropertiesANDROID מוגדר כך:

typedef struct XrSystemGlobalDimmingPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsGlobalDimming;
} XrSystemGlobalDimmingPropertiesANDROID;

תיאורי חברים

  • ‫type הוא ה-XrStructureType של המבנה הזה.
  • ‫next הוא NULL או מצביע למבנה הבא בשרשרת מבנים. מבנים כאלה לא מוגדרים ב-OpenXR או בתוסף הזה. מבנים כאלה לא מוגדרים ב-OpenXR או בתוסף הזה.
  • ‫supportsGlobalDimming הוא XrBool32 , שמציין אם המערכת הנוכחית תומכת בעמעום גלובלי.

אפליקציה יכולה לבדוק אם המערכת תומכת בעמעום גלובלי על ידי שרשור של מבנה XrSystemGlobalDimmingPropertiesANDROID אל XrSystemProperties כשקוראים ל-xrGetSystemProperties .

אם זמן הריצה מחזיר את הערך XR_FALSE עבור supportsGlobalDimming , זמן הריצה חייב להחזיר את הערך XR_ERROR_FEATURE_UNSUPPORTED כשמתבצעת קריאה ל-xrGetGlobalDimmingLevelANDROID.

שימוש תקין (משתמע)

ספירת רמות העמעום הגלובליות הנתמכות

המבנה של xrEnumerateSupportedGlobalDimmingLevelsANDROID מוגדר כך:

XrResult xrEnumerateSupportedGlobalDimmingLevelsANDROID(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    supportedGlobalDimmingLevelCapacityInput,
    uint32_t*                                   supportedGlobalDimmingLevelCountOutput,
    float*                                      supportedGlobalDimmingLevels);

תיאורי חברים

  • ‫instance הוא המכונה שממנה אוחזר systemId.
  • ‫systemId הוא ה-XrSystemId שהרמות הנתמכות שלו יפורטו.
  • ‫supportedGlobalDimmingLevelCapacityInput הוא הקיבולת של המערך supportedGlobalDimmingLevels, או 0 כדי לציין בקשה לאחזור הקיבולת הנדרשת.
  • ‫supportedGlobalDimmingLevelCountOutput הוא מצביע למספר של supportedGlobalDimmingLevels שנכתבו, או מצביע לקיבולת הנדרשת במקרה ש-supportedGlobalDimmingLevelCapacityInput לא מספיק.
  • ‫supportedGlobalDimmingLevels הוא מצביע למערך של רמות נתמכות, אבל יכול להיות NULL אם supportedGlobalDimmingLevelCapacityInput הוא 0.

אם הערך המוחזר של supportedGlobalDimmingLevelCountOutput הוא 0, כל רמות העמעום הגלובליות בין 0.0 ל-1.0 נתמכות.

‫xrEnumerateSupportedGlobalDimmingLevelsANDROID סופר את רמות העמעום הגלובליות שנתמכות על ידי XrSystemId . הרמות הנתמכות לא יכולות להשתנות במהלך משך החיים של XrInstance . רשימת הרמות שמוחזרת חייבת להיות ממוינת בסדר עולה.

סביבות זמן ריצה חייבות תמיד להחזיר תוכן מאגר זהה מהספירה הזו עבור systemId נתון ולמשך כל משך החיים של instance .

שימוש תקין (משתמע)

  • חובה להפעיל את התוסף XR_ANDROID_global_passthrough_dimming לפני שמפעילים את xrEnumerateSupportedGlobalDimmingLevelsANDROID
  • ‫ instance חייב להיות כינוי תקין של XrInstance
  • supportedGlobalDimmingLevelCountOutput חייב להיות מצביע לערך uint32_t
  • אם supportedGlobalDimmingLevelCapacityInput הוא לא 0, אז supportedGlobalDimmingLevels חייב להיות מצביע למערך של ערכי float מסוג supportedGlobalDimmingLevelCapacityInput

קודי החזרה

הצלחה

  • XR_SUCCESS

נכשל

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SYSTEM_INVALID
  • XR_ERROR_VALIDATION_FAILURE

הגדרת רמת העמעום הכללי

המבנה של XrGlobalDimmingFrameEndInfoANDROID מוגדר כך:

typedef struct XrGlobalDimmingFrameEndInfoANDROID {
    XrStructureType    type;
    const void*        next;
    float              globalDimmingLevel;
} XrGlobalDimmingFrameEndInfoANDROID;

תיאורי פרמטרים

  • ‫type הוא ה-XrStructureType של המבנה הזה.
  • ‫next הוא NULL או מצביע למבנה הבא בשרשרת מבנים. מבנים כאלה לא מוגדרים ב-OpenXR או בתוסף הזה.
  • ‫globalDimmingLevel הוא ערך בין 0.0 (שקוף) ל-1.0 (אטום). יכול להיות שסביבת זמן הריצה תמפה את הערך הזה לרמה הקרובה ביותר של עמעום גלובלי שנתמכת. האפליקציה יכולה להגדיר את הערך הזה ל-‎-1.0 כדי לציין שרמת העמעום הנוכחית מועדפת.

הערך globalDimmingLevel מציין את אחוז האור שנחסם, כאשר הערך 0.0 תואם ל-0% חסימת אור והערך 1.0 תואם ל-100% חסימת אור. באופן כללי, אפשר לייצג את אחוז האור החסום כך:

100% - Light Transmittance%

אפשר למדוד את אחוז העברת האור, לפי ISO 8980-3:2022 , בתור היחס בין שטף הקרינה המועבר לבין שטף הקרינה הפוגע באורכי גל של אור נראה (380nm עד 780nm).

‫XrGlobalDimmingFrameEndInfoANDROID הוא מבנה שאפליקציה יכולה לשרשר ב-XrFrameEndInfo כדי לבקש רמה מועדפת של עמעום גלובלי.

זמן הריצה חייב לכבד את רמת העמעום המבוקשת אם היא שונה מרמת העמעום הנוכחית.

לסביבת זמן הריצה תהיה שליטה על רמת העמעום הגלובלית, והיא עשויה להתעלם מרמת העמעום הגלובלית המועדפת מטעמי בטיחות.

שימוש תקין (משתמע)

הפונקציה xrGetGlobalDimmingLevelANDROID מוגדרת כך:

XrResult xrGetGlobalDimmingLevelANDROID(
    XrSession                                   session,
    float*                                      dimmingLevel);

תיאורי פרמטרים

  • ‫session הוא כינוי תקין של XrSession.
  • ‫dimmingLevel הוא מצביע לרמת העמעום הנוכחית.

הערך המוחזר של dimmingLevel חייב להיות בין 0.0 ל-1.0, כאשר 0.0 מציין שקיפות מלאה ו-1.0 מציין עמעום מלא.

אם רמת העמעום לא הוגדרה, זמן הריצה חייב להגדיר את רמת העמעום ל-0.0 כשמצב Passthrough מופעל, ול-1.0 כשמצב Passthrough מושבת.

שימוש תקין (משתמע)

  • חובה להפעיל את התוסף XR_ANDROID_global_passthrough_dimming לפני שקוראים לפונקציה xrGetGlobalDimmingLevelANDROID
  • ‫ session חייב להיות כינוי תקין של XrSession
  • dimmingLevel חייב להיות מצביע לערך float

קודי החזרה

הצלחה

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

נכשל

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

אירוע של שינוי רמת העמעום

המבנה של XrEventDataGlobalDimmingLevelChangedANDROID מוגדר כך:

typedef struct XrEventDataGlobalDimmingLevelChangedANDROID {
    XrStructureType    type;
    const void*        next;
    XrSession          session;
} XrEventDataGlobalDimmingLevelChangedANDROID;

תיאורי חברים

  • ‫type הוא ה-XrStructureType של המבנה הזה.
  • ‫next הוא NULL או מצביע למבנה הבא בשרשרת מבנים. מבנים כאלה לא מוגדרים ב-OpenXR או בתוסף הזה.
  • ‫session הוא כינוי תקין של XrSession.

האפליקציה יכולה לאחזר את האירוע הזה באמצעות xrPollEvent . האירוע הזה יישלח כשרמת העמעום תשתנה על ידי אפליקציות או כפתורים פיזיים במכשירים.

האירוע הזה לא יישלח כשהאפליקציה שבמוקד תתחלף באפליקציה אחרת.

האפליקציה צריכה להגיב לאירוע על ידי קריאה ל-xrGetGlobalDimmingLevelANDROID כדי לקבל את רמת העמעום החדשה ולעדכן את XrGlobalDimmingFrameEndInfoANDROID :: globalDimmingLevel בהתאם. התגובה לאירוע מבטיחה שזמן הריצה יקבל אות כשהאפליקציה תשנה את רמת העמעום המועדפת.

שימוש תקין (משתמע)

קוד לדוגמה

בדיקת יכולת המערכת ופירוט רמות העמעום הגלובליות הנתמכות

הקוד לדוגמה הבא מדגים איך לבדוק אם יש תמיכה בעמעום גלובלי.

XrInstance instance; // previously initialized
XrSystemId systemId; // previously initialized

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrEnumerateSupportedGlobalDimmingLevelsANDROID xrEnumerateSupportedGlobalDimmingLevelsANDROID;

XrSystemGlobalDimmingPropertiesANDROID dimmingControlSystemProperties { XR_TYPE_SYSTEM_GLOBAL_DIMMING_PROPERTIES_ANDROID };

XrSystemProperties systemProperties; // Chain dimmingControlSystemProperties

// ...
// Run xrGetSystemProperties()
// ...

if (!dimmingControlSystemProperties.supportsGlobalDimming) {
  // The system does not support global dimming
  return;
}

// Enumerate supported levels
uint32_t count = 0;
CHK_XR(xrEnumerateSupportedGlobalDimmingLevelsANDROID(instance, systemId, count, &count, nullptr));

std::vector<float> supportedLevels(count);
CHK_XR(xrEnumerateSupportedGlobalDimmingLevelsANDROID(instance, systemId, count, &count, supportedLevels.data()));

אירוע של שינוי רמת העמעום של הסקר

הקוד לדוגמה הבא מדגים איך לבצע סקר של אירוע שינוי רמת העמעום.

XrEventDataBuffer event{ XR_TYPE_EVENT_DATA_BUFFER };

// ...
// Run xrPollEvent()
// ...

switch (event.type) {
  // This event will not be sent when focused app switches
  case XR_TYPE_EVENT_DATA_GLOBAL_DIMMING_LEVEL_CHANGED_ANDROID:
  {
    const XrEventDataGlobalDimmingLevelChangedANDROID &dimmingLevelChangedEvent =
            *reinterpret_cast<XrEventDataGlobalDimmingLevelChangedANDROID *>(&event);

    // Query new dimming level using xrGetGlobalDimmingLevelANDROID()
  }
}

פקודות חדשות

מבנים חדשים

קבועי Enum חדשים

  • XR_ANDROID_GLOBAL_PASSTHROUGH_DIMMING_EXTENSION_NAME
  • XR_ANDROID_global_passthrough_dimming_SPEC_VERSION

  • הרחבה של XrStructureType :

    • XR_TYPE_EVENT_DATA_GLOBAL_DIMMING_LEVEL_CHANGED_ANDROID
    • XR_TYPE_GLOBAL_DIMMING_FRAME_END_INFO_ANDROID
    • XR_TYPE_SYSTEM_GLOBAL_DIMMING_PROPERTIES_ANDROID

בעיות

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

  • גרסה 1, 2025-10-07 (בריאן צ'ן)

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