AGI のトラブルシューティング

このトピックでは、Android GPU Inspector（AGI）を使用する際の一般的な問題を解決する方法について説明します。

AGI 設定をリセットする

AGI の設定は ~/.agic ファイルに保存されます。このファイルを削除すると、最近開いたトレースとデバイス検証結果のリストなど、すべての AGI 設定が削除されます。

一部のデバイスで AGI が失敗する

設定がすべての要件を満たしていることを確認してください。

次の方法も役立ちます。

  • Android Studio など、ADB を介してデバイスを操作する可能性があるプログラムをすべて停止します。

  • スリープモードが原因でデバイスの画面がオフになったときに発生する問題を防ぐために、（Android の開発者向けオプションで）Stay awake オプションを有効にします。

システム プロファイラが OpenGL ES ゲームの GPU アクティビティをレポートしない

現在、OpenGL ES アプリをトレースする際は、GPU カウンタのみがサポートされています。OpenGL ES アプリの GPU アクティビティに関する情報は現在開発中です。

一部の Vulkan ゲームでフレーム プロファイラが失敗する

まず、ゲームで Vulkan が正しく使用されていることを確認します。Vulkan 検証レイヤを使用して、ゲームからエラーや警告が出ないことを確認します。

Vulkan 検証エラーがある場合、AGI フレーム プロファイラは機能しません。

フレーム プロファイラ トレースの作成時にゲームが失敗する

ゲームが AGI なしで正常に実行されるものの、フレーム プロファイル トレースの作成時に実行できない場合、ゲームは起動シーケンス中に別のプロセスをフォークしている可能性があります。その場合、トレースするプロセスの名前をトレース オプションの [プロセス名] フィールドに指定する必要があります。

この問題を特定するには、トレースの作成時に logcat 出力を調べて、別のプロセスが開始されているかどうかを確認します。

# Clear the logcat output
adb logcat -c

## Use AGI to attempt to create a frame profile trace

Look at the logcat output to identify the processes that are running AGI. 

adb logcat | grep "this process name"
I GAPID   : gapii [gapii/cc/spy.cpp:109] this process name: com.example.mygame
I GAPID   : gapii [gapii/cc/spy.cpp:109] this process name: com.example.mygame:GameProcess

ほとんどのゲームにはプロセスが 1 つしかありません。上記の例は、複数のプロセスがあるゲームで想定される動作を示しています。

ゲームは com.example.mygame というメインプロセスで開始し、com.example.mygame:GameProcess という新しいプロセスをフォークします。実際のゲーム レンダリングが 2 番目のプロセスで行われる場合は、これがトレースするプロセスであることを AGI に伝える必要があります。これを行うには、トレース オプション ダイアログの Process name フィールドにプロセスの名前を入力します。

AGI を使用した後のゲームエラー

トレースが適切に終了しない場合、AGI は一部の Android 設定のまま、その後のアプリの実行を妨げる可能性があります。設定は次のとおりです。

  • Vulkan レイヤ関連の設定:

    • enable_gpu_debug_layers

    • gpu_debug_app

    • gpu_debug_layers

    • gpu_debug_layer_app

  • ANGLE 関連の設定:

    • angle_debug_package

    • angle_gl_driver_selection_values

    • angle_gl_driver_selection_pkgs

AGI の使用後にアプリで問題が発生した場合は、次の adb コマンドを使用してこれらの設定を消去してみてください。

# Vulkan layers
adb shell settings delete global enable_gpu_debug_layers
adb shell settings delete global gpu_debug_app
adb shell settings delete global gpu_debug_layers
adb shell settings delete global gpu_debug_layer_app
# ANGLE
adb shell settings delete global angle_debug_package
adb shell settings delete global angle_gl_driver_selection_values
adb shell settings delete global angle_gl_driver_selection_pkgs

フレーム プロファイル トレースの作成時に AGI 経由でゲームを起動すると、ゲームの表示が変わる

フレーム プロファイル トレースを作成するために、AGI はゲームによって行われたグラフィック API 呼び出しをインターセプトします。これにより、ゲームのレンダリングに影響が及ぶ可能性があります。

AGI は Vulkan 呼び出しをキャプチャします。OpenGL ES ゲームの場合、AGI は ANGLE を使用して OpenGL ES を Vulkan に変換します。AGI 経由でゲームを起動したときにゲームの外観が異なる場合（色が期待どおりでないなど）は、AGI または ANGLE のバグである可能性があります。以下をお試しください。

Vulkan ゲーム: サポートされているすべての Vulkan 拡張機能を使用したトレース

[不明な拡張機能を含める] トレース オプションでは、AGI でサポートされていない Vulkan 拡張機能を含めるかどうかを制御します。（サポートされている拡張機能のリストをご覧ください）。

AGI でサポートされていない拡張機能をアプリで使用している場合、トレースをリプレイする際に、微妙なエラーやクラッシュなど、望ましくない動作が発生する可能性があります。

このオプションを有効にしてから、別のフレーム プロファイラ トレースを起動してみてください。このオプションを有効にしてゲームが想定どおりに表示される場合、ゲームは AGI でサポートされていない Vulkan 拡張機能に依存している可能性があります。

OpenGL ES ゲーム: ANGLE のみで実行する

ANGLE を使用しても AGI を使用せずに OpenGL ES ゲームを実行して、間違ったレンダリングが ANGLE の問題にあるかどうかを確認できます。

OpenGL ES ゲームのフレーム プロファイル トレースを作成しようとした場合、AGI は ANGLE をデバイスにすでにインストールしています。AGI で使用される ANGLE パッケージの名前は org.chromium.angle.agi です。

ゲームを ANGLE で強制的に実行するには、次のコマンドを使用します。

# Make sure that the AGI capture layer will be ignored
adb shell settings delete global enable_gpu_debug_layers
# Force the package com.example.mygame to use ANGLE
adb shell settings put global angle_debug_package org.chromium.angle.agi
adb shell settings put global angle_gl_driver_selection_values angle
adb shell settings put global angle_gl_driver_selection_pkgs com.example.mygame

これらの設定でゲームの表示が異なる場合は、AGI ではなく AGLE のバグであると考えられます。これらの設定でゲームが正しく表示されるものの、AGI トレースの作成中に外観が異なる場合は、AGI のバグである可能性があります。

AGI のバグは、GitHub の問題を作成することで報告できます。