Copyright © 2015-2020 LunarG, Inc.
Vulkan Configurator allows overriding the layers configuration used by Vulkan applications at runtime.
A Vulkan application may configure layers when creating a Vulkan Instance. This layers configuration may be overridden using Vulkan Configurator globally or for a selected list of Vulkan applications.
Finally Vulkan Configurator allows using layers from user-defined directories.
- Change Log and Known Issues
- Bug reports: Please submit GitHub issues if you encounter any issue.
- Information for contributors: All contribution information, FAQ, Roadmap
- Build instruction: It requires Qt 5 to be install and Qt
bindirectory to be added to thePATHenvironment variable. Vulkan Configurator is built as part of the VulkanTools using CMake build system or alternatively withvkconfig.prousing Qt Creator.
| Windows | ✔️ |
|---|---|
 |
 |
| Linux | ✔️ |
|---|---|
 |
 |
| macOS | ✔️ |
|---|---|
 |
 |
Vulkan Configurator is delivered with the Vulkan SDK.
Vulkan Configurator is a graphical user interface (GUI) that may be launched from the console using vkconfig.
The tool is distributed differently, depending on the platform:
- Ubuntu packages: Upon installing the
lunarg-vkconfigpackage, the tools will be available from the command line asvkconfig. - Linux tarball: The vkconfig executable comes pre-built. Run vkconfig on the command line.
- Windows: The tool will be present on the start menu, in the Vulkan SDK menu. User can also invoke from a command line.
- macOS: The tool is provided as an application bundle. Run it by double-clicking the bundle from a Finder window.
Vulkan Configurator may be used with command line arguments to averride layers. Use vkconfig --help in the console for more information.
Vulkan Layer: A layer is an optional library that can intercept Vulkan functions on their way from the Vulkan application down to the Vulkan drivers. Multiple layers can be chained together to use multiple layer functionalities simultaneously.
Vulkan Layers Configuration: A collection of Vulkan Layers executed in a specific order with specific settings for each layer.
Vulkan Explicit Layers vs Implicit Layer: An explicit layer has to be explicitly activated by the user from source in vkCreateInstance, using Vulkan Configurator or VK_INSTANCE_LAYERS environment variable. Implicit layers are enabled by their existence on the system by default.
Vulkan Meta-Layer: Meta-layers are a special kind of layer which is only available through the desktop Vulkan Loader. While usual layers are associated with one particular library, a meta-layer is actually a collection layer which contains an ordered list of other layers called component layers.
Vulkan Override Layer: The Vulkan Override Layer is an implicit meta-layer found on the system with the name VK_LAYER_LUNARG_override. It is the mechanism used by Vulkan Configurator to override Vulkan applications layers. This layer contains:
- The ordered list of layers to activate
- The list of layers to exclude from execution
- The list of paths to executables that the layers override applies to. If this list is empty, the override is applied to every application upon startup.
Vulkan Layer settings: Per-layer settings loaded by each layer library and stored in the vk_layer_settings.txt file. This file is located either next to the Vulkan application executable or set globally and applied to all Vulkan applications thanks to Vulkan Configurator. These settings are described here for VK_LAYER_KHRONOS_validation and here for other layers created by LunarG.
For detailed information, read the Architecture of the Vulkan Loader Interfaces document.
The Vulkan Configurator does not make any system-wide changes to a system, but it does make user-specific changes. These changes are documented below:
Unix systems store files in the following paths:
$HOME/.local/share/vulkan/implicit_layer.d/VkLayer_override.jsontells a Vulkan application which layers to use$HOME/.local/share/vulkan/settings.d/vk_layer_settings.txttells Vulkan layers which settings to use$HOME/.config/LunarG/vkconfig.confstores the application settings forvkconfig
Windows systems store files in the following paths:
%TEMP%\VulkanLayerManager\VkLayerOverride.jsontells a Vulkan application which layers to use%TEMP%\VulkanLayerManager\vk_layer_settings.txttells Vulkan layers which settings to use
In addition, Windows system create registry entries in the following locations:
HKEY_CURRENT_USER\Software\Khronos\Vulkan\ImplicitLayerswill have an entry that points to the JSON file aboveHKEY_CURRENT_USER\Software\Khronos\Vulkan\Settingswill have an entry that points to the text file aboveHKEY_CURRENT_USER\Software\LunarG\vkconfigstores the application settings forvkconfig
On Windows, from the build directory:
ctest -C Debug --output-on-failure --parallel 16
ctest -C Release --output-on-failure --parallel 16
On Linux and macOS, from the build directory:
ctest --output-on-failure --parallel 16
With each release of the Vulkan SDK some manual tests based on use cases are done.
1/ How do I use Vulkan Configurator to override only the Vulkan layers of a selected list of applications?
This is typically done by enabling the "Apply only to the selected list of Vulkan applications" check box.
If this is not working, it's likely that the Vulkan Loader on the system is too old. Version 1.2.141 or newer of the Vulkan Loader is required. Update the Vulkan Loader by installing the latest Vulkan Runtime to enable this feature.
When *Vulkan Configurator is used to override layers, the local vk_layer_settings.txt file is ignored.
The short answer is that environment variables and Vulkan Configurator layers settings are mutually exclusive and the interaction between both is undefined.
This is because the interaction between environment variables and Vulkan Configuration layers settings are handled by the layers directly so the responsability of the layers developers.
We are working on defining layers development conventions to resolve this issue properly but in the meantime we highly recommend to use exclusively either environment variables or Vulkan Configurator.