How to use ARM’s Mali Graphics Debugger in Unity

The latest Unity release comes with two new features, enabling power savings and better performance, as well as the capability to optimize further mobile games.

The first feature that provides power savings and performance of mobile games is Vulkan. Developers can now build their app to take advantage of the latest standard API, Vulkan, available on the new devices launched from the past few months. The advantages of using Vulkan are quite significant, from increased FPS, to increase scene complexity and to extra game play-time, thanks to power savings. Check the Vulkan vs OpenGL ES: get 10-12% extra play time video and Vulkan vs OpenGL ES: scene complexity comparison video to see the advantages! ARM has added a dedicated chapter to Vulkan integration in Unity at the ARM Guide for Unity developers v3.3.

On the other side, Unity and ARM collaborated together to launch the integration of ARM Mali Graphics Debugger (MGD) in v5.6. You can also find a dedicated chapter covering the tool in the aforementioned ARM Guide for Unity.

Prior to v5.6, developers could still use MGD by following the steps building a Unity application with ARM Mali Graphics debugger blog, using a non-rooted device.

In Unity v5.6, the process is significantly simplified for applications using OpenGL ES or Vulkan. It’s now possible for Unity to detect the presence of the libMGD.so library in the project and load it automatically when the application is built with Development Build mode enabled. Development Build in Unity is used to enable built-in profiler functionality and also make the Autoconnect Profiler and Script Debugging options available.

In this article we provide not only the newly simplified steps to build an OpenGL ES Unity application with MGD support, but also the steps to build a Vulkan Unity application with MGD support. For the purposes of this article we assume we are working with a non-rooted device.

MGD support for Unity applications developed with OpenGL ES

MGD library loading has been integrated into Unity so developers can quickly and easily use MGD to profile OpenGL ES applications. From Unity 5.6 onwards, developers must follow the steps listed below:

Prerequisites

• Unity 5.6 or higher version installed
• MGD V4.0 or higher installed
• Android Software Development Kit (SDK) installed on the host machine
• PATH should include the path to the ADB binary
• A valid ADB connection to the target device (i.e. adb devices returns the ID of you device with no permission errors and you can run), see the Android device documentation for more information
• The target device should permit TCP/IP communication on port 5002
• The device must be running Android 4.2 or above

Steps

1. Locate the MGD installation folder, in Windows machines for example, the default installation path is C:Programs FilesARMMali Developer ToolsMali Graphics Debugger vX.Y.0. Locate the subfolder targetandroidarm to find the MGD Android Application MGD.apk. Install this apk on the Android device where you will profile your application.

2. In your Unity project, create the subfolder AssetsPluginsAndroid. Copy the libMGD.so library, which you can find in the MGD installation folder under targetandroidarmunrootedarmeabi-v7a, to that location.

Figure 1. MGD library libMGD.so in the Asset/Plugins/Android Unity project folder.

3. In the Unity Build Settings dialog window, check the Development Build option to allow Unity to package the libMGD.so library into the apk. This will load it automatically at runtime on the target device.

Figure 2. Unity Build Options dialog windows with Development Build option enabled.

4. Build your apk and install it on the device. If the Development Build option is not enabled the library won’t be packaged in the apk.

5. Connect MGD to the Daemon over USB by running the following command on the host: adb forward tcp:5002 tcp:5002

6. Launch the MGD Android Application on the host and enable MGD Daemon by sliding the button. You should now see your Unity application linked to libMGD.so library listed.

Figure 3. MGD Daemon application running on Android host device listing installed application linked with MGD library.

7. Launch MGD application on your desktop and click on the icon to connect to the target and start tracing. As we haven’t yet launched our application on the host, MGD will be waiting for trace input.

8. Tap on your application listed by MGD Daemon. MGD Daemon will start sending the OpenGL ES calls to MGD and showing the traces.

Figure 4. MGD registering traces from a Unity OpenGL ES application.

MGD Support for Unity applications developed with Vulkan

MGD also supports debugging of graphics applications developed with Vulkan. The debugging process in the new graphics API is completely different from OpenGL ES. In OpenGL ES, validation is performed right up front using an error-checking mechanism which is part of the pipeline. This type of validation mechanism causes the CPU to spend a significant amount of time in error checking. Vulkan has been designed to offer maximum performance so debugging is performed through validation layers that can be injected into the system at runtime. MGD interceptor library works like a validation layer.

To add validation layers to a Unity Android application based on Vulkan you must copy the libraries into the project folder Assets/Plugins/Android/libs/armeabi-v7a. To build a Vulkan application with MGD support you must also copy the MGD library in the same folder.

The pre-requisites are the same as previously listed for OpenGL ES applications.

The steps to add MGD support to a Unity application developed with Vulkan are listed below:

1. Locate the MGD Android application MGD.apk in the MGD installation folder as described previously for OpenGL ES applications. Install this apk in the Android device you will use to profile your Unity game/application.

2. Locate the MGD library libMGD.so in the MGD installation folder, but this time under the folder targetandroidarmrootedarmeabi-v7a. Make a copy of the library, rename it to libVkLayerMGD32.so and copy it to the Unity project folder AssetsPluginsAndroidlibs/armeabi-v7a. Unity will package the libVkLayerMGD32.so library into the apk.

3. Build your application with the Development Build option ticked to allow Unity enabling the validation layer mechanism at runtime. Install the apk on the device. Note that the libVkLayerMGD32.so library will be packaged into the apk independently of the state of Development Build option.

4. Connect MGD to the daemon over USB by running the following command on the host:

adb forward tcp:5002 tcp:5002

5. Launch the MGD Android Application on the host and enable MGD Daemon by sliding the button. This time MGD Daemon doesn’t list any applications developed with Vulkan.

6. Enable the MGD Vulkan layer:

adb shell

setprop debug.vulkan.layers VK_LAYER_ARM_MGD

This command tells the Vulkan loader to load the layer with the name VK_LAYER_ARM_MGD.

7. Launch MGD application on your desktop and click on the icon to connect to the target and start tracing. Press the perspective icon at the top right corner of the MGD window and select Vulkan as the API to trace. As we haven’t yet launched our application on the host MGD will be waiting for trace input.

8. Start your Android application in the host device, MGD daemon will start sending Vulkan calls to MGD and it will start showing the traces.

We encourage developers to read the ARM Guide for Unity developers v3.3, where developers can find not only the two latest features explained above in Unity v5.6, but also a compilation of best practises and optimized techniques to get the most from an ARM mobile platform. Whether the developers are a beginner to an advanced Unity user, they will find the advice they need to increase the FPS in their graphics app.