1<!-- markdownlint-disable MD041 --> 2[![Khronos Vulkan][1]][2] 3 4[1]: https://vulkan.lunarg.com/img/Vulkan_100px_Dec16.png "https://www.khronos.org/vulkan/" 5[2]: https://www.khronos.org/vulkan/ 6 7# Architecture of the Vulkan Loader Interfaces <!-- omit from toc --> 8[![Creative Commons][3]][4] 9 10<!-- Copyright © 2015-2023 LunarG, Inc. --> 11 12[3]: https://i.creativecommons.org/l/by-nd/4.0/88x31.png "Creative Commons License" 13[4]: https://creativecommons.org/licenses/by-nd/4.0/ 14## Table of Contents <!-- omit from toc --> 15 16- [Overview](#overview) 17 - [Who Should Read This Document](#who-should-read-this-document) 18 - [The Loader](#the-loader) 19 - [Goals of the Loader](#goals-of-the-loader) 20 - [Layers](#layers) 21 - [Drivers](#drivers) 22 - [Installable Client Drivers](#installable-client-drivers) 23 - [VkConfig](#vkconfig) 24- [Important Vulkan Concepts](#important-vulkan-concepts) 25 - [Instance Versus Device](#instance-versus-device) 26 - [Instance-Specific](#instance-specific) 27 - [Instance Objects](#instance-objects) 28 - [Instance Functions](#instance-functions) 29 - [Instance Extensions](#instance-extensions) 30 - [Device-Specific](#device-specific) 31 - [Device Objects](#device-objects) 32 - [Device Functions](#device-functions) 33 - [Device Extensions](#device-extensions) 34 - [Dispatch Tables and Call Chains](#dispatch-tables-and-call-chains) 35 - [Instance Call Chain Example](#instance-call-chain-example) 36 - [Device Call Chain Example](#device-call-chain-example) 37- [Elevated Privilege Caveats](#elevated-privilege-caveats) 38- [Application Interface to the Loader](#application-interface-to-the-loader) 39- [Layer Interface with the Loader](#layer-interface-with-the-loader) 40- [Driver Interface With the Loader](#driver-interface-with-the-loader) 41- [Debugging Issues](#debugging-issues) 42- [Loader Policies](#loader-policies) 43- [Filter Environment Variable Behaviors](#filter-environment-variable-behaviors) 44 - [Comparison Strings](#comparison-strings) 45 - [Comma-Delimited Lists](#comma-delimited-lists) 46 - [Globs](#globs) 47 - [Case-Insensitive](#case-insensitive) 48 - [Environment Variable Priority](#environment-variable-priority) 49- [Table of Debug Environment Variables](#table-of-debug-environment-variables) 50 - [Active Environment Variables](#active-environment-variables) 51 - [Deprecated Environment Variables](#deprecated-environment-variables) 52- [Glossary of Terms](#glossary-of-terms) 53 54## Overview 55 56Vulkan is a layered architecture, made up of the following elements: 57 * The Vulkan Application 58 * [The Vulkan Loader](#the-loader) 59 * [Vulkan Layers](#layers) 60 * [Drivers](#drivers) 61 * [VkConfig](#vkconfig) 62 63 64 65The general concepts in this document are applicable to the loaders available 66for Windows, Linux, Android, and macOS systems. 67 68 69### Who Should Read This Document 70 71While this document is primarily targeted at developers of Vulkan applications, 72drivers and layers, the information contained in it could be useful to anyone 73wanting a better understanding of the Vulkan runtime. 74 75 76### The Loader 77 78The application sits at the top and interfaces directly with the Vulkan 79loader. 80At the bottom of the stack sits the drivers. 81A driver can control one or more physical devices capable of rendering Vulkan, 82implement a conversion from Vulkan into a native graphics API (like 83[MoltenVk](https://github.com/KhronosGroup/MoltenVK), or implement a fully 84software path that can be executed on a CPU to simulate a Vulkan device (like 85[SwiftShader](https://github.com/google/swiftshader) or LavaPipe). 86Remember, Vulkan-capable hardware may be graphics-based, compute-based, or 87both. 88Between the application and the drivers, the loader can inject any number of 89optional [layers](#layers) that provide special functionality. 90The loader is critical to managing the proper dispatching of Vulkan 91functions to the appropriate set of layers and drivers. 92The Vulkan object model allows the loader to insert layers into a call-chain 93so that the layers can process Vulkan functions prior to the driver being 94called. 95 96This document is intended to provide an overview of the necessary interfaces 97between each of these. 98 99 100#### Goals of the Loader 101 102The loader was designed with the following goals in mind: 103 1. Support one or more Vulkan-capable drivers on a user's system without them 104 interfering with one another. 105 2. Support Vulkan Layers which are optional modules that can be enabled by an 106application, developer, or standard system settings. 107 3. Keep the overall overhead of the loader to the minimum possible. 108 109 110### Layers 111 112Layers are optional components that augment the Vulkan development environment. 113They can intercept, evaluate, and modify existing Vulkan functions on their 114way from the application down to the drivers and back up. 115Layers are implemented as libraries that can be enabled in different ways 116and are loaded during CreateInstance. 117Each layer can choose to hook, or intercept, Vulkan functions which in 118turn can be ignored, inspected, or augmented. 119Any function a layer does not hook is simply skipped for that layer and the 120control flow will simply continue on to the next supporting layer or 121driver. 122Because of this, a layer can choose whether to intercept all known Vulkan 123functions or only a subset it is interested in. 124 125Some examples of features that layers may expose include: 126 * Validating API usage 127 * Tracing API calls 128 * Debugging aids 129 * Profiling 130 * Overlay 131 132Because layers are optional and dynamically loaded, they can be enabled 133and disabled as desired. 134For example, while developing and debugging an application, enabling 135certain layers can assist in making sure it properly uses the Vulkan API. 136But when releasing the application, those layers are unnecessary 137and thus won't be enabled, increasing the speed of the application. 138 139 140### Drivers 141 142The library that implements Vulkan, either through supporting a physical 143hardware device directly, converting Vulkan commands into native graphics 144commands, or simulating Vulkan through software, is considered "a driver". 145The most common type of driver is still the Installable Client Driver (or ICD). 146The loader is responsible for discovering available Vulkan drivers on the 147system. 148Given a list of available drivers, the loader can enumerate all the available 149physical devices and provide this information for an application. 150 151 152#### Installable Client Drivers 153 154Vulkan allows multiple ICDs each supporting one or more devices. 155Each of these devices is represented by a Vulkan `VkPhysicalDevice` object. 156The loader is responsible for discovering available Vulkan ICDs via the standard 157driver search on the system. 158 159 160### VkConfig 161 162VkConfig is a tool LunarG has developed to assist with modifying the Vulkan 163environment on the local system. 164It can be used to find layers, enable them, change layer settings, and other 165useful features. 166VkConfig can be found by either installing the 167[Vulkan SDK](https://vulkan.lunarg.com/) or by building the source out of the 168[LunarG VulkanTools GitHub Repo](https://github.com/LunarG/VulkanTools). 169 170VkConfig generates three outputs, two of which work with the Vulkan loader and 171layers. 172These outputs are: 173 * The Vulkan Override Layer 174 * The Vulkan Layer Settings File 175 * VkConfig Configuration Settings 176 177These files are found in different locations based on your platform: 178 179<table style="width:100%"> 180 <tr> 181 <th>Platform</th> 182 <th>Output</th> 183 <th>Location</th> 184 </tr> 185 <tr> 186 <th rowspan="3">Linux</th> 187 <td>Vulkan Override Layer</td> 188 <td>$USER/.local/share/vulkan/implicit_layer.d/VkLayer_override.json</td> 189 </tr> 190 <tr> 191 <td>Vulkan Layer Settings</td> 192 <td>$USER/.local/share/vulkan/settings.d/vk_layer_settings.txt</td> 193 </tr> 194 <tr> 195 <td>VkConfig Configuration Settings</td> 196 <td>$USER/.local/share/vulkan/settings.d/vk_layer_settings.txt</td> 197 </tr> 198 <tr> 199 <th rowspan="3">Windows</th> 200 <td>Vulkan Override Layer</td> 201 <td>%HOME%\AppData\Local\LunarG\vkconfig\override\VkLayerOverride.json</td> 202 </tr> 203 <tr> 204 <td>Vulkan Layer Settings</td> 205 <td>(registry) HKEY_CURRENT_USER\Software\Khronos\Vulkan\Settings</td> 206 </tr> 207 <tr> 208 <td>VkConfig Configuration Settings</td> 209 <td>(registry) HKEY_CURRENT_USER\Software\LunarG\vkconfig </td> 210 </tr> 211</table> 212 213The [Override Meta-Layer](./LoaderLayerInterface.md#override-meta-layer) is 214an important part of how VkConfig works. 215This layer, when found by the loader, forces the loading of the desired layers 216that were enabled inside of VkConfig as well as disables those layers that 217were intentionally disabled (including implicit layers). 218 219The Vulkan Layer Settings file can be used to specify certain behaviors and 220actions each enabled layer is expected to perform. 221These settings can also be controlled by VkConfig, or they can be manually 222enabled. 223For details on what settings can be used, refer to the individual layers. 224 225In the future, VkConfig may have additional interactions with the Vulkan 226loader. 227 228More details on VkConfig can be found in its 229[GitHub documentation](https://github.com/LunarG/VulkanTools/blob/main/vkconfig/README.md). 230<br/> 231<br/> 232 233 234## Important Vulkan Concepts 235 236Vulkan has a few concepts that provide a fundamental basis for its organization. 237These concepts should be understood by any one attempting to use Vulkan or 238develop any of its components. 239 240 241### Instance Versus Device 242 243An important concept to understand, which is brought up repeatedly throughout this 244document, is how the Vulkan API is organized. 245Many objects, functions, extensions, and other behavior in Vulkan can be 246separated into two groups: 247 * [Instance-specific](#instance-specific) 248 * [Device-specific](#device-specific) 249 250 251#### Instance-Specific 252 253A "Vulkan instance" (`VkInstance`) is a high-level construct used to provide 254Vulkan system-level information and functionality. 255 256##### Instance Objects 257 258A few Vulkan objects associated directly with an instance are: 259 * `VkInstance` 260 * `VkPhysicalDevice` 261 * `VkPhysicalDeviceGroup` 262 263##### Instance Functions 264 265An "instance function" is any Vulkan function where the first parameter is an 266[instance object](#instance-objects) or no object at all. 267 268Some Vulkan instance functions are: 269 * `vkEnumerateInstanceExtensionProperties` 270 * `vkEnumeratePhysicalDevices` 271 * `vkCreateInstance` 272 * `vkDestroyInstance` 273 274An application can link directly to all core instance functions through the 275Vulkan loader's headers. 276Alternatively, an application can query function pointers using 277`vkGetInstanceProcAddr`. 278`vkGetInstanceProcAddr` can be used to query any instance or device entry-points 279in addition to all core entry-points. 280 281If `vkGetInstanceProcAddr` is called using a `VkInstance`, then any function 282pointer returned is specific to that `VkInstance` and any additional objects 283that are created from it. 284 285##### Instance Extensions 286 287Extensions to Vulkan are similarly associated based on what type of 288functions they provide. 289Because of this, extensions are broken up into instance or device extensions 290where most, if not all of the functions, in the extension are of the 291corresponding type. 292For example, an "instance extension" is composed primarily of "instance 293functions" which primarily take instance objects. 294These will be discussed in more detail later. 295 296 297#### Device-Specific 298 299A Vulkan device (`VkDevice`), on the other-hand, is a logical identifier used 300to associate functions with a particular Vulkan physical device 301(`VkPhysicalDevice`) through a particular driver on a user's system. 302 303##### Device Objects 304 305A few of the Vulkan constructs associated directly with a device include: 306 * `VkDevice` 307 * `VkQueue` 308 * `VkCommandBuffer` 309 310##### Device Functions 311 312A "device function" is any Vulkan function which takes any device object as its 313first parameter or a child object of the device. 314The vast majority of Vulkan functions are device functions. 315Some Vulkan device functions are: 316 * `vkQueueSubmit` 317 * `vkBeginCommandBuffer` 318 * `vkCreateEvent` 319 320Vulkan devices functions may be queried using either `vkGetInstanceProcAddr` or 321`vkGetDeviceProcAddr`. 322If an application chooses to use `vkGetInstanceProcAddr`, each call will have 323additional function calls built into the call chain, which will reduce 324performance slightly. 325If, instead, the application uses `vkGetDeviceProcAddr`, the call chain will be 326more optimized to the specific device, but the returned function pointers will 327**only** work for the device used when querying them. 328Unlike `vkGetInstanceProcAddr`, `vkGetDeviceProcAddr` can only be used on 329Vulkan device functions. 330 331The best solution is to query instance extension functions using 332`vkGetInstanceProcAddr`, and to query device extension functions using 333`vkGetDeviceProcAddr`. 334See 335[Best Application Performance Setup](LoaderApplicationInterface.md#best-application-performance-setup) 336section in the 337[LoaderApplicationInterface.md](LoaderApplicationInterface.md) document for more 338information on this. 339 340##### Device Extensions 341 342As with instance extensions, a device extension is a set of Vulkan device 343functions extending the Vulkan language. 344More information about device extensions can be found later in this document. 345 346 347### Dispatch Tables and Call Chains 348 349Vulkan uses an object model to control the scope of a particular action or 350operation. 351The object to be acted on is always the first parameter of a Vulkan call and is 352a dispatchable object (see Vulkan specification section 3.3 Object Model). 353Under the covers, the dispatchable object handle is a pointer to a structure, 354which in turn, contains a pointer to a dispatch table maintained by the loader. 355This dispatch table contains pointers to the Vulkan functions appropriate to 356that object. 357 358There are two types of dispatch tables the loader maintains: 359 - Instance Dispatch Table 360 - Created in the loader during the call to `vkCreateInstance` 361 - Device Dispatch Table 362 - Created in the loader during the call to `vkCreateDevice` 363 364At that time the application and the system can each specify optional layers to 365be included. 366The loader will initialize the specified layers to create a call chain for each 367Vulkan function and each entry of the dispatch table will point to the first 368element of that chain. 369Thus, the loader builds an instance call chain for each `VkInstance` that is 370created and a device call chain for each `VkDevice` that is created. 371 372When an application calls a Vulkan function, this typically will first hit a 373*trampoline* function in the loader. 374These *trampoline* functions are small, simple functions that jump to the 375appropriate dispatch table entry for the object they are given. 376Additionally, for functions in the instance call chain, the loader has an 377additional function, called a *terminator*, which is called after all enabled 378layers to marshall the appropriate information to all available drivers. 379 380 381#### Instance Call Chain Example 382 383For example, the diagram below represents what happens in the call chain for 384`vkCreateInstance`. 385After initializing the chain, the loader calls into the first layer's 386`vkCreateInstance`, which will call the next layer's `vkCreateInstance` 387before finally terminating in the loader again where it will call 388every driver's `vkCreateInstance`. 389This allows every enabled layer in the chain to set up what it needs based on 390the `VkInstanceCreateInfo` structure from the application. 391 392 393 394This also highlights some of the complexity the loader must manage when using 395instance call chains. 396As shown here, the loader's *terminator* must aggregate information to and from 397multiple drivers when they are present. 398This implies that the loader has to be aware of any instance-level extensions 399which work on a `VkInstance` to aggregate them correctly. 400 401 402#### Device Call Chain Example 403 404Device call chains are created in `vkCreateDevice` and are generally simpler 405because they deal with only a single device. 406This allows for the specific driver exposing this device to always be the 407*terminator* of the chain. 408 409 410<br/> 411 412 413## Elevated Privilege Caveats 414 415To ensure that the system is safe from exploitation, Vulkan applications which 416are run with elevated privileges are restricted from certain operations, such 417as reading environment variables from unsecure locations or searching for 418files in user controlled paths. 419This is done to ensure that an application running with elevated privileges does 420not run using components that were not installed in the proper approved 421locations. 422 423The loader uses platform-specific mechanisms (such as `secure_getenv` and its 424equivalents) for querying sensitive environment variables to avoid accidentally 425using untrusted results. 426 427These behaviors also result in ignoring certain environment variables, such as: 428 429 * `VK_DRIVER_FILES` / `VK_ICD_FILENAMES` 430 * `VK_ADD_DRIVER_FILES` 431 * `VK_LAYER_PATH` 432 * `VK_ADD_LAYER_PATH` 433 * `XDG_CONFIG_HOME` (Linux/Mac-specific) 434 * `XDG_DATA_HOME` (Linux/Mac-specific) 435 436For more information on the affected search paths, refer to 437[Layer Discovery](LoaderLayerInterface.md#layer-discovery) and 438[Driver Discovery](LoaderDriverInterface.md#driver-discovery). 439<br/> 440<br/> 441 442 443## Application Interface to the Loader 444 445The Application interface to the Vulkan loader is now detailed in the 446[LoaderApplicationInterface.md](LoaderApplicationInterface.md) document found in 447the same directory as this file. 448<br/> 449<br/> 450 451 452## Layer Interface with the Loader 453 454The Layer interface to the Vulkan loader is detailed in the 455[LoaderLayerInterface.md](LoaderLayerInterface.md) document found in the same 456directory as this file. 457<br/> 458<br/> 459 460 461## Driver Interface With the Loader 462 463The Driver interface to the Vulkan loader is detailed in the 464[LoaderDriverInterface.md](LoaderDriverInterface.md) document found in the same 465directory as this file. 466<br/> 467<br/> 468 469 470## Debugging Issues 471 472 473If your application is crashing or behaving weirdly, the loader provides 474several mechanisms for you to debug the issues. 475These are detailed in the [LoaderDebugging.md](LoaderDebugging.md) document 476found in the same directory as this file. 477<br/> 478<br/> 479 480 481## Loader Policies 482 483Loader policies with regards to the loader interaction with drivers and layers 484 are now documented in the appropriate sections. 485The intention of these sections is to clearly define expected behavior of the 486loader with regards to its interactions with those components. 487This could be especially useful in cases where a new or specialized loader may 488be required that conforms to the behavior of the existing loader. 489Because of this, the primary focus of those sections is on expected behaviors 490for all relevant components to create a consistent experience across platforms. 491In the long-run, this could also be used as validation requirements for any 492existing Vulkan loaders. 493 494To review the particular policy sections, please refer to one or both of the 495sections listed below: 496 * [Loader And Driver Policy](LoaderDriverInterface.md#loader-and-driver-policy) 497 * [Loader And Layer Policy](LoaderLayerInterface.md#loader-and-layer-policy) 498<br/> 499<br/> 500 501## Filter Environment Variable Behaviors 502 503The filter environment variables provided in certain areas have some common 504restrictions and behaviors that should be listed. 505 506### Comparison Strings 507 508The filter variables will be compared against the appropriate strings for either 509drivers or layers. 510The appropriate string for layers is the layer name provided in the layer's 511manifest file. 512Since drivers don’t have a name like layers, this substring is used to compare 513against the driver manifest's filename. 514 515### Comma-Delimited Lists 516 517All of the filter environment variables accept comma-delimited input. 518Therefore, you can chain multiple strings together and it will use the strings 519to individually enable or disable the appropriate item in the current list of 520available items. 521 522### Globs 523 524To provide enough flexibility to limit name searches to only those wanted by the 525developer, the loader uses a limited glob format for strings. 526Acceptable globs are: 527 - Prefixes: `"string*"` 528 - Suffixes: `"*string"` 529 - Substrings: `"*string*"` 530 - Whole strings: `"string"` 531 - In the case of whole strings, the string will be compared against each 532 layer or driver file name in its entirety. 533 - Because of this, it will only match the specific target such as: 534 `VK_LAYER_KHRONOS_validation` will match the layer name 535 `VK_LAYER_KHRONOS_validation`, but **not** a layer named 536 `VK_LAYER_KHRONOS_validation2` (not that there is such a layer). 537 538This is especially useful because it is difficult sometimes to determine the 539full name of a driver manifest file or even some commonly used layers 540such as `VK_LAYER_KHRONOS_validation`. 541 542### Case-Insensitive 543 544All of the filter environment variables assume the strings inside of the glob 545are not case-sensitive. 546Therefore, “Bob”, “bob”, and “BOB” all amount to the same thing. 547 548### Environment Variable Priority 549 550The values from the *disable* environment variable will be considered 551**before** the *enable* or *select* environment variable. 552Because of this, it is possible to disable a layer/driver using the *disable* 553environment variable, only to have it be re-enabled by the *enable*/*select* 554environment variable. 555This is useful if you disable all layers/drivers with the intent of only 556enabling a smaller subset of specific layers/drivers for issue triaging. 557 558## Table of Debug Environment Variables 559 560The following are all the Debug Environment Variables available for use with the 561Loader. 562These are referenced throughout the text, but collected here for ease of 563discovery. 564 565### Active Environment Variables 566 567<table style="width:100%"> 568 <tr> 569 <th>Environment Variable</th> 570 <th>Behavior</th> 571 <th>Restrictions</th> 572 <th>Example Format</th> 573 </tr> 574 <tr> 575 <td><small> 576 <i>VK_ADD_DRIVER_FILES</i> 577 </small></td> 578 <td><small> 579 Provide a list of additional driver JSON files that the loader will use 580 in addition to the drivers that the loader would find normally. 581 The list of drivers will be added first, prior to the list of drivers 582 that would be found normally. 583 The value contains a list of delimited full path listings to 584 driver JSON Manifest files.<br/> 585 </small></td> 586 <td><small> 587 If a global path to the JSON file is not used, issues may be encountered. 588 <br/> <br/> 589 <a href="#elevated-privilege-caveats"> 590 Ignored when running Vulkan application with elevated privileges. 591 </a> 592 </small></td> 593 <td><small> 594 export<br/> 595 VK_ADD_DRIVER_FILES=<br/> 596 <folder_a>/intel.json:<folder_b>/amd.json 597 <br/> <br/> 598 set<br/> 599 VK_ADD_DRIVER_FILES=<br/> 600 <folder_a>\nvidia.json;<folder_b>\mesa.json 601 </small></td> 602 </tr> 603 <tr> 604 <td><small> 605 <i>VK_ADD_LAYER_PATH</i> 606 </small></td> 607 <td><small> 608 Provide a list of additional paths that the loader will use to search 609 for layers in addition to the loader's standard Layer library search 610 folder when looking for explicit layer manifest files. 611 The paths will be added first, prior to the list of folders that would 612 be searched normally. 613 </small></td> 614 <td><small> 615 <a href="#elevated-privilege-caveats"> 616 Ignored when running Vulkan application with elevated privileges. 617 </a> 618 </small></td> 619 <td><small> 620 export<br/> 621 VK_ADD_LAYER_PATH=<br/> 622 <path_a>:<path_b><br/><br/> 623 set<br/> 624 VK_ADD_LAYER_PATH=<br/> 625 <path_a>;<path_b></small> 626 </td> 627 </tr> 628 <tr> 629 <td><small> 630 <i>VK_DRIVER_FILES</i> 631 </small></td> 632 <td><small> 633 Force the loader to use the specific driver JSON files. 634 The value contains a list of delimited full path listings to 635 driver JSON Manifest files and/or 636 paths to folders containing driver JSON files.<br/> 637 <br/> 638 This has replaced the older deprecated environment variable 639 <i>VK_ICD_FILENAMES</i>, however the older environment variable will 640 continue to work. 641 </small></td> 642 <td><small> 643 If a relative path not used, issues may be encountered. 644 <br/> <br/> 645 <a href="#elevated-privilege-caveats"> 646 Ignored when running Vulkan application with elevated privileges. 647 </a> 648 </small></td> 649 <td><small> 650 export<br/> 651 VK_DRIVER_FILES=<br/> 652 <folder_a>/intel.json:<folder_b>/amd.json 653 <br/> <br/> 654 set<br/> 655 VK_DRIVER_FILES=<br/> 656 <folder_a>\nvidia.json;<folder_b>\mesa.json 657 </small> 658 </td> 659 </tr> 660 <tr> 661 <td><small> 662 <i>VK_LAYER_PATH</i></small></td> 663 <td><small> 664 Override the loader's standard Layer library search folders and use the 665 provided delimited file and/or folders to locate explicit layer manifest files. 666 </small></td> 667 <td><small> 668 <a href="#elevated-privilege-caveats"> 669 Ignored when running Vulkan application with elevated privileges. 670 </a> 671 </small></td> 672 <td><small> 673 export<br/> 674 VK_LAYER_PATH=<br/> 675 <path_a>:<path_b><br/><br/> 676 set<br/> 677 VK_LAYER_PATH=<br/> 678 <path_a>;<path_b> 679 </small></td> 680 </tr> 681 <tr> 682 <td><small> 683 <i>VK_LOADER_DEBUG</i> 684 </small></td> 685 <td><small> 686 Enable loader debug messages using a comma-delimited list of level 687 options. These options are:<br/> 688 * error (only errors)<br/> 689 * warn (only warnings)<br/> 690 * info (only info)<br/> 691 * debug (only debug)<br/> 692 * layer (layer-specific output)<br/> 693 * driver (driver-specific output)<br/> 694 * all (report out all messages)<br/><br/> 695 To enable multiple options (outside of "all") like info, warning and 696 error messages, set the value to "error,warn,info". 697 </small></td> 698 <td><small> 699 None 700 </small></td> 701 <td><small> 702 export<br/> 703 VK_LOADER_DEBUG=all<br/> 704 <br/> 705 set<br/> 706 VK_LOADER_DEBUG=warn 707 </small></td> 708 </tr> 709 <tr> 710 <td><small> 711 <i>VK_LOADER_DEVICE_SELECT</i> 712 </small></td> 713 <td><small> 714 Allows the user to force a particular device to be prioritized above all 715 other devices in the return order of <i>vkGetPhysicalDevices<i> and 716 <i>vkGetPhysicalDeviceGroups<i> functions.<br/> 717 The value should be "<hex vendor id>:<hex device id>".<br/> 718 <b>NOTE:</b> This DOES NOT REMOVE devices from the list on reorders them. 719 </small></td> 720 <td><small> 721 <b>Linux Only</b> 722 </small></td> 723 <td><small> 724 set VK_LOADER_DEVICE_SELECT=0x10de:0x1f91 725 </small></td> 726 </tr> 727 <tr> 728 <td><small> 729 <i>VK_LOADER_DISABLE_SELECT</i> 730 </small></td> 731 <td><small> 732 Allows the user to disable the consistent sorting algorithm run in the 733 loader before returning the set of physical devices to layers.<br/> 734 </small></td> 735 <td><small> 736 <b>Linux Only</b> 737 </small></td> 738 <td><small> 739 set VK_LOADER_DISABLE_SELECT=1 740 </small></td> 741 </tr> 742 <tr> 743 <td><small> 744 <i>VK_LOADER_DISABLE_INST_EXT_FILTER</i> 745 </small></td> 746 <td><small> 747 Disable the filtering out of instance extensions that the loader doesn't 748 know about. 749 This will allow applications to enable instance extensions exposed by 750 drivers but that the loader has no support for.<br/> 751 </small></td> 752 <td><small> 753 <b>Use Wisely!</b> This may cause the loader or application to crash. 754 </small></td> 755 <td><small> 756 export<br/> 757 VK_LOADER_DISABLE_INST_EXT_FILTER=1<br/><br/> 758 set<br/> 759 VK_LOADER_DISABLE_INST_EXT_FILTER=1 760 </small></td> 761 </tr> 762 <tr> 763 <td><small> 764 <i>VK_LOADER_DRIVERS_SELECT</i> 765 </small></td> 766 <td><small> 767 A comma-delimited list of globs to search for in known drivers and 768 used to select only the drivers whose manifest file names match one or 769 more of the provided globs.<br/> 770 Since drivers don’t have a name like layers, this glob is used to 771 compare against the manifest filename. 772 Known driver manifests being those files that are already found by the 773 loader taking into account default search paths and other environment 774 variables (like <i>VK_ICD_FILENAMES</i> or <i>VK_ADD_DRIVER_FILES</i>). 775 </small></td> 776 <td><small> 777 This functionality is only available with Loaders built with version 778 1.3.234 of the Vulkan headers and later.<br/> 779 If no drivers are found with a manifest filename that matches any of the 780 provided globs, then no driver is enabled and it <b>may</b> result 781 in Vulkan applications failing to run properly. 782 </small></td> 783 <td><small> 784 export<br/> 785 VK_LOADER_DRIVERS_SELECT=nvidia*<br/> 786 <br/> 787 set<br/> 788 VK_LOADER_DRIVERS_SELECT=nvidia*<br/><br/> 789 The above would select only the Nvidia driver if it was present on the 790 system and already visible to the loader. 791 </small></td> 792 </tr> 793 <tr> 794 <td><small> 795 <i>VK_LOADER_DRIVERS_DISABLE</i> 796 </small></td> 797 <td><small> 798 A comma-delimited list of globs to search for in known drivers and 799 used to disable only the drivers whose manifest file names match one or 800 more of the provided globs.<br/> 801 Since drivers don’t have a name like layers, this glob is used to 802 compare against the manifest filename. 803 Known driver manifests being those files that are already found by the 804 loader taking into account default search paths and other environment 805 variables (like <i>VK_ICD_FILENAMES</i> or <i>VK_ADD_DRIVER_FILES</i>). 806 </small></td> 807 <td><small> 808 This functionality is only available with Loaders built with version 809 1.3.234 of the Vulkan headers and later.<br/> 810 If all available drivers are disabled using this environment variable, 811 then no drivers will be found by the loader and <b>will</b> result 812 in Vulkan applications failing to run properly.<br/> 813 This is also checked before other driver environment variables (such as 814 <i>VK_LOADER_DRIVERS_SELECT</i>) so that a user may easily disable all 815 drivers and then selectively re-enable individual drivers using the 816 enable environment variable. 817 </small></td> 818 <td><small> 819 export<br/> 820 VK_LOADER_DRIVERS_DISABLE=*amd*,*intel*<br/> 821 <br/> 822 set<br/> 823 VK_LOADER_DRIVERS_DISABLE=*amd*,*intel*<br/><br/> 824 The above would disable both Intel and AMD drivers if both were present 825 on the system and already visible to the loader. 826 </small></td> 827 </tr> 828 <tr> 829 <td><small> 830 <i>VK_LOADER_LAYERS_ENABLE</i> 831 </small></td> 832 <td><small> 833 A comma-delimited list of globs to search for in known layers and 834 used to select only the layers whose layer name matches one or more of 835 the provided globs.<br/> 836 Known layers are those which are found by the loader taking into account 837 default search paths and other environment variables 838 (like <i>VK_LAYER_PATH</i>). 839 <br/> 840 This has replaced the older deprecated environment variable 841 <i>VK_INSTANCE_LAYERS</i> 842 </small></td> 843 <td><small> 844 This functionality is only available with Loaders built with version 845 1.3.234 of the Vulkan headers and later. 846 </small></td> 847 <td><small> 848 export<br/> 849 VK_LOADER_LAYERS_ENABLE=*validation,*recon*<br/> 850 <br/> 851 set<br/> 852 VK_LOADER_LAYERS_ENABLE=*validation,*recon*<br/><br/> 853 The above would enable the Khronos validation layer and the 854 GfxReconstruct layer, if both were present on the system and already 855 visible to the loader. 856 </small></td> 857 </tr> 858 <tr> 859 <td><small> 860 <i>VK_LOADER_LAYERS_DISABLE</i> 861 </small></td> 862 <td><small> 863 A comma-delimited list of globs to search for in known layers and 864 used to disable only the layers whose layer name matches one or more of 865 the provided globs.<br/> 866 Known layers are those which are found by the loader taking into account 867 default search paths and other environment variables 868 (like <i>VK_LAYER_PATH</i>). 869 </small></td> 870 <td><small> 871 This functionality is only available with Loaders built with version 872 1.3.234 of the Vulkan headers and later.<br/> 873 Disabling a layer that an application intentionally enables as an 874 explicit layer <b>may</b> cause the application to not function 875 properly.<br/> 876 This is also checked before other layer environment variables (such as 877 <i>VK_LOADER_LAYERS_ENABLE</i>) so that a user may easily disable all 878 layers and then selectively re-enable individual layers using the 879 enable environment variable. 880 </small></td> 881 <td><small> 882 export<br/> 883 VK_LOADER_LAYERS_DISABLE=*MESA*,~implicit~<br/> 884 <br/> 885 set<br/> 886 VK_LOADER_LAYERS_DISABLE=*MESA*,~implicit~<br/><br/> 887 The above would disable any Mesa layer and all other implicit layers 888 that would normally be enabled on the system. 889 </small></td> 890 </tr> 891 <tr> 892 <td><small> 893 <i>VK_LOADER_LAYERS_ALLOW</i> 894 </small></td> 895 <td><small> 896 A comma-delimited list of globs to search for in known layers and 897 used to prevent layers whose layer name matches one or more of 898 the provided globs from being disabled by <i>VK_LOADER_LAYERS_DISABLE</i>.<br/> 899 Known layers are those which are found by the loader taking into account 900 default search paths and other environment variables 901 (like <i>VK_LAYER_PATH</i>). 902 </small></td> 903 <td><small> 904 This functionality is only available with Loaders built with version 905 1.3.262 of the Vulkan headers and later.<br/> 906 This will not cause layers to be enabled if the normal mechanism to 907 enable them 908 </small></td> 909 <td><small> 910 export<br/> 911 VK_LOADER_LAYERS_ALLOW=*validation*,*recon*<br/> 912 <br/> 913 set<br/> 914 VK_LOADER_LAYERS_ALLOW=*validation*,*recon*<br/><br/> 915 The above would allow any layer whose name is validation or recon to be 916 enabled regardless of the value of <i>VK_LOADER_LAYERS_DISABLE</i>. 917 </small></td> 918 </tr> 919 <tr> 920 <td><small> 921 <i>VK_LOADER_DISABLE_DYNAMIC_LIBRARY_UNLOADING</i> 922 </small></td> 923 <td><small> 924 If set to "1", causes the loader to not unload dynamic libraries during vkDestroyInstance. 925 This option allows leak sanitizers to have full stack traces. 926 </small></td> 927 <td><small> 928 This functionality is only available with Loaders built with version 929 1.3.259 of the Vulkan headers and later.<br/> 930 </small></td> 931 <td><small> 932 export<br/> 933 VK_LOADER_DISABLE_DYNAMIC_LIBRARY_UNLOADING=1<br/> 934 <br/> 935 set<br/> 936 VK_LOADER_DISABLE_DYNAMIC_LIBRARY_UNLOADING=1<br/><br/> 937 </small></td> 938 </tr> 939</table> 940 941<br/> 942 943### Deprecated Environment Variables 944 945These environment variables are still active and supported, however support 946may be removed in a future loader release. 947 948<table style="width:100%"> 949 <tr> 950 <th>Environment Variable</th> 951 <th>Behavior</th> 952 <th>Replaced By</th> 953 <th>Restrictions</th> 954 <th>Example Format</th> 955 </tr> 956 <tr> 957 <td><small><i>VK_ICD_FILENAMES</i></small></td> 958 <td><small> 959 Force the loader to use the specific driver JSON files. 960 The value contains a list of delimited full path listings to 961 driver JSON Manifest files.<br/> 962 <br/> 963 <b>NOTE:</b> If a global path to the JSON file is not used, issues 964 may be encountered.<br/> 965 </small></td> 966 <td><small> 967 This has been replaced by <i>VK_DRIVER_FILES</i>. 968 </small></td> 969 <td><small> 970 <a href="#elevated-privilege-caveats"> 971 Ignored when running Vulkan application with elevated privileges. 972 </a> 973 </small></td> 974 <td><small> 975 export<br/> 976 VK_ICD_FILENAMES=<br/> 977 <folder_a>/intel.json:<folder_b>/amd.json 978 <br/><br/> 979 set<br/> 980 VK_ICD_FILENAMES=<br/> 981 <folder_a>\nvidia.json;<folder_b>\mesa.json 982 </small></td> 983 </tr> 984 <tr> 985 <td><small> 986 <i>VK_INSTANCE_LAYERS</i> 987 </small></td> 988 <td><small> 989 Force the loader to add the given layers to the list of Enabled layers 990 normally passed into <b>vkCreateInstance</b>. 991 These layers are added first, and the loader will remove any duplicate 992 layers that appear in both this list as well as that passed into 993 <i>ppEnabledLayerNames</i>. 994 </small></td> 995 <td><small> 996 This has been deprecated by <i>VK_LOADER_LAYERS_ENABLE</i>. 997 It also overrides any layers disabled with 998 <i>VK_LOADER_LAYERS_DISABLE</i>. 999 </small></td> 1000 <td><small> 1001 None 1002 </small></td> 1003 <td><small> 1004 export<br/> 1005 VK_INSTANCE_LAYERS=<br/> 1006 <layer_a>;<layer_b><br/><br/> 1007 set<br/> 1008 VK_INSTANCE_LAYERS=<br/> 1009 <layer_a>;<layer_b> 1010 </small></td> 1011 </tr> 1012</table> 1013<br/> 1014<br/> 1015 1016## Glossary of Terms 1017 1018<table style="width:100%"> 1019 <tr> 1020 <th>Field Name</th> 1021 <th>Field Value</th> 1022 </tr> 1023 <tr> 1024 <td>Android Loader</td> 1025 <td>The loader designed to work primarily for the Android OS. 1026 This is generated from a different code base than the Khronos loader. 1027 But, in all important aspects, it should be functionally equivalent. 1028 </td> 1029 </tr> 1030 <tr> 1031 <td>Khronos Loader</td> 1032 <td>The loader released by Khronos and currently designed to work primarily 1033 on Windows, Linux, macOS, Stadia, and Fuchsia. 1034 This is generated from a different 1035 <a href="https://github.com/KhronosGroup/Vulkan-Loader">code base</a> 1036 than the Android loader. 1037 But in all important aspects, it should be functionally equivalent. 1038 </td> 1039 </tr> 1040 <tr> 1041 <td>Core Function</td> 1042 <td>A function that is already part of the Vulkan core specification and not 1043 an extension. <br/> 1044 For example, <b>vkCreateDevice()</b>. 1045 </td> 1046 </tr> 1047 <tr> 1048 <td>Device Call Chain</td> 1049 <td>The call chain of functions followed for device functions. 1050 This call chain for a device function is usually as follows: first the 1051 application calls into a loader trampoline, then the loader trampoline 1052 calls enabled layers, and the final layer calls into the driver specific 1053 to the device. <br/> 1054 See the 1055 <a href="#dispatch-tables-and-call-chains">Dispatch Tables and Call 1056 Chains</a> section for more information. 1057 </td> 1058 </tr> 1059 <tr> 1060 <td>Device Function</td> 1061 <td>A device function is any Vulkan function which takes a <i>VkDevice</i>, 1062 <i>VkQueue</i>, <i>VkCommandBuffer</i>, or any child of these, as its 1063 first parameter. <br/><br/> 1064 Some Vulkan device functions are: <br/> 1065 <b>vkQueueSubmit</b>, <br/> 1066 <b>vkBeginCommandBuffer</b>, <br/> 1067 <b>vkCreateEvent</b>. <br/><br/> 1068 See the <a href="#instance-versus-device">Instance Versus Device</a> 1069 section for more information. 1070 </td> 1071 </tr> 1072 <tr> 1073 <td>Discovery</td> 1074 <td>The process of the loader searching for driver and layer files to set up 1075 the internal list of Vulkan objects available.<br/> 1076 On <i>Windows/Linux/macOS</i>, the discovery process typically focuses 1077 on searching for Manifest files.<br/> 1078 On <i>Android</i>, the process focuses on searching for library files. 1079 </td> 1080 </tr> 1081 <tr> 1082 <td>Dispatch Table</td> 1083 <td>An array of function pointers (including core and possibly extension 1084 functions) used to step to the next entity in a call chain. 1085 The entity could be the loader, a layer or a driver.<br/> 1086 See <a href="#dispatch-tables-and-call-chains">Dispatch Tables and Call 1087 Chains</a> for more information. 1088 </td> 1089 </tr> 1090 <tr> 1091 <td>Driver</td> 1092 <td>The underlying library which provides support for the Vulkan API. 1093 This support can be implemented as either an ICD, API translation 1094 library, or pure software.<br/> 1095 See <a href="#drivers">Drivers</a> section for more information. 1096 </td> 1097 </tr> 1098 <tr> 1099 <td>Extension</td> 1100 <td>A concept of Vulkan used to expand the core Vulkan functionality. 1101 Extensions may be IHV-specific, platform-specific, or more broadly 1102 available. <br/> 1103 Always first query if an extension exists, and enable it during 1104 <b>vkCreateInstance</b> (if it is an instance extension) or during 1105 <b>vkCreateDevice</b> (if it is a device extension) before attempting 1106 to use it. <br/> 1107 Extensions will always have an author prefix or suffix modifier to every 1108 structure, enumeration entry, command entry-point, or define that is 1109 associated with it. 1110 For example, `KHR` is the prefix for Khronos authored extensions and 1111 will also be found on structures, enumeration entries, and commands 1112 associated with those extensions. 1113 </td> 1114 </tr> 1115 <tr> 1116 <td>Extension Function</td> 1117 <td>A function that is defined as part of an extension and not part of the 1118 Vulkan core specification. <br/> 1119 As with the extension the function is defined as part of, it will have a 1120 suffix modifier indicating the author of the extension.<br/> 1121 Some example extension suffixes include:<br/> 1122 <b>KHR</b> - For Khronos authored extensions, <br/> 1123 <b>EXT</b> - For multi-company authored extensions, <br/> 1124 <b>AMD</b> - For AMD authored extensions, <br/> 1125 <b>ARM</b> - For ARM authored extensions, <br/> 1126 <b>NV</b> - For Nvidia authored extensions.<br/> 1127 </td> 1128 </tr> 1129 <tr> 1130 <td>ICD</td> 1131 <td>Acronym for "Installable Client Driver". 1132 These are drivers that are provided by IHVs to interact with the 1133 hardware they provide. <br/> 1134 These are the most common type of Vulkan drivers. <br/> 1135 See <a href="#installable-client-drivers">Installable Client Drivers</a> 1136 section for more information. 1137 </td> 1138 </tr> 1139 <tr> 1140 <td>IHV</td> 1141 <td>Acronym for an "Independent Hardware Vendor". 1142 Typically the company that built the underlying hardware technology 1143 that is being used. <br/> 1144 A typical examples for a Graphics IHV include (but not limited to): 1145 AMD, ARM, Imagination, Intel, Nvidia, Qualcomm 1146 </td> 1147 </tr> 1148 <tr> 1149 <td>Instance Call Chain</td> 1150 <td>The call chain of functions followed for instance functions. 1151 This call chain for an instance function is usually as follows: first 1152 the application calls into a loader trampoline, then the loader 1153 trampoline calls enabled layers, the final layer calls a loader 1154 terminator, and the loader terminator calls all available 1155 drivers. <br/> 1156 See the <a href="#dispatch-tables-and-call-chains">Dispatch Tables and 1157 Call Chains</a> section for more information. 1158 </td> 1159 </tr> 1160 <tr> 1161 <td>Instance Function</td> 1162 <td>An instance function is any Vulkan function which takes as its first 1163 parameter either a <i>VkInstance</i> or a <i>VkPhysicalDevice</i> or 1164 nothing at all. <br/><br/> 1165 Some Vulkan instance functions are:<br/> 1166 <b>vkEnumerateInstanceExtensionProperties</b>, <br/> 1167 <b>vkEnumeratePhysicalDevices</b>, <br/> 1168 <b>vkCreateInstance</b>, <br/> 1169 <b>vkDestroyInstance</b>. <br/><br/> 1170 See the <a href="#instance-versus-device">Instance Versus Device</a> 1171 section for more information. 1172 </td> 1173 </tr> 1174 <tr> 1175 <td>Layer</td> 1176 <td>Layers are optional components that augment the Vulkan system. 1177 They can intercept, evaluate, and modify existing Vulkan functions on 1178 their way from the application down to the driver.<br/> 1179 See the <a href="#layers">Layers</a> section for more information. 1180 </td> 1181 </tr> 1182 <tr> 1183 <td>Layer Library</td> 1184 <td>The <b>Layer Library</b> is the group of all layers the loader is able 1185 to discover. 1186 These may include both implicit and explicit layers. 1187 These layers are available for use by applications unless disabled in 1188 some way. 1189 For more info, see 1190 <a href="LoaderLayerInterface.md#layer-layer-discovery">Layer Discovery 1191 </a>. 1192 </td> 1193 </tr> 1194 <tr> 1195 <td>Loader</td> 1196 <td>The middleware program which acts as the mediator between Vulkan 1197 applications, Vulkan layers, and Vulkan drivers.<br/> 1198 See <a href="#the-loader">The Loader</a> section for more information. 1199 </td> 1200 </tr> 1201 <tr> 1202 <td>Manifest Files</td> 1203 <td>Data files in JSON format used by the Khronos loader. 1204 These files contain specific information for either a 1205 <a href="LoaderLayerInterface.md#layer-manifest-file-format">Layer</a> 1206 or a 1207 <a href="LoaderDriverInterface.md#driver-manifest-file-format">Driver</a> 1208 and define necessary information such as where to find files and default 1209 settings. 1210 </td> 1211 </tr> 1212 <tr> 1213 <td>Terminator Function</td> 1214 <td>The last function in the instance call chain above the driver and owned 1215 by the loader. 1216 This function is required in the instance call chain because all 1217 instance functionality must be communicated to all drivers capable of 1218 receiving the call. <br/> 1219 See <a href="#dispatch-tables-and-call-chains">Dispatch Tables and Call 1220 Chains</a> for more information. 1221 </td> 1222 </tr> 1223 <tr> 1224 <td>Trampoline Function</td> 1225 <td>The first function in an instance or device call chain owned by the 1226 loader which handles the set up and proper call chain walk using the 1227 appropriate dispatch table. 1228 On device functions (in the device call chain) this function can 1229 actually be skipped.<br/> 1230 See <a href="#dispatch-tables-and-call-chains">Dispatch Tables and Call 1231 Chains</a> for more information. 1232 </td> 1233 </tr> 1234 <tr> 1235 <td>WSI Extension</td> 1236 <td>Acronym for Windowing System Integration. 1237 A Vulkan extension targeting a particular Windowing system and designed 1238 to interface between the Windowing system and Vulkan.<br/> 1239 See 1240 <a href="LoaderApplicationInterface.md#wsi-extensions">WSI Extensions</a> 1241 for more information. 1242 </td> 1243 </tr> 1244 <tr> 1245 <td>Exported Function</td> 1246 <td>A function which is intended to be obtained through the platform specific 1247 dynamic linker, specifically from a Driver or a Layer library. 1248 Functions that are required to be exported are primarily the very first 1249 functions the Loader calls on a Layer or Driver library. <br/> 1250 </td> 1251 </tr> 1252 <tr> 1253 <td>Exposed Function</td> 1254 <td>A function which is intended to be obtained through a Querying Function, such as 1255 `vkGetInstanceProcAddr`. 1256 The exact Querying Function required for a specific exposed function varies 1257 between Layers and Drivers, as well as between interface versions. <br/> 1258 </td> 1259 </tr> 1260 <tr> 1261 <td>Querying Functions</td> 1262 <td>These are functions which allow the Loader to query other functions from 1263 drivers and layers. These functions may be in the Vulkan API but also may be 1264 from the private Loader and Driver Interface or the Loader and Layer Interface. <br/> 1265 These functions are: 1266 `vkGetInstanceProcAddr`, `vkGetDeviceProcAddr`, 1267 `vk_icdGetInstanceProcAddr`, `vk_icdGetPhysicalDeviceProcAddr`, and 1268 `vk_layerGetPhysicalDeviceProcAddr`. 1269 </td> 1270 </tr> 1271</table> 1272
