XR_ANDROID_performance_metrics OpenXR 拡張機能

Name String

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（ミリ秒、浮動小数点数）- コンポジタが GPU 処理の完了を待機したフレームあたりの壁時計時間。
  • /perfmetrics_android/compositor/dropped_frame_count（整数）- すべてのアプリでドロップされたフレームの合計数。
  • /perfmetrics_android/compositor/frames_per_second（浮動小数点数）- デバイスで 1 秒間に描画されるコンポジタ フレーム数。
  • /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 に設定します。

XrPerformanceMetricsStateANDROID は、xrSetPerformanceMetricsStateANDROID を呼び出してパフォーマンス指標システムを有効または無効にするときに入力として提供されます。XrPerformanceMetricsStateANDROID は、xrGetPerformanceMetricsStateANDROID を呼び出してパフォーマンス指標システムが有効かどうかをクエリするときに、出力パラメータとして入力されます。

有効な使用方法（暗黙的）

  • 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 が含まれている場合に有効です。

XrPerformanceMetricsCounterANDROID は、xrQueryPerformanceMetricsCounterANDROID を呼び出してリアルタイムのパフォーマンス指標カウンタ情報をクエリすることで入力されます。

有効な使用方法（暗黙的）

新しい関数

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

パラメータの説明

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