When a layer is enabled, it inserts itself into the call chain for Vulkan commands the layer is interested in. A common use of layers is to validate application behavior during development. For example, the implementation will not check that Vulkan enums used by the application fall within allowed ranges. Instead, a validation layer would do those checks and flag issues. This avoids a performance penalty during production use of the application because those layers would not be enabled in production.
Vulkan layers may wrap object handles (i.e. return a different handle value to the application than that generated by the implementation). This is generally discouraged, as it increases the probability of incompatibilities with new extensions. The validation layers wrap handles in order to track the proper use and destruction of each object. See the "Vulkan Loader Specification and Architecture Overview" document for additional information.
To query the available layers, call:
VkResult vkEnumerateInstanceLayerProperties( uint32_t* pPropertyCount, VkLayerProperties* pProperties);
pPropertyCount
is a pointer to an integer related to the number of
layer properties available or queried, as described below.
pProperties
is either NULL
or a pointer to an array of
VkLayerProperties
structures.
If pProperties
is NULL
, then the number of layer properties
available is returned in pPropertyCount
.
Otherwise, pPropertyCount
must point to a variable set by the user to
the number of elements in the pProperties
array, and on return the
variable is overwritten with the number of structures actually written to
pProperties
.
If pPropertyCount
is less than the number of layer properties
available, at most pPropertyCount
structures will be written.
If pPropertyCount
is smaller than the number of layers available,
VK_INCOMPLETE
will be returned instead of VK_SUCCESS
, to
indicate that not all the available layer properties were returned.
The list of available layers may change at any time due to actions outside
of the Vulkan implementation, so two calls to
vkEnumerateInstanceLayerProperties
with the same parameters may
return different results, or retrieve different pPropertyCount
values
or pProperties
contents.
Once an instance has been created, the layers enabled for that instance will
continue to be enabled and valid for the lifetime of that instance, even if
some of them become unavailable for future instances.
The VkLayerProperties
structure is defined as:
typedef struct VkLayerProperties { char layerName[VK_MAX_EXTENSION_NAME_SIZE]; uint32_t specVersion; uint32_t implementationVersion; char description[VK_MAX_DESCRIPTION_SIZE]; } VkLayerProperties;
layerName
is a null-terminated UTF-8 string specifying the name of
the layer.
Use this name in the ppEnabledLayerNames
array passed in the
VkInstanceCreateInfo
structure to enable this layer for an
instance.
specVersion
is the Vulkan version the layer was written to,
encoded as described in the API Version Numbers and Semantics section.
implementationVersion
is the version of this layer.
It is an integer, increasing with backward compatible changes.
description
is a null-terminated UTF-8 string providing additional
details that can be used by the application to identify the layer.
To enable a layer, the name of the layer should be added to the
ppEnabledLayerNames
member of VkInstanceCreateInfo
when creating
a VkInstance
.
Loader implementations may provide mechanisms outside the Vulkan API for
enabling specific layers.
Layers enabled through such a mechanism are implicitly enabled, while
layers enabled by including the layer name in the ppEnabledLayerNames
member of VkInstanceCreateInfo
are explicitly enabled.
Except where otherwise specified, implicitly enabled and explicitly enabled
layers differ only in the way they are enabled.
Explicitly enabling a layer that is implicitly enabled has no additional
effect.
Previous versions of this specification distinguished between instance and
device layers.
Instance layers were only able to intercept commands that operate on
VkInstance
and VkPhysicalDevice
, except they were not able to
intercept vkCreateDevice
.
Device layers were enabled for individual devices when they were created,
and could only intercept commands operating on that device or its child
objects.
Device-only layers are now deprecated, and this specification no longer distinguishes between instance and device layers. Layers are enabled during instance creation, and are able to intercept all commands operating on that instance or any of its child objects. At the time of deprecation there were no known device-only layers and no compelling reason to create one.
In order to maintain compatibility with implementations released prior to
device-layer deprecation, applications should still enumerate and enable
device layers.
The behavior of vkEnumerateDeviceLayerProperties
and valid usage of
the ppEnabledLayerNames
member of VkDeviceCreateInfo
maximizes
compatibility with applications written to work with the previous
requirements.
To enumerate device layers, call:
VkResult vkEnumerateDeviceLayerProperties( VkPhysicalDevice physicalDevice, uint32_t* pPropertyCount, VkLayerProperties* pProperties);
pPropertyCount
is a pointer to an integer related to the number of
layer properties available or queried.
pProperties
is either NULL
or a pointer to an array of
VkLayerProperties
structures.
If pProperties
is NULL
, then the number of layer properties
available is returned in pPropertyCount
.
Otherwise, pPropertyCount
must point to a variable set by the user to
the number of elements in the pProperties
array, and on return the
variable is overwritten with the number of structures actually written to
pProperties
.
If pPropertyCount
is less than the number of layer properties
available, at most pPropertyCount
structures will be written.
If pPropertyCount
is smaller than the number of layers available,
VK_INCOMPLETE
will be returned instead of VK_SUCCESS
, to
indicate that not all the available layer properties were returned.
The list of layers enumerated by vkEnumerateDeviceLayerProperties
must be exactly the sequence of layers enabled for the instance.
The members of VkLayerProperties
for each enumerated layer must be
the same as the properties when the layer was enumerated by
vkEnumerateInstanceLayerProperties
.
The ppEnabledLayerNames
and enabledLayerCount
members of
VkDeviceCreateInfo
are deprecated and their values must be ignored by
implementations.
However, for compatibility, only an empty list of layers or a list that
exactly matches the sequence enabled at instance creation time are valid,
and validation layers should issue diagnostics for other cases.
Regardless of the enabled layer list provided in VkDeviceCreateInfo
,
the sequence of layers active for a device will be exactly the sequence of
layers enabled when the parent instance was created.