MGD integration in Unity

Roberto Lopez Mendez and Stephen Barton

Introduction

In a previous blog, Stephen Barton described the steps to build a Unity application with Mali Graphics Debugger (MGD) support, using a non-rooted device.

More recently, thanks to the collaboration of the Arm Tools and Gaming & Graphics teams with Unity, it has been possible to significantly simplify this process for applications using OpenGL ES. 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 blog 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 blog 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 Files\ARM\Mali Developer Tools\Mali Graphics Debugger vX.Y.0. Locate the subfolder target\android\arm\ 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 Assets\Plugins\Android\. Copy the libMGD.so library, which you can find in the MGD installation folder under target\android\arm\unrooted\armeabi-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 target\android\arm\rooted\armeabi-v7a\. Make a copy of the library, rename it to libVkLayerMGD32.so and copy it to the Unity project folder Assets\Plugins\Android\libs\armeabi-v7a. Unity will package the libVkLayerMGD32.so library into the apk.

Figure 5. MGD validation layer libVkLayerMGD32.so in the Asset/Plugins/Android/libs/armeabi-v7a Unity project folder.

3. Build your application with the Development Build option ticked to allow Unity to enable 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.

Figure 6. MGD registering traces from a Unity Vulkan application.

Conclusions

Arm’s collaboration with Unity has made it much easier to build Unity applications for Android with MGD support. Now developers can use MGD to profile Unity applications on the device with just a few quick steps. We hope this will encourage more developers to try MGD and take advantage of its many features.