Lines Matching +full:vulkan +full:- +full:layers
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,
72 drivers and layers, the information contained in it could be useful to anyone
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
89 optional [layers](#layers) that provide special functionality.
90 The loader is critical to managing the proper dispatching of Vulkan
91 functions to the appropriate set of layers and drivers.
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
110 ### Layers
112 Layers are optional components that augment the Vulkan development environment.
113 They can intercept, evaluate, and modify existing Vulkan functions on their
115 Layers are implemented as libraries that can be enabled in different ways
117 Each layer can choose to hook, or intercept, Vulkan functions which in
122 Because of this, a layer can choose whether to intercept all known Vulkan
125 Some examples of features that layers may expose include:
132 Because layers are optional and dynamically loaded, they can be enabled
135 certain layers can assist in making sure it properly uses the Vulkan API.
136 But when releasing the application, those layers are unnecessary
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
171 layers.
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
216 that were enabled inside of VkConfig as well as disables those layers that
217 were intentionally disabled (including implicit layers).
219 The Vulkan Layer Settings file can be used to specify certain behaviors and
223 For details on what settings can be used, refer to the individual layers.
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
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
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
305 A few of the Vulkan constructs associated directly with a device include:
312 A "device function" is any Vulkan function which takes any device object as its
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
329 Vulkan device functions.
335 [Best Application Performance Setup](LoaderApplicationInterface.md#best-application-performance-set…
342 As with instance extensions, a device extension is a set of Vulkan device
343 functions extending the Vulkan language.
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`
364 At that time the application and the system can each specify optional layers to
366 The loader will initialize the specified layers to create a call chain for each
367 Vulkan function and each entry of the dispatch table will point to the first
372 When an application calls a Vulkan function, this typically will first hit a
378 layers to marshall the appropriate information to all available drivers.
398 This implies that the loader has to be aware of any instance-level extensions
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
454 The Layer interface to the Vulkan loader is detailed in the
463 The Driver interface to the Vulkan loader is detailed in the
483 Loader policies with regards to the loader interaction with drivers and layers
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)
509 drivers or layers.
510 The appropriate string for layers is the layer name provided in the layer's
512 Since drivers don’t have a name like layers, this substring is used to compare
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
533 - Because of this, it will only match the specific target such as:
539 full name of a driver manifest file or even some commonly used layers
542 ### Case-Insensitive
545 are not case-sensitive.
553 environment variable, only to have it be re-enabled by the *enable*/*select*
555 This is useful if you disable all layers/drivers with the intent of only
556 enabling a smaller subset of specific layers/drivers for issue triaging.
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
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.
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/>
733 loader before returning the set of physical devices to layers.<br/>
767 A comma-delimited list of globs to search for in known drivers and
770 Since drivers don’t have a name like layers, this glob is used to
778 1.3.234 of the Vulkan headers and later.<br/>
781 in Vulkan applications failing to run properly.
798 A comma-delimited list of globs to search for in known drivers and
801 Since drivers don’t have a name like layers, this glob is used to
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
836 Known layers are those which are found by the loader taking into account
845 1.3.234 of the Vulkan headers and later.
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
866 Known layers are those which are found by the loader taking into account
872 1.3.234 of the Vulkan headers and later.<br/>
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
899 Known layers are those which are found by the loader taking into account
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
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.
989 Force the loader to add the given layers to the list of Enabled layers
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
997 It also overrides any layers disabled with
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
1052 calls enabled layers, and the final layer calls into the driver specific
1055 <a href="#dispatch-tables-and-call-chains">Dispatch Tables and Call
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>
1075 the internal list of Vulkan objects available.<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
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>
1176 <td>Layers are optional components that augment the Vulkan system.
1177 They can intercept, evaluate, and modify existing Vulkan functions on
1179 See the <a href="#layers">Layers</a> section for more information.
1184 <td>The <b>Layer Library</b> is the group of all layers the loader is able
1186 These may include both implicit and explicit layers.
1187 These layers are available for use by applications unless disabled in
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
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>
1257 between Layers and Drivers, as well as between interface versions. <br/>
1263 drivers and layers. These functions may be in the Vulkan API but also may be