Copyright © 2015-2022 LunarG, Inc.
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:
- Directly in your application using the layer's name during vkCreateInstance
- Indirectly by using the
VK_INSTANCE_LAYERSenvironment variable.
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:
- Click on "Run" in the menu
- Choose "Edit Configurations..."
- In the dialog box, look for the "Install Flags:" text box
- Enter -g
- Click "Apply"
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
- API Version: 1.4.313
- Implementation Version: 2
- Layer Manifest: VkLayer_api_dump.json
- File Format: 1.2.0
- Layer Binary: libVkLayer_api_dump.so
- Variables:
- vk_layer_settings.txt namespace: lunarg_api_dump
- Environment Variable prefix: VK_LUNARG_API_DUMP_
- Android system property prefix: adb setprop debug.vulkan.lunarg_api_dump.
- Platforms: WINDOWS_X86, WINDOWS_ARM, LINUX, MACOS, ANDROID
- Number of Layer Settings: 15
- Number of Layer Presets: 4
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 |
| 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.
| Setting Methods | Setting Variables |
|---|---|
| VK_EXT_layer_settings variable: | output_range |
| vk_layer_settings.txt variable: | lunarg_api_dump.output_range |
| Environment variables: | VK_LUNARG_API_DUMP_OUTPUT_RANGE |
| VK_API_DUMP_OUTPUT_RANGE | |
| VK_OUTPUT_RANGE | |
| VK_APIDUMP_OUTPUT_RANGE | |
| Android system properties : | adb setprop debug.vulkan.lunarg_api_dump.output_range |
| adb setprop debug.vulkan.api_dump.output_range | |
| adb setprop debug.vulkan.output_range |
- Type: STRING
- Default Value: 0-0
- Platforms: WINDOWS_X86, WINDOWS_ARM, LINUX, MACOS, ANDROID
Output Format
Specifies the format used for output; can be HTML, JSON, or Text (default -- outputs plain text)
| Setting Methods | Setting Variables |
|---|---|
| VK_EXT_layer_settings variable: | output_format |
| vk_layer_settings.txt variable: | lunarg_api_dump.output_format |
| Environment variables: | VK_LUNARG_API_DUMP_OUTPUT_FORMAT |
| VK_API_DUMP_OUTPUT_FORMAT | |
| VK_OUTPUT_FORMAT | |
| VK_APIDUMP_OUTPUT_FORMAT | |
| Android system properties : | adb setprop debug.vulkan.lunarg_api_dump.output_format |
| adb setprop debug.vulkan.api_dump.output_format | |
| adb setprop debug.vulkan.output_format |
- Type: ENUM
- Default Value: text
- Platforms: WINDOWS_X86, WINDOWS_ARM, LINUX, MACOS, ANDROID
| 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 |
Output to File
Setting this to true indicates that output should be written to file instead of stdout
| Setting Methods | Setting Variables |
|---|---|
| VK_EXT_layer_settings variable: | file |
| vk_layer_settings.txt variable: | lunarg_api_dump.file |
| Environment variables: | VK_LUNARG_API_DUMP_FILE |
| VK_API_DUMP_FILE | |
| VK_FILE | |
| Android system properties : | adb setprop debug.vulkan.lunarg_api_dump.file |
| adb setprop debug.vulkan.api_dump.file | |
| adb setprop debug.vulkan.file |
- Type: BOOL
- Default Value: false
- Platforms: WINDOWS_X86, WINDOWS_ARM, LINUX, MACOS, ANDROID
Log Filename
Specifies the file to dump to when output files are enabled
| Setting Methods | Setting Variables |
|---|---|
| VK_EXT_layer_settings variable: | log_filename |
| vk_layer_settings.txt variable: | lunarg_api_dump.log_filename |
| Environment variables: | VK_LUNARG_API_DUMP_LOG_FILENAME |
| VK_API_DUMP_LOG_FILENAME | |
| VK_LOG_FILENAME | |
| VK_APIDUMP_LOG_FILENAME | |
| Android system properties : | adb setprop debug.vulkan.lunarg_api_dump.log_filename |
| adb setprop debug.vulkan.api_dump.log_filename | |
| adb setprop debug.vulkan.log_filename |
- Type: SAVE_FILE
- Default Value: stdout
- Platforms: WINDOWS_X86, WINDOWS_ARM, LINUX, MACOS, ANDROID
| Dependences | Variables Key | Type | Value |
|---|---|---|---|
| Output to File | file | BOOL | true |
Log Flush After Write
Setting this to true causes IO to be flushed after each API call that is written
| Setting Methods | Setting Variables |
|---|---|
| VK_EXT_layer_settings variable: | flush |
| vk_layer_settings.txt variable: | lunarg_api_dump.flush |
| Environment variables: | VK_LUNARG_API_DUMP_FLUSH |
| VK_API_DUMP_FLUSH | |
| VK_FLUSH | |
| VK_APIDUMP_FLUSH | |
| Android system properties : | adb setprop debug.vulkan.lunarg_api_dump.flush |
| adb setprop debug.vulkan.api_dump.flush | |
| adb setprop debug.vulkan.flush |
- Type: BOOL
- Default Value: true
- Platforms: WINDOWS_X86, WINDOWS_ARM, LINUX, MACOS, ANDROID
Name Size
The number of characters the name of a variable should consume, assuming more are not required
| Setting Methods | Setting Variables |
|---|---|
| VK_EXT_layer_settings variable: | name_size |
| vk_layer_settings.txt variable: | lunarg_api_dump.name_size |
| Environment variables: | VK_LUNARG_API_DUMP_NAME_SIZE |
| VK_API_DUMP_NAME_SIZE | |
| VK_NAME_SIZE | |
| Android system properties : | adb setprop debug.vulkan.lunarg_api_dump.name_size |
| adb setprop debug.vulkan.api_dump.name_size | |
| adb setprop debug.vulkan.name_size |
- Type: INT
- Default Value: 32
- Platforms: WINDOWS_X86, WINDOWS_ARM, LINUX, MACOS, ANDROID
Show Types
Dump types in addition to values
| Setting Methods | Setting Variables |
|---|---|
| VK_EXT_layer_settings variable: | show_types |
| vk_layer_settings.txt variable: | lunarg_api_dump.show_types |
| Environment variables: | VK_LUNARG_API_DUMP_SHOW_TYPES |
| VK_API_DUMP_SHOW_TYPES | |
| VK_SHOW_TYPES | |
| Android system properties : | adb setprop debug.vulkan.lunarg_api_dump.show_types |
| adb setprop debug.vulkan.api_dump.show_types | |
| adb setprop debug.vulkan.show_types |
- Type: BOOL
- Default Value: true
- Platforms: WINDOWS_X86, WINDOWS_ARM, LINUX, MACOS, ANDROID
Type Size
The number of characters the name of a type should consume, assuming more are not required
| Setting Methods | Setting Variables |
|---|---|
| VK_EXT_layer_settings variable: | type_size |
| vk_layer_settings.txt variable: | lunarg_api_dump.type_size |
| Environment variables: | VK_LUNARG_API_DUMP_TYPE_SIZE |
| VK_API_DUMP_TYPE_SIZE | |
| VK_TYPE_SIZE | |
| Android system properties : | adb setprop debug.vulkan.lunarg_api_dump.type_size |
| adb setprop debug.vulkan.api_dump.type_size | |
| adb setprop debug.vulkan.type_size |
- Type: INT
- Default Value: 0
- Platforms: WINDOWS_X86, WINDOWS_ARM, LINUX, MACOS, ANDROID
| Dependences | Variables Key | Type | Value |
|---|---|---|---|
| Show Types | show_types | BOOL | true |
Show Timestamp
Show the timestamp of function calls since start in microseconds
| Setting Methods | Setting Variables |
|---|---|
| VK_EXT_layer_settings variable: | timestamp |
| vk_layer_settings.txt variable: | lunarg_api_dump.timestamp |
| Environment variables: | VK_LUNARG_API_DUMP_TIMESTAMP |
| VK_API_DUMP_TIMESTAMP | |
| VK_TIMESTAMP | |
| VK_APIDUMP_TIMESTAMP | |
| Android system properties : | adb setprop debug.vulkan.lunarg_api_dump.timestamp |
| adb setprop debug.vulkan.api_dump.timestamp | |
| adb setprop debug.vulkan.timestamp |
- Type: BOOL
- Default Value: false
- Platforms: WINDOWS_X86, WINDOWS_ARM, LINUX, MACOS, ANDROID
Show Shader
Dump the shader binary code in pCode
| Setting Methods | Setting Variables |
|---|---|
| VK_EXT_layer_settings variable: | show_shader |
| vk_layer_settings.txt variable: | lunarg_api_dump.show_shader |
| Environment variables: | VK_LUNARG_API_DUMP_SHOW_SHADER |
| VK_API_DUMP_SHOW_SHADER | |
| VK_SHOW_SHADER | |
| Android system properties : | adb setprop debug.vulkan.lunarg_api_dump.show_shader |
| adb setprop debug.vulkan.api_dump.show_shader | |
| adb setprop debug.vulkan.show_shader |
- Type: BOOL
- Default Value: false
- Platforms: WINDOWS_X86, WINDOWS_ARM, LINUX, MACOS, ANDROID
Show Parameter Details
Dump parameter details in addition to API calls
| Setting Methods | Setting Variables |
|---|---|
| VK_EXT_layer_settings variable: | detailed |
| vk_layer_settings.txt variable: | lunarg_api_dump.detailed |
| Environment variables: | VK_LUNARG_API_DUMP_DETAILED |
| VK_API_DUMP_DETAILED | |
| VK_DETAILED | |
| VK_APIDUMP_DETAILED | |
| Android system properties : | adb setprop debug.vulkan.lunarg_api_dump.detailed |
| adb setprop debug.vulkan.api_dump.detailed | |
| adb setprop debug.vulkan.detailed |
- Type: BOOL
- Default Value: true
- Platforms: WINDOWS_X86, WINDOWS_ARM, LINUX, MACOS, ANDROID
Hide Addresses
Dump "address" in place of hex addresses
| Setting Methods | Setting Variables |
|---|---|
| VK_EXT_layer_settings variable: | no_addr |
| vk_layer_settings.txt variable: | lunarg_api_dump.no_addr |
| Environment variables: | VK_LUNARG_API_DUMP_NO_ADDR |
| VK_API_DUMP_NO_ADDR | |
| VK_NO_ADDR | |
| VK_APIDUMP_NO_ADDR | |
| Android system properties : | adb setprop debug.vulkan.lunarg_api_dump.no_addr |
| adb setprop debug.vulkan.api_dump.no_addr | |
| adb setprop debug.vulkan.no_addr |
- Type: BOOL
- Default Value: false
- Platforms: WINDOWS_X86, WINDOWS_ARM, LINUX, MACOS, ANDROID
Use Spaces
Setting this to true causes all tab characters to be replaced with spaces
| Setting Methods | Setting Variables |
|---|---|
| VK_EXT_layer_settings variable: | use_spaces |
| vk_layer_settings.txt variable: | lunarg_api_dump.use_spaces |
| Environment variables: | VK_LUNARG_API_DUMP_USE_SPACES |
| VK_API_DUMP_USE_SPACES | |
| VK_USE_SPACES | |
| Android system properties : | adb setprop debug.vulkan.lunarg_api_dump.use_spaces |
| adb setprop debug.vulkan.api_dump.use_spaces | |
| adb setprop debug.vulkan.use_spaces |
- Type: BOOL
- Default Value: true
- Platforms: WINDOWS_X86, WINDOWS_ARM, LINUX, MACOS, ANDROID
Indent Size
Specifies the number of spaces that a tab is equal to
| Setting Methods | Setting Variables |
|---|---|
| VK_EXT_layer_settings variable: | indent_size |
| vk_layer_settings.txt variable: | lunarg_api_dump.indent_size |
| Environment variables: | VK_LUNARG_API_DUMP_INDENT_SIZE |
| VK_API_DUMP_INDENT_SIZE | |
| VK_INDENT_SIZE | |
| Android system properties : | adb setprop debug.vulkan.lunarg_api_dump.indent_size |
| adb setprop debug.vulkan.api_dump.indent_size | |
| adb setprop debug.vulkan.indent_size |
- Type: INT
- Default Value: 4
- Platforms: WINDOWS_X86, WINDOWS_ARM, LINUX, MACOS, ANDROID
| Dependences | Variables Key | Type | Value |
|---|---|---|---|
| Use Spaces | use_spaces | BOOL | true |
Show Thread and Frame
Show the thread and frame of each function called
| Setting Methods | Setting Variables |
|---|---|
| VK_EXT_layer_settings variable: | show_thread_and_frame |
| vk_layer_settings.txt variable: | lunarg_api_dump.show_thread_and_frame |
| Environment variables: | VK_LUNARG_API_DUMP_SHOW_THREAD_AND_FRAME |
| VK_API_DUMP_SHOW_THREAD_AND_FRAME | |
| VK_SHOW_THREAD_AND_FRAME | |
| Android system properties : | adb setprop debug.vulkan.lunarg_api_dump.show_thread_and_frame |
| adb setprop debug.vulkan.api_dump.show_thread_and_frame | |
| adb setprop debug.vulkan.show_thread_and_frame |
- Type: BOOL
- Default Value: true
- Platforms: WINDOWS_X86, WINDOWS_ARM, LINUX, MACOS, ANDROID
Layer Presets
Console Output
Output API dump to stdout
Preset Setting Values:
- Output Format: text
- Log Filename: stdout
- Output to File: false
Text Output
Output API dump to a text file
Preset Setting Values:
- Output Format: text
- Log Filename: ${VK_LOCAL}/vk_apidump.txt
- Output to File: true
HTML Output
Output API dump to a HTML file
Preset Setting Values:
- Output Format: html
- Log Filename: ${VK_LOCAL}/vk_apidump.html
- Output to File: true
JSON Output
Output API dump to a JSON file
Preset Setting Values:
- Output Format: json
- Log Filename: ${VK_LOCAL}/vk_apidump.json
- Output to File: true