XR_ANDROID_enumerate_system_extension_properties

رشته نام

XR_ANDROID_enumerate_system_extension_properties

نوع افزونه

افزونه نمونه

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

۷۲۵ عدد

بازنگری

۱

وضعیت تصویب

تصویب نشده

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

اوپن‌ایکس‌آر ۱.۰

آخرین تاریخ اصلاح

۲۰۲۶-۰۲-۱۱

وضعیت آی‌پی

هیچ ادعای مالکیت معنوی شناخته‌شده‌ای وجود ندارد.

مشارکت‌کنندگان

اسپنسر کوئین، گوگل
نیهاو جین، گوگل
کنی ورکامر، گوگل

نمای کلی

این افزونه به برنامه‌ها اجازه می‌دهد تا مشخص کنند کدام افزونه‌ها توسط پیکربندی فعلی سیستم پشتیبانی می‌شوند. حتی اگر یک افزونه توسط زمان اجرا پشتیبانی شود، ممکن است توسط سخت‌افزار فعلی سیستم پشتیبانی نشود.

ساختار 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 است. اگر 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()
);

مسائل

تاریخچه نسخه

  • نسخه ۱، ۲۰۲۶-۰۳-۱۷ (کنی ورکامر)

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