XR_ANDROID_enumerate_system_extension_properties

رشته نام

XR_ANDROID_enumerate_system_extension_properties

نوع افزونه

افزونه نمونه

شماره داخلی ثبت‌شده

725

بازبینی

1

وضعیت تصویب

تصویب‌نشده

وابستگی‌های افزونه و نسخه

OpenXR 1.0

تاریخ آخرین تغییر

2026-02-11

وضعیت 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 است، یا ۰ برای نشان دادن درخواست بازیابی ظرفیت موردنیاز.
  • propertyCountOutput تعداد ویژگی‌های افزونه درخواستی است.
  • ‫properties آرایه‌ای از ساختارهای XrSystemExtensionPropertiesANDROID است. اگر propertyCapacityInput برابر با ۰ باشد، می‌تواند NULL باشد.
  • برای شرح مفصل بازیابی اندازه properties موردنیاز، بخش پارامترهای اندازه میان‌گیر را ببینید.

استفاده معتبر (ضمنی)

  • افزونه XR_ANDROID_enumerate_system_extension_properties باید قبل‌از فراخوانی xrEnumerateSystemExtensionPropertiesANDROID فعال شود
  • instance باید شناسه XrInstance معتبری باشد
  • propertyCountOutput باید اشاره‌گری به مقدار uint32_t باشد
  • اگر propertyCapacityInput برابر با 0 نباشد، properties باید اشاره‌گری به آرایه‌ای از ساختارهای propertyCapacityInput XrSystemExtensionPropertiesANDROID باشد

کدهای برگشتی

موفقیت‌آمیز بود

  • 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()
);

مشکلات

سابقه نسخه

  • بازبینی ۱،‏ ۲۰۲۶/۰۳/۱۷ (Kenny Vercaemer)

    • نسخه اولیه افزونه.