PVRCarbon Player Command Line Options#

-h, --help

Display the help and exit.

--version

Print version information and exit.

--mode

Place the player into a particular 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

--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 surfaces. Equivalent to defining --create-windows with an empty list.

For Vulkan, if VK_EXT_headless_surface is supported it will be used for the offscreen surfaces. For other APIs and where it isn’t supported, API specific surfaces (e.g. GL FBOs, VkImages) will be used. As such, when API surfaces are used no API calls for swapping/presenting will be performed.

--mark-frame-boundaries

If supported, use VK_EXT_frame_boundary to mark an end of a frame during playback. This is useful when rendering all or part of a recording offscreen. As such, this option is enabled automatically when –offscreen or –create-windows is defined. This feature can be disabled by --mark-frame-boundaries=0.

--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=<EXTS>

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

--add-device-extensions=<EXTS>

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

--ignore-instance-extensions=<EXTS>

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

--ignore-device-extensions=<EXTS>

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.

Note

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

--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. The resulting csv file will have the following format:

frame-number, frame-time - frame-number the frame number. - frame-time the nanoseconds since the start of the application.

--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

Collect and write gpu timestamps to csv files.

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

Note

For Vulkan, the resulting csv files will have the following formats:

  • frames - frame-number, queue-handle, timestamp

    • frame-number corresponds to the frame number.

    • queue-handle corresponds to the queue upon which the vkQueuePresentKHR call was issued.

    • timestamp corresponds to nanoseconds since the start of the application.

  • command-buffers - frame-number, queue-handle, command-buffer, start-timestamp, end-timestamp

    • frame-number corresponds to the frame number.

    • queue-handle corresponds to the queue to which the command buffer was submitted.

    • command-buffer corresponds to the submitted command buffer.

    • start-timestamp corresponds to a timestamp in nanoseconds since the start of the application written at the beginning of the command buffer.

    • end-timestamp corresponds to a timestamp in nanoseconds since the start of the application written at the end of the command buffer.

Note

For OpenGL ES, only frames gpu timestamps are supported and require support for EGL_ANDROID_GLES_layers. The gpu timestamps are provided by a GLES layer that is shipped within the player APK and has to be enabled before the player is launched. This can be done with the following commands in an adb shell:

settings put global enable_gpu_debug_layers 1 settings put global gpu_debug_app com.powervr.carbon.player settings put global gpu_debug_layers_gles libGlLayer_PowerVR_gpu_timestamps.so

These settings will persist until deleted:

settings delete global enable_gpu_debug_layers settings delete global gpu_debug_app settings delete global gpu_debug_layers_gles

The generated csv file will have the following format:

  • swap, uid, timestamp

    • swap corresponds to the swap buffers the timestamp is taken from

    • uid corresponds to the call Uid of the swap buffers call

    • timestamp corresponds to the number of nanoseconds since the previous swap or in the case of the first swap, the time since the context was first made current

--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, vkQueueWaitIdle, vkFrameBoundary, glFinish, glFlush, clEnqueueRead, clEnqueueMap, IDXGISwapChainPresent]

--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.

--buffer-impl=<VALUE>

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

--buffer-drm-device`

If supported by the platform, define the DRM device to use for native buffer playback via DMA buffers. Default: The first /dev/dri/card* device that supports DRM dumb buffers.

--buffer-dma-heap

If supported by the platform, define the DMA heap to use for native buffer playback via heap allocated DMA buffers. Default: /dev/dma_heap/system.

--pixmap-impl=<VALUE>

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

--pixmap-drm-device`

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

--export-shaders, --export-shaders=<PATH>

Export the recorded source/data for shaders to files in PATH or the current working directory allowing for modification.

--import-shaders, --import-shaders=<PATH>

Import shaders previously exported with --export-shaders from PATH or the current working directory. The imported shaders will then be used for playback overriding the recorded source/data.

Note

--import-shaders cannot be used at the same time as --export-shaders. For --dump-frame-times/--dump-gpu-timestamps frames are incremented by vkQueuePresentKHR calls and vkQueueSubmit calls with a VkFrameBoundaryEXT structure included in its pNext chain with VkFrameBoundaryEXT-flags including VK_FRAME_BOUNDARY_FRAME_END_BIT_EXT.

--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.

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.