194 lines
9.0 KiB
Plaintext
194 lines
9.0 KiB
Plaintext
|
// 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 <<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 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
|
||
|
|
<<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 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[]
|