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
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
or the keyboard shortcut CTRL + O.