Additional PVRCarbon CLIs#

PVRCarbon comes with a selection of command-line tools which allow manipulation and analysis of Carbon recordings (pvrcbn files).

Most of the functionality of these tools is already implemented in the PVRCarbon GUI. However, if automatic processing or manipulation of recordings is required then these command-line tools can be used.

These tools are distributed as native executables for Windows and Linux.

For tasks that require playback (for example, Trimming), you’ll need an OpenGL ES, Vulkan, and/or OpenCL implementation installed. What is needed will depend on the APIs contained within the recorded Carbon file. On platforms like Windows where there isn’t OpenGL ES support readily available we recommend installing our PVRVFrame emulation libraries, which will provide an implementation of OpenGL ES via your desktop’s OpenGL implementation.

PVRCarbonDump#

PVRCarbonDump processes a Carbon recording to give a brief summary of the information within the file.

The syntax for running PVRCarbonDump is: PVRCarbonDump [options] [.pvrcbn file].

The available command-line options for this tool are:

-h, --help

Display help message and exit.

--version

Print version information and exit.

-o=<FOLDERNAME>

Dump to FOLDERNAME.

--header

Dump header information.

--config

Dump the configuration used for recording.

--shaders

Dump the shaders.

--screenshots

Dump the screenshots. This outputs the frames of the recordings as png files in the output directory.

--windows

Dump information about the window surfaces.

--threads

Dump information about the threads.

The full output of this tool consists of several sections.

Config#

The Config section contains all of the configuration information of the recording.

Threads#

This section contains a list of the threads used by the application, denoted by their thread id.

Surfaces#

This contains information about the window surfaces used by the application, including their dimensions and the address of the native surface object.

PVRCarbonFrameAnalysis#

The PVRCarbonFrameAnalysis performs frame analysis to generate .pvrcbna analysis files from Carbon recordings. These .pvrcbna files can then be opened in the GUI to allow in-depth analysis of a particular frame. This matches the functionality found in the GUI.

The syntax for this tool is: PVRCarbonFrameAnalysis [options] [.pvrcbn file]. The available options for this tool are:

-h, --help

Display help message and exit.

--version

Print version information and exit.

-o=<FILENAME>

FILENAME to export to.

--frame=<FRAME>

Analyse FRAME.

Example: --frame=5

--uid-range=<RANGE>

Analyse the uid range of calls.

Example: --uid-range=10-55

--ignore-errors

PVRCarbon will stop analysing if certain errors occur during playback. Enable this to ignore these errors. This may make PVRCarbon unstable and produce incomplete analysis files.

Note

PVRCarbonFrameAnalysis is also supplied as an Android command-line binary. This is designed to run in an adb shell on rooted Android devices. When running on device, ensure the binary has executable permissions, is ran from a suitable location e.g /data/local/tmp, and can write to the chosen output directory. Locations suitable for execution and writing may differ per device.

PVRCarbonStaticAnalysis#

PVRCarbonStaticAnalysis performs static analysis on a Carbon recording to ensure valid usage of the API. This matches the functionality found in the Static Analysis window in the GUI.

The valid syntax for this tool is:PVRCarbonStaticAnalysis [options] [.pvrcbn file]. The static analysis is output directly to the command-line.

-h, --help

Display help message and exit.

--version

Print version information and exit.

--uid-range=<RANGE>

Export the uid range of calls.

Example: --uid-range=10-55

--summary-only

Only displays a summary of the static analysis results.

--output-file=<FILENAME>

Output static analysis results to FILENAME.

For more information about the form of the static analysis messages, see Static Analysis Window.

PVRCarbonToCpp#

PVRCarbonToCpp exports the captured API calls from a Carbon recording as debuggable C++ source code. This provides the same functionality as the “Export calls to debuggable C++” option in the GUI.

Valid syntax for this tool is: PVRCarbonToCpp [options] [.pvrcbn file]. The available options for this tool are:

-h, --help

Display help message and exit.

--version

Print version information and exit.

-o=<FOLDERNAME>

Export to FOLDERNAME.

--name=<APPNAME>

Export binary code to APPNAME.

Example: --name=HelloWorld

--package=<NAME>

Export code to package NAME.

Example: --package=com.powervr.cpp.helloworld

--uid-range=<RANGE>

Export the uid range of calls.

Example: --uid-range=10-55

--disable-vma

By default, exported code will use the Vulkan Memory Allocator for memory management. This options disables that.

--disable-surface-replacement

By default, exported code will have its surface creation replaced with a cross-platform version. This options disables that.

--ignore-errors

PVRCarbon will stop exporting if certain errors occur during playback. Enable this option to ignore these errors. This may make PVRCarbon unstable and produce incomplete source code.

Note

PVRCarbonToCpp is also supplied as an Android command-line binary. This is designed to run in an adb shell on rooted Android devices. When running on device, ensure the binary has executable permissions, is ran from a suitable location e.g /data/local/tmp, and can write to the chosen output directory. Locations suitable for execution and writing may differ per device.

PVRCarbonToTxt#

The PVRCarbonToTxt tool allows a Carbon recording to be exported as a txt or csv file. This text file breaks down recording information by API call.

This CLI provides the same functionality as the “Export calls to TXT…” in the GUI.

The valid syntax for this tool is: PVRCarbonToTxt [options] [.pvrcbn file]. The available options for this tool are:

-h, --help

Display help message and exit.

--version

Print version information and exit.

-o=<FILENAME>

Export to FILENAME.

--format=<FORMAT>

Set the text format. Supported formats are: multiline (Default), singleline, csv.

Example: --format=csv

--frame-range=<RANGE>

Export the frame range.

Example: --frame-range=5-10

--uid-range=<RANGE>

Export the uid range of calls.

Example: --uid-range=10-55

--export-uids=<BOOL>

Set whether or not to export UIDs. Default: 1.

--export-frame-no=<BOOL>

Set whether or not to export frame numbers. Default: 1.

--export-thread-ids=<BOOL>

Set whether or not to export thread ids. Default: 1.

--export-errors=<BOOL>

Set whether or not to export API errors. Default: 1.

--export-results=<BOOL>

Set whether or not to export call results. Default: 1.

--export-arguments=<BOOL>

Set whether or not to export call arguments. Default: 1.

--export-argument-names=<BOOL>

Set whether or not to export call argument names. Default: 1.

--export-struct-members=<BOOL>

Set whether or not to export API structure members in multiline and singleline formats. Default: 1.

PVRCarbonTrim#

The PVRCarbonTrim tool allows a Carbon recording to be trimmed to a specified range of frames, calls, or API.

Usage: PVRCarbonTrim [options] [.pvrcbn file]

-h, --help

Display help message and exit.

--version

Print version information and exit.

-o=<FILENAME>

Export to FILENAME.

--uid-range=<RANGE>

Export the uid range of calls.

Example: --uid-range=10-55

--frame-range=<RANGE>

Export a range of frames.

Example: --frame-range=100-200

--apis=<APIS>

Export the requested APIs from the pvrcbn file. Supported values: gl, vk

Example: --apis=vk

--ignore-errors

PVRCarbon will stop trimming if certain errors occur during playback. Enable this to ignore these errors. This may make PVRCarbonTrim unstable and produce incomplete trimmed files.

--strip-recorded-framebuffers

Ignore any recorded framebuffers from the file while trimming.

Note

PVRCarbonTrim is also supplied as an Android command-line binary. This is designed to run in an adb shell on rooted Android devices. When running on device, ensure the binary has executable permissions, is ran from a suitable location e.g /data/local/tmp, and can write to the chosen output directory. Locations suitable for execution and writing may differ per device.