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_LAYERS` environment 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.303
- Implementation Version: 2
- Layer Manifest: VkLayer_api_dump.json
  - File Format: 1.2.0
  - Layer Binary: libVkLayer_api_dump.so
- Platforms: WINDOWS, LINUX, MACOS, ANDROID
- Number of Layer Settings: 12
- Number of Layer Presets: 4

### 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:

- vk_layer_settings.txt Variable: lunarg_api_dump.output_range
- Environment Variable: VK_APIDUMP_OUTPUT_RANGE
- Platforms: WINDOWS, LINUX, MACOS, ANDROID
- Setting Type: STRING
- Setting Default Value: 0-0

#### Output Format

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

##### Setting Properties:

- vk_layer_settings.txt Variable: lunarg_api_dump.output_format
- Environment Variable: VK_APIDUMP_OUTPUT_FORMAT
- Platforms: WINDOWS, LINUX, MACOS, ANDROID
- Setting Type: ENUM
- Setting Default Value: text

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:

- vk_layer_settings.txt Variable: lunarg_api_dump.file
- Environment Variable: VK_LUNARG_API_DUMP_FILE
- Platforms: WINDOWS, LINUX, MACOS, ANDROID
- Setting Type: BOOL
- Setting Default Value: false

#### Log Filename

Specifies the file to dump to when output files are enabled

##### Setting Properties:

- vk_layer_settings.txt Variable: lunarg_api_dump.log_filename
- Environment Variable: VK_APIDUMP_LOG_FILENAME
- Platforms: WINDOWS, LINUX, MACOS, ANDROID
- Setting Type: SAVE_FILE
- Setting Default Value: stdout

#### Log Flush After Write

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

##### Setting Properties:

- vk_layer_settings.txt Variable: lunarg_api_dump.flush
- Environment Variable: VK_APIDUMP_FLUSH
- Platforms: WINDOWS, LINUX, MACOS, ANDROID
- Setting Type: BOOL
- Setting Default Value: true

#### Name Size

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

##### Setting Properties:

- vk_layer_settings.txt Variable: lunarg_api_dump.name_size
- Environment Variable: VK_LUNARG_API_DUMP_NAME_SIZE
- Platforms: WINDOWS, LINUX, MACOS, ANDROID
- Setting Type: INT
- Setting Default Value: 32

#### Show Types

Dump types in addition to values

##### Setting Properties:

- vk_layer_settings.txt Variable: lunarg_api_dump.show_types
- Environment Variable: VK_LUNARG_API_DUMP_SHOW_TYPES
- Platforms: WINDOWS, LINUX, MACOS, ANDROID
- Setting Type: BOOL
- Setting Default Value: true

#### Type Size

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

##### Setting Properties:

- vk_layer_settings.txt Variable: lunarg_api_dump.type_size
- Environment Variable: VK_LUNARG_API_DUMP_TYPE_SIZE
- Platforms: WINDOWS, LINUX, MACOS, ANDROID
- Setting Type: INT
- Setting Default Value: 0

#### Show Timestamp

Show the timestamp of function calls since start in microseconds

##### Setting Properties:

- vk_layer_settings.txt Variable: lunarg_api_dump.timestamp
- Environment Variable: VK_APIDUMP_TIMESTAMP
- Platforms: WINDOWS, LINUX, MACOS, ANDROID
- Setting Type: BOOL
- Setting Default Value: false

#### Show Shader

Dump the shader binary code in pCode

##### Setting Properties:

- vk_layer_settings.txt Variable: lunarg_api_dump.show_shader
- Environment Variable: VK_LUNARG_API_DUMP_SHOW_SHADER
- Platforms: WINDOWS, LINUX, MACOS, ANDROID
- Setting Type: BOOL
- Setting Default Value: false

#### Show Parameter Details

Dump parameter details in addition to API calls

##### Setting Properties:

- vk_layer_settings.txt Variable: lunarg_api_dump.detailed
- Environment Variable: VK_APIDUMP_DETAILED
- Platforms: WINDOWS, LINUX, MACOS, ANDROID
- Setting Type: BOOL
- Setting Default Value: true

#### Hide Addresses

Dump "address" in place of hex addresses

##### Setting Properties:

- vk_layer_settings.txt Variable: lunarg_api_dump.no_addr
- Environment Variable: VK_APIDUMP_NO_ADDR
- Platforms: WINDOWS, LINUX, MACOS, ANDROID
- Setting Type: BOOL
- Setting Default Value: false

#### Use Spaces

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

##### Setting Properties:

- vk_layer_settings.txt Variable: lunarg_api_dump.use_spaces
- Environment Variable: VK_LUNARG_API_DUMP_USE_SPACES
- Platforms: WINDOWS, LINUX, MACOS, ANDROID
- Setting Type: BOOL
- Setting Default Value: true

#### Indent Size

Specifies the number of spaces that a tab is equal to

##### Setting Properties:

- vk_layer_settings.txt Variable: lunarg_api_dump.indent_size
- Environment Variable: VK_LUNARG_API_DUMP_INDENT_SIZE
- Platforms: WINDOWS, LINUX, MACOS, ANDROID
- Setting Type: INT
- Setting Default Value: 4

#### Show Thread and Frame

Show the thread and frame of each function called

##### Setting Properties:

- vk_layer_settings.txt Variable: lunarg_api_dump.show_thread_and_frame
- Environment Variable: VK_LUNARG_API_DUMP_SHOW_THREAD_AND_FRAME
- Platforms: WINDOWS, LINUX, MACOS, ANDROID
- Setting Type: BOOL
- Setting Default Value: true

### 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