Appendices#

This section contains tables detailing environment variables and options for PVRCarbon Recorder.

Environment Variables#

Note

See Configuration Options for how to use these environment variables.

Environment Variable	Explanation
`PVRCARBON_output_debug`	Type: Boolean. Output debug information.
`PVRCARBON_output_verbose`	Type: Boolean. Output verbose information.
`PVRCARBON_output_information`	Type: Boolean. Output information.
`PVRCARBON_output_warning`	Type: Boolean. Output warning information.
`PVRCARBON_output_error`	Type: Boolean. Output error information.
`PVRCARBON_output_calls`	Type: Boolean. Output call information.
`PVRCARBON_filename`	Type: String. Carbon recording (`.pvrcbn`) filename.
`PVRCARBON_frames`	Type: String. A comma-separated list of frames to record. See below for more information.
`PVRCARBON_frame_delimiters`	Type: String. A comma-separated list of calls to break frames on. See below for more information.
`PVRCARBON_bundle_parts`	Type: Boolean. Zip up the intermediate `.pvrcbn.part` files into a single `.pvrcbn` file.
`PVRCARBON_compress_bundle`	Type: Boolean. Compress the parts when zipping them up.
`PVRCARBON_record_unknown_calls`	Type: Boolean. If supported, record the name of unrecognised calls.
`PVRCARBON_frame_grab_enable`	Type: Boolean. Save a capture of the frame to a file.
`PVRCARBON_frame_grab_downscale`	Type: Int. Downscale the captured frame by the given value.
`PVRCARBON_frame_grab_frames`	Type: String. A comma-separated list of frames to capture. See below for more information.
`PVRCARBON_override_egl_vendor`	Type: String. Override the value returned when querying `EGL_VENDOR`.
`PVRCARBON_override_egl_version`	Type: String. Override the value returned when querying `EGL_VERSION`.
`PVRCARBON_override_gl_vendor`	Type: String. Override the value returned when querying `GL_VENDOR`.
`PVRCARBON_override_gl_renderer`	Type: String. Override the value returned when querying `GL_RENDERER`.
`PVRCARBON_override_gl_version`	Type: String. Override the value returned when querying `GL_VERSION`.
`PVRCARBON_override_vk_version`	Type: String. Override the API version returned when querying physical device properties. The `major.minor.patch` format must be followed.
`PVRCARBON_override_swap_interval`	Type: Int. Override the swap interval.
`PVRCARBON_disable_BC`	Type: Boolean. Disable the reporting of BC texture compression support.
`PVRCARBON_disable_ETC1`	Type: Boolean. Disable the reporting of ETC1 texture compression support.
`PVRCARBON_disable_ETC2`	Type: Boolean. Disable the reporting of ETC2 texture compression support.
`PVRCARBON_disable_ASTC`	Type: Boolean. Disable the reporting of ASTC texture compression support.
`PVRCARBON_disable_binary_shaders`	Type: Boolean. Disable support for binary shaders. Defaults to true.
`PVRCARBON_disable_identifiers`	Type: Boolean. Disable support for shader module identifiers. Defaults to true.
`PVRCARBON_disable_coherent_bit`	Type: Boolean. Remove the coherent bit from all memory properties.
`PVRCARBON_disable_extensions`	Type: String. A comma-separated list of extensions that the API should not report.
`PVRCARBON_align_memory_map`	Type: Boolean/UInt. Override the minimum required alignment for mapped memory offsets. If set to true, a recommended value is used.
`PVRCARBON_align_texel_buffer`	Type: Boolean/UInt. Override the minimum required alignment for texel buffer offsets. If set to true, a recommended value is used.
`PVRCARBON_align_uniform_buffer`	Type: Boolean/UInt. Override the minimum required alignment for uniform buffer offsets. If set to true, a recommended value is used.
`PVRCARBON_align_storage_buffer`	Type: Boolean/UInt. Override the minimum required alignment for storage buffer offsets. If set to true, a recommended value is used.
`PVRCARBON_align_memory`	Type: Boolean/UInt. Override the minimum required alignment for memory requirement offsets. If set to true, a recommended value is used.
`PVRCARBON_align_atom_size`	Type: Boolean/UInt. Override the non-coherent atom size. If set to true, a recommended value is used.
`PVRCARBON_align_recommended`	Type: Boolean. Override the minimum required alignment options with recommended values.
`PVRCARBON_flush_behaviour`	Type: UInt. Set the flushing behaviour. See below for more information.
`PVRCARBON_exit_after_frame`	Type: UInt. Exit after the nth frame.
`PVRCARBON_network_enable`	Type: Boolean. Enable network recording.
`PVRCARBON_config`	Type: String. Path from which to load the json config.
`PVRCARBON_api_validation_enable`	Type: Boolean. Enable use of API validation.
`PVRCARBON_api_validation_verbose`	Type: Boolean. Enable verbose API validation messages.
`PVRCARBON_api_validation_info`	Type: Boolean. Enable informational API validation messages.
`PVRCARBON_api_validation_warning`	Type: Boolean. Enable API validation messages at warning level.
`PVRCARBON_api_validation_error`	Type: Boolean. Enable API validation messages at error level.
`PVRCARBON_api_validation_record`	Type: Boolean. Record API validation messages.
`PVRCARBON_native_buffer_enable`	Type: Boolean. Enable native buffer recording.
`PVRCARBON_native_buffer_diff`	Type: Boolean. Record native buffers only when their contents have changed.
`PVRCARBON_native_buffer_frequency`	Type: UInt. Set the frame frequency of native buffer recording. 0 indicates once.
`PVRCARBON_native_buffer_drm_device`	Type: String. Set the DRM device to use for native buffer recording. If undefined, PVRCarbon will query `/dev/dri/card0` - `/dev/dri/card9` to find the device.

`PVRCARBON_frames` and `PVRCARBON_frame_grab_frames`#

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

`PVRCARBON_frame_delimiters`#

Supported values for this variable are:

eglSwapBuffers
vkQueuePresentKHR
vkQueueWaitIdle
glFinish
glFlush
clEnqueueRead
clEnqueueMap

eglSwapBuffers and vkQueuePresentKHR are selected as default.

`PVRCARBON_flush_behaviour`#

This variable expects a value ranging from 0-5, inclusive. The below table explains the behaviour of each value:

Value	Description
0	No Flushing (default).
1	Disable buffering of data blocks.
2	Disable buffering and flush after arguments.
3	Disable buffering and flush after functions.
4	Disable buffering and flush after arguments and functions.
5	Disable buffering and flush at the end of every frame.

Recording Options#

Option	Description
`filename`	Type: String. The name of the `.pvrcbn` file.
`frames`	Type: String. A comma-separated list of frames to record. See below for more information.
`frameDelimiters`	Type: String. A comma-separated list of calls to break frames on. See below for more information.
`bundleParts`	Type: Boolean. Zip up the intermediate `.pvrcbn.part` files into a single `.pvrcbn` file.
`compressBundle`	Type: Boolean. Compress the parts when zipping them up.
`flushBehaviour`	Type: UInt. Set the flushing behaviour. See below for more information.
`exitAfterFrame`	Type: Int. Exit after the nth frame.
`processName`	Type: String. The name of the process to record.

`frames`#

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

`frameDelimiters`#

Supported values for this variable are:

eglSwapBuffers
vkQueuePresentKHR
vkQueueWaitIdle
glFinish
glFlush
clEnqueueRead
clEnqueueMap

eglSwapBuffers and vkQueuePresentKHR are selected as default.

`flushBehaviour`#

This variable expects a value ranging from 0-5, inclusive. The below table explains the behaviour of each value:

Value	Description
0	No Flushing (default).
1	Disable buffering of data blocks.
2	Disable buffering and flush after arguments.
3	Disable buffering and flush after functions.
4	Disable buffering and flush after arguments and functions.
5	Disable buffering and flush at the end of every frame.

Output Options#

Option	Description
`debug`	Type: Boolean. Output debug information.
`verbose`	Type: Boolean. Output verbose information.
`information`	Type: Boolean. Output information.
`warning`	Type: Boolean. Output warnings when they occur.
`error`	Type: Boolean. Output errors when they occur.

API Validation Options#

Option	Description
`enable`	Type: Boolean. Output API validation messages.
`verbose`	Type: Boolean. Output verbose API validation messages.
`information`	Type: Boolean. Output API validation messages at information level.
`warning`	Type: Boolean. Output API validation messages at warning level.
`error`	Type: Boolean. Output API validation messages at error level.
`record`	Type: Boolean. Record API validation messages.

Override Options#

General Override Options#

Option	Description
`swapInterval`	Override the swap interval.

EGL Override Options#

Option	Description
`vendor`	Override the value returned when querying `EGL_VENDOR`.
`version`	Override the value returned when querying `EGL_VERSION`.

GL Override Options#

Option	Description
`vendor`	Override the value returned when querying `GL_VENDOR`.
`renderer`	Override the value returned when querying `GL_RENDERER`.
`version`	Override the value returned when querying `GL_VERSION`.

Vulkan Override Options#

Option	Description
`version`	Override the API version returned when querying physical device properties. The `major.minor.patch` format must be followed.

Disable Options#

Option	Description
`BC`	Type: Boolean. Disable BC texture compression.
`ETC1`	Type: Boolean. Disable ETC1 texture compression (OpenGL ES only).
`ETC2`	Type: Boolean. Disable ETC2 texture compression (Vulkan only).
`ASTC`	Type: Boolean. Disable ASTC texture compression.
`binaryShaders`	Type: Boolean. Disable binary shaders. Defaults to true.
`identifiers`	Type: Boolean. Disable support for shader module identifiers. Defaults to true.
`coherentBit`	Type: Boolean. Remove coherent bit from all memory properties.
`extensions`	Type: String. A comma-separated list of extensions that the API should not report.

Align Options#

Option	Description
`memoryMap`	Type: Boolean/UInt. Override the minimum required alignment for mapped memory offsets. If set to true, a recommended value is used.
`texelBuffer`	Type: Boolean/UInt. Override the minimum required alignment for texel buffer offsets. If set to true, a recommended value is used.
`uniformBuffer`	Type: Boolean/UInt. Override the minimum required alignment for uniform buffer offsets. If set to true, a recommended value is used.
`storageBuffer`	Type: Boolean/UInt. Override the minimum required alignment for storage buffer offsets. If set to true, a recommended value is used.
`memory`	Type: Boolean/UInt. Override the minimum required alignment for memory requirement offsets. If set to true, a recommended value is used.
`atomSize`	Type: Boolean/UInt. Override the non-coherent atom size. If set to true, a recommended value is used.
`shaderBase`	Type: Boolean/UInt. Override the shader group base alignment. If set to true, a recommended value is used.
`shaderHandle`	Type: Boolean/UInt. Override the shader group handle alignment. If set to true, a recommended value is used.
`recommended`	Type: Boolean. Override all minimum required alignment options with recommended values.

Frame Grab Options#

Option	Description
`enable`	Type: Boolean. Save a capture of the frame to a file.
`downscale`	Type: Int. Downscale the captured frame by the given value.
`frames`	Type: String. A comma-separated list of frames to capture. See below for more information.

`frames`#

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

Network Options#

Option	Description
`enable`	Type: Boolean. Enable network recording

Debug Options#

Option	Description
`outputCalls`	Type: Boolean. Output the call name and parameters as they are called.
`serialiseCalls`	Type: Boolean. Serialises the API calls in a multi-threaded application.
`log`	Type:String. Output the log to a given filename.

Native Buffer Options#

Option	Description
`enable`	Type: Boolean. Enable native buffer recording.
`diff`	Type: Boolean. Record native buffers only when their contents have changed.
`frequency`	Type: UInt. Set the frame frequency of native buffer recording. 0 indicates once.
`drmDevice`	Type: String. Set the DRM device to use for native buffer recording. If undefined, PVRCarbon will query `/dev/dri/card0` - `/dev/dri/card9` to find the device.

PVRCarbon Recorder Example Configuration File#

The following is an example of a standard PVRCarbon recorder configuration file.

{
    "recording":
    {
        "hostLibrary":
        {
            "egl": "C:/Windows/System32/libEGL.dll",
            "glesv2": "C:/Windows/System32/libGLESv2.dll"
        },
        "output":
        {
            "debug": false,
            "verbose": false,
            "information": false,
            "warning": true,
            "error": true
        },
        "filename": "File.pvrcbn",
        "bundleParts": true,
        "compressBundle": true,
        "flushBehaviour": 0,
        "exitAfterFrame": 4294967295,
        "override":
        {
            "egl":
            {
            },
            "gl":
            {
            },
            "vk":
            {
            },
            "swapInterval" : 0
        },
        "disable":
        {
            "BC": false,
            "ETC1": false,
            "ETC2": false,
            "ASTC": false,
            "binaryShaders": false,
            "extensions": ""
        },
        "align":
        {
            "memoryMap": true,
            "texelBuffer": true,
            "uniformBuffer": true,
            "storageBuffer": true,
            "memory": true,
            "atomSize": true
        },
        "network":
        {
            "enable": false
        },
        "frameGrab":
        {
            "enable": true,
            "downscale": 8,
            "frames":"0,10-100"
        },
        "nativeBuffer":
        {
            "enable": true
        }
    }
}

Appendices#

Environment Variables#

PVRCARBON_frames and PVRCARBON_frame_grab_frames#

PVRCARBON_frame_delimiters#

PVRCARBON_flush_behaviour#

Recording Options#

frames#

frameDelimiters#

flushBehaviour#

Output Options#

API Validation Options#

Override Options#

General Override Options#

EGL Override Options#

GL Override Options#

Vulkan Override Options#

Disable Options#

Align Options#

Frame Grab Options#

frames#

Network Options#

Debug Options#

Native Buffer Options#

PVRCarbon Recorder Example Configuration File#

`PVRCARBON_frames` and `PVRCARBON_frame_grab_frames`#

`PVRCARBON_frame_delimiters`#

`PVRCARBON_flush_behaviour`#

`frames`#

`frameDelimiters`#

`flushBehaviour`#

`frames`#