LunarG

Copyright © 2015-2022 LunarG, Inc.

Creative Commons

VK_LAYER_LUNARG_api_dump

The VK_LAYER_LUNARG_api_dump utility layer prints API calls, parameters, and values to the identified output stream.



Configuring the API Dump Layer

For an overview of how to configure layers, refer to the Layers Overview and Configuration document.

The API Dump Layer settings are documented in the Layer Details section below.

The API Dump Layer can also be enabled and configured using vkconfig. See the vkconfig documentation for more information.

Enabling the API Dump Layer

Desktop (Linux/Windows/MacOS)

You must add the location of the VK_LAYER_LUNARG_api_dump.json file and corresponding VkLayer_api_dump library to your VK_LAYER_PATH in order for the Vulkan loader to be able to find the layer.

Then, you must also enable the layer in one of two ways:

Setting VK_LAYER_PATH

Windows

If your source was located in: C:\my_folder\vulkantools and your build folder was build64, then you would add it to the layer path in the following way:

set VK_LAYER_PATH=C:\my_folder\vulkantools\build64\layersvt\Debug;%VK_LAYER_PATH%

Linux/MacOS

If your source was located in: /my_folder/vulkantools and your build folder was build, then you would add it to the layer path in the following way:

export VK_LAYER_PATH=/my_folder/vulkantools/build/layersvt:$VK_LAYER_PATH

Enabling the layer with VK_INSTANCE_LAYERS

To force the layer to be enabled for Vulkan applications, you can set the VK_INSTANCE_LAYERS environment variable in the following way:

Windows

set VK_INSTANCE_LAYERS=VK_LAYER_LUNARG_api_dump

Linux/MacOS

export VK_INSTANCE_LAYERS=VK_LAYER_LUNARG_api_dump



Android

Permissions

You may need to grant permissions to your application to write to system storage, even if it normally does not. This depends on whether or not you modify API Dump to output to a file or just leave it to output to text.

If you're building with Android Studio, you do this by:

If this does not work, you may still require enabling permissions for your application from the settings menu.

Failure to do so will result in your application crashing during vkCreateInstance since the layer will attempt, but fail, to create the capture file.

Globally Enabling the Layer

Use ADB to enable the layer for your project by:

adb shell "setprop debug.vulkan.layers 'VK_LAYER_LUNARG_api_dump'"

When done, disable the layer using:

adb shell "setprop debug.vulkan.layers ''"



Applying Environment Settings on Android

On Android, you must use properties to set the layer environment variables. The format of the properties to set takes the following form:

debug. + (lower-case environment variable with 'vk_' stripped)

The easiest way to set a property is from the ADB shell:

adb shell "setprop <property_name> '<property_value>'"

For example:

To set the API Dump output log filename, which on desktop uses VK_API_DUMP_LOG_FILENAME set the following property:

debug.vulkan.api_dump.log_filename

Which you can set in the following way:

adb shell "setprop debug.vulkan.api_dump.log_filename '/sdcard/Android/vk_apidump.txt'"



Layer Details

Layer Properties

Layer Settings Overview

Setting Type Default Value vk_layer_settings.txt Variable Environment Variable Platforms
Output Range STRING 0-0 lunarg_api_dump.output_range VK_APIDUMP_OUTPUT_RANGE WINDOWS, LINUX, MACOS, ANDROID
Output Format ENUM text lunarg_api_dump.output_format VK_APIDUMP_OUTPUT_FORMAT WINDOWS, LINUX, MACOS, ANDROID
Output to File BOOL false lunarg_api_dump.file VK_LUNARG_API_DUMP_FILE WINDOWS, LINUX, MACOS, ANDROID
Log Filename SAVE_FILE stdout lunarg_api_dump.log_filename VK_APIDUMP_LOG_FILENAME WINDOWS, LINUX, MACOS, ANDROID
Log Flush After Write BOOL true lunarg_api_dump.flush VK_APIDUMP_FLUSH WINDOWS, LINUX, MACOS, ANDROID
Name Size INT 32 lunarg_api_dump.name_size VK_LUNARG_API_DUMP_NAME_SIZE WINDOWS, LINUX, MACOS, ANDROID
Show Types BOOL true lunarg_api_dump.show_types VK_LUNARG_API_DUMP_SHOW_TYPES WINDOWS, LINUX, MACOS, ANDROID
Type Size INT 0 lunarg_api_dump.type_size VK_LUNARG_API_DUMP_TYPE_SIZE WINDOWS, LINUX, MACOS, ANDROID
Show Timestamp BOOL false lunarg_api_dump.timestamp VK_APIDUMP_TIMESTAMP WINDOWS, LINUX, MACOS, ANDROID
Show Shader BOOL false lunarg_api_dump.show_shader VK_LUNARG_API_DUMP_SHOW_SHADER WINDOWS, LINUX, MACOS, ANDROID
Show Parameter Details BOOL true lunarg_api_dump.detailed VK_APIDUMP_DETAILED WINDOWS, LINUX, MACOS, ANDROID
Hide Addresses BOOL false lunarg_api_dump.no_addr VK_APIDUMP_NO_ADDR WINDOWS, LINUX, MACOS, ANDROID
Use Spaces BOOL true lunarg_api_dump.use_spaces VK_LUNARG_API_DUMP_USE_SPACES WINDOWS, LINUX, MACOS, ANDROID
Indent Size INT 4 lunarg_api_dump.indent_size VK_LUNARG_API_DUMP_INDENT_SIZE WINDOWS, LINUX, MACOS, ANDROID
Show Thread and Frame BOOL true lunarg_api_dump.show_thread_and_frame VK_LUNARG_API_DUMP_SHOW_THREAD_AND_FRAME WINDOWS, LINUX, MACOS, ANDROID

Layer Settings Details

Output Range

Comma separated list of frames to output or a range of frames with a start, count, and optional interval separated by a dash. A count of 0 will output every frame after the start of the range. Example: "5-8-2" will output frame 5, continue until frame 13, dumping every other frame. Example: "3,8-2" will output frames 3, 8, and 9.

Setting Properties:

Output Format

Specifies the format used for output; can be HTML, JSON, or Text (default -- outputs plain text)

Setting Properties:
Enum Value Label Description Platforms
text Text Plain text WINDOWS, LINUX, MACOS, ANDROID
html HTML HTML WINDOWS, LINUX, MACOS, ANDROID
json JSON Json WINDOWS, LINUX, MACOS, ANDROID

Output to File

Setting this to true indicates that output should be written to file instead of stdout

Setting Properties:

Log Filename

Specifies the file to dump to when output files are enabled

Setting Properties:

Log Flush After Write

Setting this to true causes IO to be flushed after each API call that is written

Setting Properties:

Name Size

The number of characters the name of a variable should consume, assuming more are not required

Setting Properties:

Show Types

Dump types in addition to values

Setting Properties:

Type Size

The number of characters the name of a type should consume, assuming more are not required

Setting Properties:

Show Timestamp

Show the timestamp of function calls since start in microseconds

Setting Properties:

Show Shader

Dump the shader binary code in pCode

Setting Properties:

Show Parameter Details

Dump parameter details in addition to API calls

Setting Properties:

Hide Addresses

Dump "address" in place of hex addresses

Setting Properties:

Use Spaces

Setting this to true causes all tab characters to be replaced with spaces

Setting Properties:

Indent Size

Specifies the number of spaces that a tab is equal to

Setting Properties:

Show Thread and Frame

Show the thread and frame of each function called

Setting Properties:

Layer Presets

Console Output

Output API dump to stdout

Preset Setting Values:

Text Output

Output API dump to a text file

Preset Setting Values:

HTML Output

Output API dump to a HTML file

Preset Setting Values:

JSON Output

Output API dump to a JSON file

Preset Setting Values: