XR_ANDROID_enumerate_system_extension_properties

Chuỗi tên

XR_ANDROID_enumerate_system_extension_properties

Loại tiện ích

Tiện ích thực thể

Số tiện ích đã đăng ký

725

Bản sửa đổi

1

Trạng thái phê chuẩn

Chưa phê chuẩn

Tiện ích và các phần phụ thuộc vào phiên bản

OpenXR 1.0

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

2026-02-11

Trạng thái SHTT

Không có thông báo xác nhận quyền sở hữu SHTT nào được biết.

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 một tiện ích được thời gian chạy hỗ trợ, thì 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;

Mô tả thành phần

  • typeXrStructureType của cấu trúc này.
  • nextNULL hoặc một con trỏ 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 tiện ích có được hệ thống hiện tại hỗ trợ hay không.

Cách sử dụng hợp lệ (Ngụ ý)

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

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

Mô tả thành phần

  • typeXrStructureType của cấu trúc này.
  • nextNULL hoặc một con trỏ 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 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, cho phép chức năng mới.

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 xếp hàng.

Khi nhận được sự kiện này, ứng dụng nên gọi lại xrEnumerateSystemExtensionPropertiesANDROID để xác định các thuộc tính tiện ích hệ thống mới nhất, 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 đó nếu cần.

Cách sử dụng hợp lệ (Ngụ ý)

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

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

Mô tả 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 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ố thuộc tính tiện ích được yêu cầu.
  • properties là một mảng 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 vùng đệ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.

Cách sử dụng hợp lệ (Ngụ ý)

  • 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 trình xử lý XrInstance hợp lệ
  • propertyCountOutput phải là một con trỏ trỏ đến giá trị uint32_t
  • Nếu propertyCapacityInput không phải là 0 , thì properties phải là một con trỏ trỏ đến một mảng các cấu trúc propertyCapacityInput XrSystemExtensionPropertiesANDROID

Mã trả về

Thành công

  • XR_SUCCESS

Failure

  • 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 đề

Nhật ký phiên bản

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

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