Layers Overview and Configuration
Vulkan supports intercepting or hooking API entry points via a 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.
Configuring Vulkan Layers using Vulkan Configurator
Developers can configure layers through a graphical user interface. Vulkan Configurator allows full user control of Vulkan layers, including enabling or disabling specific layers, controlling layer order, changing layer settings, etc.
Configuring Vulkan Layers using Environment Variables
Application validation in Vulkan is implemented solely by the Khronos validation layer, VK_LAYER_KHRONOS_validation.
Initially, validation was implemented as a dozen or so individual layers with limited scope -- i.e., mem_tracker, object_tracker, device_limits, unique_objects, etc., and a standard validation meta-layer, VK_LAYER_LUNARG_standard_validation, was supplied to enforce a particular layer order. In order to simplify configuration, improve build times, and standardize layer interfaces, validation was further consolidated into the single, configurable Khronos validation layer, while the individual component layers and meta-layer have been deprecated. For additional detail, see the Unified Validation Layer whitepaper.
Validation Layer History
| Layer Name | Introduced | Status |
|---|---|---|
| VK_LAYER_KHRONOS_validation | March 2019 | Supported |
| VK_LAYER_LUNARG_standard_validation | February 2016 | Deprecated |
| VK_LAYER_LUNARG_core_validation | March 2016 | Deprecated |
| VK_LAYER_LUNARG_object_tracker | October 2014 | Deprecated |
| VK_LAYER_GOOGLE_threading | April 2015 | Deprecated |
| VK_LAYER_GOOGLE_unique_objects | December 2015 | Deprecated |
| VK_LAYER_LUNARG_parameter_validation | December 2014 | Deprecated |
| VK_LAYER_LUNARG_mem_tracker | November 2014 | Deprecated |
| VK_LAYER_LUNARG_draw_state | October 2014 | Deprecated |
| VK_LAYER_LUNARG_swapchain | September 2015 | Deprecated |
| VK_LAYER_LUNARG_device_limits | September 2015 | Deprecated |
| VK_LAYER_LUNARG_shader_checker | April 2015 | Deprecated |
| VK_LAYER_LUNARG_image | June 2015 | Deprecated |
Activating Layers on Windows
Before or during execution of a Vulkan application, the loader must be informed of the layers to activate. This can be done in two ways: programmatically, or by using environment variables.
Applications may programmatically activate layers via the vkCreateInstance() entry point.
Layers may also be activated by using the VK_INSTANCE_LAYERS environment variable. The variable should include a semi-colon separated list of layer names to activate. Note that order is relevant, with the initial layer being the closest to the application, and the final layer being closest to the driver.
The list of layers to activate can be specified by executing the following in a Command Window:
C:\> set VK_INSTANCE_LAYERS=VK_LAYER_LUNARG_api_dump;VK_LAYER_KHRONOS_validation
In this example, the api_dump layer will be called before the Khronos validation layer.
VK_INSTANCE_LAYERS may also be set in the system environment variables.
To activate layers located in a particular SDK installation, or layers built locally from source, specify the layer JSON manifest file directory using the VK_LAYER_PATH environment variable. For example, if a Vulkan SDK is installed in C:\VulkanSDK\1.1.121, execute the following in a Command Window:
C:\> set VK_LAYER_PATH=C:\VulkanSDK\1.1.121\Bin C:\> set VK_INSTANCE_LAYERS=VK_LAYER_LUNARG_api_dump;VK_LAYER_KHRONOS_validation C:\> vkcube
Activating Layers on Linux and macOS
Before or during execution of a Vulkan application, the loader must be informed of the layers to activate. This can be done in two ways: programmatically, or by using environment variables.
Applications may programmatically activate layers via the vkCreateInstance() entry point.
Layers may also be activated by using the VK_INSTANCE_LAYERS environment variable. The variable should include a colon-separated list of layer names to activate. Note that order is relevant, with the initial layer being the closest to the application, and the final layer being 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_KHRONOS_validation
To activate layers in a particular SDK installation, or layers built locally from source, identify certain library paths and the layer JSON manifest file directory in addition to the layers to activate.
For Linux, if the Vulkan SDK was locally installed to /sdks, VULKAN_SDK=/sdks/VulkanSDK/1.1.121/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_KHRONOS_validation $ ./vkcube
For macOS, if the Vulkan SDK was locally installed to /sdks, VULKAN_SDK=/sdks/VulkanSDK/1.1.121/macOS:
$ export VK_LAYER_PATH=$VULKAN_SDK/etc/vulkan/explicit_layers.d $ export DYLD_LIBRARY_PATH=$VULKAN_SDK/lib $ export VK_INSTANCE_LAYERS=VK_LAYER_LUNARG_api_dump:VK_LAYER_KHRONOS_validation $ cd $VULKAN_SDK/../Applications/ $ open vkcube.app
Layer Settings File
In addition to activating the layers, available layer options can be set via the vk_layer_settings.txt settings file. By default, the settings file must be named vk_layer_settings.txt and reside in the working directory of the targeted 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 control layer reporting output, a layer settings file must be provided that identifies specific reporting levels for the layers enabled via the VK_INSTANCE_LAYERS 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>
| 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 | Reserved | |
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 |
LayerName.enables | comma separated list of VkValidationFeatureEnableEXT enum values as defined in the Vulkan Specification | Enables the specified validation features |
LayerName.disables | comma separated list of VkValidationFeatureDisableEXT enum values as defined in the Vulkan Specification | Disables the specified validation features |
Sample layer settings file contents:
khronos_validation.report_flags = info,error khronos_validation.debug_action = VK_DBG_LAYER_ACTION_LOG_MSG khronos_validation.disable = VK_VALIDATION_FEATURE_DISABLE_UNIQUE_HANDLES_EXT # VK_LAYER_LUNARG_api_dump custom settings lunarg_api_dump.no_addr = TRUE lunarg_api_dump.file = FALSE
In the Vulkan-ValidationLayers repository, a sample layer settings file can be found in the ‘layers’ directory, here. In the Vulkan SDK, this Linux version of this file is located in config/vk_layer_settings.txt of your local Vulkan SDK install. On Windows, you can find a sample layer settings file in Config\vk_layer_settings.txt of your local Vulkan SDK install. Consult these sample layer settings files for additional information and detail related to available options and settings.
Note: If layers are activated via VK_INSTANCE_LAYERS 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).
Advanced Layer Configuration, Installation, and Discovery Details
The Vulkan loader searches specific platform-specific locations to find installed layers. For additional details, see the LoaderAndLayerInterface.md available here, or in the Vulkan-Loader repository, here.
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 the VK_LAYER_PATH environment variable for layer manifest files.
Applications can query available layers via the vkEnumerateInstanceLayerProperties() command.