XR_ANDROID_enumerate_system_extension_properties

Name String

XR_ANDROID_enumerate_system_extension_properties

Loại phần mở rộng

Tiện ích Instance

Số máy nhánh đã đăng ký

725

Bản sửa đổi

1

Trạng thái phê chuẩn

Chưa được phê chuẩn

Phần mở rộng và các phần phụ thuộc của phiên bản

OpenXR 1.0

Ngày sửa đổi gần đây nhất

2026-02-11

Trạng thái IP

Không có thông báo xác nhận quyền sở hữu nào đã biết về quyền sở hữu trí tuệ.

Cộng tác viên

Spencer Quin, Google
Nihav Jain, Google
Kenny Vercaemer, Google

Tổng quan

Tiện ích này cho phép các ứng dụng xác định những tiện ích được cấu hình hệ thống hiện tại hỗ trợ. Ngay cả khi được thời gian chạy hỗ trợ, một tiện ích có thể không được phần cứng hệ thống hiện tại hỗ trợ.

Cấu trúc XrSystemExtensionPropertiesANDROID được xác định như sau:

typedef struct XrSystemExtensionPropertiesANDROID {
    XrStructureType          type;
    void*                    next;
    XrExtensionProperties    properties;
    XrBool32                 isSupported;
} XrSystemExtensionPropertiesANDROID;

Nội dung mô tả thành viên

  • typeXrStructureType của cấu trúc này.
  • nextNULL hoặc con trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc.
  • propertiesXrExtensionProperties có tên tiện ích.
  • isSupported là một giá trị boolean cho biết liệu hệ thống hiện có hỗ trợ tiện ích này hay không.

Sử dụng hợp lệ (Ngầm ẩn)

Cấu trúc XrEventDataSystemPropertiesChangedANDROID được xác định như sau:

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

Nội dung mô tả thành viên

  • typeXrStructureType của cấu trúc này.
  • nextNULL hoặc con trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc.

Thời gian chạy phải xếp hàng sự kiện này khi các thuộc tính của tiện ích hệ thống đã thay đổi. Ví dụ: khi các thiết bị ngoại vi mới được kết nối, chức năng mới sẽ được bật.

Tất cả các lệnh gọi đến xrEnumerateSystemExtensionPropertiesANDROID phải trả về cùng một giá trị cho đến khi một sự kiện XrEventDataSystemPropertiesChangedANDROID mới được đưa vào hàng đợi.

Khi nhận được sự kiện này, ứng dụng phải gọi lại xrEnumerateSystemExtensionPropertiesANDROID để xác định các thuộc tính mới nhất của tiện ích hệ thống, có thể tạo hoặc huỷ các trình theo dõi được liên kết với những tiện ích đó khi cần.

Sử dụng hợp lệ (Ngầm ẩn)

Hàm xrEnumerateSystemExtensionPropertiesANDROID được xác định như sau:

XrResult xrEnumerateSystemExtensionPropertiesANDROID(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    propertyCapacityInput,
    uint32_t*                                   propertyCountOutput,
    XrSystemExtensionPropertiesANDROID*         properties);

Nội dung mô tả về tham số

  • instance là một XrInstance hợp lệ .
  • systemId là một sliink:XrSystemId hợp lệ của hệ thống để truy xuất các thuộc tính của tiện ích.
  • propertyCapacityInput là dung lượng của mảng properties hoặc 0 để cho biết yêu cầu truy xuất dung lượng cần thiết.
  • propertyCountOutput là số lượng thuộc tính tiện ích được yêu cầu.
  • properties là một mảng gồm các cấu trúc XrSystemExtensionPropertiesANDROID. Giá trị này có thểNULL nếu propertyCapacityInput là 0.
  • Hãy xem phần Tham số kích thước bộ nhớ đệm để biết nội dung mô tả chi tiết về cách truy xuất kích thước properties cần thiết.

Sử dụng hợp lệ (Ngầm ẩn)

  • Bạn phải bật tiện ích XR_ANDROID_enumerate_system_extension_properties trước khi gọi xrEnumerateSystemExtensionPropertiesANDROID
  • instance phải là một đối tượng XrInstance hợp lệ
  • propertyCountOutput phải là con trỏ đến giá trị uint32_t
  • Nếu propertyCapacityInput không phải là 0 , thì properties phải là con trỏ đến một mảng gồm propertyCapacityInput cấu trúc XrSystemExtensionPropertiesANDROID

Mã trả về

Thành công

  • XR_SUCCESS

Thất bại

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SYSTEM_INVALID
  • XR_ERROR_VALIDATION_FAILURE

Ví dụ

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

Vấn đề

Danh sách phiên bản

  • Bản sửa đổi 1, ngày 17/3/2026 (Kenny Vercaemer)

    • Phiên bản tiện ích ban đầu.