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\LoaderSettings</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
435 * `XDG_CONFIG_HOME` (Linux/Mac-specific)
436 * `XDG_DATA_HOME` (Linux/Mac-specific)
439 [Layer Discovery](LoaderLayerInterface.md#layer-discovery) and
440 [Driver Discovery](LoaderDriverInterface.md#driver-discovery).
447 The Application interface to the Vulkan loader is now detailed in the
456 The Layer interface to the Vulkan loader is detailed in the
465 The Driver interface to the Vulkan loader is detailed in the
485 Loader policies with regards to the loader interaction with drivers and layers
493 In the long-run, this could also be used as validation requirements for any
494 existing Vulkan loaders.
498 * [Loader And Driver Policy](LoaderDriverInterface.md#loader-and-driver-policy)
499 * [Loader And Layer Policy](LoaderLayerInterface.md#loader-and-layer-policy)
511 drivers or layers.
512 The appropriate string for layers is the layer name provided in the layer's
514 Since drivers don’t have a name like layers, this substring is used to compare
517 ### Comma-Delimited Lists
519 All of the filter environment variables accept comma-delimited input.
529 - Prefixes: `"string*"`
530 - Suffixes: `"*string"`
531 - Substrings: `"*string*"`
532 - Whole strings: `"string"`
533 - In the case of whole strings, the string will be compared against each
535 - Because of this, it will only match the specific target such as:
541 full name of a driver manifest file or even some commonly used layers
544 ### Case-Insensitive
547 are not case-sensitive.
555 environment variable, only to have it be re-enabled by the *enable*/*select*
557 This is useful if you disable all layers/drivers with the intent of only
558 enabling a smaller subset of specific layers/drivers for issue triaging.
591 <a href="#elevated-privilege-caveats">
592 Ignored when running Vulkan application with elevated privileges.
611 for explicit layers in addition to the loader's standard layer library
617 <a href="#elevated-privilege-caveats">
618 Ignored when running Vulkan application with elevated privileges.
636 for implicit layers in addition to the loader's standard layer library
642 <a href="#elevated-privilege-caveats">
643 Ignored when running Vulkan application with elevated privileges.
671 1.3.207 of the Vulkan headers and later.<br/>
676 <a href="#elevated-privilege-caveats">
677 Ignored when running Vulkan application with elevated privileges.
699 <a href="#elevated-privilege-caveats">
700 Ignored when running Vulkan application with elevated privileges.
720 <a href="#elevated-privilege-caveats">
721 Ignored when running Vulkan application with elevated privileges.
738 Enable loader debug messages using a comma-delimited list of level
744 * layer (layer-specific output)<br/>
745 * driver (driver-specific output)<br/>
785 loader before returning the set of physical devices to layers.<br/>
819 A comma-delimited list of globs to search for in known drivers and
822 Since drivers don’t have a name like layers, this glob is used to
830 1.3.234 of the Vulkan headers and later.<br/>
833 in Vulkan applications failing to run properly.
850 A comma-delimited list of globs to search for in known drivers and
853 Since drivers don’t have a name like layers, this glob is used to
861 1.3.234 of the Vulkan headers and later.<br/>
864 in Vulkan applications failing to run properly.<br/>
867 drivers and then selectively re-enable individual drivers using the
885 A comma-delimited list of globs to search for in known layers and
886 used to select only the layers whose layer name matches one or more of
888 Known layers are those which are found by the loader taking into account
897 1.3.234 of the Vulkan headers and later.
915 A comma-delimited list of globs to search for in known layers and
916 used to disable only the layers whose layer name matches one or more of
918 Known layers are those which are found by the loader taking into account
924 1.3.234 of the Vulkan headers and later.<br/>
930 layers and then selectively re-enable individual layers using the
939 The above would disable any Mesa layer and all other implicit layers
948 A comma-delimited list of globs to search for in known layers and
949 used to prevent layers whose layer name matches one or more of
951 Known layers are those which are found by the loader taking into account
957 1.3.262 of the Vulkan headers and later.<br/>
958 This will not cause layers to be enabled if the normal mechanism to
981 1.3.259 of the Vulkan headers and later.<br/>
1022 <a href="#elevated-privilege-caveats">
1023 Ignored when running Vulkan application with elevated privileges.
1041 Force the loader to add the given layers to the list of Enabled layers
1043 These layers are added first, and the loader will remove any duplicate
1044 layers that appear in both this list as well as that passed into
1049 It also overrides any layers disabled with
1087 <a href="https://github.com/KhronosGroup/Vulkan-Loader">code base</a>
1094 <td>A function that is already part of the Vulkan core specification and not
1104 calls enabled layers, and the final layer calls into the driver specific
1107 <a href="#dispatch-tables-and-call-chains">Dispatch Tables and Call
1113 <td>A device function is any Vulkan function which takes a <i>VkDevice</i>,
1116 Some Vulkan device functions are: <br/>
1120 See the <a href="#instance-versus-device">Instance Versus Device</a>
1127 the internal list of Vulkan objects available.<br/>
1138 See <a href="#dispatch-tables-and-call-chains">Dispatch Tables and Call
1144 <td>The underlying library which provides support for the Vulkan API.
1152 <td>A concept of Vulkan used to expand the core Vulkan functionality.
1153 Extensions may be IHV-specific, platform-specific, or more broadly
1160 structure, enumeration entry, command entry-point, or define that is
1170 Vulkan core specification. <br/>
1174 <b>KHR</b> - For Khronos authored extensions, <br/>
1175 <b>EXT</b> - For multi-company authored extensions, <br/>
1176 <b>AMD</b> - For AMD authored extensions, <br/>
1177 <b>ARM</b> - For ARM authored extensions, <br/>
1178 <b>NV</b> - For Nvidia authored extensions.<br/>
1186 These are the most common type of Vulkan drivers. <br/>
1187 See <a href="#installable-client-drivers">Installable Client Drivers</a>
1205 trampoline calls enabled layers, the final layer calls a loader
1208 See the <a href="#dispatch-tables-and-call-chains">Dispatch Tables and
1214 <td>An instance function is any Vulkan function which takes as its first
1217 Some Vulkan instance functions are:<br/>
1222 See the <a href="#instance-versus-device">Instance Versus Device</a>
1228 <td>Layers are optional components that augment the Vulkan system.
1229 They can intercept, evaluate, and modify existing Vulkan functions on
1231 See the <a href="#layers">Layers</a> section for more information.
1236 <td>The <b>Layer Library</b> is the group of all layers the loader is able
1238 These may include both implicit and explicit layers.
1239 These layers are available for use by applications unless disabled in
1242 <a href="LoaderLayerInterface.md#layer-layer-discovery">Layer Discovery
1248 <td>The middleware program which acts as the mediator between Vulkan
1249 applications, Vulkan layers, and Vulkan drivers.<br/>
1250 See <a href="#the-loader">The Loader</a> section for more information.
1257 <a href="LoaderLayerInterface.md#layer-manifest-file-format">Layer</a>
1259 <a href="LoaderDriverInterface.md#driver-manifest-file-format">Driver</a>
1271 See <a href="#dispatch-tables-and-call-chains">Dispatch Tables and Call
1282 See <a href="#dispatch-tables-and-call-chains">Dispatch Tables and Call
1289 A Vulkan extension targeting a particular Windowing system and designed
1290 to interface between the Windowing system and Vulkan.<br/>
1292 <a href="LoaderApplicationInterface.md#wsi-extensions">WSI Extensions</a>
1309 between Layers and Drivers, as well as between interface versions. <br/>
1315 drivers and layers. These functions may be in the Vulkan API but also may be