| Search Order | Directory/Environment Variable | Fallback | Additional Notes |
|---|---|---|---|
| 1 | $XDG_CONFIG_HOME | $HOME/.config | This path is ignored when running with elevated privileges such as
setuid, setgid, or filesystem capabilities. This is done because under these scenarios it is not safe to trust that the environment variables are non-malicious. |
| 1 | $XDG_CONFIG_DIRS | /etc/xdg | |
| 2 | SYSCONFDIR | /etc | Compile-time option set to possible location of layers installed from non-Linux-distribution-provided packages. |
| 3 | EXTRASYSCONFDIR | /etc | Compile-time option set to possible location of layers installed from non-Linux-distribution-provided packages. Typically only set if SYSCONFDIR is set to something other than /etc |
| 4 | $XDG_DATA_HOME | $HOME/.local/share | This path is ignored when running with elevated privileges such as
setuid, setgid, or filesystem capabilities. This is done because under these scenarios it is not safe to trust that the environment variables are non-malicious. |
| 5 | $XDG_DATA_DIRS | /usr/local/share/:/usr/share/ |
| JSON Node | Description and Notes | Restrictions | Parent | Introspection Query |
|---|---|---|---|---|
| "api_version" | The major.minor.patch version number of the Vulkan API that the layer supports. It does not require the application to make use of that API version. It simply is an indication that the layer can support Vulkan API instance and device functions up to and including that API version. For example: 1.0.33. | None | "layer"/"layers" | vkEnumerateInstanceLayerProperties |
| "app_keys" | List of paths to executables that the meta-layer applies to. | Meta-layers Only | "layer"/"layers" | N/A |
| "blacklisted_layers" | List of explicit layer names that should not be loaded even if requested by the application. | Meta-layers Only | "layer"/"layers" | N/A |
| "component_layers" | Indicates the component layer names that are
part of a meta-layer.
The names listed must be the "name" identified in each of the component
layer's Mainfest file "name" tag (this is the same as the name of the
layer that is passed to the `vkCreateInstance` command).
All component layers must be present on the system and found by the
loader in order for this meta-layer to be available and activated. This field must not be present if "library_path" is defined. |
Meta-layers Only | "layer"/"layers" | N/A |
| "description" | A high-level description of the layer and its intended use. | None | "layer"/"layers" | vkEnumerateInstanceLayerProperties |
| "device_extensions" | OPTIONAL: Contains the list of device extension names supported by this layer. One "device\_extensions" node with an array of one or more elements is required if any device extensions are supported by a layer; otherwise the node is optional. Each element of the array must have the nodes "name" and "spec_version" which correspond to `VkExtensionProperties` "extensionName" and "specVersion" respectively. Additionally, each element of the array of device extensions must have the node "entrypoints" if the device extension adds Vulkan API functions; otherwise this node is not required. The "entrypoint" node is an array of the names of all entry-points added by the supported extension. | None | "layer"/"layers" | vkEnumerateDeviceExtensionProperties |
| "disable_environment" | REQUIRED: Indicates an environment variable used to disable the
Implicit Layer (when defined to any non-empty string value). In rare cases of an application not working with an implicit layer, the application can set this environment variable (before calling Vulkan functions) in order to "blacklist" the layer. This environment variable (which may vary with each variation of the layer) must be set (not particularly to any value). If both the "enable_environment" and "disable_environment" variables are set, the implicit layer is disabled. |
Implicit Layers Only | "layer"/"layers" | N/A |
| "enable_environment" | OPTIONAL: Indicates an environment variable used to enable the
Implicit Layer (when defined to any non-empty string value). This environment variable (which may vary with each variation of the layer) must be set to the given value or else the implicit layer is not loaded. This is for application environments (e.g. Steam) which want to enable a layer(s) only for applications that they launch, and allows for applications run outside of an application environment to not get that implicit layer(s). |
Implicit Layers Only | "layer"/"layers" | N/A |
| "file_format_version" | Manifest format major.minor.patch version number. Supported versions are: 1.0.0, 1.0.1, 1.1.0, 1.1.1, 1.1.2 and 1.2.0. |
None | None | N/A |
| "functions" | OPTIONAL: This section can be used to identify a different function name for the loader to use in place of standard layer interface functions. The "functions" node is required if the layer is using an alternative name for `vkNegotiateLoaderLayerInterfaceVersion`. | None | "layer"/"layers" | vkGet*ProcAddr |
| "implementation_version" | The version of the layer implemented. If the layer itself has any major changes, this number should change so the loader and/or application can identify it properly. | None | "layer"/"layers" | vkEnumerateInstanceLayerProperties |
| "instance_extensions" | OPTIONAL: Contains the list of instance extension names supported by this layer. One "instance_extensions" node with an array of one or more elements is required if any instance extensions are supported by a layer; otherwise the node is optional. Each element of the array must have the nodes "name" and "spec_version" which correspond to `VkExtensionProperties` "extensionName" and "specVersion" respectively. | None | "layer"/"layers" | vkEnumerateInstanceExtensionProperties |
| "layer" | The identifier used to group a single layer's information together. | None | None | vkEnumerateInstanceLayerProperties |
| "layers" | The identifier used to group multiple layers' information together. This requires a minimum Manifest file format version of 1.0.1. | None | None | vkEnumerateInstanceLayerProperties |
| "library_path" | Specifies either a filename, a relative pathname, or a full pathname to
a layer shared library file.
If "library_path" specifies a relative pathname, it is relative to the
path of the JSON manifest file (e.g. for cases when an application
provides a layer that is in the same folder hierarchy as the rest of the
application files).
If "library_path" specifies a filename, the library must live in the
system's shared object search path.
There are no rules about the name of the layer shared library files
other than it should end with the appropriate suffix (".DLL" on Windows,
".so" on Linux, and ".dylib" on macOS). This field must not be present if "component_layers" is defined. |
Not Valid For Meta-layers | "layer"/"layers" | N/A | "library_arch" | Optional field which specifies the architecture of the binary associated
with "library_path". Allows the loader to quickly determine if the architecture of the layer matches that of the running application. The only valid values are "32" and "64". |
N/A |
| "name" | The string used to uniquely identify this layer to applications. | None | "layer"/"layers" | vkEnumerateInstanceLayerProperties |
| "override_paths" | List of paths which will be used as the search location for component layers. | Meta-layers Only | "layer"/"layers" | N/A |
| "pre_instance_functions" | OPTIONAL: Indicates which functions the layer wishes to
intercept, that do not require that an instance has been created.
This should be an object where each function to be intercepted is
defined as a string entry where the key is the Vulkan function name and
the value is the name of the intercept function in the layer's dynamic
library.
Available in layer manifest versions 1.1.2 and up. See Pre-Instance Functions for more information. |
Implicit Layers Only | "layer"/"layers" | vkEnumerateInstance*Properties |
| "type" | This field indicates the type of layer. The values can be: GLOBAL, or
INSTANCE. NOTE: Prior to deprecation, the "type" node was used to indicate which layer chain(s) to activate the layer upon: instance, device, or both. Distinct instance and device layers are deprecated; there are now just instance layers. Originally, allowable values were "INSTANCE", "GLOBAL" and, "DEVICE." But now "DEVICE" layers are skipped over by the loader as if they were not found. |
None | "layer"/"layers" | vkEnumerate*LayerProperties |
| Requirement Number | Requirement Description | Result of Non-Compliance | Applicable to Android? | Enforceable by Loader? | Reference Section |
|---|---|---|---|---|---|
| LLP_LAYER_1 | A layer, when inserted into an otherwise compliant Vulkan environment, must still result in a compliant Vulkan environment unless it intends to mimic non-compliant behavior (such as a device simulation layer). | The behavior is undefined and may result in crashes or corruption. | Yes | No It is not a simple task for the loader to find the cause of failure in a layer chain. |
Layer Conventions and Rules |
| LLP_LAYER_2 | A layer must not cause other layers or drivers to fail, crash, or
otherwise misbehave. It must not make invalid calls to, or rely on undefined behaviors of the layers or drivers below it. |
The behavior is undefined and may result in crashes or corruption. | Yes | No It is not a simple task for the loader to find the cause of failure in a layer chain. |
Layer Conventions and Rules |
| LLP_LAYER_3 | Any new layer developed should adhere to the naming rules defined in the "Layer Conventions and Rules" section which also correspond to the naming rules defined in the Vulkan Style Guide section 3.4 on "Version, Extension, and Layer Naming Conventions". | Layer developers could produce conflicting names causing unexpected behavior if more than one layer with the same name is available on a user's platform. | Yes | Yes Can not immediately enforce since it will cause some shipping layers to stop working. |
Vulkan Style Guide section 3.4 Layer Conventions and Rules |
| LLP_LAYER_4 | A layer should export the
vkNegotiateLoaderLayerInterfaceVersion entry-point to negotiate
an interface version. A layer using interface 2 or newer must export this function. |
The layer will not be loaded. | No | Yes | Layer Version Negotiation |
| LLP_LAYER_5 | A layer must be able to negotiate a supported version of the loader/layer interface with the loader in accordance with the stated negotiation process. | The layer will not be loaded. | No | Yes | Interface Negotiation |
| LLP_LAYER_6 | A layer must have a valid JSON manifest file for the loader to process that ends with the ".json" suffix. It is recommended validating the layer manifest file against the layer schema prior to publication. The only exception is on Android which determines layer functionality through the introspection functions defined in Layer Library API Version 0 section and in the Layer Manifest File Format table. | The layer will not be loaded. | No | Yes | Manifest File Usage |
| LLP_LAYER_7 | If a layer is a Meta-layer, each component layer in its manifest file must be present on the system. | The layer will not be loaded. | No | Yes | Meta-Layers |
| LLP_LAYER_8 | If a layer is a Meta-layer, each component layer in its manifest file must report the same or a newer Vulkan API major and minor version than the meta-layer. | The layer will not be loaded. | No | Yes | Meta-Layers |
| LLP_LAYER_9 | A layer installed as an Implicit Layer must define a disable environment variable so it can be disabled globally. | The layer will not be loaded if it does not define the environment variable. | Yes | Yes | Manifest File Format, see "disable_environment" variable |
| LLP_LAYER_10 | If a layer wraps individual object handles, it must unwrap those handles when passing the handles down the chain to the next layer. | The behavior is undefined and may result in crashes or corruption. | Yes | No | Cautions About Wrapping |
| LLP_LAYER_11 | Any layer shipped with a driver must be validated against conformance with the corresponding driver. | The behavior is undefined and may result in crashes or corruption. | Yes | No | Vulkan CTS Documentation |
| LLP_LAYER_12 | During vkCreateInstance, a layer must process the
VkLayerInstanceCreateInfo chain links appropriately. This includes getting the next layer's vkGetInstanceProcAddr function for building a dispatch table as well as updating the VkLayerInstanceCreateInfo chain link to point to the next structure in the chain for the next layer prior to calling down to the next layer's vkCreateInstance function. An example of such usage is shown in detail in the Example Code for CreateInstance section. |
The behavior will result in crashes or corruption as any following layers will access incorrect content. | Yes | No With the current loader/layer design, it is difficult for the loader to diagnose this without adding additional overhead that could impact performance. This is because the loader calls all layers at once and has no data on the intermediate state of the pNext chain contents. This could be done in the future, but requires re-designing the layer initialization process. |
Layer Dispatch Initialization | LLP_LAYER_13 | During vkCreateDevice, a layer must process the
VkLayerDeviceCreateInfo chain links appropriately. This includes updating the VkLayerDeviceCreateInfo chain link to point to the next structure in the chain for the next layer prior to calling down to the next layer's vkCreateDevice function. An example of such usage is shown in detail in the Example Code for CreateDevice section. |
The behavior will result in crashes or corruption as any following layers will access incorrect content. | Yes | No With the current loader/layer design, it is difficult for the loader to diagnose this without adding additional overhead that could impact performance. |
Layer Dispatch Initialization |
| LLP_LAYER_14 | A layer should use the application provided memory allocator functions when they are provided so that applications can keep track of allocated memory. | The allocator functions may be provided for the purpose of limiting or tracking the memory used by the Vulkan components. Because of this, if a layer ignores these allocators, it may result in undefined behavior possibly including crashes or corruption. | Yes | No | Layer Conventions and Rules |
| LLP_LAYER_15 | A layer must enumerate only its own extension properties during a
call of vkEnumerateInstanceExtensionProperties when
pLayerName refers to itself. Otherwise, it must return VK_ERROR_LAYER_NOT_PRESENT, including when pLayerName is NULL. |
The loader could become confused on what support is present in a specific layer which will result in undefined behavior possibly including crashes or corruption. | Yes | No | Layer Conventions and Rules |
| LLP_LAYER_16 | A layer must enumerate only its own extension properties during a
call of vkEnumerateDeviceExtensionProperties when
pLayerName refers to itself. Otherwise, it must ignore the call other than passing it down the standard call chain. |
The loader could become confused on what support is present in a specific layer which will result in undefined behavior possibly including crashes or corruption. | Yes | No | Layer Conventions and Rules |
| LLP_LAYER_17 | A layer's vkCreateInstance must not generate an error for unrecognized extension names as the extension could be implemented by a lower layer or driver. | The behavior is undefined and may result in crashes or corruption. | Yes | Yes | Layer Conventions and Rules |
| LLP_LAYER_18 | A layer must return NULL from vkGetInstanceProcAddr or vkGetDeviceProcAddr for entry-points that it does not support or that have not been enabled properly (for example not enabling the extension certain entry-points are associated with should result in vkGetInstanceProcAddr returning NULL when requesting them). | The behavior is undefined and may result in crashes or corruption. | Yes | No With the current loader/layer design, it is difficult for the loader to determine this without adding additional overhead that could impact performance. |
Layer Conventions and Rules |
| LLP_LAYER_19 | If a layer creates dispatchable objects, either because it is wrapping objects or implementing an extension not supported by the loader or underlying drivers, it must create the dispatch table appropriately for all created dispatchable objects. | The behavior is undefined and may result in crashes or corruption. | Yes | No | Creating New Dispatchable Objects |
| LLP_LAYER_20 | A layer must remove all manifest files and references
to those files (i.e. Registry entries on Windows) when uninstalling.
Similarly, on updating the layer files, the old files must be all updated or removed. |
The loader ignores duplicate attempts to load the same manifest file, but if an old file is left pointing to an incorrect library, it will result in undefined behavior which may include crashes or corruption. | No | No The loader has no idea what layer files are new, old, or incorrect. Any type of layer file verification would quickly become very complex since it would require the loader to maintain an internal database tracking badly behaving layers based on the layer name, version, targeted platform(s), and possibly other criteria. | N/A |
| LLP_LAYER_21 | During vkCreateInstance, a layer must not modify the
pInstance pointer during prior to calling down to the lower
layers. This is because the loader passes information in this pointer that is necessary for the initialization code in the loader's terminator function. Instead, if the layer is overriding the pInstance pointer, it must do so only after the call to the lower layers returns. |
The loader will likely crash. | No | Yes | N/A |
| Requirement Number | Requirement Description | Result of Non-Compliance | Applicable to Android? | Reference Section |
|---|---|---|---|---|
| LLP_LOADER_1 | A loader must support Vulkan layers. | Users will not have access to critical parts of the Vulkan ecosystem such as Validation Layers, GfxReconstruct, or RenderDoc. | Yes | N/A |
| LLP_LOADER_2 | A loader must support a mechanism to load layers in one or
more non-standard locations. This is to allow application/engine-specific layers as well as evaluating in-development layers without global installation. |
It will be more difficult to use a Vulkan loader by certain tools and driver developers. | No | Layer Discovery |
| LLP_LOADER_3 | A loader must filter out duplicate layer names in the various enable lists, keeping only the first occurrence. | The behavior is undefined and may result in crashes or corruption. | Yes | Layer Discovery |
| LLP_LOADER_4 | A loader must not load a Vulkan layer which defines an API version that is incompatible with itself. | The behavior is undefined and may result in crashes or corruption. | Yes | Layer Discovery |
| LLP_LOADER_5 | A loader must ignore any layer for which a compatible interface version can not be negotiated. | The loader would load a layer improperly resulting in undefined behavior which may include crashes or corruption. | No | Interface Negotiation |
| LLP_LOADER_6 | If a layer is implicit, and it has an enable environment variable,
then a loader must not consider the layer enabled unless that
enable environment variable is defined. If an implicit layer does not have an enable environment variable, it will be considered enabled by default. |
Some layers may be used when not intended. | No | Manifest File Format, see "enable_environment" variable |
| LLP_LOADER_7 | If an implicit layer is enabled, but has been disabled by some other mechanism (such as the defining of the layer's disable environment variable or through the blacklisting mechanism of the Override Layer), then a loader must not load that layer. | Some layers may be used when not intended. | No | Manifest File Format, see "disable_environment" variable |
| LLP_LOADER_8 | A loader must pass a linked list of initialization structures to each layer via the VkLayerInstanceCreateInfo structure in the pNext field of the VkInstanceCreateInfo structure. This contains necessary information for setting up the instance call chain including providing a function pointer to the next links vkGetInstanceProcAddr. | Layers will crash as they attempt to load invalid data. | Yes | Layer Dispatch Initialization |
| LLP_LOADER_9 | A loader must pass a linked list of initialization structures to each layer via the VkLayerDeviceCreateInfo structure in the pNext field of the VkDeviceCreateInfo structure. This contains necessary information for setting up the device call chain including providing a function pointer to the next links vkGetDeviceProcAddr. | Layers will crash as they attempt to load invalid data. | Yes | Layer Dispatch Initialization |
| LLP_LOADER_10 | A loader must verify that all meta-layers contain valid component layers that the loader can find on the system and that also report the same Vulkan API version as the meta-layer itself before it loads the meta-layer. | The behavior is undefined and may result in crashes or corruption. | No | Meta-Layers |
| LLP_LOADER_11 | If the override meta-layer is present, a loader must load it and corresponding component layers after all other implicit layers have been added to the call chain. | The behavior is undefined and may result in crashes or corruption. | No | Override Meta-Layer |
| LLP_LOADER_12 | If the override meta-layer is present and has a blacklist of layers to remove, a loader must disable all layers listed in the blacklist. | The behavior is undefined and may result in crashes or corruption. | No | Override Meta-Layer |
| LLP_LOADER_13 | A loader must not load from user-defined paths (including the
use of either VK_LAYER_PATH or VK_ADD_LAYER_PATH
environment variables) when running elevated (Administrator/Super-user)
applications. This is for security reasons. |
The behavior is undefined and may result in computer security lapses, crashes or corruption. | No | Layer Discovery |