XR_ANDROID_enumerate_system_extension_properties

Name String

XR_ANDROID_enumerate_system_extension_properties

Loại tiện ích

Phần mở rộng thực thể

Số máy lẻ đã đăng ký

725

Bản sửa đổi

1

Trạng thái phê chuẩn

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

Phần phụ thuộc của tiện ích và 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ó tuyên bố nào về tài sản 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 tiện ích nào đượ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ợ, 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 định nghĩa như sau:

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

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

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

Cách sử dụng hợp lệ (Ngầm ẩn)

Cấu trúc XrEventDataSystemPropertiesChangedANDROID được định nghĩa như sau:

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

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

  • type là XrStructureType của cấu trúc này.
  • next là NULL hoặc con trỏ trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc.

Môi trường thời gian chạy phải đưa sự kiện này vào hàng đợi 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, cho phép chức năng mới.

Tất 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 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 liên kết với các tiện ích đó nếu cần.

Cách sử dụng hợp lệ (Ngầm ẩn)

Hàm xrEnumerateSystemExtensionPropertiesANDROID được định nghĩa 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 các cấu trúc XrSystemExtensionPropertiesANDROID. Giá trị này có thể là NULL nếu propertyCapacityInput là 0.
  • Hãy xem phần Tham số dung lượng 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.

Cách sử dụng hợp lệ (Ngầm ẩn)

  • Tiện ích XR_ANDROID_enumerate_system_extension_properties phải được bật trước khi gọi xrEnumerateSystemExtensionPropertiesANDROID
  • instance phải là một tên người dù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à một con trỏ đến một mảng gồm các cấu trúc propertyCapacityInput XrSystemExtensionPropertiesANDROID

Mã trả về

Thành công

  • XR_SUCCESS

Không thành công

  • 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 tháng 3 năm 2026 (Kenny Vercaemer)

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