status-im
/
Vulkan-Docs
mirror of https://github.com/status-im/Vulkan-Docs.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity
Vulkan-Docs/doc/specs/vulkan/appendices/boilerplate.txt

228 lines
8.2 KiB
Plaintext
Raw Normal View History

Change log for July 10, 2016 Vulkan 1.0.20 spec update: * Bump API patch number and header version number to 20 for this update. Github Issues: * Replaced existing reference pages by text automatically extracted from the specification source, or generated from vk.xml in some cases. This isn't a complete solution for the reference pages, but puts them in a much better state. The ref pages (only) are now placed under a CC BY open source license, which is more current than the obsolete license previously used. Further improvements to the pages should not edit them directly, but instead concentrate on the specification source from which the ref pages are being extracted (public issues 44, 55, 160; internal issue 389).
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)
Change log for July 22, 2016 Vulkan 1.0.22 spec update: * Bump API patch number and header version number to 22 for this update. Github Issues: * Translate the subpass self-dependency language into concrete validity statements, and added a validity statement about the restrictions on layout parameters (public issue 267). * Add validity requirement that slink:VkAttachmentDescription::pname:finalLayout and slink:VkAttachmentReference::pname:layout must not be ename:VK_IMAGE_LAYOUT_UNDEFINED or ename:VK_IMAGE_LAYOUT_PREINITIALIZED (public issue 268). * Clarify that slink:VkSubpassDescription::pname:pResolveAttachments layouts are used. Make language consistent with other attachment arrays (public issue 270). * Changed 64-bit definition for dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE to work for x32 platform in +vk.xml+ and the resulting +vulkan.h+ (public issue 282). * Add missing error return code for flink:vkEnumerateInstanceExtensionProperties and flink:vkEnumerateDeviceExtensionProperties (public issue 285) * Fix several cases of stext::VkStructName.memberName markup to stext::VkStructName::pname:memberName, to match other usage in the spec, and describe this markup in the style guide (public issue 286). * Modified validity language generation script to avoid redundant common ancestor language if covered by generic parent language, and used `Both' instead of `Each' when appropriate (public issue 288). Internal Issues: * Add language about behavior of flink:vkAllocateDescriptorSets when allocation fails due to fragmentation, a new error ename:VK_ERROR_FRAGMENTED_POOL, and a Note explaining the situation (internal issue 309). * For the features of code:PointSize, code:ClipDistance, and code:CullDistance, the SPIR-V capability is required to be declared on use (read or write) rather than on decoration (internal issue 359). * Have desktop versions of GLSL respect precision qualification (code:mediump and code:lowp) when compiling for Vulkan. These will get translated to SPIR-V's code:RelaxedPrecision decoration as they do with OpenGL ES versions of GLSL (ESSL). The default precision of all types is code:highp when using a desktop version (internal issue 360). * Add validity statement for slink:VkImageCreateInfo specifying that multisampled images must be two-dimensional, optimally tiled, and with a single mipmap level (internal issue 369). * Add validity statements to slink:VkImageViewCreateInfo disallowing creation of images or image views with no supported features. Made some slink:VkImageViewCreateInfo validity statements more precise and consistent. Added a Note to the <<features,features>> chapter about formats with no features (internal issue 371). * Remove +manpages+ from default build targets. Nroff outputs containing imbedded latexmath will not render properly. Fixing this is a lot of work for limited use cases (internal issue 401). Other Commits: * Fix flink:vkRenderPassBeginInfo::pname:clearValueCount validity statement to be based on attachment indices rather than the number of cleared attachments (Vulkan-LoaderAndValidationLayers/issues/601). * Convert registry documentation from LaTeX to asciidoc source and rename from +src/spec/readme.tex+ to +src/spec/registry.txt+. * Fix lack of Oxford commas in validity language. * Lots of cleanup of generator scripts and Makefiles to move extension list for generator into the script arguments instead of the body of genvk.py, and express better dependencies between XML, scripts, and generated files.
2016-07-23 10:15:48 +00:00
Vulkan structures containing pname:sType members
Change log for July 10, 2016 Vulkan 1.0.20 spec update: * Bump API patch number and header version number to 20 for this update. Github Issues: * Replaced existing reference pages by text automatically extracted from the specification source, or generated from vk.xml in some cases. This isn't a complete solution for the reference pages, but puts them in a much better state. The ref pages (only) are now placed under a CC BY open source license, which is more current than the obsolete license previously used. Further improvements to the pages should not edit them directly, but instead concentrate on the specification source from which the ref pages are being extracted (public issues 44, 55, 160; internal issue 389).
2016-07-11 01:13:41 +00:00
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:
Change log for July 22, 2016 Vulkan 1.0.22 spec update: * Bump API patch number and header version number to 22 for this update. Github Issues: * Translate the subpass self-dependency language into concrete validity statements, and added a validity statement about the restrictions on layout parameters (public issue 267). * Add validity requirement that slink:VkAttachmentDescription::pname:finalLayout and slink:VkAttachmentReference::pname:layout must not be ename:VK_IMAGE_LAYOUT_UNDEFINED or ename:VK_IMAGE_LAYOUT_PREINITIALIZED (public issue 268). * Clarify that slink:VkSubpassDescription::pname:pResolveAttachments layouts are used. Make language consistent with other attachment arrays (public issue 270). * Changed 64-bit definition for dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE to work for x32 platform in +vk.xml+ and the resulting +vulkan.h+ (public issue 282). * Add missing error return code for flink:vkEnumerateInstanceExtensionProperties and flink:vkEnumerateDeviceExtensionProperties (public issue 285) * Fix several cases of stext::VkStructName.memberName markup to stext::VkStructName::pname:memberName, to match other usage in the spec, and describe this markup in the style guide (public issue 286). * Modified validity language generation script to avoid redundant common ancestor language if covered by generic parent language, and used `Both' instead of `Each' when appropriate (public issue 288). Internal Issues: * Add language about behavior of flink:vkAllocateDescriptorSets when allocation fails due to fragmentation, a new error ename:VK_ERROR_FRAGMENTED_POOL, and a Note explaining the situation (internal issue 309). * For the features of code:PointSize, code:ClipDistance, and code:CullDistance, the SPIR-V capability is required to be declared on use (read or write) rather than on decoration (internal issue 359). * Have desktop versions of GLSL respect precision qualification (code:mediump and code:lowp) when compiling for Vulkan. These will get translated to SPIR-V's code:RelaxedPrecision decoration as they do with OpenGL ES versions of GLSL (ESSL). The default precision of all types is code:highp when using a desktop version (internal issue 360). * Add validity statement for slink:VkImageCreateInfo specifying that multisampled images must be two-dimensional, optimally tiled, and with a single mipmap level (internal issue 369). * Add validity statements to slink:VkImageViewCreateInfo disallowing creation of images or image views with no supported features. Made some slink:VkImageViewCreateInfo validity statements more precise and consistent. Added a Note to the <<features,features>> chapter about formats with no features (internal issue 371). * Remove +manpages+ from default build targets. Nroff outputs containing imbedded latexmath will not render properly. Fixing this is a lot of work for limited use cases (internal issue 401). Other Commits: * Fix flink:vkRenderPassBeginInfo::pname:clearValueCount validity statement to be based on attachment indices rather than the number of cleared attachments (Vulkan-LoaderAndValidationLayers/issues/601). * Convert registry documentation from LaTeX to asciidoc source and rename from +src/spec/readme.tex+ to +src/spec/registry.txt+. * Fix lack of Oxford commas in validity language. * Lots of cleanup of generator scripts and Makefiles to move extension list for generator into the script arguments instead of the body of genvk.py, and express better dependencies between XML, scripts, and generated files.
2016-07-23 10:15:48 +00:00
include::../api/enums/VkStructureType.txt[]
Change log for July 10, 2016 Vulkan 1.0.20 spec update: * Bump API patch number and header version number to 20 for this update. Github Issues: * Replaced existing reference pages by text automatically extracted from the specification source, or generated from vk.xml in some cases. This isn't a complete solution for the reference pages, but puts them in a much better state. The ref pages (only) are now placed under a CC BY open source license, which is more current than the obsolete license previously used. Further improvements to the pages should not edit them directly, but instead concentrate on the specification source from which the ref pages are being extracted (public issues 44, 55, 160; internal issue 389).
2016-07-11 01:13:41 +00:00
// 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.
Change log for July 22, 2016 Vulkan 1.0.22 spec update: * Bump API patch number and header version number to 22 for this update. Github Issues: * Translate the subpass self-dependency language into concrete validity statements, and added a validity statement about the restrictions on layout parameters (public issue 267). * Add validity requirement that slink:VkAttachmentDescription::pname:finalLayout and slink:VkAttachmentReference::pname:layout must not be ename:VK_IMAGE_LAYOUT_UNDEFINED or ename:VK_IMAGE_LAYOUT_PREINITIALIZED (public issue 268). * Clarify that slink:VkSubpassDescription::pname:pResolveAttachments layouts are used. Make language consistent with other attachment arrays (public issue 270). * Changed 64-bit definition for dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE to work for x32 platform in +vk.xml+ and the resulting +vulkan.h+ (public issue 282). * Add missing error return code for flink:vkEnumerateInstanceExtensionProperties and flink:vkEnumerateDeviceExtensionProperties (public issue 285) * Fix several cases of stext::VkStructName.memberName markup to stext::VkStructName::pname:memberName, to match other usage in the spec, and describe this markup in the style guide (public issue 286). * Modified validity language generation script to avoid redundant common ancestor language if covered by generic parent language, and used `Both' instead of `Each' when appropriate (public issue 288). Internal Issues: * Add language about behavior of flink:vkAllocateDescriptorSets when allocation fails due to fragmentation, a new error ename:VK_ERROR_FRAGMENTED_POOL, and a Note explaining the situation (internal issue 309). * For the features of code:PointSize, code:ClipDistance, and code:CullDistance, the SPIR-V capability is required to be declared on use (read or write) rather than on decoration (internal issue 359). * Have desktop versions of GLSL respect precision qualification (code:mediump and code:lowp) when compiling for Vulkan. These will get translated to SPIR-V's code:RelaxedPrecision decoration as they do with OpenGL ES versions of GLSL (ESSL). The default precision of all types is code:highp when using a desktop version (internal issue 360). * Add validity statement for slink:VkImageCreateInfo specifying that multisampled images must be two-dimensional, optimally tiled, and with a single mipmap level (internal issue 369). * Add validity statements to slink:VkImageViewCreateInfo disallowing creation of images or image views with no supported features. Made some slink:VkImageViewCreateInfo validity statements more precise and consistent. Added a Note to the <<features,features>> chapter about formats with no features (internal issue 371). * Remove +manpages+ from default build targets. Nroff outputs containing imbedded latexmath will not render properly. Fixing this is a lot of work for limited use cases (internal issue 401). Other Commits: * Fix flink:vkRenderPassBeginInfo::pname:clearValueCount validity statement to be based on attachment indices rather than the number of cleared attachments (Vulkan-LoaderAndValidationLayers/issues/601). * Convert registry documentation from LaTeX to asciidoc source and rename from +src/spec/readme.tex+ to +src/spec/registry.txt+. * Fix lack of Oxford commas in validity language. * Lots of cleanup of generator scripts and Makefiles to move extension list for generator into the script arguments instead of the body of genvk.py, and express better dependencies between XML, scripts, and generated files.
2016-07-23 10:15:48 +00:00
include::../api/flags/VkAccessFlags.txt[]
include::../api/flags/VkAttachmentDescriptionFlags.txt[]
include::../api/flags/VkBufferCreateFlags.txt[]
include::../api/flags/VkBufferUsageFlags.txt[]
include::../api/flags/VkBufferViewCreateFlags.txt[]
include::../api/flags/VkColorComponentFlags.txt[]
include::../api/flags/VkCommandBufferResetFlags.txt[]
include::../api/flags/VkCommandBufferUsageFlags.txt[]
include::../api/flags/VkCommandPoolCreateFlags.txt[]
include::../api/flags/VkCommandPoolResetFlags.txt[]
include::../api/flags/VkCullModeFlags.txt[]
include::../api/flags/VkDependencyFlags.txt[]
include::../api/flags/VkDescriptorPoolCreateFlags.txt[]
include::../api/flags/VkDescriptorPoolResetFlags.txt[]
include::../api/flags/VkDescriptorSetLayoutCreateFlags.txt[]
include::../api/flags/VkDeviceCreateFlags.txt[]
include::../api/flags/VkDeviceQueueCreateFlags.txt[]
include::../api/flags/VkEventCreateFlags.txt[]
include::../api/flags/VkFenceCreateFlags.txt[]
include::../api/flags/VkFormatFeatureFlags.txt[]
include::../api/flags/VkFramebufferCreateFlags.txt[]
include::../api/flags/VkImageAspectFlags.txt[]
include::../api/flags/VkImageCreateFlags.txt[]
include::../api/flags/VkImageUsageFlags.txt[]
include::../api/flags/VkImageViewCreateFlags.txt[]
include::../api/flags/VkInstanceCreateFlags.txt[]
include::../api/flags/VkMemoryHeapFlags.txt[]
include::../api/flags/VkMemoryMapFlags.txt[]
include::../api/flags/VkMemoryPropertyFlags.txt[]
include::../api/flags/VkPipelineCacheCreateFlags.txt[]
include::../api/flags/VkPipelineColorBlendStateCreateFlags.txt[]
include::../api/flags/VkPipelineCreateFlags.txt[]
include::../api/flags/VkPipelineDepthStencilStateCreateFlags.txt[]
include::../api/flags/VkPipelineDynamicStateCreateFlags.txt[]
include::../api/flags/VkPipelineInputAssemblyStateCreateFlags.txt[]
include::../api/flags/VkPipelineLayoutCreateFlags.txt[]
include::../api/flags/VkPipelineMultisampleStateCreateFlags.txt[]
include::../api/flags/VkPipelineRasterizationStateCreateFlags.txt[]
include::../api/flags/VkPipelineShaderStageCreateFlags.txt[]
include::../api/flags/VkPipelineStageFlags.txt[]
include::../api/flags/VkPipelineTessellationStateCreateFlags.txt[]
include::../api/flags/VkPipelineVertexInputStateCreateFlags.txt[]
include::../api/flags/VkPipelineViewportStateCreateFlags.txt[]
include::../api/flags/VkQueryControlFlags.txt[]
include::../api/flags/VkQueryPipelineStatisticFlags.txt[]
include::../api/flags/VkQueryPoolCreateFlags.txt[]
include::../api/flags/VkQueryResultFlags.txt[]
include::../api/flags/VkQueueFlags.txt[]
include::../api/flags/VkRenderPassCreateFlags.txt[]
include::../api/flags/VkSampleCountFlags.txt[]
include::../api/flags/VkSamplerCreateFlags.txt[]
include::../api/flags/VkSemaphoreCreateFlags.txt[]
include::../api/flags/VkShaderModuleCreateFlags.txt[]
include::../api/flags/VkShaderStageFlags.txt[]
include::../api/flags/VkSparseImageFormatFlags.txt[]
include::../api/flags/VkSparseMemoryBindFlags.txt[]
include::../api/flags/VkStencilFaceFlags.txt[]
include::../api/flags/VkSubpassDescriptionFlags.txt[]
Change log for July 10, 2016 Vulkan 1.0.20 spec update: * Bump API patch number and header version number to 20 for this update. Github Issues: * Replaced existing reference pages by text automatically extracted from the specification source, or generated from vk.xml in some cases. This isn't a complete solution for the reference pages, but puts them in a much better state. The ref pages (only) are now placed under a CC BY open source license, which is more current than the obsolete license previously used. Further improvements to the pages should not edit them directly, but instead concentrate on the specification source from which the ref pages are being extracted (public issues 44, 55, 160; internal issue 389).
2016-07-11 01:13:41 +00:00
[[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:
Change log for July 22, 2016 Vulkan 1.0.22 spec update: * Bump API patch number and header version number to 22 for this update. Github Issues: * Translate the subpass self-dependency language into concrete validity statements, and added a validity statement about the restrictions on layout parameters (public issue 267). * Add validity requirement that slink:VkAttachmentDescription::pname:finalLayout and slink:VkAttachmentReference::pname:layout must not be ename:VK_IMAGE_LAYOUT_UNDEFINED or ename:VK_IMAGE_LAYOUT_PREINITIALIZED (public issue 268). * Clarify that slink:VkSubpassDescription::pname:pResolveAttachments layouts are used. Make language consistent with other attachment arrays (public issue 270). * Changed 64-bit definition for dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE to work for x32 platform in +vk.xml+ and the resulting +vulkan.h+ (public issue 282). * Add missing error return code for flink:vkEnumerateInstanceExtensionProperties and flink:vkEnumerateDeviceExtensionProperties (public issue 285) * Fix several cases of stext::VkStructName.memberName markup to stext::VkStructName::pname:memberName, to match other usage in the spec, and describe this markup in the style guide (public issue 286). * Modified validity language generation script to avoid redundant common ancestor language if covered by generic parent language, and used `Both' instead of `Each' when appropriate (public issue 288). Internal Issues: * Add language about behavior of flink:vkAllocateDescriptorSets when allocation fails due to fragmentation, a new error ename:VK_ERROR_FRAGMENTED_POOL, and a Note explaining the situation (internal issue 309). * For the features of code:PointSize, code:ClipDistance, and code:CullDistance, the SPIR-V capability is required to be declared on use (read or write) rather than on decoration (internal issue 359). * Have desktop versions of GLSL respect precision qualification (code:mediump and code:lowp) when compiling for Vulkan. These will get translated to SPIR-V's code:RelaxedPrecision decoration as they do with OpenGL ES versions of GLSL (ESSL). The default precision of all types is code:highp when using a desktop version (internal issue 360). * Add validity statement for slink:VkImageCreateInfo specifying that multisampled images must be two-dimensional, optimally tiled, and with a single mipmap level (internal issue 369). * Add validity statements to slink:VkImageViewCreateInfo disallowing creation of images or image views with no supported features. Made some slink:VkImageViewCreateInfo validity statements more precise and consistent. Added a Note to the <<features,features>> chapter about formats with no features (internal issue 371). * Remove +manpages+ from default build targets. Nroff outputs containing imbedded latexmath will not render properly. Fixing this is a lot of work for limited use cases (internal issue 401). Other Commits: * Fix flink:vkRenderPassBeginInfo::pname:clearValueCount validity statement to be based on attachment indices rather than the number of cleared attachments (Vulkan-LoaderAndValidationLayers/issues/601). * Convert registry documentation from LaTeX to asciidoc source and rename from +src/spec/readme.tex+ to +src/spec/registry.txt+. * Fix lack of Oxford commas in validity language. * Lots of cleanup of generator scripts and Makefiles to move extension list for generator into the script arguments instead of the body of genvk.py, and express better dependencies between XML, scripts, and generated files.
2016-07-23 10:15:48 +00:00
include::../api/defines/VK_VERSION_MAJOR.txt[]
Change log for July 10, 2016 Vulkan 1.0.20 spec update: * Bump API patch number and header version number to 20 for this update. Github Issues: * Replaced existing reference pages by text automatically extracted from the specification source, or generated from vk.xml in some cases. This isn't a complete solution for the reference pages, but puts them in a much better state. The ref pages (only) are now placed under a CC BY open source license, which is more current than the obsolete license previously used. Further improvements to the pages should not edit them directly, but instead concentrate on the specification source from which the ref pages are being extracted (public issues 44, 55, 160; internal issue 389).
2016-07-11 01:13:41 +00:00
// 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:
Change log for July 22, 2016 Vulkan 1.0.22 spec update: * Bump API patch number and header version number to 22 for this update. Github Issues: * Translate the subpass self-dependency language into concrete validity statements, and added a validity statement about the restrictions on layout parameters (public issue 267). * Add validity requirement that slink:VkAttachmentDescription::pname:finalLayout and slink:VkAttachmentReference::pname:layout must not be ename:VK_IMAGE_LAYOUT_UNDEFINED or ename:VK_IMAGE_LAYOUT_PREINITIALIZED (public issue 268). * Clarify that slink:VkSubpassDescription::pname:pResolveAttachments layouts are used. Make language consistent with other attachment arrays (public issue 270). * Changed 64-bit definition for dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE to work for x32 platform in +vk.xml+ and the resulting +vulkan.h+ (public issue 282). * Add missing error return code for flink:vkEnumerateInstanceExtensionProperties and flink:vkEnumerateDeviceExtensionProperties (public issue 285) * Fix several cases of stext::VkStructName.memberName markup to stext::VkStructName::pname:memberName, to match other usage in the spec, and describe this markup in the style guide (public issue 286). * Modified validity language generation script to avoid redundant common ancestor language if covered by generic parent language, and used `Both' instead of `Each' when appropriate (public issue 288). Internal Issues: * Add language about behavior of flink:vkAllocateDescriptorSets when allocation fails due to fragmentation, a new error ename:VK_ERROR_FRAGMENTED_POOL, and a Note explaining the situation (internal issue 309). * For the features of code:PointSize, code:ClipDistance, and code:CullDistance, the SPIR-V capability is required to be declared on use (read or write) rather than on decoration (internal issue 359). * Have desktop versions of GLSL respect precision qualification (code:mediump and code:lowp) when compiling for Vulkan. These will get translated to SPIR-V's code:RelaxedPrecision decoration as they do with OpenGL ES versions of GLSL (ESSL). The default precision of all types is code:highp when using a desktop version (internal issue 360). * Add validity statement for slink:VkImageCreateInfo specifying that multisampled images must be two-dimensional, optimally tiled, and with a single mipmap level (internal issue 369). * Add validity statements to slink:VkImageViewCreateInfo disallowing creation of images or image views with no supported features. Made some slink:VkImageViewCreateInfo validity statements more precise and consistent. Added a Note to the <<features,features>> chapter about formats with no features (internal issue 371). * Remove +manpages+ from default build targets. Nroff outputs containing imbedded latexmath will not render properly. Fixing this is a lot of work for limited use cases (internal issue 401). Other Commits: * Fix flink:vkRenderPassBeginInfo::pname:clearValueCount validity statement to be based on attachment indices rather than the number of cleared attachments (Vulkan-LoaderAndValidationLayers/issues/601). * Convert registry documentation from LaTeX to asciidoc source and rename from +src/spec/readme.tex+ to +src/spec/registry.txt+. * Fix lack of Oxford commas in validity language. * Lots of cleanup of generator scripts and Makefiles to move extension list for generator into the script arguments instead of the body of genvk.py, and express better dependencies between XML, scripts, and generated files.
2016-07-23 10:15:48 +00:00
include::../api/defines/VK_VERSION_MINOR.txt[]
Change log for July 10, 2016 Vulkan 1.0.20 spec update: * Bump API patch number and header version number to 20 for this update. Github Issues: * Replaced existing reference pages by text automatically extracted from the specification source, or generated from vk.xml in some cases. This isn't a complete solution for the reference pages, but puts them in a much better state. The ref pages (only) are now placed under a CC BY open source license, which is more current than the obsolete license previously used. Further improvements to the pages should not edit them directly, but instead concentrate on the specification source from which the ref pages are being extracted (public issues 44, 55, 160; internal issue 389).
2016-07-11 01:13:41 +00:00
// 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:
Change log for July 22, 2016 Vulkan 1.0.22 spec update: * Bump API patch number and header version number to 22 for this update. Github Issues: * Translate the subpass self-dependency language into concrete validity statements, and added a validity statement about the restrictions on layout parameters (public issue 267). * Add validity requirement that slink:VkAttachmentDescription::pname:finalLayout and slink:VkAttachmentReference::pname:layout must not be ename:VK_IMAGE_LAYOUT_UNDEFINED or ename:VK_IMAGE_LAYOUT_PREINITIALIZED (public issue 268). * Clarify that slink:VkSubpassDescription::pname:pResolveAttachments layouts are used. Make language consistent with other attachment arrays (public issue 270). * Changed 64-bit definition for dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE to work for x32 platform in +vk.xml+ and the resulting +vulkan.h+ (public issue 282). * Add missing error return code for flink:vkEnumerateInstanceExtensionProperties and flink:vkEnumerateDeviceExtensionProperties (public issue 285) * Fix several cases of stext::VkStructName.memberName markup to stext::VkStructName::pname:memberName, to match other usage in the spec, and describe this markup in the style guide (public issue 286). * Modified validity language generation script to avoid redundant common ancestor language if covered by generic parent language, and used `Both' instead of `Each' when appropriate (public issue 288). Internal Issues: * Add language about behavior of flink:vkAllocateDescriptorSets when allocation fails due to fragmentation, a new error ename:VK_ERROR_FRAGMENTED_POOL, and a Note explaining the situation (internal issue 309). * For the features of code:PointSize, code:ClipDistance, and code:CullDistance, the SPIR-V capability is required to be declared on use (read or write) rather than on decoration (internal issue 359). * Have desktop versions of GLSL respect precision qualification (code:mediump and code:lowp) when compiling for Vulkan. These will get translated to SPIR-V's code:RelaxedPrecision decoration as they do with OpenGL ES versions of GLSL (ESSL). The default precision of all types is code:highp when using a desktop version (internal issue 360). * Add validity statement for slink:VkImageCreateInfo specifying that multisampled images must be two-dimensional, optimally tiled, and with a single mipmap level (internal issue 369). * Add validity statements to slink:VkImageViewCreateInfo disallowing creation of images or image views with no supported features. Made some slink:VkImageViewCreateInfo validity statements more precise and consistent. Added a Note to the <<features,features>> chapter about formats with no features (internal issue 371). * Remove +manpages+ from default build targets. Nroff outputs containing imbedded latexmath will not render properly. Fixing this is a lot of work for limited use cases (internal issue 401). Other Commits: * Fix flink:vkRenderPassBeginInfo::pname:clearValueCount validity statement to be based on attachment indices rather than the number of cleared attachments (Vulkan-LoaderAndValidationLayers/issues/601). * Convert registry documentation from LaTeX to asciidoc source and rename from +src/spec/readme.tex+ to +src/spec/registry.txt+. * Fix lack of Oxford commas in validity language. * Lots of cleanup of generator scripts and Makefiles to move extension list for generator into the script arguments instead of the body of genvk.py, and express better dependencies between XML, scripts, and generated files.
2016-07-23 10:15:48 +00:00
include::../api/defines/VK_VERSION_PATCH.txt[]
Change log for July 10, 2016 Vulkan 1.0.20 spec update: * Bump API patch number and header version number to 20 for this update. Github Issues: * Replaced existing reference pages by text automatically extracted from the specification source, or generated from vk.xml in some cases. This isn't a complete solution for the reference pages, but puts them in a much better state. The ref pages (only) are now placed under a CC BY open source license, which is more current than the obsolete license previously used. Further improvements to the pages should not edit them directly, but instead concentrate on the specification source from which the ref pages are being extracted (public issues 44, 55, 160; internal issue 389).
2016-07-11 01:13:41 +00:00
// 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.
Change log for July 10, 2016 Vulkan 1.0.20 spec update: * Bump API patch number and header version number to 20 for this update. Github Issues: * Replaced existing reference pages by text automatically extracted from the specification source, or generated from vk.xml in some cases. This isn't a complete solution for the reference pages, but puts them in a much better state. The ref pages (only) are now placed under a CC BY open source license, which is more current than the obsolete license previously used. Further improvements to the pages should not edit them directly, but instead concentrate on the specification source from which the ref pages are being extracted (public issues 44, 55, 160; internal issue 389).
2016-07-11 01:13:41 +00:00
Change log for July 22, 2016 Vulkan 1.0.22 spec update: * Bump API patch number and header version number to 22 for this update. Github Issues: * Translate the subpass self-dependency language into concrete validity statements, and added a validity statement about the restrictions on layout parameters (public issue 267). * Add validity requirement that slink:VkAttachmentDescription::pname:finalLayout and slink:VkAttachmentReference::pname:layout must not be ename:VK_IMAGE_LAYOUT_UNDEFINED or ename:VK_IMAGE_LAYOUT_PREINITIALIZED (public issue 268). * Clarify that slink:VkSubpassDescription::pname:pResolveAttachments layouts are used. Make language consistent with other attachment arrays (public issue 270). * Changed 64-bit definition for dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE to work for x32 platform in +vk.xml+ and the resulting +vulkan.h+ (public issue 282). * Add missing error return code for flink:vkEnumerateInstanceExtensionProperties and flink:vkEnumerateDeviceExtensionProperties (public issue 285) * Fix several cases of stext::VkStructName.memberName markup to stext::VkStructName::pname:memberName, to match other usage in the spec, and describe this markup in the style guide (public issue 286). * Modified validity language generation script to avoid redundant common ancestor language if covered by generic parent language, and used `Both' instead of `Each' when appropriate (public issue 288). Internal Issues: * Add language about behavior of flink:vkAllocateDescriptorSets when allocation fails due to fragmentation, a new error ename:VK_ERROR_FRAGMENTED_POOL, and a Note explaining the situation (internal issue 309). * For the features of code:PointSize, code:ClipDistance, and code:CullDistance, the SPIR-V capability is required to be declared on use (read or write) rather than on decoration (internal issue 359). * Have desktop versions of GLSL respect precision qualification (code:mediump and code:lowp) when compiling for Vulkan. These will get translated to SPIR-V's code:RelaxedPrecision decoration as they do with OpenGL ES versions of GLSL (ESSL). The default precision of all types is code:highp when using a desktop version (internal issue 360). * Add validity statement for slink:VkImageCreateInfo specifying that multisampled images must be two-dimensional, optimally tiled, and with a single mipmap level (internal issue 369). * Add validity statements to slink:VkImageViewCreateInfo disallowing creation of images or image views with no supported features. Made some slink:VkImageViewCreateInfo validity statements more precise and consistent. Added a Note to the <<features,features>> chapter about formats with no features (internal issue 371). * Remove +manpages+ from default build targets. Nroff outputs containing imbedded latexmath will not render properly. Fixing this is a lot of work for limited use cases (internal issue 401). Other Commits: * Fix flink:vkRenderPassBeginInfo::pname:clearValueCount validity statement to be based on attachment indices rather than the number of cleared attachments (Vulkan-LoaderAndValidationLayers/issues/601). * Convert registry documentation from LaTeX to asciidoc source and rename from +src/spec/readme.tex+ to +src/spec/registry.txt+. * Fix lack of Oxford commas in validity language. * Lots of cleanup of generator scripts and Makefiles to move extension list for generator into the script arguments instead of the body of genvk.py, and express better dependencies between XML, scripts, and generated files.
2016-07-23 10:15:48 +00:00
include::../api/defines/VK_API_VERSION_1_0.txt[]
Change log for July 10, 2016 Vulkan 1.0.20 spec update: * Bump API patch number and header version number to 20 for this update. Github Issues: * Replaced existing reference pages by text automatically extracted from the specification source, or generated from vk.xml in some cases. This isn't a complete solution for the reference pages, but puts them in a much better state. The ref pages (only) are now placed under a CC BY open source license, which is more current than the obsolete license previously used. Further improvements to the pages should not edit them directly, but instead concentrate on the specification source from which the ref pages are being extracted (public issues 44, 55, 160; internal issue 389).
2016-07-11 01:13:41 +00:00
// 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.
Change log for July 10, 2016 Vulkan 1.0.20 spec update: * Bump API patch number and header version number to 20 for this update. Github Issues: * Replaced existing reference pages by text automatically extracted from the specification source, or generated from vk.xml in some cases. This isn't a complete solution for the reference pages, but puts them in a much better state. The ref pages (only) are now placed under a CC BY open source license, which is more current than the obsolete license previously used. Further improvements to the pages should not edit them directly, but instead concentrate on the specification source from which the ref pages are being extracted (public issues 44, 55, 160; internal issue 389).
2016-07-11 01:13:41 +00:00
Change log for July 22, 2016 Vulkan 1.0.22 spec update: * Bump API patch number and header version number to 22 for this update. Github Issues: * Translate the subpass self-dependency language into concrete validity statements, and added a validity statement about the restrictions on layout parameters (public issue 267). * Add validity requirement that slink:VkAttachmentDescription::pname:finalLayout and slink:VkAttachmentReference::pname:layout must not be ename:VK_IMAGE_LAYOUT_UNDEFINED or ename:VK_IMAGE_LAYOUT_PREINITIALIZED (public issue 268). * Clarify that slink:VkSubpassDescription::pname:pResolveAttachments layouts are used. Make language consistent with other attachment arrays (public issue 270). * Changed 64-bit definition for dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE to work for x32 platform in +vk.xml+ and the resulting +vulkan.h+ (public issue 282). * Add missing error return code for flink:vkEnumerateInstanceExtensionProperties and flink:vkEnumerateDeviceExtensionProperties (public issue 285) * Fix several cases of stext::VkStructName.memberName markup to stext::VkStructName::pname:memberName, to match other usage in the spec, and describe this markup in the style guide (public issue 286). * Modified validity language generation script to avoid redundant common ancestor language if covered by generic parent language, and used `Both' instead of `Each' when appropriate (public issue 288). Internal Issues: * Add language about behavior of flink:vkAllocateDescriptorSets when allocation fails due to fragmentation, a new error ename:VK_ERROR_FRAGMENTED_POOL, and a Note explaining the situation (internal issue 309). * For the features of code:PointSize, code:ClipDistance, and code:CullDistance, the SPIR-V capability is required to be declared on use (read or write) rather than on decoration (internal issue 359). * Have desktop versions of GLSL respect precision qualification (code:mediump and code:lowp) when compiling for Vulkan. These will get translated to SPIR-V's code:RelaxedPrecision decoration as they do with OpenGL ES versions of GLSL (ESSL). The default precision of all types is code:highp when using a desktop version (internal issue 360). * Add validity statement for slink:VkImageCreateInfo specifying that multisampled images must be two-dimensional, optimally tiled, and with a single mipmap level (internal issue 369). * Add validity statements to slink:VkImageViewCreateInfo disallowing creation of images or image views with no supported features. Made some slink:VkImageViewCreateInfo validity statements more precise and consistent. Added a Note to the <<features,features>> chapter about formats with no features (internal issue 371). * Remove +manpages+ from default build targets. Nroff outputs containing imbedded latexmath will not render properly. Fixing this is a lot of work for limited use cases (internal issue 401). Other Commits: * Fix flink:vkRenderPassBeginInfo::pname:clearValueCount validity statement to be based on attachment indices rather than the number of cleared attachments (Vulkan-LoaderAndValidationLayers/issues/601). * Convert registry documentation from LaTeX to asciidoc source and rename from +src/spec/readme.tex+ to +src/spec/registry.txt+. * Fix lack of Oxford commas in validity language. * Lots of cleanup of generator scripts and Makefiles to move extension list for generator into the script arguments instead of the body of genvk.py, and express better dependencies between XML, scripts, and generated files.
2016-07-23 10:15:48 +00:00
include::../api/defines/VK_API_VERSION.txt[]
Change log for July 10, 2016 Vulkan 1.0.20 spec update: * Bump API patch number and header version number to 20 for this update. Github Issues: * Replaced existing reference pages by text automatically extracted from the specification source, or generated from vk.xml in some cases. This isn't a complete solution for the reference pages, but puts them in a much better state. The ref pages (only) are now placed under a CC BY open source license, which is more current than the obsolete license previously used. Further improvements to the pages should not edit them directly, but instead concentrate on the specification source from which the ref pages are being extracted (public issues 44, 55, 160; internal issue 389).
2016-07-11 01:13:41 +00:00
// refEnd VK_API_VERSION
// refBegin VK_MAKE_VERSION - Construct an API version number
dname:VK_MAKE_VERSION constructs an API version number.
Change log for July 22, 2016 Vulkan 1.0.22 spec update: * Bump API patch number and header version number to 22 for this update. Github Issues: * Translate the subpass self-dependency language into concrete validity statements, and added a validity statement about the restrictions on layout parameters (public issue 267). * Add validity requirement that slink:VkAttachmentDescription::pname:finalLayout and slink:VkAttachmentReference::pname:layout must not be ename:VK_IMAGE_LAYOUT_UNDEFINED or ename:VK_IMAGE_LAYOUT_PREINITIALIZED (public issue 268). * Clarify that slink:VkSubpassDescription::pname:pResolveAttachments layouts are used. Make language consistent with other attachment arrays (public issue 270). * Changed 64-bit definition for dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE to work for x32 platform in +vk.xml+ and the resulting +vulkan.h+ (public issue 282). * Add missing error return code for flink:vkEnumerateInstanceExtensionProperties and flink:vkEnumerateDeviceExtensionProperties (public issue 285) * Fix several cases of stext::VkStructName.memberName markup to stext::VkStructName::pname:memberName, to match other usage in the spec, and describe this markup in the style guide (public issue 286). * Modified validity language generation script to avoid redundant common ancestor language if covered by generic parent language, and used `Both' instead of `Each' when appropriate (public issue 288). Internal Issues: * Add language about behavior of flink:vkAllocateDescriptorSets when allocation fails due to fragmentation, a new error ename:VK_ERROR_FRAGMENTED_POOL, and a Note explaining the situation (internal issue 309). * For the features of code:PointSize, code:ClipDistance, and code:CullDistance, the SPIR-V capability is required to be declared on use (read or write) rather than on decoration (internal issue 359). * Have desktop versions of GLSL respect precision qualification (code:mediump and code:lowp) when compiling for Vulkan. These will get translated to SPIR-V's code:RelaxedPrecision decoration as they do with OpenGL ES versions of GLSL (ESSL). The default precision of all types is code:highp when using a desktop version (internal issue 360). * Add validity statement for slink:VkImageCreateInfo specifying that multisampled images must be two-dimensional, optimally tiled, and with a single mipmap level (internal issue 369). * Add validity statements to slink:VkImageViewCreateInfo disallowing creation of images or image views with no supported features. Made some slink:VkImageViewCreateInfo validity statements more precise and consistent. Added a Note to the <<features,features>> chapter about formats with no features (internal issue 371). * Remove +manpages+ from default build targets. Nroff outputs containing imbedded latexmath will not render properly. Fixing this is a lot of work for limited use cases (internal issue 401). Other Commits: * Fix flink:vkRenderPassBeginInfo::pname:clearValueCount validity statement to be based on attachment indices rather than the number of cleared attachments (Vulkan-LoaderAndValidationLayers/issues/601). * Convert registry documentation from LaTeX to asciidoc source and rename from +src/spec/readme.tex+ to +src/spec/registry.txt+. * Fix lack of Oxford commas in validity language. * Lots of cleanup of generator scripts and Makefiles to move extension list for generator into the script arguments instead of the body of genvk.py, and express better dependencies between XML, scripts, and generated files.
2016-07-23 10:15:48 +00:00
include::../api/defines/VK_MAKE_VERSION.txt[]
Change log for July 10, 2016 Vulkan 1.0.20 spec update: * Bump API patch number and header version number to 20 for this update. Github Issues: * Replaced existing reference pages by text automatically extracted from the specification source, or generated from vk.xml in some cases. This isn't a complete solution for the reference pages, but puts them in a much better state. The ref pages (only) are now placed under a CC BY open source license, which is more current than the obsolete license previously used. Further improvements to the pages should not edit them directly, but instead concentrate on the specification source from which the ref pages are being extracted (public issues 44, 55, 160; internal issue 389).
2016-07-11 01:13:41 +00:00
* 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+.
Change log for July 22, 2016 Vulkan 1.0.22 spec update: * Bump API patch number and header version number to 22 for this update. Github Issues: * Translate the subpass self-dependency language into concrete validity statements, and added a validity statement about the restrictions on layout parameters (public issue 267). * Add validity requirement that slink:VkAttachmentDescription::pname:finalLayout and slink:VkAttachmentReference::pname:layout must not be ename:VK_IMAGE_LAYOUT_UNDEFINED or ename:VK_IMAGE_LAYOUT_PREINITIALIZED (public issue 268). * Clarify that slink:VkSubpassDescription::pname:pResolveAttachments layouts are used. Make language consistent with other attachment arrays (public issue 270). * Changed 64-bit definition for dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE to work for x32 platform in +vk.xml+ and the resulting +vulkan.h+ (public issue 282). * Add missing error return code for flink:vkEnumerateInstanceExtensionProperties and flink:vkEnumerateDeviceExtensionProperties (public issue 285) * Fix several cases of stext::VkStructName.memberName markup to stext::VkStructName::pname:memberName, to match other usage in the spec, and describe this markup in the style guide (public issue 286). * Modified validity language generation script to avoid redundant common ancestor language if covered by generic parent language, and used `Both' instead of `Each' when appropriate (public issue 288). Internal Issues: * Add language about behavior of flink:vkAllocateDescriptorSets when allocation fails due to fragmentation, a new error ename:VK_ERROR_FRAGMENTED_POOL, and a Note explaining the situation (internal issue 309). * For the features of code:PointSize, code:ClipDistance, and code:CullDistance, the SPIR-V capability is required to be declared on use (read or write) rather than on decoration (internal issue 359). * Have desktop versions of GLSL respect precision qualification (code:mediump and code:lowp) when compiling for Vulkan. These will get translated to SPIR-V's code:RelaxedPrecision decoration as they do with OpenGL ES versions of GLSL (ESSL). The default precision of all types is code:highp when using a desktop version (internal issue 360). * Add validity statement for slink:VkImageCreateInfo specifying that multisampled images must be two-dimensional, optimally tiled, and with a single mipmap level (internal issue 369). * Add validity statements to slink:VkImageViewCreateInfo disallowing creation of images or image views with no supported features. Made some slink:VkImageViewCreateInfo validity statements more precise and consistent. Added a Note to the <<features,features>> chapter about formats with no features (internal issue 371). * Remove +manpages+ from default build targets. Nroff outputs containing imbedded latexmath will not render properly. Fixing this is a lot of work for limited use cases (internal issue 401). Other Commits: * Fix flink:vkRenderPassBeginInfo::pname:clearValueCount validity statement to be based on attachment indices rather than the number of cleared attachments (Vulkan-LoaderAndValidationLayers/issues/601). * Convert registry documentation from LaTeX to asciidoc source and rename from +src/spec/readme.tex+ to +src/spec/registry.txt+. * Fix lack of Oxford commas in validity language. * Lots of cleanup of generator scripts and Makefiles to move extension list for generator into the script arguments instead of the body of genvk.py, and express better dependencies between XML, scripts, and generated files.
2016-07-23 10:15:48 +00:00
include::../api/defines/VK_HEADER_VERSION.txt[]
Change log for July 10, 2016 Vulkan 1.0.20 spec update: * Bump API patch number and header version number to 20 for this update. Github Issues: * Replaced existing reference pages by text automatically extracted from the specification source, or generated from vk.xml in some cases. This isn't a complete solution for the reference pages, but puts them in a much better state. The ref pages (only) are now placed under a CC BY open source license, which is more current than the obsolete license previously used. Further improvements to the pages should not edit them directly, but instead concentrate on the specification source from which the ref pages are being extracted (public issues 44, 55, 160; internal issue 389).
2016-07-11 01:13:41 +00:00
// 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.
Change log for July 22, 2016 Vulkan 1.0.22 spec update: * Bump API patch number and header version number to 22 for this update. Github Issues: * Translate the subpass self-dependency language into concrete validity statements, and added a validity statement about the restrictions on layout parameters (public issue 267). * Add validity requirement that slink:VkAttachmentDescription::pname:finalLayout and slink:VkAttachmentReference::pname:layout must not be ename:VK_IMAGE_LAYOUT_UNDEFINED or ename:VK_IMAGE_LAYOUT_PREINITIALIZED (public issue 268). * Clarify that slink:VkSubpassDescription::pname:pResolveAttachments layouts are used. Make language consistent with other attachment arrays (public issue 270). * Changed 64-bit definition for dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE to work for x32 platform in +vk.xml+ and the resulting +vulkan.h+ (public issue 282). * Add missing error return code for flink:vkEnumerateInstanceExtensionProperties and flink:vkEnumerateDeviceExtensionProperties (public issue 285) * Fix several cases of stext::VkStructName.memberName markup to stext::VkStructName::pname:memberName, to match other usage in the spec, and describe this markup in the style guide (public issue 286). * Modified validity language generation script to avoid redundant common ancestor language if covered by generic parent language, and used `Both' instead of `Each' when appropriate (public issue 288). Internal Issues: * Add language about behavior of flink:vkAllocateDescriptorSets when allocation fails due to fragmentation, a new error ename:VK_ERROR_FRAGMENTED_POOL, and a Note explaining the situation (internal issue 309). * For the features of code:PointSize, code:ClipDistance, and code:CullDistance, the SPIR-V capability is required to be declared on use (read or write) rather than on decoration (internal issue 359). * Have desktop versions of GLSL respect precision qualification (code:mediump and code:lowp) when compiling for Vulkan. These will get translated to SPIR-V's code:RelaxedPrecision decoration as they do with OpenGL ES versions of GLSL (ESSL). The default precision of all types is code:highp when using a desktop version (internal issue 360). * Add validity statement for slink:VkImageCreateInfo specifying that multisampled images must be two-dimensional, optimally tiled, and with a single mipmap level (internal issue 369). * Add validity statements to slink:VkImageViewCreateInfo disallowing creation of images or image views with no supported features. Made some slink:VkImageViewCreateInfo validity statements more precise and consistent. Added a Note to the <<features,features>> chapter about formats with no features (internal issue 371). * Remove +manpages+ from default build targets. Nroff outputs containing imbedded latexmath will not render properly. Fixing this is a lot of work for limited use cases (internal issue 401). Other Commits: * Fix flink:vkRenderPassBeginInfo::pname:clearValueCount validity statement to be based on attachment indices rather than the number of cleared attachments (Vulkan-LoaderAndValidationLayers/issues/601). * Convert registry documentation from LaTeX to asciidoc source and rename from +src/spec/readme.tex+ to +src/spec/registry.txt+. * Fix lack of Oxford commas in validity language. * Lots of cleanup of generator scripts and Makefiles to move extension list for generator into the script arguments instead of the body of genvk.py, and express better dependencies between XML, scripts, and generated files.
2016-07-23 10:15:48 +00:00
include::../api/defines/VK_DEFINE_HANDLE.txt[]
Change log for July 10, 2016 Vulkan 1.0.20 spec update: * Bump API patch number and header version number to 20 for this update. Github Issues: * Replaced existing reference pages by text automatically extracted from the specification source, or generated from vk.xml in some cases. This isn't a complete solution for the reference pages, but puts them in a much better state. The ref pages (only) are now placed under a CC BY open source license, which is more current than the obsolete license previously used. Further improvements to the pages should not edit them directly, but instead concentrate on the specification source from which the ref pages are being extracted (public issues 44, 55, 160; internal issue 389).
2016-07-11 01:13:41 +00:00
* 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.
Change log for July 22, 2016 Vulkan 1.0.22 spec update: * Bump API patch number and header version number to 22 for this update. Github Issues: * Translate the subpass self-dependency language into concrete validity statements, and added a validity statement about the restrictions on layout parameters (public issue 267). * Add validity requirement that slink:VkAttachmentDescription::pname:finalLayout and slink:VkAttachmentReference::pname:layout must not be ename:VK_IMAGE_LAYOUT_UNDEFINED or ename:VK_IMAGE_LAYOUT_PREINITIALIZED (public issue 268). * Clarify that slink:VkSubpassDescription::pname:pResolveAttachments layouts are used. Make language consistent with other attachment arrays (public issue 270). * Changed 64-bit definition for dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE to work for x32 platform in +vk.xml+ and the resulting +vulkan.h+ (public issue 282). * Add missing error return code for flink:vkEnumerateInstanceExtensionProperties and flink:vkEnumerateDeviceExtensionProperties (public issue 285) * Fix several cases of stext::VkStructName.memberName markup to stext::VkStructName::pname:memberName, to match other usage in the spec, and describe this markup in the style guide (public issue 286). * Modified validity language generation script to avoid redundant common ancestor language if covered by generic parent language, and used `Both' instead of `Each' when appropriate (public issue 288). Internal Issues: * Add language about behavior of flink:vkAllocateDescriptorSets when allocation fails due to fragmentation, a new error ename:VK_ERROR_FRAGMENTED_POOL, and a Note explaining the situation (internal issue 309). * For the features of code:PointSize, code:ClipDistance, and code:CullDistance, the SPIR-V capability is required to be declared on use (read or write) rather than on decoration (internal issue 359). * Have desktop versions of GLSL respect precision qualification (code:mediump and code:lowp) when compiling for Vulkan. These will get translated to SPIR-V's code:RelaxedPrecision decoration as they do with OpenGL ES versions of GLSL (ESSL). The default precision of all types is code:highp when using a desktop version (internal issue 360). * Add validity statement for slink:VkImageCreateInfo specifying that multisampled images must be two-dimensional, optimally tiled, and with a single mipmap level (internal issue 369). * Add validity statements to slink:VkImageViewCreateInfo disallowing creation of images or image views with no supported features. Made some slink:VkImageViewCreateInfo validity statements more precise and consistent. Added a Note to the <<features,features>> chapter about formats with no features (internal issue 371). * Remove +manpages+ from default build targets. Nroff outputs containing imbedded latexmath will not render properly. Fixing this is a lot of work for limited use cases (internal issue 401). Other Commits: * Fix flink:vkRenderPassBeginInfo::pname:clearValueCount validity statement to be based on attachment indices rather than the number of cleared attachments (Vulkan-LoaderAndValidationLayers/issues/601). * Convert registry documentation from LaTeX to asciidoc source and rename from +src/spec/readme.tex+ to +src/spec/registry.txt+. * Fix lack of Oxford commas in validity language. * Lots of cleanup of generator scripts and Makefiles to move extension list for generator into the script arguments instead of the body of genvk.py, and express better dependencies between XML, scripts, and generated files.
2016-07-23 10:15:48 +00:00
include::../api/defines/VK_DEFINE_NON_DISPATCHABLE_HANDLE.txt[]
Change log for July 10, 2016 Vulkan 1.0.20 spec update: * Bump API patch number and header version number to 20 for this update. Github Issues: * Replaced existing reference pages by text automatically extracted from the specification source, or generated from vk.xml in some cases. This isn't a complete solution for the reference pages, but puts them in a much better state. The ref pages (only) are now placed under a CC BY open source license, which is more current than the obsolete license previously used. Further improvements to the pages should not edit them directly, but instead concentrate on the specification source from which the ref pages are being extracted (public issues 44, 55, 160; internal issue 389).
2016-07-11 01:13:41 +00:00
* 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>>.
Change log for July 22, 2016 Vulkan 1.0.22 spec update: * Bump API patch number and header version number to 22 for this update. Github Issues: * Translate the subpass self-dependency language into concrete validity statements, and added a validity statement about the restrictions on layout parameters (public issue 267). * Add validity requirement that slink:VkAttachmentDescription::pname:finalLayout and slink:VkAttachmentReference::pname:layout must not be ename:VK_IMAGE_LAYOUT_UNDEFINED or ename:VK_IMAGE_LAYOUT_PREINITIALIZED (public issue 268). * Clarify that slink:VkSubpassDescription::pname:pResolveAttachments layouts are used. Make language consistent with other attachment arrays (public issue 270). * Changed 64-bit definition for dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE to work for x32 platform in +vk.xml+ and the resulting +vulkan.h+ (public issue 282). * Add missing error return code for flink:vkEnumerateInstanceExtensionProperties and flink:vkEnumerateDeviceExtensionProperties (public issue 285) * Fix several cases of stext::VkStructName.memberName markup to stext::VkStructName::pname:memberName, to match other usage in the spec, and describe this markup in the style guide (public issue 286). * Modified validity language generation script to avoid redundant common ancestor language if covered by generic parent language, and used `Both' instead of `Each' when appropriate (public issue 288). Internal Issues: * Add language about behavior of flink:vkAllocateDescriptorSets when allocation fails due to fragmentation, a new error ename:VK_ERROR_FRAGMENTED_POOL, and a Note explaining the situation (internal issue 309). * For the features of code:PointSize, code:ClipDistance, and code:CullDistance, the SPIR-V capability is required to be declared on use (read or write) rather than on decoration (internal issue 359). * Have desktop versions of GLSL respect precision qualification (code:mediump and code:lowp) when compiling for Vulkan. These will get translated to SPIR-V's code:RelaxedPrecision decoration as they do with OpenGL ES versions of GLSL (ESSL). The default precision of all types is code:highp when using a desktop version (internal issue 360). * Add validity statement for slink:VkImageCreateInfo specifying that multisampled images must be two-dimensional, optimally tiled, and with a single mipmap level (internal issue 369). * Add validity statements to slink:VkImageViewCreateInfo disallowing creation of images or image views with no supported features. Made some slink:VkImageViewCreateInfo validity statements more precise and consistent. Added a Note to the <<features,features>> chapter about formats with no features (internal issue 371). * Remove +manpages+ from default build targets. Nroff outputs containing imbedded latexmath will not render properly. Fixing this is a lot of work for limited use cases (internal issue 401). Other Commits: * Fix flink:vkRenderPassBeginInfo::pname:clearValueCount validity statement to be based on attachment indices rather than the number of cleared attachments (Vulkan-LoaderAndValidationLayers/issues/601). * Convert registry documentation from LaTeX to asciidoc source and rename from +src/spec/readme.tex+ to +src/spec/registry.txt+. * Fix lack of Oxford commas in validity language. * Lots of cleanup of generator scripts and Makefiles to move extension list for generator into the script arguments instead of the body of genvk.py, and express better dependencies between XML, scripts, and generated files.
2016-07-23 10:15:48 +00:00
include::../api/defines/VK_NULL_HANDLE.txt[]
Change log for July 10, 2016 Vulkan 1.0.20 spec update: * Bump API patch number and header version number to 20 for this update. Github Issues: * Replaced existing reference pages by text automatically extracted from the specification source, or generated from vk.xml in some cases. This isn't a complete solution for the reference pages, but puts them in a much better state. The ref pages (only) are now placed under a CC BY open source license, which is more current than the obsolete license previously used. Further improvements to the pages should not edit them directly, but instead concentrate on the specification source from which the ref pages are being extracted (public issues 44, 55, 160; internal issue 389).
2016-07-11 01:13:41 +00:00
// refEnd VK_NULL_HANDLE