PVRCarbon Player Command Line Options#

Option

Description

-h, --help

Display the help and exit.

--version

Print version information and exit.

--mode

Place the player into a particular mode. See below for more information.

-exit-after-frame=<FRAME>

Exit after the specified frame.

-d, --delay=<NUM>

Wait NUM milliseconds between rendering frames.

--do-failed-calls

Plays back calls that failed during recording. By default, these calls will be skipped.

-w, --create-windows=<WINDOWS>

Only create and render to native windows in the list WINDOWS. Rendering to windows not in the list will be done to offscreen API created surfaces.

Expects a comma-separated list of integers. Example: –create-windows=0,3,4

Note: API calls for swapping/presenting to native windows will not be performed for the windows that are rendering to an offscreen API surface.

--hide-created-windows

If supported by the window system, hide native windows on creation.

Currently only implemented for Windows.

--offscreen

Render all windows to offscreen API created surfaces. Equivalent to defining --create-windows with an empty list.

Note: No API calls for swapping/presenting will be performed when rendering offscreen.

--log-level=<LEVEL>

Define the level of logging. Supported levels are: [error, warning, info, verbose, critical, debug, silent].

--print-mappings

Output recorded vs playback mappings.

--wireframe

Set playback polygon mode to line.

--disable-vsync

Disable vsync if supported by the API/platform.

--ignore-errors

PVRCarbon will stop playing if certain errors occur. These errors can be ignored by enabling this option. This may make PVRCarbon unstable.

--enable-api-debug-report

Enable the API’s debug reporting extension, if supported.

--api-debug-report-level=<LEVEL>

Define the severity of the API debug messages reported.

Supported levels are: [error, warning, info, verbose, all]. Defaults to error.

Example: --api-debug-report-level=error,warning

--allow-recorded-layers

By default, the layers enabled at record time are ignored for instance/device creation. This option disables this.

--layers=<LAYERS>

Set layers to enable during playback. Expects a comma-separated list of strings.

--add-instance-extensions=<EXTENSIONS>

Set extra extensions to enable at instance creation. Expects a comma-separated list of strings.

--add-device-extensions=<EXTENSIONS>

Set extra extensions to enable at device creation. Expects a comma-separated list of strings.

--ignore-instance-extensions=<EXTENSIONS>

Set extensions to ignore at instance creation. Expects a comma-separated list of strings.

--ignore-device-extensions=<EXTENSIONS>

Set extensions to ignore at device creation. Expects a comma-separated list of strings.

--capture-frames, --capture-frames=<FRAMES>

Capture frames specified in FRAMES, or all frames if FRAMES is omitted. See below for more information.

--capture-frames-path=<STRING>

Set the output path for the captured frames. Frames are saved to this path as image files.

--capture-frames-format=<STRING>

Set the output file format for captured frames. Supported formats are png and tga. Defaults to png.

--capture-frames-filename-template=<STRING>

Set the template for generating captured frames filenames.

To ensure unique filenames, the template must include %frame or %uid. The supported replacements are:

  • %filename - the pvrcbn filename

  • %frame - the captured frame number

  • %uid - the captured frame delimiter’s call UID

  • %w - the captured frame width

  • %h - the captured frame height.

Example: --capture-frames-filename-template=screenshot_%frame will generate screenshot_0.png, screenshot_1.png, and so on.

--timestamp-calls=<UIDS>

Print a timestamp before each call specified in UIDs is played. Expects a comma-separated list of integers.

--renderdoc-capture=<FRAMES>

If RenderDoc is present, trigger a RenderDoc capture of FRAMES.

--renderdoc-path=<STRING>

Set the path to the renderdoc.dll library to use for OpenGL ES capturing. If undefined, the Player will attempt to locate automatically. Windows only.

--renderdoc-log-path-template=<STRING>

Define the filename template for the RenderDoc output.

--preload

Preload all the calls before playing.

--large-data-memory-hint

A hint (in mb) at how much large data, such as buffers and textures, should be resident in memory.

--dump-frame-times

Collect and write frame times to csv file.

--dump-frame-times-filename=<STRING>

Set the output path for the frame times.

--dump-gpu-timestamps=<MODES>

Collect and write gpu timestamps to csv files.

Supported modes are: [frames, command-buffers]. Defaults to frames.

Example: --dump-gpu-timestamps=frames,command-buffers

--dump-gpu-timestamps-path=<STRING>

Set the output path for the gpu timestamp files.

--dump-gpu-timestamps-base-filename=<STRING>

Set the base name used for the gpu timestamp files. Example: --dump-gpu-timestamps-base-filename=demo when combined with --dump-gpu-timestamps=frames will use demo_frame_gpu_timestamps.csv for gpu timestamps.

--frame-delimiters=<CALLS>

A comma-separated list of calls to break frames on. Supported values are: [eglSwapBuffers, vkQueuePresentKHR, glFinish, glFlush].

--disable-capture-replay

Disable Vulkan capture replay functionality if supported by the platform.

--ws=<VALUE>

Choose the windowing system to use. Supported values will be given by running --help on your system.

--display=<VALUE>

Choose the display to render to. This may not be supported on the chosen windowing system.

--portrait

If supported by the window system, force the screen orientation to portrait.

--landscape

If supported by the window system, force the screen orientation to landscape.

--drm-device

If supported by the platform, define the DRM device to use for native buffer playback via DMA buffers. Default: /dev/dri/card0

--mode#

Supported modes are:

  • normal - the default mode;

  • profile - enables --preload and increases the --large-data-memory-hint value to reduce I/O stalls. Also enables --disable-vsync if supported.

--capture-frames#

These options expect a String in the form of a list of integers signifying frames to be recorded and/or saved. This list can take many forms and has many functions associated with it:

  • Individual frames are specified as a comma-separated list e.g. 10,20,30.

  • Ranges can be defined, also as part of a list e.g. 10,20-25,30.

  • Multiple ranges can be specified.

Ellipses (...) can also be used to repeat the last defined range or sequence. The behaviour of ellipses is defined as:

  • If the preceding element is a range, that range will be repeated either until the end of the recording, or until a new element is specified.

  • If the preceding element of the ellipsis is an individual number, the next previous element will be used to determine the behaviour:

    • If the second element is another number, the ellipsis will treat the two numbers as a linear sequence to be repeated.

    • If the second element is a range, the ellipsis will repeat the range every X frames, where X is the difference between the end of the range and the number.

Here are some example use cases to illustrate these:

  • “10” will record frame 10.

  • “10,14” will record frames 10 and 14.

  • “10-14” will record frames 10 to 14, inclusive.

  • “10-14,15-19” will record frames 10 to 14, inclusive to one file, and 15 to 19, inclusive to another.

  • “10-14,…” will repeatedly record a section of 5 frames starting from frame 10. The first file will contain frames 10-14, inclusive. The next will contain frames 15-19, inclusive. This repeats until the recording stops.

  • “10-14,20…” will repeatedly record a section of 5 frames every 10 frames starting from frame 10. The first file will contain frames 10-14, inclusive. The next will contain frames 20-24, inclusive. This repeats until the recording stops.

  • “10-14,20…,100” will be the same as above, but will stop at (and include) frame 100.

  • “50-99,150…” will record frames 50-99, then frames 150-199, then frames 250-299, etc.

  • “0,2…” will record every second frame (0, 2, 4, 6, etc.).

  • “0,2…,10” will record every second frame up to frame 10, inclusive.

Note

Regarding --renderdoc-capture for Linux users: OpenGL ES RenderDoc captures require the RenderDoc library to be preloaded using LD_PRELOAD. e.g. LD_PRELOAD=/renderdoc/librenderdoc.so PVRCarbonPlayer.

Additional Information#

Options are applied in the order specified on the command line.

If PVRTC and ETC2 are not supported by your Vulkan implementation, the player, if possible, will use the provided PowerVR format emulation layer to emulate their support. Note, this emulation will decompress these formats to R8G8B8A8.