mirror of
https://github.com/status-im/Vulkan-Docs.git
synced 2025-02-23 03:28:19 +00:00
1f875738fd
* Bump API patch number and header version number to 6 for this
update.
Github Issues:
* Define 'invocation group' for compute and graphics shaders. Cleanup
definition and use of 'workgroup', and add glossary entries (public
issue 1).
* Various minor editorial fixes (public issue 33).
* Clarify locations for block members in the
<<interfaces-iointerfaces-locations,Location Assignment>>
section (public issue 45).
* Editorial fixes for <<commandbuffer-allocation,Command Buffer
Allocation>> section (public issues 54, 59).
* Clarify behavior of depth test in the <<fragops-depth,Depth
Test>> section (public issues 80, 81).
* Remove discussion of return codes from
flink:vkGetPhysicalDeviceSparseImageFormatProperties and
flink:vkGetImageSparseMemoryRequirements, which don't return values
(public issue 82).
* Allow flink:vkCmdDrawIndirect and flink:vkCmdDrawIndexedIndirect
pname:drawCount of 0, as well as 1, when the multiDrawIndirect
feature is not supported (public issue 88).
* Remove confusing wording in the <<features-limits,Limits>>
section describing the slink:VkPhysicalDeviceLimits
pname:minTexelBufferOffsetAlignment,
pname:minUniformBufferOffsetAlignment, and
pname:minStorageBufferOffsetAlignment members as both minimums and
maximums (public issue 91).
* Clarified that only the RGB components should be affected in places
where sRGB is referred to in the spec, such as ASTC formats. Minor
re-wording to avoid "color space" when actively incorrect, now that
we refer to the Data Format Spec which actually makes a distinction
between color space and transfer function (public issue 94).
* Treat pname:pPropertyCount == 0 consistently in
flink:vkEnumerateInstanceLayerProperties and
flink:vkEnumerateDeviceLayerProperties (public issue 99)
* Cleanup minor editorial issues in chapters 14-17 (public issue 100).
* Clarify definition of flink:vkEnumerateInstanceExtensionProperties
and flink:vkEnumerateDeviceExtensionProperties (public issue 101).
* Define the flink:vkEnumerateInstanceExtensionProperties and
flink:vkEnumerateDeviceExtensionProperties pname:pLayerName
parameter to be a pointer to a null-terminated UTF-8 string (public
issue 101).
* Rearrange "Missing information" references in mandatory format
tables (public issue 101).
* Clarify that the enumerated extensions returned by
flink:vkEnumerateInstanceExtensionProperties and
flink:vkEnumerateDeviceExtensionProperties will only include
extensions provided by the platform or extensions implemented in
implicitly enabled layers (public issue 101).
* Miscellaneous editorial fixes. Include the Vulkan spec patch number
in the PDF title. Fix label on <<fig-non-strict-lines,Non
strict lines>> diagram. Use more easily distinguished symbols in
tables in the <<features-required-format-support,Required
Format Support>> section. Don't require FQDNs used as layer names be
encoded in lower case if not possible, in the
<<extensions-naming-conventions, Extension and Layer Naming
Conventions>> section (public issues 101, 119, 121).
Internal Issues:
* Fixed excessive spacing in tables in XHTML (internal issue 18).
* Clarify that ename:VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT
applies to secondary command buffers. Previously spec only referred
to the members of pname:pCommandBuffers being affected by this bit.
Added a separate slink:VkSubmitInfo Valid Usage restriction
specifying that ename:VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT
also applies to any secondary command buffers that are recorded into
the primary command buffers in pname:pCommandBuffers (internal issue
106).
* Clarify that slink:VkDeviceCreateInfo::pname:pEnabledFeatures can be
NULL (internal issue 117).
* Remove "the value of" where it is redundant (e.g. speaking of an API
parameter, struct member, or SPIR-V variable, but not when speaking
of color components) (internal issue 175).
* Forced patch version to always be 0 in the header. Add a
"VK_API_VERSION_<major>_<minor>" macro for people to use to do the
right thing. Add a VK_HEADER_VERSION which captures the header
release number independent of the spec patch number (internal issue
176).
* Correct description of
slink:VkPipelineShaderStageCreateInfo::pname:pName to "a pointer to
a null-terminated UTF-8 string" (internal issue #197).
Other Commits:
* Updated DataFormat spec reference to the new date for revision 5 of
that spec.
* Fixed KEEP option (to retain LaTeX intermediate files) in the
Makefile to be included when edited there, as well as set on the
command line.
* Reserve and add "VK_IMG_filter_cubic" to the registry, and implement
script functionality to add and remove validity from existing
functions. Includes schema and readme changes.
* Update GL_KHR_vulkan_glsl so push_constants do not have descriptor
sets.
188 lines
9.0 KiB
Plaintext
188 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 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[]
|