XR_ANDROID_enumerate_system_extension_properties

Name String

XR_ANDROID_enumerate_system_extension_properties

Extension Type

Instance extension

Registered Extension Number

725

Revision

1

Ratification Status

Not ratified

Extension and Version Dependencies

OpenXR 1.0

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

2026-02-11

IP Status

No known IP claims.

المساهمون

Spencer Quin, Google
Nihav Jain, Google
Kenny Vercaemer, Google

نظرة عامة

تسمح هذه الإضافة للتطبيقات بتحديد الإضافات المتوافقة مع إعدادات النظام الحالية. حتى إذا كانت الإضافة متوافقة مع وقت التشغيل، قد لا تكون متوافقة مع أجهزة النظام الحالية.

يتم تعريف بنية XrSystemExtensionPropertiesANDROID على النحو التالي:

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

Member Descriptions

  • type هو XrStructureType لهذه البنية.
  • next هو NULL أو مؤشر إلى البنية التالية في سلسلة البنية.
  • properties هو XrExtensionProperties باسم الإضافة.
  • isSupported هي قيمة منطقية تشير إلى ما إذا كانت الإضافة متوافقة حاليًا مع النظام.

Valid Usage (Implicit)

يتم تعريف بنية XrEventDataSystemPropertiesChangedANDROID على النحو التالي:

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

Member Descriptions

  • type هو XrStructureType لهذه البنية.
  • next هو NULL أو مؤشر إلى البنية التالية في سلسلة البنية.

يجب أن يضع وقت التشغيل هذا الحدث في قائمة الانتظار عند تغيير خصائص إضافة النظام. على سبيل المثال، عند توصيل أجهزة طرفية جديدة تتيح وظائف جديدة.

يجب أن تعرض جميع طلبات xrEnumerateSystemExtensionPropertiesANDROID القيم نفسها إلى أن يتم وضع حدث XrEventDataSystemPropertiesChangedANDROID جديد في قائمة الانتظار.

عندما يتلقّى التطبيق هذا الحدث، يجب أن يعاود طلب xrEnumerateSystemExtensionPropertiesANDROID لتحديد أحدث خصائص إضافة النظام، وربما إنشاء أدوات التتبُّع المرتبطة بهذه الإضافات أو إزالتها حسب الحاجة.

Valid Usage (Implicit)

يتم تعريف الدالة xrEnumerateSystemExtensionPropertiesANDROID على النحو التالي:

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

Parameter Descriptions

  • instance هو XrInstance صالح .
  • systemId هو sliink:XrSystemId صالح للنظام الذي سيتم استرداد خصائص الإضافة له.
  • propertyCapacityInput هي سعة مصفوفة properties، أو 0 للإشارة إلى طلب استرداد السعة المطلوبة.
  • propertyCountOutput هو عدد خصائص الإضافة المطلوبة.
  • properties هي مصفوفة من بُنى XrSystemExtensionPropertiesANDROID. يمكن أن تكون NULL إذا كانت propertyCapacityInput هي 0.
  • راجِع قسم مَعلمات حجم المخزن المؤقت للحصول على وصف تفصيلي لاسترداد حجم properties المطلوب.

Valid Usage (Implicit)

  • يجب تفعيل الإضافة XR_ANDROID_enumerate_system_extension_properties قبل طلب xrEnumerateSystemExtensionPropertiesANDROID
  • instance يجب أن يكون XrInstance مؤشر صالحًا
  • propertyCountOutput يجب أن يكون مؤشرًا إلى قيمة uint32_t
  • إذا لم تكن propertyCapacityInput هي 0 ، properties يجب أن يكون مؤشرًا إلى مصفوفة من بُنى propertyCapacityInput XrSystemExtensionPropertiesANDROID

Return Codes

Success

  • 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، 2026-03-17 (Kenny Vercaemer)

    • الإصدار الأوّلي للإضافة