XR_ANDROID_enumerate_system_extension_properties

名稱字串

XR_ANDROID_enumerate_system_extension_properties

擴充功能類型

執行個體擴充功能

擴充功能註冊編號

725

修訂版本

1

批准狀態

未批准

擴充功能和版本依附元件

OpenXR 1.0

上次修改日期

2026-02-11

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，或是指向結構鏈中下一個結構的指標。
  • properties 是具有擴充功能名稱的 XrExtensionProperties。
  • isSupported：布林值，指出系統目前是否支援擴充功能。

有效用量 (隱含)

  • 必須先啟用 XR_ANDROID_enumerate_system_extension_properties 擴充功能，才能使用 XrSystemExtensionPropertiesANDROID
  • type 必須為 XR_TYPE_SYSTEM_EXTENSION_PROPERTIES_ANDROID
  • next 必須是 NULL，或是指向結構體鏈結中下一個結構體的有效指標

XrEventDataSystemPropertiesChangedANDROID 結構體的定義如下：

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

成員說明

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

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

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

應用程式收到這項事件時，應再次呼叫 xrEnumerateSystemExtensionPropertiesANDROID，判斷最新的系統擴充功能屬性，並視需要建立或銷毀與這些擴充功能相關聯的追蹤器。

有效用量 (隱含)

  • 使用 XrEventDataSystemPropertiesChangedANDROID 前，XR_ANDROID_enumerate_system_extension_properties 擴充功能必須啟用
  • type 必須為 XR_TYPE_EVENT_DATA_SYSTEM_PROPERTIES_CHANGED_ANDROID
  • next 必須是 NULL，或是指向結構體鏈結中下一個結構體的有效指標

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 年 3 月 17 日 (Kenny Vercaemer)

    • 擴充功能初始版本。