XR_ANDROID_enumerate_system_extension_properties

Name String

XR_ANDROID_enumerate_system_extension_properties

Extension Type

ส่วนขยายอินสแตนซ์

Registered Extension Number

725

Revision

1

Ratification Status

ยังไม่อนุมัติ

Extension and Version Dependencies

OpenXR 1.0

Last Modified Date

2026-02-11

IP Status

ไม่มีการอ้างสิทธิ์ IP ที่ทราบ

Contributors

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 หรือ Pointer ไปยังโครงสร้างถัดไปในเชนโครงสร้าง
  • properties คือ XrExtensionProperties ที่มีชื่อส่วนขยาย
  • isSupported คือบูลีนที่ระบุว่าระบบรองรับส่วนขยายในปัจจุบันหรือไม่

การใช้งานที่ถูกต้อง (โดยนัย)

โครงสร้าง XrEventDataSystemPropertiesChangedANDROID มีการกำหนดไว้ดังนี้

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

คำอธิบายสมาชิก

  • type คือ XrStructureType ของโครงสร้างนี้
  • next คือ NULL หรือ Pointer ไปยังโครงสร้างถัดไปในเชนโครงสร้าง

รันไทม์ต้อง จัดคิวเหตุการณ์นี้เมื่อพร็อพเพอร์ตี้ส่วนขยายระบบมีการเปลี่ยนแปลง เช่น เมื่อมีการเชื่อมต่ออุปกรณ์ต่อพ่วงใหม่ซึ่งทำให้ฟังก์ชันการทำงานใหม่เปิดใช้ได้

การเรียกใช้ 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 ต้อง เป็น Pointer ไปยังค่า uint32_t
  • หาก propertyCapacityInput ไม่ใช่ 0 , properties ต้อง เป็น Pointer ไปยังอาร์เรย์ของโครงสร้าง XrSystemExtensionPropertiesANDROID propertyCapacityInput

รหัสการคืนค่า

สำเร็จ

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

    • ส่วนขยายเวอร์ชันเริ่มต้น