mirror of
https://github.com/status-im/Vulkan-Docs.git
synced 2025-01-27 06:34:53 +00:00
cebb71d062
* Bump API patch number and header version number to 50 for this update.
Github Issues:
* Fix numerous minor issues with the VK_EXT_debug_report extension (public
issues 478, 483, 486, 489, 490).
Internal Issues:
* Update flink:vkAllocateDescriptorSets to specify conditions under which
to return ename:VK_ERROR_FRAGMENTED_POOL or
ename:VK_ERROR_OUT_OF_POOL_MEMORY instead of
out-of-host/out-of-device-memory, and improve the
<<fundamentals-errorcodes, description of those errors (internal issue
654).
* Add a NOTE documenting that flink:vkAcquireNextImageKHR can only signal
a single semaphore, and how to deal with that when multiple physical
devices in a logical device need to wait on it (internal issue 730).
* Improve description of pname:pNext chains of
slink:VkPhysicalDeviceImageFormatInfo2KHR and
slink:VkImageFormatProperties2KHR (internal issue 814).
* Clean up math markup issues in the <<textures, Image Operations>>
chapter (internal issue 818).
* Update validusage target to use more robust code for preprocessing, by
making direct use of Asciidoctor's preprocessor. Added uniqueItems check
to JSON vu schema and add clean_validusage target (internal issue 826).
* Update style guide to prohibit writing non-self-contained (on a single
bullet point) Valid Usage statements, and modify offending Valid Usage
statements in the Specification to match, to assist with automatic
extraction for the validation layers (internal issue 828).
* Add ename:VK_VALIDATION_CHECK_SHADERS_EXT to elink:VkValidationCheckEXT
of the `VK_EXT_validation_flags` extension, to selectively disable
shader validation.
* Remove duplicate valid usage statement for slink:VkImageMemoryBarrier.
* Modify reflow.py script to place VUID tag anchors standalone on a line
following their corresponding bullet point, and reflow the spec text
accordingly (this had been pending since the initial tag deployment).
New Extensions:
* `VK_AMD_texture_gather_bias_lod`
338 lines
16 KiB
Plaintext
338 lines
16 KiB
Plaintext
// Copyright (c) 2015-2017 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 Vulkan commands, while an extension may: do
|
|
so.
|
|
|
|
The set of layers to enable is specified when creating an instance, and
|
|
those layers are able to intercept any Vulkan command dispatched to that
|
|
instance or any of its child objects.
|
|
|
|
Extensions can operate at either the instance or device _extension scope_.
|
|
Enabled instance extensions are able to affect the operation of the instance
|
|
and any of its child objects, while device extensions may: only be available
|
|
on a subset of physical devices, must: be individually enabled per-device,
|
|
and only affect the operation of the devices where they are enabled.
|
|
|
|
Examples of these might be:
|
|
|
|
* Whole API validation is an example of a layer.
|
|
* Debug capabilities might make a good instance extension.
|
|
* A layer that provides hardware-specific performance telemetry and
|
|
analysis could be a layer that is only active for devices created from
|
|
compatible physical devices.
|
|
* 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 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 <<LoaderAndValidationLayers, "Vulkan Loader Specification and
|
|
Architecture Overview">> document for additional information.
|
|
|
|
// refBegin vkEnumerateInstanceLayerProperties Returns up to requested number of global layer properties
|
|
|
|
To query the available layers, call:
|
|
|
|
include::../api/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.
|
|
|
|
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 list of available layers may change at any time due to actions outside
|
|
of the Vulkan implementation, so two calls to
|
|
fname:vkEnumerateInstanceLayerProperties with the same parameters may:
|
|
return different results, or retrieve different pname:pPropertyCount values
|
|
or pname: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.
|
|
|
|
include::../validity/protos/vkEnumerateInstanceLayerProperties.txt[]
|
|
|
|
// refBegin VkLayerProperties Structure specifying layer properties
|
|
|
|
The sname:VkLayerProperties structure is defined as:
|
|
|
|
include::../api/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 structure to enable this layer for an
|
|
instance.
|
|
* pname:specVersion is the Vulkan 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[]
|
|
|
|
To enable a layer, the name of the layer should: be added to the
|
|
pname:ppEnabledLayerNames member of slink:VkInstanceCreateInfo when creating
|
|
a sname: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 pname:ppEnabledLayerNames
|
|
member of slink: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.
|
|
|
|
|
|
[[extended-functionality-device-layer-deprecation]]
|
|
=== Device Layer Deprecation
|
|
|
|
Previous versions of this specification distinguished between instance and
|
|
device layers.
|
|
Instance layers were only able to intercept commands that operate on
|
|
sname:VkInstance and sname:VkPhysicalDevice, except they were not able to
|
|
intercept flink: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 fname:vkEnumerateDeviceLayerProperties and valid usage of
|
|
the pname:ppEnabledLayerNames member of sname:VkDeviceCreateInfo maximizes
|
|
compatibility with applications written to work with the previous
|
|
requirements.
|
|
|
|
// refBegin vkEnumerateDeviceLayerProperties Returns properties of available physical device layers
|
|
|
|
To enumerate device layers, call:
|
|
|
|
include::../api/protos/vkEnumerateDeviceLayerProperties.txt[]
|
|
|
|
* pname:pPropertyCount is a pointer to an integer related to the number of
|
|
layer properties available or queried.
|
|
* pname:pProperties is either `NULL` or a pointer to an array of
|
|
slink:VkLayerProperties structures.
|
|
|
|
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 list of layers enumerated by fname:vkEnumerateDeviceLayerProperties
|
|
must: be exactly the sequence of layers enabled for the instance.
|
|
The members of sname:VkLayerProperties for each enumerated layer must: be
|
|
the same as the properties when the layer was enumerated by
|
|
fname:vkEnumerateInstanceLayerProperties.
|
|
|
|
include::../validity/protos/vkEnumerateDeviceLayerProperties.txt[]
|
|
|
|
The pname:ppEnabledLayerNames and pname:enabledLayerCount members of
|
|
sname: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 sname:VkDeviceCreateInfo,
|
|
the sequence of layers active for a device will be exactly the sequence of
|
|
layers enabled when the parent instance was created.
|
|
|
|
|
|
[[extended-functionality-extensions]]
|
|
== Extensions
|
|
|
|
Extensions may: define new Vulkan 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 Vulkan implementation.
|
|
|
|
Because extensions may: extend or change the behavior of the Vulkan API,
|
|
extension authors should: add support for their extensions to the Khronos
|
|
validation layers.
|
|
This is especially important for new commands whose parameters have been
|
|
wrapped by the validation layers.
|
|
See the <<LoaderAndValidationLayers, "Vulkan Loader Specification and
|
|
Architecture Overview">> document for additional information.
|
|
|
|
// refBegin vkEnumerateInstanceExtensionProperties Returns up to requested number of global extension properties
|
|
|
|
To query the available instance extensions, call:
|
|
|
|
include::../api/protos/vkEnumerateInstanceExtensionProperties.txt[]
|
|
|
|
* pname:pLayerName is either `NULL` or a pointer to a null-terminated
|
|
UTF-8 string naming the 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.
|
|
|
|
When pname:pLayerName parameter is NULL, only extensions provided by the
|
|
Vulkan 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.
|
|
|
|
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.
|
|
|
|
Because the list of available layers may change externally between calls to
|
|
pname:vkEnumerateInstanceExtensionProperties, two calls may retrieve
|
|
different results if a pname:pLayerName is available in one call but not in
|
|
another.
|
|
The extensions supported by a layer may also change between two calls, e.g.
|
|
if the layer implementation is replaced by a different version between those
|
|
calls.
|
|
|
|
include::../validity/protos/vkEnumerateInstanceExtensionProperties.txt[]
|
|
|
|
To enable an instance extension, the name of the extension should: be added
|
|
to the pname:ppEnabledExtensionNames member of slink:VkInstanceCreateInfo
|
|
when creating a sname:VkInstance.
|
|
|
|
Enabling an extension does not change behavior of functionality exposed by
|
|
the core Vulkan API or any other extension, other than making valid the use
|
|
of the commands, enums and structures defined by that extension.
|
|
|
|
// refBegin vkEnumerateDeviceExtensionProperties Returns properties of available physical device extensions
|
|
|
|
To query the extensions available to a given physical device, call:
|
|
|
|
include::../api/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 layer to retrieve extensions from.
|
|
* pname:pPropertyCount is a pointer to an integer related to the number of
|
|
extension properties available or queried, and is treated in the same
|
|
fashion as the
|
|
flink:vkEnumerateInstanceExtensionProperties::pname:pPropertyCount
|
|
parameter.
|
|
* pname:pProperties is either `NULL` or a pointer to an array of
|
|
slink:VkExtensionProperties structures.
|
|
|
|
When pname:pLayerName parameter is NULL, only extensions provided by the
|
|
Vulkan 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.
|
|
|
|
include::../validity/protos/vkEnumerateDeviceExtensionProperties.txt[]
|
|
|
|
// refBegin VkExtensionProperties Structure specifying a extension properties
|
|
|
|
The sname:VkExtensionProperties structure is defined as:
|
|
|
|
include::../api/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[]
|
|
|
|
|
|
[[extended-functionality-instance-extensions-and-devices]]
|
|
=== Instance Extensions and Device Extensions
|
|
|
|
This section provides some guidelines and rules for when to expose new
|
|
functionality as an instance extension, as a device extension, or as both.
|
|
The decision depends on the scope of the new functionality; such as whether
|
|
it extends instance-level or device-level functionality.
|
|
All Vulkan commands, structures, and enumerants are considered either
|
|
instance-level, physical-device-level, or device-level.
|
|
|
|
Commands that are dispatched from instances (sname:VkInstance) are
|
|
considered instance-level commands.
|
|
Any structure, enumerated type, and enumerant that is used with
|
|
instance-level commands are considered instance-level objects.
|
|
New instance-level extension functionality must: be structured within an
|
|
instance extension.
|
|
|
|
Any command or object that must: be used after calling flink:vkCreateDevice
|
|
is a device-level command or object.
|
|
These objects include all children of sname:VkDevice objects, such as queues
|
|
(sname:VkQueue) and command buffers (sname:VkCommandBuffer).
|
|
New device-level extension functionality may: be structured within a device
|
|
extension.
|
|
|
|
Commands that are dispatched from physical devices (sname:VkPhysicalDevice)
|
|
are considered physical-device-level commands.
|
|
Any structure, enumerated type, and enumerant that is used with
|
|
physical-device-level commands, and not used with instance-level commands,
|
|
are considered physical-device-level objects.
|
|
Vulkan 1.0 requires all new physical-device-level extension functionality to
|
|
be structured within an instance extension.
|
|
ifdef::VK_KHR_get_physical_device_properties2[]
|
|
In order to avoid using an instance extension, which often requires loader
|
|
support, the +VK_KHR_get_physical_device_properties2+ extension allows
|
|
physical-device-level extension functionality to be implemented within
|
|
device extensions (which must: depend on the
|
|
+VK_KHR_get_physical_device_properties2+ extension).
|
|
endif::VK_KHR_get_physical_device_properties2[]
|