Overview

This tutorial describes how to use Arm Graphics Analyzer to capture a graphics trace of a debuggable application running on an Android device with a Mali GPU.

Choose Next to browse through the steps as you work through them, or choose Single Page to view all the steps on one page.

Before you begin

On your host machine:

  1. Download and install the Arm Mobile Studio package appropriate to your host platform (Windows, Linux, or macOS).
  2. Install Android Debug Bridge (ADB). ADB is available with the Android SDK platform tools.
  3. Install Python 3.5 (or higher). You will need this to run the provided Python script aga_me.py, which connects Graphics Analyzer to your Android target. 
  4. Edit your PATH environment variable to add the paths to the Python3 directory and the Android SDK platform tools directory.
    You can also set the path to Android Debug Bridge in Graphics Analyzer. Select Edit > Preferences and select Browse in the Path to ADB field to locate the adb executable.
  5. Your machine must be able to use TCP/IP on port 5002 to communicate with the device.
  6. You will need to be able modify the application you want to analyze, so you need access to the project or source code for it.

Configure your device

  1. Ensure Developer Mode is enabled, then enable USB Debugging using Settings > Developer options.
  2. Connect the device to your host machine. To test the connection, run the adb devices command in a terminal window on the host, which should return the ID of your device.
    adb devices
    List of devices attached
    ce12345abcdf1a1234       device

    If adb devices does not work, check that you have installed Android Debug Bridge correctly, see Before you begin.

  3. The device must be able to use TCP/IP on port 5002 to communicate with the host. Make sure that this port is not in use.

Prepare your application

To enable Graphics Analyzer to perform a trace, you need to add the Arm interceptor library to your application. The interceptor library collects information about the OpenGL ES and EGL function calls made by the application.

If you're using Unity or Unreal Engine to build your application, follow the instructions here instead:

  1. Specify the location of the interceptor library, libAGA.so, in the module’s build.gradle file by adding the following line to the SourceSet main:
     jniLibs.srcDirs += ['<install_dir>/graphics_analyzer/target/android/arm/unrooted/']
    Note: Specify the unrooted directory, not the subdirectory that contains the library.
  2. Ensure that the abiFilters property in the module’s build.gradle file is set to a value that the interceptor supports; either armeabi-v7a, arm64-v8a, or both. For example, to support both Armv7 and Armv8 targets, specify:
    android {
             …
             defaultConfig {
                   …
                   ndk {
                        abiFilters 'armeabi-v7a', 'arm64-v8a'
                   }
             }
     }
  3. Enable the interceptor by adding a Java component to the application to be traced to enable it to load the interceptor library. The details of this step depend on the type of application.

    For applications that use C or C++ only:
    1. Create a new Activity class that extends android.app.NativeActivity.
    2. Reference this new Activity in your AndroidManifest.xml as the android:name attribute of the activity element.
    3. Ensure that the android:hasCode attribute of the application element is set to true, otherwise the Java file will not be included in the APK.
    For applications that use Java, C/C++, or both, add the following code to the beginning of the project's main Activity class:
    static
    {
          try
          {
               System.loadLibrary("GA");
          }
          catch (UnsatisfiedLinkError e)
          {            // Feel free to remove this log message.
               Log.e("[GA]", "GA not loaded: " + e.getMessage());
               Log.d("[GA]", Log.getStackTraceString(e));
          }
    }
    Note: For more information about this step, see the Target installation section of the Graphics Analyzer User Guide.
  4. Recompile the application and install it on the target device.

Prepare your Unity application

To enable Graphics Analyzer to trace your application, you need to add the Arm interceptor library to your Unity project. The interceptor library intercepts and collects information about the OpenGL ES and EGL function calls made by the application. Unity detects the presence of the interceptor library and automatically loads it when you build the application. Follow these steps to add the library and set Unity’s player and build settings to use it.

The library libMGD.so is provided in your Arm Mobile Studio package:

<install_directory>/graphics_analyzer/target/android/arm/unrooted/

Two versions of the library are provided:

  • For 64-bit applications, use the library file located in the arm64-v8a directory.
  • For 32-bit applications, use the library file located in the armeabi-v7a directory.

    Note: You can package one or both interceptor libraries depending on the requirements of your application. 

Prerequisites

Check that you are using the Unity recommended Android SDK and Android NDK versions in the Unity editor.

  • On Windows and Linux, select Edit > Preferences > External Tools.
  • On macOS, select Unity > Preferences > External Tools.

If the checkboxes are selected, they are installed. Otherwise, you can add them as modules. See https://docs.unity3d.com/Manual/android-sdksetup.html for more information.

Procedure

  1. Copy the required interceptor library, libMGD.so, into the Unity project directory Assets/Plugins/Android/, creating this directory if it does not already exist.

    If you are packaging both interceptor libraries: 
    1. Create two directories in the Assets/Plugins/ directory. For example, armv7 and armv8.
    2. Create a directory called Android in each of these directories.
    3. Copy each libMGD.so file into the appropriate Android directory.
  2. Select the library in Unity and set the following attributes in the Inspector:
    • Under Select platforms for plugin, select Android
    • Under Platform settings, set the CPU architecture to ARM64 for 64-bit applications, or ARMv7 for 32-bit applications.
    • Click Apply.
    • Unity Inspector settings for Graphics Analyzer interceptor library 
  3. Select File > Build Settings, then select Player Settings.
  4. Under Identification, set Target API Level to the required Android version.
    By default, Target API Level is set to the latest version of the Android SDK tools that you have installed. If you change to a lower API level, ensure that you have the SDK tools for that version installed, and be aware that if you want to build for a higher API version later, you will need to change this setting accordingly.
  5. Under Configuration, set the following options to build a 64-bit application:
    1. Set the scripting backend in Unity to work with 64-bit targets. SetScripting Backend to IL2CPP. For more information about IL2CPP, refer to the Unity documentation.
    2. Under Target Architectures, select ARM64.
      Unity Player Settings
      To build a 32-bit application:
      1. Leave the scripting backend at its default setting, Mono.
      2. Under Target Architectures, select ARM7.

  6. Close the Player Settings. In the Build Settings, select the Development Build checkbox. This option ensures that your application is marked as debuggable in the Android application manifest.
  7. Select Build and Run to build your APK and install it on your device in one step. Alternatively, select Build to build the APK and then install it on your device using Android Debug Bridge:
    adb install -r YourApplication.apk

Prepare your Unreal Engine application

To enable Graphics Analyzer to trace your application, you need to enable Graphics Analyzer in your Unreal Engine project:

  1. Open your Unreal Engine project.
  2. Open the Project Settings window.
  3. Under Platforms, select Android.
  4. On the right-hand side, under Graphics Debugger, select Mali Graphics Debugger from the Android Graphics Debugger drop-down list.
    Note: Mali Graphics Debugger is the old name for Graphics Analyzer.
  5. In the Mali Graphics Debugger Path field, enter the path to the Graphics Analyzer folder in the Arm Mobile Studio installation directory:
      <install_directory>/graphics_analyzer 

Capture a trace

Connect to your device and start the capture in Graphics Analyzer.

  1. In a terminal, navigate to the Arm Mobile Studio installation directory, where you will find a Python script, named aga_me.py which helps Graphics Analyzer capture data from your device:
    cd <install_directory>/graphics_analyzer/target/android/arm/
  2. Run the aga_me.py script, giving the Android package name of the application you want to profile:

    Tip: If you don't know the package name, run the script with the ‑‑list_packages option first, to see a list of the debuggable packages installed on the device:

    python3 aga_me.py --list_packages

    For OpenGL ES applications, run the script with:

    python3 aga_me.py com.MyCompany.MyApp

    For Vulkan applications, use the -v option to instruct the script to install the Vulkan layer. Refer to the Android documentation for more details.

    python3 aga_me.py -v com.MyCompany.MyApp
  3. The script connects to your device and configures it so that Graphics Analyzer can collect data. The script returns instructions to the terminal about the next required steps, and waits for you to complete them before starting the trace.

  4. Select Open the Device Manager from the Debug menu. If your device is connected successfully it will be listed in the Android Devices window. However, don't use the button here to make the connection, as this may not work for some Android versions. Instead, use the Connect to an IP fields at the bottom of the dialog.
    1.  Specify an IP Address of 127.0.0.1
    2. Specify the Port number 5002
    3. Click Connect.

      Graphics Analyzer Device Manager
  5. Optionally, select Trace Config and select which API assets are captured. Only enable the asset types you need. The more asset types you enable, the slower the application will run, the more memory is required, and the generated trace file will be larger.
    Graphics Analyzer Trace Configuration
  6. In the terminal, press Enter to continue the script. The script will launch your application on the device and start capturing the trace. Graphics Analyzer begins displaying the trace data as it receives it from the target.
  7. Perform your test scenario on the device.
  8. To stop tracing, press Enter in the terminal to continue the script. The script will stop the trace, remove the Graphics Analyzer daemon from your device, and terminate. Graphics Analyzer will report a warning that connection to your device has been interrupted. You can safely ignore this warning.
  9. Save or export the trace file, using options under the File menu.
  10. Analyze your trace in Graphics Analyzer. See the Graphics Analyzer user guide for information about how to explore your application.