Technical docs‎ > ‎

GPU Debugger

The GPU Debugger helps you analyze and debug your OpenGL ES apps. It lets you inspect the GPU state and helps you understand what caused a specific rendering outcome. You can start a GPU trace from an app project in Android Studio, as well as an APK, even one created by another IDE. You can then display the GPU trace in the GPU Debugger.

For information about GPU Debugger beta features, see Analyze OpenGL ES Apps with the GPU Debugger. It includes important information about GPU tracing in general, requirements for capturing a trace, how to capture a trace from an Android Studio project, and how to view a saved GPU trace file. This page describes an experimental feature: how to capture a GPU trace from a debuggable APK. Be sure to meet the prerequisites before beginning a GPU trace of an APK.

Preparing an APK for a GPU Trace

To capture a GPU trace from an APK, follow these steps:

  1. Open an Android Studio project.

Although the APK doesn’t need to be associated with a project, Android Studio lists GPU traces in the Captures window for a project. It stores the trace in the project captures directory.

You can create an empty project for the purpose of capturing GPU traces. If you develop and run within Android Studio, we recommend that you instead follow the steps for capturing a GPU trace for an Android Studio project.

  1. Connect an Android hardware device to your USB port.

If the Allow USB Debugging dialog appears on the device, click OK.

This dialog typically appears on your home screen (for example, after you log in), not on the boot screen. If you don’t allow USB debugging, Android Monitor shows your device as OFFLINE, and you can’t perform a trace.

  1. Install the APK on your hardware device.

If the APK is on your development computer, you can transfer it to your phone with adb. For example:

adb install /Users/me/Downloads/myapp.apk

  1. Start a GPU trace from the GPU Monitor.

Capturing a GPU Trace from the GPU Monitor
After you install your app on a connected hardware device, as described in the previous sections, you can use the GPU Monitor to capture a trace.

To capture a GPU trace from the GPU Monitor, follow these steps:

  1. Open Android Monitor.

  2. In the Device menu, select the hardware device.

  3. Click the Monitors tab and display the GPU Monitor.

  4. Click Launch to start tracing.

If the GPU Debugging tools aren’t yet installed, the GPU Tools Missing dialog appears. Click OK to install the GPU Debugging tools. In the Install Missing Components dialog, click Finish to complete the installation.

The Launch Activity dialog appears.

  1. Select the app process in the dialog.

For example, the Zooshi app has a process that you can select.

  1. Click Trace.

The Graphics Trace dialog appears. First, the tool attaches the trace library. Then it starts the trace.

If your device doesn’t support GPU tracing, you receive an error:

The GPU debugger does not currently support tracing on this device.

  1. Interact with your app on the hardware device.

As long as the MB value keeps rising as you interact with the app, the GPU trace is proceeding normally.

  1. To end the GPU trace, click Stop.

The trace opens in the GPU Debugger.

Analyzing Trace Results

Teapot Geometry tab

Traces are logged to a captures folder inside your project. When you open a trace, the top bar of the UI will show the full sequence of logged frames. You can select an individual frame through either the top bar or the GPU commands panel; after you select a frame, the center right framebuffer window will update to show that frame’s contents. If you expand the frame on the lefthand GPU commands window, you’ll see the individual draw commands and GL calls that were used.  

If you click a draw command, the framebuffer preview is updated to reflect the contents as of that draw call. As applicable, the Memory tab is also be updated to show relevant memory state at the time of the call.

At any point, you can use the GPU State tab or the Textures tab to explore relevant GPU state at the time of your selected frame or draw calls.

If you run into issues, please help us improve the 2.2 release by logging bugs in our public Issues Tracker. You can create an issue through this link or by clicking HelpSubmit Feedback directly in Android Studio.