Loader Settings File

Table of Contents

• Purpose of the Settings File
• Settings File Discovery
  • Windows
  • Linux/MacOS/BSD/QNX/Fuchsia/GNU
  • Other Platforms
  • Exception for Elevated Privileges
• Per-Application Settings File
• File Format
• Example Settings File
  • Fields
• Behavior

Purpose of the Settings File

The purpose of the Loader Settings File is to give developers superb control over the behavior of the Vulkan-Loader. It enables enhanced controls over which layers to load, the order layers in the call chain, logging, and which drivers are available.

The Loader Settings File is intended to be used by "Developer Control Panels" for the Vulkan API, such as the Vulkan Configurator, as a replacement for setting debug envrionment variables.

Settings File Discovery

The Loader Settings File is located by searching in specific file system paths or through platform specific mechanisms such as the Windows Registry.

Windows

The Vulkan Loader first searches the Registry Key HKEY_CURRENT_USER\SOFTWARE\Khronos\Vulkan\LoaderSettings for a DWORD value whose name is a valid path to a file named 'vk_loader_settings.json'. If there are no matching values or the file doesn't exist, the Vulkan Loader performs the same behavior as described above for the Registry Key HKEY_LOCAL_MACHINE\SOFTWARE\Khronos\Vulkan\LoaderSettings.

Linux/MacOS/BSD/QNX/Fuchsia/GNU

The Loader Settings File is located by searching for a file named vk_loader_settings.json in the following locations:

$HOME/.local/share/vulkan/loader_settings.d/ $XDG_DATA_HOME/vulkan/loader_settings.d/ /etc/vulkan/loader_settings.d/

Where $HOME and %XDG_DATA_HOME refer to the values contained in the environment variables of the same name. If a given environment variables is not present, that path is ignored.

Other Platforms

Platforms not listed above currently do not support the Loader Settings File due to not having an appropriate search mechanism.

Exception for Elevated Privileges

Because the Loader Settings File contains paths to Layer and ICD manifests, which contain the paths to various executable binaries, it is necessary to restrict the use of the Loader Settings File when the application is running with elevated privileges.

This is accomplished by not using any Loader Settings Files that are found in non-privileged locations.

On Windows, running with Elevated Privileges will ignore HKEY_CURRENT_USER\SOFTWARE\Khronos\Vulkan\LoaderSettings.

On Linux/MacOS/BSD/QNX/Fuchsia/GNU, running with Elevated Privileges will use a secure method of querying $HOME and$XDG_DATA_HOME to prevent malicious injection of unsecure search directories.

Per-Application Settings File

File Format

The Loader Settings File is a JSON file with a

Example Settings File

{
   "file_format_version" : "1.0.1",
   "settings": {

   }
}

Fields

Behavior

JSON Node	Description and Notes	Restrictions	Parent	Introspection Query