XR_ANDROID_enumerate_system_extension_properties

Name String

XR_ANDROID_enumerate_system_extension_properties

擴充功能類型

執行個體擴充功能

擴充功能註冊編號

725

修訂版本

1

批准狀態

未批准

擴充功能和版本依附元件

OpenXR 1.0

上次修改日期

2026-02-11

IP 狀態

沒有已知的智慧財產權聲明。

著作人


Google 的 Spencer Quin
Google 的 Nihav Jain Google 的 Kenny Vercaemer

總覽

這項擴充功能可讓應用程式判斷目前的系統設定支援哪些擴充功能。即使執行階段支援某個擴充功能，目前的系統硬體可能不支援。

XrSystemExtensionPropertiesANDROID 結構定義如下：

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

成員說明

  • type 是這個結構的 XrStructureType。
  • next 是 NULL，或指向結構鏈中下一個結構的指標。
  • properties 是含有擴充功能名稱的 XrExtensionProperties。
  • isSupported 是布林值，指出系統目前是否支援擴充功能。

有效用途 (隱含)

XrEventDataSystemPropertiesChangedANDROID 結構定義如下：

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

成員說明

  • type 是這個結構的 XrStructureType。
  • next 是 NULL，或指向結構鏈中下一個結構的指標。

系統擴充功能屬性變更時，執行階段必須將這個事件排入佇列。例如連接新周邊裝置，啟用新功能。

在新的 XrEventDataSystemPropertiesChangedANDROID 事件排入佇列前，所有對 xrEnumerateSystemExtensionPropertiesANDROID 的呼叫都必須傳回相同的值。

應用程式收到這個事件時，應再次呼叫 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 結構的陣列。如果 propertyCapacityInput 為 0，則可以是 NULL。
  • 如要進一步瞭解如何擷取必要的 properties 大小，請參閱「緩衝區大小參數」一節。

有效用途 (隱含)

傳回代碼

成功

  • 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)

    • 初始擴充功能版本。