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, Linux, and macOS.
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:
Option |
Description |
|---|---|
|
Display help message and exit. |
|
Print version information and exit. |
|
Dump to FOLDERNAME. |
|
Dump header information. |
|
Dump the configuration used for recording. |
|
Dump the shaders. |
|
Dump the screenshots. This outputs the frames of the recordings as png files in the output directory. |
|
Dump information about the window surfaces. |
|
Dump information about the threads. |
The full output of this tool consists of several sections.
Header#
The Header section contains information on the Recorder used to capture the .pvrcbn file, including the Recorder version, information about the build, and the OS.
It also displays the application that was being recorded.
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:
Option |
Description |
|---|---|
|
Display help message and exit. |
|
Print version information and exit. |
|
FILENAME to export to. |
|
Analyse FRAME. Example: |
|
Analyse the uid range of calls. Example: |
|
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.
Option |
Description |
|---|---|
|
Display help message and exit. |
|
Print version information and exit. |
|
Export the uid range of calls. Example: |
|
Only displays a summary of the static analysis results. |
|
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:
Option |
Description |
|---|---|
|
Display help message and exit. |
|
Print version information and exit. |
|
Export to FOLDERNAME. |
|
Export binary code to APPNAME. Example: |
|
Export code to package NAME. Example: |
|
Export the uid range of calls. Example: |
|
By default, exported code will use the Vulkan Memory Allocator for memory management. This options disables that. |
|
By default, exported code will have its surface creation replaced with a cross-platform version. This options disables that. |
|
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 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:
Option |
Description |
|---|---|
|
Display help message and exit. |
|
Print version information and exit. |
|
Export to |
|
Set the text format. Supported formats are: multiline (Default), singleline, csv. Example: |
|
Export the frame range. Example: |
|
Export the uid range of calls. Example: |
|
Set whether or not to export UIDs. Default: 1. |
|
Set whether or not to export frame numbers. Default: 1. |
|
Set whether or not to export thread ids. Default: 1. |
|
Set whether or not to export API errors. Default: 1. |
|
Set whether or not to export call results. Default: 1. |
|
Set whether or not to export call arguments. Default: 1. |
|
Set whether or not to export call argument names. Default: 1. |
|
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]
Option |
Description |
|---|---|
|
Display help message and exit. |
|
Print version information and exit. |
|
Export to FILENAME. |
|
Export the uid range of calls. Example: |
|
Export a range of frames. Example: |
|
Export the requested APIs from the pvrcbn file. Supported values: |
|
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. |
|
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.