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 # Layer Interface to the 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/
16 ## Table of Contents <!-- omit from toc -->
18 - [Overview](#overview)
19 - [Layer Discovery](#layer-discovery)
20 - [Layer Manifest File Usage](#layer-manifest-file-usage)
21 - [Android Layer Discovery](#android-layer-discovery)
22 - [Windows Layer Discovery](#windows-layer-discovery)
23 - [Linux Layer Discovery](#linux-layer-discovery)
24 - [Example Linux Explicit Layer Search Path](#example-linux-explicit-layer-search-path)
25 - [Fuchsia Layer Discovery](#fuchsia-layer-discovery)
26 - [macOS Layer Discovery](#macos-layer-discovery)
27 - [Example macOS Implicit Layer Search Path](#example-macos-implicit-layer-search-path)
28 - [Layer Filtering](#layer-filtering)
29 - [Layer Enable Filtering](#layer-enable-filtering)
30 - [Layer Disable Filtering](#layer-disable-filtering)
31 - [Layer Special Case Disable](#layer-special-case-disable)
32 - [Layer Disable Warning](#layer-disable-warning)
33 …- [Allow certain Layers to ignore Layer Disabling](#allow-certain-layers-to-ignore-layer-disabling)
34 - [`VK_INSTANCE_LAYERS`](#vk_instance_layers)
35 - [Exception for Elevated Privileges](#exception-for-elevated-privileges)
36 - [Layer Version Negotiation](#layer-version-negotiation)
37 - [Layer Call Chains and Distributed Dispatch](#layer-call-chains-and-distributed-dispatch)
38 - [Layer Unknown Physical Device Extensions](#layer-unknown-physical-device-extensions)
39 …- [Reason for adding `vk_layerGetPhysicalDeviceProcAddr`](#reason-for-adding-vk_layergetphysicalde…
40 - [Layer Intercept Requirements](#layer-intercept-requirements)
41 - [Distributed Dispatching Requirements](#distributed-dispatching-requirements)
42 - [Layer Conventions and Rules](#layer-conventions-and-rules)
43 - [Layer Dispatch Initialization](#layer-dispatch-initialization)
44 - [Example Code for CreateInstance](#example-code-for-createinstance)
45 - [Example Code for CreateDevice](#example-code-for-createdevice)
46 - [Meta-layers](#meta-layers)
47 - [Override Meta-Layer](#override-meta-layer)
48 - [Pre-Instance Functions](#pre-instance-functions)
49 - [Special Considerations](#special-considerations)
50 …- [Associating Private Data with Vulkan Objects Within a Layer](#associating-private-data-with-vul…
51 - [Wrapping](#wrapping)
52 - [Cautions About Wrapping](#cautions-about-wrapping)
53 - [Hash Maps](#hash-maps)
54 - [Creating New Dispatchable Objects](#creating-new-dispatchable-objects)
55 - [Versioning and Activation Interactions](#versioning-and-activation-interactions)
56 - [Layer Manifest File Format](#layer-manifest-file-format)
57 - [Layer Manifest File Version History](#layer-manifest-file-version-history)
58 - [Layer Manifest File Version 1.2.1](#layer-manifest-file-version-121)
59 - [Layer Manifest File Version 1.2.0](#layer-manifest-file-version-120)
60 - [Layer Manifest File Version 1.1.2](#layer-manifest-file-version-112)
61 - [Layer Manifest File Version 1.1.1](#layer-manifest-file-version-111)
62 - [Layer Manifest File Version 1.1.0](#layer-manifest-file-version-110)
63 - [Layer Manifest File Version 1.0.1](#layer-manifest-file-version-101)
64 - [Layer Manifest File Version 1.0.0](#layer-manifest-file-version-100)
65 - [Layer Interface Versions](#layer-interface-versions)
66 - [Layer Interface Version 2](#layer-interface-version-2)
67 - [Layer Interface Version 1](#layer-interface-version-1)
68 - [Layer Interface Version 0](#layer-interface-version-0)
69 - [Loader and Layer Interface Policy](#loader-and-layer-interface-policy)
70 - [Number Format](#number-format)
71 - [Android Differences](#android-differences)
72 - [Requirements of Well-Behaved Layers](#requirements-of-well-behaved-layers)
73 - [Requirements of a Well-Behaved Loader](#requirements-of-a-well-behaved-loader)
78 This is the Layer-centric view of working with the Vulkan loader.
86 [Implicit versus Explicit](LoaderApplicationInterface.md#implicit-vs-explicit-layers),
88 [LoaderApplicationInterface.md](LoaderApplicationInterface.md) document, layers
90 * Implicit Layers
91 * Explicit Layers
93 The main difference between the two is that implicit layers are automatically
94 enabled, unless overridden, and explicit layers must be enabled.
95 Remember, implicit layers are not present on all Operating Systems (like
98 On any system, the loader looks in specific areas for information on the layers
100 The process of finding the available layers on a system is known as Layer
102 During discovery, the loader determines what layers are available, the layer
107 The group of layers available to the loader is known as the `Layer Library`.
108 This section defines an extensible interface to discover what layers are
113 layers.
123 point to different library files, the order which the layers is loaded is
124 …ehavior of readdir](https://www.ibm.com/support/pages/order-directory-contents-returned-calls-read…
127 globally among all enabled layers, during calls to `vkCreateInstance` or
134 On Windows, Linux, and macOS systems, JSON-formatted manifest files are used to
136 In order to find system-installed layers, the Vulkan loader will read the JSON
137 files to identify the names and attributes of layers and their extensions.
140 The format of [Layer Manifest File](#layer-manifest-file-format) is detailed
149 present in layers to maintain consistency.
151 [Layer Manifest File Format](#layer-manifest-file-format) table.
156 On Android, the loader looks for layers to enumerate in the
157 `/data/local/debug/vulkan` folder.
159 layers in that location.
164 In order to find system-installed layers, the Vulkan loader will scan the
168 HKEY_LOCAL_MACHINE\SOFTWARE\Khronos\Vulkan\ExplicitLayers
169 HKEY_CURRENT_USER\SOFTWARE\Khronos\Vulkan\ExplicitLayers
170 HKEY_LOCAL_MACHINE\SOFTWARE\Khronos\Vulkan\ImplicitLayers
171 HKEY_CURRENT_USER\SOFTWARE\Khronos\Vulkan\ImplicitLayers
174 Except when running a 32-bit application on 64-bit Windows, when the loader
175 will instead scan the 32-bit registry location:
178 HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Khronos\Vulkan\ExplicitLayers
179 HKEY_CURRENT_USER\SOFTWARE\WOW6432Node\Khronos\Vulkan\ExplicitLayers
180 HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Khronos\Vulkan\ImplicitLayers
181 HKEY_CURRENT_USER\SOFTWARE\WOW6432Node\Khronos\Vulkan\ImplicitLayers
190 not run layers that did not need administrator access to install.
192 Because some layers are installed alongside drivers, the loader will scan
196 contain configuration information for base settings, including Vulkan, OpenGL,
211 In addition, on 64-bit systems there may be another set of registry values,
213 These values record the locations of 32-bit layers on 64-bit operating systems,
214 in the same way as the Windows-on-Windows functionality.
229 In general, applications should install layers into the
230 `SOFTWARE\Khronos\Vulkan` paths.
231 The PnP registry locations are intended specifically for layers that are
233 An application installer should not modify the device-specific registries,
236 Additionally, the Vulkan loader will scan the system for well-known Windows
241 [OpenCL™, OpenGL®, and Vulkan® Compatibility Pack](https://apps.microsoft.com/store/detail/9NQPSL29…
243 The Vulkan loader will open each manifest file to obtain information about the
271 See [Exception for Elevated Privileges](#exception-for-elevated-privileges)
275 [Forcing Layer Source Folders](LoaderApplicationInterface.md#forcing-layer-source-folders)
282 On Linux, the Vulkan loader will scan for manifest files using environment
300 that the environment variables are non-malicious.
313 <td>Compile-time option set to possible location of layers installed from
314 non-Linux-distribution-provided packages.
321 <td>Compile-time option set to possible location of layers installed from
322 non-Linux-distribution-provided packages.
333 that the environment variables are non-malicious.
350 * Implicit Layers: Suffix = /vulkan/implicit_layer.d
351 * Explicit Layers: Suffix = /vulkan/explicit_layer.d
381 See [Exception for Elevated Privileges](#exception-for-elevated-privileges)
386 …ehavior of readdir](https://www.ibm.com/support/pages/order-directory-contents-returned-calls-read…
389 [Forcing Layer Source Folders](LoaderApplicationInterface.md#forcing-layer-source-folders)
413 /home/me/.config/vulkan/explicit_layer.d
414 /etc/xdg/vulkan/explicit_layer.d
415 /usr/local/etc/vulkan/explicit_layer.d
416 /etc/vulkan/explicit_layer.d
417 /home/me/.local/share/vulkan/explicit_layer.d
418 /usr/local/share/vulkan/explicit_layer.d
419 /usr/share/vulkan/explicit_layer.d
424 On Fuchsia, the Vulkan loader will scan for manifest files using environment
426 variable is not defined in the same way as [Linux](#linux-layer-discovery).
433 On macOS, the Vulkan loader will scan for manifest files using the application
446 <bundle>/Contents/Resources/vulkan/implicit_layer.d
447 /Users/Me/.config/vulkan/implicit_layer.d
448 /etc/xdg/vulkan/implicit_layer.d
449 /usr/local/etc/vulkan/implicit_layer.d
450 /etc/vulkan/implicit_layer.d
451 /Users/Me/.local/share/vulkan/implicit_layer.d
452 /usr/local/share/vulkan/implicit_layer.d
453 /usr/share/vulkan/implicit_layer.d
459 1.3.234 of the Vulkan headers and later.
462 disable known layers.
463 Known layers are those that are already found by the loader taking into account
471 [Filter Environment Variable Behaviors](LoaderInterfaceArchitecture.md#filter-environment-variable-…
477 comma-delimited list of globs to search for in known layers.
481 These layers are enabled after implicit layers but before other explicit layers.
489 [Vulkan Loader] WARNING | LAYER: Layer "VK_LAYER_LUNARG_wrap_objects" force enabled due to env var…
495 comma-delimited list of globs to search for in known layers.
501 This could mean that layers requested by an application are also not enabled
511 [Vulkan Loader] WARNING | LAYER: Layer "VK_LAYER_LUNARG_wrap_objects" disabled because name matche…
516 Because there are different types of layers, there are 3 additional special
527 This enables a developer to disable all layers on the system.
529 layers still present in the application call chain).
531 layers still present in the application call chain).
535 Disabling layers, whether just through normal usage of
538 relying on features provided by one or more explicit layers.
540 #### Allow certain Layers to ignore Layer Disabling
543 1.3.262 of the Vulkan headers and later.
546 comma-delimited list of globs to search for in known layers.
551 Implicit layers have the ability to only be enabled when a layer specified
560 Explicit layers listed by `VK_LOADER_LAYERS_ALLOW` will not be enabled.
561 Implicit layers listed by ``VK_LOADER_LAYERS_ALLOW` which are always active,
568 Because of this, any layers enabled via `VK_INSTANCE_LAYERS` will be treated the
569 same as layers enabled with `VK_LOADER_LAYERS_ENABLE` and will therefore
575 and `VK_ADD_IMPLICIT_LAYER_PATH` are ignored if running the Vulkan application
583 [Elevated Privilege Caveats](LoaderInterfaceArchitecture.md#elevated-privilege-caveats)
584 in the top-level
590 in the case of implicit layers, it can be loaded by default.
596 include/vulkan/vk_layer.h:
617 The `VkNegotiateLayerInterface` structure is similar to other Vulkan structures.
626 Once the loader has grabbed a valid address to the layers function, the loader
631 - This is for future growth
634 - The minimum value sent by the loader will be 2 since it is the first
659 The layer should report `VK_SUCCESS` in case the loader-provided interface
681 - "pfnGetInstanceProcAddr" should be set to the layer’s internal
683 - "pfnGetDeviceProcAddr" should be set to the layer’s internal
685 - "pfnGetPhysicalDeviceProcAddr" should be set to the layer’s internal
687 - If the layer supports no physical device extensions, it may set the
689 - More on this function later
705 [Dispatch Tables and Call Chains](LoaderInterfaceArchitecture.md#dispatch-tables-and-call-chains)
709 What's important to note here is that a layer can intercept Vulkan instance
719 Normally, when a layer intercepts a given Vulkan function, it will call down
728 This means that a dispatch mechanism is required for all Vulkan functions that
730 If a Vulkan function is not intercepted by a layer, or if a layer chooses to
734 For example, if the enabled layers intercepted only certain instance functions,
738 Likewise, if the enabled layers intercepted only a few of the device functions,
742 The loader is responsible for dispatching all core and instance extension Vulkan
748 Layers that intercept entrypoints which take a `VkPhysicalDevice` as the first
764 extension entry-points.
784 chain_info->u.pLayerInfo->pfnNextGetPhysicalDeviceProcAddr
786 [Example Code for CreateInstance](#example-code-for-createinstance)
801 structure during [Layer Version Negotiation](#layer-version-negotiation).
811 - If it is, return the function pointer
813 - If it is, return the function pointer
815 - If it returns non-NULL, return a trampoline to a generic physical device
819 - If it returns non-NULL, treat it as an unknown logical device command.
831 `vk_layerGetPhysicalDeviceProcAddr`, until at least a Vulkan version bump,
839 - If it was, it would return the function pointer
841 - If it was, it would return the function pointer
844 - If it returned non-NULL, treat it as an unknown logical device command.
845 - This meant setting up a generic trampoline function that takes in a
863 * Layers intercept a Vulkan function by defining a C/C++ function with
864 signature **identical** to the Vulkan API for that function.
869 * For any Vulkan function a layer intercepts which has a non-void return
873 corresponding Vulkan function in the next entity.
878 * This is because the function will not be received by layers further
886 * These functions only call down the chain for Vulkan functions that they
888 * Layer intercept functions **may insert extra calls** to Vulkan functions in
903 - For each entry-point a layer intercepts, it must keep track of the
904 entry-point residing in the next entity in the chain it will call down into.
909 - A layer can use the `VkLayerDispatchTable` structure as a device dispatch
910 table (see include/vulkan/vk_dispatch_table_helper.h).
911 - A layer can use the `VkLayerInstanceDispatchTable` structure as a instance
912 dispatch table (see include/vulkan/vk_dispatch_table_helper.h).
913 - A Layer's `vkGetInstanceProcAddr` function uses the next entity's
915 non-intercepted) functions.
916 - A Layer's `vkGetDeviceProcAddr` function uses the next entity's
917 `vkGetDeviceProcAddr` to call down the chain for unknown (i.e. non-intercepted)
919 - A Layer's `vk_layerGetPhysicalDeviceProcAddr` function uses the next entity's
921 non-intercepted) functions.
926 A layer, when inserted into an otherwise compliant Vulkan driver, <b>must</b>
927 still result in a compliant Vulkan driver.
928 The intention is for layers to have a well-defined baseline behavior.
931 In order for layers to have unique names, and reduce the chance of conflicts
932 that could occur when the loader attempts to load these layers, layers
938 * Follow that with the specific name of the layer (typically lower-case but not
954 * OS-modifier = "32" (for 32-bit version)
960 [Vulkan style-guide](https://www.khronos.org/registry/vulkan/specs/1.2/styleguide.html#extensions-n…
963 A layer is always chained with other layers.
965 layers.
966 When it changes the behavior of a function, it must make sure its upper layers
967 do not make invalid calls to or rely on undefined behaviors of its lower layers
970 objects created by its lower layers, it must make sure its lower layers never
972 layers.
977 For example, this usually applies to implicit layers that are always enabled.
981 - `vkEnumerateInstanceLayerProperties` **must** enumerate and **only**
983 - `vkEnumerateInstanceExtensionProperties` **must** handle the case where
985 - It **must** return `VK_ERROR_LAYER_NOT_PRESENT` otherwise, including when
987 - `vkEnumerateDeviceLayerProperties` **is deprecated and may be omitted**.
988 - Using this will result in undefined behavior.
989 - `vkEnumerateDeviceExtensionProperties` **must** handle the case where
991 - In other cases, it should chain to other layers.
992 - `vkCreateInstance` **must not** generate an error for unrecognized layer
994 - It may assume the layer names and extension names have been validated.
995 - `vkGetInstanceProcAddr` intercepts a Vulkan function by returning a local
996 entry-point
997 - Otherwise it returns the value obtained by calling down the instance call
999 - `vkGetDeviceProcAddr` intercepts a Vulkan function by returning a local
1000 entry-point
1001 - Otherwise it returns the value obtained by calling down the device call
1003 - These additional functions must be intercepted if the layer implements
1004 device-level call chaining:
1005 - `vkGetDeviceProcAddr`
1006 - `vkCreateDevice`(only required for any device-level chaining)
1007 - **NOTE:** older layer libraries may expect that
1010 - The specification **requires** `NULL` to be returned from
1012 - A layer may return `NULL` itself or rely on the following layers to do so.
1013 - A layer's implementation `vkGetInstanceProcAddr` **should**, when querying for
1016 - The specification **requires** that the `instance` parameter **must** be NULL.
1018 for non-NULL `instance` handles to be passed in and return a valid `vkCreateInstance`
1019 function pointer. The Vulkan-Loader itself does this and will continue to do so to
1020 maintain compatibility with layers which were released before this specification
1025 - A layer initializes its instance dispatch table within its `vkCreateInstance`
1027 - A layer initializes its device dispatch table within its `vkCreateDevice`
1029 - The loader passes a linked list of initialization structures to layers via
1032 - The head node in this linked list is of type `VkLayerInstanceCreateInfo` for
1034 See file `include/vulkan/vk_layer.h` for details.
1035 - A VK_STRUCTURE_TYPE_LOADER_INSTANCE_CREATE_INFO is used by the loader for the
1037 - A VK_STRUCTURE_TYPE_LOADER_DEVICE_CREATE_INFO is used by the loader for the
1039 - The "function" field indicates how the union field "u" should be interpreted
1044 - The `VkLayerInstanceLink` and `VkLayerDeviceLink` structures are the list
1046 - The `VkLayerInstanceLink` contains the next entity's `vkGetInstanceProcAddr`
1048 - The `VkLayerDeviceLink` contains the next entity's `vkGetInstanceProcAddr`
1050 - Given the above structures set up by the loader, layer must initialize their
1052 - Find the `VkLayerInstanceCreateInfo`/`VkLayerDeviceCreateInfo` structure in
1054 - Get the next entity's vkGet*ProcAddr from the "pLayerInfo" field.
1055 - For CreateInstance get the next entity's `vkCreateInstance` by calling the
1058 - For CreateDevice get the next entity's `vkCreateDevice` by calling the
1062 - Advanced the linked list to the next node: pLayerInfo = pLayerInfo->pNext.
1063 - Call down the chain either `vkCreateDevice` or `vkCreateInstance`
1064 - Initialize the layer dispatch table by calling the next entity's
1065 Get*ProcAddr function once for each Vulkan function needed in the dispatch
1080 assert(chain_info->u.pLayerInfo);
1082 chain_info->u.pLayerInfo->pfnNextGetInstanceProcAddr;
1092 chain_info->u.pLayerInfo = chain_info->u.pLayerInfo->pNext;
1103 *pInstance, my_data->instance_dispatch_table, fpGetInstanceProcAddr);
1127 chain_info->u.pLayerInfo->pfnNextGetInstanceProcAddr;
1129 chain_info->u.pLayerInfo->pfnNextGetDeviceProcAddr;
1139 chain_info->u.pLayerInfo = chain_info->u.pLayerInfo->pNext;
1163 ## Meta-layers
1165 Meta-layers are a special kind of layer which is only available through the
1167 While normal layers are associated with one particular library, a meta-layer
1168 is actually a collection layer which contains an ordered list of other layers
1169 (called component layers).
1171 The benefits of a meta-layer are:
1173 grouping multiple layers in a meta-layer.
1174 2. The order of individual component layers is loaded can be defined within
1175 the meta-layer.
1176 3. Layer configurations (internal to the meta-layer manifest file) can easily
1179 a meta-layer's component layers, and report them as the meta-layer's properties
1182 Restrictions to defining and using a meta-layer are:
1183 1. A Meta-layer Manifest file **must** be a properly formatted that contains
1184 one or more component layers.
1185 3. All component layers **must be** present on a system for the meta-layer to
1187 4. All component layers **must be** at the same Vulkan API major and minor
1188 version as the meta-layer for the meta-layer to be used.
1190 The ordering of a meta-layer's component layers in the instance or device call-
1195 Inside the meta-layer Manifest file, each component layer is listed by its
1198 file under the "layer" or "layers" tag.
1203 all enabled layers, will simply be ignored by the loader.
1207 `VK_INSTANCE_LAYERS` and have that same layer listed in a meta-layer, then the
1208 environment-variable-enabled layer will be used and the component layer will
1210 Likewise, if a person were to enable a meta-layer and then separately enable
1211 one of the component layers afterwards, the second instantiation of the layer
1214 The Manifest file formatting necessary to define a meta-layer can be found in
1215 the [Layer Manifest File Format](#layer-manifest-file-format) section.
1217 ### Override Meta-Layer
1219 If an implicit meta-layer was found on the system with the name
1221 This is used to selectively enable and disable other layers from being loaded.
1224 * `blacklisted_layers` - List of explicit layer names that should not be
1226 * `app_keys` - List of paths to executables that the override layer applies
1228 * `override_paths` - List of paths which will be used as the search location
1229 for component layers.
1238 paths exclusively for component layers.
1244 The override meta-layer is primarily enabled when using the
1246 tool included in the Vulkan SDK.
1250 ## Pre-Instance Functions
1252 Vulkan includes a small number of functions which are called without any
1254 <b>Most layers do not intercept these functions</b>, as layers are enabled when
1259 One reason why a layer may desire to intercept these pre-instance functions is
1260 to filter out extensions that would normally be returned from Vulkan drivers to
1263 pre-instance functions so that it may disable extensions it doesn't support.
1265 In order to intercept the pre-instance functions, several conditions must be
1269 * The layer must export the entry-point symbols for each intercepted function
1278 Pre-instance functions work differently from all other layer intercept
1283 creation so that layers can call down the chain.
1284 Because there is no need to create an instance before calling the pre-instance
1332 [Layer Manifest File Format](#layer-manifest-file-format)).
1350 return pChain->pfnNextLayer(
1351 pChain->pNextLink, pLayerName, pPropertyCount, pProperties);
1367 return pChain->CallDown(pLayerName, pPropertyCount, pProperties);
1371 Unlike with other functions in layers, the layer may not save any global data
1373 Because Vulkan does not store any state until an instance has been created, all
1374 layer libraries are released at the end of each pre-instance call.
1375 This means that implicit layers can use pre-instance intercepts to modify data
1381 ### Associating Private Data with Vulkan Objects Within a Layer
1383 A layer may want to associate its own private data with one or more Vulkan
1390 The loader supports layers wrapping any Vulkan object, including dispatchable
1395 However, when the value is returned from a lower-level layer (possibly the
1398 When a layer receives a Vulkan function using something that it previously
1401 This means that the layer **must intercept every Vulkan function which uses**
1404 object the layer wraps as well as any loader-layer interface functions such as
1407 Layers above the object wrapping layer will see the wrapped object.
1408 Layers which wrap dispatchable objects must ensure that the first field in the
1426 Layers that wrap dispatchable objects must follow the guidelines for creating
1431 Layers are generally discouraged from wrapping objects, because of the
1439 This is because the lower-level layers and drivers won't receive the handle that
1445 layers that wrap objects must check which extensions are being used by the
1449 The reason that the validation layers wrap objects is to track the proper use
1471 Layers which create dispatchable objects must take special care.
1478 - Layers that wrap dispatchable objects
1479 - Layers which add extensions that create dispatchable objects
1480 - Layers which insert extra Vulkan functions in the stream of functions they
1482 - Drivers which add extensions that create dispatchable objects
1509 - For `VkInstanceCreateInfo` the callback structure pointed to by "pNext" is
1510 `VkLayerInstanceCreateInfo` as defined in `include/vulkan/vk_layer.h`.
1511 - A "sType" field in of VK_STRUCTURE_TYPE_LOADER_INSTANCE_CREATE_INFO within
1513 - Within `VkLayerInstanceCreateInfo`, the "function" field indicates how the
1515 - A "function" equal to VK_LOADER_DATA_CALLBACK indicates the "u" field will
1517 - For `VkDeviceCreateInfo` the callback structure pointed to by "pNext" is
1518 `VkLayerDeviceCreateInfo` as defined in `include/vulkan/vk_layer.h`.
1519 - A "sType" field in of VK_STRUCTURE_TYPE_LOADER_DEVICE_CREATE_INFO within
1521 - Within `VkLayerDeviceCreateInfo`, the "function" field indicates how the union
1523 - A "function" equal to VK_LOADER_DATA_CALLBACK indicates the "u" field will
1540 There are several interacting rules concerning the activation of layers with
1541 non-obvious results.
1545 * The Vulkan Loader in versions 1.3.228 and above will enable implicit layers
1552 determined that the perceived protection of preventing older layers running
1554 This was due to older layers no longer working with newer applications
1555 for no apparent reason, as well as older layers having to update the manifest
1561 potentially badly behaving layers.
1568 Layers found in this path are treated as explicit, even if they contain all the
1572 * Meta layers do not have to be implicit - they can be explicit.
1576 implicitly enabled and explicitely enabled layers from activating.
1577 Any layers in an application's `VkInstanceCreateInfo::ppEnabledLayerNames` that
1586 replace the search paths the loader uses to find component layers.
1594 for explicit layers.
1596 present, none of the layers in `VK_LAYER_PATH` are discoverable, and the
1603 and layers.
1607 for applications to determine what layers should actually be loaded.
1658 Here's a snippet with the changes required to support multiple layers per
1663 "layers": [
1678 Here's an example of a meta-layer manifest file:
1687 "description" : "LunarG Meta-layer example",
1707 <td>The major.minor.patch version number of the Vulkan API that the layer
1710 It simply is an indication that the layer can support Vulkan API
1715 <td>"layer"/"layers"</td>
1720 <td>List of paths to executables that the meta-layer applies to.
1722 <td><b>Meta-layers Only</b></td>
1723 <td>"layer"/"layers"</td>
1731 <td><b>Meta-layers Only</b></td>
1732 <td>"layer"/"layers"</td>
1738 part of a meta-layer.
1742 All component layers must be present on the system and found by the
1743 loader in order for this meta-layer to be available and activated. <br/>
1746 <td><b>Meta-layers Only</b></td>
1747 <td>"layer"/"layers"</td>
1752 <td>A high-level description of the layer and its intended use.</td>
1754 <td>"layer"/"layers"</td>
1767 the node "entrypoints" if the device extension adds Vulkan API
1769 The "entrypoint" node is an array of the names of all entry-points added
1773 <td>"layer"/"layers"</td>
1779 Implicit Layer (when defined to any non-empty string value).<br/>
1781 application can set this environment variable (before calling Vulkan
1788 <td><b>Implicit Layers Only</b></td>
1789 <td>"layer"/"layers"</td>
1795 Implicit Layer (when defined to any non-empty string value).<br/>
1804 <td><b>Implicit Layers Only</b></td>
1805 <td>"layer"/"layers"</td>
1826 <td>"layer"/"layers"</td>
1836 <td>"layer"/"layers"</td>
1851 <td>"layer"/"layers"</td>
1863 <td>"layers"</td>
1864 <td>The identifier used to group multiple layers' information together.
1886 <td><b>Not Valid For Meta-layers</b></td>
1887 <td>"layer"/"layers"</td>
1903 <td>"layer"/"layers"</td>
1909 layers.
1911 <td><b>Meta-layers Only</b></td>
1912 <td>"layer"/"layers"</td>
1920 defined as a string entry where the key is the Vulkan function name and
1924 See <a href="#pre-instance-functions">Pre-Instance Functions</a> for
1927 <td><b>Implicit Layers Only</b></td>
1928 <td>"layer"/"layers"</td>
1938 Distinct instance and device layers are deprecated; there are now just
1939 instance layers.
1941 But now "DEVICE" layers are skipped over by the loader as if they were
1945 <td>"layer"/"layers"</td>
1953 Information about each version is detailed in the following sub-sections:
1964 [layer manifest schema](https://github.com/LunarG/VulkanTools/blob/main/vkconfig_core/layers/layers…
1972 These changes were made to enable third-party layers to expose their features
1974 [Vulkan Configurator](https://github.com/LunarG/VulkanTools/blob/main/vkconfig/README.md)
1979 Version 1.1.2 introduced the ability of layers to intercept function calls that
2005 loader needs to query using OS-specific calls.
2006 - NOTE: This is an optional field and, as the two previous fields, only
2014 The ability to define multiple layers using the "layers" array was added.
2016 layers.
2050 [loader and layer interface](#layer-version-negotiation) using the
2053 [Layer Unknown Physical Device Extensions](#layer-unknown-physical-device-extensions)
2070 introspection functions, unrelated to any Vulkan function despite the names,
2073 - `vkEnumerateInstanceLayerProperties` enumerates all layers in a
2075 - This function never fails.
2076 - When the `Layer Library` contains only one layer, this function may be an
2078 - `vkEnumerateInstanceExtensionProperties` enumerates instance extensions of
2079 layers in the `Layer Library`.
2080 - "pLayerName" is always a valid layer name.
2081 - This function never fails.
2082 - When the `Layer Library` contains only one layer, this function may be an
2084 - `vkEnumerateDeviceLayerProperties` enumerates a subset (can be full,
2085 proper, or empty subset) of layers in the `Layer Library`.
2086 - "physicalDevice" is always `VK_NULL_HANDLE`.
2087 - This function never fails.
2088 - If a layer is not enumerated by this function, it will not participate in
2090 - `vkEnumerateDeviceExtensionProperties` enumerates device extensions of
2091 layers in the `Layer Library`.
2092 - "physicalDevice" is always `VK_NULL_HANDLE`.
2093 - "pLayerName" is always a valid layer name.
2094 - This function never fails.
2099 - `<layerName>GetInstanceProcAddr(instance, pName)` behaves identically to a
2105 - `<layerName>GetDeviceProcAddr` behaves identically to a layer's
2111 All layers contained within a library must support `vk_layer.h`.
2119 and layers.
2120 Much of this section is additive to the Vulkan spec, and necessary for
2124 Additionally, there should be a way to identify bad or non-conformant behavior
2133 best experience to end-users and developers.
2142 - Layers: which will have the string `LAYER_` as part of the policy number.
2143 - The Loader: which will have the string `LOADER_` as part of the policy
2154 which indicates which policy statements apply to layers that are focused
2157 <a href="https://source.android.com/devices/graphics/implement-vulkan">
2158 Android Vulkan documentation</a>.
2161 ### Requirements of Well-Behaved Layers
2167 <th>Result of Non-Compliance</th>
2174 <td>A layer, when inserted into an otherwise compliant Vulkan
2175 environment, <b>must</b> still result in a compliant Vulkan environment
2176 unless it intends to mimic non-compliant behavior (such as a device
2185 <a href="#layer-conventions-and-rules">Layer Conventions and Rules</a>
2191 <td>A layer <b>must not</b> cause other layers or drivers to fail, crash, or
2194 of the layers or drivers below it.
2202 <a href="#layer-conventions-and-rules">Layer Conventions and Rules</a>
2210 the naming rules defined in the Vulkan Style Guide section 3.4 on
2219 Can not immediately enforce since it will cause some shipping layers
2222 …<a href="https://www.khronos.org/registry/vulkan/specs/1.2/styleguide.html#extensions-naming-conve…
2223 Vulkan Style Guide section 3.4</a> <br/>
2224 <a href="#layer-conventions-and-rules">Layer Conventions and Rules</a>
2231 <i>vkNegotiateLoaderLayerInterfaceVersion</i> entry-point to negotiate
2239 <a href="#layer-version-negotiation">Layer Version Negotiation</a>
2253 <a href="#loader-and-layer-interface-negotiation">
2262 … <a href="https://github.com/LunarG/VulkanTools/blob/main/vkconfig_core/layers/layers_schema.json">
2266 <a href="#layer-library-api-version-0">Layer Library API Version 0</a>
2268 <a href="#layer-manifest-file-format">Layer Manifest File Format</a>
2275 <a href="#layer-manifest-file-usage">Manifest File Usage</a></small>
2280 <td>If a layer is a Meta-layer, each component layer in its manifest file
2287 <a href="#meta-layers">Meta-Layers</a></small>
2292 <td>If a layer is a Meta-layer, each component layer in its manifest file
2293 <b>must</b> report the same or a newer Vulkan API major and minor
2294 version than the meta-layer.
2300 <a href="#meta-layers">Meta-Layers</a></small>
2314 <a href="#layer-manifest-file-format">Manifest File Format</a>, see
2328 <a href="#cautions-about-wrapping">Cautions About Wrapping</a></small>
2340 <a href="https://github.com/KhronosGroup/VK-GL-CTS/blob/main/external/openglcts/README.md">
2341 Vulkan CTS Documentation</a>
2355 <a href=#example-code-for-createinstance>Example Code for
2359 layers will access incorrect content.</td>
2365 This is because the loader calls all layers at once and has no data on
2367 This could be done in the future, but requires re-designing the layer
2371 <a href=""#layer-dispatch-initialization">
2383 <a href="#example-code-for-createdevice">Example Code for
2387 layers will access incorrect content.</td>
2394 <a href="#layer-dispatch-initialization">
2406 or tracking the memory used by the Vulkan components.
2413 <a href="#layer-conventions-and-rules">Layer Conventions and Rules</a>
2432 <a href="#layer-conventions-and-rules">Layer Conventions and Rules</a>
2451 <a href="#layer-conventions-and-rules">Layer Conventions and Rules</a>
2465 <a href="#layer-conventions-and-rules">Layer Conventions and Rules</a>
2472 or <i>vkGetDeviceProcAddr</i> for entry-points that it does not support
2474 extension certain entry-points are associated with should result in
2485 <a href="#layer-conventions-and-rules">Layer Conventions and Rules</a>
2500 <a href="#creating-new-dispatchable-objects">
2522 tracking badly behaving layers based on the layer name, version,
2530 layers.<br/>
2535 <b>must</b> do so only after the call to the lower layers returns.
2546 layers.<br/>
2551 <b>must</b> do so only after the call to the lower layers returns.
2561 ### Requirements of a Well-Behaved Loader
2567 <th>Result of Non-Compliance</th>
2573 <td>A loader <b>must</b> support Vulkan layers.</td>
2574 <td>Users will not have access to critical parts of the Vulkan ecosystem
2575 such as Validation Layers, GfxReconstruct, or RenderDoc.</td>
2581 <td>A loader <b>must</b> support a mechanism to load layers in one or
2582 more non-standard locations.<br/>
2583 This is to allow application/engine-specific layers as well as
2584 evaluating in-development layers without global installation.
2586 <td>It will be more difficult to use a Vulkan loader by certain
2589 <td><small><a href="#layer-discovery">Layer Discovery</a></small></td>
2598 <td><small><a href="#layer-discovery">Layer Discovery</a></small></td>
2602 <td>A loader <b>must not</b> load a Vulkan layer which defines an
2607 <td><small><a href="#layer-discovery">Layer Discovery</a></small></td>
2618 <a href="#loader-and-layer-interface-negotiation">
2630 <td>Some layers may be used when not intended.</td>
2633 <a href="#layer-manifest-file-format">Manifest File Format</a>, see
2644 <td>Some layers may be used when not intended.</td>
2647 <a href="#layer-manifest-file-format">Manifest File Format</a>, see
2660 <td>Layers will crash as they attempt to load invalid data.</td>
2663 <a href="#layer-dispatch-initialization">
2676 <td>Layers will crash as they attempt to load invalid data.</td>
2679 <a href="#layer-dispatch-initialization">
2686 <td>A loader <b>must</b> verify that all meta-layers contain valid
2687 component layers that the loader can find on the system and that also
2688 report the same Vulkan API version as the meta-layer itself before it
2689 loads the meta-layer.
2694 <a href="#meta-layers">Meta-Layers</a></small>
2699 <td>If the override meta-layer is present, a loader <b>must</b> load it
2700 and corresponding component layers after all other implicit layers have
2706 <a href="#override-meta-layer">Override Meta-Layer</a></small>
2711 <td>If the override meta-layer is present and has a blacklist of layers to
2712 remove, a loader <b>must</b> disable all layers listed in the blacklist.
2717 <a href="#override-meta-layer">Override Meta-Layer</a></small>
2722 <td>A loader <b>must</b> not load from user-defined paths (including the
2725 elevated (Administrator/Super-user) applications.<br/>
2732 <td><small><a href="#layer-discovery">Layer Discovery</a></small></td>
2738 [Return to the top-level LoaderInterfaceArchitecture.md file.](LoaderInterfaceArchitecture.md)