Lines Matching +full:vulkan +full:- +full:rules
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),
111 This section also specifies the minimal conventions and rules a layer must
124 …ehavior of readdir](https://www.ibm.com/support/pages/order-directory-contents-returned-calls-read…
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
140 The format of [Layer Manifest File](#layer-manifest-file-format) is detailed
151 [Layer Manifest File Format](#layer-manifest-file-format) table.
157 `/data/local/debug/vulkan` folder.
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
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.
230 `SOFTWARE\Khronos\Vulkan` paths.
233 An application installer should not modify the device-specific registries,
236 The Vulkan loader will open each manifest file to obtain information about the
254 See [Exception for Elevated Privileges](#exception-for-elevated-privileges)
258 [Forcing Layer Source Folders](LoaderApplicationInterface.md#forcing-layer-source-folders)
265 On Linux, the Vulkan loader will scan for manifest files using environment
283 that the environment variables are non-malicious.
296 <td>Compile-time option set to possible location of layers installed from
297 non-Linux-distribution-provided packages.
304 <td>Compile-time option set to possible location of layers installed from
305 non-Linux-distribution-provided packages.
316 that the environment variables are non-malicious.
333 * Implicit Layers: Suffix = /vulkan/implicit_layer.d
334 * Explicit Layers: Suffix = /vulkan/explicit_layer.d
351 See [Exception for Elevated Privileges](#exception-for-elevated-privileges)
356 …ehavior of readdir](https://www.ibm.com/support/pages/order-directory-contents-returned-calls-read…
359 [Forcing Layer Source Folders](LoaderApplicationInterface.md#forcing-layer-source-folders)
383 /home/me/.config/vulkan/explicit_layer.d
384 /etc/xdg/vulkan/explicit_layer.d
385 /usr/local/etc/vulkan/explicit_layer.d
386 /etc/vulkan/explicit_layer.d
387 /home/me/.local/share/vulkan/explicit_layer.d
388 /usr/local/share/vulkan/explicit_layer.d
389 /usr/share/vulkan/explicit_layer.d
394 On Fuchsia, the Vulkan loader will scan for manifest files using environment
396 variable is not defined in the same way as [Linux](#linux-layer-discovery).
403 On macOS, the Vulkan loader will scan for manifest files using the application
416 <bundle>/Contents/Resources/vulkan/implicit_layer.d
417 /Users/Me/.config/vulkan/implicit_layer.d
418 /etc/xdg/vulkan/implicit_layer.d
419 /usr/local/etc/vulkan/implicit_layer.d
420 /etc/vulkan/implicit_layer.d
421 /Users/Me/.local/share/vulkan/implicit_layer.d
422 /usr/local/share/vulkan/implicit_layer.d
423 /usr/share/vulkan/implicit_layer.d
429 1.3.234 of the Vulkan headers and later.
441 [Filter Environment Variable Behaviors](LoaderInterfaceArchitecture.md#filter-environment-variable-…
447 comma-delimited list of globs to search for in known layers.
465 comma-delimited list of globs to search for in known layers.
513 1.3.262 of the Vulkan headers and later.
516 comma-delimited list of globs to search for in known layers.
545 running the Vulkan application with elevated privileges.
552 [Elevated Privilege Caveats](LoaderInterfaceArchitecture.md#elevated-privilege-caveats)
553 in the top-level
565 include/vulkan/vk_layer.h:
586 The `VkNegotiateLayerInterface` structure is similar to other Vulkan structures.
600 - This is for future growth
603 - The minimum value sent by the loader will be 2 since it is the first
628 The layer should report `VK_SUCCESS` in case the loader-provided interface
650 - "pfnGetInstanceProcAddr" should be set to the layer’s internal
652 - "pfnGetDeviceProcAddr" should be set to the layer’s internal
654 - "pfnGetPhysicalDeviceProcAddr" should be set to the layer’s internal
656 - If the layer supports no physical device extensions, it may set the
658 - More on this function later
674 [Dispatch Tables and Call Chains](LoaderInterfaceArchitecture.md#dispatch-tables-and-call-chains)
678 What's important to note here is that a layer can intercept Vulkan instance
688 Normally, when a layer intercepts a given Vulkan function, it will call down
697 This means that a dispatch mechanism is required for all Vulkan functions that
699 If a Vulkan function is not intercepted by a layer, or if a layer chooses to
711 The loader is responsible for dispatching all core and instance extension Vulkan
733 extension entry-points.
753 chain_info->u.pLayerInfo->pfnNextGetPhysicalDeviceProcAddr
755 [Example Code for CreateInstance](#example-code-for-createinstance)
770 structure during [Layer Version Negotiation](#layer-version-negotiation).
780 - If it is, return the function pointer
782 - If it is, return the function pointer
784 - If it returns non-NULL, return a trampoline to a generic physical device
788 - If it returns non-NULL, treat it as an unknown logical device command.
800 `vk_layerGetPhysicalDeviceProcAddr`, until at least a Vulkan version bump,
808 - If it was, it would return the function pointer
810 - If it was, it would return the function pointer
813 - If it returned non-NULL, treat it as an unknown logical device command.
814 - This meant setting up a generic trampoline function that takes in a
832 * Layers intercept a Vulkan function by defining a C/C++ function with
833 signature **identical** to the Vulkan API for that function.
838 * For any Vulkan function a layer intercepts which has a non-void return
842 corresponding Vulkan function in the next entity.
855 * These functions only call down the chain for Vulkan functions that they
857 * Layer intercept functions **may insert extra calls** to Vulkan functions in
872 - For each entry-point a layer intercepts, it must keep track of the
873 entry-point residing in the next entity in the chain it will call down into.
878 - A layer can use the `VkLayerDispatchTable` structure as a device dispatch
879 table (see include/vulkan/vk_dispatch_table_helper.h).
880 - A layer can use the `VkLayerInstanceDispatchTable` structure as a instance
881 dispatch table (see include/vulkan/vk_dispatch_table_helper.h).
882 - A Layer's `vkGetInstanceProcAddr` function uses the next entity's
884 non-intercepted) functions.
885 - A Layer's `vkGetDeviceProcAddr` function uses the next entity's
886 `vkGetDeviceProcAddr` to call down the chain for unknown (i.e. non-intercepted)
888 - A Layer's `vk_layerGetPhysicalDeviceProcAddr` function uses the next entity's
890 non-intercepted) functions.
893 ## Layer Conventions and Rules
895 A layer, when inserted into an otherwise compliant Vulkan driver, <b>must</b>
896 still result in a compliant Vulkan driver.
897 The intention is for layers to have a well-defined baseline behavior.
898 Therefore, it must follow some conventions and rules defined below.
907 * Follow that with the specific name of the layer (typically lower-case but not
923 * OS-modifier = "32" (for 32-bit version)
929 [Vulkan style-guide](https://www.khronos.org/registry/vulkan/specs/1.2/styleguide.html#extensions-n…
949 Additional rules include:
950 - `vkEnumerateInstanceLayerProperties` **must** enumerate and **only**
952 - `vkEnumerateInstanceExtensionProperties` **must** handle the case where
954 - It **must** return `VK_ERROR_LAYER_NOT_PRESENT` otherwise, including when
956 - `vkEnumerateDeviceLayerProperties` **is deprecated and may be omitted**.
957 - Using this will result in undefined behavior.
958 - `vkEnumerateDeviceExtensionProperties` **must** handle the case where
960 - In other cases, it should chain to other layers.
961 - `vkCreateInstance` **must not** generate an error for unrecognized layer
963 - It may assume the layer names and extension names have been validated.
964 - `vkGetInstanceProcAddr` intercepts a Vulkan function by returning a local
965 entry-point
966 - Otherwise it returns the value obtained by calling down the instance call
968 - `vkGetDeviceProcAddr` intercepts a Vulkan function by returning a local
969 entry-point
970 - Otherwise it returns the value obtained by calling down the device call
972 - These additional functions must be intercepted if the layer implements
973 device-level call chaining:
974 - `vkGetDeviceProcAddr`
975 - `vkCreateDevice`(only required for any device-level chaining)
976 - **NOTE:** older layer libraries may expect that
979 - The specification **requires** `NULL` to be returned from
981 - A layer may return `NULL` itself or rely on the following layers to do so.
986 - A layer initializes its instance dispatch table within its `vkCreateInstance`
988 - A layer initializes its device dispatch table within its `vkCreateDevice`
990 - The loader passes a linked list of initialization structures to layers via
993 - The head node in this linked list is of type `VkLayerInstanceCreateInfo` for
995 See file `include/vulkan/vk_layer.h` for details.
996 - A VK_STRUCTURE_TYPE_LOADER_INSTANCE_CREATE_INFO is used by the loader for the
998 - A VK_STRUCTURE_TYPE_LOADER_DEVICE_CREATE_INFO is used by the loader for the
1000 - The "function" field indicates how the union field "u" should be interpreted
1005 - The `VkLayerInstanceLink` and `VkLayerDeviceLink` structures are the list
1007 - The `VkLayerInstanceLink` contains the next entity's `vkGetInstanceProcAddr`
1009 - The `VkLayerDeviceLink` contains the next entity's `vkGetInstanceProcAddr`
1011 - Given the above structures set up by the loader, layer must initialize their
1013 - Find the `VkLayerInstanceCreateInfo`/`VkLayerDeviceCreateInfo` structure in
1015 - Get the next entity's vkGet*ProcAddr from the "pLayerInfo" field.
1016 - For CreateInstance get the next entity's `vkCreateInstance` by calling the
1019 - For CreateDevice get the next entity's `vkCreateDevice` by calling the
1023 - Advanced the linked list to the next node: pLayerInfo = pLayerInfo->pNext.
1024 - Call down the chain either `vkCreateDevice` or `vkCreateInstance`
1025 - Initialize the layer dispatch table by calling the next entity's
1026 Get*ProcAddr function once for each Vulkan function needed in the dispatch
1041 assert(chain_info->u.pLayerInfo);
1043 chain_info->u.pLayerInfo->pfnNextGetInstanceProcAddr;
1053 chain_info->u.pLayerInfo = chain_info->u.pLayerInfo->pNext;
1064 *pInstance, my_data->instance_dispatch_table, fpGetInstanceProcAddr);
1088 chain_info->u.pLayerInfo->pfnNextGetInstanceProcAddr;
1090 chain_info->u.pLayerInfo->pfnNextGetDeviceProcAddr;
1100 chain_info->u.pLayerInfo = chain_info->u.pLayerInfo->pNext;
1124 ## Meta-layers
1126 Meta-layers are a special kind of layer which is only available through the
1128 While normal layers are associated with one particular library, a meta-layer
1132 The benefits of a meta-layer are:
1134 grouping multiple layers in a meta-layer.
1136 the meta-layer.
1137 3. Layer configurations (internal to the meta-layer manifest file) can easily
1140 a meta-layer's component layers, and report them as the meta-layer's properties
1143 Restrictions to defining and using a meta-layer are:
1144 1. A Meta-layer Manifest file **must** be a properly formatted that contains
1146 3. All component layers **must be** present on a system for the meta-layer to
1148 4. All component layers **must be** at the same Vulkan API major and minor
1149 version as the meta-layer for the meta-layer to be used.
1151 The ordering of a meta-layer's component layers in the instance or device call-
1156 Inside the meta-layer Manifest file, each component layer is listed by its
1168 `VK_INSTANCE_LAYERS` and have that same layer listed in a meta-layer, then the
1169 environment-variable-enabled layer will be used and the component layer will
1171 Likewise, if a person were to enable a meta-layer and then separately enable
1175 The Manifest file formatting necessary to define a meta-layer can be found in
1176 the [Layer Manifest File Format](#layer-manifest-file-format) section.
1178 ### Override Meta-Layer
1180 If an implicit meta-layer was found on the system with the name
1185 * `blacklisted_layers` - List of explicit layer names that should not be
1187 * `app_keys` - List of paths to executables that the override layer applies
1189 * `override_paths` - List of paths which will be used as the search location
1205 The override meta-layer is primarily enabled when using the
1207 tool included in the Vulkan SDK.
1211 ## Pre-Instance Functions
1213 Vulkan includes a small number of functions which are called without any
1220 One reason why a layer may desire to intercept these pre-instance functions is
1221 to filter out extensions that would normally be returned from Vulkan drivers to
1224 pre-instance functions so that it may disable extensions it doesn't support.
1226 In order to intercept the pre-instance functions, several conditions must be
1230 * The layer must export the entry-point symbols for each intercepted function
1239 Pre-instance functions work differently from all other layer intercept
1245 Because there is no need to create an instance before calling the pre-instance
1293 [Layer Manifest File Format](#layer-manifest-file-format)).
1311 return pChain->pfnNextLayer(
1312 pChain->pNextLink, pLayerName, pPropertyCount, pProperties);
1328 return pChain->CallDown(pLayerName, pPropertyCount, pProperties);
1334 Because Vulkan does not store any state until an instance has been created, all
1335 layer libraries are released at the end of each pre-instance call.
1336 This means that implicit layers can use pre-instance intercepts to modify data
1342 ### Associating Private Data with Vulkan Objects Within a Layer
1344 A layer may want to associate its own private data with one or more Vulkan
1351 The loader supports layers wrapping any Vulkan object, including dispatchable
1356 However, when the value is returned from a lower-level layer (possibly the
1359 When a layer receives a Vulkan function using something that it previously
1362 This means that the layer **must intercept every Vulkan function which uses**
1365 object the layer wraps as well as any loader-layer interface functions such as
1400 This is because the lower-level layers and drivers won't receive the handle that
1439 - Layers that wrap dispatchable objects
1440 - Layers which add extensions that create dispatchable objects
1441 - Layers which insert extra Vulkan functions in the stream of functions they
1443 - Drivers which add extensions that create dispatchable objects
1470 - For `VkInstanceCreateInfo` the callback structure pointed to by "pNext" is
1471 `VkLayerInstanceCreateInfo` as defined in `include/vulkan/vk_layer.h`.
1472 - A "sType" field in of VK_STRUCTURE_TYPE_LOADER_INSTANCE_CREATE_INFO within
1474 - Within `VkLayerInstanceCreateInfo`, the "function" field indicates how the
1476 - A "function" equal to VK_LOADER_DATA_CALLBACK indicates the "u" field will
1478 - For `VkDeviceCreateInfo` the callback structure pointed to by "pNext" is
1479 `VkLayerDeviceCreateInfo` as defined in `include/vulkan/vk_layer.h`.
1480 - A "sType" field in of VK_STRUCTURE_TYPE_LOADER_DEVICE_CREATE_INFO within
1482 - Within `VkLayerDeviceCreateInfo`, the "function" field indicates how the union
1484 - A "function" equal to VK_LOADER_DATA_CALLBACK indicates the "u" field will
1501 There are several interacting rules concerning the activation of layers with
1502 non-obvious results.
1506 * The Vulkan Loader in versions 1.3.228 and above will enable implicit layers
1533 * Meta layers do not have to be implicit - they can be explicit.
1639 Here's an example of a meta-layer manifest file:
1648 "description" : "LunarG Meta-layer example",
1668 <td>The major.minor.patch version number of the Vulkan API that the layer
1671 It simply is an indication that the layer can support Vulkan API
1681 <td>List of paths to executables that the meta-layer applies to.
1683 <td><b>Meta-layers Only</b></td>
1692 <td><b>Meta-layers Only</b></td>
1699 part of a meta-layer.
1704 loader in order for this meta-layer to be available and activated. <br/>
1707 <td><b>Meta-layers Only</b></td>
1713 <td>A high-level description of the layer and its intended use.</td>
1728 the node "entrypoints" if the device extension adds Vulkan API
1730 The "entrypoint" node is an array of the names of all entry-points added
1740 Implicit Layer (when defined to any non-empty string value).<br/>
1742 application can set this environment variable (before calling Vulkan
1756 Implicit Layer (when defined to any non-empty string value).<br/>
1842 There are no rules about the name of the layer shared library files
1847 <td><b>Not Valid For Meta-layers</b></td>
1872 <td><b>Meta-layers Only</b></td>
1881 defined as a string entry where the key is the Vulkan function name and
1885 See <a href="#pre-instance-functions">Pre-Instance Functions</a> for
1914 Information about each version is detailed in the following sub-sections:
1933 These changes were made to enable third-party layers to expose their features
1935 [Vulkan Configurator](https://github.com/LunarG/VulkanTools/blob/main/vkconfig/README.md)
1966 loader needs to query using OS-specific calls.
1967 - NOTE: This is an optional field and, as the two previous fields, only
2011 [loader and layer interface](#layer-version-negotiation) using the
2014 [Layer Unknown Physical Device Extensions](#layer-unknown-physical-device-extensions)
2031 introspection functions, unrelated to any Vulkan function despite the names,
2034 - `vkEnumerateInstanceLayerProperties` enumerates all layers in a
2036 - This function never fails.
2037 - When the `Layer Library` contains only one layer, this function may be an
2039 - `vkEnumerateInstanceExtensionProperties` enumerates instance extensions of
2041 - "pLayerName" is always a valid layer name.
2042 - This function never fails.
2043 - When the `Layer Library` contains only one layer, this function may be an
2045 - `vkEnumerateDeviceLayerProperties` enumerates a subset (can be full,
2047 - "physicalDevice" is always `VK_NULL_HANDLE`.
2048 - This function never fails.
2049 - If a layer is not enumerated by this function, it will not participate in
2051 - `vkEnumerateDeviceExtensionProperties` enumerates device extensions of
2053 - "physicalDevice" is always `VK_NULL_HANDLE`.
2054 - "pLayerName" is always a valid layer name.
2055 - This function never fails.
2060 - `<layerName>GetInstanceProcAddr(instance, pName)` behaves identically to a
2066 - `<layerName>GetDeviceProcAddr` behaves identically to a layer's
2081 Much of this section is additive to the Vulkan spec, and necessary for
2085 Additionally, there should be a way to identify bad or non-conformant behavior
2094 best experience to end-users and developers.
2103 - Layers: which will have the string `LAYER_` as part of the policy number.
2104 - The Loader: which will have the string `LOADER_` as part of the policy
2118 <a href="https://source.android.com/devices/graphics/implement-vulkan">
2119 Android Vulkan documentation</a>.
2122 ### Requirements of Well-Behaved Layers
2128 <th>Result of Non-Compliance</th>
2135 <td>A layer, when inserted into an otherwise compliant Vulkan
2136 environment, <b>must</b> still result in a compliant Vulkan environment
2137 unless it intends to mimic non-compliant behavior (such as a device
2146 <a href="#layer-conventions-and-rules">Layer Conventions and Rules</a>
2163 <a href="#layer-conventions-and-rules">Layer Conventions and Rules</a>
2169 <td>Any new layer developed <b>should</b> adhere to the naming rules defined
2170 in the "Layer Conventions and Rules" section which also correspond to
2171 the naming rules defined in the Vulkan Style Guide section 3.4 on
2183 …<a href="https://www.khronos.org/registry/vulkan/specs/1.2/styleguide.html#extensions-naming-conve…
2184 Vulkan Style Guide section 3.4</a> <br/>
2185 <a href="#layer-conventions-and-rules">Layer Conventions and Rules</a>
2192 <i>vkNegotiateLoaderLayerInterfaceVersion</i> entry-point to negotiate
2200 <a href="#layer-version-negotiation">Layer Version Negotiation</a>
2214 <a href="#loader-and-layer-interface-negotiation">
2227 <a href="#layer-library-api-version-0">Layer Library API Version 0</a>
2229 <a href="#layer-manifest-file-format">Layer Manifest File Format</a>
2236 <a href="#layer-manifest-file-usage">Manifest File Usage</a></small>
2241 <td>If a layer is a Meta-layer, each component layer in its manifest file
2248 <a href="#meta-layers">Meta-Layers</a></small>
2253 <td>If a layer is a Meta-layer, each component layer in its manifest file
2254 <b>must</b> report the same or a newer Vulkan API major and minor
2255 version than the meta-layer.
2261 <a href="#meta-layers">Meta-Layers</a></small>
2275 <a href="#layer-manifest-file-format">Manifest File Format</a>, see
2289 <a href="#cautions-about-wrapping">Cautions About Wrapping</a></small>
2301 <a href="https://github.com/KhronosGroup/VK-GL-CTS/blob/main/external/openglcts/README.md">
2302 Vulkan CTS Documentation</a>
2316 <a href=#example-code-for-createinstance>Example Code for
2328 This could be done in the future, but requires re-designing the layer
2332 <a href=""#layer-dispatch-initialization">
2344 <a href="#example-code-for-createdevice">Example Code for
2355 <a href="#layer-dispatch-initialization">
2367 or tracking the memory used by the Vulkan components.
2374 <a href="#layer-conventions-and-rules">Layer Conventions and Rules</a>
2393 <a href="#layer-conventions-and-rules">Layer Conventions and Rules</a>
2412 <a href="#layer-conventions-and-rules">Layer Conventions and Rules</a>
2426 <a href="#layer-conventions-and-rules">Layer Conventions and Rules</a>
2433 or <i>vkGetDeviceProcAddr</i> for entry-points that it does not support
2435 extension certain entry-points are associated with should result in
2446 <a href="#layer-conventions-and-rules">Layer Conventions and Rules</a>
2461 <a href="#creating-new-dispatchable-objects">
2522 ### Requirements of a Well-Behaved Loader
2528 <th>Result of Non-Compliance</th>
2534 <td>A loader <b>must</b> support Vulkan layers.</td>
2535 <td>Users will not have access to critical parts of the Vulkan ecosystem
2543 more non-standard locations.<br/>
2544 This is to allow application/engine-specific layers as well as
2545 evaluating in-development layers without global installation.
2547 <td>It will be more difficult to use a Vulkan loader by certain
2550 <td><small><a href="#layer-discovery">Layer Discovery</a></small></td>
2559 <td><small><a href="#layer-discovery">Layer Discovery</a></small></td>
2563 <td>A loader <b>must not</b> load a Vulkan layer which defines an
2568 <td><small><a href="#layer-discovery">Layer Discovery</a></small></td>
2579 <a href="#loader-and-layer-interface-negotiation">
2594 <a href="#layer-manifest-file-format">Manifest File Format</a>, see
2608 <a href="#layer-manifest-file-format">Manifest File Format</a>, see
2624 <a href="#layer-dispatch-initialization">
2640 <a href="#layer-dispatch-initialization">
2647 <td>A loader <b>must</b> verify that all meta-layers contain valid
2649 report the same Vulkan API version as the meta-layer itself before it
2650 loads the meta-layer.
2655 <a href="#meta-layers">Meta-Layers</a></small>
2660 <td>If the override meta-layer is present, a loader <b>must</b> load it
2667 <a href="#override-meta-layer">Override Meta-Layer</a></small>
2672 <td>If the override meta-layer is present and has a blacklist of layers to
2678 <a href="#override-meta-layer">Override Meta-Layer</a></small>
2683 <td>A loader <b>must</b> not load from user-defined paths (including the
2685 environment variables) when running elevated (Administrator/Super-user)
2693 <td><small><a href="#layer-discovery">Layer Discovery</a></small></td>
2699 [Return to the top-level LoaderInterfaceArchitecture.md file.](LoaderInterfaceArchitecture.md)