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 # Application Interface to Loader <!-- 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/
15 ## Table of Contents <!-- omit from toc -->
17 - [Overview](#overview)
18 - [Interfacing with Vulkan Functions](#interfacing-with-vulkan-functions)
19 - [Vulkan Direct Exports](#vulkan-direct-exports)
20 - [Directly Linking to the Loader](#directly-linking-to-the-loader)
21 - [Dynamic Linking](#dynamic-linking)
22 - [Static Linking](#static-linking)
23 - [Indirectly Linking to the Loader](#indirectly-linking-to-the-loader)
24 - [Best Application Performance Setup](#best-application-performance-setup)
25 - [ABI Versioning](#abi-versioning)
26 - [Windows Dynamic Library Usage](#windows-dynamic-library-usage)
27 - [Linux Dynamic Library Usage](#linux-dynamic-library-usage)
28 - [MacOs Dynamic Library Usage](#macos-dynamic-library-usage)
29 - [Bundling the Loader With An Application](#bundling-the-loader-with-an-application)
30 - [Application Layer Usage](#application-layer-usage)
31 - [Meta-Layers](#meta-layers)
32 - [Implicit vs Explicit Layers](#implicit-vs-explicit-layers)
33 - [Override Layer](#override-layer)
34 - [Forcing Layer Source Folders](#forcing-layer-source-folders)
35 - [Exception for Elevated Privileges](#exception-for-elevated-privileges)
36 …- [Forcing Layers to be Enabled on Windows, Linux and macOS](#forcing-layers-to-be-enabled-on-wind…
37 - [Overall Layer Ordering](#overall-layer-ordering)
38 - [Debugging Possible Layer Issues](#debugging-possible-layer-issues)
39 - [Application Usage of Extensions](#application-usage-of-extensions)
40 - [Instance and Device Extensions](#instance-and-device-extensions)
41 - [WSI Extensions](#wsi-extensions)
42 - [Unknown Extensions](#unknown-extensions)
43 …- [Filtering Out Unknown Instance Extension Names](#filtering-out-unknown-instance-extension-names)
44 - [Physical Device Ordering](#physical-device-ordering)
48 This is the Application-centric view of working with the Vulkan loader.
52 ## Interfacing with Vulkan Functions
54 There are several ways Vulkan functions may be interfaced through the loader:
57 ### Vulkan Direct Exports
60 Vulkan entry-points and all appropriate Window System Interface (WSI)
61 entry-points.
62 This is done to make it simpler to get started with Vulkan development.
64 Vulkan calls are simple *trampoline* functions that jump to the appropriate
93 - The loader can never be updated without re-linking the application
94 - The possibility that two included libraries could contain different versions
96 - Could cause conflicts between the different loader versions
103 they can use the appropriate platform-specific dynamic symbol lookup on the
106 It also provides the fastest mechanism for the application to call Vulkan
112 and `vkEnumerateInstanceLayerProperties` in a platform-independent way.
116 To get the best possible performance in a Vulkan application, the application
117 should set up its own dispatch table for every Vulkan API entry-point.
118 For every instance-level Vulkan command in the dispatch table, the function pointer
120 Additionally, for every device-level Vulkan command, the function pointer
127 Remember, a [Vulkan instance is a high-level construct used to provide Vulkan
128 system-level information](LoaderInterfaceArchitecture.md#instance-specific).
132 three enabled layers:
136 This is also how a Vulkan device function call chain looks if queried
142 layers and the driver.
143 Thus, using a loader-exported Vulkan device function, the call chain
150 This further optimizes the call chain by removing the loader all-together under
155 Also, notice if no layers are enabled, the application function pointers point
157 With many function calls, the lack of indirection in each adds up to non-trivial
169 object into an driver-specific KHR_surface object prior to passing down the rest
180 The Vulkan loader library will be distributed in various ways including Vulkan
184 However, the name and versioning of the Vulkan loader library is specified so
185 an app can link to the correct Vulkan ABI library version.
194 The Vulkan loader library file name is `vulkan-<ABI version>.dll`.
195 For example, for Vulkan version 1.X on Windows the library filename is
196 `vulkan-1.dll`.
198 directory (on 64-bit Windows installs, the 32-bit version of the loader with
207 On Linux, applications that have a hard dependency on Vulkan should request
209 For example by importing the CMake target `Vulkan::Vulkan` or by using the
210 output of `pkg-config --cflags --libs vulkan` as compiler flags.
213 Linux applications that load Vulkan-Loader dynamically at runtime do not
228 platform-specific way (i.e. packages on Linux) or as part of a driver install
229 (i.e. using the Vulkan Runtime installer on Windows).
230 Applications or engines may desire to install the Vulkan loader locally to their
234 1) Guarantees certain Vulkan API exports are available in the loader
235 2) Ensures certain loader behavior is well-known
243 2) It can prevent the application/engine from taking advantage of new Vulkan
245 3) The application/engine will miss out on important loader bug-fixes
254 But, that relies upon end-users correctly performing whatever update process is
258 One better alternative, at least on Windows, is to package the Vulkan Runtime
259 installer for the desired version of the Vulkan loader with your product.
260 Then, the installation process can use that to ensure the end-user's system
266 versions of Vulkan yet display a warning indicating functionality is disabled
272 Applications desiring Vulkan functionality beyond what Vulkan drivers
273 on their system already expose, may use various layers to augment the API.
274 A layer cannot add new Vulkan core API entry-points that are not exposed in
275 Vulkan.h.
276 However, layers may offer implementations of extensions that introduce
277 additional entry-points beyond what is available without those layers.
278 These additional extension entry-points can be queried through the Vulkan
281 A common use of layers is for API validation which can be enabled during
287 To find out what layers are available to an application, use
289 This will report all layers that have been discovered by the loader.
290 The loader looks in various locations to find layers on the system.
292 [Layer discovery](LoaderLayerInterface.md#layer-discovery)
296 To enable specific layers, simply pass the names of the layers to
299 Once done, the layers that have been enabled will be active for all Vulkan functions
302 **NOTE:** Layer ordering is important in several cases since some layers
304 Be careful when enabling layers as this may be the case.
305 See the [Overall Layer Ordering](#overall-layer-ordering) section for more
333 err = vkCreateInstance(&inst_info, NULL, &demo->inst);
340 that include the application specified (enabled) layers.
344 See the [Overall Layer Ordering](#overall-layer-ordering) section for more
347 **NOTE:** *Device Layers Are Now Deprecated*
348 > `vkCreateDevice` originally was able to select layers in a similar manner to
350 > This led to the concept of "instance layers" and "device layers".
352 > only consider "instance layers".
353 > Therefore, `vkCreateDevice` will use the layers specified at
362 ### Meta-Layers
364 Meta-layers are layers which contain an ordered list of other layers to enable.
365 This is to allow grouping layers together in a specified order so that they can
367 Originally, this was used to group together the individual Vulkan Validation
368 layers in the proper order to avoid conflicts.
370 split into multiple component layers.
372 layer, dropping the need for meta layers.
373 While not necessary for validation anymore, VkConfig does use meta layers to
374 group layers together based on user's preferences.
377 and the section later on the [Override Layer](#override-layer).
379 Meta-layers are detailed more in the
380 [Meta-Layers](LoaderLayerInterface.md#meta-layers) section of the
384 ### Implicit vs Explicit Layers
386 
388 Explicit layers are layers which are enabled by an application (e.g. with the
391 Implicit layers are enabled automatically by their very existence, unless
392 requiring an additional manual enable step, unlike explicit layers that must be
395 infotainment system) may have layers which they always want enabled for all
397 Other implicit layers may be for all applications started on a given system
398 (e.g. layers that overlay frames-per-second).
400 Implicit layers have an additional requirement over explicit layers in that
410 Discovery of system-installed implicit and explicit layers is described later
411 in the [Layer discovery](LoaderLayerInterface.md#layer-discovery)
415 Implicit and explicit layers may be found in different locations based on the
426 <td>Implicit layers are located in a different Windows registry location
427 than explicit layers.</td>
431 <td>Implicit layers are located in a different directory location than
432 explicit layers.</td>
436 <td>There is **No Support For Implicit Layers** on Android.</td>
440 <td>Implicit layers are located in a different directory location than
441 explicit layers.</td>
448 The "Override Layer" is a special implicit meta-layer created by the
452 return to standard Vulkan behavior.
454 pull it into the layer call stack with the standard implicit layers along with
455 all layers contained in the list of layers to load.
456 This allows an end-user or developer to easily force on any number of layers
460 [Override Meta-Layer](LoaderLayerInterface.md#override-meta-layer) section of the
466 Developers may need to use special, pre-production layers, without modifying
467 the system-installed layers.
473 tool shipped with the Vulkan SDK.
474 2. Directing the loader to look for layers in specific files and/or folders by using the
478 paths separated by the operating-system specific path separator.
494 [Table of Debug Environment Variables](LoaderInterfaceArchitecture.md#table-of-debug-environment-va…
507 [Elevated Privilege Caveats](LoaderInterfaceArchitecture.md#elevated-privilege-caveats)
508 in the top-level
512 ### Forcing Layers to be Enabled on Windows, Linux and macOS
514 Developers may want to enable layers that are not enabled by the given
519 1. Selecting specific layers using the
521 tool shipped with the Vulkan SDK.
522 2. Directing the loader to look for additional layers by name using the
525 Both can be used to enable additional layers which are not specified (enabled)
529 separated by the operating-system specific path separator.
533 the top-most layer (closest to the application) and the last layer name in the
534 list being the bottom-most layer (closest to the driver).
535 See the [Overall Layer Ordering](#overall-layer-ordering) section for more
538 Application specified layers and user specified layers (via environment
540 layers.
541 Layers specified via environment variable are top-most (closest to the
542 application) while layers specified by the application are bottom-most.
552 [Table of Debug Environment Variables](LoaderInterfaceArchitecture.md#table-of-debug-environment-va…
559 The overall ordering of all layers by the loader based on the above looks
564 Ordering may also be important internally to the list of explicit layers.
565 Some layers may be dependent on other behavior being implemented before
570 validation layer can intercept any Vulkan API calls the overlay layer needs to
578 [Debugging Possible Layer Issues](LoaderDebugging.md#debugging-possible-layer-issues)
587 Extensions can modify the behavior of the Vulkan API and need to be specified
589 These extensions can be implemented by a Vulkan driver, the loader, or a layer
591 Information about various extensions can be found in the Vulkan Spec, and
592 vulkan.h header file.
598 [Instance Versus Device](LoaderInterfaceArchitecture.md#instance-versus-device)
606 instance-level objects, such as `VkInstance` and `VkPhysicalDevice`.
607 A device extension does the same for device-level objects, such as `VkDevice`,
616 extensions of their respective type from layers (both explicit and implicit),
619 Looking at `vulkan.h`, both functions are very similar,
643 layer or the Vulkan platform implementation.
644 If "pLayerName" is NULL, extensions from Vulkan implementation components
645 (including loader, implicit layers, and drivers) are enumerated.
649 **Note:** While device layers are deprecated, the instance enabled layers are
650 still present in the device call-chain.
661 The Validation layers will catch this invalid API usage.
666 Khronos-approved WSI extensions are available and provide Windows System
674 For the most part, the selection is done in the loader using compile-time
678 - VK_KHR_surface
679 - VK_KHR_swapchain
680 - VK_KHR_display
682 In addition, each of the following OS targets for the loader support target-
686 | ---------------- | ------------------------------------------ |
694 entry-points for these extensions, there is a handshake required to actually
703 Only then can the WSI extension be properly used in a Vulkan program.
708 With the ability to expand Vulkan so easily, extensions will be created that
711 entry-point down the device call chain ending with the appropriate
712 driver entry-points.
731 Because the device call-chain does not normally pass through the loader
761 variable to a non-zero number.
769 To remedy this, the Vulkan loader will now sort devices once they have been
771 layers) in the following fashion:
795 environment variable `VK_LOADER_DISABLE_SELECT` to a non-zero value.
799 [Return to the top-level LoaderInterfaceArchitecture.md file.](LoaderInterfaceArchitecture.md)