PVRCarbon Quick Start Guide

A guide to the API tracing and debugging tool, PVRCarbon

Introduction

PVRCarbon is a suite of tools allowing developers to record and analyse the graphics API usage of an application.

The following graphics APIs are supported:

  • Vulkan (all versions)
  • EGL (all versions)
  • OpenGL ES (2.0 and above)

In comparison to other similar tools, PVRCarbon features:

  • A low recording overhead for minimal runtime impact
  • Small file sizes for easy transmission
  • Simplified remote recording from the GUI
  • The ability to export recordings to C++ source code

PVRCarbon can be broken down into three main components: the GUI, Recorder, and Player. Each component can be used individually, but the GUI acts as an interconnectivity hub, as it can control the Recorder and send data to the Player.

The GUI

The PVRCarbon GUI is the central component. It is mainly used for analysing and processing a PVRCarbon recording. A recording can come from:

  • An existing PVRCARBON (.pvrcarbon) file
  • A live recording by connecting to a remote device such as a phone or tablet

Once a PVRCarbon recording has been loaded, the GUI allows various tasks such as viewing its API calls, exporting it to C++ source code, and playing it back on remote devices.

The GUI is available for Windows, macOS, and Linux.

PVRCarbon Recorder

The PVRCarbon Recorder is a set of libraries that are used to intercept the API calls made by an application before forwarding them on to the graphics drivers. These libraries allow calls to be saved to a PVRCARBON file or streamed over the network to the GUI.

While the Recorder libraries can be used manually on all platforms to take recordings, the PVRCarbon GUI contains the libraries for Android, so that it can deploy them automatically during remote recording sessions.

The Recorder can also be installed separately and a recording can be taken without being connected to a GUI. See Manual Recordings for more details.

The Recorder libraries are available for Android, Linux, and Windows.

PVRCarbon Player

The PVRCarbon Player is a component used to play back a PVRCarbon recording. It replicates the sequence of API calls that were captured during the recording as closely as possible.

The GUI contains its own internal Player, and it can also connect to and use a stand-alone instance that is running remotely, such as on a connected phone or tablet. Alternatively, a stand-alone Player can play back a recording from a PVRCARBON file directly, without the need for the GUI.

Playing back a PVRCARBON recording is done by invoking the PVRCarbon Player through a command-line argument.

The stand-alone Player is available for Android, Linux, and Windows.

Usage Example

PVRCarbon can be used in multiple ways, but the most common is to take a recording of an application on an Android device and analyse it in the GUI. For this, PVRCarbon has been designed to be as straight forward as possible, requiring only a handful of steps.
  1. Connect to the device.
    Upon startup, PVRCarbon will show a window for connecting to a target device. The connection can be either through USB or via a network. In the case of USB, the device should be listed on the Remote Connection window. If connecting via a network, the IP address of the device needs to be supplied. In both cases, the device will be saved for quick access in future.
  2. Select application to record.
    The window will change to show a list of the currently installed applications on the device. Select which application to profile by double-clicking on the desired application. If the desired target is not shown, double check the device.
    Additionally, some application have specific activities within them. The Activity Selector allows a specific activity to be launched instead of the entire application.
  3. Configure recording options.
    The final window will allow users to specify other parameters regarding the recording. Once the connection is established, the rest of the GUI will load up.
  4. Analyse the recording in the GUI.
    Once the recording has completed, all information is displayed automatically in PVRCarbon for viewing and analysis.

Analysing Data

Once the recording has completed, or been loaded, data analysis can be performed. PVRCarbon can be used to identify frame-by-frame issues within an application or overall bottlenecks.

Along the bottom is the frame control bar. Relevant information is displayed in its respective windows around the GUI.

Manual Recordings

In some cases the remote recording might fail. In such situations the PVRCarbon libraries will need to be manually installed and the recording will need to be manually triggered. A script is supplied in order to make this easier.

Manual recordings can be opened in the PVRCarbon GUI with the menu control File > Open or the keyboard shortcut CTRL + O.