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 Properties

Layer Settings Overview

Label Variables Key Type Default Value Platforms
Output Range output_range STRING 0-0 WINDOWS_X86, WINDOWS_ARM, LINUX, MACOS, ANDROID
Output Format output_format ENUM text WINDOWS_X86, WINDOWS_ARM, LINUX, MACOS, ANDROID
    Pre-dump the parameters. pre_dump BOOL false WINDOWS_X86, WINDOWS_ARM, LINUX, MACOS, ANDROID
Output to File file BOOL false WINDOWS_X86, WINDOWS_ARM, LINUX, MACOS, ANDROID
    Log Filename log_filename SAVE_FILE stdout WINDOWS_X86, WINDOWS_ARM, LINUX, MACOS, ANDROID
Log Flush After Write flush BOOL true WINDOWS_X86, WINDOWS_ARM, LINUX, MACOS, ANDROID
Name Size name_size INT 32 WINDOWS_X86, WINDOWS_ARM, LINUX, MACOS, ANDROID
Show Types show_types BOOL true WINDOWS_X86, WINDOWS_ARM, LINUX, MACOS, ANDROID
    Type Size type_size INT 0 WINDOWS_X86, WINDOWS_ARM, LINUX, MACOS, ANDROID
Show Timestamp timestamp BOOL false WINDOWS_X86, WINDOWS_ARM, LINUX, MACOS, ANDROID
Show Shader show_shader BOOL false WINDOWS_X86, WINDOWS_ARM, LINUX, MACOS, ANDROID
Show Parameter Details detailed BOOL true WINDOWS_X86, WINDOWS_ARM, LINUX, MACOS, ANDROID
Hide Addresses no_addr BOOL false WINDOWS_X86, WINDOWS_ARM, LINUX, MACOS, ANDROID
Use Spaces use_spaces BOOL true WINDOWS_X86, WINDOWS_ARM, LINUX, MACOS, ANDROID
    Indent Size indent_size INT 4 WINDOWS_X86, WINDOWS_ARM, LINUX, MACOS, ANDROID
Show Thread and Frame show_thread_and_frame BOOL true WINDOWS_X86, WINDOWS_ARM, 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.

Methods:
VK_EXT_layer_settings:
const char* data[] = { "0-0" };
VkLayerSettingEXT setting {
 "VK_LAYER_LUNARG_api_dump", "output_range", VK_LAYER_SETTING_TYPE_STRING_EXT,
 static_cast<uint32_t>(std::size(data)), data };
vk_layer_settings.txt:
lunarg_api_dump.output_range = 0-0
Environment variables:
export VK_LUNARG_API_DUMP_OUTPUT_RANGE=0-0
export VK_API_DUMP_OUTPUT_RANGE=0-0
export VK_OUTPUT_RANGE=0-0
export VK_APIDUMP_OUTPUT_RANGE=0-0
Android system properties:
adb setprop debug.vulkan.lunarg_api_dump.output_range 0-0
adb setprop debug.vulkan.api_dump.output_range 0-0
adb setprop debug.vulkan.output_range 0-0

Output Format

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

Sub-setting: Pre-dump the parameters.,

Enum Value Label Description Platforms
text Text Plain text WINDOWS_X86, WINDOWS_ARM, LINUX, MACOS, ANDROID
html HTML HTML WINDOWS_X86, WINDOWS_ARM, LINUX, MACOS, ANDROID
json JSON Json WINDOWS_X86, WINDOWS_ARM, LINUX, MACOS, ANDROID
Methods:
VK_EXT_layer_settings:
const char* data[] = { "text" };
VkLayerSettingEXT setting {
 "VK_LAYER_LUNARG_api_dump", "output_format", VK_LAYER_SETTING_TYPE_STRING_EXT,
 static_cast<uint32_t>(std::size(data)), data };
vk_layer_settings.txt:
lunarg_api_dump.output_format = text
Environment variables:
export VK_LUNARG_API_DUMP_OUTPUT_FORMAT=text
export VK_API_DUMP_OUTPUT_FORMAT=text
export VK_OUTPUT_FORMAT=text
export VK_APIDUMP_OUTPUT_FORMAT=text
Android system properties:
adb setprop debug.vulkan.lunarg_api_dump.output_format text
adb setprop debug.vulkan.api_dump.output_format text
adb setprop debug.vulkan.output_format text

Pre-dump the parameters.

Setting this to true causes parameters to calls be logged before the function as well as after the function.

Dependences Variables Key Type Value
Output Format output_format ENUM text
Methods:
VK_EXT_layer_settings:
VkBool32 data[] = { VK_FALSE };
VkLayerSettingEXT setting {
 "VK_LAYER_LUNARG_api_dump", "pre_dump", VK_LAYER_SETTING_TYPE_BOOL32_EXT,
 static_cast<uint32_t>(std::size(data)), data };
vk_layer_settings.txt:
lunarg_api_dump.pre_dump = false
Environment variables:
export VK_LUNARG_API_DUMP_PRE_DUMP=false
export VK_API_DUMP_PRE_DUMP=false
export VK_PRE_DUMP=false
export VK_APIDUMP_PRE_DUMP=false
Android system properties:
adb setprop debug.vulkan.lunarg_api_dump.pre_dump false
adb setprop debug.vulkan.api_dump.pre_dump false
adb setprop debug.vulkan.pre_dump false

Output to File

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

Sub-setting: Log Filename,

Methods:
VK_EXT_layer_settings:
VkBool32 data[] = { VK_FALSE };
VkLayerSettingEXT setting {
 "VK_LAYER_LUNARG_api_dump", "file", VK_LAYER_SETTING_TYPE_BOOL32_EXT,
 static_cast<uint32_t>(std::size(data)), data };
vk_layer_settings.txt:
lunarg_api_dump.file = false
Environment variables:
export VK_LUNARG_API_DUMP_FILE=false
export VK_API_DUMP_FILE=false
export VK_FILE=false
Android system properties:
adb setprop debug.vulkan.lunarg_api_dump.file false
adb setprop debug.vulkan.api_dump.file false
adb setprop debug.vulkan.file false

Log Filename

Specifies the file to dump to when output files are enabled.

Dependences Variables Key Type Value
Output to File file BOOL true
Methods:
VK_EXT_layer_settings:
const char* data[] = { "stdout" };
VkLayerSettingEXT setting {
 "VK_LAYER_LUNARG_api_dump", "log_filename", VK_LAYER_SETTING_TYPE_STRING_EXT,
 static_cast<uint32_t>(std::size(data)), data };
vk_layer_settings.txt:
lunarg_api_dump.log_filename = stdout
Environment variables:
export VK_LUNARG_API_DUMP_LOG_FILENAME=stdout
export VK_API_DUMP_LOG_FILENAME=stdout
export VK_LOG_FILENAME=stdout
export VK_APIDUMP_LOG_FILENAME=stdout
Android system properties:
adb setprop debug.vulkan.lunarg_api_dump.log_filename stdout
adb setprop debug.vulkan.api_dump.log_filename stdout
adb setprop debug.vulkan.log_filename stdout

Log Flush After Write

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

Methods:
VK_EXT_layer_settings:
VkBool32 data[] = { VK_TRUE };
VkLayerSettingEXT setting {
 "VK_LAYER_LUNARG_api_dump", "flush", VK_LAYER_SETTING_TYPE_BOOL32_EXT,
 static_cast<uint32_t>(std::size(data)), data };
vk_layer_settings.txt:
lunarg_api_dump.flush = true
Environment variables:
export VK_LUNARG_API_DUMP_FLUSH=true
export VK_API_DUMP_FLUSH=true
export VK_FLUSH=true
export VK_APIDUMP_FLUSH=true
Android system properties:
adb setprop debug.vulkan.lunarg_api_dump.flush true
adb setprop debug.vulkan.api_dump.flush true
adb setprop debug.vulkan.flush true

Name Size

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

Methods:
VK_EXT_layer_settings:
int32_t data[] = { 32 };
VkLayerSettingEXT setting {
 "VK_LAYER_LUNARG_api_dump", "name_size", VK_LAYER_SETTING_TYPE_INT32_EXT,
 static_cast<uint32_t>(std::size(data)), data };
vk_layer_settings.txt:
lunarg_api_dump.name_size = 32
Environment variables:
export VK_LUNARG_API_DUMP_NAME_SIZE=32
export VK_API_DUMP_NAME_SIZE=32
export VK_NAME_SIZE=32
Android system properties:
adb setprop debug.vulkan.lunarg_api_dump.name_size 32
adb setprop debug.vulkan.api_dump.name_size 32
adb setprop debug.vulkan.name_size 32

Show Types

Dump types in addition to values.

Sub-setting: Type Size,

Methods:
VK_EXT_layer_settings:
VkBool32 data[] = { VK_TRUE };
VkLayerSettingEXT setting {
 "VK_LAYER_LUNARG_api_dump", "show_types", VK_LAYER_SETTING_TYPE_BOOL32_EXT,
 static_cast<uint32_t>(std::size(data)), data };
vk_layer_settings.txt:
lunarg_api_dump.show_types = true
Environment variables:
export VK_LUNARG_API_DUMP_SHOW_TYPES=true
export VK_API_DUMP_SHOW_TYPES=true
export VK_SHOW_TYPES=true
Android system properties:
adb setprop debug.vulkan.lunarg_api_dump.show_types true
adb setprop debug.vulkan.api_dump.show_types true
adb setprop debug.vulkan.show_types true

Type Size

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

Dependences Variables Key Type Value
Show Types show_types BOOL true
Methods:
VK_EXT_layer_settings:
int32_t data[] = { 0 };
VkLayerSettingEXT setting {
 "VK_LAYER_LUNARG_api_dump", "type_size", VK_LAYER_SETTING_TYPE_INT32_EXT,
 static_cast<uint32_t>(std::size(data)), data };
vk_layer_settings.txt:
lunarg_api_dump.type_size = 0
Environment variables:
export VK_LUNARG_API_DUMP_TYPE_SIZE=0
export VK_API_DUMP_TYPE_SIZE=0
export VK_TYPE_SIZE=0
Android system properties:
adb setprop debug.vulkan.lunarg_api_dump.type_size 0
adb setprop debug.vulkan.api_dump.type_size 0
adb setprop debug.vulkan.type_size 0

Show Timestamp

Show the timestamp of function calls since start in microseconds.

Methods:
VK_EXT_layer_settings:
VkBool32 data[] = { VK_FALSE };
VkLayerSettingEXT setting {
 "VK_LAYER_LUNARG_api_dump", "timestamp", VK_LAYER_SETTING_TYPE_BOOL32_EXT,
 static_cast<uint32_t>(std::size(data)), data };
vk_layer_settings.txt:
lunarg_api_dump.timestamp = false
Environment variables:
export VK_LUNARG_API_DUMP_TIMESTAMP=false
export VK_API_DUMP_TIMESTAMP=false
export VK_TIMESTAMP=false
export VK_APIDUMP_TIMESTAMP=false
Android system properties:
adb setprop debug.vulkan.lunarg_api_dump.timestamp false
adb setprop debug.vulkan.api_dump.timestamp false
adb setprop debug.vulkan.timestamp false

Show Shader

Dump the shader binary code in pCode.

Methods:
VK_EXT_layer_settings:
VkBool32 data[] = { VK_FALSE };
VkLayerSettingEXT setting {
 "VK_LAYER_LUNARG_api_dump", "show_shader", VK_LAYER_SETTING_TYPE_BOOL32_EXT,
 static_cast<uint32_t>(std::size(data)), data };
vk_layer_settings.txt:
lunarg_api_dump.show_shader = false
Environment variables:
export VK_LUNARG_API_DUMP_SHOW_SHADER=false
export VK_API_DUMP_SHOW_SHADER=false
export VK_SHOW_SHADER=false
Android system properties:
adb setprop debug.vulkan.lunarg_api_dump.show_shader false
adb setprop debug.vulkan.api_dump.show_shader false
adb setprop debug.vulkan.show_shader false

Show Parameter Details

Dump parameter details in addition to API calls.

Methods:
VK_EXT_layer_settings:
VkBool32 data[] = { VK_TRUE };
VkLayerSettingEXT setting {
 "VK_LAYER_LUNARG_api_dump", "detailed", VK_LAYER_SETTING_TYPE_BOOL32_EXT,
 static_cast<uint32_t>(std::size(data)), data };
vk_layer_settings.txt:
lunarg_api_dump.detailed = true
Environment variables:
export VK_LUNARG_API_DUMP_DETAILED=true
export VK_API_DUMP_DETAILED=true
export VK_DETAILED=true
export VK_APIDUMP_DETAILED=true
Android system properties:
adb setprop debug.vulkan.lunarg_api_dump.detailed true
adb setprop debug.vulkan.api_dump.detailed true
adb setprop debug.vulkan.detailed true

Hide Addresses

Dump "address" in place of hex addresses.

Methods:
VK_EXT_layer_settings:
VkBool32 data[] = { VK_FALSE };
VkLayerSettingEXT setting {
 "VK_LAYER_LUNARG_api_dump", "no_addr", VK_LAYER_SETTING_TYPE_BOOL32_EXT,
 static_cast<uint32_t>(std::size(data)), data };
vk_layer_settings.txt:
lunarg_api_dump.no_addr = false
Environment variables:
export VK_LUNARG_API_DUMP_NO_ADDR=false
export VK_API_DUMP_NO_ADDR=false
export VK_NO_ADDR=false
export VK_APIDUMP_NO_ADDR=false
Android system properties:
adb setprop debug.vulkan.lunarg_api_dump.no_addr false
adb setprop debug.vulkan.api_dump.no_addr false
adb setprop debug.vulkan.no_addr false

Use Spaces

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

Sub-setting: Indent Size,

Methods:
VK_EXT_layer_settings:
VkBool32 data[] = { VK_TRUE };
VkLayerSettingEXT setting {
 "VK_LAYER_LUNARG_api_dump", "use_spaces", VK_LAYER_SETTING_TYPE_BOOL32_EXT,
 static_cast<uint32_t>(std::size(data)), data };
vk_layer_settings.txt:
lunarg_api_dump.use_spaces = true
Environment variables:
export VK_LUNARG_API_DUMP_USE_SPACES=true
export VK_API_DUMP_USE_SPACES=true
export VK_USE_SPACES=true
Android system properties:
adb setprop debug.vulkan.lunarg_api_dump.use_spaces true
adb setprop debug.vulkan.api_dump.use_spaces true
adb setprop debug.vulkan.use_spaces true

Indent Size

Specifies the number of spaces that a tab is equal to.

Dependences Variables Key Type Value
Use Spaces use_spaces BOOL true
Methods:
VK_EXT_layer_settings:
int32_t data[] = { 4 };
VkLayerSettingEXT setting {
 "VK_LAYER_LUNARG_api_dump", "indent_size", VK_LAYER_SETTING_TYPE_INT32_EXT,
 static_cast<uint32_t>(std::size(data)), data };
vk_layer_settings.txt:
lunarg_api_dump.indent_size = 4
Environment variables:
export VK_LUNARG_API_DUMP_INDENT_SIZE=4
export VK_API_DUMP_INDENT_SIZE=4
export VK_INDENT_SIZE=4
Android system properties:
adb setprop debug.vulkan.lunarg_api_dump.indent_size 4
adb setprop debug.vulkan.api_dump.indent_size 4
adb setprop debug.vulkan.indent_size 4

Show Thread and Frame

Show the thread and frame of each function called.

Methods:
VK_EXT_layer_settings:
VkBool32 data[] = { VK_TRUE };
VkLayerSettingEXT setting {
 "VK_LAYER_LUNARG_api_dump", "show_thread_and_frame", VK_LAYER_SETTING_TYPE_BOOL32_EXT,
 static_cast<uint32_t>(std::size(data)), data };
vk_layer_settings.txt:
lunarg_api_dump.show_thread_and_frame = true
Environment variables:
export VK_LUNARG_API_DUMP_SHOW_THREAD_AND_FRAME=true
export VK_API_DUMP_SHOW_THREAD_AND_FRAME=true
export VK_SHOW_THREAD_AND_FRAME=true
Android system properties:
adb setprop debug.vulkan.lunarg_api_dump.show_thread_and_frame true
adb setprop debug.vulkan.api_dump.show_thread_and_frame true
adb setprop debug.vulkan.show_thread_and_frame true

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: