Android GPU Inspector (AGI) is currently in open beta. Learn more.

AGI Frame Profiler

AGI's Frame Profiler allows you to capture a frame of your application to perform an in-depth analysis of your application's GPU usage. AGI will capture your application's Vulkan API calls issued to render the frame and then allow you to inspect the commands as well as the entire state of the Vulkan API, such as textures, shaders, geometries, etc. AGI will replay the captured commands on your Android device and collect profiling data from the GPU, which it will then associate with your command buffers and render passes. This allows you to quickly find bottlenecks in your application and help you improve the GPU performance of your application.

Capture a Frame Profiler Trace

To capture a frame profiler trace, connect a supported Android device and select the Capture a new trace option on AGI startup, or through the File > Capture Trace menu. This opens the trace capture dialog. Once you select your Android device, you can select either Vulkan or OpenGL on ANGLE from the Type list.

Select Vulkan if your application uses the Vulkan API directly, but select OpenGL on ANGLE if your application uses GLES. AGI supports tracing Vulkan only, but supports tracing applications using GLES on top of ANGLE, which will translate the GLES commands to Vulkan commands. AGI uses a special build of ANGLE that will annotate the translated Vulkan commands with extra GLES metadata allowing you to profile and debug your GLES application using AGI.

Frame Profiler Trace Configuration

Once you have selected the appropriate trace type for your application, you need to fill in the remaining sections of the trace configuration dialog. Provide the package, activity, and action of your application to launch in the Application field. The simplest way to do so is to click the ... browse button, which will cause AGI to query your device for installed tracable applications and allow you to select from the list. In the Additional Arguments field, provide additional flags to be passed to the am start-activity command issued to the device to start your application. For more information, consult the help output of adb shell am -h.

In the Start and Duration section, you can choose how to trigger the capturing of the frame in AGI. You have the following options:

  • Beginning: This will cause AGI to capture all the commands from application startup to the end of the first rendered frame.
  • Manual: You will manually trigger the frame capture via a button provided by AGI's tracing dialog.
  • Time: AGI will automatically capture a frame after the given number of seconds have elapsed.
  • Frame: AGI will automatically trigger the capture of the specified n-th frame.

In the Trace Options section you can enable/disable some tracing flags:

  • Disable Buffering: Check this box to disable the in-memory buffering on the device of capture data. This increases the overhead of AGI slightly, but is useful if you are debugging an application crash as it will ensure that all tracing data up to the crash will be serialized.
  • Hide Unknown Extensions: AGI will hide any extensions the Android device may provide, but AGI doesn't understand from the application. Uncheck this to disable this filtering. Note that if the application uses an extension that AGI doesn't support, the resulting trace may not replay propertly.
  • Clear Package Data: Causes AGI to request the Android device clear your application's user data before launching, via pm clear. For more information, consult the help output of adb shell pm.

In the Output section, provide a directory to store trace files in and optionally modify the automatically generated trace file name to your liking.

Trace Capture

To start the capture after all the configuration has been provided, click the OK button. AGI will then setup the environment and launch your application to perform a frame profiler capture, and display a progress dialog. In the progress dialog, you can click the Start button to trigger the frame capture and then optionally press the Stop button to pre-maturely end the capture. Note that if you press the Stop button, the capture may be incomplete rendering the trace file unusable. Once the trace capture has completed, you can open the trace by pressing the Open button.