# Layers Overview and Configuration

Vulkan supports intercepting or hooking API entry points via the layer framework. A layer can intercept all or any subset of Vulkan API entry points. Multiple layers can be chained together to cascade their functionality in the appearance of a single, larger layer.

Vulkan validation and utility layers give Vulkan application developers the ability to add additional functionality to applications without modifying the application itself, e.g., dumping api entry points or generating screenshots of specified frames.

## Layers Included in the SDK

The LunarG Vulkan SDK includes the following layers:

Layer Name | Layer Type | Description
--- | --- | ---
`VK_LAYER_LUNARG_api_dump` | utility | print API calls and their parameters and values
`VK_LAYER_LUNARG_assistant_layer` | utility | highlight potential application issues that are not specifically prohibited by the Vulkan spec, but which can still create problems
`VK_LAYER_LUNARG_core_validation` | validation | print and validate the descriptor set, pipeline state, and dynamic state; validate the interfaces between SPIR-V modules and the graphics pipeline; track and validate GPU memory and its binding to objects and command buffers; validate texture formats and render target formats
`VK_LAYER_LUNARG_device_simulation` | utility | allows modification of an actual device's reported features, limits, and capabilities
`VK_LAYER_LUNARG_monitor` | utility | outputs the frames-per-second of the target application in the applications title bar
`VK_LAYER_LUNARG_object_tracker` | validation | track all Vulkan objects and flag invalid objects and object memory leaks
`VK_LAYER_LUNARG_parameter_validation` | validation | validate API parameter values
`VK_LAYER_LUNARG_screenshot` | utility | outputs specified frames to an image file as they are presented
`VK_LAYER_GOOGLE_threading` | validation | check validity of multi-threaded API usage
`VK_LAYER_GOOGLE_unique_objects` | utility | wrap all Vulkan objects in a unique pointer at create time and unwrap them at use time

See the Validation Layers and Utility Layers sections for more information about validation and utility layers.

## A Note on Layer Message Types

Vulkan layers will output messages of several types. It is important to note the meaning of the ERROR type as compared to the WARN type:

Type | Definitions
--- | ---
Error | Errors are output when a layer detects some application behavior has violated the Vulkan Specification. When an error is encountered it is recommended that the user callback function return 'true' for optimal validation results. Any validation error may result in undefined behavior and errors should be corrected as they are encountered for best results
Warn | Warnings are output in cases where mistakes are commonly made and do NOT necessarily indicate that an app has violated the Vulkan specification. Warnings basically translate to 'Did you really mean to do this?'
Perf Warn | Performance Warnings are output in cases where a possible inefficiency has been detected. These also do NOT imply that the specification was violated
Info | These log messages are for informational purposes only. For instance, the core validation layer can print out lists of memory objects and their bindings which may help with debugging or improving application efficiency

## Configuring Layers on Linux

The Vulkan loader searches the `/usr/share/vulkan/implicit_layer.d`, `/usr/share/vulkan/explicit_layer.d`, `/etc/vulkan/implicit_layer.d`, `/etc/vulkan/explicit_layer.d` `$HOME/.local/share/vulkan/explicit_layer.d`, and `$HOME/.local/share/vulkan/implicit_layer.d` directories for layer JSON manifest files.

Sample layer manifest file (`core_validation.json`):

    {
        "file_format_version" : "1.0.0",
        "layer" : {
            "name": "VK_LAYER_LUNARG_core_validation",
            "type": "GLOBAL",
            "library_path": "libVKLayer_core_validation.so",
            "api_version": "1.0.21",
            "implementation_version": "1",
            "description": "LunarG Validation Layer",
            "instance_extensions": [
                 {
                     "name": "VK_EXT_debug_report",
                     "spec_version": "3"
                 }
             ]
        }
    }

Full and relative (to JSON manifest file) `library_path` names are supported, as are unqualified file names. If just a filename is specified, the loader will search the default library directory (e.g., `/usr/lib/x86_64-linux-gnu/` on Ubuntu x64) for the layer shared library.

Setting the `VK_LAYER_PATH` environment variable overrides the default loader layer search mechanism. When set, the loader will search only the directory(s) identified by `$VK_LAYER_PATH` for layer manifest files.

Applications can query available layers via the `vkEnumerateInstanceLayerProperties()` command.

## Configuring Layers on Windows

The Vulkan loader searches the following registry keys to find layers:

    HKEY_LOCAL_MACHINE\SOFTWARE\Khronos\Vulkan\ExplicitLayers
    HKEY_LOCAL_MACHINE\SOFTWARE\Khronos\Vulkan\ImplicitLayers

For each value in each of the above two keys for which DWORD data is set to 0, the Vulkan loader opens the json text file specified by the value name. For example, if the `HKEY_LOCAL_MACHINE\SOFTWARE\Khronos\Vulkan\ExplicitLayers` key contains the following value:

    Name                                          Type         Data
    C:\VulkanSDK\1.0.21\Bin\core_validation.json   REG_DWORD    0x00000000

The loader will open the file `C:\VulkanSDK\1.0.21\Bin\core_validation.json` to find the pathname to the layer library file. The `core_validation.json` file might contain:

    {
        "file_format_version" : "1.0.0",
        "layer" : {
            "name": "VK_LAYER_LUNARG_core_validation",
            "type": "GLOBAL",
            "library_path": ".\\libVKLayer_core_validation.dll",
            "api_version": "1.0.21",
            "implementation_version": "1",
            "description": "LunarG Validation Layer",
            "instance_extensions": [
                 {
                     "name": "VK_EXT_debug_report",
                     "spec_version": "3"
                 }
             ]
        }
    }

Full and relative (to JSON manifest file) `library_path` names are supported, as are unqualified file names. If just a filename is specified, the loader will search the default library directory (typically `C:\Windows\System32`) for the layer shared library. For the above example, the layer library file for the `VK_LAYER_LUNARG_core_validation` layer is `libVKLayer_core_validation.dll`, and that file will be loaded from `C:\VulkanSDK\1.0.21\Bin` and used by the loader if the `VK_LAYER_LUNARG_core_validation` layer is activated.

## Activating Layers on Linux

Before or during execution of a Vulkan application, the loader must be informed of the layers to activate. Applications can activate layers at runtime via the `vkCreateInstance()` entry point.

Layers configured in `/usr/share/vulkan/implicit_layer.d`, `$HOME/.local/share/vulkan/implicit_layer.d`, and `/etc/vulkan/implicit_layer.d` are activated automatically by the Loader.

Layers configured in `/usr/share/vulkan/explicit_layer.d`, `$HOME/.local/share/vulkan/explicit_layer.d`, and `/etc/vulkan/explicit_layer.d` can be activated by applications at runtime. These explicit layers can also be activated by the user by setting the `VK_INSTANCE_LAYERS` environment variable. Set this variable to identify a colon separated list of layer names to activate. Order is relevant with the first layer in the list being the topmost layer (closest to the application) and the last layer in the list being the bottom-most layer (closest to the driver).

For example, the list of explicit layers to activate can be specified with:

    $ export VK_INSTANCE_LAYERS=VK_LAYER_LUNARG_api_dump:VK_LAYER_LUNARG_core_validation

To activate layers in a local SDK install, identify certain library paths and the layer JSON manifest file directory in addition to the layers to activate. If the Vulkan SDK was locally installed to `/sdks`, `VULKAN_SDK=/sdks/VulkanSDK/1.0.21/x86_64`:

    $ export VK_LAYER_PATH=$VULKAN_SDK/lib/vulkan/layers
    $ export LD_LIBRARY_PATH=$VULKAN_SDK/lib:$VULKAN_SDK/lib/vulkan/layers
    $ export VK_INSTANCE_LAYERS=VK_LAYER_LUNARG_api_dump:VK_LAYER_LUNARG_core_validation
    $ ./cube

Developers may choose to activate all Vulkan validation layers simply by using `VK_LAYER_LUNARG_standard_validation`. (See the Validation Layers page for more information about the standard validation meta-layer.) To do so via the environment:

    $ export VK_INSTANCE_LAYERS=VK_LAYER_LUNARG_standard_validation

Alternatively, the layers can be loaded manually like so:

    $ export VK_INSTANCE_LAYERS=VK_LAYER_LUNARG_core_validation:VK_LAYER_LUNARG_object_tracker:VK_LAYER_LUNARG_parameter_validation:VK_LAYER_GOOGLE_threading:VK_LAYER_GOOGLE_unique_objects

## Activating Layers on Windows

Before or during execution of a Vulkan application, the loader must be informed of the layers to activate. Applications can activate layers at runtime via the `vkCreateInstance()` entry point.

Layers configured in registry key `HKEY_LOCAL_MACHINE\SOFTWARE\Khronos\Vulkan\ImplicitLayers` are activated automatically by the Loader.

Layers configured in registry key `HKEY_LOCAL_MACHINE\SOFTWARE\Khronos\Vulkan\ExplicitLayers` can be activated by applications at runtime. These explicit layers can also be activated by the user by setting the `VK_INSTANCE_LAYERS` environment variable. Set this variable to identify a semi-colon separated list of layer names to activate. Order is relevant with the first layer in the list being the topmost layer (closest to the application) and the last layer in the list being the bottom-most layer (closest to the driver).

In a Command Window, the list of explicit layers to activate can be specified with:

    C:\> set VK_INSTANCE_LAYERS=VK_LAYER_LUNARG_api_dump;VK_LAYER_LUNARG_core_validation

`VK_INSTANCE_LAYERS` can also be set in the system environment variables.

To activate layers located in a particular SDK install, identify the layer JSON manifest file directory using the `VK_LAYER_PATH` environment variable. For example, if a Vulkan SDK is locally installed to `C:\VulkanSDK\1.0.21`:

    C:\> set VK_LAYER_PATH=C:\VulkanSDK\1.0.21\Bin
    C:\> set VK_INSTANCE_LAYERS=VK_LAYER_LUNARG_api_dump;VK_LAYER_LUNARG_core_validation
    C:\> cube

Developers may choose to activate all Vulkan validation layers simply by using `VK_LAYER_LUNARG_standard_validation`. (See the Validation Layers page for more information about the standard validation meta-layer.) To do so via the environment:

    C:\> set  VK_INSTANCE_LAYERS=VK_LAYER_LUNARG_standard_validation

Alternatively, the layers can be loaded manually like so:

    C:\> set  VK_INSTANCE_LAYERS=VK_LAYER_LUNARG_core_validation;VK_LAYER_LUNARG_object_tracker;VK_LAYER_LUNARG_parameter_validation;VK_LAYER_GOOGLE_threading

## Layer Controls

There are two general methods for controlling layer behavior supported by most of the layers listed herein: layer settings file and a debug extension. The layer settings file provides a general mechanism for a user to control various layer behaviors by providing arbitrary settings. Currently the layer settings file has settings only pertaining to layer message logging.

There are currently two available debug extensions: VK_EXT_debug_utils and VK_EXT_debug_report. Both are available for use by applications to programmatically control layer message logging. `VK_EXT_debug_utils` is preferable to `VK_EXT_debug_report` as the later extension has become deprecated and will not continue to evolve with the Vulkan API. However, `VK_EXT_debug_report` will continue to work for existing applications supporting Vulkan 1.0 should that be all you require.

Vulkan layers support both methods.

### Layer Settings File

In addition to activating the layers, specific reporting levels must be set for each layer programmatically or via the `vk_layer_settings.txt` settings file. If no environment variable variable `VK_LAYER_SETTINGS_PATH` is set, then this must be a file called `vk_layer_settings.txt` in the working directory of the application. If `VK_LAYER_SETTINGS_PATH` is set and is a directory, then the settings file must be a file called `vk_layer_settings.txt` in the directory given by `VK_LAYER_SETTINGS_PATH`. If `VK_LAYER_SETTINGS_PATH` is set and is not a directory, then it must point to a file (with any name) which is the layer settings file.

Note: To generate layer reporting output, a layer settings file must be provided that identifies specific reporting levels for the layers enabled via the `VK_INSTANCE_LAYER` environment variable.

The settings file consists of comment lines and settings lines. Comment lines begin with the `#` character. Settings lines have the following format:

`<``LayerName``><``setting_name``> = <``setting_value``>`

Three settings are common to all layers:

Setting | Values | Description
--- | --- | ---
`LayerName``.report_flags` | `info` | Report information level messages
| `warn` | Report warning level messages
| `perf` | Report performance level warning messages
| `error` | Report error level messages
| `debug` | No output messages
`LayerName``.debug_action` | `VK_DBG_LAYER_ACTION_IGNORE` | Ignore message reporting
| `VK_DBG_LAYER_ACTION_LOG_MSG` | Report messages to log
| `VK_DBG_LAYER_ACTION_DEBUG_OUTPUT` | (Windows) Report messages to debug console of Microsoft Visual Studio
| `VK_DBG_LAYER_ACTION_BREAK` | Break on messages (not currently used)
`LayerName``.log_filename` | `filename``.txt` | Name of file to log `report_flags` level messages; default is `stdout`

Layer-specific settings are also supported in the layer settings file.

Sample layer settings file contents:

    lunarg_core_validation.report_flags = info,error
    lunarg_core_validation.debug_action = VK_DBG_LAYER_ACTION_LOG_MSG
    # VK_LAYER_LUNARG_api_dump custom settings
    lunarg_api_dump.no_addr = TRUE
    lunarg_api_dump.file = FALSE

The LunarG Vulkan SDK includes a sample layer settings file identifying the available and supported settings for each layer. On Linux, you can find the sample layer settings file in `config/vk_layer_settings.txt` of your local Vulkan SDK install. On Windows, you can find the sample layer settings file in `Config\vk_layer_settings.txt` of your local Vulkan SDK install.

Note: If layers are activated via `VK_INSTANCE_LAYER` environment variable and if neither an application-defined callback is defined nor a layer settings file is present, the loader/layers will provide default callbacks enabling output of error-level messages to standard out (and via `OutputDebugString` on Windows).

### VK\_EXT\_debug\_utils The preferred method for an app to control layer logging is via `VK_EXT_debug_utils` extension. Using `VK_EXT_debug_utils` extension allows an application to register multiple messengers with the layers. Each messenger can trigger a message callback when a log message occurs. Some messenger callbacks may log the information to a file, others may cause a debug break point or other application defined behavior. An application can create a messenger even when no layers are enabled, but they will only be called for loader and, if implemented, driver events. Each message is identified by both a severity level and a message type. Severity levels indicate the severity of the message that should be logged including: error, warning, etc. Message types indicate the specific type of message including: validation, performance, etc. Some layers return a unique message ID string per message as well. Using the severity, type, and message ID, an application can easily filter the messages received by their messenger callback.

#### Message Types As Reported By VK_EXT_debug_utils flags:

Type | Debug Utils Severity | Debug Utils Type
--- | --- | ---
Error | `VK_DEBUG_UTILS_MESSAGE_SEVERITY_ERROR_BIT_EXT` | `VK_DEBUG_UTILS_MESSAGE_TYPE_VALIDATION_BIT_EXT`
Warn | `VK_DEBUG_UTILS_MESSAGE_SEVERITY_WARNING_BIT_EXT` | `VK_DEBUG_UTILS_MESSAGE_TYPE_VALIDATION_BIT_EXT`
Perf Warn | `VK_DEBUG_UTILS_MESSAGE_SEVERITY_WARNING_BIT_EXT` | `VK_DEBUG_UTILS_MESSAGE_TYPE_PERFORMANCE_BIT_EXT`
Info | `VK_DEBUG_UTILS_MESSAGE_SEVERITY_INFO_BIT_EXT` | `VK_DEBUG_UTILS_MESSAGE_TYPE_GENERAL_BIT_EXT` or `VK_DEBUG_UTILS_MESSAGE_TYPE_VALIDATION_BIT_EXT`

Refer to the Debug Utils Messenger section of the full Vulkan Spec for details on this extension.

### VK\_EXT\_debug\_report The `VK_EXT_debug_report` extension provides functionality similar to the `VK_EXT_debug_utils` extension. **It has been deprecated and should not be used for new applications.** Instead, use the new `VK_EXT_debug_utils` extension for your applications.

#### Message Types As Reported By VK_EXT_debug_report flags:

Type | Debug Report Flag
--- | ---
Error | `VK_DEBUG_REPORT_ERROR_BIT_EXT`
Warn | `VK_DEBUG_REPORT_WARNING_BIT_EXT`
Perf Warn | `VK_DEBUG_REPORT_PERFORMANCE_WARNING_BIT_EXT`
Info | `VK_DEBUG_REPORT_INFORMATION_BIT_EXT`

If you are still interested in learning more about this extension, refer to the "Debug Report Callbacks" section of the full Vulkan Spec for more details.