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 應用程式進行指定最佳化。應用程式「不應」依據計數器讀取值變更行為。

效能指標計數器會在根路徑 /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 (毫秒，浮點值) - 等待 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 核心的 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 填入為輸出參數。

有效用法 (隱含)

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，則表示要求擷取所需容量。
  • counterPathCountOutput 會由執行階段填入，其中包含寫入的 counterPaths 計數，或是在 counterPathCapacityInput 不足的情況下所需的容量。
  • counterPaths 是 XrPath 的陣列，由執行階段填入，其中包含所有可用的成效指標計數器，但如果 counterPathCapacityInput 為 0，則可以為 NULL。
  • 如要進一步瞭解如何擷取所需的 counterPaths 大小，請參閱「緩衝區大小參數」一節。

有效用法 (隱含)

傳回代碼

成功

  • 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