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

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

概览

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

性能指标计数器以预定义的 XrPath 值组织，位于根路径 /perfmetrics_android 下。应用可以通过 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 （毫秒，浮点型）- 合成器每帧等待 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 核心数减一）- 设备每 CPU 核心利用率（随时间平均）。
/perfmetrics_android/device/cpu_frequency （兆赫，浮点型）- 设备 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 作为输出参数填充。

有效用法（隐式）

使用 XrPerformanceMetricsStateANDROID 之前必须启用 XR_ANDROID_performance_metrics 扩展。
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。

有效用法（隐式）

使用 XrPerformanceMetricsCounterANDROID 之前必须启用 XR_ANDROID_performance_metrics 扩展。
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 表示请求检索所需容量。
counterPathCountOutput 由运行时填充，其中包含写入的 counterPaths 计数，或者在 counterPathCapacityInput 不足的情况下填充所需容量。
counterPaths 是一个由运行时填充的 XrPath 数组，其中包含所有可用的性能指标计数器，但如果 counterPathCapacityInput 为 0，则可以为 NULL。
有关检索所需 counterPaths 大小的详细说明，请参阅“缓冲区大小参数”部分。

有效用法（隐式）

调用 xrEnumeratePerformanceMetricsCounterPathsANDROID 之前必须启用 XR_ANDROID_performance_metrics 扩展。
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 函数用于启用或禁用性能指标系统。

有效用法（隐式）

调用 xrSetPerformanceMetricsStateANDROID 之前必须启用 XR_ANDROID_performance_metrics 扩展。
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 函数获取性能指标系统的当前状态。

有效用法（隐式）

调用 xrGetPerformanceMetricsStateANDROID 之前必须启用 XR_ANDROID_performance_metrics 扩展。
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 启用性能指标系统。

有效用法（隐式）

调用 xrQueryPerformanceMetricsCounterANDROID 之前必须启用 XR_ANDROID_performance_metrics 扩展。
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 徽标是 The Khronos Group Inc. 拥有的商标，并在中国、欧盟、日本和英国注册为商标。

XR_ANDROID_performance_metrics OpenXR 扩展 利用收藏集保持井然有序 根据您的偏好保存和分类内容。

概览

新标志类型

新枚举常量

新枚举

新结构体

成员说明

有效用法（隐式）

成员说明

有效用法（隐式）

新函数

参数说明

有效用法（隐式）

返回代码

参数说明

有效用法（隐式）

返回代码

参数说明

有效用法（隐式）

返回代码

参数说明

有效用法（隐式）

返回代码

XR_ANDROID_performance_metrics OpenXR 扩展