XR_ANDROID_enumerate_system_extension_properties

Name String

XR_ANDROID_enumerate_system_extension_properties

ประเภทส่วนขยาย

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

หมายเลขต่อที่ลงทะเบียน

725

การแก้ไข

1

สถานะการให้สัตยาบัน

ยังไม่ให้สัตยาบัน

การขึ้นต่อกันของส่วนขยายและเวอร์ชัน

OpenXR 1.0

วันที่แก้ไขล่าสุด

2026-02-11

สถานะ IP

ไม่มีการอ้างสิทธิ์ใน 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 หรือ 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 ไปยังอาร์เรย์ของโครงสร้าง 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()
);

ปัญหา

ประวัติเวอร์ชัน

  • ฉบับแก้ไขที่ 1, 17-03-2026 (Kenny Vercaemer)

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