Get started with Graphics Analyzer

This tutorial describes how to set up and run Graphics Analyzer with an unrooted Android target.

Before you begin

  1. 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. The ADB executable, adb, must be accessible to Graphics Analyzer. Either add the Android SDK platform tools directory to the PATH environment variable or set the adbpath in the Graphics Analyzer host application using Edit > Preferences > Path to ADB.
  2. On the target device, ensure Developer Mode is enabled, then enable USB Debugging using Settings > Developer options.
  3. The Android target must be connected to the host. To test this, run the adb devices command on the host to return the ID of your device and then you should be able to run adb shell without issues.
  4. The host and target must be able to communicate using TCP/IP on port 5002.
  5. You will need to modify and rebuild the application to be traced, so you must have access to the source code for the application.

Procedure

Note: For Unity or Unreal Engine applications, replace steps 2-4 in the following list with the steps described in Packaging the interceptor for OpenGL ES Unity and Unreal Engine applications.
  1. Install the Graphics Analyzer (GA) Android application on the target device. This application collects the trace data from the application being traced, and transfers it to the host.
    1. Open the Graphics Analyzer host application. From the Debug menu, select Open the Device Manager.
    2. If the target device is listed, right-click on it and select (Re-)install the Graphics Analyzer Android App on the selected device(s):

  2. Package the interceptor library into the application to be traced. The interceptor library intercepts and collects information about the OpenGL ES and EGL function calls made by the application. 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.
  3. 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'
                   }
             }
     }
  4. 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.
  5. Ensure the Android application's manifest uses an android:targetSdkVersion of 25 or lower. 
  6. Recompile the application and install it on the target device.
  7. Connect the host to the target device. To do this, in the Graphics Analyzer host application, select Open the Device Manager from the Debug menu. The Device Manager automatically detects and lists any Android devices that are connected using ADB. Click on the Connect to this device button , or right-click your target device and select Connect to the selected device(s):
  8. Optionally, set the process trace configuration to control which types of API assets will be sent to the host: 

    Note:
    • Enabling more asset types slows down the application, causes Graphics Analyzer to require more memory, and generates a larger trace file.
    • You can change the configuration after the application has started.
  9. Launch the Graphics Analyzer Android application on the target. The application to be traced should appear in the list of traceable apps. Ensure that the Enable Graphics Analyzer Daemon option is enabled:
  10. Start the application to be traced by selecting it from the list of traceable apps. The GA host application begins displaying the trace data as it receives it from the target.
    Note:
    If you start the application before enabling the GA daemon, only the function calls made from the time the daemon was started are traced. This might result in some data being unavailable in the host tool interface. Arm recommends always tracing from the start of the application.
  11. To stop tracing, select the Stop tracing the target and disconnect button .
  12. Optionally, save or export the trace file, using options under the File menu.

Packaging the interceptor for OpenGL ES Unity and Unreal Engine applications

Packaging and enabling the interceptor in a Unity or Unreal Engine application is straightforward:
  • Unity detects the presence of the interceptor library in the project and automatically loads it when you build the application.
  • Unreal Engine version 4.15 and later supports packaging the interceptor library into your application from the Project Settings.
For a Unity application, replace steps 2-4 in the tutorial above with the following steps:
  1. Launch Unity on the host.
  2. Copy the interceptor library, libMGD.so, into the Unity project directory Assets/Plugins/Android/, creating this directory if it does not already exist. The library is located in the following directory in your Arm Mobile Studio installation:
    <install_dir>/graphics_analyzer/target/android/arm/unrooted/armeabi-v7a/
    Note: Take care to copy the file named libMGD.so, not libAGA.so.
  3. In the Unity Build Settings dialog, select the Development Build option. This option enables Unity to package the library into the APK.
For an Unreal Engine application, replace steps 2-4 above with the following steps:
  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 Graphics Analyzer:
      <install_dir>/graphics_analyzer