Document Loader Settings File

Author: charles-lunarg

docs/LoaderSettingsFile.md

@@ -0,0 +1,114 @@
+<!-- markdownlint-disable MD041 -->
+[![Khronos Vulkan][1]][2]
+
+[1]: https://vulkan.lunarg.com/img/Vulkan_100px_Dec16.png "https://www.khronos.org/vulkan/"
+[2]: https://www.khronos.org/vulkan/
+
+# Loader Settings File <!-- omit from toc -->
+
+[![Creative Commons][3]][4]
+
+<!-- Copyright &copy; 2025 LunarG, Inc. -->
+
+[3]: https://i.creativecommons.org/l/by-nd/4.0/88x31.png "Creative Commons License"
+[4]: https://creativecommons.org/licenses/by-nd/4.0/
+
+
+## Table of Contents <!-- omit from toc -->
+
+- [Purpose of the Settings File](#purpose-of-the-settings-file)
+- [Settings File Discovery](#settings-file-discovery)
+  - [Windows](#windows)
+  - [Linux/MacOS/BSD/QNX/Fuchsia/GNU](#linuxmacosbsdqnxfuchsiagnu)
+  - [Other Platforms](#other-platforms)
+  - [Exception for Elevated Privileges](#exception-for-elevated-privileges)
+- [Per-Application Settings File](#per-application-settings-file)
+- [File Format](#file-format)
+- [Example Settings File](#example-settings-file)
+  - [Fields](#fields)
+- [Behavior](#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
+
+
+```json
+{
+   "file_format_version" : "1.0.1",
+   "settings": {
+
+   }
+}
+```
+
+### Fields
+
+<table style="width:100%">
+  <tr>
+    <th>JSON Node</th>
+    <th>Description and Notes</th>
+    <th>Restrictions</th>
+    <th>Parent</th>
+    <th>Introspection Query</th>
+  </tr>
+
+
+
+
+## Behavior