754 lines
30 KiB
Plaintext
754 lines
30 KiB
Plaintext
// Copyright (c) 2015-2019 Khronos Group. This work is licensed under a
|
|
// Creative Commons Attribution 4.0 International License; see
|
|
// http://creativecommons.org/licenses/by/4.0/
|
|
|
|
[[extendingvulkan]]
|
|
= Extending Vulkan
|
|
|
|
New functionality may: be added to Vulkan via either new extensions or new
|
|
versions of the core, or new versions of an extension in some cases.
|
|
|
|
This chapter describes how Vulkan is versioned, how compatibility is
|
|
affected between different versions, and compatibility rules that are
|
|
followed by the Vulkan Working Group.
|
|
|
|
|
|
[[extendingvulkan-instanceanddevicefunctionality]]
|
|
== Instance and Device Functionality
|
|
|
|
Commands that enumerate instance properties, or that accept a
|
|
slink:VkInstance object as a parameter, are considered instance-level
|
|
functionality.
|
|
Commands
|
|
ifdef::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[]
|
|
that enumerate physical device properties, or
|
|
endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[]
|
|
that accept a slink:VkDevice object or any of a device's child objects as a
|
|
parameter, are considered device-level functionality.
|
|
|
|
ifdef::VK_VERSION_1_1[]
|
|
[NOTE]
|
|
.Note
|
|
====
|
|
Applications usually interface to Vulkan using a loader that implements only
|
|
instance-level functionality, passing device-level functionality to
|
|
implementations of the full Vulkan API on the system.
|
|
In some circumstances, as these may be implemented independently, it's
|
|
possible that the loader and device implementations on a given installation
|
|
will support different versions.
|
|
To allow for this and call out when it happens, the Vulkan specification
|
|
enumerates device and instance level functionality separately - they have
|
|
<<extendingvulkan-coreversions-queryingversionsupport,independent version
|
|
queries>>.
|
|
====
|
|
endif::VK_VERSION_1_1[]
|
|
|
|
[NOTE]
|
|
.Note
|
|
====
|
|
Vulkan 1.0 initially specified new physical device enumeration functionality
|
|
as instance-level, requiring it to be included in an instance extension.
|
|
As the capabilities of device-level functionality require discovery via
|
|
physical device enumeration, this led to the situation where many device
|
|
extensions required an instance extension as well.
|
|
To alleviate this extra work, `VK_KHR_get_physical_device_properties2` (and
|
|
subsequently Vulkan 1.1) redefined device-level functionality to include
|
|
physical device enumeration.
|
|
====
|
|
|
|
|
|
[[extendingvulkan-coreversions]]
|
|
== Core Versions
|
|
|
|
The Vulkan Specification is regularly updated with bug fixes and
|
|
clarifications.
|
|
Occasionally new functionality is added to the core and at some point it is
|
|
expected that there will be a desire to perform a large, breaking change to
|
|
the API.
|
|
In order to indicate to developers how and when these changes are made to
|
|
the specification, and to provide a way to identify each set of changes, the
|
|
Vulkan API maintains a version number.
|
|
|
|
|
|
[[extendingvulkan-coreversions-versionnumbers]]
|
|
=== Version Numbers
|
|
|
|
The Vulkan version number comprises three parts indicating the major, minor
|
|
and patch version of the Vulkan API Specification.
|
|
|
|
The _major version_ indicates a significant change in the API, which will
|
|
encompass a wholly new version of the specification.
|
|
|
|
The _minor version_ indicates the incorporation of new functionality into
|
|
the core specification.
|
|
|
|
The _patch version_ indicates bug fixes, clarifications, and language
|
|
improvements have been incorporated into the specification.
|
|
|
|
Compatibility guarantees made about versions of the API sharing any of the
|
|
same version numbers are documented in
|
|
<<extendingvulkan-compatibility-coreversions>>
|
|
|
|
The version number is used in several places in the API.
|
|
In each such use, the version numbers are packed into a 32-bit integer as
|
|
follows:
|
|
|
|
* The major version is a 10-bit integer packed into bits 31-22.
|
|
* The minor version number is a 10-bit integer packed into bits 21-12.
|
|
* The patch version number is a 12-bit integer packed into bits 11-0.
|
|
|
|
[open,refpage='VK_VERSION_MAJOR',desc='Extract API major version number',type='defines']
|
|
--
|
|
|
|
dname:VK_VERSION_MAJOR extracts the API major version number from a packed
|
|
version number:
|
|
|
|
include::../api/defines/VK_VERSION_MAJOR.txt[]
|
|
|
|
--
|
|
|
|
[open,refpage='VK_VERSION_MINOR',desc='Extract API minor version number',type='defines']
|
|
--
|
|
|
|
dname:VK_VERSION_MINOR extracts the API minor version number from a packed
|
|
version number:
|
|
|
|
include::../api/defines/VK_VERSION_MINOR.txt[]
|
|
|
|
--
|
|
|
|
[open,refpage='VK_VERSION_PATCH',desc='Extract API patch version number',type='defines']
|
|
--
|
|
|
|
dname:VK_VERSION_PATCH extracts the API patch version number from a packed
|
|
version number:
|
|
|
|
include::../api/defines/VK_VERSION_PATCH.txt[]
|
|
|
|
--
|
|
|
|
[open,refpage='VK_MAKE_VERSION',desc='Construct an API version number',type='defines',xrefs='VkApplicationInfo vkCreateInstance']
|
|
--
|
|
|
|
dname:VK_MAKE_VERSION constructs an API version number.
|
|
|
|
include::../api/defines/VK_MAKE_VERSION.txt[]
|
|
|
|
* pname:major is the major version number.
|
|
* pname:minor is the minor version number.
|
|
* pname:patch is the patch version number.
|
|
--
|
|
|
|
[open,refpage='VK_API_VERSION_1_0',desc='Return API version number for Vulkan 1.0',type='defines',xrefs='vkCreateInstance vkGetPhysicalDeviceProperties']
|
|
--
|
|
|
|
dname:VK_API_VERSION_1_0 returns the API version number for Vulkan 1.0.0.
|
|
|
|
include::../api/defines/VK_API_VERSION_1_0.txt[]
|
|
|
|
--
|
|
|
|
ifdef::VK_VERSION_1_1[]
|
|
[open,refpage='VK_API_VERSION_1_1',desc='Return API version number for Vulkan 1.1',type='defines',xrefs='vkCreateInstance vkGetPhysicalDeviceProperties']
|
|
--
|
|
|
|
dname:VK_API_VERSION_1_1 returns the API version number for Vulkan 1.1.0.
|
|
|
|
include::../api/defines/VK_API_VERSION_1_1.txt[]
|
|
|
|
--
|
|
endif::VK_VERSION_1_1[]
|
|
|
|
|
|
[[extendingvulkan-coreversions-queryingversionsupport]]
|
|
=== Querying Version Support
|
|
|
|
ifndef::VK_VERSION_1_1[]
|
|
[NOTE]
|
|
.Note
|
|
====
|
|
In Vulkan 1.0, there is no mechanism to detect the separate versions of
|
|
<<extendingvulkan-instanceanddevicefunctionality,instance-level and
|
|
device-level functionality>> supported.
|
|
However, the fname:vkEnumerateInstanceVersion command was added in Vulkan
|
|
1.1 to determine the supported version of instance-level functionality -
|
|
querying for this function via flink:vkGetInstanceProcAddr will return
|
|
`NULL` on implementations that only support Vulkan 1.0 functionality.
|
|
For more information on this, please refer to the Vulkan 1.1 specification.
|
|
====
|
|
endif::VK_VERSION_1_1[]
|
|
|
|
ifdef::VK_VERSION_1_1[]
|
|
The version of instance-level functionality can be queried by calling
|
|
flink:vkEnumerateInstanceVersion.
|
|
endif::VK_VERSION_1_1[]
|
|
|
|
The version of device-level functionality can be queried by calling
|
|
flink:vkGetPhysicalDeviceProperties
|
|
ifdef::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[]
|
|
or flink:vkGetPhysicalDeviceProperties2,
|
|
endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[]
|
|
and is returned in slink:VkPhysicalDeviceProperties::pname:apiVersion,
|
|
encoded as described in <<extendingvulkan-coreversions-versionnumbers>>.
|
|
|
|
|
|
[[extendingvulkan-layers]]
|
|
== Layers
|
|
|
|
When a layer is enabled, it inserts itself into the call chain for Vulkan
|
|
commands the layer is interested in.
|
|
Layers can: be used for a variety of tasks that extend the base behavior of
|
|
Vulkan beyond what is required by the specification - such as call logging,
|
|
tracing, validation, or providing additional extensions.
|
|
|
|
[NOTE]
|
|
.Note
|
|
====
|
|
For example, an implementation is not expected to check that the value of
|
|
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.
|
|
====
|
|
|
|
[NOTE]
|
|
.Note
|
|
====
|
|
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 <<LoaderAndLayerInterface, "`Vulkan Loader Specification and
|
|
Architecture Overview`">> document for additional information.
|
|
====
|
|
|
|
[open,refpage='vkEnumerateInstanceLayerProperties',desc='Returns up to requested number of global layer properties',type='protos']
|
|
--
|
|
|
|
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[]
|
|
--
|
|
|
|
[open,refpage='VkLayerProperties',desc='Structure specifying layer properties',type='structs']
|
|
--
|
|
|
|
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 <<extendingvulkan-coreversions-versionnumbers>>.
|
|
* 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.
|
|
|
|
|
|
[[extendingvulkan-layers-devicelayerdeprecation]]
|
|
=== 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.
|
|
|
|
[open,refpage='vkEnumerateDeviceLayerProperties',desc='Returns properties of available physical device layers',type='protos']
|
|
--
|
|
|
|
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.
|
|
|
|
|
|
[[extendingvulkan-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_core.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 <<LoaderAndLayerInterface, "`Vulkan Loader Specification and
|
|
Architecture Overview`">> document for additional information.
|
|
|
|
[NOTE]
|
|
.Note
|
|
====
|
|
Valid Usage sections for individual commands and structures do not currently
|
|
contain which extensions have to be enabled in order to make their use
|
|
valid, although it might do so in the future.
|
|
It is defined only in the <<fundamentals-validusage-extensions>> section.
|
|
====
|
|
|
|
|
|
=== Instance Extensions
|
|
|
|
Instance extensions add new
|
|
<<extendingvulkan-instanceanddevicefunctionality,instance-level
|
|
functionality>> to the API, outside of the core specification.
|
|
|
|
[open,refpage='vkEnumerateInstanceExtensionProperties',desc='Returns up to requested number of global extension properties',type='protos']
|
|
--
|
|
|
|
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
|
|
flink: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.
|
|
|
|
Implementations must: not advertise any pair of extensions that cannot be
|
|
enabled together due to behavioral differences, or any extension that cannot
|
|
be enabled against the advertised version.
|
|
|
|
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.
|
|
|
|
[NOTE]
|
|
.Note
|
|
====
|
|
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.
|
|
====
|
|
|
|
|
|
=== Device Extensions
|
|
|
|
Device extensions add new
|
|
<<extendingvulkan-instanceanddevicefunctionality,device-level
|
|
functionality>> to the API, outside of the core specification.
|
|
|
|
[open,refpage='vkEnumerateDeviceExtensionProperties',desc='Returns properties of available physical device extensions',type='protos']
|
|
--
|
|
|
|
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.
|
|
|
|
Implementations must: not advertise any pair of extensions that cannot be
|
|
enabled together due to behavioral differences, or any extension that cannot
|
|
be enabled against the advertised version.
|
|
|
|
include::../validity/protos/vkEnumerateDeviceExtensionProperties.txt[]
|
|
--
|
|
|
|
[open,refpage='VkExtensionProperties',desc='Structure specifying an extension properties',type='structs']
|
|
--
|
|
|
|
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[]
|
|
--
|
|
|
|
[[extendingvulkan-extensions-extensiondependencies]]
|
|
== Extension Dependencies
|
|
|
|
Some extensions are dependent on other extensions to function.
|
|
To enable extensions with dependencies, such _required extensions_ must:
|
|
also be enabled through the same API mechanisms when creating an instance
|
|
with flink:vkCreateInstance or a device with flink:vkCreateDevice.
|
|
Each extension which has such dependencies documents them in the
|
|
<<extensions, appendix summarizing that extension>>.
|
|
|
|
If an extension is supported (as queried by
|
|
flink:vkEnumerateInstanceExtensionProperties or
|
|
flink:vkEnumerateDeviceExtensionProperties), then _required extensions_ of
|
|
that extension must: also be supported for the same instance or physical
|
|
device.
|
|
|
|
Any device extension that has an instance extension dependency that is not
|
|
enabled by flink:vkCreateInstance is considered to be unsupported, hence it
|
|
must: not be returned by flink:vkEnumerateDeviceExtensionProperties for any
|
|
slink:VkPhysicalDevice child of the instance.
|
|
|
|
|
|
== Compatibility Guarantees (Informative)
|
|
|
|
This section is marked as informal as there is no binding responsibility on
|
|
implementations of the Vulkan API - these guarantees are however a contract
|
|
between the Vulkan Working Group and developers using this Specification.
|
|
|
|
|
|
[[extendingvulkan-compatibility-coreversions]]
|
|
=== Core Versions
|
|
|
|
Each of the <<extendingvulkan-coreversions,major, minor, and patch
|
|
versions>> of the Vulkan specification provide different compatibility
|
|
guarantees.
|
|
|
|
|
|
==== Patch Versions
|
|
|
|
A difference in the patch version indicates that a set of bug fixes or
|
|
clarifications have been made to the Specification.
|
|
Informative enums returned by Vulkan commands that won't affect the runtime
|
|
behavior of a valid application may be added in a patch version (e.g.
|
|
elink:VkVendorId).
|
|
|
|
The specification's patch version is strictly increasing for a given major
|
|
version of the specification; any change to a specification as described
|
|
above will result in the patch version being increased by 1.
|
|
Patch versions are applied to all minor versions, even if a given minor
|
|
version is not affected by the provoking change.
|
|
|
|
Specifications with different patch versions but the same major and minor
|
|
version are _fully compatible_ with each other - such that a valid
|
|
application written against one will work with an implementation of another.
|
|
|
|
[NOTE]
|
|
.Note
|
|
====
|
|
If a patch version includes a bug fix or clarification that could have a
|
|
significant impact on developer expectations, these will be highlighted in
|
|
the change log.
|
|
Generally the Vulkan Working Group tries to avoid these kinds of changes,
|
|
instead fixing them in either an extension or core version.
|
|
====
|
|
|
|
|
|
==== Minor Versions
|
|
|
|
Changes in the minor version of the specification indicate that new
|
|
functionality has been added to the core specification.
|
|
This will usually include new interfaces in the header, and may: also
|
|
include behavior changes and bug fixes.
|
|
Core functionality may: be deprecated in a minor version, but will not be
|
|
obsoleted or removed.
|
|
|
|
The specification's minor version is strictly increasing for a given major
|
|
version of the specification; any change to a specification as described
|
|
above will result in the minor version being increased by 1.
|
|
Changes that can be accomodated in a patch version will not increase the
|
|
minor version.
|
|
|
|
Specifications with a lower minor version are _backwards compatible_ with an
|
|
implementation of a specification with a higher minor version for core
|
|
functionality and extensions issued with the KHR vendor tag.
|
|
Vendor and multi-vendor extensions are not guaranteed to remain functional
|
|
across minor versions, though in general they are with few exceptions - see
|
|
<<extendingvulkan-compatibility-obsoletion>> for more information.
|
|
|
|
|
|
==== Major Versions
|
|
|
|
A difference in the major version of specifications indicates a large set of
|
|
changes which will likely include interface changes, behavioral changes,
|
|
removal of <<extendingvulkan-compatibility-deprecation,deprecated
|
|
functionality>>, and the modification, addition, or replacement of other
|
|
functionality.
|
|
|
|
The specification's major version is monotonically increasing; any change to
|
|
the specification as described above will result in the major version being
|
|
increased.
|
|
Changes that can be accomodated in a patch or minor version will not
|
|
increase the major version.
|
|
|
|
The Vulkan Working Group intends to only issue a new major version of the
|
|
Specification in order to realise significant improvements to the Vulkan API
|
|
that will necessarily require breaking compatibility.
|
|
|
|
A new major version will likely include a wholly new version of the
|
|
specification to be issued - which could include an overhaul of the
|
|
versioning semantics for the minor and patch versions.
|
|
The patch and minor versions of a specification are therefore not meaningful
|
|
across major versions.
|
|
If a major version of the specification includes similar versioning
|
|
semantics, it is expected that the the patch and minor version will be reset
|
|
to 0 for that major version.
|
|
|
|
|
|
[[extendingvulkan-compatibility-extensions]]
|
|
=== Extensions
|
|
|
|
A KHR extension must: be able to be enabled alongside any other KHR
|
|
extension, and for any minor or patch version of the core Specification
|
|
beyond the minimum version it requires.
|
|
A multi-vendor extension should: be able to be enabled alongside any KHR
|
|
extension or other multi-vendor extension, and for any minor or patch
|
|
version of the core Specification beyond the minimum version it requires.
|
|
A vendor extension should: be able to be enabled alongside any KHR
|
|
extension, multi-vendor extension, or other vendor extension from the same
|
|
vendor, and for any minor or patch version of the core Specification beyond
|
|
the minimum version it requires.
|
|
A vendor extension may: be able to be enabled alongside vendor extensions
|
|
from another vendor.
|
|
|
|
The one other exception to this is if a vendor or multi-vendor extension is
|
|
<<extendingvulkan-compatibility-obsoletion, made obsolete>> by either a core
|
|
version or another extension, which will be highlighted in the
|
|
<<extensions,extension appendix>>.
|
|
|
|
|
|
[[extendingvulkan-compatibility-promotion]]
|
|
==== Promotion
|
|
|
|
Extensions, or features of an extension, may: be promoted to a new
|
|
<<versions,core version of the API>>, or a newer extension which an equal or
|
|
greater number of implementors are in favour of.
|
|
|
|
When extension functionality is promoted, minor changes may: be introduced,
|
|
limited to the following:
|
|
|
|
* Naming
|
|
* Non-intrusive parameters changes
|
|
* <<features-features,Feature advertisement/enablement>>
|
|
* Combining structure parameters into larger structures
|
|
* Author ID suffixes changed or removed
|
|
|
|
[NOTE]
|
|
.Note
|
|
====
|
|
If extension functionality is promoted, there's no guarantee of direct
|
|
compatibility, however it should require little effort to port code from the
|
|
original feature to the promoted one.
|
|
|
|
The Vulkan Working Group endeavours to ensure that larger changes are marked
|
|
as either <<extendingvulkan-compatibility-deprecation, deprecated>> or
|
|
<<extendingvulkan-compatibility-obsoletion, obsoleted>> as appropriate, and
|
|
can do so retroactively if necessary.
|
|
====
|
|
|
|
Extensions that are promoted are listed as being promoted in their extension
|
|
appendices, with reference to where they were promoted to.
|
|
|
|
|
|
[[extendingvulkan-compatibility-deprecation]]
|
|
==== Deprecation
|
|
|
|
Extensions may: be marked as deprecated when the intended use cases either
|
|
become irrelevant or can be solved in other ways.
|
|
Generally, a new feature will become available to solve the use case in
|
|
another extension or core version of the API, but it is not guaranteed.
|
|
|
|
[NOTE]
|
|
.Note
|
|
====
|
|
Features that are intended to replace deprecated functionality have no
|
|
guarantees of compatibility, and applications may require drastic
|
|
modification in order to make use of the new features.
|
|
====
|
|
|
|
Extensions that are deprecated are listed as being deprecated in their
|
|
extension appendices, with an explanation of the deprecation and any
|
|
features that are relevant.
|
|
|
|
|
|
[[extendingvulkan-compatibility-obsoletion]]
|
|
==== Obsoletion
|
|
|
|
Occasionally, an extension will be marked as obsolete if a new version of
|
|
the core API or a new extension is fundamentally incompatible with it.
|
|
An obsoleted extension must: not be used with the extension or core version
|
|
that obsoleted it.
|
|
|
|
Extensions that are obsoleted are listed as being obsoleted in their
|
|
extension appendices, with reference to what they were obsoleted by.
|
|
|
|
|
|
[[extendingvulkan-compatibility-aliases]]
|
|
==== Aliases
|
|
|
|
When an extension is promoted or deprecated by a newer feature, some or all
|
|
of its functionality may: be replicated into the newer feature.
|
|
Rather than duplication of all the documentation and definitions, the
|
|
specification instead identifies the identical commands and types as
|
|
_aliases_ of one another.
|
|
Each alias is mentioned together with the definition it aliases, with the
|
|
older aliases marked as "equivalents".
|
|
Each alias of the same command has identical behavior, and each alias of the
|
|
same type has identical meaning - they can be used interchangably in an
|
|
application with no compatibility issues.
|
|
|
|
[NOTE]
|
|
.Note
|
|
====
|
|
For promoted types, the aliased extension type is semantically identical to
|
|
the new core type.
|
|
The C99 headers simply `typedef` the older aliases to the promoted types.
|
|
|
|
For promoted command aliases, however, there are two separate entry point
|
|
definitions, due to the fact that the C99 ABI has no way to alias command
|
|
definitions without resorting to macros.
|
|
Calling via either entry point definition will produce identical behavior
|
|
within the bounds of the specification, and should still invoke the same
|
|
entry point in the implementation.
|
|
Debug tools may use separate entry points with different debug behavior; to
|
|
write the appropriate command name to an output log, for instance.
|
|
====
|