XR_ANDROID_enumerate_system_extension_properties

מחרוזת שם

XR_ANDROID_enumerate_system_extension_properties

סוג התוסף

הרחבת המכונה

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

725

Revision

1

סטטוס האישור

לא אושר

תלות בתוסף ובגרסה

OpenXR 1.0

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

2026-02-11

סטטוס כתובת ה-IP

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

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

ספנסר קווין (Spencer Quin),‏ Google
ניחב ג'יין (Nihav Jain),‏ Google
קני ורקרמר (Kenny Vercaemer),‏ Google

סקירה כללית

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

המבנה XrSystemExtensionPropertiesANDROID מוגדר כך:

typedef struct XrSystemExtensionPropertiesANDROID {
    XrStructureType          type;
    void*                    next;
    XrExtensionProperties    properties;
    XrBool32                 isSupported;
} XrSystemExtensionPropertiesANDROID;

תיאורי חברים

  • type הוא XrStructureType של המבנה הזה.
  • next הוא NULL או מצביע למבנה הבא בשרשרת מבנים.
  • properties הוא XrExtensionProperties עם שם התוסף.
  • isSupported הוא ערך בוליאני שמציין אם המערכת תומכת כרגע בתוסף.

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

המבנה XrEventDataSystemPropertiesChangedANDROID מוגדר כך:

typedef struct XrEventDataSystemPropertiesChangedANDROID {
    XrStructureType    type;
    const void*        next;
} XrEventDataSystemPropertiesChangedANDROID;

תיאורי חברים

  • type הוא XrStructureType של המבנה הזה.
  • next הוא NULL או מצביע למבנה הבא בשרשרת מבנים.

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

כל הקריאות אל xrEnumerateSystemExtensionPropertiesANDROID חייבות להחזיר את אותם ערכים עד שאירוע חדש של XrEventDataSystemPropertiesChangedANDROID מתווסף לתור.

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

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

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

XrResult xrEnumerateSystemExtensionPropertiesANDROID(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    propertyCapacityInput,
    uint32_t*                                   propertyCountOutput,
    XrSystemExtensionPropertiesANDROID*         properties);

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

  • instance הוא XrInstance תקין .
  • systemId הוא sliink:XrSystemId תקין של המערכת שממנה יאוחזרו מאפייני התוסף.
  • propertyCapacityInput הוא הקיבולת של המערך properties, או 0 כדי לציין בקשה לאחזור הקיבולת הנדרשת.
  • propertyCountOutput הוא מספר המאפיינים המבוקשים של התוסף.
  • properties הוא מערך של מבני XrSystemExtensionPropertiesANDROID. הערך יכול להיות NULL אם propertyCapacityInput הוא 0.
  • בקטע פרמטרים של גודל המאגר מפורט תיאור של אחזור הגודל הנדרש של properties.

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

  • התוסף XR_ANDROID_enumerate_system_extension_properties חייב להיות מופעל לפני הקריאה ל-xrEnumerateSystemExtensionPropertiesANDROID
  • instance חייב להיות ידית XrInstance תקינה
  • propertyCountOutput חייב להיות מצביע לערך uint32_t
  • אם propertyCapacityInput הוא לא 0 , ‏ properties חייב להיות מצביע למערך של מבני propertyCapacityInput XrSystemExtensionPropertiesANDROID

קודי החזרה

הצלחה

  • XR_SUCCESS

Failure

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

דוגמה

XrInstance instance; // XrInstance previously created

XrSystemId systemId; // XrSystemId from a previously created instance

PFN_xrEnumerateSystemExtensionPropertiesANDROID xrEnumerateSystemExtensionPropertiesANDROID;

// Poll events for recommended resolution changes.
XrEventDataBuffer event = {XR_TYPE_EVENT_DATA_BUFFER};
XrResult result = xrPollEvent(instance, &event);

if (result == XR_SUCCESS) {
    switch (event.type) {
        case XR_TYPE_EVENT_DATA_SYSTEM_PROPERTIES_CHANGED_ANDROID:
            // It's possible that the system was lost and a new id will be returned
            XrSystemId newSystemId;
            XrSystemGetInfo getInfo = {XR_TYPE_SYSTEM_GET_INFO};
            getInfo.formFactor = XR_FORM_FACTOR_HEAD_MOUNTED_DISPLAY;
            if(XR_SUCCESS == xrGetSystem(instance, &getInfo, &newSystemId)) {
                if(systemId != newSystemId) {
                    //Do things like recreate the session
                    systemId = newSystemId;
                }
            }

            // Enumerate the extensions to see which ones are now supported based on hardware changes
            uint32_t extensionsCount;
            xrEnumerateSystemExtensionPropertiesANDROID(instance, systemId, 0, &extensionsCount, NULL);

            std::vector<XrSystemExtensionPropertiesANDROID> properties(extensionsCount,
                {.type = XR_TYPE_SYSTEM_EXTENSION_PROPERTIES_ANDROID});

            XrResult result = xrEnumerateSystemExtensionPropertiesANDROID(
                instance,
                systemId,
                extensionsCount,
                &extensionsCount,
                properties.data()
            );

            // Do something based on which extensions are now supported by the system
            break;
    }
}
PFN_xrEnumerateSystemExtensionPropertiesANDROID xrEnumerateSystemExtensionPropertiesANDROID;

XrInstance instance;
XrInstanceCreateInfo createInfo = {XR_TYPE_INSTANCE_CREATE_INFO};
// Initialize the createInfo with appropriate values for the application
CHK_XR(xrCreateInstance(&createInfo, &instance));

// Get the systemId for the system.
XrSystemId systemId;
XrSystemGetInfo getInfo = {XR_TYPE_SYSTEM_GET_INFO};
getInfo.formFactor = XR_FORM_FACTOR_HEAD_MOUNTED_DISPLAY;
CHK_XR(xrGetSystem(instance, &getInfo, &systemId));

// Enumerate the system extension properties.
uint32_t extensionsCount;
xrEnumerateSystemExtensionPropertiesANDROID(instance, systemId, 0, &extensionsCount, NULL);

std::vector<XrSystemExtensionPropertiesANDROID> properties(extensionsCount,
    {.type = XR_TYPE_SYSTEM_EXTENSION_PROPERTIES_ANDROID});

XrResult result = xrEnumerateSystemExtensionPropertiesANDROID(
    instance,
    systemId,
    extensionsCount,
    &extensionsCount,
    properties.data()
);

בעיות

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

  • גרסה 1, ‏17 במרץ 2026 (Kenny Vercaemer)

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