2016-07-11 01:13:41 +00:00
|
|
|
// Copyright (c) 2016 The Khronos Group Inc.
|
|
|
|
|
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
|
|
|
|
|
|
|
|
|
|
[appendix]
|
|
|
|
|
[[boilerplate]]
|
|
|
|
|
= API Boilerplate
|
|
|
|
|
|
|
|
|
|
This appendix defines Vulkan API features that are infrastructure required
|
|
|
|
|
for a complete functional description of Vulkan, but do not logically belong
|
|
|
|
|
elsewhere in the Specification.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
[[boilerplate-sType]]
|
|
|
|
|
== Structure Types
|
|
|
|
|
|
|
|
|
|
// refBegin VkStructureType Vulkan structure types (pname:stype)
|
|
|
|
|
|
|
|
|
|
Vulkan structures containing elink:VkStructureType::pname:sType members
|
|
|
|
|
must: have a value of pname:sType matching the type of the structure, as
|
|
|
|
|
described more fully in <<fundamentals-validusage-sType,Valid Usage for
|
|
|
|
|
Structure Types>>. Structure types supported by the Vulkan API include:
|
|
|
|
|
|
|
|
|
|
include::../enums/VkStructureType.txt[]
|
|
|
|
|
|
|
|
|
|
// refEnd VkStructureType
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
[[boilerplate-flags]]
|
|
|
|
|
== Flag Types
|
|
|
|
|
|
|
|
|
|
Vulkan flag types are all bitmasks aliasing the base type basetype:VkFlags and
|
|
|
|
|
with corresponding bit flag types defining the valid bits for that flag, as
|
|
|
|
|
described in <<fundamentals-validusage-flags, Valid Usage for Flags>>. Flag
|
|
|
|
|
types supported by the Vulkan API include:
|
|
|
|
|
|
|
|
|
|
// All of these types have autogenerated ref pages at present, although
|
|
|
|
|
// bringing that content into the spec (by adding // refBegin and // refEnd
|
|
|
|
|
// comments and explanatory text for the ref pages) would be more complete.
|
|
|
|
|
|
|
|
|
|
include::../flags/VkAccessFlags.txt[]
|
|
|
|
|
include::../flags/VkAttachmentDescriptionFlags.txt[]
|
|
|
|
|
include::../flags/VkBufferCreateFlags.txt[]
|
|
|
|
|
include::../flags/VkBufferUsageFlags.txt[]
|
|
|
|
|
include::../flags/VkBufferViewCreateFlags.txt[]
|
|
|
|
|
include::../flags/VkColorComponentFlags.txt[]
|
|
|
|
|
include::../flags/VkCommandBufferResetFlags.txt[]
|
|
|
|
|
include::../flags/VkCommandBufferUsageFlags.txt[]
|
|
|
|
|
include::../flags/VkCommandPoolCreateFlags.txt[]
|
|
|
|
|
include::../flags/VkCommandPoolResetFlags.txt[]
|
|
|
|
|
include::../flags/VkCullModeFlags.txt[]
|
|
|
|
|
include::../flags/VkDependencyFlags.txt[]
|
|
|
|
|
include::../flags/VkDescriptorPoolCreateFlags.txt[]
|
|
|
|
|
include::../flags/VkDescriptorPoolResetFlags.txt[]
|
|
|
|
|
include::../flags/VkDescriptorSetLayoutCreateFlags.txt[]
|
|
|
|
|
include::../flags/VkDeviceCreateFlags.txt[]
|
|
|
|
|
include::../flags/VkDeviceQueueCreateFlags.txt[]
|
|
|
|
|
include::../flags/VkEventCreateFlags.txt[]
|
|
|
|
|
include::../flags/VkFenceCreateFlags.txt[]
|
|
|
|
|
include::../flags/VkFormatFeatureFlags.txt[]
|
|
|
|
|
include::../flags/VkFramebufferCreateFlags.txt[]
|
|
|
|
|
include::../flags/VkImageAspectFlags.txt[]
|
|
|
|
|
include::../flags/VkImageCreateFlags.txt[]
|
|
|
|
|
include::../flags/VkImageUsageFlags.txt[]
|
|
|
|
|
include::../flags/VkImageViewCreateFlags.txt[]
|
|
|
|
|
include::../flags/VkInstanceCreateFlags.txt[]
|
|
|
|
|
include::../flags/VkMemoryHeapFlags.txt[]
|
|
|
|
|
include::../flags/VkMemoryMapFlags.txt[]
|
|
|
|
|
include::../flags/VkMemoryPropertyFlags.txt[]
|
|
|
|
|
include::../flags/VkPipelineCacheCreateFlags.txt[]
|
|
|
|
|
include::../flags/VkPipelineColorBlendStateCreateFlags.txt[]
|
|
|
|
|
include::../flags/VkPipelineCreateFlags.txt[]
|
|
|
|
|
include::../flags/VkPipelineDepthStencilStateCreateFlags.txt[]
|
|
|
|
|
include::../flags/VkPipelineDynamicStateCreateFlags.txt[]
|
|
|
|
|
include::../flags/VkPipelineInputAssemblyStateCreateFlags.txt[]
|
|
|
|
|
include::../flags/VkPipelineLayoutCreateFlags.txt[]
|
|
|
|
|
include::../flags/VkPipelineMultisampleStateCreateFlags.txt[]
|
|
|
|
|
include::../flags/VkPipelineRasterizationStateCreateFlags.txt[]
|
|
|
|
|
include::../flags/VkPipelineShaderStageCreateFlags.txt[]
|
|
|
|
|
include::../flags/VkPipelineStageFlags.txt[]
|
|
|
|
|
include::../flags/VkPipelineTessellationStateCreateFlags.txt[]
|
|
|
|
|
include::../flags/VkPipelineVertexInputStateCreateFlags.txt[]
|
|
|
|
|
include::../flags/VkPipelineViewportStateCreateFlags.txt[]
|
|
|
|
|
include::../flags/VkQueryControlFlags.txt[]
|
|
|
|
|
include::../flags/VkQueryPipelineStatisticFlags.txt[]
|
|
|
|
|
include::../flags/VkQueryPoolCreateFlags.txt[]
|
|
|
|
|
include::../flags/VkQueryResultFlags.txt[]
|
|
|
|
|
include::../flags/VkQueueFlags.txt[]
|
|
|
|
|
include::../flags/VkRenderPassCreateFlags.txt[]
|
|
|
|
|
include::../flags/VkSampleCountFlags.txt[]
|
|
|
|
|
include::../flags/VkSamplerCreateFlags.txt[]
|
|
|
|
|
include::../flags/VkSemaphoreCreateFlags.txt[]
|
|
|
|
|
include::../flags/VkShaderModuleCreateFlags.txt[]
|
|
|
|
|
include::../flags/VkShaderStageFlags.txt[]
|
|
|
|
|
include::../flags/VkSparseImageFormatFlags.txt[]
|
|
|
|
|
include::../flags/VkSparseMemoryBindFlags.txt[]
|
|
|
|
|
include::../flags/VkStencilFaceFlags.txt[]
|
|
|
|
|
include::../flags/VkSubpassDescriptionFlags.txt[]
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
[[boilerplate-macros]]
|
|
|
|
|
== Macro Definitions in +vulkan.h+
|
|
|
|
|
|
|
|
|
|
Vulkan is defined as a C API. The supplied +vulkan.h+ header defines a small
|
|
|
|
|
number of C preprocessor macros that are described below.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
[[boilerplate-versions]]
|
|
|
|
|
=== Vulkan Version Number Macros
|
|
|
|
|
|
|
|
|
|
<<fundamentals-versionnum,API Version Numbers>> are packed into integers.
|
|
|
|
|
These macros manipulate version numbers in useful ways.
|
|
|
|
|
|
|
|
|
|
// refBegin VK_VERSION_MAJOR - Extract API major version number
|
|
|
|
|
|
|
|
|
|
dname:VK_VERSION_MAJOR extracts the API major version number
|
|
|
|
|
from a packed version number:
|
|
|
|
|
|
|
|
|
|
include::../defines/VK_VERSION_MAJOR.txt[]
|
|
|
|
|
|
|
|
|
|
// refEnd VK_VERSION_MAJOR
|
|
|
|
|
|
|
|
|
|
// refBegin VK_VERSION_MINOR - Extract API minor version number
|
|
|
|
|
|
|
|
|
|
dname:VK_VERSION_MINOR extracts the API minor version number
|
|
|
|
|
from a packed version number:
|
|
|
|
|
|
|
|
|
|
include::../defines/VK_VERSION_MINOR.txt[]
|
|
|
|
|
|
|
|
|
|
// refEnd VK_VERSION_MINOR
|
|
|
|
|
|
|
|
|
|
// refBegin VK_VERSION_PATCH - Extract API patch version number
|
|
|
|
|
|
|
|
|
|
dname:VK_VERSION_PATCH extracts the API patch version number
|
|
|
|
|
from a packed version number:
|
|
|
|
|
|
|
|
|
|
include::../defines/VK_VERSION_PATCH.txt[]
|
|
|
|
|
|
|
|
|
|
// refEnd VK_VERSION_PATCH
|
|
|
|
|
|
|
|
|
|
// refBegin VK_API_VERSION_1_0 - Return API version number for Vulkan 1.0
|
|
|
|
|
|
|
|
|
|
dname:VK_API_VERSION_1_0 returns the API version number for Vulkan 1.0. The
|
Change log for July 15, 2016 Vulkan 1.0.21 spec update:
* Bump API patch number and header version number to 21 for this update.
Github Issues:
* Clarify how <<features-supported-sample-counts,sample count queries>>
relate to the limits in slink:VkPhysicalDeviceLimits. (public issue
185).
* Clarify in the <<interfaces-iointerfaces,Shader Input and Output
Interfaces>> section that shader output variables have undefined values
until the shader writes to them (public issue 240).
* Specify the implicit value of image parameters that cannot be set in
slink:VkSwapchainCreateInfo::pname:flags, pname:imageType,
pname:mipLevels, pname:samples, pname:tiling, and pname:initialLayout
(public issue 243).
* Make use of code:NULL and code:VK_NULL_HANDLE consistent in the
VK_KHR_swapchain extension (public issue 276).
Internal Issues:
* Clarify that presenting an image to a display surface swapchain applies
the display surface's mode, and that destroying a display surface
swapchain may reset the display's mode, in the VK_KHR_display_swapchain
extension (internal issue 247).
* Better describe what a slink:VkSurfaceKHR is, and that creating one does
not set a mode, in the VK_KHR_display extension. This is a round-about
way of pointing out that mode setting is not covered by the extension,
but rather is performed as a side effect of presentation (internal issue
247).
* Add more valid usage statements to flink:vkQueuePresentKHR command when
the VK_KHR_display_swapchain extension is present (internal issue
247).
* Add more includes to the VK_KHR_swapchain extension to better document
interactions with VK_KHR_display_swapchain (internal issue 247).
* Clarify restrictions on location aliasing in the
<<fxvertex,Fixed-Function Vertex Processing>> section (internal issue
370).
* Add mathematical description of blitting to flink:vkCmdBlitImage, and
link it to the <<textures,Image Operations>> chapter. Use mathematical
notation for ranges of texel coordinates in the <<textures,Image
Operations>> chapter. Fixed miscellaneous validity statements for
flink:vkCmdBlit and slink:VkImageBlit (internal issue 382).
Other Commits:
* Added a valid usage rule to flink:VkGraphicsPipelineCreateInfo that the
ename:VK_PRIMITIVE_TOPOLOGY_PATCH_LIST topology must only be used when
tessellation shaders are used.
* Expand the style guide into a formal "Procedures and Conventions"
document. Add a API Naming Conventions section, move most of the API
Specification Appendix C (Layers and Extensions) content into the new
document, and define the resulting procedures as mandatory (where
relevant). This more clearly separates use vs. specification of Vulkan
APIs.
* Update vk_platform.h to handle 32-bit ARMv8 binaries.
* Various minor cleanups to the Makefile and build process.
2016-07-16 02:05:43 +00:00
|
|
|
patch version number in this macro will always be zero. The supported patch
|
|
|
|
|
version for a physical device can: be queried with
|
|
|
|
|
flink:vkGetPhysicalDeviceProperties.
|
2016-07-11 01:13:41 +00:00
|
|
|
|
|
|
|
|
include::../defines/VK_API_VERSION_1_0.txt[]
|
|
|
|
|
|
|
|
|
|
// refEnd VK_API_VERSION_1_0 vkCreateInstance vkGetPhysicalDeviceProperties
|
|
|
|
|
|
|
|
|
|
// refBegin VK_API_VERSION - Deprecated version number macro
|
|
|
|
|
|
Change log for July 15, 2016 Vulkan 1.0.21 spec update:
* Bump API patch number and header version number to 21 for this update.
Github Issues:
* Clarify how <<features-supported-sample-counts,sample count queries>>
relate to the limits in slink:VkPhysicalDeviceLimits. (public issue
185).
* Clarify in the <<interfaces-iointerfaces,Shader Input and Output
Interfaces>> section that shader output variables have undefined values
until the shader writes to them (public issue 240).
* Specify the implicit value of image parameters that cannot be set in
slink:VkSwapchainCreateInfo::pname:flags, pname:imageType,
pname:mipLevels, pname:samples, pname:tiling, and pname:initialLayout
(public issue 243).
* Make use of code:NULL and code:VK_NULL_HANDLE consistent in the
VK_KHR_swapchain extension (public issue 276).
Internal Issues:
* Clarify that presenting an image to a display surface swapchain applies
the display surface's mode, and that destroying a display surface
swapchain may reset the display's mode, in the VK_KHR_display_swapchain
extension (internal issue 247).
* Better describe what a slink:VkSurfaceKHR is, and that creating one does
not set a mode, in the VK_KHR_display extension. This is a round-about
way of pointing out that mode setting is not covered by the extension,
but rather is performed as a side effect of presentation (internal issue
247).
* Add more valid usage statements to flink:vkQueuePresentKHR command when
the VK_KHR_display_swapchain extension is present (internal issue
247).
* Add more includes to the VK_KHR_swapchain extension to better document
interactions with VK_KHR_display_swapchain (internal issue 247).
* Clarify restrictions on location aliasing in the
<<fxvertex,Fixed-Function Vertex Processing>> section (internal issue
370).
* Add mathematical description of blitting to flink:vkCmdBlitImage, and
link it to the <<textures,Image Operations>> chapter. Use mathematical
notation for ranges of texel coordinates in the <<textures,Image
Operations>> chapter. Fixed miscellaneous validity statements for
flink:vkCmdBlit and slink:VkImageBlit (internal issue 382).
Other Commits:
* Added a valid usage rule to flink:VkGraphicsPipelineCreateInfo that the
ename:VK_PRIMITIVE_TOPOLOGY_PATCH_LIST topology must only be used when
tessellation shaders are used.
* Expand the style guide into a formal "Procedures and Conventions"
document. Add a API Naming Conventions section, move most of the API
Specification Appendix C (Layers and Extensions) content into the new
document, and define the resulting procedures as mandatory (where
relevant). This more clearly separates use vs. specification of Vulkan
APIs.
* Update vk_platform.h to handle 32-bit ARMv8 binaries.
* Various minor cleanups to the Makefile and build process.
2016-07-16 02:05:43 +00:00
|
|
|
dname:VK_API_VERSION is now commented out of +vulkan.h+ and cannot: be used.
|
2016-07-11 01:13:41 +00:00
|
|
|
|
|
|
|
|
include::../defines/VK_API_VERSION.txt[]
|
|
|
|
|
|
|
|
|
|
// refEnd VK_API_VERSION
|
|
|
|
|
|
|
|
|
|
// refBegin VK_MAKE_VERSION - Construct an API version number
|
|
|
|
|
|
|
|
|
|
dname:VK_MAKE_VERSION constructs an API version number.
|
|
|
|
|
|
|
|
|
|
include::../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.
|
|
|
|
|
|
|
|
|
|
This macro can: be used when constructing the
|
|
|
|
|
slink:VkApplicationInfo::pname:apiVersion parameter passed to
|
|
|
|
|
flink:vkCreateInstance.
|
|
|
|
|
|
|
|
|
|
// refEnd VK_MAKE_VERSION VkApplicationInfo vkCreateInstance
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
=== Vulkan Header File Version Number
|
|
|
|
|
|
|
|
|
|
// refBegin VK_HEADER_VERSION - Vulkan header file version number
|
|
|
|
|
|
|
|
|
|
dname:VK_HEADER_VERSION is the version number of the +vulkan.h+ header. This
|
|
|
|
|
value is currently kept synchronized with the release number of the
|
|
|
|
|
Specification. However, it is not guaranteed to remain synchronized, since
|
|
|
|
|
most Specification updates have no effect on +vulkan.h+.
|
|
|
|
|
|
|
|
|
|
include::../defines/VK_HEADER_VERSION.txt[]
|
|
|
|
|
|
|
|
|
|
// refEnd VK_HEADER_VERSION
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
=== Vulkan Handle macros
|
|
|
|
|
|
|
|
|
|
// refBegin VK_DEFINE_HANDLE - Declare a dispatchable object handle
|
|
|
|
|
|
|
|
|
|
dname:VK_DEFINE_HANDLE defines a <<fundamentals-objectmodel-overview,
|
|
|
|
|
dispatchable handle>> type.
|
|
|
|
|
|
|
|
|
|
include::../defines/VK_DEFINE_HANDLE.txt[]
|
|
|
|
|
|
|
|
|
|
* pname:object is the name of the resulting C type.
|
|
|
|
|
|
|
|
|
|
The only dispatchable handle types are those related to device and instance
|
|
|
|
|
management, such as slink:VkDevice.
|
|
|
|
|
|
|
|
|
|
// refEnd VK_DEFINE_HANDLE VkCommandBuffer VkDevice VkInstance VkPhysicalDevice VkQueue
|
|
|
|
|
|
|
|
|
|
// refBegin VK_DEFINE_NON_DISPATCHABLE_HANDLE - Declare a non-dispatchable object handle
|
|
|
|
|
|
|
|
|
|
dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE defines a
|
|
|
|
|
<<fundamentals-objectmodel-overview, non-dispatchable handle>> type.
|
|
|
|
|
|
|
|
|
|
include::../defines/VK_DEFINE_NON_DISPATCHABLE_HANDLE.txt[]
|
|
|
|
|
|
|
|
|
|
* pname:object is the name of the resulting C type.
|
|
|
|
|
|
|
|
|
|
Most Vulkan handle types, such as slink:VkBuffer, are non-dispatchable.
|
|
|
|
|
|
|
|
|
|
// refEnd VK_DEFINE_NON_DISPATCHABLE_HANDLE VkBuffer
|
|
|
|
|
|
|
|
|
|
// refBegin VK_NULL_HANDLE - Reserved non-valid object handle
|
|
|
|
|
|
|
|
|
|
dname:VK_NULL_HANDLE is a reserved value representing a non-valid object
|
|
|
|
|
handle. It may be passed to and returned from Vulkan commands only when
|
|
|
|
|
<<fundamentals-validusage-handles, specifically allowed>>.
|
|
|
|
|
|
|
|
|
|
include::../defines/VK_NULL_HANDLE.txt[]
|
|
|
|
|
|
|
|
|
|
// refEnd VK_NULL_HANDLE
|