This topic describes how to fix common issues when using Android GPU Inspector (AGI) .
Resetting AGI settings
AGI stores its settings in the ~/.agic file.
Removing this file deletes all AGI settings, including the list of
recently opened traces and device validation results.
AGI fails on some devices
Please make sure that your setup meets all the requirements.
The following can also help:
Stop any program that may interact with the device over ADB, such as Android Studio.
Enable the
Stay awakeoption (under Developer options on Android) to prevent issues that arise when the device screen turns off due to sleep mode.
System profiler doesn't report GPU activity for OpenGL ES games
Currently, only GPU counters are supported when you trace an OpenGL ES application. GPU activity information for OpenGL ES applications is under active development.
Frame profiler fails on some Vulkan games
The first thing to verify is that your game uses Vulkan correctly. Use the Vulkan validation layer and make sure that your game raises no errors or warnings.
If there is any Vulkan validation error, then AGI frame profiler is not expected to work.
Game failure when creating a frame profiler trace
If the game runs successfully without AGI but fails to run when creating a frame profile trace, the game might be forking a different process during its startup sequence. In that case, you need to specify the name of the process to trace in the "Process name" field in trace options.
To identify this issue, you can check the logcat output while you create a trace and verify whether a different process is starting:
# 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
Most games have only one process, the example above shows what to expect for a game that has more than one process.
The game starts in a main process named com.example.mygame, and then forks a
new process named com.example.mygame:GameProcess.
If the actual game rendering happens in the second process, then you must tell
AGI that this is the process you want to trace.
You can do so by entering the name of the process in the Process name field of
the trace option dialog.
Game failure after using AGI
If a trace does not terminate properly, AGI may leave some Android settings in a state that may interrupt subsequent runs of the app. These settings are:
Vulkan layers related settings:
enable_gpu_debug_layersgpu_debug_appgpu_debug_layersgpu_debug_layer_app
ANGLE related settings:
angle_debug_packageangle_gl_driver_selection_valuesangle_gl_driver_selection_pkgs
If your app has any issues after using AGI, you can try clearing these settings with the following adb commands:
# 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
Your game looks different when launching it via AGI while creating a frame profile trace
To create a frame profile trace, AGI intercepts the graphics API calls made by the game, which may affect the game renderings.
AGI captures Vulkan calls. For OpenGL ES games, AGI relies on ANGLE to translate OpenGL ES to Vulkan. If your game looks different (e.g. some colors are not the ones you expect) when you launch it via AGI, it is probably a bug in AGI or ANGLE. You can help us get a better understanding of the root cause of the issue by trying the following.
Vulkan games: trace with all Vulkan extensions supported
The Include Unknown Extensions tracing option controls whether AGI should include Vulkan extensions it does not support. (Browse a list of supported extensions.)
If your app uses an extension that isn't supported by AGI, you might encounter undesirable behavior, including subtle errors or crashes, when replaying the trace.
Try enabling this option, then launch another frame profiler trace. If the game displays as expected with the option is enabled, the game may rely on a Vulkan extension that is not supported by AGI.
OpenGL ES games: run with ANGLE only
You can run your OpenGL ES game with ANGLE but without AGI to see if the wrong rendering comes from an issue in ANGLE.
If you already tried to create a frame profile trace of your OpenGL ES
game, then AGI already installed ANGLE on your device. The ANGLE package used by
AGI is named org.chromium.angle.agi.
To force your game to run on ANGLE, use the following commands:
# 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
If the game looks different with these settings, then it is probably a bug in ANGLE, and not AGI. If the game looks correct with these settings, but looks different while creating an AGI trace, then it is probably a bug in AGI.
You can report AGI bugs by creating a GitHub issue.