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 data 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_native_pixmap_type`	Type: String. Define the platform’s native pixmap type. See below for more information.
`PVRCARBON_memory_tracking_enable`	Type: Boolean. Enable the recorder’s memory tracking to track writes made to coherent mapped memory.
`PVRCARBON_memory_tracking_mode`	Type: String. Define the method used for tracking memory writes. See below for more information.
`PVRCARBON_page_guard_sync`	Type: String. Define the level of synchronisation performed when the memory tracking mode is set to `page_guard`. See below for more information.
`PVRCARBON_page_guard_align_memory`	Type: Boolean. When the memory tracking mode is set to `page_guard` and synchronisation is disabled for writes you may have issues with missing data if more than one API object (e.g. Buffer) exist in the same page. This option forces alignment of objects to be at the page boundaries so only one may exist in a page.

`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
vkFrameBoundary
glFinish
glFlush
clEnqueueRead
clEnqueueMap
IDXGISwapChainPresent

eglSwapBuffers, vkQueuePresentKHR, and IDXGISwapChainPresent 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.

`PVRCARBON_native_pixmap_type`#

This option defines the platform’s native pixmap type. Supported values are:

none

The platform doesn’t have a native pixmap type.
default

Use the default defined native pixmap type for the platform.
rel

The platform uses EGLNativePixmapTypeREL for its native pixmap type.

`PVRCARBON_memory_tracking_mode`#

This option defines the method to use when memory tracking is enabled. Supported values are:

page_guard

This method where supported is the default and uses the page guard technique for tracking writes to coherent mapped memory. This method creates protected shadow memory for catching reads and writes made to the memory. The shadow memory is synchronised with the mapped memory at various points.
compare

Slow and inefficient method that takes a copy of the coherent mapped memory and compares it to the mapped memory writing out any differences.

`PVRCARBON_page_guard_sync`#

This option defines the level of synchronisation performed between the page guard’s shadow memory and the GPU mapped memory when the page_guard implementation detects a read or a write. Supported values are:

read or r

On detected reads synchronise the shadow memory with the mapped memory.
write or w

On detected writes synchronise the shadow memory with the mapped memory.
read_write or rw

On detected reads and writes synchronise the shadow memory with the mapped memory.
disable

Do not synchronise the shadow memory with the mapped memory when a read or write is detected. Synchronisation will still occur on particular API calls.

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

eglSwapBuffers, vkQueuePresentKHR, and IDXGISwapChainPresent 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

Memory Tracking Options#

Option	Description
`enable`	Type: Boolean. Enable the recorder’s memory tracking to track writes made to coherent mapped memory.
`mode`	Type: String. Define the method used for tracking memory writes. See below for more information.

`mode`#

This option defines the method to use when memory tracking is enabled. Supported values are:

page_guard

This method where supported is the default and uses the page guard technique for tracking writes to coherent mapped memory. This method creates protected shadow memory for catching reads and writes made to the memory. The shadow memory is synchronised with the mapped memory at various points.
compare

Slow and inefficient method that takes a copy of the coherent mapped memory and compares it to the mapped memory writing out any differences.

Page Guard Options#

These options allow you to configure various aspects of the page_guard memory tracking mode.

Option	Description
`sync`	Type: String. Define the level of synchronisation performed. See below for more information.
`align_memory`	Type: Boolean. When synchronisation is disabled for writes you may have issues with missing data if more than one API object (e.g. Buffer) exist in the same page. This option forces alignment of objects to be at the page boundaries so only one may exist in a page.

`sync`#

This option defines the level of synchronisation performed between the shadow memory and the GPU mapped memory when a read or write is detected. Supported values are:

read or r

On detected reads synchronise the shadow memory with the mapped memory.
write or w

On detected writes synchronise the shadow memory with the mapped memory.
read_write or rw

On detected reads and writes synchronise the shadow memory with the mapped memory.
disable

Do not synchronise the shadow memory with the mapped memory when a read or write is detected. Synchronisation will still occur on particular API calls.

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

Native Pixmap Options#

Option	Description
`type`	Type: String. Define the platform’s native pixmap type. See below for more information.

`type`#

This option defines the platform’s native pixmap type. Supported values are:

none

The platform doesn’t have a native pixmap type.
default

Use the default defined native pixmap type for the platform.
rel

The platform uses EGLNativePixmapTypeREL for its native pixmap type.

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"
        },
        "memoryTracking":
        {
            "enable": true,
            "mode": "page_guard"
        },
        "pageGuard":
        {
            "sync": "read_write",
            "align_memory": false
        },
        "nativeBuffer":
        {
            "enable": true
        }
    }
}

Appendices#

Environment Variables#

PVRCARBON_frames and PVRCARBON_frame_grab_frames#

PVRCARBON_frame_delimiters#

PVRCARBON_flush_behaviour#

PVRCARBON_native_pixmap_type#

PVRCARBON_memory_tracking_mode#

PVRCARBON_page_guard_sync#

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#

Memory Tracking Options#

mode#

Page Guard Options#

sync#

Debug Options#

Native Buffer Options#

Native Pixmap Options#

type#

PVRCarbon Recorder Example Configuration File#

`PVRCARBON_frames` and `PVRCARBON_frame_grab_frames`#

`PVRCARBON_frame_delimiters`#

`PVRCARBON_flush_behaviour`#

`PVRCARBON_native_pixmap_type`#

`PVRCARBON_memory_tracking_mode`#

`PVRCARBON_page_guard_sync`#

`frames`#

`frameDelimiters`#

`flushBehaviour`#

`frames`#

`mode`#

`sync`#

`type`#