Android XR SDK 现已推出开发者预览版。我们期望收到您的反馈！请访问我们的支持页面与我们联系。

此页面由 Cloud Translation API 翻译。

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。

有效用法（隐式）

必须先启用 XR_ANDROID_performance_metrics 扩展程序，然后才能使用 XrPerformanceMetricsCounterANDROID
type 必须为 XR_TYPE_PERFORMANCE_METRICS_COUNTER_ANDROID
next 必须为 NULL 或指向结构链中下一个结构的有效指针
counterFlags 必须为 0 或 XrPerformanceMetricsCounterFlagsANDROID 值的有效组合
counterUnit 必须是有效的 XrPerformanceMetricsCounterUnitANDROID 值

新函数

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

参数说明

session 是之前使用 xrCreateSession 创建的 XrSession 句柄。
state 是指向 XrPerformanceMetricsStateANDROID 结构的指针。

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

有效用法（隐式）

必须先启用 XR_ANDROID_performance_metrics 扩展程序，然后才能调用 xrSetPerformanceMetricsStateANDROID
session 必须是有效的 XrSession 句柄
state 必须是指向有效 XrPerformanceMetricsStateANDROID 结构的指针

返回代码

成功

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

参数说明

session 是之前使用 xrCreateSession 创建的 XrSession 句柄。
state 是指向 XrPerformanceMetricsStateANDROID 结构的指针。

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

有效用法（隐式）

必须先启用 XR_ANDROID_performance_metrics 扩展程序，然后才能调用 xrGetPerformanceMetricsStateANDROID
session 必须是有效的 XrSession 句柄
state 必须是指向 XrPerformanceMetricsStateANDROID 结构的指针

返回代码

成功

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

参数说明

session 是之前使用 xrCreateSession 创建的 XrSession 句柄。
counterPath 是有效的效果指标计数器路径。
counter 是指向 XrPerformanceMetricsCounterANDROID 结构的指针。

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

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

有效用法（隐式）

必须先启用 XR_ANDROID_performance_metrics 扩展程序，然后才能调用 xrQueryPerformanceMetricsCounterANDROID
session 必须是有效的 XrSession 句柄
counter 必须是指向 XrPerformanceMetricsCounterANDROID 结构的指针

返回代码

成功

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

OpenXR™ 和 OpenXR 徽标是 Khronos Group Inc. 拥有的商标，已在中国、欧盟、日本和英国注册为商标。

XR_ANDROID_performance_metrics OpenXR 扩展 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

概览

新增标志类型

新的枚举常量

新的枚举

新结构

成员说明

有效用法（隐式）

成员说明

有效用法（隐式）

新函数

参数说明

有效用法（隐式）

返回代码

参数说明

有效用法（隐式）

返回代码

参数说明

有效用法（隐式）

返回代码

参数说明

有效用法（隐式）

返回代码

XR_ANDROID_performance_metrics OpenXR 扩展