XR_ANDROID_performance_metrics OpenXR 扩展

名称字符串

XR_ANDROID_performance_metrics

扩展程序类型

实例扩展

已注册的扩展号码

466

上次修改日期

2024-09-06

IP 状态

没有已知的 IP 版权主张。

扩展程序和版本依赖项

OpenXR 1.0

创作贡献者

Dmitry Kotov，Google

Levana Chen，Google

Jared Finder，Google

Spencer Quin，Google

概览

此扩展程序提供了用于枚举和查询当前 XR 设备、合成器和 XR 应用的各种性能指标计数器的 API。开发者可以使用收集的性能指标计数器对 XR 应用执行性能分析并进行有针对性的优化。应用不应根据计数器读取情况更改其行为。

性能指标计数器会整理为根路径 /perfmetrics_android 下的预定义 XrPath 值。应用可以通过 xrEnumeratePerformanceMetricsCounterPathsANDROID 查询可用的计数器。以下是 Android 设备上可能会提供的性能指标计数器路径的列表：

  • /perfmetrics_android/app/cpu_frametime（毫秒，浮点值）- 客户端处理一个帧所花费的实际时间。
  • /perfmetrics_android/app/gpu_frametime（毫秒，浮点值）- 客户端在等待 GPU 工作完成所花费的每帧时钟时间。注意：
    • 等待时间过长可能表示 GPU 正忙于处理其他任务，而不一定表示此客户端执行的 GPU 工作过多。
    • 如果在合成器检查时渲染已完成，GPU 等待时间可以为零。
  • /perfmetrics_android/app/cpu_utilization（百分比，浮点值）- 一段时间内的平均应用 CPU 利用率。
    • 在多核处理器上，该值可以高于 100%。
  • /perfmetrics_android/app/gpu_utilization（百分比）- 一段时间内的应用总 GPU 利用率平均值。
  • /perfmetrics_android/app/motion_to_photon_latency（毫秒，浮点值）- 从用户发起动作事件到显示屏上相应实体图片更新所花费的时间。
  • /perfmetrics_android/compositor/cpu_frametime（毫秒，浮点值）- 合成器处理一帧所花费的实际时间。
  • /perfmetrics_android/compositor/gpu_frametime（毫秒，浮点值）- 每帧 compositor 等待 GPU 工作完成所花费的实际时间。
  • /perfmetrics_android/compositor/dropped_frame_count（整数）- 所有应用丢弃的帧总数。
  • /perfmetrics_android/compositor/frames_per_second（浮点值）- 每秒在设备上绘制的合成器帧数。
  • /perfmetrics_android/device/cpu_utilization_average（百分比，浮点值）- 所有核心在一段时间内的平均 CPU 利用率。
  • /perfmetrics_android/device/cpu_utilization_worst（百分比，浮点值）- 一段时间内性能最差的核心的设备 CPU 利用率的平均值。
  • /perfmetrics_android/device/cpu0_utilization 到 /perfmetrics_android/device/cpuX_utilization（百分比，浮点数，X 是 CPU 核心数减 1）- 一段时间内每个 CPU 核心的设备 CPU 利用率的平均值。
  • /perfmetrics_android/device/cpu_frequency（MHz，浮点值）- 所有核心在一段时间内的平均设备 CPU 频率。
  • /perfmetrics_android/device/gpu_utilization（百分比，浮点值）- 一段时间内的设备 GPU 利用率平均值。

创建会话后，应用可以使用 xrSetPerformanceMetricsStateANDROID 为该会话启用性能指标系统。应用可以使用 xrQueryPerformanceMetricsCounterANDROID 查询启用了性能指标系统的会话中的性能指标计数器，也可以使用 xrGetPerformanceMetricsStateANDROID 查询性能指标系统是否处于启用状态。

如需启用此扩展程序的功能，应用应使用 XrInstanceCreateInfo::enabledExtensionNames 参数将扩展程序的名称传递给 xrCreateInstance，如扩展程序部分所述。

新增标志类型

typedef XrFlags64 XrPerformanceMetricsCounterFlagsANDROID;

// Flag bits for XrPerformanceMetricsCounterFlagsANDROID
static const XrPerformanceMetricsCounterFlagsANDROID XR_PERFORMANCE_METRICS_COUNTER_ANY_VALUE_VALID_BIT_ANDROID = 0x00000001;
static const XrPerformanceMetricsCounterFlagsANDROID XR_PERFORMANCE_METRICS_COUNTER_UINT_VALUE_VALID_BIT_ANDROID = 0x00000002;
static const XrPerformanceMetricsCounterFlagsANDROID XR_PERFORMANCE_METRICS_COUNTER_FLOAT_VALUE_VALID_BIT_ANDROID = 0x00000004;

新的枚举常量

XrStructureType 枚举已扩展为：

  • XR_TYPE_PERFORMANCE_METRICS_STATE_ANDROID
  • XR_TYPE_PERFORMANCE_METRICS_COUNTER_ANDROID

新的枚举

typedef enum XrPerformanceMetricsCounterUnitANDROID {
    XR_PERFORMANCE_METRICS_COUNTER_UNIT_GENERIC_ANDROID = 0,
    XR_PERFORMANCE_METRICS_COUNTER_UNIT_PERCENTAGE_ANDROID = 1,
    XR_PERFORMANCE_METRICS_COUNTER_UNIT_MILLISECONDS_ANDROID = 2,
    XR_PERFORMANCE_METRICS_COUNTER_UNIT_BYTES_ANDROID = 3,
    XR_PERFORMANCE_METRICS_COUNTER_UNIT_HERTZ_ANDROID = 4
} XrPerformanceMetricsCounterUnitANDROID;

新结构

XrPerformanceMetricsStateANDROID 结构定义如下：

typedef struct XrPerformanceMetricsStateANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           enabled;
} XrPerformanceMetricsStateANDROID;

成员说明

  • type 是此结构的 XrStructureType。
  • next 是 NULL 或指向结构链中下一个结构的指针。核心 OpenXR 或此扩展中未定义任何此类结构。
  • 获取状态时，enabled 设置为 XR_TRUE 表示性能指标系统处于启用状态，否则为 XR_FALSE。设置状态时，设置为 XR_TRUE 可启用效果指标系统，设置为 XR_FALSE 可停用该系统。

调用 xrSetPerformanceMetricsStateANDROID 以启用或停用性能指标系统时，会将 XrPerformanceMetricsStateANDROID 作为输入提供。调用 xrGetPerformanceMetricsStateANDROID 以查询性能指标系统是否已启用时，系统会将 XrPerformanceMetricsStateANDROID 填充为输出参数。

有效用法（隐式）

  • 必须先启用 XR_ANDROID_performance_metrics 扩展，然后才能使用 XrPerformanceMetricsStateANDROID
  • type 必须为 XR_TYPE_PERFORMANCE_METRICS_STATE_ANDROID
  • next 必须为 NULL 或指向结构链中下一个结构的有效指针

XrPerformanceMetricsCounterANDROID 结构的定义如下：

typedef struct XrPerformanceMetricsCounterANDROID {
    XrStructureType                            type;
    void*                                      next;
    XrPerformanceMetricsCounterFlagsANDROID    counterFlags;
    XrPerformanceMetricsCounterUnitANDROID     counterUnit;
    uint32_t                                   uintValue;
    float                                      floatValue;
} XrPerformanceMetricsCounterANDROID;

成员说明

  • type 是此结构的 XrStructureType。
  • next 是 NULL 或指向结构链中下一个结构的指针。核心 OpenXR 或此扩展中未定义任何此类结构。
  • counterFlags 是 XrPerformanceMetricsCounterFlagsANDROID 的位掩码，用于描述值成员的有效性。
  • counterUnit 是 XrPerformanceMetricsCounterUnitANDROID 的枚举，用于描述测量单位。
  • uintValue 是采用 uint32_t 格式的计数器值。如果 counterFlags 包含 XR_PERFORMANCE_METRICS_COUNTER_UINT_VALUE_VALID_BIT_ANDROID，则有效。
  • floatValue 是采用 float 格式的计数器值。如果 counterFlags 包含 XR_PERFORMANCE_METRICS_COUNTER_FLOAT_VALUE_VALID_BIT_ANDROID，则有效。

通过调用 xrQueryPerformanceMetricsCounterANDROID 来查询实时性能指标计数器信息，从而填充 XrPerformanceMetricsCounterANDROID。

有效用法（隐式）

新函数

xrEnumeratePerformanceMetricsCounterPathsANDROID 函数会枚举运行时支持的所有性能指标计数器路径，其定义如下：

XrResult xrEnumeratePerformanceMetricsCounterPathsANDROID(
    XrInstance                                  instance,
    uint32_t                                    counterPathCapacityInput,
    uint32_t*                                   counterPathCountOutput,
    XrPath*                                     counterPaths);

参数说明

  • instance 是之前使用 xrCreateInstance 创建的 XrInstance 句柄。
  • counterPathCapacityInput 是 counterPaths 数组的容量，或 0，表示请求检索所需的容量。
  • 如果 counterPathCapacityInput 不足，运行时会使用已写入的 counterPaths 数量或所需容量来填充 counterPathCountOutput。
  • counterPaths 是由运行时填充的 XrPath 数组，其中包含所有可用的效果指标计数器，但如果 counterPathCapacityInput 为 0，则可以为 NULL。
  • 如需详细了解如何检索所需的 counterPaths 大小，请参阅缓冲区大小参数部分。

有效用法（隐式）

  • 必须先启用 XR_ANDROID_performance_metrics 扩展程序，然后才能调用 xrEnumeratePerformanceMetricsCounterPathsANDROID
  • instance 必须是有效的 XrInstance 句柄
  • counterPathCountOutput 必须是指向 uint32_t 值的指针
  • 如果 counterPathCapacityInput 不为 0，counterPaths 必须是指向 counterPathCapacityInput 个 XrPath 值的数组的指针

返回代码

成功

  • XR_SUCCESS

失败

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_VALIDATION_FAILURE
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SIZE_INSUFFICIENT

xrSetPerformanceMetricsStateANDROID 函数的定义如下：

XrResult xrSetPerformanceMetricsStateANDROID(
    XrSession                                   session,
    const XrPerformanceMetricsStateANDROID*     state);

参数说明

xrSetPerformanceMetricsStateANDROID 函数用于启用或停用性能指标系统。

有效用法（隐式）

返回代码

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失败

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_VALIDATION_FAILURE
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST

xrGetPerformanceMetricsStateANDROID 函数的定义如下：

XrResult xrGetPerformanceMetricsStateANDROID(
    XrSession                                   session,
    XrPerformanceMetricsStateANDROID*           state);

参数说明

xrGetPerformanceMetricsStateANDROID 函数用于获取性能指标系统的当前状态。

有效用法（隐式）

返回代码

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失败

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_VALIDATION_FAILURE
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST

xrQueryPerformanceMetricsCounterANDROID 函数的定义如下：

XrResult xrQueryPerformanceMetricsCounterANDROID(
    XrSession                                   session,
    XrPath                                      counterPath,
    XrPerformanceMetricsCounterANDROID*         counter);

参数说明

xrQueryPerformanceMetricsCounterANDROID 函数用于查询性能指标计数器。

在使用 xrQueryPerformanceMetricsCounterANDROID 查询指标之前，应用应先通过调用 xrSetPerformanceMetricsStateANDROID 来启用性能指标系统。

有效用法（隐式）

返回代码

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失败

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_VALIDATION_FAILURE
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_PATH_UNSUPPORTED
  • XR_ERROR_PATH_INVALID