XR_ANDROID_enumerate_system_extension_properties

名称字符串

XR_ANDROID_enumerate_system_extension_properties

扩展程序类型

实例扩展程序

已注册的扩展程序编号

725

修订版本

1

批准状态

未批准

扩展程序和版本依赖项

OpenXR 1.0

上次修改日期

2026-02-11

IP 状态

没有已知的 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 是一个布尔值，表示系统当前是否支持该扩展程序。

有效用法（隐式）

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

    • 初始扩展程序版本。