PerfHUD ES: An Introduction

In the mobile game development world, developer studios are discovering that the Tegra chipset offers a huge array of visual features that cannot be found on other mobile platforms.

When developers create games designed to take advantage of Tegra features, they want to use every tool at their disposal to tune the performance of their game. PerfHUD ES is one type of tool that lets developers get the most out of their Tegra-based hardware.

The newest game from Madfinger, Dead Trigger, highlights this eloquently (and by “eloquently”, we mean “lots of violent visual effects”). If you aren’t too squeamish, we encourage you to check out the video at the bottom of this article that dramatically highlights those differences.

What does PerfHUD ES do?

"Yet again, NVIDIA shows they really know what developers are looking for. This is essential stuff!”

Simon Morris, CTOStrawdog Studios

PerfHUD ES uses data provided by the OpenGL ES driver and the NVIDIA Tegra GPU to show your GPU performance and highlight bottlenecks. This lets you target optimizations where they are most needed, instead of wasting time with unnecessary optimizations.

Simon Morris, CTO of Strawdog Studios, captured the heart of the tool, "PerfHUD ES is one of those special tools that developers tend to fall in love with. You have to work really smart to get the best out of GPUs on mobile devices and this tool has been a revelation - it shows us exactly where we can improve the quality and performance of our rendering pipeline. The ability to edit and recompile shaders on-the-fly is particularly awesome."

During your debugging, PerfHUD ES provides full access to the state of the OpenGL ES pipeline, related textures and shaders, as well as all rendering states. This helps you quickly spot causes for improper setup and rendering anomalies.

PerfHUD ES uses a client-server model, and the target device must run a special instrumented driver that communicates back to the host via TCP/IP. The PerfHUD ES host runs on any PC (Windows, Mac or linux) that supports OpenGL 1.5 (or higher), but keep in mind that PerfHUD ES for Tegra only supports OpenGL ES 2.0.

PerfHUD ES is available to all Tegra Android Developers. Simply join the Tegra Registered Developer Program and download the Tegra Android Development Pack.

Ok, I downloaded it. Now what?

The Tegra Android Development Pack contains all the basic software you need to setup a full Android development environment on Windows, OSX or Linux, including the Android SDK/NDK, the Eclipse development environment, PerfHUD ES, and several samples.

PerfHUD ES works on a number of "consumer" devices, as well as Tegra “DevKits” provided to key partners. Here are just a few of the devices that support PerfHUD ES:

ASUS Transformer Prime (TF201)

ASUS Transformer Pad 300 (TF300)

HTC One X (International)

Acer Iconia Tab 500

Getting started with PerfHUD ES

The PerfHUD ES interposer is enabled on the target device with the following command:

adb shell setprop debug.perfhudes 1

This sets the debug.perfhudes property to 1, unleashing the phenomenal cosmic power of PerfHUD ES. Note that this property isn’t persistent - you must re-enable it after every boot.

PerfHUD ES requires TCP/IP to communicate to the host system. For this reason, you must make sure Internet permissions are enabled in your application (by adding <uses-permission android:name="android.permission.INTERNET"></uses-permission>in the AndroidManifest.xml).

Hello (Visual) World

We want to start off with a very simple demonstration of PerfHUD ES to help get you started. To do this, we are going to use the Globe application as our first application to debug (and let's face it, you have to appreciate the literal interpretation of "Hello World").

Let’s start by building the NativeGlobe application in Eclipse. We only cover using Eclipse here but the Tegra Android Development Pack installs this sample by default so you can also check it out there.

For this example, we’re going to assume that you’ve installed the proper USB drivers for your Tegra device (Windows only) and that adb is working properly (‘adb devices’ from a command shell should list your device). If not, see this Android Developer page for more information.

Open the Tegra Android Samples in Eclipse:

Launch the version of Eclipse installed by Tegra Android Development Pack (found in C:\NVPACK\eclipse by default).

You will need to select a Workspace for Eclipse. For the Tegra samples, select C:\NVPACK\nvsample_workspace.

In Eclipse, the first time it is launched, a “Welcome” screen is presented. Before continuing on, make sure you select “Workbench” (the curled arrow icon).

Compile the Tegra Android Samples:

In Eclipse, compile by going to Project -> Build All.

If you only get warnings in the “Problems” tab on the bottom panel, move on to the next step.

If you get the error, “The project cannot be built until build path errors are resolved”:

Launch PerfHUD ES on the Host:

The PerfHUD ES Host will automatically attempt to connect to running applications on the target device using ADB. Note that if you have problems with adb port forwarding, you may need to check that a local firewall is not blocking the port.

Your working application should look like this:

Now that you have PerfHUD ES running, feel free to experiment with the application. Next time we’ll dive into the details.

CAVEATS

Instrumented debugging always comes with tradeoffs, and while we wish we could offer a truly transparent GPU debugger, there are a couple of small guidelines to remember:

In the dashboard settings, enabling the “GPU Idle trace” may affect performance. If you don’t directly require this particular trace, it’s advisable to go ahead and disable it.

To keep the function call count (and its subsequent timing overhead) to a minimum, you should disable error-checking in your profile build and try to reduce gl calls to a minimum.