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.
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 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.