// Copyright (c) 2015-2016 The Khronos Group Inc. // Copyright notice at https://www.khronos.org/registry/speccopyright.html [[extended-functionality]] = Extended Functionality Additional functionality may: be provided by layers or extensions. A layer cannot: add or modify {apiname} commands, while an extension may: do so. There are two kinds of layers and extensions, instance and device. Instance layers and extensions are general purpose and do not depend on a specific device. Device layers and extensions operate on specific devices, and require a valid sname:VkDevice to be used. Instance extensions usually affect the operation of the API as a whole, whereas device layers and extensions tend to be hardware-specific. Examples of these might be: * Whole API validation is an example of a good instance layer. * Debug capabilities might make a good instance extension. * A layer that provides hardware-specific performance telemetry and analysis could be a device layer. * Functions to allow an application to use additional hardware features beyond the core would be a good candidate for a device extension. [[extended-functionality-layers]] == Layers When a layer is enabled, it inserts itself into the call chain for {apiname} 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 {apiname} 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 instance layers, call: include::../protos/vkEnumerateInstanceLayerProperties.txt[] * pname:pPropertyCount is the number of layer properties that can be returned in pname:pProperties. * pname:pProperties is an array of slink:VkLayerProperties structures in which properties of instance layers available on this implementation are returned. include::../validity/protos/vkEnumerateInstanceLayerProperties.txt[] To enable a instance layer, the name of the layer should be added to the pname:ppEnabledLayerNames member of slink:VkInstanceCreateInfo when creating a slink:VkInstance. To query the layers available to a given physical device, call: include::../protos/vkEnumerateDeviceLayerProperties.txt[] * pname:physicalDevice is the physical device that will be queried. * pname:pPropertyCount is the number of layer properties that can be returned in pname:pProperties. * pname:pProperties is an array of slink:VkLayerProperties structures in which properties of layers available on pname:physicalDevice are returned. include::../validity/protos/vkEnumerateDeviceLayerProperties.txt[] To enable a device layer, the name of the layer should be added to the pname:ppEnabledLayerNames member of slink:VkDeviceCreateInfo when creating a slink:VkDevice. Both commands will return an array of sname:VkLayerProperties of the respective instance or device layers present. Calling fname:vkEnumerateInstanceLayerProperties or fname:vkEnumerateDeviceLayerProperties with pname:pProperties set to `NULL` will return the number of supported layers in the basetype:uint32_t variable pointed to by pname:pPropertyCount. If pname:pProperties is not set to `NULL`, the query will fill the array and update pname:pPropertyCount to indicate the number of sname:VkLayerProperties filled in. If pname:pPropertyCount is smaller than the number of layers available, ename:VK_INCOMPLETE will be returned instead of ename:VK_SUCCESS, to indicate that not all the available properties were returned. The definition of sname:VkLayerProperties is: include::../structs/VkLayerProperties.txt[] * pname:layerName is a null-terminated string specifying the name of the layer. Use this name in the pname:ppEnabledLayerNames array in the sname:VkInstanceCreateInfo given to fname:vkCreateInstance to enable this layer in the instance. * pname:apiVersion is the {apiname} version the layer was written to, encoded as described in the <> section. * pname:implementationVersion is the version of this layer. It is an integer, increasing with backward compatible changes. * pname:description is a null-terminated string providing additional details that can: be used by the application to identify the layer. include::../validity/structs/VkLayerProperties.txt[] Loader implementations may: provide mechanisms outside the {apiname} API for enabling specific layers. Layers enabled through such a mechanism are _implicitly enabled_, while layers enabled by including the layer name in the pname:ppEnabledLayerNames member of slink:VkDeviceCreateInfo 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. [[extended-functionality-extensions]] == Extensions Extensions may: define new {apiname} commands, structures, and enumerants. For compilation purposes, the interfaces defined by registered extensions, including new structures and enumerants as well as function pointer types for new commands, are defined in the Khronos-supplied +vulkan.h+ together with the core API. However, commands defined by extensions maynot: be available for static linking - in which case function pointers to these commands should: be queried at runtime as described in <>. Extensions may: be provided by layers as well as by a {apiname} implementation. To query the available instance extensions, call: include::../protos/vkEnumerateInstanceExtensionProperties.txt[] * pname:pLayerName is either `NULL` or the name of a instance layer to retrieve extensions from. * pname:pPropertyCount is the number of extension properties that can be returned in pname:pProperties. * pname:pProperties is an array of slink:VkExtensionProperties structures in which properties of instance extensions available on this implementation are returned. include::../validity/protos/vkEnumerateInstanceExtensionProperties.txt[] Any instance extensions provided by the {apiname} implementation or by implicitly enabled layers, but not by explicitly enabled layers, are returned when pname:pLayerName parameter is `NULL`. When pname:pLayerName is the name of a layer, the instance extensions provided by that layer are returned. To enable a instance extension, the name of the extension should be added to the pname:ppEnabledExtensionNames member of slink:VkInstanceCreateInfo when creating a slink:VkInstance. To query the extensions available to a given physical device, call: include::../protos/vkEnumerateDeviceExtensionProperties.txt[] * pname:physicalDevice is the physical device that will be queried. * pname:pLayerName is either `NULL` or the name of a device layer to retrieve extensions from. * pname:pPropertyCount is the number of extension properties that can be returned in pname:pProperties. * pname:pProperties is an array of slink:VkExtensionProperties structures in which properties of extensions available on pname:physicalDevice are returned. include::../validity/protos/vkEnumerateDeviceExtensionProperties.txt[] Any device extensions provided by the {apiname} implementation or by implicitly enabled layers, but not by explicitly enabled layers, are returned when pname:pLayerName parameter is `NULL`. When pname:pLayerName is the name of a layer, the device extensions provided by that layer are returned. To enable a device layer, the name of the layer should be added to the pname:ppEnabledExtensionNames member of slink:VkDeviceCreateInfo when creating a slink:VkDevice. Both commands return an array of sname:VkExtensionProperties for any extensions implemented by the given pname:pLayerName. Set pname:pLayerName to `NULL` to query for extensions not part of any layer. Calling fname:vkEnumerateInstanceExtensionProperties or fname:vkEnumerateDeviceExtensionProperties with pname:pProperties set to `NULL` will return the count of extensions for the given layer in the basetype:uint32_t variable pointed to by pname:pPropertyCount. With pname:pProperties pointing to an array of sname:VkExtensionProperties, fname:vkEnumerateInstanceExtensionProperties and fname:vkEnumerateDeviceExtensionProperties will fill the array and update the count to indicate the number of sname:VkExtensionProperties filled in. If the provided count is smaller than the number of extensions available, ename:VK_INCOMPLETE will be returned instead of ename:VK_SUCCESS to indicate that not all the available properties were returned. The definition of sname:VkExtensionProperties is: include::../structs/VkExtensionProperties.txt[] * pname:extensionName is a null-terminated string specifying the name of the extension. * pname:specVersion is the version of this extension. It is an integer, incremented with backward compatible changes. include::../validity/structs/VkExtensionProperties.txt[]