XR_ANDROID_enumerate_system_extension_properties

Name String

XR_ANDROID_enumerate_system_extension_properties

نوع الإضافة

إضافة مثيل

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

725

المراجعة

1

حالة التصديق

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

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

OpenXR 1.0

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

2026-02-11

حالة الملكية الفكرية

ما مِن مطالبات معروفة بشأن الملكية الفكرية.

المساهمون

سبنسر كوين، Google
نيهاف جاين، Google
كيني فيركايمر، 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

رموز الإرجاع

Success

  • XR_SUCCESS

تعذّر الإجراء

  • 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-03-2026 (كيني فيركايمر)

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