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/vkspec.txt

144 lines
2.7 KiB
Plaintext
Raw Normal View History

Change log for January 5, 2018 Vulkan 1.0.67 spec update: * Bump API patch number and header version number to 67 for this update. * Update copyright dates to 2018 Github Issues: * Fix texture lookup functions in `GL_KHR_vulkan_glsl` specification (public pull request 363). * Clarify the state waited semaphores are left in when a call to flink:vkQueuePresentKHR fails (public issue 572). * Cleanup descriptions of slink:VkObjectTablePushConstantEntryNVX and slink:VkObjectTableDescriptorSetEntryNVX (public issue 583) * Remove redundant flink:vkCmdSetDiscardRectangleEXT valid usage statements (public pull 586). * Make dynamic state array length valid usage statements implicit for flink:vkCmdSetViewportWScalingNV, flink:vkCmdSetDiscardRectangleEXT, and flink:vkCmdSetViewport (public pull 589). * Clarify meaning of window extent (0,0) in slink:VkSwapchainKHR for the Windows and X11 platforms, in their respective extensions (public issue 590). * Allow flink:vkGetPastPresentationTimingGOOGLE to return ename:VK_INCOMPLETE (public issue 604). * Add synchronization valid usage statements to flink:vkAcquireNextImage (public pull 611). * Fix some broken external links and internal xrefs (public pull 613). * Clean up slink:VkViewport valid usage statements in the presence or absence of relevant extensions (public pull 623). * Remove ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL_KHR token from VK_KHR_maintenance2 from the non-extension VU path for slink:VkGraphicsPipelineCreateInfo (public issue 628). * Miscellaneous minor markup fixes - extension name strings (public pull 631), Notes (pull 633), queue names emitted by generator scripts (pull 634), block formatting in slink:VkDescriptorUpdateTemplateEntryKHR (pull 635), ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_CUBIC_BIT_IMG (pull 641), quotes and apostrophes (pull 643), * Miscellaneous minor grammar fixes (public pull 644). * Fix markup macros so usage like ptext:*Src* works (public pull 647). Internal Issues: * Clarify in the `VK_KHR_surface` and `VK_KHR_swapchain` extensions that parameter combinations which aren't supported for normal images are also unsupported for presentable images, even if the parameter values are individually supported as reported by the surface capability queries (internal issue 1029). * Fixed XML typo in the valid value field of the pname:sType member of slink:VkPhysicalDeviceExternalMemoryHostPropertiesEXT (internal issue 1100). Other Issues: * Add memory semantics validity rules to the <<spirvenv-module-validation, Validation Rules within a Module>> section of the SPIR-V environment appendix, and specify that sequentiality consistency is not supported. This forbids certain cases like "`Load+Release`" that we don't expect to ever be meaningful. * Document mapping of OpenGL Shading Language barriers to SPIR-V scope and semantics in the `GL_KHR_vulkan_glsl` specification. New Extensions: * `VK_EXT_conservative_rasterization`
2018-01-06 01:39:15 +00:00
// Copyright (c) 2014-2018 Khronos Group. This work is licensed under a
Change log for June 24, 2017 Vulkan 1.0.53 spec update: * Bump API patch number and header version number to 53 for this update. Github Issues: Internal Issues: * Clarify mappings of coordinates for mutable, compatible image views in slink:VkImageViewCreateInfo (internal issue 815). * Make ename:VK_BIND_SFR_BIT require a logical device with multiple physical devices, so that standard sparse image block dimensions are only required on systems that support multi-GPU (internal issue 835). * Convert all files from use of // refBegin .. // refEnd comments to delimit ref pages, to use of open blocks, and update style guide accordingly (internal issue 839). * Add valid usage for slink:VkWriteDescriptorSet when performing updates to a ename:VK_STORAGE_IMAGE descriptor with layout ename:VK_IMAGE_LAYOUT_GENERAL. * Add a hack to the validity generator script to support an odd interaction between flink:vkCmdFillBuffer and an extension (internal issue 853). * Remove redundant text describing slink:VkBufferCreateInfo::pname:usage, which was already covered by implicit valid usage (internal issue 854). * Update implicit validity generator script to properly handle the pname:sType and pname:pNext members of "returnedonly" structures (internal issue 874). * Note that slink:VkApplicationInfo::pname:pApplicationName & slink:VkApplicationInfo::pname:pEngineName are optional, and add missing implicit valid usage statements for flink:vkDestroyInstance. * Added missing valid usage for flink:vkCmdWriteTimestamp to require a timestamp query pool. * Simplify and/or split "`non-atomic`" valid usage statements. New Extensions: * `VK_AMD_gpu_shader_int16` * `VK_EXT_blend_operation_advanced` * `VK_EXT_sampler_filter_minmax` * `VK_NV_framebuffer_mixed_samples` ----------------------------------------------------- Note: the 1.0.52 spec wasn't published on github, so the 1.0.53 release combines both change sets. ----------------------------------------------------- Change log for June 13, 2017 Vulkan 1.0.52 spec update: * Bump API patch number and header version number to 52 for this update. Github Issues: Internal Issues: * Clarify behavior when non-coherent memory has <<memory-device-unmap-does-not-flush, not been flushed before being unmapped>> (internal issue 819). * Fix description of code:WorkgroupSize builtin to note it decorates an object, not a variable (internal issue 836). * Fix asciidoc attributes so that trailing '{plus}' symbols in [eq] style equations are rendered properly (internal issue 845). * Add language to the "`Extension Handles, Objects, Enums, and Typedefs`" section of the Procedures and Conventions document stating that any new handle type requires a corresponding entry in the elink:VkObjectType enumerated type (internal issue 856). * Update style guide to use slink macro for Vulkan handle type names, and define narrow conditions under which to use the *name and *text macros instead of *link (internal issue 886). * Add a dependency of the <<VK_KHX_device_group,VK_KHX_device_group>> extension on VK_KHX_device_group_creation to +vk.xml+ and the extension appendix. * Change the copyright on Vulkan specification asciidoc *source* files to CC-BY 4.0, and update the proprietary Khronos copyright applied to the generated *output* formats (internal issue 327). This enables broader re-use and modification of the Vulkan specification sources, while not affecting the Reciprocal IP License between Vulkan Adopters and Working Group Members. New Extensions: * `VK_NV_fill_rectangle` * `VK_NV_fragment_coverage_to_color`
2017-06-27 02:32:10 +00:00
// Creative Commons Attribution 4.0 International License; see
// http://creativecommons.org/licenses/by/4.0/
Vulkan 1.0 branch 1.0 for release
2016-02-16 09:53:44 +00:00
Change log for February 10, 2017 Vulkan 1.0.40 spec update: * Bump API patch number and header version number to 40 for this update. * There is a major build change in this release. We are now using the Ruby-based ``asciidoctor'' implementation, rather than the Python-based ``asciidoc'' implementation, to process the specification. While the actual specification markup changes were minimal, this requires a new set of build tools and a very different installation process, especially because we now use an experimental direct-to-PDF backend for Asciidoctor instead of Docbook->dblatex->PDF. It is no longer possible to build the Specification using asciidoc. See doc/specs/vulkan/README.adoc for some guidance on installing the new toolchain components. * There are some minor rendering issues in the PDF output due to teething problems with the asciidoctor toolchain, especially with mathematical equations. We are aware of these and working on them. Github Issues: * Updated sample code for the <<sparsememory-examples-basic,sparse resource binding example>> (public issue 97). * Modify line and point clipping behavior in the <<vertexpostproc-clipping, Primitive Clipping>> section to allow for pop-free behavior. The ability to check for which behavior is implemented may be added a future feature or extension (public issue 113). * Unify the discussions of implicit ordering throughout the spec, in particular in the new sections <<drawing-primitive-order, Primitive Order>>, <<primrast-order, Rasterization Order>>, and <<synchronization-implicit, Implicit Synchronization Guarantees>>; the discussion of <<synchronization-submission-order, submission order>>; and references elsewhere to these sections (public issue 133). * Clarify \<\<descriptorsets-compatibility,Pipeline Layout Compatibility>> language and introduce the term ``identically defined'' (public issue 164). * Add a dependency to the +VK_EXT_debug_marker+ extension that's needed to reuse the object type enum from +VK_EXT_debug_report+, and moves the definition of that enum into +VK_EXT_debug_report+ where it should be (public issue 409). * Remove redundant valid usage statement from slink:VkImageBlit (public issue 421). * Update GL_KHR_vulkan_glsl to allow the ternary operator to result in a specialization constant (public issue 424). * Fix valid usage for flink:VkPipelineShaderStageCreateInfo (public issue 426). * Correct typo in New Objects list for <<VK_EXT_debug_report>> (public issue 447). Internal Issues: * Moved to asciidoctor for spec builds (internal issue 121). * Update style guide to describe where to put new extensions-specific asciidoc files, and what to name them (internal issue 626). * Add src/spec/indexExt.py to autogenerate registry index entries linking into the 1.0-extensions specification, instead of maintaining the index manually. (internal issue 642). * Autogenerate extension dependencies and lists of all extensions and all KHR extensions from the "supported" attributes in +vk.xml+. Execute +make config/extDependency.sh+ from +doc/specs/vulkan+ when a supported extension is added to vk.xml, to regenerate the dependency script. The consequence is that specifying a single extension to the +makeExt+ script will automatically enable all extensions it depends on as well, and that the +makeAllExts+ and +makeKHR+ scripts do not need to be updated when a new extension is supported (internal issue 648). * Put extension appendices all at the same asciidoc section level, so KHR WSI extensions show up in the HTML index (internal issue 648). Other Issues: * Imbed images in the generated HTML specs instead of loading them from the images/ directory. * Fix missing EXT in extension name (ename:VK_EXT_SWAPCHAIN_COLOR_SPACE_EXTENSION_NAME). * Add new +VK_EXT_SMPTE_2086_metadata+ extension. * In the <<platformCreateSurface_xlib,Xlib Surface>> section of the +VK_KHR_xlib_surface+ specification, add language warning users that they always need to call code:XinitThreads. * Use the term "presentable image" (rather than "swapchain image") consistently in +VK_KHR_swapchain+ and related extensions, and add a glossary term defining it. * Relocate the valid usage for samples of flink:vkGetPhysicalDeviceSparseImageFormatProperties2KHR::pname:pFormatInfo to be below the flink:VkPhysicalDeviceSparseImageFormatInfo2KHR structure.
2017-02-11 04:37:39 +00:00
= Vulkan^(R)^ {revnumber} - A Specification {apititle}
Change log for March 10, 2016 Vulkan 1.0.6 spec update: * 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 &lt;&lt;interfaces-iointerfaces-locations,Location Assignment>> section (public issue 45). * Editorial fixes for &lt;&lt;commandbuffer-allocation,Command Buffer Allocation>> section (public issues 54, 59). * Clarify behavior of depth test in the &lt;&lt;fragops-depth,Depth Test&gt;&gt; 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 &lt;&lt;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 &lt;&lt;fig-non-strict-lines,Non strict lines>> diagram. Use more easily distinguished symbols in tables in the &lt;&lt;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 &lt;&lt;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.
2016-03-11 01:33:02 +00:00
The Khronos Vulkan Working Group
Change log for February 10, 2017 Vulkan 1.0.40 spec update: * Bump API patch number and header version number to 40 for this update. * There is a major build change in this release. We are now using the Ruby-based ``asciidoctor'' implementation, rather than the Python-based ``asciidoc'' implementation, to process the specification. While the actual specification markup changes were minimal, this requires a new set of build tools and a very different installation process, especially because we now use an experimental direct-to-PDF backend for Asciidoctor instead of Docbook->dblatex->PDF. It is no longer possible to build the Specification using asciidoc. See doc/specs/vulkan/README.adoc for some guidance on installing the new toolchain components. * There are some minor rendering issues in the PDF output due to teething problems with the asciidoctor toolchain, especially with mathematical equations. We are aware of these and working on them. Github Issues: * Updated sample code for the <<sparsememory-examples-basic,sparse resource binding example>> (public issue 97). * Modify line and point clipping behavior in the <<vertexpostproc-clipping, Primitive Clipping>> section to allow for pop-free behavior. The ability to check for which behavior is implemented may be added a future feature or extension (public issue 113). * Unify the discussions of implicit ordering throughout the spec, in particular in the new sections <<drawing-primitive-order, Primitive Order>>, <<primrast-order, Rasterization Order>>, and <<synchronization-implicit, Implicit Synchronization Guarantees>>; the discussion of <<synchronization-submission-order, submission order>>; and references elsewhere to these sections (public issue 133). * Clarify \<\<descriptorsets-compatibility,Pipeline Layout Compatibility>> language and introduce the term ``identically defined'' (public issue 164). * Add a dependency to the +VK_EXT_debug_marker+ extension that's needed to reuse the object type enum from +VK_EXT_debug_report+, and moves the definition of that enum into +VK_EXT_debug_report+ where it should be (public issue 409). * Remove redundant valid usage statement from slink:VkImageBlit (public issue 421). * Update GL_KHR_vulkan_glsl to allow the ternary operator to result in a specialization constant (public issue 424). * Fix valid usage for flink:VkPipelineShaderStageCreateInfo (public issue 426). * Correct typo in New Objects list for <<VK_EXT_debug_report>> (public issue 447). Internal Issues: * Moved to asciidoctor for spec builds (internal issue 121). * Update style guide to describe where to put new extensions-specific asciidoc files, and what to name them (internal issue 626). * Add src/spec/indexExt.py to autogenerate registry index entries linking into the 1.0-extensions specification, instead of maintaining the index manually. (internal issue 642). * Autogenerate extension dependencies and lists of all extensions and all KHR extensions from the "supported" attributes in +vk.xml+. Execute +make config/extDependency.sh+ from +doc/specs/vulkan+ when a supported extension is added to vk.xml, to regenerate the dependency script. The consequence is that specifying a single extension to the +makeExt+ script will automatically enable all extensions it depends on as well, and that the +makeAllExts+ and +makeKHR+ scripts do not need to be updated when a new extension is supported (internal issue 648). * Put extension appendices all at the same asciidoc section level, so KHR WSI extensions show up in the HTML index (internal issue 648). Other Issues: * Imbed images in the generated HTML specs instead of loading them from the images/ directory. * Fix missing EXT in extension name (ename:VK_EXT_SWAPCHAIN_COLOR_SPACE_EXTENSION_NAME). * Add new +VK_EXT_SMPTE_2086_metadata+ extension. * In the <<platformCreateSurface_xlib,Xlib Surface>> section of the +VK_KHR_xlib_surface+ specification, add language warning users that they always need to call code:XinitThreads. * Use the term "presentable image" (rather than "swapchain image") consistently in +VK_KHR_swapchain+ and related extensions, and add a glossary term defining it. * Relocate the valid usage for samples of flink:vkGetPhysicalDeviceSparseImageFormatProperties2KHR::pname:pFormatInfo to be below the flink:VkPhysicalDeviceSparseImageFormatInfo2KHR structure.
2017-02-11 04:37:39 +00:00
:data-uri:
:icons: font
Vulkan 1.0 branch 1.0 for release
2016-02-16 09:53:44 +00:00
:toc2:
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
:toclevels: 2
Vulkan 1.0 branch 1.0 for release
2016-02-16 09:53:44 +00:00
:max-width: 100
:numbered:
Change log for February 10, 2017 Vulkan 1.0.40 spec update: * Bump API patch number and header version number to 40 for this update. * There is a major build change in this release. We are now using the Ruby-based ``asciidoctor'' implementation, rather than the Python-based ``asciidoc'' implementation, to process the specification. While the actual specification markup changes were minimal, this requires a new set of build tools and a very different installation process, especially because we now use an experimental direct-to-PDF backend for Asciidoctor instead of Docbook->dblatex->PDF. It is no longer possible to build the Specification using asciidoc. See doc/specs/vulkan/README.adoc for some guidance on installing the new toolchain components. * There are some minor rendering issues in the PDF output due to teething problems with the asciidoctor toolchain, especially with mathematical equations. We are aware of these and working on them. Github Issues: * Updated sample code for the <<sparsememory-examples-basic,sparse resource binding example>> (public issue 97). * Modify line and point clipping behavior in the <<vertexpostproc-clipping, Primitive Clipping>> section to allow for pop-free behavior. The ability to check for which behavior is implemented may be added a future feature or extension (public issue 113). * Unify the discussions of implicit ordering throughout the spec, in particular in the new sections <<drawing-primitive-order, Primitive Order>>, <<primrast-order, Rasterization Order>>, and <<synchronization-implicit, Implicit Synchronization Guarantees>>; the discussion of <<synchronization-submission-order, submission order>>; and references elsewhere to these sections (public issue 133). * Clarify \<\<descriptorsets-compatibility,Pipeline Layout Compatibility>> language and introduce the term ``identically defined'' (public issue 164). * Add a dependency to the +VK_EXT_debug_marker+ extension that's needed to reuse the object type enum from +VK_EXT_debug_report+, and moves the definition of that enum into +VK_EXT_debug_report+ where it should be (public issue 409). * Remove redundant valid usage statement from slink:VkImageBlit (public issue 421). * Update GL_KHR_vulkan_glsl to allow the ternary operator to result in a specialization constant (public issue 424). * Fix valid usage for flink:VkPipelineShaderStageCreateInfo (public issue 426). * Correct typo in New Objects list for <<VK_EXT_debug_report>> (public issue 447). Internal Issues: * Moved to asciidoctor for spec builds (internal issue 121). * Update style guide to describe where to put new extensions-specific asciidoc files, and what to name them (internal issue 626). * Add src/spec/indexExt.py to autogenerate registry index entries linking into the 1.0-extensions specification, instead of maintaining the index manually. (internal issue 642). * Autogenerate extension dependencies and lists of all extensions and all KHR extensions from the "supported" attributes in +vk.xml+. Execute +make config/extDependency.sh+ from +doc/specs/vulkan+ when a supported extension is added to vk.xml, to regenerate the dependency script. The consequence is that specifying a single extension to the +makeExt+ script will automatically enable all extensions it depends on as well, and that the +makeAllExts+ and +makeKHR+ scripts do not need to be updated when a new extension is supported (internal issue 648). * Put extension appendices all at the same asciidoc section level, so KHR WSI extensions show up in the HTML index (internal issue 648). Other Issues: * Imbed images in the generated HTML specs instead of loading them from the images/ directory. * Fix missing EXT in extension name (ename:VK_EXT_SWAPCHAIN_COLOR_SPACE_EXTENSION_NAME). * Add new +VK_EXT_SMPTE_2086_metadata+ extension. * In the <<platformCreateSurface_xlib,Xlib Surface>> section of the +VK_KHR_xlib_surface+ specification, add language warning users that they always need to call code:XinitThreads. * Use the term "presentable image" (rather than "swapchain image") consistently in +VK_KHR_swapchain+ and related extensions, and add a glossary term defining it. * Relocate the valid usage for samples of flink:vkGetPhysicalDeviceSparseImageFormatProperties2KHR::pname:pFormatInfo to be below the flink:VkPhysicalDeviceSparseImageFormatInfo2KHR structure.
2017-02-11 04:37:39 +00:00
:source-highlighter: coderay
Change log for September 30, 2016 Vulkan 1.0.29 spec update: * Bump API patch number and header version number to 29 for this update. Github Issues: * Remove redundant constraint on slink:VkCommandBufferInheritanceInfo::pname:queryFlags (public issue 224). * Fix typo and remove link in Note in the <<extended-functionality-instance-extensions-and-devices, Instance Extensions and Device Extensions>> section (public issue 359). * Fix erroneous validation statement for the pname:layout member of slink:VkComputePipelineCreateInfo (public issue 362). Internal Issues: * Restore long figure captions using asciidoc sidebar blocks, due to restrictions of asciidoc syntax (internal issue 101). * Replace most latexmath equations with comparable markup in straight asciidoc, which significantly improves time required to fully load and process the HTML forms of the Specification. There are known minor font and alignment inconsistencies with MathJax and PDF rendering of latexmath equations. Please do not file github issues about these. We are aware of the inconsistencies and will make refinements over time, while the performance improvements are compelling in at least some major browsers (internal issue 313). * Move handcoded validity statements from +vk.xml+ into the Specification body, easing work in the single-branch model. Specify the distinction between these explicit statements, and the implicit validity statements inferred from vk.xml. Validity statements now appear in two blocks for each command and structure - handcoded "Valid Usage" and the implicit "Valid Usage (Implicit)" (internal issue 392). * Add the +returnedonly="false"+ attribute to WSI output structures, removing incorrectly generated implicit validity statements for slink:VkDisplayPropertiesKHR, slink:VkDisplayPlanePropertiesKHR, slink:VkDisplayModePropertiesKHR, slink:VkDisplayPlaneCapabilitiesKHR, slink:VkSurfaceCapabilitiesKHR, and slink:VkSurfaceFormatKHR structures (internal issue 486). * Update slink:VkImageLayout to require the ename:VK_IMAGE_USAGE_SAMPLED_BIT be set for sampled depth/stencil images (internal issue 487). * Use an explicit format specifier string for the date command invocation in the +Makefile+ instead of the shorthand -R option, which doesn't work on BSD and MaxOS X date commands (internal issue 500). Other Issues: * Use the terms ``allocation scope'' and ``extension scope'' instead of just ``scope'', and add them to the glossary.
2016-10-01 04:13:37 +00:00
// Various special / math symbols. This is easier to edit with than Unicode.
include::config/attribs.txt[]
Vulkan 1.0 branch 1.0 for release
2016-02-16 09:53:44 +00:00
//:editing-notes:
<<<<
Change log for September 23, 2016 Vulkan 1.0.28 spec update: * Bump API patch number and header version number to 28 for this update. Github Issues: * Minor spelling and typography cleanup, add definitions of ename:VK_FALSE and ename:VK_TRUE as just what their names say (public issues 220, 318, 325, 365; internal issues 451, 496) * Clarify that the pname:maxDescriptorSet limits in the <<features-limits-required,Required Limits>> table are n * maxPerStage limit (where n=number of supported stages) (public issue 254). * Minor cleanup to <<boilerplate-platform-macros,Platform-Specific Macro Definitions>> appendix (public issue 314). * Add valid usage statement to slink:VkPipelineLayoutCreateInfo disallowing multiple push constant ranges for the same shader stage (public issue 340). * Clarify the elink:VkSharingMode description of what executing the "same" barriers means in case of ownership transfer (public issue 347). * Rename copyright.txt and add COPYING.md to try and reduce confusion about applicable copyrights (public issue 350). * Extend the table in the <<boilerplate-wsi-header, Window System-Specific Header Control>> section to describe the external headers included when each etext:VK_USE_PLATFORM_* macro is defined (public issue 376). Internal Issues: * Add "Revision History" to the PDF outputs following the table of contents, to match HTML outputs (internal issue 43). * Clarified that flink:vkMapMemory may fail due to virtual address space limitations (internal issue 346). * Add +refBody+ comment markup for ref page autoextraction when required (internal issue 400). * Document proper use of "mipmap" and "mip" in the style guide API naming rules, matching the spelling rules (internal issue 471). * Tweak the <<extensions,Layers and Extensions>> appendix to note that the Specification may be built with arbitrary combinations of extensions (internal issue 483). * Remove incorrect statement allowing slink:VkClearAttachment::pname:colorAttachment to be >= slink:VkSubpassDescription::pname:colorAttachmentCount (internal issue 488). * The <<features-limits-viewportboundsrange,viewportBoundsRange>> is expressed in terms of the pname:maxViewportDimensions but this is actually two values. Clarify that it's based on the larger of the two (if they differ) (internal issue 499). Other Issues: * Reflowed text of the entire spec using the 'reflow' Makefile gater, to (hopefully) reduce future internal git churn as edits are made and extensions added in return for one-time pain. This has no perceptible change on the spec outputs but considerable changes on the asciidoc source (internal issue 367).
2016-09-24 07:58:11 +00:00
include::copyright-spec.txt[]
Vulkan 1.0 branch 1.0 for release
2016-02-16 09:53:44 +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
// Table of contents is inserted here
toc::[]
Vulkan 1.0 branch 1.0 for release
2016-02-16 09:53:44 +00:00
:leveloffset: 1
Change log for September 30, 2016 Vulkan 1.0.29 spec update: * Bump API patch number and header version number to 29 for this update. Github Issues: * Remove redundant constraint on slink:VkCommandBufferInheritanceInfo::pname:queryFlags (public issue 224). * Fix typo and remove link in Note in the <<extended-functionality-instance-extensions-and-devices, Instance Extensions and Device Extensions>> section (public issue 359). * Fix erroneous validation statement for the pname:layout member of slink:VkComputePipelineCreateInfo (public issue 362). Internal Issues: * Restore long figure captions using asciidoc sidebar blocks, due to restrictions of asciidoc syntax (internal issue 101). * Replace most latexmath equations with comparable markup in straight asciidoc, which significantly improves time required to fully load and process the HTML forms of the Specification. There are known minor font and alignment inconsistencies with MathJax and PDF rendering of latexmath equations. Please do not file github issues about these. We are aware of the inconsistencies and will make refinements over time, while the performance improvements are compelling in at least some major browsers (internal issue 313). * Move handcoded validity statements from +vk.xml+ into the Specification body, easing work in the single-branch model. Specify the distinction between these explicit statements, and the implicit validity statements inferred from vk.xml. Validity statements now appear in two blocks for each command and structure - handcoded "Valid Usage" and the implicit "Valid Usage (Implicit)" (internal issue 392). * Add the +returnedonly="false"+ attribute to WSI output structures, removing incorrectly generated implicit validity statements for slink:VkDisplayPropertiesKHR, slink:VkDisplayPlanePropertiesKHR, slink:VkDisplayModePropertiesKHR, slink:VkDisplayPlaneCapabilitiesKHR, slink:VkSurfaceCapabilitiesKHR, and slink:VkSurfaceFormatKHR structures (internal issue 486). * Update slink:VkImageLayout to require the ename:VK_IMAGE_USAGE_SAMPLED_BIT be set for sampled depth/stencil images (internal issue 487). * Use an explicit format specifier string for the date command invocation in the +Makefile+ instead of the shorthand -R option, which doesn't work on BSD and MaxOS X date commands (internal issue 500). Other Issues: * Use the terms ``allocation scope'' and ``extension scope'' instead of just ``scope'', and add them to the glossary.
2016-10-01 04:13:37 +00:00
:test: 0
ifeval::["{test}"=="1"]
Change log for February 10, 2017 Vulkan 1.0.40 spec update: * Bump API patch number and header version number to 40 for this update. * There is a major build change in this release. We are now using the Ruby-based ``asciidoctor'' implementation, rather than the Python-based ``asciidoc'' implementation, to process the specification. While the actual specification markup changes were minimal, this requires a new set of build tools and a very different installation process, especially because we now use an experimental direct-to-PDF backend for Asciidoctor instead of Docbook->dblatex->PDF. It is no longer possible to build the Specification using asciidoc. See doc/specs/vulkan/README.adoc for some guidance on installing the new toolchain components. * There are some minor rendering issues in the PDF output due to teething problems with the asciidoctor toolchain, especially with mathematical equations. We are aware of these and working on them. Github Issues: * Updated sample code for the <<sparsememory-examples-basic,sparse resource binding example>> (public issue 97). * Modify line and point clipping behavior in the <<vertexpostproc-clipping, Primitive Clipping>> section to allow for pop-free behavior. The ability to check for which behavior is implemented may be added a future feature or extension (public issue 113). * Unify the discussions of implicit ordering throughout the spec, in particular in the new sections <<drawing-primitive-order, Primitive Order>>, <<primrast-order, Rasterization Order>>, and <<synchronization-implicit, Implicit Synchronization Guarantees>>; the discussion of <<synchronization-submission-order, submission order>>; and references elsewhere to these sections (public issue 133). * Clarify \<\<descriptorsets-compatibility,Pipeline Layout Compatibility>> language and introduce the term ``identically defined'' (public issue 164). * Add a dependency to the +VK_EXT_debug_marker+ extension that's needed to reuse the object type enum from +VK_EXT_debug_report+, and moves the definition of that enum into +VK_EXT_debug_report+ where it should be (public issue 409). * Remove redundant valid usage statement from slink:VkImageBlit (public issue 421). * Update GL_KHR_vulkan_glsl to allow the ternary operator to result in a specialization constant (public issue 424). * Fix valid usage for flink:VkPipelineShaderStageCreateInfo (public issue 426). * Correct typo in New Objects list for <<VK_EXT_debug_report>> (public issue 447). Internal Issues: * Moved to asciidoctor for spec builds (internal issue 121). * Update style guide to describe where to put new extensions-specific asciidoc files, and what to name them (internal issue 626). * Add src/spec/indexExt.py to autogenerate registry index entries linking into the 1.0-extensions specification, instead of maintaining the index manually. (internal issue 642). * Autogenerate extension dependencies and lists of all extensions and all KHR extensions from the "supported" attributes in +vk.xml+. Execute +make config/extDependency.sh+ from +doc/specs/vulkan+ when a supported extension is added to vk.xml, to regenerate the dependency script. The consequence is that specifying a single extension to the +makeExt+ script will automatically enable all extensions it depends on as well, and that the +makeAllExts+ and +makeKHR+ scripts do not need to be updated when a new extension is supported (internal issue 648). * Put extension appendices all at the same asciidoc section level, so KHR WSI extensions show up in the HTML index (internal issue 648). Other Issues: * Imbed images in the generated HTML specs instead of loading them from the images/ directory. * Fix missing EXT in extension name (ename:VK_EXT_SWAPCHAIN_COLOR_SPACE_EXTENSION_NAME). * Add new +VK_EXT_SMPTE_2086_metadata+ extension. * In the <<platformCreateSurface_xlib,Xlib Surface>> section of the +VK_KHR_xlib_surface+ specification, add language warning users that they always need to call code:XinitThreads. * Use the term "presentable image" (rather than "swapchain image") consistently in +VK_KHR_swapchain+ and related extensions, and add a glossary term defining it. * Relocate the valid usage for samples of flink:vkGetPhysicalDeviceSparseImageFormatProperties2KHR::pname:pFormatInfo to be below the flink:VkPhysicalDeviceSparseImageFormatInfo2KHR structure.
2017-02-11 04:37:39 +00:00
// include::config/mathtest.txt[]
Change log for January 23, 2017 Vulkan 1.0.39 spec update: * Bump API patch number and header version number to 39 for this update. Github Issues: * Clarified that only accesses via the specified buffer/image subresource ranges are included in the access scopes (public issue 306). * Add missing valid usage statements for flink:vkCreateComputePipelines and flink:vkCreateGraphicsPipelines (public issue 427). Internal Issues: * Add a Note to the <<invariance,Invariance>> appendix about a difference between OpenGL and Vulkan with regards to how primitives derived from offsets are handled (internal issue 355). * Add the +<<VK_KHR_get_physical_device_properties2>>+, +<<VK_KHR_maintenance1>>+, and +<<VK_KHR_shader_draw_parameters>>+ extensions (internal issue 448). * Add the +<<VK_EXT_shader_subgroup_vote>>+ and +<<VK_EXT_shader_subgroup_ballot>>+ extensions (internal issue 449). * Update the texture level-of-detail equation in the <<textures-scale-factor,Scale Factor Operation>> section to better approximate the ellipse major and minor axes (internal issue 547). * Forbid non-explicitly allowed uses of interface decorations in the introduction to the <<interfaces,Shader Interfaces>> chapter (internal issue 607). * Replace use of MathJax with KaTeX, for improved load-time performance as well as avoiding the scrolling-and-scrolling behavior due to MathJax asynchronous rendering when loading at an anchor inside the spec. This change also requires moving to HTML5 output for the spec instead of XHTML, and there is a visible difference in that the chapter navigation index is now in a scrollable sidebar instead of at the top of the document. We may or may not retain the nav sidebar based on feedback (internal issue 613). * Improve consistency of markup and formatting in extension appendices (internal issue 631). Other Issues: * Add explicit valid usage statements to slink:VkImageCopy requiring that the source and destination layer ranges be contained in their respective source and destination images. * Add valid usage language for swapchain of flink:vkAcquireNextImage. If the swapchain has been replaced, then it should not be passed to flink:vkAcquireNextImage. * Add a valid usage statement to flink:vkCreateImageView, that the image must have been created with an appropriate usage bit set. * Noted that slink:VkDisplayPresentInfoKHR is a valid extension of slink:VkPresentInfoKHR in the <<wsi_swapchain,WSI Swapchain>> section. * Update valid usage for flink:vkCmdSetViewport and flink:vkCmdSetScissor to account for the multiple viewport feature. If the feature is not enabled, the parameters for these functions have required values that are defined in the <<features-features-multiViewport,multiple viewports>> section of the spec but were not reflected in the valid usage text for these functions. * Add the +<<VK_EXT_swapchain_colorspace>>+ extension defining common color spaces.
2017-01-18 04:11:25 +00:00
include::chapters/fundamentals.txt[]
Change log for February 10, 2017 Vulkan 1.0.40 spec update: * Bump API patch number and header version number to 40 for this update. * There is a major build change in this release. We are now using the Ruby-based ``asciidoctor'' implementation, rather than the Python-based ``asciidoc'' implementation, to process the specification. While the actual specification markup changes were minimal, this requires a new set of build tools and a very different installation process, especially because we now use an experimental direct-to-PDF backend for Asciidoctor instead of Docbook->dblatex->PDF. It is no longer possible to build the Specification using asciidoc. See doc/specs/vulkan/README.adoc for some guidance on installing the new toolchain components. * There are some minor rendering issues in the PDF output due to teething problems with the asciidoctor toolchain, especially with mathematical equations. We are aware of these and working on them. Github Issues: * Updated sample code for the <<sparsememory-examples-basic,sparse resource binding example>> (public issue 97). * Modify line and point clipping behavior in the <<vertexpostproc-clipping, Primitive Clipping>> section to allow for pop-free behavior. The ability to check for which behavior is implemented may be added a future feature or extension (public issue 113). * Unify the discussions of implicit ordering throughout the spec, in particular in the new sections <<drawing-primitive-order, Primitive Order>>, <<primrast-order, Rasterization Order>>, and <<synchronization-implicit, Implicit Synchronization Guarantees>>; the discussion of <<synchronization-submission-order, submission order>>; and references elsewhere to these sections (public issue 133). * Clarify \<\<descriptorsets-compatibility,Pipeline Layout Compatibility>> language and introduce the term ``identically defined'' (public issue 164). * Add a dependency to the +VK_EXT_debug_marker+ extension that's needed to reuse the object type enum from +VK_EXT_debug_report+, and moves the definition of that enum into +VK_EXT_debug_report+ where it should be (public issue 409). * Remove redundant valid usage statement from slink:VkImageBlit (public issue 421). * Update GL_KHR_vulkan_glsl to allow the ternary operator to result in a specialization constant (public issue 424). * Fix valid usage for flink:VkPipelineShaderStageCreateInfo (public issue 426). * Correct typo in New Objects list for <<VK_EXT_debug_report>> (public issue 447). Internal Issues: * Moved to asciidoctor for spec builds (internal issue 121). * Update style guide to describe where to put new extensions-specific asciidoc files, and what to name them (internal issue 626). * Add src/spec/indexExt.py to autogenerate registry index entries linking into the 1.0-extensions specification, instead of maintaining the index manually. (internal issue 642). * Autogenerate extension dependencies and lists of all extensions and all KHR extensions from the "supported" attributes in +vk.xml+. Execute +make config/extDependency.sh+ from +doc/specs/vulkan+ when a supported extension is added to vk.xml, to regenerate the dependency script. The consequence is that specifying a single extension to the +makeExt+ script will automatically enable all extensions it depends on as well, and that the +makeAllExts+ and +makeKHR+ scripts do not need to be updated when a new extension is supported (internal issue 648). * Put extension appendices all at the same asciidoc section level, so KHR WSI extensions show up in the HTML index (internal issue 648). Other Issues: * Imbed images in the generated HTML specs instead of loading them from the images/ directory. * Fix missing EXT in extension name (ename:VK_EXT_SWAPCHAIN_COLOR_SPACE_EXTENSION_NAME). * Add new +VK_EXT_SMPTE_2086_metadata+ extension. * In the <<platformCreateSurface_xlib,Xlib Surface>> section of the +VK_KHR_xlib_surface+ specification, add language warning users that they always need to call code:XinitThreads. * Use the term "presentable image" (rather than "swapchain image") consistently in +VK_KHR_swapchain+ and related extensions, and add a glossary term defining it. * Relocate the valid usage for samples of flink:vkGetPhysicalDeviceSparseImageFormatProperties2KHR::pname:pFormatInfo to be below the flink:VkPhysicalDeviceSparseImageFormatInfo2KHR structure.
2017-02-11 04:37:39 +00:00
Change log for March 7, 2018 Vulkan 1.1.70 spec update: * Vulkan 1.1 initial release. Bump API patch number and header version number to 70 for this update. The patch number will be used for both Vulkan 1.1 and Vulkan 1.0 updates, and continues to increment continuously from the previous Vulkan 1.0.69 update. NOTE: We are not publishing an updated 1.0.70 specification, or 1.1 reference pages, along with 1.1.70. There are still minor issues to work out with those build targets. However, we will soon generate all three types of documents as part of the regular spec update cycle. NOTE: The GitHub KhronosGroup/Vulkan-Docs repository now maintains the current specification in the `master` branch. The `1.0` branch is out of date and will not be maintained, since we will be generating both 1.1 and 1.0 specifications from the `master` branch in the future. Github Issues: * Clarify how mapped memory ranges are flushed in flink:vkFlushMappedMemoryRanges (public issue 127). * Specify that <<synchronization-pipeline-stages, Pipeline Stages>> are a list of tasks that each command performs, rather than necessarily being discrete pieces of hardware that one task flows through. Add a "`synchronization command`" pipeline type which all synchronization command execute (it's just TOP + BOTTOM), with an explanatory note (public issue 554). Internal Issues: * Regenerate all images used in the spec in Inkscape with a consistent look-and-feel, and adjust image size attributes so they're all legible, and not too large with respect to the spec body text (internal issue 701). * Document in the <<extensions,extensions>> appendix and in the style guide that `KHX` extensions are no longer supported or used in the Vulkan 1.1 timeframe (internal issue 714). * Remove the leftover equations_temp directory after PDF build completes (internal issue 925). * Update the <<credits, Credits (Informative)>> appendix to include contributors to Vulkan 1.1, and to list them according to the API version(s) they contributed to (internal issue 987). * Add a NOTE to the introduction explaining that interfaces defined by extensions which were promoted to Vulkan 1.1 are now expressed as aliases of the Vulkan 1.1 type (internal issue 991). * Instrument spec source conditionals so spec can be built with 1.1 features, extensions promoted to 1.1, or both (internal issues 992, 998). * Modify the XML schema and tools to support explicit aliasing of types, structures, and commands, and use this to express the promotion of 1.0 extensions to 1.1 core features, by making the extension interfaces aliases of the core features they were promoted to. Mark up promoted interfaces to allow still generating 1.0 + extension specifications (internal issue 991). * Platform names, along with corresponding preprocessor symbols to enable extensions specific to those platforms, are now reserved in vk.xml using the <platform> tag. Update the registry schema and schema specification to match (internal issue 1011). * Updated the <<textures-texel-replacement, Texel Replacement>> section to clarify that reads from invalid texels for image resources result in undefined values (internal issue 1014). * Modify description of patch version so it continues to increment across minor version changes (internal issue 1033). * Clarify and unify language describing physical device-level core and extension functionality in the <<fundamentals-validusage-extensions, Valid Usage for Extensions>>, <<fundamentals-validusage-versions, Valid Usage for Newer Core Versions>>, <<initialization-functionpointers Command Function Pointers>>, <<initialization-phys-dev-extensions, Extending Physical Device From Device Extensions>> <<extended-functionality-instance-extensions-and-devices, Instance Extensions and Device Extensions>> sections and for flink:vkGetPhysicalDeviceImageFormatProperties2. This documents that instance-level functionality is tied to the loader, and independent of the ICD; physical device-level functionality is tied to the ICD, and associated with device extensions; physical devices are treated more uniformly between core and extensions; and instance and physical versions can be different (internal issue 1048). * Updated the <<commandbuffers-lifecycle, Command Buffer Lifecycle>> section to clarify the ability for pending command buffers to transition to the invalid state after submission, and add a command buffer lifecycle diagram (internal issue 1050). * Clarify that some flink:VkDescriptorUpdateTemplateCreateInfo parameters are ignored when push descriptors are not supported (internal issue 1054). * Specify that flink:vkCreateImage will return an error if the image is too large, in a NOTE in the slink:VkImageFormatProperties description (internal issue 1078). * Remove near-duplicate NOTEs about when to query function pointers dynamically in the <<initialization, Initialization>> chapter and replace by extending the NOTE in the <<fundamentals-abi, Application Binary Interface>> section (internal issue 1085). * Restore missing references to "`Sparse Resource Features`" in the flink:VkBufferCreateFlagBits description (internal issue 1086). * Tidy up definitions of descriptor types in the `GL_KHR_vulkan_glsl` specification, the <<descriptorsets, Resource Descriptors>> section and its subsections, and the <<interfaces-resources-descset, Descriptor Set Interface>> for consistency, reduction of duplicate information, and removal of GLSL correspondance/examples (internal issue 1090). * Correctly describe code:PrimitiveId as an Input for tessellation control and evaluation shaders, not an Output (internal issue 1109). * Relax the requirements on chroma offsets for nearest filtering in <<textures-implict-reconstruction, Implicit Reconstruction>> (internal issue 1116). Other Issues: * Clarify the intended relationship between specification language and certain terms defined in the Khronos Intellectual Property Rights policy. Specific changes include: ** Rewrote IP/Copyright preamble and introduction to better agree with normative language both as laid out in the introduction, and the Khronos IPR policy. ** Added notion of fully informative sections, which are now tagged with "`(Informative)`" in their titles. ** Removed non-normative uses of the phrase "`not required`" ** Clarified the distinction between terms "`optional`" and "`not required:`" as they relate to the IPR Policy, and updated specification text to use terms consistent with the intent. ** Reduced additions to RFC 2119, and ensured the specification agreed with the leaner language. ** Removed the terms "`hardware`", "`software`", "`CPU`", and "`GPU`" from normative text. ** Moved several paragraphs that should not have been normative to informative notes. ** Clarified a number of definitions in the Glossary. ** Updated the document writing guide to match new terminology changes. * Explicitly state in the <<fundamentals-objectmodel-lifetime-acquire, application memory lifetime>> language that that for objects other than descriptor sets, a slink:VkDescriptorSetLayout object used in the creation of another object (such as slink:VkPipelineLayout or slink:VkDescriptorUpdateTemplateKHR) is only in use during the creation of that object and can be safely destroyed afterwards. * Updated the <<textures-scale-factor, Scale Factor Operation>> section to use the ratio of anisotropy, rather than the integer sample rate, to perform the LOD calculation. The spec still allows use of the sample rate as the value used to calculate the LOD, but no longer requires it. * Update `vulkan_ext.c` to include all platform-related definitions from the Vulkan platform headers, following the split of the headers into platform-specific and non-platform-specific files. * Fix bogus anchor name in the <<commandbuffers, Command Buffers>> chapter which accidentally duplicated an anchor in the pipelines chapter. There were no reference to this anchor, fortunately. * Add valid usage statement for slink:VkWriteDescriptorSet and slink:VkCopyDescriptorSet requiring that the slink:VkDescriptorSetLayout used to allocate the source and destination sets must not have been destroyed at the time flink:vkUpdateDescriptorSets is called. * Document mapping of subgroup barrier functions to SPIR-V, and clarify a place where subgroupBarrier sounds like it's execution-only in the standalone `GL_KHR_shader_subgroup` specification. * Use an HTML stylesheet derived from the Asciidoctor `colony` theme, with the default Arial font family replaced by the sans-serif Noto font family. * Numerous minor updates to README.adoc, build scripts, Makefiles, and registry and style guide specifications to support Vulkan 1.1 outputs, use them as defaults, and remove mention of `KHX` extensions, which are no longer supported. New Extensions: * `VK_EXT_vertex_attrib_divisor`
2018-03-07 12:18:52 +00:00
include::chapters/memory.txt[]
Change log for September 30, 2016 Vulkan 1.0.29 spec update: * Bump API patch number and header version number to 29 for this update. Github Issues: * Remove redundant constraint on slink:VkCommandBufferInheritanceInfo::pname:queryFlags (public issue 224). * Fix typo and remove link in Note in the <<extended-functionality-instance-extensions-and-devices, Instance Extensions and Device Extensions>> section (public issue 359). * Fix erroneous validation statement for the pname:layout member of slink:VkComputePipelineCreateInfo (public issue 362). Internal Issues: * Restore long figure captions using asciidoc sidebar blocks, due to restrictions of asciidoc syntax (internal issue 101). * Replace most latexmath equations with comparable markup in straight asciidoc, which significantly improves time required to fully load and process the HTML forms of the Specification. There are known minor font and alignment inconsistencies with MathJax and PDF rendering of latexmath equations. Please do not file github issues about these. We are aware of the inconsistencies and will make refinements over time, while the performance improvements are compelling in at least some major browsers (internal issue 313). * Move handcoded validity statements from +vk.xml+ into the Specification body, easing work in the single-branch model. Specify the distinction between these explicit statements, and the implicit validity statements inferred from vk.xml. Validity statements now appear in two blocks for each command and structure - handcoded "Valid Usage" and the implicit "Valid Usage (Implicit)" (internal issue 392). * Add the +returnedonly="false"+ attribute to WSI output structures, removing incorrectly generated implicit validity statements for slink:VkDisplayPropertiesKHR, slink:VkDisplayPlanePropertiesKHR, slink:VkDisplayModePropertiesKHR, slink:VkDisplayPlaneCapabilitiesKHR, slink:VkSurfaceCapabilitiesKHR, and slink:VkSurfaceFormatKHR structures (internal issue 486). * Update slink:VkImageLayout to require the ename:VK_IMAGE_USAGE_SAMPLED_BIT be set for sampled depth/stencil images (internal issue 487). * Use an explicit format specifier string for the date command invocation in the +Makefile+ instead of the shorthand -R option, which doesn't work on BSD and MaxOS X date commands (internal issue 500). Other Issues: * Use the terms ``allocation scope'' and ``extension scope'' instead of just ``scope'', and add them to the glossary.
2016-10-01 04:13:37 +00:00
endif::[]
ifeval::["{test}"!="1"]
Vulkan 1.0 branch 1.0 for release
2016-02-16 09:53:44 +00:00
include::chapters/introduction.txt[]
include::chapters/fundamentals.txt[]
include::chapters/initialization.txt[]
include::chapters/devsandqueues.txt[]
include::chapters/cmdbuffers.txt[]
include::chapters/synchronization.txt[]
include::chapters/renderpass.txt[]
include::chapters/shaders.txt[]
include::chapters/pipelines.txt[]
include::chapters/memory.txt[]
include::chapters/resources.txt[]
include::chapters/samplers.txt[]
include::chapters/descriptorsets.txt[]
include::chapters/interfaces.txt[]
include::chapters/textures.txt[]
include::chapters/queries.txt[]
// Transfer operations
include::chapters/clears.txt[]
include::chapters/copies.txt[]
// Graphics Operations
include::chapters/drawing.txt[]
include::chapters/fxvertex.txt[]
include::chapters/tessellation.txt[]
include::chapters/geometry.txt[]
include::chapters/vertexpostproc.txt[]
include::chapters/primsrast.txt[]
include::chapters/fragops.txt[]
include::chapters/framebuffer.txt[]
// Compute
include::chapters/dispatch.txt[]
Change log for November 25, 2016 Vulkan 1.0.35 spec update: * Bump API patch number and header version number to 35 for this update. Github Issues: * Document in the <<memory-device-hostaccess,Host Access>> section that mapping and unmapping does not invalidate or flush the mapped memory (public issues 27, 126). * Redefine the entire <<synchronization>> chapter in terms of consistent and well defined terminology, that's called out at the start of the chapter. This terminology is applied equally to all synchronization types, including subpass dependencies, submissions, and much of the implicit ordering stuff dotted around the spec. Key terms are laid out in the <<synchronization-dependencies,Execution and Memory Dependencies>> section at the top of the rewritten chapter (public issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407). * Specify order of submission for batches in the <<vkQueueSubmit,vkQueueSubmit>> and <<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371). * Add valid usage statements to each of the WSI extension sections indicating that the WSI-specific structure parameters must be valid, and remove automatically generated valid usage statements now covered by the manual sections (public issue 383). * Clarify render pass compatibility for flink:vkCmdExecuteCommands (public issue 390). Internal Issues: * Update +vk.xml+ to make previously explicit valid usage statements for <<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead (internal issue 553). * Add valid usage statement for slink:VkCreateImageInfo preventing creation of 1D sparse images (internal issue 573). * Fix Python scripts to always read/write files in utf-8 encoding, and a logic error in reflib.py which could cause a fatal error for malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
// Device Generated Commands
ifdef::VK_NVX_device_generated_commands[]
include::chapters/VK_NVX_device_generated_commands/generatedcommands.txt[]
endif::VK_NVX_device_generated_commands[]
Vulkan 1.0 branch 1.0 for release
2016-02-16 09:53:44 +00:00
// Sparse
include::chapters/sparsemem.txt[]
Change log for August 26, 2016 Vulkan 1.0.25 spec update: * Bump API patch number and header version number to 25 for this update. * Structurally change the specification so that multiple extensions are included in the +1.0+ git branch, and specifications will include or not include those extensions at build time based on options passed to the Makefile. See +doc/specs/vulkan/README.html+ and the ``Layers and Extensions'' section of the ``Vulkan Documentation and Extensions'' document for more information on this change. * Register and publish new extensions in the single-branch form: ** +VK_NV_external_memory_capabilities+ ** +VK_NV_external_memory+ ** +VK_NV_external_memory_win32+ ** +VK_NV_win32_keyed_mutex+ Github Issues: * Clarify description of GetInstanceProcAddr and GetDeviceProcAddr (public issue 212). * Add SPIR-V <<textures-operation-validation, instruction validation>> for single-sampled images (public issue 316). * Fix spelling of ``tesselation'' in a few places and note it as an exception to the American spelling rules convention (public issue 327). * Fix Makefile to create output directory for ``styleguide'' target (public issue 329). * Fix numerous minor issues with incorrectly tags on enumerant names and table titles (public issue 330). * Generate specversion.txt date in UTC time and RFC 2822 format (public issue 335). * Convert link to the SPIR-V Specification for flink:VkShaderModuleCreateInfo into an internal link to the normative reference (public issue 336). * Add ename:VK_ERROR_OUT_OF_MEMORY error code to flink:vkCreateDebugReportCallbackEXT (public issue 337). Internal Issues: * Update style guide regarding use of code:NULL and dname:VK_NULL_HANDLE (internal issue 393). * Change the definition of latexmath:[$q$] in the <<textures-image-level-selection,texture image level selection>> section to be the index of the maximum defined level for the view, not the number of levels in the view (internal issue 406). * Allow developers to override dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE with their own binary-compatible definition (internal issue 439). * Fix +vk_platform.h+ conditional logic causing compile failure with some Android compilers (internal issue 441). * Implement the single-branch model as described above (internal issue 461). Other Issues:
2016-08-28 10:47:19 +00:00
ifdef::VK_KHR_surface[]
include::chapters/VK_KHR_surface/wsi.txt[]
endif::VK_KHR_surface[]
Vulkan 1.0 branch 1.0 for release
2016-02-16 09:53:44 +00:00
// Sort of an appendix
include::chapters/extensions.txt[]
include::chapters/features.txt[]
Change log for September 23, 2016 Vulkan 1.0.28 spec update: * Bump API patch number and header version number to 28 for this update. Github Issues: * Minor spelling and typography cleanup, add definitions of ename:VK_FALSE and ename:VK_TRUE as just what their names say (public issues 220, 318, 325, 365; internal issues 451, 496) * Clarify that the pname:maxDescriptorSet limits in the <<features-limits-required,Required Limits>> table are n * maxPerStage limit (where n=number of supported stages) (public issue 254). * Minor cleanup to <<boilerplate-platform-macros,Platform-Specific Macro Definitions>> appendix (public issue 314). * Add valid usage statement to slink:VkPipelineLayoutCreateInfo disallowing multiple push constant ranges for the same shader stage (public issue 340). * Clarify the elink:VkSharingMode description of what executing the "same" barriers means in case of ownership transfer (public issue 347). * Rename copyright.txt and add COPYING.md to try and reduce confusion about applicable copyrights (public issue 350). * Extend the table in the <<boilerplate-wsi-header, Window System-Specific Header Control>> section to describe the external headers included when each etext:VK_USE_PLATFORM_* macro is defined (public issue 376). Internal Issues: * Add "Revision History" to the PDF outputs following the table of contents, to match HTML outputs (internal issue 43). * Clarified that flink:vkMapMemory may fail due to virtual address space limitations (internal issue 346). * Add +refBody+ comment markup for ref page autoextraction when required (internal issue 400). * Document proper use of "mipmap" and "mip" in the style guide API naming rules, matching the spelling rules (internal issue 471). * Tweak the <<extensions,Layers and Extensions>> appendix to note that the Specification may be built with arbitrary combinations of extensions (internal issue 483). * Remove incorrect statement allowing slink:VkClearAttachment::pname:colorAttachment to be >= slink:VkSubpassDescription::pname:colorAttachmentCount (internal issue 488). * The <<features-limits-viewportboundsrange,viewportBoundsRange>> is expressed in terms of the pname:maxViewportDimensions but this is actually two values. Clarify that it's based on the larger of the two (if they differ) (internal issue 499). Other Issues: * Reflowed text of the entire spec using the 'reflow' Makefile gater, to (hopefully) reduce future internal git churn as edits are made and extensions added in return for one-time pain. This has no perceptible change on the spec outputs but considerable changes on the asciidoc source (internal issue 367).
2016-09-24 07:58:11 +00:00
include::chapters/debugging.txt[]
Change log for August 26, 2016 Vulkan 1.0.25 spec update: * Bump API patch number and header version number to 25 for this update. * Structurally change the specification so that multiple extensions are included in the +1.0+ git branch, and specifications will include or not include those extensions at build time based on options passed to the Makefile. See +doc/specs/vulkan/README.html+ and the ``Layers and Extensions'' section of the ``Vulkan Documentation and Extensions'' document for more information on this change. * Register and publish new extensions in the single-branch form: ** +VK_NV_external_memory_capabilities+ ** +VK_NV_external_memory+ ** +VK_NV_external_memory_win32+ ** +VK_NV_win32_keyed_mutex+ Github Issues: * Clarify description of GetInstanceProcAddr and GetDeviceProcAddr (public issue 212). * Add SPIR-V <<textures-operation-validation, instruction validation>> for single-sampled images (public issue 316). * Fix spelling of ``tesselation'' in a few places and note it as an exception to the American spelling rules convention (public issue 327). * Fix Makefile to create output directory for ``styleguide'' target (public issue 329). * Fix numerous minor issues with incorrectly tags on enumerant names and table titles (public issue 330). * Generate specversion.txt date in UTC time and RFC 2822 format (public issue 335). * Convert link to the SPIR-V Specification for flink:VkShaderModuleCreateInfo into an internal link to the normative reference (public issue 336). * Add ename:VK_ERROR_OUT_OF_MEMORY error code to flink:vkCreateDebugReportCallbackEXT (public issue 337). Internal Issues: * Update style guide regarding use of code:NULL and dname:VK_NULL_HANDLE (internal issue 393). * Change the definition of latexmath:[$q$] in the <<textures-image-level-selection,texture image level selection>> section to be the index of the maximum defined level for the view, not the number of levels in the view (internal issue 406). * Allow developers to override dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE with their own binary-compatible definition (internal issue 439). * Fix +vk_platform.h+ conditional logic causing compile failure with some Android compilers (internal issue 441). * Implement the single-branch model as described above (internal issue 461). Other Issues:
2016-08-28 10:47:19 +00:00
Vulkan 1.0 branch 1.0 for release
2016-02-16 09:53:44 +00:00
// Appendices
:numbered!:
include::appendices/spirvenv.txt[]
Change log for September 8, 2018 Vulkan 1.1.84 spec update: * Update release number to 84. Public Issues: * Fix code sample in the `<<VK_EXT_debug_utils>>` extension (public issue 751). * Fix misleading comment in `vk.xml` for slink:VkDescriptorBufferInfo::pname:buffer (public pull request 762). * Fix formatting of deprecation attributes in schema doc (public pull request 767). * Change `can` to `may` in the description of elink:VkSparseImageFormatFlagBits, which are return values from queries (public pull request 768). * Prettify generated contact list in extension appendices, adding logos and a New Issue link (public pull request 770). * Enable sRGB conversion based on the image view format, not the image format, in the <<textures-format-conversion, Format Conversion>> section (public pull request 773). * Fix typo in equation in the <<primsrast-lines-basic, Basic Line Segment Rasterization>> section (public pull request 780). * Fix special characters in GitHub contacts links (public pull request 783). * Make clean_pdf target remove pdf folder (public pull request 784). * Fix styleguide bad markup of block continuation (public pull request 792). Other Issues: * Allow a zero vertex attribute divisor in the `<<VK_EXT_vertex_attribute_divisor>>` extension, exposed via the slink:VkPhysicalDeviceVertexAttributeDivisorFeaturesEXT feature. * Add missing `structextends="VkDeviceCreateInfo"` to slink:VkPhysicalDeviceShaderDrawParameterFeatures and slink:VkPhysicalDeviceBlendOperationAdvancedFeaturesEXT. New Extensions: * `VK_KHR_memory_model` * `VK_EXT_astc_decode_mode` * `VK_EXT_inline_uniform_block`
2018-09-08 22:52:13 +00:00
ifdef::VK_KHR_vulkan_memory_model[]
include::appendices/memorymodel.txt[]
endif::VK_KHR_vulkan_memory_model[]
Vulkan 1.0 branch 1.0 for release
2016-02-16 09:53:44 +00:00
include::appendices/compressedtex.txt[]
Change log for March 7, 2018 Vulkan 1.1.70 spec update: * Vulkan 1.1 initial release. Bump API patch number and header version number to 70 for this update. The patch number will be used for both Vulkan 1.1 and Vulkan 1.0 updates, and continues to increment continuously from the previous Vulkan 1.0.69 update. NOTE: We are not publishing an updated 1.0.70 specification, or 1.1 reference pages, along with 1.1.70. There are still minor issues to work out with those build targets. However, we will soon generate all three types of documents as part of the regular spec update cycle. NOTE: The GitHub KhronosGroup/Vulkan-Docs repository now maintains the current specification in the `master` branch. The `1.0` branch is out of date and will not be maintained, since we will be generating both 1.1 and 1.0 specifications from the `master` branch in the future. Github Issues: * Clarify how mapped memory ranges are flushed in flink:vkFlushMappedMemoryRanges (public issue 127). * Specify that <<synchronization-pipeline-stages, Pipeline Stages>> are a list of tasks that each command performs, rather than necessarily being discrete pieces of hardware that one task flows through. Add a "`synchronization command`" pipeline type which all synchronization command execute (it's just TOP + BOTTOM), with an explanatory note (public issue 554). Internal Issues: * Regenerate all images used in the spec in Inkscape with a consistent look-and-feel, and adjust image size attributes so they're all legible, and not too large with respect to the spec body text (internal issue 701). * Document in the <<extensions,extensions>> appendix and in the style guide that `KHX` extensions are no longer supported or used in the Vulkan 1.1 timeframe (internal issue 714). * Remove the leftover equations_temp directory after PDF build completes (internal issue 925). * Update the <<credits, Credits (Informative)>> appendix to include contributors to Vulkan 1.1, and to list them according to the API version(s) they contributed to (internal issue 987). * Add a NOTE to the introduction explaining that interfaces defined by extensions which were promoted to Vulkan 1.1 are now expressed as aliases of the Vulkan 1.1 type (internal issue 991). * Instrument spec source conditionals so spec can be built with 1.1 features, extensions promoted to 1.1, or both (internal issues 992, 998). * Modify the XML schema and tools to support explicit aliasing of types, structures, and commands, and use this to express the promotion of 1.0 extensions to 1.1 core features, by making the extension interfaces aliases of the core features they were promoted to. Mark up promoted interfaces to allow still generating 1.0 + extension specifications (internal issue 991). * Platform names, along with corresponding preprocessor symbols to enable extensions specific to those platforms, are now reserved in vk.xml using the <platform> tag. Update the registry schema and schema specification to match (internal issue 1011). * Updated the <<textures-texel-replacement, Texel Replacement>> section to clarify that reads from invalid texels for image resources result in undefined values (internal issue 1014). * Modify description of patch version so it continues to increment across minor version changes (internal issue 1033). * Clarify and unify language describing physical device-level core and extension functionality in the <<fundamentals-validusage-extensions, Valid Usage for Extensions>>, <<fundamentals-validusage-versions, Valid Usage for Newer Core Versions>>, <<initialization-functionpointers Command Function Pointers>>, <<initialization-phys-dev-extensions, Extending Physical Device From Device Extensions>> <<extended-functionality-instance-extensions-and-devices, Instance Extensions and Device Extensions>> sections and for flink:vkGetPhysicalDeviceImageFormatProperties2. This documents that instance-level functionality is tied to the loader, and independent of the ICD; physical device-level functionality is tied to the ICD, and associated with device extensions; physical devices are treated more uniformly between core and extensions; and instance and physical versions can be different (internal issue 1048). * Updated the <<commandbuffers-lifecycle, Command Buffer Lifecycle>> section to clarify the ability for pending command buffers to transition to the invalid state after submission, and add a command buffer lifecycle diagram (internal issue 1050). * Clarify that some flink:VkDescriptorUpdateTemplateCreateInfo parameters are ignored when push descriptors are not supported (internal issue 1054). * Specify that flink:vkCreateImage will return an error if the image is too large, in a NOTE in the slink:VkImageFormatProperties description (internal issue 1078). * Remove near-duplicate NOTEs about when to query function pointers dynamically in the <<initialization, Initialization>> chapter and replace by extending the NOTE in the <<fundamentals-abi, Application Binary Interface>> section (internal issue 1085). * Restore missing references to "`Sparse Resource Features`" in the flink:VkBufferCreateFlagBits description (internal issue 1086). * Tidy up definitions of descriptor types in the `GL_KHR_vulkan_glsl` specification, the <<descriptorsets, Resource Descriptors>> section and its subsections, and the <<interfaces-resources-descset, Descriptor Set Interface>> for consistency, reduction of duplicate information, and removal of GLSL correspondance/examples (internal issue 1090). * Correctly describe code:PrimitiveId as an Input for tessellation control and evaluation shaders, not an Output (internal issue 1109). * Relax the requirements on chroma offsets for nearest filtering in <<textures-implict-reconstruction, Implicit Reconstruction>> (internal issue 1116). Other Issues: * Clarify the intended relationship between specification language and certain terms defined in the Khronos Intellectual Property Rights policy. Specific changes include: ** Rewrote IP/Copyright preamble and introduction to better agree with normative language both as laid out in the introduction, and the Khronos IPR policy. ** Added notion of fully informative sections, which are now tagged with "`(Informative)`" in their titles. ** Removed non-normative uses of the phrase "`not required`" ** Clarified the distinction between terms "`optional`" and "`not required:`" as they relate to the IPR Policy, and updated specification text to use terms consistent with the intent. ** Reduced additions to RFC 2119, and ensured the specification agreed with the leaner language. ** Removed the terms "`hardware`", "`software`", "`CPU`", and "`GPU`" from normative text. ** Moved several paragraphs that should not have been normative to informative notes. ** Clarified a number of definitions in the Glossary. ** Updated the document writing guide to match new terminology changes. * Explicitly state in the <<fundamentals-objectmodel-lifetime-acquire, application memory lifetime>> language that that for objects other than descriptor sets, a slink:VkDescriptorSetLayout object used in the creation of another object (such as slink:VkPipelineLayout or slink:VkDescriptorUpdateTemplateKHR) is only in use during the creation of that object and can be safely destroyed afterwards. * Updated the <<textures-scale-factor, Scale Factor Operation>> section to use the ratio of anisotropy, rather than the integer sample rate, to perform the LOD calculation. The spec still allows use of the sample rate as the value used to calculate the LOD, but no longer requires it. * Update `vulkan_ext.c` to include all platform-related definitions from the Vulkan platform headers, following the split of the headers into platform-specific and non-platform-specific files. * Fix bogus anchor name in the <<commandbuffers, Command Buffers>> chapter which accidentally duplicated an anchor in the pipelines chapter. There were no reference to this anchor, fortunately. * Add valid usage statement for slink:VkWriteDescriptorSet and slink:VkCopyDescriptorSet requiring that the slink:VkDescriptorSetLayout used to allocate the source and destination sets must not have been destroyed at the time flink:vkUpdateDescriptorSets is called. * Document mapping of subgroup barrier functions to SPIR-V, and clarify a place where subgroupBarrier sounds like it's execution-only in the standalone `GL_KHR_shader_subgroup` specification. * Use an HTML stylesheet derived from the Asciidoctor `colony` theme, with the default Arial font family replaced by the sans-serif Noto font family. * Numerous minor updates to README.adoc, build scripts, Makefiles, and registry and style guide specifications to support Vulkan 1.1 outputs, use them as defaults, and remove mention of `KHX` extensions, which are no longer supported. New Extensions: * `VK_EXT_vertex_attrib_divisor`
2018-03-07 12:18:52 +00:00
ifdef::VK_VERSION_1_1[]
include::appendices/versions.txt[]
endif::VK_VERSION_1_1[]
Change log for September 6, 2016 Vulkan 1.0.26 spec update: * Bump API patch number and header version number to 26 for this update. Github Issues: * Bring sample code in the +VK_KHR_surface+ and +VK_KHR_swapchain+ extension summary appendices up to date, and note they will be replaced with pointers to the LunarG SDK examples in the future (public issue 279). * Add a new <<fundamentals-commandsyntax-results-lifetime,Lifetime of Retrieved Results>> section specifying that ftext:vkGet* and ftext:VkEnumerate* results are invariant unless otherwise specified, and specify behavior for individual commands which are not invariant (public issue 280). * Remove conflicting definition of slink:VkDisplayPlaneCapabilitiesKHR::pname:maxSrcPosition and clean up language of the remaining definition (public issue 351). * Fix many minor spelling errors and add rules to the style guide to prevent recurrences (public issue 352). Internal Issues: * Remove redundant descriptions of the etext:VK_USE_PLATFORM_* macros from the <<wsi,Window System Integration>> chapter in favor of the description in the <<boilerplate-wsi-header,Window System-Specific Header Control>> appendix (internal issue 6). * Replace misleading 'can: be destroyed when not X' with more correct 'must: not be destroyed while X' in the <<fundamentals-objectmodel-lifetime,Object Lifetime>> section. Disallow destroying a pipeline layout while a command buffer using it is recording (internal issue 241). * Clarify that ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT is valid for all images used as attachments in elink:VkImageUsageFlagBits and the slink:VkImageLayout validity language (internal issue 320). * Note that <<extended-functionality-layers,Layers>> may wrap object handles, but that this is a generally discouraged. A link to additional information in the documentation for layer authors is provided (issue 398) * Replace the mustnot: and shouldnot: macros with equivalent must: not and should: not to get rid of non-English words while still highlighting normative language (internal issue 407). * Disallow creating multisampled images with ename:VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT in the slink:VkImageLayout validity language and the <<features-supported-sample-counts,Supported Sample Counts>> section (internal issue 445). * Fix typo so that flink:vkCmdDrawIndexedIndirect is defined in terms of flink:vkCmdDrawIndexed rather than flink:vkCmdDrawIndirect (internal issue 446). * Reorganize the per-extension information sections to all be in the <<extensions,Layers & Extensions>> appendix. Also fix a typo in +VK_IMG_filter_cubic+ which incorrectly identified it as a +KHR+ extension (internal issue 461). Other Issues: * Use asciidoc markup instead of latexmath to simplify diagrams in the <<features-formats-non-packed,byte mapping tables>> for color formats. * Fix a markup problem with the wildcarded enumerant names in a NOTE in the <<textures-texel-replacement,Texel Replacement>> section. * Fix missing attributes in the XML interface for elink:VkExternalMemoryHandleTypeFlagBitsNV and elink:VkExternalMemoryFeatureFlagBitsNV (KhronosGroup/Vulkan-Hpp issue #25) * Cleanup reference page builds so only core pages are built for releases.
2016-09-06 13:17:27 +00:00
// Extension appendices are now included from extensions.txt
Vulkan 1.0 branch 1.0 for release
2016-02-16 09:53:44 +00:00
include::appendices/extensions.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
include::appendices/boilerplate.txt[]
Vulkan 1.0 branch 1.0 for release
2016-02-16 09:53:44 +00:00
include::appendices/invariance.txt[]
include::appendices/glossary.txt[]
include::appendices/credits.txt[]
Change log for January 23, 2017 Vulkan 1.0.39 spec update: * Bump API patch number and header version number to 39 for this update. Github Issues: * Clarified that only accesses via the specified buffer/image subresource ranges are included in the access scopes (public issue 306). * Add missing valid usage statements for flink:vkCreateComputePipelines and flink:vkCreateGraphicsPipelines (public issue 427). Internal Issues: * Add a Note to the <<invariance,Invariance>> appendix about a difference between OpenGL and Vulkan with regards to how primitives derived from offsets are handled (internal issue 355). * Add the +<<VK_KHR_get_physical_device_properties2>>+, +<<VK_KHR_maintenance1>>+, and +<<VK_KHR_shader_draw_parameters>>+ extensions (internal issue 448). * Add the +<<VK_EXT_shader_subgroup_vote>>+ and +<<VK_EXT_shader_subgroup_ballot>>+ extensions (internal issue 449). * Update the texture level-of-detail equation in the <<textures-scale-factor,Scale Factor Operation>> section to better approximate the ellipse major and minor axes (internal issue 547). * Forbid non-explicitly allowed uses of interface decorations in the introduction to the <<interfaces,Shader Interfaces>> chapter (internal issue 607). * Replace use of MathJax with KaTeX, for improved load-time performance as well as avoiding the scrolling-and-scrolling behavior due to MathJax asynchronous rendering when loading at an anchor inside the spec. This change also requires moving to HTML5 output for the spec instead of XHTML, and there is a visible difference in that the chapter navigation index is now in a scrollable sidebar instead of at the top of the document. We may or may not retain the nav sidebar based on feedback (internal issue 613). * Improve consistency of markup and formatting in extension appendices (internal issue 631). Other Issues: * Add explicit valid usage statements to slink:VkImageCopy requiring that the source and destination layer ranges be contained in their respective source and destination images. * Add valid usage language for swapchain of flink:vkAcquireNextImage. If the swapchain has been replaced, then it should not be passed to flink:vkAcquireNextImage. * Add a valid usage statement to flink:vkCreateImageView, that the image must have been created with an appropriate usage bit set. * Noted that slink:VkDisplayPresentInfoKHR is a valid extension of slink:VkPresentInfoKHR in the <<wsi_swapchain,WSI Swapchain>> section. * Update valid usage for flink:vkCmdSetViewport and flink:vkCmdSetScissor to account for the multiple viewport feature. If the feature is not enabled, the parameters for these functions have required values that are defined in the <<features-features-multiViewport,multiple viewports>> section of the spec but were not reflected in the valid usage text for these functions. * Add the +<<VK_EXT_swapchain_colorspace>>+ extension defining common color spaces.
2017-01-18 04:11:25 +00:00
Change log for September 30, 2016 Vulkan 1.0.29 spec update: * Bump API patch number and header version number to 29 for this update. Github Issues: * Remove redundant constraint on slink:VkCommandBufferInheritanceInfo::pname:queryFlags (public issue 224). * Fix typo and remove link in Note in the <<extended-functionality-instance-extensions-and-devices, Instance Extensions and Device Extensions>> section (public issue 359). * Fix erroneous validation statement for the pname:layout member of slink:VkComputePipelineCreateInfo (public issue 362). Internal Issues: * Restore long figure captions using asciidoc sidebar blocks, due to restrictions of asciidoc syntax (internal issue 101). * Replace most latexmath equations with comparable markup in straight asciidoc, which significantly improves time required to fully load and process the HTML forms of the Specification. There are known minor font and alignment inconsistencies with MathJax and PDF rendering of latexmath equations. Please do not file github issues about these. We are aware of the inconsistencies and will make refinements over time, while the performance improvements are compelling in at least some major browsers (internal issue 313). * Move handcoded validity statements from +vk.xml+ into the Specification body, easing work in the single-branch model. Specify the distinction between these explicit statements, and the implicit validity statements inferred from vk.xml. Validity statements now appear in two blocks for each command and structure - handcoded "Valid Usage" and the implicit "Valid Usage (Implicit)" (internal issue 392). * Add the +returnedonly="false"+ attribute to WSI output structures, removing incorrectly generated implicit validity statements for slink:VkDisplayPropertiesKHR, slink:VkDisplayPlanePropertiesKHR, slink:VkDisplayModePropertiesKHR, slink:VkDisplayPlaneCapabilitiesKHR, slink:VkSurfaceCapabilitiesKHR, and slink:VkSurfaceFormatKHR structures (internal issue 486). * Update slink:VkImageLayout to require the ename:VK_IMAGE_USAGE_SAMPLED_BIT be set for sampled depth/stencil images (internal issue 487). * Use an explicit format specifier string for the date command invocation in the +Makefile+ instead of the shorthand -R option, which doesn't work on BSD and MaxOS X date commands (internal issue 500). Other Issues: * Use the terms ``allocation scope'' and ``extension scope'' instead of just ``scope'', and add them to the glossary.
2016-10-01 04:13:37 +00:00
endif::[]