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 8[![Creative Commons][3]][4] 9 10<!-- Copyright © 2015-2021 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 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- [Loader Policies](#loader-policies) 42- [Table of Debug Environment Variables](#table-of-debug-environment-variables) 43- [Glossary of Terms](#glossary-of-terms) 44 45## Overview 46 47Vulkan is a layered architecture, made up of the following elements: 48 * The Vulkan Application 49 * [The Vulkan Loader](#the-loader) 50 * [Vulkan Layers](#layers) 51 * [Drivers](#drivers) 52 * [VkConfig](#vkconfig) 53 54 55 56The general concepts in this document are applicable to the loaders available 57for Windows, Linux, Android, and macOS systems. 58 59 60### Who Should Read This Document 61 62While this document is primarily targeted at developers of Vulkan applications, 63drivers and layers, the information contained in it could be useful to anyone 64wanting a better understanding of the Vulkan runtime. 65 66 67### The Loader 68 69The application sits at the top and interfaces directly with the Vulkan 70loader. 71At the bottom of the stack sits the drivers. 72A driver can control one or more physical devices capable of rendering Vulkan, 73implement a conversion from Vulkan into a native graphics API (like 74[MoltenVk](https://github.com/KhronosGroup/MoltenVK), or implement a fully 75software path that can be executed on a CPU to simulate a Vulkan device (like 76[SwiftShader](https://github.com/google/swiftshader) or LavaPipe). 77Remember, Vulkan-capable hardware may be graphics-based, compute-based, or 78both. 79Between the application and the drivers, the loader can inject any number of 80optional [layers](#layers) that provide special functionality. 81The loader is critical to managing the proper dispatching of Vulkan 82functions to the appropriate set of layers and drivers. 83The Vulkan object model allows the loader to insert layers into a call-chain 84so that the layers can process Vulkan functions prior to the driver being 85called. 86 87This document is intended to provide an overview of the necessary interfaces 88between each of these. 89 90 91#### Goals of the Loader 92 93The loader was designed with the following goals in mind: 94 1. Support one or more Vulkan-capable drivers on a user's system without them 95 interfering with one another. 96 2. Support Vulkan Layers which are optional modules that can be enabled by an 97application, developer, or standard system settings. 98 3. Keep the overall overhead of the loader to the minimum possible. 99 100 101### Layers 102 103Layers are optional components that augment the Vulkan development environment. 104They can intercept, evaluate, and modify existing Vulkan functions on their 105way from the application down to the drivers and back up. 106Layers are implemented as libraries that can be enabled in different ways 107and are loaded during CreateInstance. 108Each layer can choose to hook, or intercept, Vulkan functions which in 109turn can be ignored, inspected, or augmented. 110Any function a layer does not hook is simply skipped for that layer and the 111control flow will simply continue on to the next supporting layer or 112driver. 113Because of this, a layer can choose whether to intercept all known Vulkan 114functions or only a subset it is interested in. 115 116Some examples of features that layers may expose include: 117 * Validating API usage 118 * Tracing API calls 119 * Debugging aids 120 * Profiling 121 * Overlay 122 123Because layers are optional and dynamically loaded, they can be enabled 124and disabled as desired. 125For example, while developing and debugging an application, enabling 126certain layers can assist in making sure it properly uses the Vulkan API. 127But when releasing the application, those layers are unnecessary 128and thus won't be enabled, increasing the speed of the application. 129 130 131### Drivers 132 133The library that implements Vulkan, either through supporting a physical 134hardware device directly, converting Vulkan commands into native graphics 135commands, or simulating Vulkan through software, is considered "a driver". 136The most common type of driver is still the Installable Client Driver (or ICD). 137The loader is responsible for discovering available Vulkan drivers on the 138system. 139Given a list of available drivers, the loader can enumerate all the available 140physical devices and provide this information for an application. 141 142 143#### Installable Client Drivers 144 145Vulkan allows multiple ICDs each supporting one or more devices. 146Each of these devices is represented by a Vulkan `VkPhysicalDevice` object. 147The loader is responsible for discovering available Vulkan ICDs via the standard 148driver search on the system. 149 150 151### VkConfig 152 153VkConfig is a tool LunarG has developed to assist with modifying the Vulkan 154environment on the local system. 155It can be used to find layers, enable them, change layer settings, and other 156useful features. 157VkConfig can be found by either installing the 158[Vulkan SDK](https://vulkan.lunarg.com/) or by building the source out of the 159[LunarG VulkanTools GitHub Repo](https://github.com/LunarG/VulkanTools). 160 161VkConfig generates three outputs, two of which work with the Vulkan loader and 162layers. 163These outputs are: 164 * The Vulkan Override Layer 165 * The Vulkan Layer Settings File 166 * VkConfig Configuration Settings 167 168These files are found in different locations based on your platform: 169 170<table style="width:100%"> 171 <tr> 172 <th>Platform</th> 173 <th>Output</th> 174 <th>Location</th> 175 </tr> 176 <tr> 177 <th rowspan="3">Linux</th> 178 <td>Vulkan Override Layer</td> 179 <td>$USER/.local/share/vulkan/implicit_layer.d/VkLayer_override.json</td> 180 </tr> 181 <tr> 182 <td>Vulkan Layer Settings</td> 183 <td>$USER/.local/share/vulkan/settings.d/vk_layer_settings.txt</td> 184 </tr> 185 <tr> 186 <td>VkConfig Configuration Settings</td> 187 <td>$USER/.local/share/vulkan/settings.d/vk_layer_settings.txt</td> 188 </tr> 189 <tr> 190 <th rowspan="3">Windows</th> 191 <td>Vulkan Override Layer</td> 192 <td>%HOME%\AppData\Local\LunarG\vkconfig\override\VkLayerOverride.json</td> 193 </tr> 194 <tr> 195 <td>Vulkan Layer Settings</td> 196 <td>(registry) HKEY_CURRENT_USER\Software\Khronos\Vulkan\Settings</td> 197 </tr> 198 <tr> 199 <td>VkConfig Configuration Settings</td> 200 <td>(registry) HKEY_CURRENT_USER\Software\LunarG\vkconfig </td> 201 </tr> 202</table> 203 204The [Override Meta-Layer](./LoaderLayerInterface.md#override-meta-layer) is 205an important part of how VkConfig works. 206This layer, when found by the loader, forces the loading of the desired layers 207that were enabled inside of VkConfig as well as disables those layers that 208were intentionally disabled (including implicit layers). 209 210The Vulkan Layer Settings file can be used to specify certain behaviors and 211actions each enabled layer is expected to perform. 212These settings can also be controlled by VkConfig, or they can be manually 213enabled. 214For details on what settings can be used, refer to the individual layers. 215 216In the future, VkConfig may have additional interactions with the Vulkan 217loader. 218 219More details on VkConfig can be found in its 220[GitHub documentation](https://github.com/LunarG/VulkanTools/blob/master/vkconfig/README.md). 221<br/> 222<br/> 223 224 225## Important Vulkan Concepts 226 227Vulkan has a few concepts that provide a fundamental basis for its organization. 228These concepts should be understood by any one attempting to use Vulkan or 229develop any of its components. 230 231 232### Instance Versus Device 233 234An important concept to understand, which is brought up repeatedly throughout this 235document, is how the Vulkan API is organized. 236Many objects, functions, extensions, and other behavior in Vulkan can be 237separated into two groups: 238 * [Instance-specific](#instance-specific) 239 * [Device-specific](#device-specific) 240 241 242#### Instance-Specific 243 244A "Vulkan instance" (`VkInstance`) is a high-level construct used to provide 245Vulkan system-level information and functionality. 246 247##### Instance Objects 248 249A few Vulkan objects associated directly with an instance are: 250 * `VkInstance` 251 * `VkPhysicalDevice` 252 * `VkPhysicalDeviceGroup` 253 254##### Instance Functions 255 256An "instance function" is any Vulkan function where the first parameter is an 257[instance object](#instance-objects) or no object at all. 258 259Some Vulkan instance functions are: 260 * `vkEnumerateInstanceExtensionProperties` 261 * `vkEnumeratePhysicalDevices` 262 * `vkCreateInstance` 263 * `vkDestroyInstance` 264 265An application can link directly to all core instance functions through the 266Vulkan loader's headers. 267Alternatively, an application can query function pointers using 268`vkGetInstanceProcAddr`. 269`vkGetInstanceProcAddr` can be used to query any instance or device entry-points 270in addition to all core entry-points. 271 272If `vkGetInstanceProcAddr` is called using a `VkInstance`, then any function 273pointer returned is specific to that `VkInstance` and any additional objects 274that are created from it. 275 276##### Instance Extensions 277 278Extensions to Vulkan are similarly associated based on what type of 279functions they provide. 280Because of this, extensions are broken up into instance or device extensions 281where most, if not all of the functions, in the extension are of the 282corresponding type. 283For example, an "instance extension" is composed primarily of "instance 284functions" which primarily take instance objects. 285These will be discussed in more detail later. 286 287 288#### Device-Specific 289 290A Vulkan device (`VkDevice`), on the other-hand, is a logical identifier used 291to associate functions with a particular Vulkan physical device 292(`VkPhysicalDevice`) through a particular driver on a user's system. 293 294##### Device Objects 295 296A few of the Vulkan constructs associated directly with a device include: 297 * `VkDevice` 298 * `VkQueue` 299 * `VkCommandBuffer` 300 301##### Device Functions 302 303A "device function" is any Vulkan function which takes any device object as its 304first parameter or a child object of the device. 305The vast majority of Vulkan functions are device functions. 306Some Vulkan device functions are: 307 * `vkQueueSubmit` 308 * `vkBeginCommandBuffer` 309 * `vkCreateEvent` 310 311Vulkan devices functions may be queried using either `vkGetInstanceProcAddr` or 312`vkGetDeviceProcAddr`. 313If an application chooses to use `vkGetInstanceProcAddr`, each call will have 314additional function calls built into the call chain, which will reduce 315performance slightly. 316If, instead, the application uses `vkGetDeviceProcAddr`, the call chain will be 317more optimized to the specific device, but the returned function pointers will 318**only** work for the device used when querying them. 319Unlike `vkGetInstanceProcAddr`, `vkGetDeviceProcAddr` can only be used on 320Vulkan device functions. 321 322The best solution is to query instance extension functions using 323`vkGetInstanceProcAddr`, and to query device extension functions using 324`vkGetDeviceProcAddr`. 325See 326[Best Application Performance Setup](LoaderApplicationInterface.md#best-application-performance-setup) 327section in the 328[LoaderApplicationInterface.md](LoaderApplicationInterface.md) document for more 329information on this. 330 331##### Device Extensions 332 333As with instance extensions, a device extension is a set of Vulkan device 334functions extending the Vulkan language. 335More information about device extensions can be found later in this document. 336 337 338### Dispatch Tables and Call Chains 339 340Vulkan uses an object model to control the scope of a particular action or 341operation. 342The object to be acted on is always the first parameter of a Vulkan call and is 343a dispatchable object (see Vulkan specification section 3.3 Object Model). 344Under the covers, the dispatchable object handle is a pointer to a structure, 345which in turn, contains a pointer to a dispatch table maintained by the loader. 346This dispatch table contains pointers to the Vulkan functions appropriate to 347that object. 348 349There are two types of dispatch tables the loader maintains: 350 - Instance Dispatch Table 351 - Created in the loader during the call to `vkCreateInstance` 352 - Device Dispatch Table 353 - Created in the loader during the call to `vkCreateDevice` 354 355At that time the application and the system can each specify optional layers to 356be included. 357The loader will initialize the specified layers to create a call chain for each 358Vulkan function and each entry of the dispatch table will point to the first 359element of that chain. 360Thus, the loader builds an instance call chain for each `VkInstance` that is 361created and a device call chain for each `VkDevice` that is created. 362 363When an application calls a Vulkan function, this typically will first hit a 364*trampoline* function in the loader. 365These *trampoline* functions are small, simple functions that jump to the 366appropriate dispatch table entry for the object they are given. 367Additionally, for functions in the instance call chain, the loader has an 368additional function, called a *terminator*, which is called after all enabled 369layers to marshall the appropriate information to all available drivers. 370 371 372#### Instance Call Chain Example 373 374For example, the diagram below represents what happens in the call chain for 375`vkCreateInstance`. 376After initializing the chain, the loader calls into the first layer's 377`vkCreateInstance`, which will call the next layer's `vkCreateInstance 378before finally terminating in the loader again where it will call 379every driver's `vkCreateInstance`. 380This allows every enabled layer in the chain to set up what it needs based on 381the `VkInstanceCreateInfo` structure from the application. 382 383 384 385This also highlights some of the complexity the loader must manage when using 386instance call chains. 387As shown here, the loader's *terminator* must aggregate information to and from 388multiple drivers when they are present. 389This implies that the loader has to be aware of any instance-level extensions 390which work on a `VkInstance` to aggregate them correctly. 391 392 393#### Device Call Chain Example 394 395Device call chains are created in `vkCreateDevice` and are generally simpler 396because they deal with only a single device. 397This allows for the specific driver exposing this device to always be the 398*terminator* of the chain. 399 400 401<br/> 402 403 404## Elevated Privilege Caveats 405 406To ensure that the system is safe from exploitation, Vulkan applications which 407are run with elevated privileges are restricted from certain operations, such 408as reading environment variables from unsecure locations or searching for 409files in user controlled paths. 410This is done to ensure that an application running with elevated privileges does 411not run using components that were not installed in the proper approved 412locations. 413 414The loader uses platform-specific mechanisms (such as `secure_getenv` and its 415equivalents) for querying sensitive environment variables to avoid accidentally 416using untrusted results. 417 418These behaviors also result in ignoring certain environment variables, such as: 419 420 * `VK_DRIVER_FILES` / `VK_ICD_FILENAMES` 421 * `VK_ADD_DRIVER_FILES` 422 * `VK_LAYER_PATH` 423 * `VK_ADD_LAYER_PATH` 424 * `XDG_CONFIG_HOME` (Linux/Mac-specific) 425 * `XDG_DATA_HOME` (Linux/Mac-specific) 426 427For more information on the affected search paths, refer to 428[Layer Discovery](LoaderLayerInterface.md#layer-discovery) and 429[Driver Discovery](LoaderDriverInterface.md#driver-discovery). 430<br/> 431<br/> 432 433 434## Application Interface to the Loader 435 436The Application interface to the Vulkan loader is now detailed in the 437[LoaderApplicationInterface.md](LoaderApplicationInterface.md) document found in 438the same directory as this file. 439<br/> 440<br/> 441 442 443## Layer Interface with the Loader 444 445The Layer interface to the Vulkan loader is detailed in the 446[LoaderLayerInterface.md](LoaderLayerInterface.md) document found in the same 447directory as this file. 448<br/> 449<br/> 450 451 452## Driver Interface With the Loader 453 454The Driver interface to the Vulkan loader is detailed in the 455[LoaderDriverInterface.md](LoaderDriverInterface.md) document found in the same 456directory as this file. 457<br/> 458<br/> 459 460 461## Loader Policies 462 463Loader policies with regards to the loader interaction with drivers and layers 464 are now documented in the appropriate sections. 465The intention of these sections is to clearly define expected behavior of the 466loader with regards to its interactions with those components. 467This could be especially useful in cases where a new or specialized loader may 468be required that conforms to the behavior of the existing loader. 469Because of this, the primary focus of those sections is on expected behaviors 470for all relevant components to create a consistent experience across platforms. 471In the long-run, this could also be used as validation requirements for any 472existing Vulkan loaders. 473 474To review the particular policy sections, please refer to one or both of the 475sections listed below: 476 * [Loader And Driver Policy](LoaderDriverInterface.md#loader-and-driver-policy) 477 * [Loader And Layer Policy](LoaderLayerInterface.md#loader-and-layer-policy) 478<br/> 479<br/> 480 481 482## Table of Debug Environment Variables 483 484The following are all the Debug Environment Variables available for use with the 485Loader. 486These are referenced throughout the text, but collected here for ease of 487discovery. 488 489### Active Environment Variables 490 491<table style="width:100%"> 492 <tr> 493 <th>Environment Variable</th> 494 <th>Behavior</th> 495 <th>Restrictions</th> 496 <th>Example Format</th> 497 </tr> 498 <tr> 499 <td><small> 500 <i>VK_ADD_DRIVER_FILES</i> 501 </small></td> 502 <td><small> 503 Provide a list of additional driver JSON files that the loader will use 504 in addition to the drivers that the loader would find normally. 505 The list of drivers will be added first, prior to the list of drivers 506 that would be found normally. 507 The value contains a list of delimited full path listings to 508 driver JSON Manifest files.<br/> 509 </small></td> 510 <td><small> 511 If a global path to the JSON file is not used, issues may be encountered. 512 <br/> <br/> 513 <a href="#elevated-privilege-caveats"> 514 Ignored when running Vulkan application with elevated privileges. 515 </a> 516 </small></td> 517 <td><small> 518 export<br/> 519 VK_ADD_DRIVER_FILES=<br/> 520 <folder_a>/intel.json:<folder_b>/amd.json 521 <br/> <br/> 522 set<br/> 523 VK_ADD_DRIVER_FILES=<br/> 524 <folder_a>\nvidia.json;<folder_b>\mesa.json 525 </small></td> 526 </tr> 527 <tr> 528 <td><small> 529 <i>VK_ADD_LAYER_PATH</i> 530 </small></td> 531 <td><small> 532 Provide a list of additional paths that the loader will use to search 533 for layers in addition to the loader's standard Layer library search 534 folder when looking for explicit layer manifest files. 535 The paths will be added first, prior to the list of folders that would 536 be searched normally. 537 </small></td> 538 <td><small> 539 <a href="#elevated-privilege-caveats"> 540 Ignored when running Vulkan application with elevated privileges. 541 </a> 542 </small></td> 543 <td><small> 544 export<br/> 545 VK_ADD_LAYER_PATH=<br/> 546 <path_a>:<path_b><br/><br/> 547 set<br/> 548 VK_ADD_LAYER_PATH=<br/> 549 <path_a>;<path_b></small> 550 </td> 551 </tr> 552 <tr> 553 <td><small> 554 <i>VK_DRIVER_FILES</i> 555 </small></td> 556 <td><small> 557 Force the loader to use the specific driver JSON files. 558 The value contains a list of delimited full path listings to 559 driver JSON Manifest files.<br/> 560 <br/> 561 This has replaced the older deprecated environment variable 562 <i>VK_ICD_FILENAMES</i>, however the older environment variable will 563 continue to work for some time. 564 </small></td> 565 <td><small> 566 If a global path to the JSON file is not used, issues may be encountered. 567 <br/> <br/> 568 <a href="#elevated-privilege-caveats"> 569 Ignored when running Vulkan application with elevated privileges. 570 </a> 571 </small></td> 572 <td><small> 573 export<br/> 574 VK_DRIVER_FILES=<br/> 575 <folder_a>/intel.json:<folder_b>/amd.json 576 <br/> <br/> 577 set<br/> 578 VK_DRIVER_FILES=<br/> 579 <folder_a>\nvidia.json;<folder_b>\mesa.json 580 </small> 581 </td> 582 </tr> 583 <tr> 584 <td><small> 585 <i>VK_INSTANCE_LAYERS</i> 586 </small></td> 587 <td><small> 588 Force the loader to add the given layers to the list of Enabled layers 589 normally passed into <b>vkCreateInstance</b>. 590 These layers are added first, and the loader will remove any duplicate 591 layers that appear in both this list as well as that passed into 592 <i>ppEnabledLayerNames</i>. 593 </small></td> 594 <td><small> 595 None 596 </small></td> 597 <td><small> 598 export<br/> 599 VK_INSTANCE_LAYERS=<br/> 600 <layer_a>:<layer_b><br/><br/> 601 set<br/> 602 VK_INSTANCE_LAYERS=<br/> 603 <layer_a>;<layer_b> 604 </small></td> 605 </tr> 606 <tr> 607 <td><small> 608 <i>VK_LAYER_PATH</i></small></td> 609 <td><small> 610 Override the loader's standard Layer library search folders and use the 611 provided delimited folders to search for explicit layer manifest files. 612 </small></td> 613 <td><small> 614 <a href="#elevated-privilege-caveats"> 615 Ignored when running Vulkan application with elevated privileges. 616 </a> 617 </small></td> 618 <td><small> 619 export<br/> 620 VK_LAYER_PATH=<br/> 621 <path_a>:<path_b><br/><br/> 622 set<br/> 623 VK_LAYER_PATH=<br/> 624 <path_a>;<path_b> 625 </small></td> 626 </tr> 627 <tr> 628 <td><small> 629 <i>VK_LOADER_DEVICE_SELECT</i> 630 </small></td> 631 <td><small> 632 Allows the user to force a particular device to be prioritized above all 633 other devices in the return order of <i>vkGetPhysicalDevices<i> and 634 <i>vkGetPhysicalDeviceGroups<i> functions.<br/> 635 The value should be "<hex vendor id>:<hex device id>".<br/> 636 <b>NOTE:</b> This DOES NOT REMOVE devices from the list on reorders them. 637 </small></td> 638 <td><small> 639 <b>Linux Only</b> 640 </small></td> 641 <td><small> 642 set VK_LOADER_DEVICE_SELECT=0x10de:0x1f91 643 </small></td> 644 </tr> 645 <tr> 646 <td><small> 647 <i>VK_LOADER_DISABLE_SELECT</i> 648 </small></td> 649 <td><small> 650 Allows the user to disable the consistent sorting algorithm run in the 651 loader before returning the set of physical devices to layers.<br/> 652 </small></td> 653 <td><small> 654 <b>Linux Only</b> 655 </small></td> 656 <td><small> 657 set VK_LOADER_DISABLE_SELECT=1 658 </small></td> 659 </tr> 660 <tr> 661 <td><small> 662 <i>VK_LOADER_DISABLE_INST_EXT_FILTER</i> 663 </small></td> 664 <td><small> 665 Disable the filtering out of instance extensions that the loader doesn't 666 know about. 667 This will allow applications to enable instance extensions exposed by 668 drivers but that the loader has no support for.<br/> 669 </small></td> 670 <td><small> 671 <b>Use Wisely!</b> This may cause the loader or application to crash. 672 </small></td> 673 <td><small> 674 export<br/> 675 VK_LOADER_DISABLE_INST_EXT_FILTER=1<br/><br/> 676 set<br/> 677 VK_LOADER_DISABLE_INST_EXT_FILTER=1 678 </small></td> 679 </tr> 680 <tr> 681 <td><small> 682 <i>VK_LOADER_DEBUG</i> 683 </small></td> 684 <td><small> 685 Enable loader debug messages using a comma-delimited list of level 686 options. These options are:<br/> 687 * error (only errors)<br/> 688 * warn (only warnings)<br/> 689 * info (only info)<br/> 690 * debug (only debug)<br/> 691 * layer (layer-specific output)<br/> 692 * driver (driver-specific output)<br/> 693 * all (report out all messages)<br/><br/> 694 To enable multiple options (outside of "all") like info, warning and 695 error messages, set the value to "error,warn,info". 696 </small></td> 697 <td><small> 698 None 699 </small></td> 700 <td><small> 701 export<br/> 702 VK_LOADER_DEBUG=all<br/> 703 <br/> 704 set<br/> 705 VK_LOADER_DEBUG=warn 706 </small></td> 707 </tr> 708</table> 709 710<br/> 711 712### Deprecated Environment Variables 713 714These environment variables are still active and supported, however support 715may be removed in a future loader release. 716 717<table style="width:100%"> 718 <tr> 719 <th>Environment Variable</th> 720 <th>Behavior</th> 721 <th>Replaced By</th> 722 <th>Restrictions</th> 723 <th>Example Format</th> 724 </tr> 725 <tr> 726 <td><small><i>VK_ICD_FILENAMES</i></small></td> 727 <td><small> 728 Force the loader to use the specific driver JSON files. 729 The value contains a list of delimited full path listings to 730 driver JSON Manifest files.<br/> 731 <br/> 732 <b>NOTE:</b> If a global path to the JSON file is not used, issues 733 may be encountered.<br/> 734 </small></td> 735 <td><small> 736 This has been replaced by <i>VK_DRIVER_FILES</i>. 737 </small></td> 738 <td><small> 739 <a href="#elevated-privilege-caveats"> 740 Ignored when running Vulkan application with elevated privileges. 741 </a> 742 </small></td> 743 <td><small> 744 export<br/> 745 VK_ICD_FILENAMES=<br/> 746 <folder_a>/intel.json:<folder_b>/amd.json 747 <br/><br/> 748 set<br/> 749 VK_ICD_FILENAMES=<br/> 750 <folder_a>\nvidia.json;<folder_b>\mesa.json 751 </small></td> 752 </tr> 753</table> 754<br/> 755<br/> 756 757## Glossary of Terms 758 759<table style="width:100%"> 760 <tr> 761 <th>Field Name</th> 762 <th>Field Value</th> 763 </tr> 764 <tr> 765 <td>Android Loader</td> 766 <td>The loader designed to work primarily for the Android OS. 767 This is generated from a different code base than the Khronos loader. 768 But, in all important aspects, it should be functionally equivalent. 769 </td> 770 </tr> 771 <tr> 772 <td>Khronos Loader</td> 773 <td>The loader released by Khronos and currently designed to work primarily 774 on Windows, Linux, macOS, Stadia, and Fuchsia. 775 This is generated from a different 776 <a href="https://github.com/KhronosGroup/Vulkan-Loader">code base</a> 777 than the Android loader. 778 But in all important aspects, it should be functionally equivalent. 779 </td> 780 </tr> 781 <tr> 782 <td>Core Function</td> 783 <td>A function that is already part of the Vulkan core specification and not 784 an extension. <br/> 785 For example, <b>vkCreateDevice()</b>. 786 </td> 787 </tr> 788 <tr> 789 <td>Device Call Chain</td> 790 <td>The call chain of functions followed for device functions. 791 This call chain for a device function is usually as follows: first the 792 application calls into a loader trampoline, then the loader trampoline 793 calls enabled layers, and the final layer calls into the driver specific 794 to the device. <br/> 795 See the 796 <a href="#dispatch-tables-and-call-chains">Dispatch Tables and Call 797 Chains</a> section for more information. 798 </td> 799 </tr> 800 <tr> 801 <td>Device Function</td> 802 <td>A device function is any Vulkan function which takes a <i>VkDevice</i>, 803 <i>VkQueue</i>, <i>VkCommandBuffer</i>, or any child of these, as its 804 first parameter. <br/><br/> 805 Some Vulkan device functions are: <br/> 806 <b>vkQueueSubmit</b>, <br/> 807 <b>vkBeginCommandBuffer</b>, <br/> 808 <b>vkCreateEvent</b>. <br/><br/> 809 See the <a href="#instance-versus-device">Instance Versus Device</a> 810 section for more information. 811 </td> 812 </tr> 813 <tr> 814 <td>Discovery</td> 815 <td>The process of the loader searching for driver and layer files to set up 816 the internal list of Vulkan objects available.<br/> 817 On <i>Windows/Linux/macOS</i>, the discovery process typically focuses on 818 searching for Manifest files.<br/> 819 On <i>Android</i>, the process focuses on searching for library files. 820 </td> 821 </tr> 822 <tr> 823 <td>Dispatch Table</td> 824 <td>An array of function pointers (including core and possibly extension 825 functions) used to step to the next entity in a call chain. 826 The entity could be the loader, a layer or a driver.<br/> 827 See <a href="#dispatch-tables-and-call-chains">Dispatch Tables and Call 828 Chains</a> for more information. 829 </td> 830 </tr> 831 <tr> 832 <td>Driver</td> 833 <td>The underlying library which provides support for the Vulkan API. 834 This support can be implemented as either an ICD, API translation 835 library, or pure software.<br/> 836 See <a href="#drivers">Drivers</a> section for more information. 837 </td> 838 </tr> 839 <tr> 840 <td>Extension</td> 841 <td>A concept of Vulkan used to expand the core Vulkan functionality. 842 Extensions may be IHV-specific, platform-specific, or more broadly 843 available. <br/> 844 Always first query if an extension exists, and enable it during 845 <b>vkCreateInstance</b> (if it is an instance extension) or during 846 <b>vkCreateDevice</b> (if it is a device extension) before attempting 847 to use it. <br/> 848 Extensions will always have an author prefix or suffix modifier to every 849 structure, enumeration entry, command entry-point, or define that is 850 associated with it. 851 For example, `KHR` is the prefix for Khronos authored extensions and 852 will also be found on structures, enumeration entries, and commands 853 associated with those extensions. 854 </td> 855 </tr> 856 <tr> 857 <td>Extension Function</td> 858 <td>A function that is defined as part of an extension and not part of the 859 Vulkan core specification. <br/> 860 As with the extension the function is defined as part of, it will have a 861 suffix modifier indicating the author of the extension.<br/> 862 Some example extension suffixes include:<br/> 863 <b>KHR</b> - For Khronos authored extensions, <br/> 864 <b>EXT</b> - For multi-company authored extensions, <br/> 865 <b>AMD</b> - For AMD authored extensions, <br/> 866 <b>ARM</b> - For ARM authored extensions, <br/> 867 <b>NV</b> - For Nvidia authored extensions.<br/> 868 </td> 869 </tr> 870 <tr> 871 <td>ICD</td> 872 <td>Acronym for "Installable Client Driver". 873 These are drivers that are provided by IHVs to interact with the 874 hardware they provide. <br/> 875 These are the most common type of Vulkan drivers. <br/> 876 See <a href="#installable-client-drivers">Installable Client Drivers</a> 877 section for more information. 878 </td> 879 </tr> 880 <tr> 881 <td>IHV</td> 882 <td>Acronym for an "Independent Hardware Vendor". 883 Typically the company that built the underlying hardware technology 884 that is being used. <br/> 885 A typical examples for a Graphics IHV include (but not limited to): 886 AMD, ARM, Imagination, Intel, Nvidia, Qualcomm 887 </td> 888 </tr> 889 <tr> 890 <td>Instance Call Chain</td> 891 <td>The call chain of functions followed for instance functions. 892 This call chain for an instance function is usually as follows: first 893 the application calls into a loader trampoline, then the loader 894 trampoline calls enabled layers, the final layer calls a loader 895 terminator, and the loader terminator calls all available 896 drivers. <br/> 897 See the <a href="#dispatch-tables-and-call-chains">Dispatch Tables and 898 Call Chains</a> section for more information. 899 </td> 900 </tr> 901 <tr> 902 <td>Instance Function</td> 903 <td>An instance function is any Vulkan function which takes as its first 904 parameter either a <i>VkInstance</i> or a <i>VkPhysicalDevice</i> or 905 nothing at all. <br/><br/> 906 Some Vulkan instance functions are:<br/> 907 <b>vkEnumerateInstanceExtensionProperties</b>, <br/> 908 <b>vkEnumeratePhysicalDevices</b>, <br/> 909 <b>vkCreateInstance</b>, <br/> 910 <b>vkDestroyInstance</b>. <br/><br/> 911 See the <a href="#instance-versus-device">Instance Versus Device</a> 912 section for more information. 913 </td> 914 </tr> 915 <tr> 916 <td>Layer</td> 917 <td>Layers are optional components that augment the Vulkan system. 918 They can intercept, evaluate, and modify existing Vulkan functions on 919 their way from the application down to the driver.<br/> 920 See the <a href="#layers">Layers</a> section for more information. 921 </td> 922 </tr> 923 <tr> 924 <td>Layer Library</td> 925 <td>The <b>Layer Library</b> is the group of all layers the loader is able 926 to discover. 927 These may include both implicit and explicit layers. 928 These layers are available for use by applications unless disabled in 929 some way. 930 For more info, see 931 <a href="LoaderLayerInterface.md#layer-layer-discovery">Layer Discovery 932 </a>. 933 </td> 934 </tr> 935 <tr> 936 <td>Loader</td> 937 <td>The middleware program which acts as the mediator between Vulkan 938 applications, Vulkan layers, and Vulkan drivers.<br/> 939 See <a href="#the-loader">The Loader</a> section for more information. 940 </td> 941 </tr> 942 <tr> 943 <td>Manifest Files</td> 944 <td>Data files in JSON format used by the Khronos loader. 945 These files contain specific information for either a 946 <a href="LoaderLayerInterface.md#layer-manifest-file-format">Layer</a> 947 or a 948 <a href="LoaderDriverInterface.md#driver-manifest-file-format">Driver</a> 949 and define necessary information such as where to find files and default 950 settings. 951 </td> 952 </tr> 953 <tr> 954 <td>Terminator Function</td> 955 <td>The last function in the instance call chain above the driver and owned 956 by the loader. 957 This function is required in the instance call chain because all 958 instance functionality must be communicated to all drivers capable of 959 receiving the call. <br/> 960 See <a href="#dispatch-tables-and-call-chains">Dispatch Tables and Call 961 Chains</a> for more information. 962 </td> 963 </tr> 964 <tr> 965 <td>Trampoline Function</td> 966 <td>The first function in an instance or device call chain owned by the 967 loader which handles the set up and proper call chain walk using the 968 appropriate dispatch table. 969 On device functions (in the device call chain) this function can 970 actually be skipped.<br/> 971 See <a href="#dispatch-tables-and-call-chains">Dispatch Tables and Call 972 Chains</a> for more information. 973 </td> 974 </tr> 975 <tr> 976 <td>WSI Extension</td> 977 <td>Acronym for Windowing System Integration. 978 A Vulkan extension targeting a particular Windowing system and designed 979 to interface between the Windowing system and Vulkan.<br/> 980 See 981 <a href="LoaderApplicationInterface.md#wsi-extensions">WSI Extensions</a> 982 for more information. 983 </td> 984 </tr> 985</table> 986
