Lines Matching +full:vulkan +full:- +full:device +full:- +full:select +full:- +full:layer
1 <!-- markdownlint-disable MD041 -->
2 [![Khronos Vulkan][1]][2]
4 [1]: https://vulkan.lunarg.com/img/Vulkan_100px_Dec16.png "https://www.khronos.org/vulkan/"
5 [2]: https://www.khronos.org/vulkan/
7 # Architecture of the Vulkan Loader Interfaces <!-- omit from toc -->
10 <!-- Copyright © 2015-2023 LunarG, Inc. -->
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 -->
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)
56 Vulkan is a layered architecture, made up of the following elements:
57 * The Vulkan Application
58 * [The Vulkan Loader](#the-loader)
59 * [Vulkan Layers](#layers)
71 While this document is primarily targeted at developers of Vulkan applications,
73 wanting a better understanding of the Vulkan runtime.
78 The application sits at the top and interfaces directly with the Vulkan
81 A driver can control one or more physical devices capable of rendering Vulkan,
82 implement a conversion from Vulkan into a native graphics API (like
84 software path that can be executed on a CPU to simulate a Vulkan device (like
86 Remember, Vulkan-capable hardware may be graphics-based, compute-based, or
90 The loader is critical to managing the proper dispatching of Vulkan
92 The Vulkan object model allows the loader to insert layers into a call-chain
93 so that the layers can process Vulkan functions prior to the driver being
103 1. Support one or more Vulkan-capable drivers on a user's system without them
105 2. Support Vulkan Layers which are optional modules that can be enabled by an
112 Layers are optional components that augment the Vulkan development environment.
113 They can intercept, evaluate, and modify existing Vulkan functions on their
117 Each layer can choose to hook, or intercept, Vulkan functions which in
119 Any function a layer does not hook is simply skipped for that layer and the
120 control flow will simply continue on to the next supporting layer or
122 Because of this, a layer can choose whether to intercept all known Vulkan
135 certain layers can assist in making sure it properly uses the Vulkan API.
142 The library that implements Vulkan, either through supporting a physical
143 hardware device directly, converting Vulkan commands into native graphics
144 commands, or simulating Vulkan through software, is considered "a driver".
146 The loader is responsible for discovering available Vulkan drivers on the
154 Vulkan allows multiple ICDs each supporting one or more devices.
155 Each of these devices is represented by a Vulkan `VkPhysicalDevice` object.
156 The loader is responsible for discovering available Vulkan ICDs via the standard
162 VkConfig is a tool LunarG has developed to assist with modifying the Vulkan
164 It can be used to find layers, enable them, change layer settings, and other
167 [Vulkan SDK](https://vulkan.lunarg.com/) or by building the source out of the
170 VkConfig generates three outputs, two of which work with the Vulkan loader and
173 * The Vulkan Override Layer
174 * The Vulkan Layer Settings File
187 <td>Vulkan Override Layer</td>
188 <td>$USER/.local/share/vulkan/implicit_layer.d/VkLayer_override.json</td>
191 <td>Vulkan Layer Settings</td>
192 <td>$USER/.local/share/vulkan/settings.d/vk_layer_settings.txt</td>
196 <td>$USER/.local/share/vulkan/settings.d/vk_layer_settings.txt</td>
200 <td>Vulkan Override Layer</td>
204 <td>Vulkan Layer Settings</td>
205 <td>(registry) HKEY_CURRENT_USER\Software\Khronos\Vulkan\Settings</td>
213 The [Override Meta-Layer](./LoaderLayerInterface.md#override-meta-layer) is
215 This layer, when found by the loader, forces the loading of the desired layers
219 The Vulkan Layer Settings file can be used to specify certain behaviors and
220 actions each enabled layer is expected to perform.
225 In the future, VkConfig may have additional interactions with the Vulkan
234 ## Important Vulkan Concepts
236 Vulkan has a few concepts that provide a fundamental basis for its organization.
237 These concepts should be understood by any one attempting to use Vulkan or
241 ### Instance Versus Device
244 document, is how the Vulkan API is organized.
245 Many objects, functions, extensions, and other behavior in Vulkan can be
247 * [Instance-specific](#instance-specific)
248 * [Device-specific](#device-specific)
251 #### Instance-Specific
253 A "Vulkan instance" (`VkInstance`) is a high-level construct used to provide
254 Vulkan system-level information and functionality.
258 A few Vulkan objects associated directly with an instance are:
265 An "instance function" is any Vulkan function where the first parameter is an
266 [instance object](#instance-objects) or no object at all.
268 Some Vulkan instance functions are:
275 Vulkan loader's headers.
278 `vkGetInstanceProcAddr` can be used to query any instance or device entry-points
279 in addition to all core entry-points.
287 Extensions to Vulkan are similarly associated based on what type of
289 Because of this, extensions are broken up into instance or device extensions
297 #### Device-Specific
299 A Vulkan device (`VkDevice`), on the other-hand, is a logical identifier used
300 to associate functions with a particular Vulkan physical device
303 ##### Device Objects
305 A few of the Vulkan constructs associated directly with a device include:
310 ##### Device Functions
312 A "device function" is any Vulkan function which takes any device object as its
313 first parameter or a child object of the device.
314 The vast majority of Vulkan functions are device functions.
315 Some Vulkan device functions are:
320 Vulkan devices functions may be queried using either `vkGetInstanceProcAddr` or
326 more optimized to the specific device, but the returned function pointers will
327 **only** work for the device used when querying them.
329 Vulkan device functions.
332 `vkGetInstanceProcAddr`, and to query device extension functions using
335 [Best Application Performance Setup](LoaderApplicationInterface.md#best-application-performance-set…
340 ##### Device Extensions
342 As with instance extensions, a device extension is a set of Vulkan device
343 functions extending the Vulkan language.
344 More information about device extensions can be found later in this document.
349 Vulkan uses an object model to control the scope of a particular action or
351 The object to be acted on is always the first parameter of a Vulkan call and is
352 a dispatchable object (see Vulkan specification section 3.3 Object Model).
355 This dispatch table contains pointers to the Vulkan functions appropriate to
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`
367 Vulkan function and each entry of the dispatch table will point to the first
370 created and a device call chain for each `VkDevice` that is created.
372 When an application calls a Vulkan function, this typically will first hit a
385 After initializing the chain, the loader calls into the first layer's
386 `vkCreateInstance`, which will call the next layer's `vkCreateInstance`
389 This allows every enabled layer in the chain to set up what it needs based on
398 This implies that the loader has to be aware of any instance-level extensions
402 #### Device Call Chain Example
404 Device call chains are created in `vkCreateDevice` and are generally simpler
405 because they deal with only a single device.
406 This allows for the specific driver exposing this device to always be the
409 
415 To ensure that the system is safe from exploitation, Vulkan applications which
423 The loader uses platform-specific mechanisms (such as `secure_getenv` and its
433 * `XDG_CONFIG_HOME` (Linux/Mac-specific)
434 * `XDG_DATA_HOME` (Linux/Mac-specific)
437 [Layer Discovery](LoaderLayerInterface.md#layer-discovery) and
438 [Driver Discovery](LoaderDriverInterface.md#driver-discovery).
445 The Application interface to the Vulkan loader is now detailed in the
452 ## Layer Interface with the Loader
454 The Layer interface to the Vulkan loader is detailed in the
463 The Driver interface to the Vulkan loader is detailed in the
491 In the long-run, this could also be used as validation requirements for any
492 existing Vulkan loaders.
496 * [Loader And Driver Policy](LoaderDriverInterface.md#loader-and-driver-policy)
497 * [Loader And Layer Policy](LoaderLayerInterface.md#loader-and-layer-policy)
510 The appropriate string for layers is the layer name provided in the layer's
515 ### Comma-Delimited Lists
517 All of the filter environment variables accept comma-delimited input.
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).
542 ### Case-Insensitive
545 are not case-sensitive.
551 **before** the *enable* or *select* environment variable.
552 Because of this, it is possible to disable a layer/driver using the *disable*
553 environment variable, only to have it be re-enabled by the *enable*/*select*
589 <a href="#elevated-privilege-caveats">
590 Ignored when running Vulkan application with elevated privileges.
609 for layers in addition to the loader's standard Layer library search
610 folder when looking for explicit layer manifest files.
615 <a href="#elevated-privilege-caveats">
616 Ignored when running Vulkan application with elevated privileges.
645 <a href="#elevated-privilege-caveats">
646 Ignored when running Vulkan application with elevated privileges.
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.
668 <a href="#elevated-privilege-caveats">
669 Ignored when running Vulkan application with elevated privileges.
686 Enable loader debug messages using a comma-delimited list of level
692 * layer (layer-specific output)<br/>
693 * driver (driver-specific output)<br/>
714 Allows the user to force a particular device to be prioritized above all
717 The value should be "<hex vendor id>:<hex device id>".<br/>
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
778 1.3.234 of the Vulkan headers and later.<br/>
781 in Vulkan applications failing to run properly.
789 The above would select only the Nvidia driver if it was present on the
798 A comma-delimited list of globs to search for in known drivers and
809 1.3.234 of the Vulkan headers and later.<br/>
812 in Vulkan applications failing to run properly.<br/>
815 drivers and then selectively re-enable individual drivers using the
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
845 1.3.234 of the Vulkan headers and later.
853 The above would enable the Khronos validation layer and the
854 GfxReconstruct layer, if both were present on the system and already
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
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
876 This is also checked before other layer environment variables (such as
878 layers and then selectively re-enable individual layers using the
887 The above would disable any Mesa layer and all other implicit layers
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
905 1.3.262 of the Vulkan headers and later.<br/>
915 The above would allow any layer whose name is validation or recon to be
929 1.3.259 of the Vulkan headers and later.<br/>
970 <a href="#elevated-privilege-caveats">
971 Ignored when running Vulkan application with elevated privileges.
1035 <a href="https://github.com/KhronosGroup/Vulkan-Loader">code base</a>
1042 <td>A function that is already part of the Vulkan core specification and not
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
1052 calls enabled layers, and the final layer calls into the driver specific
1053 to the device. <br/>
1055 <a href="#dispatch-tables-and-call-chains">Dispatch Tables and Call
1060 <td>Device Function</td>
1061 <td>A device function is any Vulkan function which takes a <i>VkDevice</i>,
1064 Some Vulkan device functions are: <br/>
1068 See the <a href="#instance-versus-device">Instance Versus Device</a>
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/>
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
1092 <td>The underlying library which provides support for the Vulkan API.
1100 <td>A concept of Vulkan used to expand the core Vulkan functionality.
1101 Extensions may be IHV-specific, platform-specific, or more broadly
1105 <b>vkCreateDevice</b> (if it is a device extension) before attempting
1108 structure, enumeration entry, command entry-point, or define that is
1118 Vulkan core specification. <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/>
1134 These are the most common type of Vulkan drivers. <br/>
1135 See <a href="#installable-client-drivers">Installable Client Drivers</a>
1153 trampoline calls enabled layers, the final layer calls a loader
1156 See the <a href="#dispatch-tables-and-call-chains">Dispatch Tables and
1162 <td>An instance function is any Vulkan function which takes as its first
1165 Some Vulkan instance functions are:<br/>
1170 See the <a href="#instance-versus-device">Instance Versus Device</a>
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
1183 <td>Layer Library</td>
1184 <td>The <b>Layer Library</b> is the group of all layers the loader is able
1190 <a href="LoaderLayerInterface.md#layer-layer-discovery">Layer Discovery
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.
1205 <a href="LoaderLayerInterface.md#layer-manifest-file-format">Layer</a>
1207 <a href="LoaderDriverInterface.md#driver-manifest-file-format">Driver</a>
1219 See <a href="#dispatch-tables-and-call-chains">Dispatch Tables and Call
1225 <td>The first function in an instance or device call chain owned by the
1228 On device functions (in the device call chain) this function can
1230 See <a href="#dispatch-tables-and-call-chains">Dispatch Tables and Call
1237 A Vulkan extension targeting a particular Windowing system and designed
1238 to interface between the Windowing system and Vulkan.<br/>
1240 <a href="LoaderApplicationInterface.md#wsi-extensions">WSI Extensions</a>
1247 dynamic linker, specifically from a Driver or a Layer library.
1249 functions the Loader calls on a Layer or Driver library. <br/>
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/>