Vulkan-Docs/doc/specs/vulkan/chapters/extensions.txt

// 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 a pointer to an integer related to the number of
    layer properties available or queried, as described below.
  * pname:pProperties is either `NULL` or a pointer to an array of
    slink:VkLayerProperties structures.

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 a pointer to an integer related to the number of
    layer properties available or queried, as described below.
  * pname:pProperties is either `NULL` or a pointer to an array of
    slink:VkLayerProperties structures.

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.

For both flink:vkEnumerateInstanceLayerProperties and
flink:vkEnumerateDeviceLayerProperties, if pname:pProperties is `NULL`, then
the number of layer properties available is returned in pname:pPropertyCount.
Otherwise, pname:pPropertyCount must: point to a variable set by the user to
the number of elements in the pname:pProperties array, and on return the
variable is overwritten with the number of structures actually written to
pname:pProperties. If pname:pPropertyCount is less than the
number of layer properties available, at most pname:pPropertyCount
structures will be written. 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 layer properties
were returned.

The definition of sname:VkLayerProperties is:

include::../structs/VkLayerProperties.txt[]

  * pname:layerName is a null-terminated UTF-8 string specifying the name of
    the layer. Use this name in the pname:ppEnabledLayerNames array passed
    in the slink:VkInstanceCreateInfo and slink:VkDeviceCreateInfo
    structures passed to flink:vkCreateInstance and flink:vkCreateDevice,
    respectively, to enable this layer for an instance or device.
  * pname:apiVersion is the {apiname} version the layer was written to,
    encoded as described in the <<fundamentals-versionnum,API Version
    Numbers and Semantics>> section.
  * pname:implementationVersion is the version of this layer. It is an
    integer, increasing with backward compatible changes.
  * pname:description is a null-terminated UTF-8 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 may: not be
available for static linking - in which case function pointers to these
commands should: be queried at runtime as described in
<<initialization-functionpointers>>. 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 a pointer to a null-terminated
    UTF-8 string naming the instance layer to retrieve extensions from.
  * pname:pPropertyCount is a pointer to an integer related to the number of
    extension properties available or queried, as described below.
  * pname:pProperties is either `NULL` or a pointer to an array of
    slink:VkExtensionProperties structures.

include::../validity/protos/vkEnumerateInstanceExtensionProperties.txt[]

When pLayerName parameter is NULL, only extensions provided by the {apiname}
implementation or by implicitly enabled layers are returned.
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 a pointer to a null-terminated
    UTF-8 string naming the device layer to retrieve extensions from.
  * pname:pPropertyCount is a pointer to an integer related to the number of
    extension properties available or queried, as described below.
  * pname:pProperties is either `NULL` or a pointer to an array of
    slink:VkExtensionProperties structures.

include::../validity/protos/vkEnumerateDeviceExtensionProperties.txt[]

When pLayerName parameter is NULL, only extensions provided by the {apiname}
implementation or by implicitly enabled layers are returned.
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.

For both flink:vkEnumerateInstanceExtensionProperties and
flink:vkEnumerateDeviceExtensionProperties, if pname:pProperties is `NULL`,
then the number of extensions properties available is returned in
pname:pPropertyCount. Otherwise, pname:pPropertyCount must: point to a
variable set by the user to the number of elements in the pname:pProperties
array, and on return the variable is overwritten with the number of
structures actually written to pname:pProperties. If
pname:pPropertyCount is less than the number of extension properties
available, at most pname:pPropertyCount structures will be written. If
pname:pPropertyCount 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[]