Name String
XR_ANDROID_performance_metrics
拡張機能の種類
インスタンスの拡張
登録されている電話番号
466
最終更新日
2024-09-06
IP ステータス
既知の IP に関する申し立てはありません。
拡張機能とバージョンの依存関係
寄与者
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_ANDROIDXR_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 を呼び出してリアルタイムのパフォーマンス指標カウンタ情報をクエリすることで入力されます。
有効な使用方法（暗黙的）
- 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はcounterPathCapacityInputXrPath値の配列へのポインタである必要があります。
戻りコード
XR_SUCCESS
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_VALIDATION_FAILUREXR_ERROR_RUNTIME_FAILUREXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_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_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_VALIDATION_FAILUREXR_ERROR_RUNTIME_FAILUREXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_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_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_VALIDATION_FAILUREXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_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_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_VALIDATION_FAILUREXR_ERROR_RUNTIME_FAILUREXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_SESSION_LOSTXR_ERROR_PATH_UNSUPPORTEDXR_ERROR_PATH_INVALID