Mali Android GPU Profiling & Debugging Tools – How to Debug your Applications

Introduction

If you are developing an android application or game sometimes you can run into issues. When this happens they usually fall into one of two categories: The graphics in my application don’t look like I imagined them, or the speed or frame rate of the application is not good enough for the playing experience to be enjoyable by the end user. There are tools to help you through these issues and this guide is going to show you how and when to use which tools to get the results that you want.

Download the correct tools for the job

If your issue is performance related then you should start by downloading ARM Streamline.  This can be found at https://developer.arm.com/products/software-development-tools/ds-5-development-studio/downloads. This tool allows you to quickly identify where your performance bottleneck is. From there, if you find you’re CPU bound then you should stay with Streamline as it can give you a wealth of information about where CPU time is spent on your application.

However, if you find you are graphics bound or have a graphics related defect, then you can move to the Mali Graphics Debugger (MGD) as it’s the best tool for debugging and optimizing graphics applications.

Setup

So, we are at the point where we know what the problem is and we have selected MGD to help us solve it. First you need to download it from: http://malideveloper.arm.com/resources/tools/mali-graphics-debugger/

The tool works on Windows, Linux and Mac so just pick the version that works for you. From there you can choose to use MGD on a rooted or non-rooted device.

MGD on a rooted device

The simple steps to set this up can be found in the user guide supplied with MGD. The idea is that you will replace your graphics driver on your device with the MGD library. The MGD library will then call the graphics driver on behalf of the application, profiling all the applications on a device without needing to modify any of the source code.

MGD on a non-rooted device

If your device is not rooted then you need to include the MGD in your application. We have various guides available depending on which game engine you are working with:

• If you are creating the application with Unity then follow this guide: https://www.community.arm.com/graphics/b/ece70eab2a564598933fdbde95b81196/posts/building-a-unity-application-with-mali-graphics-debugger-support
• If you are creating the application with Unreal Engine then follow this guide: https://www.community.arm.com/graphics/b/ece70eab2a564598933fdbde95b81196/posts/building-an-unreal-engine-application-with-mali-graphics-debugger-support
• Finally, if you are creating your application with a custom engine then you should follow this guide: https://www.community.arm.com/graphics/b/ece70eab2a564598933fdbde95b81196/posts/using-mali-graphics-debugger-on-a-non-rooted-device

Let’s generate a trace

Okay so now we have our application on the target and we are ready to start to generate a trace. Start up the MGD application on your device and start the deamon with the little toggle on the top.

Now connect from the host application where a blank trace should have been created. MGD is now ready for you to start tracing. Click on the application on the MGD app, your application should now spring into life and MGD should start populating the overview panel and the trace panel with information.

Let the application play out until you get to the area in your application that you are interested in and then pause it using MGD. Once this is complete we are going to do 4 things:

• A frame capture: To do this you need to just click the capture icon. MGD will then run the next frame and capture all of the frame data that is drawn per draw call. This is great to see how your scene is composed.
• An overdraw capture: To do this you need to click on the overdraw icon which should be two to the right of the frame capture icon. Then when this button is selected press the frame capture button again. MGD will then do an Overdraw capture. This is similar to a frame capture in that MGD captures all of the frame data that is drawn per draw call, but this feature also replaces your shader with an almost transparent white. This means the whiter the image the more times you have drawn to the same pixel. If there are areas in your scene that are over 3X overdraw then this is a great place to start optimizing.

• Shader map capture: To do this you need to click on the shadermap icon which should be to the right of the overdraw icon. When this button is selected you then press the frame capture button again. MGD will then do another capture but this time will replace each of your fragment shaders with a unique colour. This will allow you to see which shaders are responsible for drawing different areas of the screen.
• Fragment count: To do this you need to click on the fragment count icon which should be to the right of the shader map icon. When this button is selected you then press the frame capture button again. This will allow MGD to capture all the data from the next frame and while it is doing that it will count how many fragments are drawn to the screen. As MGD already knows how expensive a shader is it means MGD can estimate how many cycles each shader spent on the GPU.

We recommend that you do these 4 things on all traces that you run with MGD whether you are looking for graphics imperfections or you just want to increase performance.

What is wrong (Graphics defects)

So you have graphics imperfections, how can the Mali Graphics Debugger help you? It depends where your imperfection is but here are a few suggestions that you can try:

• If a particular object is not displaying correctly in your scene you could use the Frame Capture above to find out which draw call is the one that is creating the defect. This quickly narrows down your problem area so you can immediately start trying to fix it.
• Once you know which draw call is producing the issue you can use the Geometry Viewer to make sure the geometry that is being sent to the draw call is correct. If this is wrong then you know that this is a problem with the vertices or indices that you are passing to the draw call. If all of this data is correct the problem must be elsewhere.
• If you have a frame that is working correctly and one that then shows you an issue you can select both of the Frames and then right click and select Generate Diff. This will tell you the differences in OpenGL ES state between the two points. If these are different then this is definitely something to look into.
• MGD always does error checking for all api calls so it is easy to pinpoint when there is an error. This also extends to the shaders in your application if they don’t compile or link correctly.

What is wrong (Performance)

If you are looking to improve the performance of your application then you first need to work out whether you are fragment bound, vertex bound, bandwidth bound or CPU bound.  As mentioned earlier, the best tool to work out which one you are is Streamline and you should start your analysis there. The rest of this guide assumes you know which one you are and how you can use MGD to resolve the issue.

Insert a photo here

Vertex bound

Being Vertex bound is uncommon but does happen when you are either drawing too many vertices or you have too many instructions or cycles in your vertex shader. The Trace Outline view gives you an indication of how many vertices are in each of your frames so the best way to start analysing your problem is to select which frame has the most. Then, if you select the shaders view, MGD will tell you which shaders contribute the most to the scene. It is these you want to start to optimize as they will make a difference in your application’s overall performance.

Fragment bound

If your application is fragment bound then there are a few main causes. The first is that you are drawing too many fragments. To reduce this you simply need to reduce the resolution of your application. If you are rendering to a 2560 x 1440 screen that doesn’t mean you need to use that resolution on your game. You could easily switch to 1920 x 1080 and be drawing to just slightly more than half as many fragments.

The next cause could be that you are drawing to the same pixel more than once on the screen. This is known as overdraw. Use the overdraw capture mode described earlier in this article. The area that has the highest overdraw factor should be the easiest to reduce. If you reduce your average overdraw factor from 6x to 3x then, again, you have reduced your fragment load by half.

The final cause is much the same as the vertex one and is that your fragment shaders are simply too expensive. If you take the fragment count capture that you did earlier you can look at the shaders view and see which shaders contribute the most to the scene. It is these you want to start to optimize as they will make the biggest difference to your application’s performance.

Bandwidth bound

If you are bandwidth bound then you should start to look at reducing the size of your textures by including texture compression in your application. MGD will list all your textures in your application as well as whether they are currently being compressed and their current resolution. If you need help in compressing your textures you should use the Texture Compression Tool which can be found at: http://malideveloper.arm.com/resources/tools/mali-gpu-texture-compression-tool/.

You should also start to use Vertex Buffer Objects, again MGD will show you all of the information about the buffers you are currently using.

For more information and resources please see the links below including some of our ARM Tools blogs.

• Draw-call by Draw-call stepping
  To identify draw call related issues, redundant draw calls and other opportunities to optimize
• Texture View
  Visualize an application’s texture usage, to identify opportunities to compress textures or change formats.
• Shader Statistics
  Understand which vertex and fragment shaders are the most expensive with cycle count reporting
• and more…

• • Samples & Tutorials
    Numerous samples from the basic set-up to more complex examples demonstrating shader effects.
    Samples demonstrating features of OpenGL ES 2.0 and OpenGL ES 3.x.
  • Visual Studio Projects
    Project files for all samples supplied for Visual Studio.
    Make files also provided for command line building
  • Simple Framework
    A light weight framework with common math functions, text displaying and timing to see your results quickly.