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 # 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
126 versus the call chain of a device functions.
127 Remember, a [Vulkan instance is a high-level construct used to provide Vulkan
128 system-level information](LoaderInterfaceArchitecture.md#instance-specific).
136 This is also how a Vulkan device function call chain looks if queried
138 On the other hand, a device function doesn't need to worry about the broadcast
140 physical device the call should terminate at.
143 Thus, using a loader-exported Vulkan device function, the call chain
146 
149 `vkGetDeviceProcAddr` call on all device functions.
150 This further optimizes the call chain by removing the loader all-together under
153 
157 With many function calls, the lack of indirection in each adds up to non-trivial
160 **NOTE:** There are some device functions which still require the loader to
164 In those cases, even the device call chain will continue to look like the
166 One example of a device function requiring a *terminator* is
169 object into an driver-specific KHR_surface object prior to passing down the rest
173 * `vkGetInstanceProcAddr` is used to query instance and physical device
175 * `vkGetDeviceProcAddr` is only used to query device functions.
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
270 ## Application Layer Usage
272 Applications desiring Vulkan functionality beyond what Vulkan drivers
274 A layer cannot add new Vulkan core API entry-points that are not exposed in
275 Vulkan.h.
277 additional entry-points beyond what is available without those layers.
278 These additional extension entry-points can be queried through the Vulkan
292 [Layer discovery](LoaderLayerInterface.md#layer-discovery)
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
305 See the [Overall Layer Ordering](#overall-layer-ordering) section for more
309 `VK_LAYER_KHRONOS_validation` layer.
333 err = vkCreateInstance(&inst_info, NULL, &demo->inst);
335 // Couldn't find the validation layer
342 topmost (closest to the application) layer inserted in the chain and the last
344 See the [Overall Layer Ordering](#overall-layer-ordering) section for more
345 information on layer ordering.
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".
351 > It was decided by Khronos to deprecate the "device layer" functionality and
362 ### Meta-Layers
364 Meta-layers are layers which contain an ordered list of other layers to enable.
367 Originally, this was used to group together the individual Vulkan Validation
369 It was necessary because instead of a single Validation layer, validation was
371 The new `VK_LAYER_KHRONOS_validation` layer pulled everything into a single
372 layer, dropping the need for meta layers.
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
398 (e.g. layers that overlay frames-per-second).
408 are defined in the layer's JSON file.
410 Discovery of system-installed implicit and explicit layers is described later
411 in the [Layer discovery](LoaderLayerInterface.md#layer-discovery)
422 <th>Implicit Layer Identification</th>
446 #### Override Layer
448 The "Override Layer" is a special implicit meta-layer created by the
451 Once VkConfig exits, the override layer is removed, and the system should
452 return to standard Vulkan behavior.
453 Whenever the override layer is present in the layer search path, the loader will
454 pull it into the layer call stack with the standard implicit layers along with
456 This allows an end-user or developer to easily force on any number of layers
459 The override layer is discussed more in the
460 [Override Meta-Layer](LoaderLayerInterface.md#override-meta-layer) section of the
464 ### Forcing Layer Source Folders
466 Developers may need to use special, pre-production layers, without modifying
467 the system-installed layers.
471 1. Selecting specific layer paths using the
473 tool shipped with the Vulkan SDK.
478 the operating-system specific path separator.
483 layer manifest files.
484 Implicit layer discovery is unaffected by this environment variable.
485 Each directory listed should be the full pathname of a folder containing layer
489 [Table of Debug Environment Variables](LoaderInterfaceArchitecture.md#table-of-debug-environment-va…
502 [Elevated Privilege Caveats](LoaderInterfaceArchitecture.md#elevated-privilege-caveats)
503 in the top-level
516 tool shipped with the Vulkan SDK.
523 The `VK_INSTANCE_LAYERS` environment variable is a list of layer names to enable
524 separated by the operating-system specific path separator.
527 The order of the names is relevant with the first layer name in the list being
528 the top-most layer (closest to the application) and the last layer name in the
529 list being the bottom-most layer (closest to the driver).
530 See the [Overall Layer Ordering](#overall-layer-ordering) section for more
536 Layers specified via environment variable are top-most (closest to the
537 application) while layers specified by the application are bottom-most.
540 layer `VK_LAYER_KHRONOS_validation` on Linux or macOS is as follows:
547 [Table of Debug Environment Variables](LoaderInterfaceArchitecture.md#table-of-debug-environment-va…
552 ### Overall Layer Ordering
557 
562 For example: An overlay layer may want to use `VK_LAYER_KHRONOS_validation`
563 to verify that the overlay layer is behaving appropriately.
564 This requires putting the overlay layer closer to the application so that the
565 validation layer can intercept any Vulkan API calls the overlay layer needs to
569 ### Debugging Possible Layer Issues
571 If it is possible that a layer is causing issues, there are several things that
573 [Debugging Possible Layer Issues](LoaderDebugging.md#debugging-possible-layer-issues)
580 Extensions are optional functionality provided by a layer, the loader, or a
582 Extensions can modify the behavior of the Vulkan API and need to be specified
584 These extensions can be implemented by a Vulkan driver, the loader, or a layer
586 Information about various extensions can be found in the Vulkan Spec, and
587 vulkan.h header file.
590 ### Instance and Device Extensions
593 [Instance Versus Device](LoaderInterfaceArchitecture.md#instance-versus-device)
598 * Device Extensions
601 instance-level objects, such as `VkInstance` and `VkPhysicalDevice`.
602 A device extension does the same for device-level objects, such as `VkDevice`,
606 instance extensions must be enabled with `vkCreateInstance` while device
614 Looking at `vulkan.h`, both functions are very similar,
637 The "pLayerName" parameter in these functions is used to select either a single
638 layer or the Vulkan platform implementation.
639 If "pLayerName" is NULL, extensions from Vulkan implementation components
641 If "pLayerName" is equal to a discovered layer module name then only extensions
642 from that layer (which may be implicit or explicit) are enumerated.
644 **Note:** While device layers are deprecated, the instance enabled layers are
645 still present in the device call-chain.
647 Duplicate extensions (e.g. an implicit layer and driver might report support for
649 For duplicates, the driver version is reported and the layer version is culled.
661 Khronos-approved WSI extensions are available and provide Windows System
669 For the most part, the selection is done in the loader using compile-time
673 - VK_KHR_surface
674 - VK_KHR_swapchain
675 - VK_KHR_display
677 In addition, each of the following OS targets for the loader support target-
681 | ---------------- | ------------------------------------------ |
689 entry-points for these extensions, there is a handshake required to actually
691 * At least one physical device must support the extension(s)
692 * The application must use such a physical device when creating a logical
693 device
695 instance or logical device (this depends on whether or not the given extension
696 works with an instance or a device)
698 Only then can the WSI extension be properly used in a Vulkan program.
703 With the ability to expand Vulkan so easily, extensions will be created that
705 If the extension is a device extension, the loader will pass the unknown
706 entry-point down the device call chain ending with the appropriate
707 driver entry-points.
709 takes a physical device parameter as its first component.
724 expose entry points that take a physical device as their first parameter.
726 Because the device call-chain does not normally pass through the loader
727 *terminator*, this is not a problem for device extensions.
728 Additionally, since a physical device is associated with one driver, the loader
736 Most extension functionality only affects either a physical or logical device
756 variable to a non-zero number.
760 ## Physical Device Ordering
764 To remedy this, the Vulkan loader will now sort devices once they have been
767 * Sort based on device type (Discrete, Integrated, Virtual, all others)
768 * Sort internal to the types based on PCI information (Domain, Bus, Device, and
771 This allows for a consistent physical device order from run to run on the same
775 specific device, `VK_LOADER_DEVICE_SELECT`.
777 Vendor Id and Device Id (as returned from `vkGetPhysicalDeviceProperties` in
785 This will force on the device with a vendor ID of "0x10de" and a device ID
787 If that device is not found, this is simply ignored.
789 All device selection work done in the loader can be disabled by setting the
790 environment variable `VK_LOADER_DISABLE_SELECT` to a non-zero value.
792 device selection mechanism, but can be used by others.
794 [Return to the top-level LoaderInterfaceArchitecture.md file.](LoaderInterfaceArchitecture.md)