diff --git a/.gitattributes b/.gitattributes index ef64bff441..13d344ae28 100644 --- a/.gitattributes +++ b/.gitattributes @@ -5,5 +5,6 @@ doc/specs/vulkan/makeExt text eol=lf doc/specs/vulkan/makeKHR text eol=lf doc/specs/vulkan/sandboxCopy text eol=lf doc/specs/vulkan/config/optimize-pdf text eol=lf +doc/specs/vulkan/scripts/checkXrefs text eol=lf *.sh text eol=lf diff --git a/ChangeLog.txt b/ChangeLog.txt index 80667e6b44..63b2b6f020 100644 --- a/ChangeLog.txt +++ b/ChangeLog.txt @@ -1,1240 +1,844 @@ -Update Log for the Vulkan-Docs repository on Github. This just -summarizes the periodic public updates, not individual commits to the -tree. For the most part, commits on Github are done as single large -patches at the release point, collecting together the resolution of many -Khronos internal and public issues. +Update Log for the Vulkan-Docs repository on Github. Updates are in +reverse chronological order starting with the latest public release. + +This summarizes the periodic public updates, not individual commits. For the +most part, commits on Github are done as single large patches at the release +point, collecting together the resolution of many Khronos internal and +public issues. ----------------------------------------------------- -February 16, 2016 - Vulkan 1.0 initial public release +Change log for March 17, 2017 Vulkan 1.0.44 spec update: ------------------------------------------------------ + * Bump API patch number and header version number to 44 for this update. -Change log for February 25, 2015 Vulkan 1.0.4 spec update: +Github Issues: - * Bump API patch number from 3 to 4 for the first public update to the - spec. Add patch number to the spec title (this will be done - automatically from XML, later). - * Fixes for numerous editorial issues. Regularize descriptions of - variable-length array queries. Properly tag enumerants so they come - out in the right font (many were mislabeled in usage tags in vk.xml, - or not tagged). Spelling and markup corrections (public issue 4). - * Fix typos and clearly separate description of different types of - memory areas (public issue 5). - * Use standards-compliant preprocessor guard symbols on headers - (public issue 7). - * Note that Github users cannot currently set labels on issues, and - recommend a fallback approach (public issue 15). - * Use latexmath prefix on len= attributes (public issue 29). - * Make flink:vkCmdUpdateBuffer pname:dataSize limit consistent (public - issue 65). - * Add VK_KHR_mirror_clamp_to_edge extension to core API branch, as an - optional feature not introducing new commands or enums (internal - issue 104). - * Cleanup invariance language inherited from the GL specification to - not refer to nonexistent (GL-specific) state (internal issue 111). - * Modify the flink:vkCmdDrawIndexed pname:vertexOffset definition to - not be the "base offset within the index buffer" but rather the - "value added to the vertex index before indexing into the vertex - buffer" (internal issue 118). - * Fix drawing chapter in the "Programmable Primitive Shading" section - where it described categories of drawing commands. It referenced - flink:vkCmdDrawIndexed twice. Replace the second reference with - flink:vkCmdDrawIndexedIndirect (internal issue 119). - * Typo fixed in <> sparse memory example (internal issue 122). - * Add flink:VkDisplayPlaneAlphaFlagsKHR to section of - VK_KHR_display extension (internal issue 125) - * Add missing optional="false,true" to - flink:vkGetImageSparseMemoryRequirements - pname:pSparseMemoryRequirementCount parameter (internal issue 132) - * Rename ename:VK_STRUCTURE_TYPE_DEBUG_REPORT_CREATE_INFO_EXT to - ename:VK_STRUCTURE_TYPE_DEBUG_REPORT_CALLBACK_CREATE_INFO_EXT - (internal issue 133) - * Fix a handful of broken cross-references in the - <> chapter (internal issue 134). - * Fix "Input Attachement" GLSL example to use correct syntax (internal - issue 135). - * Update XML schema and documentation to accomodate recently added - attributes for validity. Add some introductory material describing - design choices and pointing to the public repository to file issues. - * Put include of validity in the core spec extensions chapter on its - own line, so that asciidoc is happy. - * Fix vertexOffset language to specify that it is the value added to - the vertex index before indexing into the vertex buffer, not the - base offset within the index buffer. - * Fix error in the description of flink:vkCmdNextSubpass. + * Fix description of <> (public issue 290). + * Better specify VK_DEVICE_LOST behavior around flink:vkQueueSubmit, + flink:vkWaitForFences, and flink:vkGetFenceStatus (public issue 423). + * Clarify definition of flink:vkGetQueryPoolResults::pname:queryCount + (public issue 441). + * Simplify and clean up normative language. Remove shall and replace + recommend and variants with should wherever possible (public issue 448). + * Fix all dangling internal cross-references in the 1.0-extensions + specification, and add scripts/checkXrefs to find these in the future + (public issue 456). + * Reverse order of ChangeLog.txt entries so the most recent version is + documented first (public issue 463) + * Removes "become invalid" which clashes with invalid state for command + buffers. (public issue 467) + * Disallowed pending state in spec text for vkResetCommandBuffer, matching + valid usage (public issue 468) + * Removes sentence describing invalid state "like initial state". (public + issue 469) + * Disallows begin command buffer from resetting command buffers in the + "recording" state. (public issue 470) + * Removes mention of state from description of + VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT (public issue 471) + * Removed extra valid usage statement in VkSubmitInfo (public issue 472) + +Internal Issues: + + * Clarify description of the pname:imageLayout member of + sname:VkDescriptorImageInfo. + * Fix typos where etext:VK_VIEW_TYPE* was used instead of + etext:VK_IMAGE_VIEW_TYPE. + * Removed the <> and <> example + code from the specification and noted it has been moved to the Vulkan + SDK cube demo (internal issue 179). + * Reorder VkExternalMemoryHandleTypeFlagBitsNV description (internal issue + 480). + * Clarify than an implementation is + <> in a bitfield (internal issue 640). + * Break Valid Usage statements describing unrelated parameters into + separate statements, and add a style guide entry to follow this approach + (internal issue 685). + * Move valid usage statement for slink:VkImageCreateInfo from spec body to + the explicit valid usage block (internal issue 693). + * Fix typos in the descriptions of slink:VkDisplaySurfaceCreateInfoKHR, + flink:vkCreateDisplayModeKHR, and + flink:vkGetDisplayPlaneSupportedDisplaysKHR in the <> section (internal issue 698, 704, 716). + * Clarified that mandatory depth/stencil formats are only a requirement + for 2D images (internal issue 719). + * Clarify that variables decorated with DeviceIndex/ViewIndex must be in + the Input storage class (internal issue 733). + * Work around generator script problem with removal of Unicode literals + from Python 3.0-3.2 using `future` package (internal issue 737). + * Remove nonexistent structure type enums from vk.xml (internal issue + 738). + * Fix validextensionstructs attributes for structures in the pname:pNext + chain for VkPresentInfoKHR, fixing implicit valid usage statements for + those structures (internal issue 740). ----------------------------------------------------- -Change log for March 4, 2016 Vulkan 1.0.5 spec update: +Change log for March 10, 2017 Vulkan 1.0.43 spec update: - * Bump API patch number to 5 for this update. + * Bump API patch number and header version number to 43 for this update. Github Issues: - * Correctly describe slink:VkPhysicalDeviceProperties pname:deviceName - member as a string, not a pointer to a string. Also one typo fix for - "hetereogeneous" (public issue 4). - * Replace maynot: macro with may: not, and "may: or maynot:" with - "may:" (public issue 4). - * Clarify that redundantly setting the state of a fence or event has - no effect (public issue 4). - * Minor fixes to ref pages to track descriptions of memory bits that - changed in the core spec. Fix name of a member in the description of - sname:sname:VkPipelineMultisampleStateCreateInfo (public issues 8, - 13). - * Remove redundant validity statement for - sname:VkGraphicsPipelineCreateInfo::pname:stageCount (public issue - 14). - * Fix typos in chapters 7-9 (public issue 14). - * Clarify the example demonstrating the behavior of - code:OpMemoryBarrier in the - <> section (public issue 16). - * Specify that freeing mapped memory implicitly unmaps the memory in - the description of flink:vkFreeMemory (public issue 17). - * Forbid allocation callbacks from calling into the API in the - <> section (public issue - 20). - * Add missing validity rules about size being greater than 0 and - offset being less than size of object. Fix - flink:VkMappedMemoryRange's misinterpretation of offset (public - issues 27, 31). - * Add validity rule disallowing overlapping source/destination - descriptors in flink:VkCopyDescriptorSet (public issue 32). - * Clarify that array and matrix stride has to be a multiple of the - base alignment of the array or matrix in the - <> - section (public issue 38). - * Correct parenthesis floor nesting error in equation for - <>. - Clarify case of when exp' is forced to 0, avoiding log2(0) undefined - problem (public issue 40). - * Remove redundant statement from the code:FragDepth description in - the <> - section (public issue 47). - * Define the clamping of the - <> by linking to the slink:VkPhysicalDevice feature - pname:maxSamplerLodBias (public issue 64). - * Fix typo "optimal linear resources" and clarify the set of resources - <> applies to (public issue - 67). - * Replace 'descriptor accessed by a pipeline' language for - sname:VkDescriptorSetAllocateInfo with more precise phrasing about - binding a descriptor set before a command that invokes work using - that set (public issue 69). - * tstripadj.svg contained an Inkscape tag which caused Firefox and IE - 11 to fail to render it, and was illegal SVG. Generating Plain SVG - from the Inkscape SVG source fixes this (public issue 70). - * Fix validity for sname:VkVertexInputBindingDescription and - sname:VkVertexInputAttributeDescription numbers (public issue 72). + * Make clearer that color write mask is applied regardless of whether + blending is enabled, by referring to the + <> section (public issue + 241). + * Fix public issue 414: + ** Added two new command buffer states (invalid, pending), and an explicit + "command buffer lifecycle" section to explain them. + ** Replaced "pending execution" with "in the pending state". + ** Replaced a bunch of "this will invalidate the command buffer" language + with "this will move the command buffer to the invalid state", and added + validation language for what state those command buffers should be in. + ** Added additional validation language about what state a command buffer + should be in for various commands that affect it. + ** Added invalidation language to destroy commands in the lifetimes section + of fundamentals. + ** Added command buffers to list of objects which must not be deleted + whilst a (primary) command buffer is in the recording or pending state. + * Update `GL_KHR_vulkan_glsl` extension to allow anonymous push constant + blocks (public issue 428). Internal Issues: - * Clarify the meaning of - ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT in - elink:VkFormatFeatureFlagBits with respect to depth compare - (internal issue 107). - * Added a note explaining that ename:VK_QUEUE_TRANSFER_BIT may or may - not be reported for a queue family that already supports - ename:VK_QUEUE_GRAPHICS_BIT or ename:VK_QUEUE_COMPUTE_BIT as the - former is a strict subset of the latter ones (internal issue 116). - * Add validity language for sname:VkDescriptorSetAllocateInfo about - exceeding the descriptor pool capacity (internal issue 140). - * Add ename:VK_INCOMPLETE success code for - flink:vkEnumeratePhysicalDevices query (internal issue 163). + * Document rules about extension interactions in the style guide (internal + issue 579). + * Require ename:VK_PRESENT_MODE_MAILBOX_KHR support in queries of surfaces + created with flink:vkCreateWaylandSurfaceKHR using the + VK_KHR_wayland_surface extension (internal issue 666). + * Remove Valid Usage constraints for flink:vkAllocateDescriptorSets when + the `VK_KHR_maintainance1` extension is present (internal issue 686). + * Remove undocumented KHX-variants of vkGetPhysicalDeviceProperties2KHR + and vkGetPhysicalDeviceImageFormatProperties2KHR from the + <> and + <> extensions. -Other Commits: +New Extensions: - * Add the VK_NV_glsl_shader extension definitions to the API. - * Update GL_KHR_vulkan_glsl with 1) origin_upper_left as default 2) - specialization array constant semantics. - * Corrected/updated Data Format Specification date. + * `VK_EXT_hdr_metadata` + * `VK_GOOGLE_display_timing` ----------------------------------------------------- -Change log for March 10, 2016 Vulkan 1.0.6 spec update: +Change log for February 27, 2017 Vulkan 1.0.42 spec update: - * Bump API patch number and header version number to 6 for this - update. + * Bump API patch number and header version number to 42 for this update + (the first anniversary edition). 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 - <> - section (public issue 45). - * Editorial fixes for <> section (public issues 54, 59). - * Clarify behavior of depth test in the <> - section (public issues 80, 81). - * Remove discussion of return codes from - flink:vkGetPhysicalDeviceSparseImageFormatProperties and - flink:vkGetImageSparseMemoryRequirements, which do not 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 <> - 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 <> diagram. Use more easily distinguished symbols in - tables in the <> section. Do not require FQDNs used as layer names be - encoded in lower case if not possible, in the - <> section (public issues 101, 119, 121). + * Changed asciidoctor macros so cross-page links in the standalone + reference pages function properly (public issue 462). 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__" 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). + * Clarified host visibility discussion for slink:VkMemoryType, + flink:vkInvalidateMappedMemoryRanges, elink:VkAccessFlagBits, and the + <> + section, removing duplicated information and adding a central definition + in the access types section (internal issue 552). + * Change description of + slink:vkGetPhysicalDeviceSurfacePresentModesKHR::pname:pPresentModes to + return an array of values, not structures (internal issue 699). -Other Commits: +New Extensions: - * 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. + * Add a NOTE to the <> chapter describing + the experimental status of `KHX` extensions. + * Add new Khronos, Khronos Experimental, and vendor Vulkan extensions for + release at GDC: + ** VK_KHR_descriptor_update_template + ** VK_KHR_push_descriptor + ** VK_KHX_device_group + ** VK_KHX_device_group_creation + ** VK_KHX_external_memory + ** VK_KHX_external_memory_capabilities + ** VK_KHX_external_memory_fd + ** VK_KHX_external_memory_win32 + ** VK_KHX_external_semaphore + ** VK_KHX_external_semaphore_capabilities + ** VK_KHX_external_semaphore_fd + ** VK_KHX_external_semaphore_win32 + ** VK_KHX_multiview + ** VK_KHX_win32_keyed_mutex + ** VK_EXT_discard_rectangles + ** VK_MVK_ios_surface + ** VK_MVK_macos_surface + ** VK_NVX_multiview_per_view_attributes + ** VK_NV_clip_space_w_scaling + ** VK_NV_geometry_shader_passthrough + ** VK_NV_sample_mask_override_coverage + ** VK_NV_viewport_array2 + ** VK_NV_viewport_swizzle + * Add new GLSL vendor extensions to support new builtin variables: + ** GL_EXT_device_group + ** GL_EXT_multiview ----------------------------------------------------- -Change log for March 25, 2016 Vulkan 1.0.7 spec update: +Change log for February 17, 2017 Vulkan 1.0.41 spec update: - * Bump API patch number and header version number to 7 for this - update. + * Bump API patch number and header version number to 41 for this update. Github Issues: - * Fix slink:VkSpecializationMapEntry example to avoid C/C++ strict - aliasing issues (public issue 14). - * Clarify the meaning of "matching" in flink:vkCmdBindDescriptorSets - validity language (public issue 33). - * Add stub reference pages so xrefs to not-yet-written pages do not - generate 404 errors. However, the actual content of these pages - still needs to be filled in as time allows (public issue 44, but - does not close that issue out). - * Remove incorrect validity statement for - flink:vkGetImageSparseMemoryRequirements (public issue 85). - * Reword the - <> - feature in terms of "aliasing", and clarify that it applies to - bindings in the same memory object (public issue 90). - * Clarify the relationship of the slink:VkPhysicalDeviceLimits - pname:maxViewportDimensions and pname:viewportBoundsRange limits - (public issue 92). - * Specify sparse unbound texture replacement in the - <> section - independently of robust buffer access language (public issue 100). - * Add the <> - section to explain architecture constraints Vulkan has chosen to - accept in order to enable portable and performant code (public issue - 122). - * State that an object must not be destroyed until *all* (not *any*) - uses of that object have completed (public issue 123). - * Minor editorial cleanup (public issues 129, 134, 146, 148). - * Add validity language for layer and extension names to - slink:VkDeviceCreateInfo matching that used for - slink:VkInstanceCreateInfo (public issue 130). - * Clean up terminology for the case when the bits set in one bitmask - are a subset of the bits set in another bitmask (public issue 138). - * Document that input attachments are UniformConstant not Input, in - the <> section (public glslang bug 169). + * Made all uses of `NULL` vs. code:VK_NULL_HANDLE consistent (public issue + 276). + * Clarify render pass compatibility in different usage scenarios (public + issues 303 and 304). + * Add valid usage statements to slink:VkFramebufferCreateInfo requiring + that the width, height, and number of layers of the framebuffer all be + nonzero (public issue 432). + * Allow `offset` and `align` in any GLSL version for the + `GL_KHR_vulkan_glsl` extension (public issue 435). + * Specify lifetime of string objects passed to the + tlink:PFN_vkDebugReportCallbackEXT user callback in the + +VK_EXT_debug_report+ extension (public issue 446). + * Fix inter-page links in multi-file reference pages (public issue 454). Internal Issues: - * Add max enum values to "flag bits" enums (internal issue 136). - * Clarify language around the various uses of the term "block" in the - <> section - (internal issue 202). - * Removed "expand" dependency from groups in vk.xml and added - auto-generation code in the scripts to infer it instead, to ensure - consistency. This caused renaming of sname:VkColorSpaceKHR and - sname:VkPresentModeKHR etext:BEGIN_RANGE (etc.) tokens, but those - tokens are metadata, not part of the API, and the Vulkan WG is OK - with this change. This change adds ranges to two additional enums - that were missing them due to not defining the "expand" attribute - (internal issue 217). - * Tweak makefile to generate ref page nroff (.3) files in the right - output directory, working around an a2x limitation (internal issue - 223). + * Update valid usage language for slink:VkImageCreateInfo to disallow + creating images that have ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT + set without other attachment usage bits + (ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT, + ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT, or + ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT) (internal issue 540). + * Disable `VK_EXT_swapchain_colorspace` extension until internal issues + 640 and 661 are mutually resolved. + * Allow alternative mipmap level selection when [eq]#lambda == 0.5# during + texture <> + (internal issue 680). -Other Commits: +Other Issues: - * Add validity requirements for flink:vkCmdCopyQueryPoolResults - pname:dstBuffer parameter. - * Fix ref page build to generate .3 targets in the right output - directory. + * Add a clarification to the style guide that the extension revision + number is treated as a patch number, so that changes to published + extensions should only include bug fixes and spec clarifications. ----------------------------------------------------- -Change log for April 1, 2016 Vulkan 1.0.8 spec update: +Change log for February 10, 2017 Vulkan 1.0.40 spec update: - * Bump API patch number and header version number to 8 for this - 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: - * Specify in the validity language for flink:vkBeginCommandBuffer that - pname:commandBuffer must not currently be pending execution (public - issue 96). - * Describe depth comparison using the correct temporary variable names - in the <> - section (public issue 100). - * Clarify the order of descriptor update operations in the - flink:vkUpdateDescriptorSets command (public issue 115). - * Specify in the VK_KHR_swapchain extension that - flink:vkAcquireNextImageKHR's pname:semaphore and pname:fence - parameters cannot both be sname:VK_NULL_HANDLE (partly addresses, - but does not fully close, public issue 117 / internal issue 246). - * Change reference to the "lifetime" of a Vulkan command to - "duration", and define the "duration" term (public issue 135). - * Added valid usage language for slink:VkImageLayout to require both - pname:height and pname:depth to be 1 for 1D images and pname:depth - to be 1 for 2D images (public issue 137). - * Fix SPIR-V example code in the - <> section to - properly decorate the code:InputAttachmentIndex (public issue 139). - * Fix reference to nonexistent pname:imageInfo in the description of - flink:VkWriteDescriptorSet to refer to pname:pImageInfo (public - issue 140). + * Updated sample code for the <> (public issue 97). + * Modify line and point clipping behavior in the + <> 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 <>, <>, and + <>; the + discussion of <>; + and references elsewhere to these sections (public issue 133). + * Clarify \<\> + 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 <> (public + issue 447). Internal Issues: - * Link to the fixed-function vertex chapter from the drawing chapter - (internal issue 110) - * Fix typo in slink:VkImageCreateInfo validity language: - ptext:maxExtent.sampleCounts -> pname:sampleCounts (internal issue - 249). - * Explain why the non-core token etext:VK_IMAGE_LAYOUT_PRESENT_SRC_KHR - is used in the example in the - <> section (internal issue - 251). - * Attempt to clarify in the VK_KHR_android_surface extension's - <> section - that there is no Android-specific WSI query, and why (internal issue - 252). + * 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 Commits: +Other Issues: - * Add missing language about ename:VK_INCOMPLETE being returned from - array queries when the passed array is too short, in the - VK_KHR_display, VK_KHR_swapchain, and VK_KHR_surface extensions. + * 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 <> 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. ----------------------------------------------------- -Change log for April 8, 2016 Vulkan 1.0.9 spec update: +Change log for January 23, 2017 Vulkan 1.0.39 spec update: - * Bump API patch number and header version number to 9 for this - update. + * Bump API patch number and header version number to 39 for this update. Github Issues: - * Fix memory type preorder definition and clarify example list and source - code for slink:VkMemoryRequirements and slink:VkMemoryHeap (public issue - 26). - * Ensure slink:VkAllocationCallbacks are properly defined (public issue - 73). - * Clarify the WSI extension language by switching from the fuzzier - "ownership" language to more-consistent "acquire" language (public issue - 117). - * Add language allowing allocation and freeing of memory scoped to the - duration of any API command in the <> section (public issue 136). - * Clarify the explicit location assignment always overrides the inherited - location in the <> section, even for the first member of a block (public issue - 141). - * Fixed references to - slink:VkCommandBufferInheritanceInfo::pname:pipelineStatistics (public - issue 158). - * Fix name of slink:VkBufferCopy::pname:size field in validity language - for flink:vkCmdCopyBuffer (public issue 162). + * 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: - * Update GL_KHR_vulkan_glsl specification to clarify disallowance of - spec-const arrays in initializers (internal issue 248). - * Clarify <> section - to state that user-defined variable interface must match too (internal - issue 250). - ------------------------------------------------------ - -Change log for April 15, 2016 Vulkan 1.0.10 spec update: - - * Bump API patch number and header version number to 10 for this - update. - -Github Issues: - - * Slightly tweak the <> allocator language - so that an application wrapping the standard C alloc/free/realloc - functions is still correct - the previous language was too strong with - regards to freeing memory. Also made certain scenarios clearer - an - implementation may now continue without error if an allocation failed - and it is able to continue correctly (public issue 21). - * Require that etext:VK_*_CREATE_SPARSE_BINDING_BIT is set when the - corresponding etext:VK_*_CREATE_SPARSE_RESIDENCY_BIT is used, in the - <> section and related commands - flink:vkCreateBuffer and flink:vkCreateImage (public issue 84). - * Update the <> chapter to clarify - interactions between optional features and dynamic state for the - pname:depthBiasClamp and pname:wideLines features (public issue 89). - * Describe the code:WorkgroupSize builtin in the - <> section, and update - the <> section to further clarify how - to set the number of workgroups to execute in a compute shader (public - issue 145). - * Use the term *image subresource* everywhere instead of *subresource*, - except for the special case of *host-accessible subresource*, which may - be either an image subresource or buffer range (public issue 120) - * Add a note to the <> section - about extensibility of structures (Public issue 165). - * Fix return code flink:vkAcquireNextImageKHR when the timeout parameter - is 0 to ename:VK_NOT_READY instead of ename:VK_TIMEOUT (public issue - 170). - * Fix typo in slink:VkLayerProperties::pname:apiVersion field (public - issue 172). + * Add a Note to the <> appendix about a difference + between OpenGL and Vulkan with regards to how primitives derived from + offsets are handled (internal issue 355). + * Add the +<>+, + +<>+, and +<>+ + extensions (internal issue 448). + * Add the +<>+ and + +<>+ extensions (internal issue 449). + * Update the texture level-of-detail equation in the + <> 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 <> 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). -Internal Issues: +Other Issues: - * Fix a few minor internally-detected typos. - * Minor formatting tweaks to pseudocode in the <> chapter (internal issue 179). - * Fix typo in the definition of point sampling for - elink:VkCullModeFlagBits (internal issue 268). + * 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 <> 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 <> section of the spec but were not reflected in the valid + usage text for these functions. + * Add the +<>+ extension defining common + color spaces. ----------------------------------------------------- -Change log for April 22, 2016 Vulkan 1.0.11 spec update: +Change log for December 16, 2016 Vulkan 1.0.38 spec update: - * Bump API patch number and header version number to 11 for this - update. + * Bump API patch number and header version number to 38 for this update. Github Issues: - * Clarify the WSI extension language by switching from the fuzzier - "ownership" language to more-consistent "acquire" language (public - issue 117). - * Clarify that memory barriers apply to all commands in the dependency - chains in the flink:vkGetRenderAreaGranularity command and the - <> section (public issue 132). - * Clarify that a queue family is a set of queues in the - <> section (public issue - 166). - * Removed requirement from valid usage language that - VkPresentInfoKHR::waitSemaphoreCount must be greater than 0 (public - issue 171). - * Fix broken internal links, describe structures consistently, use - consistent style for SPIR-V codewords, and tag normative terms that - were missing asciidoc tags (public issue 183 and ancillary - markup/normative language fixes). - * Fix typos for slink:VkPhysicalDeviceLimits member names in - slink:VkImageCreateInfo validity language (public issue 184). + * Make ename:VK_PIPELINE_STAGE_HOST_BIT invalid for all stage masks, + except for flink:vkCmdWaitEvents (public issue 261). Internal Issues: - * Document that the requested patch version number specified as part - of slink:VkApplicationInfo::pname:apiVersion is ignored when - creating an instance (internal issue 176). - * Clarify handling of extension structs in the - <> section (internal issue 254). - * Update required slink:VkImageFormatProperties::pname:maxMipLevels to - be limited to the maximum allowed mipmap pyramid size corresponding - to the actual maximum supported size for the format (internal issue - 256). - * Modify the <> section so the allowed maximum extent is the maximum - image dimension supported for each dimension of the type of texture - being queried (internal issue 257). - * Clarify in the <> section that at least one of the code:LocalSize execution - mode or code:WorkgroupSize decoration is required for each compute - shader entry point in a shader module (internal issue 279). - * Add validity rules for formats in flink:vkCmdClearColorImage and - flink:vkCmdClearDepthStencilImage (internal issue 283). - * Clarify that slink:VkImageFormatProperties::pname:maxResourceSize is - an upper bound, and that it may not be possible to create an image - anywhere near that size (internal issue 284). + * Added validation language for flink:vkQueueBindSparse, + slink:VkPresentInfoKHR, and slink:VkSubmitInfo, and a note to the + <> + section to clarify that semaphores must be signaled and waited on in a + 1:1 fashion (internal issue 546). + * Modify valid usage for slink:VkBufferImageCopy to only require + pname:bufferOffset to be a multiple of the image format's element size + when the format is not depth/stencil (internal issue 594). -Other Commits: +Other Issues: - * Fix various minor markup errors reported by validation scripts. - * Change copyright from Khronos Free Use License to Apache 2.0 license - on relevant script/XML/header files. This does not affect the - specification source copyright. + * Vulkan(R) is now a registered trademark symbol, and this is reflected in + documents and copyright statements. ----------------------------------------------------- -Change log for April 29, 2016 Vulkan 1.0.12 spec update: +Change log for December 10, 2016 Vulkan 1.0.37 spec update: - * Bump API patch number and header version number to 12 for this - update. + * Bump API patch number and header version number to 37 for this update. Github Issues: - * Change valid usage statements intended to be "sub-points" to - be actual sub-points (public issue 66). - * Replace double negation in description of - slink:VkRenderPassBeginInfo::pname:pClearValues (based on public - merge 142). - * Cleanup minor typos in spec, ref pages and XML, including those - proposed in public pull requests 144, 150, 151, 167, 168, 181, and - 186. - * Use *strict subset* in describing the partial order of memory - property types for slink:VkMemoryType, and update the style guide - accordingly (public issue 190). - * Fix various "a image" -> "an image" typos (public issue 191). - * Note in the <> and - <> sections that - structures defined by extensions which may be passed in structure - chains using the ptext:pNext member must include initial - ptext:sType and ptext:pNext members (public issue 192). + * Add usability guarantees on the values returned by + flink:vkGetPhysicalDeviceSurfaceCapabilitiesKHR in the + slink:VkSurfaceCapabilitiesKHR structure and by + flink:vkGetPhysicalDeviceSurfaceFormatsKHR in the + pname:pSurfaceFormatCount parameter (public issue 385). + * Add elink:VkDebugReportObjectTypeEXT enumerants for new object types + introduced by new extensions (public issue 408). + * Add +VK_NVX_device_generated_commands+ etext:ACCESS bits and define how + they are used (public issue 415). + * Fix indentation for slink:VkDebugReportCallbackCreateInfoEXT member + descriptions (public issue 419). Internal Issues: - * Remove duplicate language from the description of the pname:fence - parameter to flink:vkQueueSubmit and improve validity language - (internal issue 91). - * Added documentation for "optional" attribute to XML readme.tex/pdf - (internal issue 149). - * Clarify the host-side data validity rules and behavior of - flink:vkFlushMappedMemoryRanges and - flink:vkInvalidateMappedMemoryRanges (internal issue 266). - -Other Commits: - - * Added clarification to flink:vkCmdFillBuffer regarding the use of - ename:VK_WHOLE_SIZE. - * Fixed and documented implementation of "validextensionstructs" - attribute. in XML processing scripts and readme.tex/pdf. - * Add missing validity statements to flink:vkResetEvent and - flink:vkCmdResetEvent. - * Fix validity for the - ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT flag. - Correct all the draw/dispatch commands to mention optimally tiled - images as well as linear tiled images, and say image VIEWS instead - of images. Add validity statement to flink:vkCmdBlitImage - * Replace the {apiname} macro with hardcoded "Vulkan", now that we have - committed to that name. - * Add the VK_AMD_rasterization_order extension to vk.xml. + * Expand requirements memory binding of non-sparse images and buffers from + the <> section into + valid usage statements for all of the applicable API calls (internal + issue 508). + * Explicitly state that valid usage of flink:vkCreateImage requires that + flink:vkGetPhysicalDeviceImageFormatProperties would return + ename:VK_SUCCESS for the requested image configuration (internal issue + 598). ----------------------------------------------------- -Change log for May 13, 2016 Vulkan 1.0.13 spec update: +Change log for December 1, 2016 Vulkan 1.0.36 spec update: - * Bump API patch number and header version number to 13 for this - update. + * Bump API patch number and header version number to 36 for this update. Github Issues: - * Improve the description of ename:VK_PRESENT_MODE_FIFO_RELAXED_KHR in the - VK_KHR_surface extension (public issue 174). - * Clarify use of etext:*_SIMULTANEOUS_USE_BIT for secondary command - buffers (public issue 182). - * Fix typos in VK_KHR_wayland_surface extension where code:wl_device was - used instead of code:wl_display (public issue 193). - * Replaced {apiname} with ``Vulkan'' in XML validity statements (public - issue 199). - * Fix dead links for WSI handle types (public issue 200). - * Use "signaled" instead of "signalled" spelling everywhere (public issue - 201). - * Move readme.pdf target directory for XML schema documentation into the - target generation directory, instead of leaving it checked into the spec - source tree (public issue 203). - * Fix duplicate 'which which' typo in description of - elink:VkCommandPoolResetFlagBits (public issue 204). - * Move the <> section up one level, out of - the <> section - (public issue 209). + * Fix "recorded with" terminology in the valid usage language for the + flink:vkCmdExecuteCommands::pname:pCommandBuffers parameter (public + issue 390). + * Modify +genvk.py+ to support specifying extensions to remove from output + generators, allowing the extension loader +vulkan_ext.c+ to be created + without WSI extensions which are statically exported by the Vulkan + loader (public issue 412). + * Added validation language for slink:VkSubpassDependency and in the + <> + section to catch access masks that include bits which are not supported + by pipeline stages in the stage masks (partially addresses + github.com/KhronosGroup/Vulkan-LoaderAndValidationLayers/issues/1006 ). Internal Issues: - * Clarify in the <> section that - implementations should not manage the size of pipeline cache (internal - issue 192). - * Deprecate the concept of device layers and associated commands (internal - issue 255). - * Remove ename:VK_INCOMPLETE from the list of possible result codes of - flink:vkGetPhysicalDeviceSurfaceCapabilitiesKHR (internal issue 314). - * Add missing std140/std430 rule: the base alignment of a member following - a structure is a multiple of the structure's base alignment (internal - issue 321). - * Fixes naming of the single elink:VkColorSpaceKHR enum from - ename:VK_COLORSPACE_SRGB_NONLINEAR_KHR to - ename:VK_COLOR_SPACE_SRGB_NONLINEAR_KHR in XML/header and the - VK_KHR_swapchain and VK_KHR_surface extensions to match the style of the - typename (space and color are two words, not one) (internal issue 322). - * Make it clear that code:LocalInvocationID should only be applied to an - input variable and normalize the language describing - code:LocalInvocationID to the language for other compute shader - variables in the <> - section, and add normative language (internal issue 323). - * Clarify in the <> section that - the result pointer may be modified for specific commands, even if a - runtime error is returned (internal issue 324). + * Added validation language for flink:vkCmdWaitEvents, + flink:vkQueueSubmit, flink:VkRenderPassCreateInfo, and in the + <> section to prevent + recording stage dependencies that aren't supported on the queue + (internal issue 516). + * Make a few changes that generalize spec language for use with possible + future extensions by adding glossary terms and generalizing ``feature'' + to ``feature or extension'' where relevant (internal issues 448, 590). + * Added "pipeline type" attribute to +vk.xml+ for relevant commands and + utilize it in automatic generation of the Command Properties table + (internal issue 517). + * Specify that WSI implementations must provide both UNORM and sRGB + formats in the description of slink:VkColorSpaceKHR (internal issue + 529). + * Remove nesting of explicit valid usage statements where it is not + meaningful (internal issue 583). + +Other Issues: + + * Add validity language requiring that + slink:VkPushConstantRange::pname:offset be a multiple of 4, as stated in + the spec language. ----------------------------------------------------- -Change log for May 20, 2016 Vulkan 1.0.14 spec update: +Change log for November 25, 2016 Vulkan 1.0.35 spec update: - * Bump API patch number and header version number to 14 for this - update. + * Bump API patch number and header version number to 35 for this update. Github Issues: - * Fix validity language for sname:VkCommandBufferAllocateInfo to - impose range limits on pname:commandBufferCount (public issue 178). - * Fix validity language for flink:vkCmdExecuteCommands to refer to the - correct structure names (public issue 179). - * Fix two copy-and-paste errors in the WSI queries, where the wrong - term was used for what was being returned (public issue 206). - * Add a note in the documentation of - flink:vkGetPhysicalDeviceSurfaceFormatsKHR, about what it means if - ename:VK_FORMAT_UNDEFINED is returned (public issue 207). + * Document in the <> section that + mapping and unmapping does not invalidate or flush the mapped memory + (public issues 27, 126). + * Redefine the entire <> 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 <> 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 + <> and + <> 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: - * Clarify the usage and correct the name for the bitmask referenced in - <> (internal issue - 334). - -Other Commits: - - * Fix the names of decorations listed in the - <> section such - that they match the SPIR-V specification. + * Update +vk.xml+ to make previously explicit valid usage statements for + <> 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). ----------------------------------------------------- -Change log for May 27, 2016 Vulkan 1.0.15 spec update: +Change log for November 18, 2016 Vulkan 1.0.34 spec update: - * Bump API patch number and header version number to 15 for this - update. + * Bump API patch number and header version number to 34 for this update. Github Issues: - * Fixed the <> entry for Fragment Input Attachment - Interface to specify code:UniformConstant storage class (public issue - 156). - * Disallow lazily allocated memory for buffers in the description of - slink:VkMemoryRequirements::pname:memoryTypeBits (public issue 196). - * Add numbered figure captions (public issue 219). - * Fix output variable names in the <> section and related - minor normative language and markup cleanup (public issue 220). + * Allow vkUpdateDescriptorSets overflow to skip empty bindings. Clarify + that unused bindings have a descriptorCount of zero. Improve some valid + usage for vkUpdateDescriptorSets (public issue 256). + * Require that slink:VkImageSubresourceRange always define a non-empty + range of the resource (public issue 303). + * Added valid usage for slink:VkPresentInfoKHR on the layout of presented + images (public issue 397). Internal Issues: - * Fix reference to nonexistent etext:VK_IMAGE_LAYOUT_TRANSFER_{SRC,DST}BIT - to the actual etext:VK_IMAGE_LAYOUT{SRC,DST}_OPTIMAL (internal issue - 296). - * Update the <> to refer to the correct feature names - (internal issue 305). + * Add dependency in src/spec/Makefile so specversion.txt is regenerated + when needed (internal issue 462). + * Shorten the table of contents in the single-page ref page HTML output. + Still working on the PDF (internal issue 536). ----------------------------------------------------- -Change log for June 10, 2016 Vulkan 1.0.16 spec update: +Change log for November 11, 2016 Vulkan 1.0.33 spec update: - * Bump API patch number and header version number to 16 for this - update. + * Bump API patch number and header version number to 33 for this update. Github Issues: - * Clarify that integer border values are meant to be 0/1, and that - integer texture lookups are sign-extended in the - <> and - <> sections (public - issue 52). - * Add logic to generate spec boilerplate without using the 'git' - command-line client, needed when building from a tarball or another - source of the Vulkan tree rather than a cloned git repo. Remove - boilerplate as part of 'clean' target (public issue 195). - * Document that color writes and clears to unused attachments have no - effect for slink:VkClearAttachment and - elink:VkColorComponentFlagBits (public issue 198). - * Fixed flink:vkCmdExecuteCommands validity statement for - sname:VkCommandBufferInheritanceInfo::pname:framebuffer. If used, it - must match the framebuffer in the current renderpass instance - (public issue 226). - * Added valid usage language to require for all functions that set - dynamic state that the currently bound graphics pipeline has the - corresponding dynamic state enabled (public issue 235). + * Added implicit external synchronization parameters to + vkBegin/EndCommandBuffer, and fixed missing command pool host + synchronization from per-command lists (public issue 398). + * Started using git tags including the spec release number, such as + 'v1.0.32-core', instead of tags including the date of release, such as + 'v1.0-core-20161025' (public issue 405). Internal Issues: - * Clarify for flink:vkEnumerateInstanceExtensionProperties, in the - <> section, and in the - <> section when functionality should be exposed - as an instance extension, as a device extension, or as both - (internal issue 109). - * Place WorkgroupSize in alphabetical order in the - <> section - (internal issue 323). - * Corrects valid usage in vkEndRenderPass to only affect primary - render passes, as secondaries may be entirely within a render pass, - and should be able to be ended (previous language disallowed that) - (internal issue 338). - * Fix relational operator from <= to >= in the - <> section - (internal issue 343). - * Disallow recursion under SPIR-V entry points in the - <> - section (internal SPIR-V issue 37). + * Add validity constraint for + slink:VkImportMemoryWin32HandleInfoNV::pname:handle (internal issue + #480). + * Add scripts to compare two Vulkan HTML specifications, derived from W3 + htmldiff service (internal issue 525). + * Relax requirement that memoryTypeBits can't depend on format, to allow + it to differ only for depth/stencil formats (internal issue 544). + * Add a new generator script to create a simple extension loader for + Vulkan based on +vk.xml+ (internal issue 558). + * Add the overlooked requirement that buffer and image memory + alignment requirements must be a power of two in the + <> section + (internal issue 569). -Other Commits: +Other Issues: - * Use standard Python ElementTree package instead of lxml.etree in - header / validation layer / include autogeneration from XML, - reducing platform dependencies. + * Add a naming rule to the style guide for members of extension structures + defining array lengths which are the same as array lengths of the core + structure they are chained from. + * Add a new generator to create a simple extension loader in + +src/ext_loader/vulkan_ext.[ch]+ from +vk.xml+. This code can be + included in your project, and is expected to be packaged in the Vulkan + SDK provided by LunarG in the future. ----------------------------------------------------- -Change log for June 17, 2016 Vulkan 1.0.17 spec update: +Change log for October 25, 2016 Vulkan 1.0.32 spec update: - * Bump API patch number and header version number to 17 for this - update. + * Bump API patch number and header version number to 32 for this update. Github Issues: - * Update description of vertex shader reuse in - <> (public issue 106). - * Simplify validity language around pname:ppEnabledExtensionNames and - pname:ppEnabledLayerNames (in the <> and - <> sections) (public issue 214). - * Add missing validity rule to flink:vkCmdBeginRenderPass requiring - compatibility between slink:VkAttachmentDescription pname:initalLayout - members and the corresponding attached framebuffer images (public issue - 233). - * Fix Unicode arrows appearing in output instead of relational operators - (public issue 239). - * Correctly describe the required number of elements for - code:TessLevelInner and code:TessLevelOuter arrays in the - <> section as two and - four, respectively, instead of the other way around, and refer to this - section from the <> chapter (public issue - 246). - -Internal Issues: - - * Document deprecation of ename:VK_COLORSPACE_SRGB_NONLINEAR_KHR in the - VK_KHR_surface extension, and of - ename:VK_STRUCTURE_TYPE_DEBUG_REPORT_CREATE_INFO_EXT in the - VK_EXT_debug_report extension (internal issue 328). - * Added language to define what a valid usage statement is and should be, - with a note about some apparent weirdnesses this might entail (internal - issue 357). + * Add automatic visibility operations to the presentation engineE when + doing a queue present in flink:vkAcquireNextImageKHR. Removed all + references to MEMORY_READ that referenced WSI - they no longer make + sense (some aspects of public issues 128, 131, 132, 261, and 298). + * Document valid non-boolean +externsync+ attribute values for + tags in +vk.xml+ (public issue 265). + * Add valid usage to slink:VkImageCreateInfo requiring that + pname:arrayLayers be 1 for images of type ename:VK_IMAGE_TYPE_3D + (public issue 319). + * Add missing captions to figures in the <> + chapter (public issue 334). + * Clarify WSI interaction with exclusive sharing mode (public issue + 344). + * Added explicit language clarifying the allowed queue usage of + resources created with ename:VK_SHARING_MODE_CONCURRENT (public + issue 386). + * Require that the + slink:VkDescriptorSetLayoutCreateInfo::pname:binding members of the + pname:pBindings array passed to + flink:vkDescriptorSetLayoutCreateInfo all be distinct (public issue + 391). -Other Commits: +Internal Issues: - * Added missing ename:VK_ERROR_DEVICE_LOST error to - flink:vkQueueBindSparse. + * Remove empty validity blocks from +vk.xml+ and suppressed broken + validity statements and added missing statements to explicit + validity. Doesn't affect output, other than some statements + appearing in another block now (internal issue 513). ----------------------------------------------------- -Change log for June 24, 2016 Vulkan 1.0.18 spec update: +Change log for October 14, 2016 Vulkan 1.0.31 spec update: - * Bump API patch number and header version number to 18 for this - update. + * Bump API patch number and header version number to 31 for this update. Github Issues: - * Added "queue operation" terminology, and modified spec to actually - use this terminology (public issue 155). The act of submitting a - piece of work to a queue now generates "operations" for the queue to - execute, including operations to wait on/signal semaphores and - fences. Synchronization waits on these operations, making execution - dependency chains more obvious for semaphores and fences (though - additional work is still needed here). These changes include: - ** Overview of "queue submission" commands in chapter - <>. - ** Updated descriptions for fence and semaphore waits and signals in - the synchronization chapter <>, - <> and - <>. - ** Clarifications to semaphore and fence operation within queue - submission functions. - ** New glossary terms. - ** Moved device idle and queue wait idle to synchronization chapter in - order to describe them in terms of other synchronization - primitives. - ** Clarifications to semaphore and fence operation allowed removal of - the "implicit ordering guarantees" section, as this information is - now wholly covered where these primitives are described. - *** The "host writes" section of this is still there for now - in its - own section. This could probably be merged into other sections - later. - *** Modified fundamentals chapter on queue ordering to make sense in - context of the new changes, and avoid duplication. - <> - * Added "aspect" and "component" definitions to the glossary, and made - sure these terms are referenced correctly (public issue 163). - * Update valid usage for ftext:vkGet*ProcAddr to only include - conditions that must be met to get a valid result. In particular, - it is okay to call flink:vkGetDeviceProcAddr with any string and will - get a code:NULL if that string is not a core Vulkan function or an - enabled extension function (addresses but does not fully close - public issue 214). - * Change the WSI extension dependencies to refer to version 1.0 of the - Vulkan API, instead of the pre-1.0-release internal revisions - numbers (public issue 238). - * Specified that <> result in undefined values input to the blending - unit or color attachment (public issue 240). - * Fix latexmath:[$\leq$] operators turning into Unicode left arrow symbols - (public issue 245). + * Clarifying wording of slink:VkGraphicsPipelineCreateInfo parameters and + adding Valid Usage statements on render pass compatibility to the + <> (public issue 375). + * Replace 'texel size' with 'element size', and add a definition to the + glossary (public issue 382). + * Clarify the description of ename:VK_ERROR_NATIVE_WINDOW_IN_USE_KHR to + make it accurate, but still generic (non-exhaustive). Remove two Valid + Usage statements describing error situations that will return + ename:VK_ERROR_NATIVE_WINDOW_IN_USE_KHR (public issue 387). + * Fix refBegin tag for elink:VkDebugReportFlagBitsEXT (public issue 392). + * The <> code:PrimitiveId + in a fragment shader needs the code:Input storage class (public issue + 393). Internal Issues: - * Better documented that the registry XML "optional" tag for values - only applies when that value is the size of an array (internal issue - 335). - * Add a stronger definition for the valid usages of - VkSpecializationMapEntry.size in the - <> - section (internal issue 345). - * Change code:OpName to code:OpDecorate (along with appropriate - syntax) for vertex shader built-ins (internal issue 368). - * Add missing ref pages (those which are not currently stubs) to - apispec.txt for the single-page version of the ref pages (internal - issue 378). - -Other Commits: - - * Fix example in the <> section to use - M, N, and I, describing set, binding, and index, consistently - throughout the example code. + * Unused ({y,z} and {height,depth} for 1D, z and depth for 2D) offsets + must be 0 and unused extents must be 1. Added basic offset and extent + valid usage for slink:VkImageResolve to match that of slink:VkImageCopy + (internal issue 413). + * Describe what flink:vkGetPhysicalDeviceImageFormatProperties returns for + pname:sampleCounts when for pname:usage only includes transfer-related + flags (internal issue 478). + * Remove mention of + slink:VkPhysicalDeviceLimits::pname:maxImageArrayLayers from the valid + usage for slink:VkImageCreateInfo::pname:arrayLayers (internal issue + 520). + * Tag usages of ``dynamically uniform'' as glossary terms and add a + glossary entry pointing to the SPIR-V Specification's definition of the + term (internal issue 531). ----------------------------------------------------- -Change log for July 1, 2016 Vulkan 1.0.19 spec update: +Change log for October 7, 2016 Vulkan 1.0.30 spec update: - * Bump API patch number and header version number to 19 for this - update. + * Bump API patch number and header version number to 30 for this update. Github Issues: - * Clarified how flink:vkGetImageSubresourceLayout interacts with image - layouts (public issue 247). - * Remove ename:VK_IMAGE_LAYOUT_PREINITIALIZED from valid usage rule for - slink:VkImageMemoryBarrier::pname:oldLayout. It is only valid if it is - the current layout (public issue 248). - * Modify valid usage for flink:vkBindBufferMemory so implementations are - free to require a different backing memory size than the buffer size - (public issue 251). - * Clarify that filtering rules for flink:vkCmdBlitImage always apply, and - are usually no-ops if the formats are the same (public issue 253). - * Remove 'non-sparse' from description of - flink:vkGetBufferMemoryRequirements and - flink:vkGetImageMemoryRequirements (public issue 257). - * Remove ename:VK_ERROR_LAYER_NOT_PRESENT error code from - flink:vkCreateDevice (public issue 259). - * Change "must: not" to "should: not" in constraint on when - flink:vkAcquireNextImageKHR is called in the VK_KHR_swapchain branch - (public issue 262). - * Change type of flink:vkCmdUpdateBuffer::pname:pData from - basetype:uint32_t* to basetype:void* (public issue 263). - * Change should: to must: in description of where additional segments are - placed in the <<[tessellation-tessellator-spacing,Tessellator Spacing>> - section (public issue 264). + * Document missing pname:sType and pname:pNext parameters for + slink:VkCommandBufferInheritanceInfo (public issue 224). + * As promised, we are removing the example code, from the appendix, for + the VK_KHR_surface and VK_KHR_swapchain extensions. The cube demo + (shipped in the official Khronos SDK) has been updated, and is the + example code that we want people to look at for how to use these two + extensions (public issues 279, 308, and 311). + * Clarify the formats for which the slink:VkClearColorValue pname:float32 + member is used. Also clean up related language for flink:vkCmdBlitImage + (public issue 369). + * Reword the <> appendix chapter to better match + Vulkan terminology (public issue 372). Internal Issues: - * Normalize the language of all the compute shader built-ins in the - <> section (internal - issue 323). - * Remove definition of presentation engine internal queue lengths - associated with ename:VK_PRESENT_MODE_FIFO_KHR and - ename:VK_PRESENT_MODE_FIFO_RELAXED_KHR in the <> chapter (internal issue 374). - * The language of a Note was too broad, and implied that loaders for a - given OS would statically export functions for WSI extensions that - were not relevant to (or supported on) the OS. Also, removed - "Khronos-provided" since the Android loader is not (internal issue 380) - -Other Commits: - - * Add ename:VK_INCOMPLETE to list of return values for - flink:vkGetPipelineCacheData. Spec says this value is returnable, but it - was not listed in the error codes. - * Fix "correponds" typo in member definitions for - slink:VkSubpassDescription. + * Update slink:VkMemoryRequirements to not require a host_visible memory + type exists that can be bound to sparse buffers (internal issue 494). + * Modify the <> + language to allow multisampled depth-stencil images (internal issue + 521). ----------------------------------------------------- -Change log for July 8, 2016 Vulkan 1.0.20 spec update: +Change log for September 30, 2016 Vulkan 1.0.29 spec update: - * Bump API patch number and header version number to 20 for this - update. + * Bump API patch number and header version number to 29 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 - is not 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. Various minor tweaks to the Specification sources were - made to enable this, and a new ``API Boilerplate'' chapter added to - include definitions of all the entities in the API and +vulkan.h+ which - were not already described in some form in the document. + * Remove redundant constraint on + slink:VkCommandBufferInheritanceInfo::pname:queryFlags (public issue + 224). + * Fix typo and remove link in Note in the + <> section (public issue 359). + * Fix erroneous validation statement for the pname:layout member of + slink:VkComputePipelineCreateInfo (public issue 362). - 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). +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). -Change log for July 15, 2016 Vulkan 1.0.21 spec update: +Other Issues: - * Bump API patch number and header version number to 21 for this update. + * Use the terms ``allocation scope'' and ``extension scope'' instead of + just ``scope'', and add them to the glossary. -Github Issues: +----------------------------------------------------- - * Clarify how <> - relate to the limits in slink:VkPhysicalDeviceLimits. (public issue - 185). - * Clarify in the <> section that shader output variables have undefined values - until the shader writes to them (public issue 240). - * Specify the implicit value of image parameters that cannot be set in - slink:VkSwapchainCreateInfo::pname:flags, pname:imageType, - pname:mipLevels, pname:samples, pname:tiling, and pname:initialLayout - (public issue 243). - * Make use of code:NULL and code:VK_NULL_HANDLE consistent in the - VK_KHR_swapchain extension (public issue 276). - -Internal Issues: - - * Clarify that presenting an image to a display surface swapchain applies - the display surface's mode, and that destroying a display surface - swapchain may reset the display's mode, in the VK_KHR_display_swapchain - extension (internal issue 247). - * Better describe what a slink:VkSurfaceKHR is, and that creating one does - not set a mode, in the VK_KHR_display extension. This is a round-about - way of pointing out that mode setting is not covered by the extension, - but rather is performed as a side effect of presentation (internal issue - 247). - * Add more valid usage statements to flink:vkQueuePresentKHR command when - the VK_KHR_display_swapchain extension is present (internal issue - 247). - * Add more includes to the VK_KHR_swapchain extension to better document - interactions with VK_KHR_display_swapchain (internal issue 247). - * Clarify restrictions on location aliasing in the - <> section (internal issue - 370). - * Add mathematical description of blitting to flink:vkCmdBlitImage, and - link it to the <> chapter. Use mathematical - notation for ranges of texel coordinates in the <> chapter. Fixed miscellaneous validity statements for - flink:vkCmdBlit and slink:VkImageBlit (internal issue 382). - -Other Commits: - - * Added a valid usage rule to flink:VkGraphicsPipelineCreateInfo that the - ename:VK_PRIMITIVE_TOPOLOGY_PATCH_LIST topology must only be used when - tessellation shaders are used. - * Expand the style guide into a formal "Procedures and Conventions" - document. Add a API Naming Conventions section, move most of the API - Specification Appendix C (Layers and Extensions) content into the new - document, and define the resulting procedures as mandatory (where - relevant). This more clearly separates use vs. specification of Vulkan - APIs. - * Update vk_platform.h to handle 32-bit ARMv8 binaries. - * Various minor cleanups to the Makefile and build process. - ------------------------------------------------------ - -Change log for July 22, 2016 Vulkan 1.0.22 spec update: +Change log for September 23, 2016 Vulkan 1.0.28 spec update: - * Bump API patch number and header version number to 22 for this update. + * Bump API patch number and header version number to 28 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). + * 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 + <> table are n * + maxPerStage limit (where n=number of supported stages) (public issue + 254). + * Minor cleanup to <> 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 <> section to describe the external headers included when + each etext:VK_USE_PLATFORM_* macro is defined (public issue 376). 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 <> 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). + * 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 <> 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 <> 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 Commits: +Other Issues: - * 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. + * Reflowed text of the entire spec using the 'reflow' Makefile target, to + (hopefully) reduce future internal git churn as edits are made and + extensions added in return for one-time pain. This has no perceptible + effect on the spec outputs, but considerable changes on the asciidoc + source (internal issue 367). ----------------------------------------------------- -Change log for August 5, 2016 Vulkan 1.0.23 spec update: +Change log for September 16, 2016 Vulkan 1.0.27 spec update: - * Bump API patch number and header version number to 23 for this update. + * Bump API patch number and header version number to 27 for this update. Github Issues: - * Add explicit valid value attributes to pname:sType members in vk.xml - (public issue 34). - * Clarify usage of flink:vkGetInstanceProcAddr and - flink:vkGetDeviceProcAddr (public issue 225). - * Fix a copy-and-paste error in the description of - pname:pSwapchainImageCount saying that it was the count of ``format - pairs'' instead of ``swapchain images'' (public issue 292). - * flink:vkCmdExecuteCommandBuffers requires all command buffers to be - allocated from command pools created for the same queue family (public - issue 296). - * Remove bogus +optional+ attribute for - flink:vkEnumerateDeviceLayerProperties::pname:physicalDevice from vk.xml - (public issue 301). - * Clean up the <> reference and contents. Use full enumerant names. - Refer to pname:layerCount in the ``view parameters'' column instead of - pname:arrayLayers. Require N >= 1 for the cube array subview row, not - just arrayLayers >= 6 N (public issue 304). - * Modify description of <> to - be consistent with the description of - <> (public - issue 307). + * Weaken flink:vkGetPipelineCacheData invariance conditions; previous + conditions were stronger than agreed and can't be guaranteed (public + issue 280). + * Add link to "Vulkan Loader Specification and Architecture Overview" + document to Normative References section (public issue 359). Internal Issues: - * Describe remaining +vk_platform.h+ macros in the <> appendix (internal issue 6). - * Clarify - <> - feature behavior; what memory can be accessed, how bounds checking is - performed, and allowing for vectorization (internal issue 332). - * Document markup for automatic extraction of reference pages from the - spec sources in the style guide (internal issue 395). - * Allow flink:vkCreateDisplayModeKHR to return - ename:VK_ERROR_INITIALIZAION_FAILED_KHR if the user requests mode - parameters that the specified display does not support (internal issue - 411). - * Remove atomic counters (atomic_uint style) from KHR_vulkan_glsl, and - more clearly remove the subroutine keyword alongside it (internal issue - 421). - * Clarify behavior of flink:vkCmdBindDescriptorSets for descriptor sets - not contained in the layout (internal issue 427). + * Be more clear in the <> section that block offsets can be out of order + (internal issue 396). + * Document that extension authors should add support for their extensions + to the validation layers (internal issue 398). + * Clarify that the valid range of depth clear values should be limited + to the 0..1 range and that copies to depth aspect must also be in this + range (internal issue 412). + * Specify ``a'' vs. ``an'' use in the style guide (internal issue 432). + * Increase the maximum pname:nonCoherentAtomSize value in the + <> section from 128 to 256 + (internal issue 435). + * Fix vk_platform.h for compiler errors on some Android platforms + (internal issue 441). + * Clarify that slink:VkPhysicalDeviceFeatures::pname:pEnabledFeatures == + `NULL` disables all features, including the "required" feature + pname:robustBufferAccess (internal issue 479). -Other Commits: +Other Issues: - * Change the order in which members of sname:VkAttachmentDescription and - sname:VkPipelineInputAssemblyStateCreateInfo are described to match - their order in the structures. + * Expand style guide and make it more self-consistent. + * Use ISO 8601 date format everywhere. + * Emphasise the correct way of using + slink:VkSurfaceCapabilitiesKHR::pname:maxImageCount. + * Added +VK_EXT_validation_flags+ extension for validation flag mechanism. + * Fix an <> to include their current employer. ----------------------------------------------------- -Change log for August 12, 2016 Vulkan 1.0.24 spec update: +Change log for September 6, 2016 Vulkan 1.0.26 spec update: - * Bump API patch number and header version number to 24 for this update. - -Github Issues: - - * Fix type mismatch in swapchain image equivalency table (public issue - 289). - * Fix a copy-and-paste error in the description of - flink:vkGetSwapchainImagesKHR::pname:pSwapchainImages, that said it - was an array of ``sname:VkSwapchainImageKHR structures'' instead of - an array of ``sname:VkImage handles'' (public issue 292). - * Specify that ename:VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT is only valid - for ename:VK_IMAGE_TYPE_2D images (public issue 293). - * Add a valid usage statement to flink:vkCmdExecuteCommands saying - that when called outside a render pass instance, the secondary - command buffers must not have been created with the - ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT (public issue - 297). - * Fix description of +VK_NO_STDINT_H+ in the - <> section (public - issue 314). - -Internal Issues: - - * Normalize the language for the remaining built-in variables in the - <> section. Fix - code:FrontFacing and code:HelperInvocation, as they should be of - code:boolean type rather than code:integer (internal issue 323). - * Clarify that when ename:VK_WHOLE_SIZE is used for a buffer - descriptor range, the effective range must still be within the max - buffer range (internal issue 426). - * Clarify that command buffers and descriptor sets are allocated - rather than created. Also clarify when the recording state of a - command buffer is relevant (internal issue 434). - ------------------------------------------------------ - -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 <> 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 - <> 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). - ------------------------------------------------------ - -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. + * Bump API patch number and header version number to 26 for this update. Github Issues: @@ -1300,760 +904,1227 @@ Other Issues: ----------------------------------------------------- -Change log for September 16, 2016 Vulkan 1.0.27 spec update: +Change log for August 26, 2016 Vulkan 1.0.25 spec update: - * Bump API patch number and header version number to 27 for this 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: - * Weaken flink:vkGetPipelineCacheData invariance conditions; previous - conditions were stronger than agreed and can't be guaranteed (public - issue 280). - * Add link to "Vulkan Loader Specification and Architecture Overview" - document to Normative References section (public issue 359). + * Clarify description of GetInstanceProcAddr and GetDeviceProcAddr (public + issue 212). + * Add SPIR-V <> 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: - * Be more clear in the <> section that block offsets can be out of order - (internal issue 396). - * Document that extension authors should add support for their extensions - to the validation layers (internal issue 398). - * Clarify that the valid range of depth clear values should be limited - to the 0..1 range and that copies to depth aspect must also be in this - range (internal issue 412). - * Specify ``a'' vs. ``an'' use in the style guide (internal issue 432). - * Increase the maximum pname:nonCoherentAtomSize value in the - <> section from 128 to 256 - (internal issue 435). - * Fix vk_platform.h for compiler errors on some Android platforms - (internal issue 441). - * Clarify that slink:VkPhysicalDeviceFeatures::pname:pEnabledFeatures == - `NULL` disables all features, including the "required" feature - pname:robustBufferAccess (internal issue 479). - -Other Issues: - - * Expand style guide and make it more self-consistent. - * Use ISO 8601 date format everywhere. - * Emphasise the correct way of using - slink:VkSurfaceCapabilitiesKHR::pname:maxImageCount. - * Added +VK_EXT_validation_flags+ extension for validation flag mechanism. - * Fix an <> to include their current employer. + * Update style guide regarding use of code:NULL and dname:VK_NULL_HANDLE + (internal issue 393). + * Change the definition of latexmath:[$q$] in the + <> 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). ----------------------------------------------------- -Change log for September 23, 2016 Vulkan 1.0.28 spec update: +Change log for August 12, 2016 Vulkan 1.0.24 spec update: - * Bump API patch number and header version number to 28 for this update. + * Bump API patch number and header version number to 24 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 - <> table are n * - maxPerStage limit (where n=number of supported stages) (public issue - 254). - * Minor cleanup to <> 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 <> section to describe the external headers included when - each etext:VK_USE_PLATFORM_* macro is defined (public issue 376). + * Fix type mismatch in swapchain image equivalency table (public issue + 289). + * Fix a copy-and-paste error in the description of + flink:vkGetSwapchainImagesKHR::pname:pSwapchainImages, that said it + was an array of ``sname:VkSwapchainImageKHR structures'' instead of + an array of ``sname:VkImage handles'' (public issue 292). + * Specify that ename:VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT is only valid + for ename:VK_IMAGE_TYPE_2D images (public issue 293). + * Add a valid usage statement to flink:vkCmdExecuteCommands saying + that when called outside a render pass instance, the secondary + command buffers must not have been created with the + ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT (public issue + 297). + * Fix description of +VK_NO_STDINT_H+ in the + <> section (public + issue 314). 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 <> 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 <> 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 target, to - (hopefully) reduce future internal git churn as edits are made and - extensions added in return for one-time pain. This has no perceptible - effect on the spec outputs, but considerable changes on the asciidoc - source (internal issue 367). + * Normalize the language for the remaining built-in variables in the + <> section. Fix + code:FrontFacing and code:HelperInvocation, as they should be of + code:boolean type rather than code:integer (internal issue 323). + * Clarify that when ename:VK_WHOLE_SIZE is used for a buffer + descriptor range, the effective range must still be within the max + buffer range (internal issue 426). + * Clarify that command buffers and descriptor sets are allocated + rather than created. Also clarify when the recording state of a + command buffer is relevant (internal issue 434). ----------------------------------------------------- -Change log for September 30, 2016 Vulkan 1.0.29 spec update: +Change log for August 5, 2016 Vulkan 1.0.23 spec update: - * Bump API patch number and header version number to 29 for this update. + * Bump API patch number and header version number to 23 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 - <> 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). + * Add explicit valid value attributes to pname:sType members in vk.xml + (public issue 34). + * Clarify usage of flink:vkGetInstanceProcAddr and + flink:vkGetDeviceProcAddr (public issue 225). + * Fix a copy-and-paste error in the description of + pname:pSwapchainImageCount saying that it was the count of ``format + pairs'' instead of ``swapchain images'' (public issue 292). + * flink:vkCmdExecuteCommandBuffers requires all command buffers to be + allocated from command pools created for the same queue family (public + issue 296). + * Remove bogus +optional+ attribute for + flink:vkEnumerateDeviceLayerProperties::pname:physicalDevice from vk.xml + (public issue 301). + * Clean up the <> reference and contents. Use full enumerant names. + Refer to pname:layerCount in the ``view parameters'' column instead of + pname:arrayLayers. Require N >= 1 for the cube array subview row, not + just arrayLayers >= 6 N (public issue 304). + * Modify description of <> to + be consistent with the description of + <> (public + issue 307). -Other Issues: +Internal Issues: - * Use the terms ``allocation scope'' and ``extension scope'' instead of - just ``scope'', and add them to the glossary. + * Describe remaining +vk_platform.h+ macros in the <> appendix (internal issue 6). + * Clarify + <> + feature behavior; what memory can be accessed, how bounds checking is + performed, and allowing for vectorization (internal issue 332). + * Document markup for automatic extraction of reference pages from the + spec sources in the style guide (internal issue 395). + * Allow flink:vkCreateDisplayModeKHR to return + ename:VK_ERROR_INITIALIZAION_FAILED_KHR if the user requests mode + parameters that the specified display does not support (internal issue + 411). + * Remove atomic counters (atomic_uint style) from KHR_vulkan_glsl, and + more clearly remove the subroutine keyword alongside it (internal issue + 421). + * Clarify behavior of flink:vkCmdBindDescriptorSets for descriptor sets + not contained in the layout (internal issue 427). + +Other Commits: + + * Change the order in which members of sname:VkAttachmentDescription and + sname:VkPipelineInputAssemblyStateCreateInfo are described to match + their order in the structures. ----------------------------------------------------- -Change log for October 7, 2016 Vulkan 1.0.30 spec update: +Change log for July 22, 2016 Vulkan 1.0.22 spec update: - * Bump API patch number and header version number to 30 for this update. + * Bump API patch number and header version number to 22 for this update. Github Issues: - * Document missing pname:sType and pname:pNext parameters for - slink:VkCommandBufferInheritanceInfo (public issue 224). - * As promised, we are removing the example code, from the appendix, for - the VK_KHR_surface and VK_KHR_swapchain extensions. The cube demo - (shipped in the official Khronos SDK) has been updated, and is the - example code that we want people to look at for how to use these two - extensions (public issues 279, 308, and 311). - * Clarify the formats for which the slink:VkClearColorValue pname:float32 - member is used. Also clean up related language for flink:vkCmdBlitImage - (public issue 369). - * Reword the <> appendix chapter to better match - Vulkan terminology (public issue 372). + * 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: - * Update slink:VkMemoryRequirements to not require a host_visible memory - type exists that can be bound to sparse buffers (internal issue 494). - * Modify the <> - language to allow multisampled depth-stencil images (internal issue - 521). + * 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 <> 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. ----------------------------------------------------- -Change log for October 14, 2016 Vulkan 1.0.31 spec update: +Change log for July 15, 2016 Vulkan 1.0.21 spec update: - * Bump API patch number and header version number to 31 for this update. + * Bump API patch number and header version number to 21 for this update. Github Issues: - * Clarifying wording of slink:VkGraphicsPipelineCreateInfo parameters and - adding Valid Usage statements on render pass compatibility to the - <> (public issue 375). - * Replace 'texel size' with 'element size', and add a definition to the - glossary (public issue 382). - * Clarify the description of ename:VK_ERROR_NATIVE_WINDOW_IN_USE_KHR to - make it accurate, but still generic (non-exhaustive). Remove two Valid - Usage statements describing error situations that will return - ename:VK_ERROR_NATIVE_WINDOW_IN_USE_KHR (public issue 387). - * Fix refBegin tag for elink:VkDebugReportFlagBitsEXT (public issue 392). - * The <> code:PrimitiveId - in a fragment shader needs the code:Input storage class (public issue - 393). + * Clarify how <> + relate to the limits in slink:VkPhysicalDeviceLimits. (public issue + 185). + * Clarify in the <> section that shader output variables have undefined values + until the shader writes to them (public issue 240). + * Specify the implicit value of image parameters that cannot be set in + slink:VkSwapchainCreateInfo::pname:flags, pname:imageType, + pname:mipLevels, pname:samples, pname:tiling, and pname:initialLayout + (public issue 243). + * Make use of code:NULL and code:VK_NULL_HANDLE consistent in the + VK_KHR_swapchain extension (public issue 276). Internal Issues: - * Unused ({y,z} and {height,depth} for 1D, z and depth for 2D) offsets - must be 0 and unused extents must be 1. Added basic offset and extent - valid usage for slink:VkImageResolve to match that of slink:VkImageCopy - (internal issue 413). - * Describe what flink:vkGetPhysicalDeviceImageFormatProperties returns for - pname:sampleCounts when for pname:usage only includes transfer-related - flags (internal issue 478). - * Remove mention of - slink:VkPhysicalDeviceLimits::pname:maxImageArrayLayers from the valid - usage for slink:VkImageCreateInfo::pname:arrayLayers (internal issue - 520). - * Tag usages of ``dynamically uniform'' as glossary terms and add a - glossary entry pointing to the SPIR-V Specification's definition of the - term (internal issue 531). + * Clarify that presenting an image to a display surface swapchain applies + the display surface's mode, and that destroying a display surface + swapchain may reset the display's mode, in the VK_KHR_display_swapchain + extension (internal issue 247). + * Better describe what a slink:VkSurfaceKHR is, and that creating one does + not set a mode, in the VK_KHR_display extension. This is a round-about + way of pointing out that mode setting is not covered by the extension, + but rather is performed as a side effect of presentation (internal issue + 247). + * Add more valid usage statements to flink:vkQueuePresentKHR command when + the VK_KHR_display_swapchain extension is present (internal issue + 247). + * Add more includes to the VK_KHR_swapchain extension to better document + interactions with VK_KHR_display_swapchain (internal issue 247). + * Clarify restrictions on location aliasing in the + <> section (internal issue + 370). + * Add mathematical description of blitting to flink:vkCmdBlitImage, and + link it to the <> chapter. Use mathematical + notation for ranges of texel coordinates in the <> chapter. Fixed miscellaneous validity statements for + flink:vkCmdBlit and slink:VkImageBlit (internal issue 382). + +Other Commits: + + * Added a valid usage rule to flink:VkGraphicsPipelineCreateInfo that the + ename:VK_PRIMITIVE_TOPOLOGY_PATCH_LIST topology must only be used when + tessellation shaders are used. + * Expand the style guide into a formal "Procedures and Conventions" + document. Add a API Naming Conventions section, move most of the API + Specification Appendix C (Layers and Extensions) content into the new + document, and define the resulting procedures as mandatory (where + relevant). This more clearly separates use vs. specification of Vulkan + APIs. + * Update vk_platform.h to handle 32-bit ARMv8 binaries. + * Various minor cleanups to the Makefile and build process. ----------------------------------------------------- -Change log for October 25, 2016 Vulkan 1.0.32 spec update: +Change log for July 8, 2016 Vulkan 1.0.20 spec update: - * Bump API patch number and header version number to 32 for this update. + * Bump API patch number and header version number to 20 for this + update. Github Issues: - * Add automatic visibility operations to the presentation engineE when - doing a queue present in flink:vkAcquireNextImageKHR. Removed all - references to MEMORY_READ that referenced WSI - they no longer make - sense (some aspects of public issues 128, 131, 132, 261, and 298). - * Document valid non-boolean +externsync+ attribute values for - tags in +vk.xml+ (public issue 265). - * Add valid usage to slink:VkImageCreateInfo requiring that - pname:arrayLayers be 1 for images of type ename:VK_IMAGE_TYPE_3D - (public issue 319). - * Add missing captions to figures in the <> - chapter (public issue 334). - * Clarify WSI interaction with exclusive sharing mode (public issue - 344). - * Added explicit language clarifying the allowed queue usage of - resources created with ename:VK_SHARING_MODE_CONCURRENT (public - issue 386). - * Require that the - slink:VkDescriptorSetLayoutCreateInfo::pname:binding members of the - pname:pBindings array passed to - flink:vkDescriptorSetLayoutCreateInfo all be distinct (public issue - 391). - -Internal Issues: + * Replaced existing reference pages by text automatically extracted from + the specification source, or generated from vk.xml in some cases. This + is not 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. Various minor tweaks to the Specification sources were + made to enable this, and a new ``API Boilerplate'' chapter added to + include definitions of all the entities in the API and +vulkan.h+ which + were not already described in some form in the document. - * Remove empty validity blocks from +vk.xml+ and suppressed broken - validity statements and added missing statements to explicit - validity. Doesn't affect output, other than some statements - appearing in another block now (internal issue 513). + 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). ----------------------------------------------------- -Change log for November 11, 2016 Vulkan 1.0.33 spec update: +Change log for July 1, 2016 Vulkan 1.0.19 spec update: - * Bump API patch number and header version number to 33 for this update. + * Bump API patch number and header version number to 19 for this + update. Github Issues: - * Added implicit external synchronization parameters to - vkBegin/EndCommandBuffer, and fixed missing command pool host - synchronization from per-command lists (public issue 398). - * Started using git tags including the spec release number, such as - 'v1.0.32-core', instead of tags including the date of release, such as - 'v1.0-core-20161025' (public issue 405). + * Clarified how flink:vkGetImageSubresourceLayout interacts with image + layouts (public issue 247). + * Remove ename:VK_IMAGE_LAYOUT_PREINITIALIZED from valid usage rule for + slink:VkImageMemoryBarrier::pname:oldLayout. It is only valid if it is + the current layout (public issue 248). + * Modify valid usage for flink:vkBindBufferMemory so implementations are + free to require a different backing memory size than the buffer size + (public issue 251). + * Clarify that filtering rules for flink:vkCmdBlitImage always apply, and + are usually no-ops if the formats are the same (public issue 253). + * Remove 'non-sparse' from description of + flink:vkGetBufferMemoryRequirements and + flink:vkGetImageMemoryRequirements (public issue 257). + * Remove ename:VK_ERROR_LAYER_NOT_PRESENT error code from + flink:vkCreateDevice (public issue 259). + * Change "must: not" to "should: not" in constraint on when + flink:vkAcquireNextImageKHR is called in the VK_KHR_swapchain branch + (public issue 262). + * Change type of flink:vkCmdUpdateBuffer::pname:pData from + basetype:uint32_t* to basetype:void* (public issue 263). + * Change should: to must: in description of where additional segments are + placed in the <<[tessellation-tessellator-spacing,Tessellator Spacing>> + section (public issue 264). Internal Issues: - * Add validity constraint for - slink:VkImportMemoryWin32HandleInfoNV::pname:handle (internal issue - #480). - * Add scripts to compare two Vulkan HTML specifications, derived from W3 - htmldiff service (internal issue 525). - * Relax requirement that memoryTypeBits can't depend on format, to allow - it to differ only for depth/stencil formats (internal issue 544). - * Add a new generator script to create a simple extension loader for - Vulkan based on +vk.xml+ (internal issue 558). - * Add the overlooked requirement that buffer and image memory - alignment requirements must be a power of two in the - <> section - (internal issue 569). + * Normalize the language of all the compute shader built-ins in the + <> section (internal + issue 323). + * Remove definition of presentation engine internal queue lengths + associated with ename:VK_PRESENT_MODE_FIFO_KHR and + ename:VK_PRESENT_MODE_FIFO_RELAXED_KHR in the <> chapter (internal issue 374). + * The language of a Note was too broad, and implied that loaders for a + given OS would statically export functions for WSI extensions that + were not relevant to (or supported on) the OS. Also, removed + "Khronos-provided" since the Android loader is not (internal issue 380) -Other Issues: +Other Commits: - * Add a naming rule to the style guide for members of extension structures - defining array lengths which are the same as array lengths of the core - structure they are chained from. - * Add a new generator to create a simple extension loader in - +src/ext_loader/vulkan_ext.[ch]+ from +vk.xml+. This code can be - included in your project, and is expected to be packaged in the Vulkan - SDK provided by LunarG in the future. + * Add ename:VK_INCOMPLETE to list of return values for + flink:vkGetPipelineCacheData. Spec says this value is returnable, but it + was not listed in the error codes. + * Fix "correponds" typo in member definitions for + slink:VkSubpassDescription. ----------------------------------------------------- -Change log for November 18, 2016 Vulkan 1.0.34 spec update: +Change log for June 24, 2016 Vulkan 1.0.18 spec update: - * Bump API patch number and header version number to 34 for this update. + * Bump API patch number and header version number to 18 for this + update. Github Issues: - * Allow vkUpdateDescriptorSets overflow to skip empty bindings. Clarify - that unused bindings have a descriptorCount of zero. Improve some valid - usage for vkUpdateDescriptorSets (public issue 256). - * Require that slink:VkImageSubresourceRange always define a non-empty - range of the resource (public issue 303). - * Added valid usage for slink:VkPresentInfoKHR on the layout of presented - images (public issue 397). + * Added "queue operation" terminology, and modified spec to actually + use this terminology (public issue 155). The act of submitting a + piece of work to a queue now generates "operations" for the queue to + execute, including operations to wait on/signal semaphores and + fences. Synchronization waits on these operations, making execution + dependency chains more obvious for semaphores and fences (though + additional work is still needed here). These changes include: + ** Overview of "queue submission" commands in chapter + <>. + ** Updated descriptions for fence and semaphore waits and signals in + the synchronization chapter <>, + <> and + <>. + ** Clarifications to semaphore and fence operation within queue + submission functions. + ** New glossary terms. + ** Moved device idle and queue wait idle to synchronization chapter in + order to describe them in terms of other synchronization + primitives. + ** Clarifications to semaphore and fence operation allowed removal of + the "implicit ordering guarantees" section, as this information is + now wholly covered where these primitives are described. + *** The "host writes" section of this is still there for now - in its + own section. This could probably be merged into other sections + later. + *** Modified fundamentals chapter on queue ordering to make sense in + context of the new changes, and avoid duplication. + <> + * Added "aspect" and "component" definitions to the glossary, and made + sure these terms are referenced correctly (public issue 163). + * Update valid usage for ftext:vkGet*ProcAddr to only include + conditions that must be met to get a valid result. In particular, + it is okay to call flink:vkGetDeviceProcAddr with any string and will + get a code:NULL if that string is not a core Vulkan function or an + enabled extension function (addresses but does not fully close + public issue 214). + * Change the WSI extension dependencies to refer to version 1.0 of the + Vulkan API, instead of the pre-1.0-release internal revisions + numbers (public issue 238). + * Specified that <> result in undefined values input to the blending + unit or color attachment (public issue 240). + * Fix latexmath:[$\leq$] operators turning into Unicode left arrow symbols + (public issue 245). Internal Issues: - * Add dependency in src/spec/Makefile so specversion.txt is regenerated - when needed (internal issue 462). - * Shorten the table of contents in the single-page ref page HTML output. - Still working on the PDF (internal issue 536). + * Better documented that the registry XML "optional" tag for values + only applies when that value is the size of an array (internal issue + 335). + * Add a stronger definition for the valid usages of + VkSpecializationMapEntry.size in the + <> + section (internal issue 345). + * Change code:OpName to code:OpDecorate (along with appropriate + syntax) for vertex shader built-ins (internal issue 368). + * Add missing ref pages (those which are not currently stubs) to + apispec.txt for the single-page version of the ref pages (internal + issue 378). + +Other Commits: + + * Fix example in the <> section to use + M, N, and I, describing set, binding, and index, consistently + throughout the example code. ----------------------------------------------------- -Change log for November 25, 2016 Vulkan 1.0.35 spec update: +Change log for June 17, 2016 Vulkan 1.0.17 spec update: - * Bump API patch number and header version number to 35 for this update. + * Bump API patch number and header version number to 17 for this + update. Github Issues: - * Document in the <> section that - mapping and unmapping does not invalidate or flush the mapped memory - (public issues 27, 126). - * Redefine the entire <> 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 <> 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 - <> and - <> 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). + * Update description of vertex shader reuse in + <> (public issue 106). + * Simplify validity language around pname:ppEnabledExtensionNames and + pname:ppEnabledLayerNames (in the <> and + <> sections) (public issue 214). + * Add missing validity rule to flink:vkCmdBeginRenderPass requiring + compatibility between slink:VkAttachmentDescription pname:initalLayout + members and the corresponding attached framebuffer images (public issue + 233). + * Fix Unicode arrows appearing in output instead of relational operators + (public issue 239). + * Correctly describe the required number of elements for + code:TessLevelInner and code:TessLevelOuter arrays in the + <> section as two and + four, respectively, instead of the other way around, and refer to this + section from the <> chapter (public issue + 246). Internal Issues: - * Update +vk.xml+ to make previously explicit valid usage statements for - <> 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). + * Document deprecation of ename:VK_COLORSPACE_SRGB_NONLINEAR_KHR in the + VK_KHR_surface extension, and of + ename:VK_STRUCTURE_TYPE_DEBUG_REPORT_CREATE_INFO_EXT in the + VK_EXT_debug_report extension (internal issue 328). + * Added language to define what a valid usage statement is and should be, + with a note about some apparent weirdnesses this might entail (internal + issue 357). ------------------------------------------------------ +Other Commits: -Change log for December 1, 2016 Vulkan 1.0.36 spec update: + * Added missing ename:VK_ERROR_DEVICE_LOST error to + flink:vkQueueBindSparse. - * Bump API patch number and header version number to 36 for this update. +----------------------------------------------------- -Github Issues: +Change log for June 10, 2016 Vulkan 1.0.16 spec update: - * Fix "recorded with" terminology in the valid usage language for the - flink:vkCmdExecuteCommands::pname:pCommandBuffers parameter (public - issue 390). - * Modify +genvk.py+ to support specifying extensions to remove from output - generators, allowing the extension loader +vulkan_ext.c+ to be created - without WSI extensions which are statically exported by the Vulkan - loader (public issue 412). - * Added validation language for slink:VkSubpassDependency and in the - <> - section to catch access masks that include bits which are not supported - by pipeline stages in the stage masks (partially addresses - github.com/KhronosGroup/Vulkan-LoaderAndValidationLayers/issues/1006 ). + * Bump API patch number and header version number to 16 for this + update. -Internal Issues: +Github Issues: - * Added validation language for flink:vkCmdWaitEvents, - flink:vkQueueSubmit, flink:VkRenderPassCreateInfo, and in the - <> section to prevent - recording stage dependencies that aren't supported on the queue - (internal issue 516). - * Make a few changes that generalize spec language for use with possible - future extensions by adding glossary terms and generalizing ``feature'' - to ``feature or extension'' where relevant (internal issues 448, 590). - * Added "pipeline type" attribute to +vk.xml+ for relevant commands and - utilize it in automatic generation of the Command Properties table - (internal issue 517). - * Specify that WSI implementations must provide both UNORM and sRGB - formats in the description of slink:VkColorSpaceKHR (internal issue - 529). - * Remove nesting of explicit valid usage statements where it is not - meaningful (internal issue 583). + * Clarify that integer border values are meant to be 0/1, and that + integer texture lookups are sign-extended in the + <> and + <> sections (public + issue 52). + * Add logic to generate spec boilerplate without using the 'git' + command-line client, needed when building from a tarball or another + source of the Vulkan tree rather than a cloned git repo. Remove + boilerplate as part of 'clean' target (public issue 195). + * Document that color writes and clears to unused attachments have no + effect for slink:VkClearAttachment and + elink:VkColorComponentFlagBits (public issue 198). + * Fixed flink:vkCmdExecuteCommands validity statement for + sname:VkCommandBufferInheritanceInfo::pname:framebuffer. If used, it + must match the framebuffer in the current renderpass instance + (public issue 226). + * Added valid usage language to require for all functions that set + dynamic state that the currently bound graphics pipeline has the + corresponding dynamic state enabled (public issue 235). -Other Issues: +Internal Issues: - * Add validity language requiring that - slink:VkPushConstantRange::pname:offset be a multiple of 4, as stated in - the spec language. + * Clarify for flink:vkEnumerateInstanceExtensionProperties, in the + <> section, and in the + <> section when functionality should be exposed + as an instance extension, as a device extension, or as both + (internal issue 109). + * Place WorkgroupSize in alphabetical order in the + <> section + (internal issue 323). + * Corrects valid usage in vkEndRenderPass to only affect primary + render passes, as secondaries may be entirely within a render pass, + and should be able to be ended (previous language disallowed that) + (internal issue 338). + * Fix relational operator from <= to >= in the + <> section + (internal issue 343). + * Disallow recursion under SPIR-V entry points in the + <> + section (internal SPIR-V issue 37). + +Other Commits: + + * Use standard Python ElementTree package instead of lxml.etree in + header / validation layer / include autogeneration from XML, + reducing platform dependencies. ----------------------------------------------------- -Change log for December 10, 2016 Vulkan 1.0.37 spec update: +Change log for May 27, 2016 Vulkan 1.0.15 spec update: - * Bump API patch number and header version number to 37 for this update. + * Bump API patch number and header version number to 15 for this + update. Github Issues: - * Add usability guarantees on the values returned by - flink:vkGetPhysicalDeviceSurfaceCapabilitiesKHR in the - slink:VkSurfaceCapabilitiesKHR structure and by - flink:vkGetPhysicalDeviceSurfaceFormatsKHR in the - pname:pSurfaceFormatCount parameter (public issue 385). - * Add elink:VkDebugReportObjectTypeEXT enumerants for new object types - introduced by new extensions (public issue 408). - * Add +VK_NVX_device_generated_commands+ etext:ACCESS bits and define how - they are used (public issue 415). - * Fix indentation for slink:VkDebugReportCallbackCreateInfoEXT member - descriptions (public issue 419). + * Fixed the <> entry for Fragment Input Attachment + Interface to specify code:UniformConstant storage class (public issue + 156). + * Disallow lazily allocated memory for buffers in the description of + slink:VkMemoryRequirements::pname:memoryTypeBits (public issue 196). + * Add numbered figure captions (public issue 219). + * Fix output variable names in the <> section and related + minor normative language and markup cleanup (public issue 220). Internal Issues: - * Expand requirements memory binding of non-sparse images and buffers from - the <> section into - valid usage statements for all of the applicable API calls (internal - issue 508). - * Explicitly state that valid usage of flink:vkCreateImage requires that - flink:vkGetPhysicalDeviceImageFormatProperties would return - ename:VK_SUCCESS for the requested image configuration (internal issue - 598). + * Fix reference to nonexistent etext:VK_IMAGE_LAYOUT_TRANSFER_{SRC,DST}BIT + to the actual etext:VK_IMAGE_LAYOUT{SRC,DST}_OPTIMAL (internal issue + 296). + * Update the <> to refer to the correct feature names + (internal issue 305). ----------------------------------------------------- -Change log for December 16, 2016 Vulkan 1.0.38 spec update: +Change log for May 20, 2016 Vulkan 1.0.14 spec update: - * Bump API patch number and header version number to 38 for this update. + * Bump API patch number and header version number to 14 for this + update. Github Issues: - * Make ename:VK_PIPELINE_STAGE_HOST_BIT invalid for all stage masks, - except for flink:vkCmdWaitEvents (public issue 261). + * Fix validity language for sname:VkCommandBufferAllocateInfo to + impose range limits on pname:commandBufferCount (public issue 178). + * Fix validity language for flink:vkCmdExecuteCommands to refer to the + correct structure names (public issue 179). + * Fix two copy-and-paste errors in the WSI queries, where the wrong + term was used for what was being returned (public issue 206). + * Add a note in the documentation of + flink:vkGetPhysicalDeviceSurfaceFormatsKHR, about what it means if + ename:VK_FORMAT_UNDEFINED is returned (public issue 207). Internal Issues: - * Added validation language for flink:vkQueueBindSparse, - slink:VkPresentInfoKHR, and slink:VkSubmitInfo, and a note to the - <> - section to clarify that semaphores must be signaled and waited on in a - 1:1 fashion (internal issue 546). - * Modify valid usage for slink:VkBufferImageCopy to only require - pname:bufferOffset to be a multiple of the image format's element size - when the format is not depth/stencil (internal issue 594). + * Clarify the usage and correct the name for the bitmask referenced in + <> (internal issue + 334). -Other Issues: +Other Commits: - * Vulkan(R) is now a registered trademark symbol, and this is reflected in - documents and copyright statements. + * Fix the names of decorations listed in the + <> section such + that they match the SPIR-V specification. ----------------------------------------------------- -Change log for January 23, 2017 Vulkan 1.0.39 spec update: +Change log for May 13, 2016 Vulkan 1.0.13 spec update: - * Bump API patch number and header version number to 39 for this update. + * Bump API patch number and header version number to 13 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). + * Improve the description of ename:VK_PRESENT_MODE_FIFO_RELAXED_KHR in the + VK_KHR_surface extension (public issue 174). + * Clarify use of etext:*_SIMULTANEOUS_USE_BIT for secondary command + buffers (public issue 182). + * Fix typos in VK_KHR_wayland_surface extension where code:wl_device was + used instead of code:wl_display (public issue 193). + * Replaced {apiname} with ``Vulkan'' in XML validity statements (public + issue 199). + * Fix dead links for WSI handle types (public issue 200). + * Use "signaled" instead of "signalled" spelling everywhere (public issue + 201). + * Move readme.pdf target directory for XML schema documentation into the + target generation directory, instead of leaving it checked into the spec + source tree (public issue 203). + * Fix duplicate 'which which' typo in description of + elink:VkCommandPoolResetFlagBits (public issue 204). + * Move the <> section up one level, out of + the <> section + (public issue 209). Internal Issues: - * Add a Note to the <> appendix about a difference - between OpenGL and Vulkan with regards to how primitives derived from - offsets are handled (internal issue 355). - * Add the +<>+, - +<>+, and +<>+ - extensions (internal issue 448). - * Add the +<>+ and - +<>+ extensions (internal issue 449). - * Update the texture level-of-detail equation in the - <> 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 <> 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 <> 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 <> section of the spec but were not reflected in the valid - usage text for these functions. - * Add the +<>+ extension defining common - color spaces. + * Clarify in the <> section that + implementations should not manage the size of pipeline cache (internal + issue 192). + * Deprecate the concept of device layers and associated commands (internal + issue 255). + * Remove ename:VK_INCOMPLETE from the list of possible result codes of + flink:vkGetPhysicalDeviceSurfaceCapabilitiesKHR (internal issue 314). + * Add missing std140/std430 rule: the base alignment of a member following + a structure is a multiple of the structure's base alignment (internal + issue 321). + * Fixes naming of the single elink:VkColorSpaceKHR enum from + ename:VK_COLORSPACE_SRGB_NONLINEAR_KHR to + ename:VK_COLOR_SPACE_SRGB_NONLINEAR_KHR in XML/header and the + VK_KHR_swapchain and VK_KHR_surface extensions to match the style of the + typename (space and color are two words, not one) (internal issue 322). + * Make it clear that code:LocalInvocationID should only be applied to an + input variable and normalize the language describing + code:LocalInvocationID to the language for other compute shader + variables in the <> + section, and add normative language (internal issue 323). + * Clarify in the <> section that + the result pointer may be modified for specific commands, even if a + runtime error is returned (internal issue 324). ----------------------------------------------------- -Change log for February 10, 2017 Vulkan 1.0.40 spec update: +Change log for April 29, 2016 Vulkan 1.0.12 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. + * Bump API patch number and header version number to 12 for this + update. Github Issues: - * Updated sample code for the <> (public issue 97). - * Modify line and point clipping behavior in the - <> 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 <>, <>, and - <>; the - discussion of <>; - and references elsewhere to these sections (public issue 133). - * Clarify \<\> - 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 <> (public - issue 447). + * Change valid usage statements intended to be "sub-points" to + be actual sub-points (public issue 66). + * Replace double negation in description of + slink:VkRenderPassBeginInfo::pname:pClearValues (based on public + merge 142). + * Cleanup minor typos in spec, ref pages and XML, including those + proposed in public pull requests 144, 150, 151, 167, 168, 181, and + 186. + * Use *strict subset* in describing the partial order of memory + property types for slink:VkMemoryType, and update the style guide + accordingly (public issue 190). + * Fix various "a image" -> "an image" typos (public issue 191). + * Note in the <> and + <> sections that + structures defined by extensions which may be passed in structure + chains using the ptext:pNext member must include initial + ptext:sType and ptext:pNext members (public issue 192). 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). + * Remove duplicate language from the description of the pname:fence + parameter to flink:vkQueueSubmit and improve validity language + (internal issue 91). + * Added documentation for "optional" attribute to XML readme.tex/pdf + (internal issue 149). + * Clarify the host-side data validity rules and behavior of + flink:vkFlushMappedMemoryRanges and + flink:vkInvalidateMappedMemoryRanges (internal issue 266). -Other Issues: +Other Commits: - * 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 <> 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. + * Added clarification to flink:vkCmdFillBuffer regarding the use of + ename:VK_WHOLE_SIZE. + * Fixed and documented implementation of "validextensionstructs" + attribute. in XML processing scripts and readme.tex/pdf. + * Add missing validity statements to flink:vkResetEvent and + flink:vkCmdResetEvent. + * Fix validity for the + ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT flag. + Correct all the draw/dispatch commands to mention optimally tiled + images as well as linear tiled images, and say image VIEWS instead + of images. Add validity statement to flink:vkCmdBlitImage + * Replace the {apiname} macro with hardcoded "Vulkan", now that we have + committed to that name. + * Add the VK_AMD_rasterization_order extension to vk.xml. ----------------------------------------------------- -Change log for February 17, 2017 Vulkan 1.0.41 spec update: +Change log for April 22, 2016 Vulkan 1.0.11 spec update: - * Bump API patch number and header version number to 41 for this update. + * Bump API patch number and header version number to 11 for this + update. Github Issues: - * Made all uses of `NULL` vs. code:VK_NULL_HANDLE consistent (public issue - 276). - * Clarify render pass compatibility in different usage scenarios (public - issues 303 and 304). - * Add valid usage statements to slink:VkFramebufferCreateInfo requiring - that the width, height, and number of layers of the framebuffer all be - nonzero (public issue 432). - * Allow `offset` and `align` in any GLSL version for the - `GL_KHR_vulkan_glsl` extension (public issue 435). - * Specify lifetime of string objects passed to the - tlink:PFN_vkDebugReportCallbackEXT user callback in the - +VK_EXT_debug_report+ extension (public issue 446). - * Fix inter-page links in multi-file reference pages (public issue 454). + * Clarify the WSI extension language by switching from the fuzzier + "ownership" language to more-consistent "acquire" language (public + issue 117). + * Clarify that memory barriers apply to all commands in the dependency + chains in the flink:vkGetRenderAreaGranularity command and the + <> section (public issue 132). + * Clarify that a queue family is a set of queues in the + <> section (public issue + 166). + * Removed requirement from valid usage language that + VkPresentInfoKHR::waitSemaphoreCount must be greater than 0 (public + issue 171). + * Fix broken internal links, describe structures consistently, use + consistent style for SPIR-V codewords, and tag normative terms that + were missing asciidoc tags (public issue 183 and ancillary + markup/normative language fixes). + * Fix typos for slink:VkPhysicalDeviceLimits member names in + slink:VkImageCreateInfo validity language (public issue 184). Internal Issues: - * Update valid usage language for slink:VkImageCreateInfo to disallow - creating images that have ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT - set without other attachment usage bits - (ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT, - ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT, or - ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT) (internal issue 540). - * Disable `VK_EXT_swapchain_colorspace` extension until internal issues - 640 and 661 are mutually resolved. - * Allow alternative mipmap level selection when [eq]#lambda == 0.5# during - texture <> - (internal issue 680). + * Document that the requested patch version number specified as part + of slink:VkApplicationInfo::pname:apiVersion is ignored when + creating an instance (internal issue 176). + * Clarify handling of extension structs in the + <> section (internal issue 254). + * Update required slink:VkImageFormatProperties::pname:maxMipLevels to + be limited to the maximum allowed mipmap pyramid size corresponding + to the actual maximum supported size for the format (internal issue + 256). + * Modify the <> section so the allowed maximum extent is the maximum + image dimension supported for each dimension of the type of texture + being queried (internal issue 257). + * Clarify in the <> section that at least one of the code:LocalSize execution + mode or code:WorkgroupSize decoration is required for each compute + shader entry point in a shader module (internal issue 279). + * Add validity rules for formats in flink:vkCmdClearColorImage and + flink:vkCmdClearDepthStencilImage (internal issue 283). + * Clarify that slink:VkImageFormatProperties::pname:maxResourceSize is + an upper bound, and that it may not be possible to create an image + anywhere near that size (internal issue 284). -Other Issues: +Other Commits: - * Add a clarification to the style guide that the extension revision - number is treated as a patch number, so that changes to published - extensions should only include bug fixes and spec clarifications. + * Fix various minor markup errors reported by validation scripts. + * Change copyright from Khronos Free Use License to Apache 2.0 license + on relevant script/XML/header files. This does not affect the + specification source copyright. ----------------------------------------------------- -Change log for February 27, 2017 Vulkan 1.0.42 spec update: +Change log for April 15, 2016 Vulkan 1.0.10 spec update: - * Bump API patch number and header version number to 42 for this update - (the first anniversary edition). + * Bump API patch number and header version number to 10 for this + update. Github Issues: - * Changed asciidoctor macros so cross-page links in the standalone - reference pages function properly (public issue 462). + * Slightly tweak the <> allocator language + so that an application wrapping the standard C alloc/free/realloc + functions is still correct - the previous language was too strong with + regards to freeing memory. Also made certain scenarios clearer - an + implementation may now continue without error if an allocation failed + and it is able to continue correctly (public issue 21). + * Require that etext:VK_*_CREATE_SPARSE_BINDING_BIT is set when the + corresponding etext:VK_*_CREATE_SPARSE_RESIDENCY_BIT is used, in the + <> section and related commands + flink:vkCreateBuffer and flink:vkCreateImage (public issue 84). + * Update the <> chapter to clarify + interactions between optional features and dynamic state for the + pname:depthBiasClamp and pname:wideLines features (public issue 89). + * Describe the code:WorkgroupSize builtin in the + <> section, and update + the <> section to further clarify how + to set the number of workgroups to execute in a compute shader (public + issue 145). + * Use the term *image subresource* everywhere instead of *subresource*, + except for the special case of *host-accessible subresource*, which may + be either an image subresource or buffer range (public issue 120) + * Add a note to the <> section + about extensibility of structures (Public issue 165). + * Fix return code flink:vkAcquireNextImageKHR when the timeout parameter + is 0 to ename:VK_NOT_READY instead of ename:VK_TIMEOUT (public issue + 170). + * Fix typo in slink:VkLayerProperties::pname:apiVersion field (public + issue 172). Internal Issues: - * Clarified host visibility discussion for slink:VkMemoryType, - flink:vkInvalidateMappedMemoryRanges, elink:VkAccessFlagBits, and the - <> - section, removing duplicated information and adding a central definition - in the access types section (internal issue 552). - * Change description of - slink:vkGetPhysicalDeviceSurfacePresentModesKHR::pname:pPresentModes to - return an array of values, not structures (internal issue 699). - -New Extensions: - - * Add a NOTE to the <> chapter describing - the experimental status of `KHX` extensions. - * Add new Khronos, Khronos Experimental, and vendor Vulkan extensions for - release at GDC: - ** VK_KHR_descriptor_update_template - ** VK_KHR_push_descriptor - ** VK_KHX_device_group - ** VK_KHX_device_group_creation - ** VK_KHX_external_memory - ** VK_KHX_external_memory_capabilities - ** VK_KHX_external_memory_fd - ** VK_KHX_external_memory_win32 - ** VK_KHX_external_semaphore - ** VK_KHX_external_semaphore_capabilities - ** VK_KHX_external_semaphore_fd - ** VK_KHX_external_semaphore_win32 - ** VK_KHX_multiview - ** VK_KHX_win32_keyed_mutex - ** VK_EXT_discard_rectangles - ** VK_MVK_ios_surface - ** VK_MVK_macos_surface - ** VK_NVX_multiview_per_view_attributes - ** VK_NV_clip_space_w_scaling - ** VK_NV_geometry_shader_passthrough - ** VK_NV_sample_mask_override_coverage - ** VK_NV_viewport_array2 - ** VK_NV_viewport_swizzle - * Add new GLSL vendor extensions to support new builtin variables: - ** GL_EXT_device_group - ** GL_EXT_multiview + * Fix a few minor internally-detected typos. + * Minor formatting tweaks to pseudocode in the <> chapter (internal issue 179). + * Fix typo in the definition of point sampling for + elink:VkCullModeFlagBits (internal issue 268). ----------------------------------------------------- -Change log for March 10, 2017 Vulkan 1.0.43 spec update: +Change log for April 8, 2016 Vulkan 1.0.9 spec update: - * Bump API patch number and header version number to 43 for this update. + * Bump API patch number and header version number to 9 for this + update. Github Issues: - * Make clearer that color write mask is applied regardless of whether - blending is enabled, by referring to the - <> section (public issue - 241). - * Fix public issue 414: - ** Added two new command buffer states (invalid, pending), and an explicit - "command buffer lifecycle" section to explain them. - ** Replaced "pending execution" with "in the pending state". - ** Replaced a bunch of "this will invalidate the command buffer" language - with "this will move the command buffer to the invalid state", and added - validation language for what state those command buffers should be in. - ** Added additional validation language about what state a command buffer - should be in for various commands that affect it. - ** Added invalidation language to destroy commands in the lifetimes section - of fundamentals. - ** Added command buffers to list of objects which must not be deleted - whilst a (primary) command buffer is in the recording or pending state. - * Update `GL_KHR_vulkan_glsl` extension to allow anonymous push constant - blocks (public issue 428). + * Fix memory type preorder definition and clarify example list and source + code for slink:VkMemoryRequirements and slink:VkMemoryHeap (public issue + 26). + * Ensure slink:VkAllocationCallbacks are properly defined (public issue + 73). + * Clarify the WSI extension language by switching from the fuzzier + "ownership" language to more-consistent "acquire" language (public issue + 117). + * Add language allowing allocation and freeing of memory scoped to the + duration of any API command in the <> section (public issue 136). + * Clarify the explicit location assignment always overrides the inherited + location in the <> section, even for the first member of a block (public issue + 141). + * Fixed references to + slink:VkCommandBufferInheritanceInfo::pname:pipelineStatistics (public + issue 158). + * Fix name of slink:VkBufferCopy::pname:size field in validity language + for flink:vkCmdCopyBuffer (public issue 162). Internal Issues: - * Document rules about extension interactions in the style guide (internal - issue 579). - * Require ename:VK_PRESENT_MODE_MAILBOX_KHR support in queries of surfaces - created with flink:vkCreateWaylandSurfaceKHR using the - VK_KHR_wayland_surface extension (internal issue 666). - * Remove Valid Usage constraints for flink:vkAllocateDescriptorSets when - the `VK_KHR_maintainance1` extension is present (internal issue 686). - * Remove undocumented KHX-variants of vkGetPhysicalDeviceProperties2KHR - and vkGetPhysicalDeviceImageFormatProperties2KHR from the - <> and - <> extensions. + * Update GL_KHR_vulkan_glsl specification to clarify disallowance of + spec-const arrays in initializers (internal issue 248). + * Clarify <> section + to state that user-defined variable interface must match too (internal + issue 250). -New Extensions: +----------------------------------------------------- + +Change log for April 1, 2016 Vulkan 1.0.8 spec update: + + * Bump API patch number and header version number to 8 for this + update. + +Github Issues: + + * Specify in the validity language for flink:vkBeginCommandBuffer that + pname:commandBuffer must not currently be pending execution (public + issue 96). + * Describe depth comparison using the correct temporary variable names + in the <> + section (public issue 100). + * Clarify the order of descriptor update operations in the + flink:vkUpdateDescriptorSets command (public issue 115). + * Specify in the VK_KHR_swapchain extension that + flink:vkAcquireNextImageKHR's pname:semaphore and pname:fence + parameters cannot both be sname:VK_NULL_HANDLE (partly addresses, + but does not fully close, public issue 117 / internal issue 246). + * Change reference to the "lifetime" of a Vulkan command to + "duration", and define the "duration" term (public issue 135). + * Added valid usage language for slink:VkImageLayout to require both + pname:height and pname:depth to be 1 for 1D images and pname:depth + to be 1 for 2D images (public issue 137). + * Fix SPIR-V example code in the + <> section to + properly decorate the code:InputAttachmentIndex (public issue 139). + * Fix reference to nonexistent pname:imageInfo in the description of + flink:VkWriteDescriptorSet to refer to pname:pImageInfo (public + issue 140). + +Internal Issues: + + * Link to the fixed-function vertex chapter from the drawing chapter + (internal issue 110) + * Fix typo in slink:VkImageCreateInfo validity language: + ptext:maxExtent.sampleCounts -> pname:sampleCounts (internal issue + 249). + * Explain why the non-core token etext:VK_IMAGE_LAYOUT_PRESENT_SRC_KHR + is used in the example in the + <> section (internal issue + 251). + * Attempt to clarify in the VK_KHR_android_surface extension's + <> section + that there is no Android-specific WSI query, and why (internal issue + 252). + +Other Commits: + + * Add missing language about ename:VK_INCOMPLETE being returned from + array queries when the passed array is too short, in the + VK_KHR_display, VK_KHR_swapchain, and VK_KHR_surface extensions. + +----------------------------------------------------- + +Change log for March 25, 2016 Vulkan 1.0.7 spec update: + + * Bump API patch number and header version number to 7 for this + update. + +Github Issues: + + * Fix slink:VkSpecializationMapEntry example to avoid C/C++ strict + aliasing issues (public issue 14). + * Clarify the meaning of "matching" in flink:vkCmdBindDescriptorSets + validity language (public issue 33). + * Add stub reference pages so xrefs to not-yet-written pages do not + generate 404 errors. However, the actual content of these pages + still needs to be filled in as time allows (public issue 44, but + does not close that issue out). + * Remove incorrect validity statement for + flink:vkGetImageSparseMemoryRequirements (public issue 85). + * Reword the + <> + feature in terms of "aliasing", and clarify that it applies to + bindings in the same memory object (public issue 90). + * Clarify the relationship of the slink:VkPhysicalDeviceLimits + pname:maxViewportDimensions and pname:viewportBoundsRange limits + (public issue 92). + * Specify sparse unbound texture replacement in the + <> section + independently of robust buffer access language (public issue 100). + * Add the <> + section to explain architecture constraints Vulkan has chosen to + accept in order to enable portable and performant code (public issue + 122). + * State that an object must not be destroyed until *all* (not *any*) + uses of that object have completed (public issue 123). + * Minor editorial cleanup (public issues 129, 134, 146, 148). + * Add validity language for layer and extension names to + slink:VkDeviceCreateInfo matching that used for + slink:VkInstanceCreateInfo (public issue 130). + * Clean up terminology for the case when the bits set in one bitmask + are a subset of the bits set in another bitmask (public issue 138). + * Document that input attachments are UniformConstant not Input, in + the <> section (public glslang bug 169). + +Internal Issues: + + * Add max enum values to "flag bits" enums (internal issue 136). + * Clarify language around the various uses of the term "block" in the + <> section + (internal issue 202). + * Removed "expand" dependency from groups in vk.xml and added + auto-generation code in the scripts to infer it instead, to ensure + consistency. This caused renaming of sname:VkColorSpaceKHR and + sname:VkPresentModeKHR etext:BEGIN_RANGE (etc.) tokens, but those + tokens are metadata, not part of the API, and the Vulkan WG is OK + with this change. This change adds ranges to two additional enums + that were missing them due to not defining the "expand" attribute + (internal issue 217). + * Tweak makefile to generate ref page nroff (.3) files in the right + output directory, working around an a2x limitation (internal issue + 223). + +Other Commits: + + * Add validity requirements for flink:vkCmdCopyQueryPoolResults + pname:dstBuffer parameter. + * Fix ref page build to generate .3 targets in the right output + directory. + +----------------------------------------------------- + +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 + <> + section (public issue 45). + * Editorial fixes for <> section (public issues 54, 59). + * Clarify behavior of depth test in the <> + section (public issues 80, 81). + * Remove discussion of return codes from + flink:vkGetPhysicalDeviceSparseImageFormatProperties and + flink:vkGetImageSparseMemoryRequirements, which do not 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 <> + 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 <> diagram. Use more easily distinguished symbols in + tables in the <> section. Do not require FQDNs used as layer names be + encoded in lower case if not possible, in the + <> 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__" 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. + +----------------------------------------------------- + +Change log for March 4, 2016 Vulkan 1.0.5 spec update: + + * Bump API patch number to 5 for this update. + +Github Issues: + + * Correctly describe slink:VkPhysicalDeviceProperties pname:deviceName + member as a string, not a pointer to a string. Also one typo fix for + "hetereogeneous" (public issue 4). + * Replace maynot: macro with may: not, and "may: or maynot:" with + "may:" (public issue 4). + * Clarify that redundantly setting the state of a fence or event has + no effect (public issue 4). + * Minor fixes to ref pages to track descriptions of memory bits that + changed in the core spec. Fix name of a member in the description of + sname:sname:VkPipelineMultisampleStateCreateInfo (public issues 8, + 13). + * Remove redundant validity statement for + sname:VkGraphicsPipelineCreateInfo::pname:stageCount (public issue + 14). + * Fix typos in chapters 7-9 (public issue 14). + * Clarify the example demonstrating the behavior of + code:OpMemoryBarrier in the + <> section (public issue 16). + * Specify that freeing mapped memory implicitly unmaps the memory in + the description of flink:vkFreeMemory (public issue 17). + * Forbid allocation callbacks from calling into the API in the + <> section (public issue + 20). + * Add missing validity rules about size being greater than 0 and + offset being less than size of object. Fix + flink:VkMappedMemoryRange's misinterpretation of offset (public + issues 27, 31). + * Add validity rule disallowing overlapping source/destination + descriptors in flink:VkCopyDescriptorSet (public issue 32). + * Clarify that array and matrix stride has to be a multiple of the + base alignment of the array or matrix in the + <> + section (public issue 38). + * Correct parenthesis floor nesting error in equation for + <>. + Clarify case of when exp' is forced to 0, avoiding log2(0) undefined + problem (public issue 40). + * Remove redundant statement from the code:FragDepth description in + the <> + section (public issue 47). + * Define the clamping of the + <> by linking to the slink:VkPhysicalDevice feature + pname:maxSamplerLodBias (public issue 64). + * Fix typo "optimal linear resources" and clarify the set of resources + <> applies to (public issue + 67). + * Replace 'descriptor accessed by a pipeline' language for + sname:VkDescriptorSetAllocateInfo with more precise phrasing about + binding a descriptor set before a command that invokes work using + that set (public issue 69). + * tstripadj.svg contained an Inkscape tag which caused Firefox and IE + 11 to fail to render it, and was illegal SVG. Generating Plain SVG + from the Inkscape SVG source fixes this (public issue 70). + * Fix validity for sname:VkVertexInputBindingDescription and + sname:VkVertexInputAttributeDescription numbers (public issue 72). + +Internal Issues: + + * Clarify the meaning of + ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT in + elink:VkFormatFeatureFlagBits with respect to depth compare + (internal issue 107). + * Added a note explaining that ename:VK_QUEUE_TRANSFER_BIT may or may + not be reported for a queue family that already supports + ename:VK_QUEUE_GRAPHICS_BIT or ename:VK_QUEUE_COMPUTE_BIT as the + former is a strict subset of the latter ones (internal issue 116). + * Add validity language for sname:VkDescriptorSetAllocateInfo about + exceeding the descriptor pool capacity (internal issue 140). + * Add ename:VK_INCOMPLETE success code for + flink:vkEnumeratePhysicalDevices query (internal issue 163). + +Other Commits: + + * Add the VK_NV_glsl_shader extension definitions to the API. + * Update GL_KHR_vulkan_glsl with 1) origin_upper_left as default 2) + specialization array constant semantics. + * Corrected/updated Data Format Specification date. + +----------------------------------------------------- + +Change log for February 25, 2015 Vulkan 1.0.4 spec update: + + * Bump API patch number from 3 to 4 for the first public update to the + spec. Add patch number to the spec title (this will be done + automatically from XML, later). + * Fixes for numerous editorial issues. Regularize descriptions of + variable-length array queries. Properly tag enumerants so they come + out in the right font (many were mislabeled in usage tags in vk.xml, + or not tagged). Spelling and markup corrections (public issue 4). + * Fix typos and clearly separate description of different types of + memory areas (public issue 5). + * Use standards-compliant preprocessor guard symbols on headers + (public issue 7). + * Note that Github users cannot currently set labels on issues, and + recommend a fallback approach (public issue 15). + * Use latexmath prefix on len= attributes (public issue 29). + * Make flink:vkCmdUpdateBuffer pname:dataSize limit consistent (public + issue 65). + * Add VK_KHR_mirror_clamp_to_edge extension to core API branch, as an + optional feature not introducing new commands or enums (internal + issue 104). + * Cleanup invariance language inherited from the GL specification to + not refer to nonexistent (GL-specific) state (internal issue 111). + * Modify the flink:vkCmdDrawIndexed pname:vertexOffset definition to + not be the "base offset within the index buffer" but rather the + "value added to the vertex index before indexing into the vertex + buffer" (internal issue 118). + * Fix drawing chapter in the "Programmable Primitive Shading" section + where it described categories of drawing commands. It referenced + flink:vkCmdDrawIndexed twice. Replace the second reference with + flink:vkCmdDrawIndexedIndirect (internal issue 119). + * Typo fixed in <> sparse memory example (internal issue 122). + * Add flink:VkDisplayPlaneAlphaFlagsKHR to section of + VK_KHR_display extension (internal issue 125) + * Add missing optional="false,true" to + flink:vkGetImageSparseMemoryRequirements + pname:pSparseMemoryRequirementCount parameter (internal issue 132) + * Rename ename:VK_STRUCTURE_TYPE_DEBUG_REPORT_CREATE_INFO_EXT to + ename:VK_STRUCTURE_TYPE_DEBUG_REPORT_CALLBACK_CREATE_INFO_EXT + (internal issue 133) + * Fix a handful of broken cross-references in the + <> chapter (internal issue 134). + * Fix "Input Attachement" GLSL example to use correct syntax (internal + issue 135). + * Update XML schema and documentation to accomodate recently added + attributes for validity. Add some introductory material describing + design choices and pointing to the public repository to file issues. + * Put include of validity in the core spec extensions chapter on its + own line, so that asciidoc is happy. + * Fix vertexOffset language to specify that it is the value added to + the vertex index before indexing into the vertex buffer, not the + base offset within the index buffer. + * Fix error in the description of flink:vkCmdNextSubpass. + +----------------------------------------------------- + +February 16, 2016 - Vulkan 1.0 initial public release - * `VK_EXT_hdr_metadata` - * `VK_GOOGLE_display_timing` diff --git a/doc/specs/vulkan/Makefile b/doc/specs/vulkan/Makefile index ad7e2b4841..b488df7d7c 100644 --- a/doc/specs/vulkan/Makefile +++ b/doc/specs/vulkan/Makefile @@ -86,7 +86,7 @@ VERBOSE = # $(EXTENSIONS)) # ADOCOPTS options for asciidoc->HTML5 output NOTEOPTS = -a editing-notes -a implementation-guide -SPECREVISION = 1.0.43 +SPECREVISION = 1.0.44 # Spell out RFC2822 format as not all date commands support -R SPECDATE = $(shell echo `date -u "+%a, %d %b %Y %T %z"`) diff --git a/doc/specs/vulkan/appendices/VK_AMD_rasterization_order.txt b/doc/specs/vulkan/appendices/VK_AMD_rasterization_order.txt index 974e02a2d5..270f9da992 100644 --- a/doc/specs/vulkan/appendices/VK_AMD_rasterization_order.txt +++ b/doc/specs/vulkan/appendices/VK_AMD_rasterization_order.txt @@ -91,9 +91,9 @@ reduce overdraw by appropriately ordering the input primitives? *RESOLVED*: While the relaxed rasterization order might somewhat limit the effectiveness of such content optimizations, most of the benefits of it are -expected to be retained even when the relaxed rasterization order is used so -applications are still recommended to apply these optimizations even if they -intend to use the extension. +expected to be retained even when the relaxed rasterization order is used, +so applications should: still apply these optimizations even if they intend +to use the extension. 3) Are there any guarantees about the primitive rasterization order when using the new relaxed mode? diff --git a/doc/specs/vulkan/appendices/VK_EXT_display_surface_counter.txt b/doc/specs/vulkan/appendices/VK_EXT_display_surface_counter.txt index cb569b8ecd..40e22ea09a 100644 --- a/doc/specs/vulkan/appendices/VK_EXT_display_surface_counter.txt +++ b/doc/specs/vulkan/appendices/VK_EXT_display_surface_counter.txt @@ -28,7 +28,7 @@ This is extension defines a vertical blanking period counter associated with display surfaces. It provides a mechanism to query support for such a counter from a -slink:VkSurface object. +slink:VkSurfaceKHR object. === New Enum Constants diff --git a/doc/specs/vulkan/appendices/VK_EXT_swapchain_colorspace.txt b/doc/specs/vulkan/appendices/VK_EXT_swapchain_colorspace.txt index 29034f17e0..4090e829e7 100644 --- a/doc/specs/vulkan/appendices/VK_EXT_swapchain_colorspace.txt +++ b/doc/specs/vulkan/appendices/VK_EXT_swapchain_colorspace.txt @@ -108,7 +108,7 @@ flink:vkCreateSwapchainKHR will create a swapchain using that color space. Vulkan requires that all implementations support the sRGB OETF and EOTF when using an SRGB pixel format. -Other transfer functions, such as SMPTE 170M, must not: be performed by the +Other transfer functions, such as SMPTE 170M, must: not be performed by the implementation, but can: be performed by the application shader. === New Enum Constants diff --git a/doc/specs/vulkan/appendices/VK_KHR_display.txt b/doc/specs/vulkan/appendices/VK_KHR_display.txt index 44053a955b..58f15e4217 100644 --- a/doc/specs/vulkan/appendices/VK_KHR_display.txt +++ b/doc/specs/vulkan/appendices/VK_KHR_display.txt @@ -13,9 +13,9 @@ *Status*:: Draft. *Last Modified Date*:: - 2015-12-18 + 2017-03-13 *Revision*:: - 21 + 23 *IP Status*:: No known IP claims. *Dependencies*:: @@ -199,19 +199,18 @@ be implemented as two side-by-side displays using the same display engine (and sometimes cabling) resources as two physically separate display devices. -*PROPOSED RESOLUTION*: Tiled displays will appear as a single display object -in this API. +*RESOLVED*: Tiled displays will appear as a single display object in this +API. 14) Should the raw EDID data be included in the display information? -*PROPOSED RESOLUTION*: None. -Unclear whether this is a good idea. -Provides a path for forward-compatibility as new EDID extensions are -introduced, but may be complicated by the outcome of issue 13. +*RESOLVED*: No. +A future extension could be added which reports the EDID if necessary. +This may be complicated by the outcome of issue 13. 15) Should min and max scaling factor capabilities of overlays be exposed? -*PROPOSED RESOLUTION*: Yes. +*RESOLVED*: Yes. This is exposed indirectly by allowing applications to query the min/max position and extent of the source and destination regions from which image contents are fetched by the display engine when using a particular mode and @@ -220,17 +219,20 @@ overlay pair. 16) Should devices be able to expose planes that can be moved between displays? If so, how? -*PROPOSED RESOLUTION*: None. +*RESOLVED*: Yes. +Applications can determine which displays a given plane supports using +vkGetDisplayPlaneSupportedDisplaysKHR. 17) Should there be a way to destroy display modes? If so, does it support destroying "`built in`" modes? -*PROPOSED RESOLUTION*: None. +*RESOLVED*: Not in this extension. +A future extension could add this functionality. 18) What should the lifetime of display and built-in display mode objects be? -*PROPOSED RESOLUTION*: The lifetime of the instance. +*RESOLVED*: The lifetime of the instance. These objects can not be destroyed. A future extension may be added to expose a way to destroy these objects and/or support display hotplug. @@ -238,179 +240,20 @@ and/or support display hotplug. 19) Should persistent mode for smart panels be enabled/disabled at swap chain creation time, or on a per-present basis. -*PROPOSED RESOLUTION*: On a per-present basis. +*RESOLVED*: On a per-present basis. === Examples -**Example 1** - -Enumerating displays, display modes, and planes, and creating a VkSurfaceKHR - -[source,c++] ----------------------------------------- - extern VkBool32 ModeMatchesMyCriteria(const VkDisplayModePropertiesKHR *m); - extern VkInstance instance; - extern VkPhysicalDevice physDevice; - extern VkSurfaceKHR surface; - - uint32_t displayCount, planeCount, i, j, k; - VkDisplayPropertiesKHR* pDisplayProps; - VkDisplayPlanePropertiesKHR* pPlaneProps; - VkDisplayModeKHR myMode = VK_NULL_HANDLE; - VkDisplayKHR myDisplay = VK_NULL_HANDLE; - uint32_t bestPlane = UINT32_MAX; - VkDisplayPlaneAlphaFlagBitsKHR alphaMode = 0; - PFN_vkGetPhysicalDeviceDisplayPropertiesKHR pfnGetPhysicalDeviceDisplayPropertiesKHR; - PFN_vkGetPhysicalDeviceDisplayPlanePropertiesKHR pfnGetPhysicalDeviceDisplayPlanePropertiesKHR; - PFN_vkGetDisplayModePropertiesKHR pfnGetDisplayModePropertiesKHR; - PFN_vkGetDisplayPlaneCapabilitiesKHR pfnGetDisplayPlaneCapabilitiesKHR; - PFN_vkGetDisplayPlaneSupportedDisplaysKHR pfnGetDisplayPlaneSupportedDisplaysKHR; - PFN_vkCreateDisplayPlaneSurfaceKHR pfnCreateDisplayPlaneSurfaceKHR; - - pfnGetPhysicalDeviceDisplayPropertiesKHR = - (PFN_vkGetPhysicalDeviceDisplayPropertiesKHR) - vkGetInstanceProcAddr(instance, "vkGetPhysicalDeviceDisplayPropertiesKHR"); - pfnGetPhysicalDeviceDisplayPlanePropertiesKHR = - (PFN_vkGetPhysicalDeviceDisplayPlanePropertiesKHR) - vkGetInstanceProcAddr(instance, "vkGetPhysicalDeviceDisplayPlanePropertiesKHR"); - pfnGetDisplayModePropertiesKHR = - (PFN_vkGetDisplayModePropertiesKHR) - vkGetInstanceProcAddr(instance, "vkGetDisplayModePropertiesKHR"); - pfnGetDisplayPlaneCapabilitiesKHR = - (PFN_vkGetDisplayPlaneCapabilitiesKHR) - vkGetInstanceProcAddr(instance, "vkGetDisplayPlaneCapabilitiesKHR"); - pfnGetDisplayPlaneSupportedDisplaysKHR = - (PFN_vkGetDisplayPlaneSupportedDisplaysKHR) - vkGetInstanceProcAddr(instance, "vkGetDisplayPlaneSupportedDisplaysKHR"); - pfnCreateDisplayPlaneSurfaceKHR = - (PFN_vkCreateDisplayPlaneSurfaceKHR) - vkGetInstanceProcAddr(instance, "vkCreateDisplayPlaneSurfaceKHR"); - - // Get a list of displays on a physical device - displayCount = 0; - pfnGetPhysicalDeviceDisplayPropertiesKHR(physDevice, &displayCount, NULL); - - pDisplayProps = (VkDisplayPropertiesKHR*)malloc(sizeof(VkDisplayPropertiesKHR) * displayCount); - pfnGetPhysicalDeviceDisplayPropertiesKHR(physDevice, &displayCount, pDisplayProps); - - // Get a list of display planes on a physical device - planeCount = 0; - pfnGetPhysicalDeviceDisplayPlanePropertiesKHR(physDevice, &planeCount, NULL); - pPlaneProps = (VkDisplayPlanePropertiesKHR*)malloc(sizeof(VkDisplayPlanePropertiesKHR) * planeCount); - pfnGetPhysicalDeviceDisplayPlanePropertiesKHR(physDevice, &planeCount, pPlaneProps); - - // Get the list of pModes each display supports - for (i = 0; i < displayCount; ++i) - { - VkDisplayKHR display = pDisplayProps[i].display; - VkDisplayModePropertiesKHR* pModes; - uint32_t modeCount; - - vkGetDisplayModePropertiesKHR(physDevice, display, &modeCount, NULL); - - pModes = (VkDisplayModePropertiesKHR*)malloc(sizeof(VkDisplayModePropertiesKHR) * modeCount); - vkGetDisplayModePropertiesKHR(physDevice, display, &modeCount, pModes); - - myMode = VK_NULL_HANDLE; - for (j = 0; j < modeCount; ++j) - { - const VkDisplayModePropertiesKHR* mode = &pModes[i]; - - if (ModeMatchesMyCriteria(mode)) - { - myMode = mode->displayMode; - break; - } - } - - free(pModes); - - // If there are no usable pModes found then check the next display. - if (myMode == VK_NULL_HANDLE) - continue; - - // Find a plane that matches these criteria, in order of preference: - // -Is compatible with the chosen display + mode. - // -Is not currently bound to another display. - // -Supports per-pixel alpha, if possible. - for (j = 0; j < planeCount; ++j) - { - uint32_t supportedCount = 0; - VkDisplayKHR* pSupportedDisplays; - VkDisplayPlaneCapabilitiesKHR planeCaps; - // See if the plane is compatible with the current display. - pfnGetDisplayPlaneSupportedDisplaysKHR(physDevice, j, &supportedCount, NULL); - - // Plane does not support any displays. This might happen on a card - // that has a fixed mapping between planes and connectors when no - // displays are currently attached to this plane's connector, for - // example. - if (supportedCount == 0) - continue; - - pSupportedDisplays = (VkDisplayKHR*)malloc(sizeof(VkDisplayKHR) * supportedCount); - pfnGetDisplayPlaneSupportedDisplaysKHR(physDevice, j, &supportedCount, pSupportedDisplays); - - for (k = 0; k < supportedCount; ++k) - if (pSupportedDisplays[k] == display) { - // If no supported plane has yet been found, this is - // currently the best available plane. - if (bestPlane == UINT32_MAX) - bestPlane = j; - break; - } - - // If the plane cannot be used with the chosen display, keep looking. - // Each display must have at least one compatible plane. - if (k == supportedCount) - continue; - - // If the plane passed the above test and is currently bound to the - // desired display, or is not in use, it is the best plane found so - // far. - if ((pPlaneProps[j].currentDisplay == VK_NULL_HANDLE) && - (pPlaneProps[j].currentDisplay == display)) - bestPlane = j; - else - continue; - - pfnGetDisplayPlaneCapabilitiesKHR(physDevice, myMode, j, &planeCaps); - - // Prefer a plane that supports per-pixel alpha. - if (planeCaps.supportedAlpha & VK_DISPLAY_PLANE_ALPHA_PER_PIXEL_BIT_KHR) - { - // This is the perfect plane for the given criteria. Use it. - bestPlane = j; - alphaMode = VK_DISPLAY_PLANE_ALPHA_PER_PIXEL_BIT_KHR; - break; - } - } - } - - free(pDisplayProps); - - if (myDisplay == VK_NULL_HANDLE || myMode == VK_NULL_HANDLE) { - // No suitable display + mode could be found. Abort. - abort(); - } else { - // Success. Create a VkSurfaceKHR object for this plane. - const VkDisplaySurfaceCreateInfoKHR createInfo = - { - VK_STRUCTURE_TYPE_DISPLAY_SURFACE_CREATE_INFO_KHR, // sType - NULL, // pNext - 0, // flags - myMode, // displayMode - bestPlane, // planeIndex - pPlaneProps[bestPlane].currentStackIndex, // planeStackIndex - VK_SURFACE_TRANSFORM_IDENTITY_KHR, // transform - 1.0f, // globalAlpha - alphaMode, // alphaMode - ... - } - - pfnCreateDisplayPlaneSurfaceKHR(instance, &createInfo, NULL, &surface); - } ----------------------------------------- +[NOTE] +.Note +==== +The example code for the +VK_KHR_display+ and +VK_KHR_display_swapchain+ +extensions was removed from the appendix after revision 1.0.43. +The display enumeration example code was ported to the cube demo that is +shipped with the official Khronos SDK, and is being kept up-to-date in that +location (see: +https://github.com/KhronosGroup/Vulkan-LoaderAndValidationLayers/blob/master/demos/cube.c). +==== === Version History @@ -542,3 +385,10 @@ Enumerating displays, display modes, and planes, and creating a VkSurfaceKHR * Revision 22, 2015-12-18 (James Jones) - Added missing "planeIndex" parameter to vkGetDisplayPlaneSupportedDisplaysKHR() + + * Revision 23, 2017-03-13 (James Jones) + - Closed all remaining issues. + The specification and implementations have been shipping with the + proposed resolutions for some time now. + - Removed the sample code and noted it has been integrated into the + official Vulkan SDK cube demo. diff --git a/doc/specs/vulkan/appendices/VK_KHR_display_swapchain.txt b/doc/specs/vulkan/appendices/VK_KHR_display_swapchain.txt index 04f223bd97..2c46a78ead 100644 --- a/doc/specs/vulkan/appendices/VK_KHR_display_swapchain.txt +++ b/doc/specs/vulkan/appendices/VK_KHR_display_swapchain.txt @@ -13,9 +13,9 @@ *Status*:: Draft. *Last Modified Date*:: - 2015-11-10 + 2017-03-13 *Revision*:: - 9 + 10 *IP Status*:: No known IP claims. *Dependencies*:: @@ -61,20 +61,20 @@ None should it be up to the application to destroy the swapchains and images in an order that avoids the need for reference counting? -*PROPOSED RESOLUTION*: Take a reference. +*RESOLVED*: Take a reference. The lifetime of presentable images is already complex enough. 2) Should the srcRect/dstRect parameters be specified as part of the present command, or at swapchain creation time? -*PROPOSED RESOLUTION*: As part of the presentation command. +*RESOLVED*: As part of the presentation command. This allows moving and scaling the image on the screen without the need to -respecify the mode or create a new swapchain presentable images. +respecify the mode or create a new swapchain and presentable images. 3) Should srcRect/dstRect be specified as rects, or separate offset/extent values? -*PROPOSED RESOLUTION*: As rects. +*RESOLVED*: As rects. Specifying them separately might make it easier for hardware to expose support for one but not the other, but in such cases applications must just take care to obey the reported capabilities and not use non-zero offsets or @@ -104,74 +104,16 @@ use for that image. === Examples -**Example 1** - -Create a swapchain on a display mode and plane - -[source,c++] ----------------------------------------- - // See VK_KHR_display for an example of how to pick a display, - // display mode, plane, and how to create a VkSurfaceKHR for - // that plane. - extern VkPhysicalDevice physDevice; - extern VkDisplayModePropertiesKHR myModeProps; - extern VkSurfaceKHR mySurface; - extern VkDevice device; - - uint32_t queueCount, i; - uint32_t presentQueueFamilyIndex = UINT32_MAX; - VkBool32 supportsPresent; - - // Find a queue family that supports presenting to this surface - uint32_t familyCount; - vkGetPhysicalDeviceQueueFamilyProperties(physDevice, &familyCount, NULL); - - for (i = 0; i < familyCount; ++i) - { - vkGetPhysicalDeviceSurfaceSupportKHR(physDevice, i, mySurface, &supportsPresent); - - if (supportsPresent) { - // Found a queue family that supports present. See - // VK_KHR_surface for an example of how to find a queue that - // supports both presentation and graphics - presentQueueFamilyIndex = i; - break; - } - } - - // Figure out which formats and present modes this surface supports. - uint32_t formatCount; - vkGetPhysicalDeviceSurfaceFormatsKHR(physDevice, mySurface, &formatCount, NULL); - - VkSurfaceFormatKHR* formats = (VkSurfaceFormatKHR*)malloc(sizeof(VkSurfaceFormatKHR) * formatCount); - vkGetPhysicalDeviceSurfaceFormatsKHR(physDevice, mySurface, &formatCount, formats); - - const VkSwapchainCreateInfoKHR createInfo = - { - VK_STRUCTURE_TYPE_SWAPCHAIN_CREATE_INFO_KHR, // sType - NULL, // pNext - 0, // flags - mySurface, // surface - 3, // minImageCount - formats[0].format, // imageFormat - formats[0].colorSpace, // imageColorSpace - myModeProps.parameters.visibleRegion, // imageExtent - 1, // imageArrayLayers - VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT, // imageUsage - VK_SHARING_MODE_EXCLUSIVE, // imageSharingMode - 0, // queueFamilyIndexCount - NULL, // pQueueFamilyIndices - VK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR, // preTransform - VK_COMPOSITE_ALPHA_OPAQUE_BIT_KHR, // compositeAlpha - VK_PRESENT_MODE_FIFO_KHR, // presentMode - VK_TRUE, // clipped - VK_NULL_HANDLE // oldSwapchain - }; - - VkSwapchainKHR swapchain; - // This is equivalent to vkCreateSwapchainKHR. - vkCreateSharedSwapchainsKHR(device, 1, &createInfo, NULL, &swapchain); ----------------------------------------- +[NOTE] +.Note +==== +The example code for the +VK_KHR_display+ and +VK_KHR_display_swapchain+ +extensions was removed from the appendix after revision 1.0.43. +The display swapchain creation example code was ported to the cube demo that +is shipped with the official Khronos SDK, and is being kept up-to-date in +that location (see: +https://github.com/KhronosGroup/Vulkan-LoaderAndValidationLayers/blob/master/demos/cube.c). +==== === Version History @@ -208,3 +150,10 @@ Create a swapchain on a display mode and plane * Revision 9, 2015-11-10 (Jesse Hall) - Replaced ftext:VkDisplaySwapchainCreateInfoKHR with vkCreateSharedSwapchainsKHR, changing resolution of issue #4. + + * Revision 10, 2017-03-13 (James Jones) + - Closed all remaining issues. + The specification and implementations have been shipping with the + proposed resolutions for some time now. + - Removed the sample code and noted it has been integrated into the + official Vulkan SDK cube demo. diff --git a/doc/specs/vulkan/appendices/VK_KHR_surface.txt b/doc/specs/vulkan/appendices/VK_KHR_surface.txt index b399415478..7762ea70e3 100644 --- a/doc/specs/vulkan/appendices/VK_KHR_surface.txt +++ b/doc/specs/vulkan/appendices/VK_KHR_surface.txt @@ -104,15 +104,16 @@ Additionally, on some platforms, such as the X Window System, different drivers and devices might be used for different windows depending on which section of the desktop they exist on. -2) Should the flink:vkGetSurfacePropertiesKHR, flink:vkGetSurfaceFormatsKHR, -and flink:vkGetSurfacePresentModesKHR functions from +VK_KHR_swapchain+ be -modified to operate on physical devices and moved to this extension to -implement the resolution of issue 1? +2) Should the flink:vkGetPhysicalDeviceSurfaceCapabilitiesKHR, +flink:vkGetPhysicalDeviceSurfaceFormatsKHR, and +flink:vkGetPhysicalDeviceSurfacePresentModesKHR functions from ++VK_KHR_swapchain+ be modified to operate on physical devices and moved to +this extension to implement the resolution of issue 1? *RESOLVED*: No, separate query functions are needed, as the purposes served are similar but incompatible. -The flink:vkGetSurface*KHR functions return information that could -potentially depend on an initialized device. +The ftext:vkGetPhysicalDeviceSurface*KHR functions return information that +could potentially depend on an initialized device. For example, the formats supported for presentation to the surface might vary depending on which device extensions are enabled. The query introduced to resolve issue 1 should be used only to query generic diff --git a/doc/specs/vulkan/appendices/VK_KHR_swapchain.txt b/doc/specs/vulkan/appendices/VK_KHR_swapchain.txt index 8989399d49..281a39c13c 100644 --- a/doc/specs/vulkan/appendices/VK_KHR_swapchain.txt +++ b/doc/specs/vulkan/appendices/VK_KHR_swapchain.txt @@ -247,7 +247,7 @@ be left out of the base KHR extensions. A future extension could add this for platforms where it is supported. 14) Should there be a special value for -slink:VkSurfacePropertiesKHR::pname:maxImageCount to indicate there are no +slink:VkSurfaceCapabilitiesKHR::pname:maxImageCount to indicate there are no practical limits on the number of images in a swapchain? *RESOLVED*: Yes. @@ -260,7 +260,7 @@ It is better in such cases to leave it to applications to figure such soft limits out via trial/failure iterations. 15) Should there be a special value for -slink:VkSurfacePropertiesKHR::pname:currentExtent to indicate the size of +slink:VkSurfaceCapabilitiesKHR::pname:currentExtent to indicate the size of the platform surface is undefined? *RESOLVED*: Yes. @@ -268,7 +268,7 @@ On some platforms (Wayland, for example), the surface size is defined by the images presented to it rather than the other way around. 16) Should there be a special value for -slink:VkSurfacePropertiesKHR::pname:maxImageExtent to indicate there is no +slink:VkSurfaceCapabilitiesKHR::pname:maxImageExtent to indicate there is no practical limit on the surface size? *RESOLVED*: No. @@ -357,7 +357,8 @@ using a Vulkan swapchain, the application can set the pretransform to none are available, a platform-specific default will be used. Platforms that do not specify a reasonable default or do not provide native mechanisms to specify such transforms should not include the inherit bits in -the supportedTransform bitmask they return in slink:VkSurfacePropertiesKHR. +the supportedTransform bitmask they return in +slink:VkSurfaceCapabilitiesKHR. 22) Should the content of presentable images be clipped by objects obscuring their target surface? @@ -380,7 +381,7 @@ displayed, the color space of the presented image must be known to the swapchain. A swapchain will only support a restricted set of color format and -space pairs. -This set can be discovered via flink:vkGetSurfaceInfoKHR. +This set can be discovered via flink:vkGetPhysicalDeviceSurfaceFormatsKHR. As it can be expected that most display devices support the sRGB color space, at least one format/color-space pair has to be exposed, where the color space is ename:VK_COLOR_SPACE_SRGB_NONLINEAR. @@ -420,10 +421,10 @@ driver, a value of INHERIT is provided like for surface transforms. 27) Is flink:vkCreateSwapchainKHR the right function to return ename:VK_ERROR_NATIVE_WINDOW_IN_USE_KHR, or should the various -platform-specific slink:VkSurface factory functions catch this error +platform-specific slink:VkSurfaceKHR factory functions catch this error earlier? -*RESOLVED*: For most platforms, the slink:VkSurface structure is a simple +*RESOLVED*: For most platforms, the slink:VkSurfaceKHR structure is a simple container holding the data that identifies a native window or other object representing a surface on a particular platform. For the surface factory functions to return this error, they would likely @@ -439,7 +440,7 @@ native surface. Therefore, it makes more sense for swapchain creation to be the point at which native object exclusivity is enforced. Platforms may choose to enforce further restrictions on the number of -slink:VkSurface objects that may be created for the same native window if +slink:VkSurfaceKHR objects that may be created for the same native window if such a requirement makes sense on a particular platform, but a global requirement is only sensible at the swapchain level. diff --git a/doc/specs/vulkan/appendices/VK_KHR_wayland_surface.txt b/doc/specs/vulkan/appendices/VK_KHR_wayland_surface.txt index 5dace736a9..e22a2b8cd3 100644 --- a/doc/specs/vulkan/appendices/VK_KHR_wayland_surface.txt +++ b/doc/specs/vulkan/appendices/VK_KHR_wayland_surface.txt @@ -75,7 +75,7 @@ physical device and a specific Wayland display? This would be a more general query than flink:vkGetPhysicalDeviceSurfaceSupportKHR: if the Wayland-specific query returned true for a (slink:VkPhysicalDevice, struct wl_display*) pair, then the physical device could be assumed to support -presentation to any slink:VkSurface for surfaces on the display. +presentation to any slink:VkSurfaceKHR for surfaces on the display. *RESOLVED*: Yes. flink:vkGetPhysicalDeviceWaylandPresentationSupportKHR was added to address diff --git a/doc/specs/vulkan/appendices/VK_KHX_external_memory_fd.txt b/doc/specs/vulkan/appendices/VK_KHX_external_memory_fd.txt index 69c53f443d..cf74d0ef0f 100644 --- a/doc/specs/vulkan/appendices/VK_KHX_external_memory_fd.txt +++ b/doc/specs/vulkan/appendices/VK_KHX_external_memory_fd.txt @@ -61,7 +61,7 @@ None. === Issues 1) Does the application need to close the file descriptor returned by -flink:vkGetMemoryFdKHR? +flink:vkGetMemoryFdKHX? *RESOLVED*: Yes, unless it is passed back in to a driver instance to import the memory. diff --git a/doc/specs/vulkan/appendices/VK_KHX_external_memory_win32.txt b/doc/specs/vulkan/appendices/VK_KHX_external_memory_win32.txt index d066f3ef4a..2c5141c56e 100644 --- a/doc/specs/vulkan/appendices/VK_KHX_external_memory_win32.txt +++ b/doc/specs/vulkan/appendices/VK_KHX_external_memory_win32.txt @@ -64,8 +64,17 @@ None. === Issues 1) Do applications need to call CloseHandle() on the values returned from -flink:VkGetMemoryWin32HandleKHR when pname:handleType is -ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT_KHR? +flink:vkGetMemoryWin32HandleKHX when pname:handleType is +ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT_KHX? + +ifdef::editing-notes[] +[NOTE] +.editing-note +================== +(Jon) This issue refers to a token from `VK_KHX_external_semaphore_win32`, +but there's no dependency or interaction with that extension defined above. +================== +endif::editing-notes[] *RESOLVED*: Yes, unless it is passed back in to another driver instance to import the object. diff --git a/doc/specs/vulkan/appendices/VK_KHX_external_semaphore_fd.txt b/doc/specs/vulkan/appendices/VK_KHX_external_semaphore_fd.txt index 1abf594472..9e58e501f5 100644 --- a/doc/specs/vulkan/appendices/VK_KHX_external_semaphore_fd.txt +++ b/doc/specs/vulkan/appendices/VK_KHX_external_semaphore_fd.txt @@ -58,7 +58,7 @@ None. === Issues 1) Does the application need to close the file descriptor returned by -flink:vkGetSemaphoreFdKHR? +flink:vkGetSemaphoreFdKHX? *RESOLVED*: Yes, unless it is passed back in to a driver instance to import the semaphore. diff --git a/doc/specs/vulkan/appendices/VK_KHX_external_semaphore_win32.txt b/doc/specs/vulkan/appendices/VK_KHX_external_semaphore_win32.txt index 6e6452f49f..e3fb142ab4 100644 --- a/doc/specs/vulkan/appendices/VK_KHX_external_semaphore_win32.txt +++ b/doc/specs/vulkan/appendices/VK_KHX_external_semaphore_win32.txt @@ -61,8 +61,8 @@ None. === Issues 1) Do applications need to call code:CloseHandle() on the values returned -from flink:VkGetSemaphoreWin32HandleKHR when pname:handleType is -ename:VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_BIT_KHR? +from flink:vkGetSemaphoreWin32HandleKHX when pname:handleType is +ename:VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_BIT_KHX? *RESOLVED*: Yes, unless it is passed back in to another driver instance to import the object. diff --git a/doc/specs/vulkan/appendices/VK_NVX_device_generated_commands.txt b/doc/specs/vulkan/appendices/VK_NVX_device_generated_commands.txt index b1f5fb399a..6dbb925321 100644 --- a/doc/specs/vulkan/appendices/VK_NVX_device_generated_commands.txt +++ b/doc/specs/vulkan/appendices/VK_NVX_device_generated_commands.txt @@ -56,7 +56,7 @@ The intended usage for this extension is for the application to: * create a slink:VkObjectTableNVX, and register the various Vulkan objects that are needed to evaluate the input parameters. * create a slink:VkIndirectCommandsLayoutNVX, which lists the - slink:VkIndirectCommandsTokenTypes it wants to dynamically change as + slink:VkIndirectCommandsTokenTypeNVX it wants to dynamically change as atomic command sequence. This step likely involves some internal device code compilation, since the intent is for the GPU to generate the command buffer in the @@ -81,7 +81,7 @@ For each draw/dispatch, the following can be specified: * a number of vertex buffer bindings, with an optional dynamic offset * a different index buffer, with an optional dynamic offset -It is recommended to register a small number of objects and to use dynamic +Applications should: register a small number of objects, and use dynamic offsets whenever possible. While the GPU can be faster than a CPU to generate the commands, it may not @@ -291,7 +291,7 @@ implementation that could process the inputs directly in pipe. If the data is "`referenced`", then it allows both types of implementation The inputs are "`referenced`", and should not be modified after the call to -flink:vkCmdProcessCommands and until after the rendering of the target +flink:vkCmdProcessCommandsNVX and until after the rendering of the target command buffer is finished. 18) Why is this +NVX+ and not +NV+? diff --git a/doc/specs/vulkan/appendices/VK_NV_external_memory_win32.txt b/doc/specs/vulkan/appendices/VK_NV_external_memory_win32.txt index cce24e494c..17f93883a1 100644 --- a/doc/specs/vulkan/appendices/VK_NV_external_memory_win32.txt +++ b/doc/specs/vulkan/appendices/VK_NV_external_memory_win32.txt @@ -92,8 +92,17 @@ Vulkan API. Both of these are beyond the scope of this extension. 3) Do applications need to call code:CloseHandle() on the values returned -from flink:VkGetMemoryWin32HandleKHR when pname:handleType is -ename:VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_BIT_KHR? +from flink:vkGetMemoryWin32HandleNV when pname:handleType is +ename:VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_BIT_KHX? + +ifdef::editing-notes[] +[NOTE] +.editing-note +================== +(Jon) This issue refers to a token from `VK_KHX_external_semaphore_win32`, +but there's no dependency or interaction with that extension defined above. +================== +endif::editing-notes[] *RESOLVED*: Yes, unless it is passed back in to another driver instance to import the object. diff --git a/doc/specs/vulkan/appendices/boilerplate.txt b/doc/specs/vulkan/appendices/boilerplate.txt index 59d39658d7..7b241034ad 100644 --- a/doc/specs/vulkan/appendices/boilerplate.txt +++ b/doc/specs/vulkan/appendices/boilerplate.txt @@ -119,6 +119,9 @@ include::../api/flags/VkSparseImageFormatFlags.txt[] include::../api/flags/VkSparseMemoryBindFlags.txt[] include::../api/flags/VkStencilFaceFlags.txt[] include::../api/flags/VkSubpassDescriptionFlags.txt[] +ifdef::VK_EXT_display_surface_counter[] +include::../api/flags/VkSurfaceCounterFlagsEXT.txt[] +endif::VK_EXT_display_surface_counter[] [[boilerplate-macros]] diff --git a/doc/specs/vulkan/appendices/glossary.txt b/doc/specs/vulkan/appendices/glossary.txt index 25f6428b3f..e3f5f75b64 100644 --- a/doc/specs/vulkan/appendices/glossary.txt +++ b/doc/specs/vulkan/appendices/glossary.txt @@ -757,7 +757,7 @@ endif::VK_KHR_swapchain[] Preserve Attachment:: One of a list of attachments in a subpass description that is not read or written by the subpass, but that is read or written on earlier and - later subpasses and whose contents must be preserved through this + later subpasses and whose contents must: be preserved through this subpass. Primary Command Buffer:: diff --git a/doc/specs/vulkan/appendices/invariance.txt b/doc/specs/vulkan/appendices/invariance.txt index 16a4054a7d..708c994f74 100644 --- a/doc/specs/vulkan/appendices/invariance.txt +++ b/doc/specs/vulkan/appendices/invariance.txt @@ -138,7 +138,7 @@ times with the same input as long as:_ The OpenGL spec has the following invariance rule: Consider a primitive p' obtained by translating a primitive p through an offset (x, y) in window coordinates, where x and y are integers. -As long as neither p' nor p is clipped, it must be the case that each +As long as neither p' nor p is clipped, it must: be the case that each fragment f' produced from p' is identical to a corresponding fragment f from p except that the center of f' is offset by (x, y) from the center of f. diff --git a/doc/specs/vulkan/chapters/VK_EXT_debug_marker.txt b/doc/specs/vulkan/chapters/VK_EXT_debug_marker.txt index d942bed063..c5c94994f7 100644 --- a/doc/specs/vulkan/chapters/VK_EXT_debug_marker.txt +++ b/doc/specs/vulkan/chapters/VK_EXT_debug_marker.txt @@ -169,19 +169,15 @@ When viewed from the linear series of submissions to a single queue, the calls to fname:vkCmdDebugMarkerBeginEXT and fname:vkCmdDebugMarkerEndEXT must: be matched and balanced. -Any calls to fname:vkCmdDebugMarkerBeginEXT within a secondary command -buffer must have a matching fname:vkCmdDebugMarkerEndEXT in that same -command buffer, and marker regions begun outside of the secondary command -buffer must not be ended inside it. - .Valid Usage **** * There must: be an outstanding flink:vkCmdDebugMarkerBeginEXT command prior to the fname:vkCmdDebugMarkerEndEXT on the queue that pname:commandBuffer is submitted to - * If the matching flink:vkCmdDebugMarkerBeginEXT command was in a - secondary command buffer, the fname:vkCmdDebugMarkerEndEXT must be in - the same pname:commandBuffer + * If pname:commandBuffer is a secondary command buffer, there must: be an + outstanding flink:vkCmdDebugMarkerBeginEXT command recorded to + pname:commandBuffer that has not previously been ended by a call to + flink:vkCmdDebugMarkerEndEXT. **** include::../validity/protos/vkCmdDebugMarkerEndEXT.txt[] diff --git a/doc/specs/vulkan/chapters/VK_EXT_debug_report.txt b/doc/specs/vulkan/chapters/VK_EXT_debug_report.txt index 9517e8068c..60622a1ce7 100644 --- a/doc/specs/vulkan/chapters/VK_EXT_debug_report.txt +++ b/doc/specs/vulkan/chapters/VK_EXT_debug_report.txt @@ -3,6 +3,15 @@ [[debugging-debug-report-callbacks]] == Debug Report Callbacks +// refBegin VkDebugReportCallbackEXT Opaque handle to a debug report callback object + +Debug report callbacks are represented by sname:VkDebugReportCallbackEXT +handles: + +include::../api/handles/VkDebugReportCallbackEXT.txt[] + +// refEnd VkDebugReportCallbackEXT + // refBegin vkCreateDebugReportCallbackEXT Create a debug report callback object Debug report callbacks give more detailed feedback on the application's use diff --git a/doc/specs/vulkan/chapters/VK_GOOGLE_display_timing/queries.txt b/doc/specs/vulkan/chapters/VK_GOOGLE_display_timing/queries.txt index 1c8af91875..d3080872de 100644 --- a/doc/specs/vulkan/chapters/VK_GOOGLE_display_timing/queries.txt +++ b/doc/specs/vulkan/chapters/VK_GOOGLE_display_timing/queries.txt @@ -64,6 +64,10 @@ include::../../api/structs/VkRefreshCycleDurationGOOGLE.txt[] * pname:refreshDuration is the number of nanoseconds from the start of one refresh cycle to the next. +include::../../validity/structs/VkRefreshCycleDurationGOOGLE.txt[] + +// refEnd VkRefreshCycleDurationGOOGLE + The rate at which an application renders and presents new images is known as the image present rate (IPR, a.k.a. frame rate). diff --git a/doc/specs/vulkan/chapters/VK_KHR_display/display.txt b/doc/specs/vulkan/chapters/VK_KHR_display/display.txt index 1f114a8a79..f7c7a0cf11 100644 --- a/doc/specs/vulkan/chapters/VK_KHR_display/display.txt +++ b/doc/specs/vulkan/chapters/VK_KHR_display/display.txt @@ -10,12 +10,20 @@ directly to display devices without using an intermediate windowing system. This can: be useful for embedded applications, or implementing the rendering/presentation backend of a windowing system using Vulkan. The +VK_KHR_display+ extension provides the functionality necessary to -enumerate display devices and create sname:VkSurface objects that target +enumerate display devices and create sname:VkSurfaceKHR objects that target displays. === Display Enumeration +// refBegin VkDisplayKHR - Opaque handle to a display object + +Displays are represented by sname:VkDisplayKHR handles: + +include::../../api/handles/VkDisplayKHR.txt[] + +// refEnd VkDisplayKHR + // refBegin vkGetPhysicalDeviceDisplayPropertiesKHR - Query information about the available displays Various functions are provided for enumerating the available display devices @@ -158,20 +166,20 @@ include::../../api/protos/vkGetDisplayPlaneSupportedDisplaysKHR.txt[] * pname:planeIndex is the plane which the application wishes to use, and must: be in the range [eq]#[0, physical device plane count - 1]#. * pname:pDisplayCount is a pointer to an integer related to the number of - display planes available or queried, as described below. + displays available or queried, as described below. * pname:pDisplays is either `NULL` or a pointer to an array of - sname:VkDisplayKHR structures. + sname:VkDisplayKHR handles. If pname:pDisplays is `NULL`, then the number of displays usable with the specified pname:planeIndex for pname:physicalDevice is returned in pname:pDisplayCount. Otherwise, pname:pDisplayCount must: point to a variable set by the user to the number of elements in the pname:pDisplays array, and on return the -variable is overwritten with the number of structures actually written to +variable is overwritten with the number of handles actually written to pname:pDisplays. If the value of pname:pDisplayCount is less than the number of display -planes for pname:physicalDevice, at most pname:pDisplayCount structures will -be written. +planes for pname:physicalDevice, at most pname:pDisplayCount handles will be +written. If pname:pDisplayCount is smaller than the number of displays usable with the specified pname:planeIndex for pname:physicalDevice, ename:VK_INCOMPLETE will be returned instead of ename:VK_SUCCESS to indicate that not all the @@ -192,6 +200,14 @@ functions. ==== Display Modes +// refBegin VkDisplayModeKHR - Opaque handle to a display mode object + +Display modes are represented by sname:VkDisplayModeKHR handles: + +include::../../api/handles/VkDisplayModeKHR.txt[] + +// refEnd VkDisplayModeKHR + // refBegin vkGetDisplayModePropertiesKHR - Query the set of mode properties supported by the display Each display has one or more supported modes associated with it by default. @@ -268,8 +284,8 @@ include::../../api/protos/vkCreateDisplayModeKHR.txt[] * pname:pCreateInfo is a slink:VkDisplayModeCreateInfoKHR structure describing the new mode to create. * pname:pAllocator is the allocator used for host memory allocated for the - surface object when there is no more specific allocator available (see - <>). + display mode object when there is no more specific allocator available + (see <>). * pname:pMode returns the handle of the mode created. include::../../validity/protos/vkCreateDisplayModeKHR.txt[] @@ -431,7 +447,7 @@ include::../../api/structs/VkDisplaySurfaceCreateInfoKHR.txt[] This value is ignored if pname:alphaMode is not ename:VK_DISPLAY_PLANE_ALPHA_GLOBAL_BIT_KHR. * pname:alphaMode is the type of alpha blending to use. - * pname:imageSize The size of the presentable images to use with the + * pname:imageExtent The size of the presentable images to use with the surface. [NOTE] @@ -474,7 +490,7 @@ to a display surface. include::../../validity/structs/VkDisplaySurfaceCreateInfoKHR.txt[] -// refBegin VkDisplayPlaneAlphaFlagBitsKHR - alpha blending type +// refBegin VkDisplayPlaneAlphaFlagBitsKHR - Alpha blending type Types of alpha blending supported by or used on a display are defined by the bitmask ename:VkDisplayPlaneAlphaFlagBitsKHR, which contains the following diff --git a/doc/specs/vulkan/chapters/VK_KHR_surface/wsi.txt b/doc/specs/vulkan/chapters/VK_KHR_surface/wsi.txt index 0458d2b3a2..5c6921eddb 100644 --- a/doc/specs/vulkan/chapters/VK_KHR_surface/wsi.txt +++ b/doc/specs/vulkan/chapters/VK_KHR_surface/wsi.txt @@ -37,9 +37,14 @@ before using them. == WSI Surface -A sname:VkSurfaceKHR object abstracts a native platform surface or window -object for use with Vulkan. -The +VK_KHR_surface extension+ declares the sname:VkSurfaceKHR object, and +// refBegin VkSurfaceKHR - Opaque handle to a surface object + +Native platform surface or window objects are abstracted by surface objects, +which are represented by sname:VkSurfaceKHR handles: + +include::../../api/handles/VkSurfaceKHR.txt[] + +The +VK_KHR_surface+ extension declares the sname:VkSurfaceKHR object, and provides a function for destroying sname:VkSurfaceKHR objects. Separate platform-specific extensions each provide a function for creating a sname:VkSurfaceKHR object for the respective platform. @@ -60,6 +65,8 @@ This does not affect the loader-layer interface; layers may: wrap sname:VkSurfaceKHR objects. ==== +// refEnd VkSurfaceKHR + ifdef::editing-notes[] [NOTE] .editing-note @@ -476,7 +483,7 @@ The color components of Non-linear color space swap chain images have had the appropriate transfer function applied. Vulkan requires that all implementations support the sRGB OETF and EOTF transfer functions when using an SRGB pixel format. -Other transfer functions, such as SMPTE 170M, must not: be performed by the +Other transfer functions, such as SMPTE 170M, must: not be performed by the implementation, but can: be performed by the application shader. endif::VK_EXT_swapchain_colorspace[] diff --git a/doc/specs/vulkan/chapters/VK_KHR_swapchain/wsi.txt b/doc/specs/vulkan/chapters/VK_KHR_swapchain/wsi.txt index 6e5f7bfa1c..a7b8f06a96 100644 --- a/doc/specs/vulkan/chapters/VK_KHR_swapchain/wsi.txt +++ b/doc/specs/vulkan/chapters/VK_KHR_swapchain/wsi.txt @@ -3,8 +3,14 @@ == WSI Swapchain -A sname:VkSwapchainKHR object (a.k.a. +// refBegin VkSwapchainKHR - Opaque handle to a swapchain object + +A swapchain object (a.k.a. swapchain) provides the ability to present rendering results to a surface. +Swapchain objects are represented by sname:VkSwapchainKHR handles: + +include::../../api/handles/VkSwapchainKHR.txt[] + A swapchain is an abstraction for an array of presentable images that are associated with a surface. The presentable images are represented by sname:VkImage objects created by @@ -64,6 +70,8 @@ referencing all of the images in the swapchain at initialization time, rather than in its main loop. ==== +// refEnd VkSwapchainKHR + How this all works is described below. // refBegin vkCreateSwapchainKHR - Create a swapchain diff --git a/doc/specs/vulkan/chapters/VK_KHR_wayland_surface/platformCreateSurface_wayland.txt b/doc/specs/vulkan/chapters/VK_KHR_wayland_surface/platformCreateSurface_wayland.txt index e5e6828e7f..f4cceaa258 100644 --- a/doc/specs/vulkan/chapters/VK_KHR_wayland_surface/platformCreateSurface_wayland.txt +++ b/doc/specs/vulkan/chapters/VK_KHR_wayland_surface/platformCreateSurface_wayland.txt @@ -81,5 +81,5 @@ If the application wishes to synchronize any window changes with a particular frame, such requests must: be sent to the Wayland display server prior to calling flink:vkQueuePresentKHR. For full control over interactions between Vulkan rendering and other -Wayland protocol requests and events, using a present mode of -ename:VK_PRESENT_MODE_MAILBOX_KHR is recommended. +Wayland protocol requests and events, a present mode of +ename:VK_PRESENT_MODE_MAILBOX_KHR should: be used. diff --git a/doc/specs/vulkan/chapters/VK_KHR_xlib_surface/platformCreateSurface_xlib.txt b/doc/specs/vulkan/chapters/VK_KHR_xlib_surface/platformCreateSurface_xlib.txt index 11ab7b2e03..062974e0f3 100644 --- a/doc/specs/vulkan/chapters/VK_KHR_xlib_surface/platformCreateSurface_xlib.txt +++ b/doc/specs/vulkan/chapters/VK_KHR_xlib_surface/platformCreateSurface_xlib.txt @@ -51,7 +51,7 @@ Therefore, a swapchain's pname:imageExtent must: match the window's size. Some Vulkan functions may: send protocol over the specified Xlib code:Display connection when using a swapchain or presentable images created -from a VkSurface referring to an Xlib window. +from a slink:VkSurfaceKHR referring to an Xlib window. Applications must: therefore ensure the display connection is available to Vulkan for the duration of any functions that manipulate such swapchains or their presentable images, and any functions that build or queue command diff --git a/doc/specs/vulkan/chapters/VK_NVX_device_generated_commands/generatedcommands.txt b/doc/specs/vulkan/chapters/VK_NVX_device_generated_commands/generatedcommands.txt index 6df107af32..fc44bbbd39 100644 --- a/doc/specs/vulkan/chapters/VK_NVX_device_generated_commands/generatedcommands.txt +++ b/doc/specs/vulkan/chapters/VK_NVX_device_generated_commands/generatedcommands.txt @@ -21,9 +21,9 @@ Execution of such generated commands can either be triggered directly with the generation process, or by executing the secondary sname:VkCommandBuffer that was chosen as optional target. The latter allows re-using generated commands as well. -Similar to sname:VkDescriptorSet special care must be taken for the lifetime -of resources referenced in sname:VkObjectTableNVX, which may be accessed at -either generation or execution time. +Similar to sname:VkDescriptorSet, special care should: be taken for the +lifetime of resources referenced in sname:VkObjectTableNVX, which may be +accessed at either generation or execution time. flink:vkCmdProcessCommandsNVX executes in a separate logical pipeline from either graphics or compute. @@ -93,4 +93,4 @@ include::objecttable.txt[] include::indirectcommands.txt[] -include::generation.txt[] \ No newline at end of file +include::generation.txt[] diff --git a/doc/specs/vulkan/chapters/VK_NVX_device_generated_commands/generation.txt b/doc/specs/vulkan/chapters/VK_NVX_device_generated_commands/generation.txt index ce0bbfc667..062e6cb061 100644 --- a/doc/specs/vulkan/chapters/VK_NVX_device_generated_commands/generation.txt +++ b/doc/specs/vulkan/chapters/VK_NVX_device_generated_commands/generation.txt @@ -107,12 +107,12 @@ include::../../api/structs/VkCmdProcessCommandsInfoNVX.txt[] **** * The provided pname:objectTable must: include all objects referenced by the generation process. - * pname:indirectCommandsTokenCount must match the - pname:indirectCommandsLayout's tokenCount. + * pname:indirectCommandsTokenCount must: match the + pname:indirectCommandsLayout's pname:tokenCount. * The pname:tokenType member of each entry in the - pname:pIndirectCommandsTokens array must match the values used at + pname:pIndirectCommandsTokens array must: match the values used at creation time of pname:indirectCommandsLayout - * If pname:targetCommandBuffer is provided, it must have reserved command + * If pname:targetCommandBuffer is provided, it must: have reserved command space. * If pname:targetCommandBuffer is provided, the pname:objectTable must: match the reservation's objectTable and must: have had all referenced @@ -124,12 +124,12 @@ include::../../api/structs/VkCmdProcessCommandsInfoNVX.txt[] must: not exceed the reservation's maxSequencesCount. * If pname:sequencesCountBuffer is used, its usage flag must: have ename:VK_BUFFER_USAGE_INDIRECT_BUFFER_BIT bit set. - * If pname:sequencesCountBuffer is used, pname:sequencesCountOffset must + * If pname:sequencesCountBuffer is used, pname:sequencesCountOffset must: be aligned to sname:VkDeviceGeneratedCommandsLimitsNVX::pname:minSequenceCountBufferOffsetAlignment. * If pname:sequencesIndexBuffer is used, its usage flag must: have ename:VK_BUFFER_USAGE_INDIRECT_BUFFER_BIT bit set. - * If pname:sequencesIndexBuffer is used, pname:sequencesIndexOffset must + * If pname:sequencesIndexBuffer is used, pname:sequencesIndexOffset must: be aligned to sname:VkDeviceGeneratedCommandsLimitsNVX::pname:minSequenceIndexBufferOffsetAlignment. **** @@ -166,7 +166,7 @@ cmdProcessAllSequences(cmd, objectTable, .Note ==== It is important to note that the state that may be affected through -generated commands must be considered undefined for the commands following +generated commands must: be considered undefined for the commands following them. It is not possible to setup generated state and provoking work that uses this state outside of the generated sequence. diff --git a/doc/specs/vulkan/chapters/VK_NVX_device_generated_commands/indirectcommands.txt b/doc/specs/vulkan/chapters/VK_NVX_device_generated_commands/indirectcommands.txt index e2244849a3..3584ab90ad 100644 --- a/doc/specs/vulkan/chapters/VK_NVX_device_generated_commands/indirectcommands.txt +++ b/doc/specs/vulkan/chapters/VK_NVX_device_generated_commands/indirectcommands.txt @@ -35,7 +35,7 @@ void cmdProcessAllSequences(cmd, objectTable, indirectCommandsLayout, pIndirectC --------------------------------------------------- The processing of each sequence is considered stateless, therefore all state -changes must occur prior work provoking commands within the sequence. +changes must: occur prior work provoking commands within the sequence. A single sequence is either strictly targeting sname:VK_PIPELINE_BIND_POINT_GRAPHICS or ename:VK_PIPELINE_BIND_POINT_COMPUTE. @@ -83,11 +83,11 @@ include::../../api/structs/VkIndirectCommandsLayoutTokenNVX.txt[] .Valid Usage **** - * pname:bindingUnit must stay within device supported limits for the + * pname:bindingUnit must: stay within device supported limits for the appropriate commands. - * pname:dynamicCount must stay within device supported limits for the + * pname:dynamicCount must: stay within device supported limits for the appropriate commands. - * pname:divisor must greater '0' and power of two. + * pname:divisor must: be greater than `0` and a power of two. **** include::../../validity/structs/VkIndirectCommandsLayoutTokenNVX.txt[] @@ -326,4 +326,4 @@ include::../../api/protos/vkDestroyIndirectCommandsLayoutNVX.txt[] was created, pname:pAllocator must: be `NULL` **** -include::../../validity/protos/vkDestroyIndirectCommandsLayoutNVX.txt[] \ No newline at end of file +include::../../validity/protos/vkDestroyIndirectCommandsLayoutNVX.txt[] diff --git a/doc/specs/vulkan/chapters/VK_NVX_device_generated_commands/objecttable.txt b/doc/specs/vulkan/chapters/VK_NVX_device_generated_commands/objecttable.txt index b1373faa56..a3e96f41f9 100644 --- a/doc/specs/vulkan/chapters/VK_NVX_device_generated_commands/objecttable.txt +++ b/doc/specs/vulkan/chapters/VK_NVX_device_generated_commands/objecttable.txt @@ -47,7 +47,6 @@ include::../../api/structs/VkObjectTableCreateInfoNVX.txt[] * pname:pNext is `NULL` or a pointer to an extension-specific structure. * pname:objectCount is the number of entry configurations that the object table supports. - The following array parameters must match the size provided here. * pname:pObjectEntryTypes is an array of elink:VkObjectEntryTypeNVX providing the entry type of a given configuration. * pname:pObjectEntryCounts is an array of counts how many objects can be @@ -115,15 +114,15 @@ include::../../api/enums/VkObjectEntryUsageFlagBitsNVX.txt[] sname:VkDeviceGeneratedCommandsFeaturesNVX::pname:computeBindingPointSupport feature is not enabled, pname:pObjectEntryUsageFlags must: not contain ename:VK_OBJECT_ENTRY_USAGE_COMPUTE_BIT_NVX - * Any value within pname:pObjectEntryCounts must not exceed + * Any value within pname:pObjectEntryCounts must: not exceed sname:VkDeviceGeneratedCommandsLimitsNVX::pname:maxObjectEntryCounts - * pname:maxUniformBuffersPerDescriptor must be within the limits supported - by the device. - * pname:maxStorageBuffersPerDescriptor must be within the limits supported - by the device. - * pname:maxStorageImagesPerDescriptor must be within the limits supported + * pname:maxUniformBuffersPerDescriptor must: be within the limits + supported by the device. + * pname:maxStorageBuffersPerDescriptor must: be within the limits + supported by the device. + * pname:maxStorageImagesPerDescriptor must: be within the limits supported by the device. - * pname:maxSampledImagesPerDescriptor must be within the limits supported + * pname:maxSampledImagesPerDescriptor must: be within the limits supported by the device. **** @@ -156,7 +155,7 @@ include::../../validity/protos/vkDestroyObjectTableNVX.txt[] Resource bindings of Vulkan objects are registered at an arbitrary ftext:uint32_t index within an object table. -As long as the object table references such objects, they must not be +As long as the object table references such objects, they must: not be deleted. include::../../api/protos/vkRegisterObjectsNVX.txt[] @@ -176,7 +175,7 @@ include::../../api/protos/vkRegisterObjectsNVX.txt[] .Valid Usage **** - * The contents of pname:pObjectTableEntry must yield plausible bindings + * The contents of pname:pObjectTableEntry must: yield plausible bindings supported by the device. * At any pname:pObjectIndices there must: not be a registered resource already. @@ -213,7 +212,7 @@ include::../../api/structs/VkObjectTablePipelineEntryNVX.txt[] .Valid Usage **** - * pname:type must be ename:VK_OBJECT_ENTRY_PIPELINE_NVX + * pname:type must: be ename:VK_OBJECT_ENTRY_PIPELINE_NVX **** include::../../validity/structs/VkObjectTablePipelineEntryNVX.txt[] @@ -227,7 +226,7 @@ include::../../api/structs/VkObjectTableDescriptorSetEntryNVX.txt[] .Valid Usage **** - * pname:type must be ename:VK_OBJECT_ENTRY_DESCRIPTOR_SET_NVX + * pname:type must: be ename:VK_OBJECT_ENTRY_DESCRIPTOR_SET_NVX **** include::../../validity/structs/VkObjectTableDescriptorSetEntryNVX.txt[] @@ -239,7 +238,7 @@ include::../../api/structs/VkObjectTableVertexBufferEntryNVX.txt[] .Valid Usage **** - * pname:type must be ename:VK_OBJECT_ENTRY_VERTEX_BUFFER_NVX + * pname:type must: be ename:VK_OBJECT_ENTRY_VERTEX_BUFFER_NVX **** include::../../validity/structs/VkObjectTableVertexBufferEntryNVX.txt[] @@ -253,7 +252,7 @@ include::../../api/structs/VkObjectTableIndexBufferEntryNVX.txt[] .Valid Usage **** - * pname:type must be ename:VK_OBJECT_ENTRY_INDEX_BUFFER_NVX + * pname:type must: be ename:VK_OBJECT_ENTRY_INDEX_BUFFER_NVX **** include::../../validity/structs/VkObjectTableIndexBufferEntryNVX.txt[] @@ -267,7 +266,7 @@ include::../../api/structs/VkObjectTablePushConstantEntryNVX.txt[] .Valid Usage **** - * pname:type must be ename:VK_OBJECT_ENTRY_PUSH_CONSTANT_NVX + * pname:type must: be ename:VK_OBJECT_ENTRY_PUSH_CONSTANT_NVX **** include::../../validity/structs/VkObjectTablePushConstantEntryNVX.txt[] @@ -291,7 +290,7 @@ include::../../api/protos/vkUnregisterObjectsNVX.txt[] already. * The pname:pObjectEntryTypes of the resource at pname:pObjectIndices must: match. - * All operations on the device using the registered resource must have + * All operations on the device using the registered resource must: have been completed. **** diff --git a/doc/specs/vulkan/chapters/VK_NV_external_memory_win32/import_memory_win32.txt b/doc/specs/vulkan/chapters/VK_NV_external_memory_win32/import_memory_win32.txt index 8ae12c2654..96279acf20 100644 --- a/doc/specs/vulkan/chapters/VK_NV_external_memory_win32/import_memory_win32.txt +++ b/doc/specs/vulkan/chapters/VK_NV_external_memory_win32/import_memory_win32.txt @@ -11,31 +11,13 @@ include::../../api/structs/VkImportMemoryWin32HandleInfoNV.txt[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to an extension-specific structure. - * pname:handleType is 0 or a flag specifying the type of memory handle in + * pname:handleType is `0` or a bit specifying the type of memory handle in pname:handle. - Flags which may: be specified are: -+ --- -// refBegin VkExternalMemoryHandleTypeFlagBitsNV - Bitmask specifying memory handle types -include::../../api/enums/VkExternalMemoryHandleTypeFlagBitsNV.txt[] --- - ** if pname:handleType is - ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT_NV or - ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT_NV, the - handle is one returned by flink:vkGetMemoryWin32HandleNV or, in the - case of ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT_NV, one - duplicated from such a handle using `DuplicateHandle()`. - ** if pname:handleType is - ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_IMAGE_BIT_NV, the handle is - a valid NT handle returned by - `IDXGIResource1::ftext:CreateSharedHandle()`, or a handle duplicated - from such a handle using `DuplicateHandle()`. - ** if pname:handleType is - ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_IMAGE_KMT_BIT_NV, the handle - is one returned by `IDXGIResource::GetSharedHandle()`. + See elink:VkExternalMemoryHandleTypeFlagBitsNV below for a description + of the supported bits. * pname:handle is a Windows code:HANDLE referring to the memory. -If pname:handleType is 0, this structure is ignored by consumers of the +If pname:handleType is `0`, this structure is ignored by consumers of the slink:VkMemoryAllocateInfo structure it is chained from. .Valid Usage @@ -46,3 +28,33 @@ slink:VkMemoryAllocateInfo structure it is chained from. **** include::../../validity/structs/VkImportMemoryWin32HandleInfoNV.txt[] + +Bits which can: be set in pname:handleType are: + +// refBegin VkExternalMemoryHandleTypeFlagBitsNV - Bitmask specifying external memory handle types +include::../../api/enums/VkExternalMemoryHandleTypeFlagBitsNV.txt[] + + * ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT_NV or + ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT_NV indicate a + handle to memory returned by flink:vkGetMemoryWin32HandleNV or, in the + case of ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT_NV, one + duplicated from such a handle using `DuplicateHandle()`. + * ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_IMAGE_BIT_NV indicates a + valid NT handle to memory returned by + `IDXGIResource1::ftext:CreateSharedHandle()`, or a handle duplicated + from such a handle using `DuplicateHandle()`. + * ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_IMAGE_KMT_BIT_NV indicates a + handle to memory returned by `IDXGIResource::GetSharedHandle()`. + +ifdef::editing-notes[] +[NOTE] +.editing-note +================== +(Jon) If additional (non-Win32) bits are added to the possible memory types, +this type should move to the `VK_NV_external_memory_capabilities` section, +and each bit would then be protected by ifdefs for the extension it's +defined by. +================== +endif::editing-notes[] + +// refEnd VkExternalMemoryHandleTypeFlagBitsNV diff --git a/doc/specs/vulkan/chapters/clears.txt b/doc/specs/vulkan/chapters/clears.txt index a1ebb2c856..320065594d 100644 --- a/doc/specs/vulkan/chapters/clears.txt +++ b/doc/specs/vulkan/chapters/clears.txt @@ -57,8 +57,7 @@ endif::VK_KHR_maintenance1[] * pname:imageLayout must: specify the layout of the image subresource ranges of pname:image specified in pname:pRanges at the time this command is executed on a sname:VkDevice - * pname:imageLayout must: be either of - ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL or + * pname:imageLayout must: be ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL or ename:VK_IMAGE_LAYOUT_GENERAL * The image range of any given element of pname:pRanges must: be an image subresource range that is contained within pname:image diff --git a/doc/specs/vulkan/chapters/cmdbuffers.txt b/doc/specs/vulkan/chapters/cmdbuffers.txt index 7cb46a9639..e3c32d693e 100644 --- a/doc/specs/vulkan/chapters/cmdbuffers.txt +++ b/doc/specs/vulkan/chapters/cmdbuffers.txt @@ -94,8 +94,6 @@ Invalid:: Some operations, such as modifying or deleting a resource that was used in a command recorded to a command buffer, will transition the state of a command buffer into the _invalid state_. - This state is largely equivalent to the _initial state_, except that - resources are still associated with it. Command buffers in the invalid state can: only be reset, moved to the _recording state_, or freed. @@ -182,16 +180,13 @@ include::../api/enums/VkCommandPoolCreateFlagBits.txt[] will be reset or freed in a relatively short timeframe. This flag may: be used by the implementation to control memory allocation behavior within the pool. - ** ename:VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT controls whether - command buffers allocated from the pool can: be individually reset. - If this flag is set, individual command buffers allocated from the pool - can: be reset either explicitly, by calling fname:vkResetCommandBuffer, - or implicitly, by calling fname:vkBeginCommandBuffer on an executable - command buffer. - If this flag is not set, then fname:vkResetCommandBuffer and - fname:vkBeginCommandBuffer (on an executable command buffer) must: not - be called on the command buffers allocated from the pool, and they can: - only be reset in bulk by calling fname:vkResetCommandPool. + ** ename:VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT allows any + command buffer allocated from a pool to be individually reset to the + <>; either by calling + flink:vkResetCommandBuffer, or via the implicit reset when calling + flink:vkBeginCommandBuffer. + If this flag is not set on a pool, then fname:vkResetCommandBuffer + must: not be called for any command buffer allocated from that pool. * pname:queueFamilyIndex designates a queue family as described in section <>. All command buffers allocated from this command pool must: be submitted @@ -315,9 +310,7 @@ include::../api/protos/vkDestroyCommandPool.txt[] <> chapter. When a pool is destroyed, all command buffers allocated from the pool are -implicitly freed and become invalid. -Command buffers allocated from a given pool do not need to be freed before -destroying that command pool. +<>. Any primary command buffer allocated from another slink:VkCommandPool that is in the <> and @@ -406,8 +399,9 @@ To reset command buffers, call: include::../api/protos/vkResetCommandBuffer.txt[] * pname:commandBuffer is the command buffer to reset. - The command buffer can: be in any state, and is put in the initial - state. + The command buffer can: be in any state other than + <>, and is moved into the + <>. * pname:flags is a bitmask controlling the reset operation. Bits which can: be set include: + @@ -642,10 +636,10 @@ buffers to be patched in-place if needed, rather than creating a copy of the command buffer. ==== -If a command buffer is in the <>, and the command buffer was allocated from a command -pool with the ename:VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT flag -set, then fname:vkBeginCommandBuffer implicitly resets the command buffer, +If a command buffer is in the <>, and the command buffer was allocated from a command pool +with the ename:VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT flag set, +then fname:vkBeginCommandBuffer implicitly resets the command buffer, behaving as if fname:vkResetCommandBuffer had been called with ename:VK_COMMAND_BUFFER_RESET_RELEASE_RESOURCES_BIT not set. After the implicit reset, pname:commandBuffer is moved to the @@ -684,6 +678,12 @@ executable state>>. an active render pass instance * All queries made <> during the recording of pname:commandBuffer must: have been made inactive +ifdef::VK_EXT_debug_marker[] + * If pname:commandBuffer is a secondary command buffer, there must: not be + an outstanding flink:vkCmdDebugMarkerBeginEXT command recorded to + pname:commandBuffer that has not previously been ended by a call to + flink:vkCmdDebugMarkerEndEXT. +endif::VK_EXT_debug_marker[] **** include::../validity/protos/vkEndCommandBuffer.txt[] @@ -751,6 +751,17 @@ If a command buffer was recorded with the ename:VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT flag, it instead moves back to the <>. +If fname:vkQueueSubmit fails, it may: return +ename:VK_ERROR_OUT_OF_HOST_MEMORY or ename:VK_ERROR_OUT_OF_DEVICE_MEMORY. +If it does, the implementation must: ensure that the state and contents of +any resources or synchronization primitives referenced by the submitted +command buffers and any semaphores referenced by pname:pSubmits is +unaffected by the call or its failure. +If fname:vkQueueSubmit fails in such a way that the implementation can: not +make that guarantee, the implementation must: return +ename:VK_ERROR_DEVICE_LOST. +See <>. + .Valid Usage **** * If pname:fence is not dlink:VK_NULL_HANDLE, pname:fence must: be @@ -842,8 +853,6 @@ otherwise execute out of order. .Valid Usage **** - * Any given element of pname:pCommandBuffers must: be in the executable - state * Any given element of pname:pCommandBuffers must: not have been allocated with ename:VK_COMMAND_BUFFER_LEVEL_SECONDARY * If the <> feature is @@ -949,7 +958,7 @@ include::../api/structs/VkWin32KeyedMutexAcquireReleaseInfoKHX.txt[] .Valid Usage **** - * Each member of pname:pAcquireSyncs and pname:pReleaseSyncs must be a + * Each member of pname:pAcquireSyncs and pname:pReleaseSyncs must: be a device memory object imported by setting slink:VkImportMemoryWin32HandleInfoKHX::pname:handleType to ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_BIT_KHX or diff --git a/doc/specs/vulkan/chapters/copies.txt b/doc/specs/vulkan/chapters/copies.txt index d792ed0346..004b559d3d 100644 --- a/doc/specs/vulkan/chapters/copies.txt +++ b/doc/specs/vulkan/chapters/copies.txt @@ -36,7 +36,7 @@ Some rules for valid operation are common to all copy commands: * Source image subresources must: be in either the ename:VK_IMAGE_LAYOUT_GENERAL or ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL layout. - Destination image subresources must: be in either the + Destination image subresources must: be in the ename:VK_IMAGE_LAYOUT_GENERAL or ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL layout. As a consequence, if an image subresource is used as both source and @@ -168,11 +168,6 @@ region of the destination image. pname:srcImage and pname:dstImage can: be the same image or alias the same memory. -Copies are done layer by layer starting with pname:baseArrayLayer member of -pname:srcSubresource for the source and pname:dstSubresource for the -destination. -pname:layerCount layers are copied to the destination image. - [[copies-images-format-compatibility]] The formats of pname:srcImage and pname:dstImage must: be compatible. Formats are considered compatible if their element size is the same between @@ -272,9 +267,8 @@ endif::VK_KHR_maintenance1[] * pname:srcImageLayout must: specify the layout of the image subresources of pname:srcImage specified in pname:pRegions at the time this command is executed on a sname:VkDevice - * pname:srcImageLayout must: be either of - ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL or - ename:VK_IMAGE_LAYOUT_GENERAL + * pname:srcImageLayout must: be ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL + or ename:VK_IMAGE_LAYOUT_GENERAL ifdef::VK_KHR_maintenance1[] * pname:dstImage must: use a format that supports ename:VK_FORMAT_FEATURE_TRANSFER_DST_BIT_KHR, which is indicated by @@ -290,9 +284,8 @@ endif::VK_KHR_maintenance1[] * pname:dstImageLayout must: specify the layout of the image subresources of pname:dstImage specified in pname:pRegions at the time this command is executed on a sname:VkDevice - * pname:dstImageLayout must: be either of - ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL or - ename:VK_IMAGE_LAYOUT_GENERAL + * pname:dstImageLayout must: be ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL + or ename:VK_IMAGE_LAYOUT_GENERAL * The elink:VkFormat of each of pname:srcImage and pname:dstImage must: be compatible, as defined <> * The sample count of pname:srcImage and pname:dstImage must: match @@ -512,9 +505,8 @@ endif::VK_KHR_maintenance1[] * pname:dstImageLayout must: specify the layout of the image subresources of pname:dstImage specified in pname:pRegions at the time this command is executed on a sname:VkDevice - * pname:dstImageLayout must: be either of - ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL or - ename:VK_IMAGE_LAYOUT_GENERAL + * pname:dstImageLayout must: be ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL + or ename:VK_IMAGE_LAYOUT_GENERAL **** include::../validity/protos/vkCmdCopyBufferToImage.txt[] @@ -564,9 +556,8 @@ endif::VK_KHR_maintenance1[] * pname:srcImageLayout must: specify the layout of the image subresources of pname:srcImage specified in pname:pRegions at the time this command is executed on a sname:VkDevice - * pname:srcImageLayout must: be either of - ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL or - ename:VK_IMAGE_LAYOUT_GENERAL + * pname:srcImageLayout must: be ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL + or ename:VK_IMAGE_LAYOUT_GENERAL * pname:dstBuffer must: have been created with ename:VK_BUFFER_USAGE_TRANSFER_DST_BIT usage flag * If pname:dstBuffer is non-sparse then it must: be bound completely and @@ -900,7 +891,7 @@ representable range of the destination format, then casting the value. sampled during the blit operation * pname:srcImage must: use a format that supports ename:VK_FORMAT_FEATURE_BLIT_SRC_BIT, which is indicated by - sname:VkFormatProperties::pname:linearTilingFeatures (for linear tiled + sname:VkFormatProperties::pname:linearTilingFeatures (for linearly tiled images) or sname:VkFormatProperties::pname:optimalTilingFeatures (for optimally tiled images) - as returned by fname:vkGetPhysicalDeviceFormatProperties @@ -911,12 +902,11 @@ representable range of the destination format, then casting the value. * pname:srcImageLayout must: specify the layout of the image subresources of pname:srcImage specified in pname:pRegions at the time this command is executed on a sname:VkDevice - * pname:srcImageLayout must: be either of - ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL or - ename:VK_IMAGE_LAYOUT_GENERAL + * pname:srcImageLayout must: be ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL + or ename:VK_IMAGE_LAYOUT_GENERAL * pname:dstImage must: use a format that supports ename:VK_FORMAT_FEATURE_BLIT_DST_BIT, which is indicated by - sname:VkFormatProperties::pname:linearTilingFeatures (for linear tiled + sname:VkFormatProperties::pname:linearTilingFeatures (for linearly tiled images) or sname:VkFormatProperties::pname:optimalTilingFeatures (for optimally tiled images) - as returned by fname:vkGetPhysicalDeviceFormatProperties @@ -927,9 +917,8 @@ representable range of the destination format, then casting the value. * pname:dstImageLayout must: specify the layout of the image subresources of pname:dstImage specified in pname:pRegions at the time this command is executed on a sname:VkDevice - * pname:dstImageLayout must: be either of - ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL or - ename:VK_IMAGE_LAYOUT_GENERAL + * pname:dstImageLayout must: be ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL + or ename:VK_IMAGE_LAYOUT_GENERAL * The sample count of pname:srcImage and pname:dstImage must: both be equal to ename:VK_SAMPLE_COUNT_1_BIT * If either of pname:srcImage or pname:dstImage was created with a signed @@ -1094,15 +1083,13 @@ pname:layerCount layers are resolved to the destination image. * pname:srcImageLayout must: specify the layout of the image subresources of pname:srcImage specified in pname:pRegions at the time this command is executed on a sname:VkDevice - * pname:srcImageLayout must: be either of - ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL or - ename:VK_IMAGE_LAYOUT_GENERAL + * pname:srcImageLayout must: be ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL + or ename:VK_IMAGE_LAYOUT_GENERAL * pname:dstImageLayout must: specify the layout of the image subresources of pname:dstImage specified in pname:pRegions at the time this command is executed on a sname:VkDevice - * pname:dstImageLayout must: be either of - ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL or - ename:VK_IMAGE_LAYOUT_GENERAL + * pname:dstImageLayout must: be ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL + or ename:VK_IMAGE_LAYOUT_GENERAL * If pname:dstImage was created with pname:tiling equal to ename:VK_IMAGE_TILING_LINEAR, pname:dstImage must: have been created with a pname:format that supports being a color attachment, as specified diff --git a/doc/specs/vulkan/chapters/descriptorsets.txt b/doc/specs/vulkan/chapters/descriptorsets.txt index caed37c8ae..1d81d239d0 100644 --- a/doc/specs/vulkan/chapters/descriptorsets.txt +++ b/doc/specs/vulkan/chapters/descriptorsets.txt @@ -118,7 +118,7 @@ formats which report support for the feature. Load and store operations on storage images can: only be done on images in -ename:VK_IMAGE_LAYOUT_GENERAL layout. +the ename:VK_IMAGE_LAYOUT_GENERAL layout. When the <> feature is enabled, stores and atomic @@ -1636,10 +1636,6 @@ element zero. If a binding has a pname:descriptorCount of zero, it is skipped. This behavior applies recursively, with the update affecting consecutive bindings as needed to update all pname:descriptorCount descriptors. -All consecutive bindings updated via a single sname:VkWriteDescriptorSet -structure, except those with a pname:descriptorCount of zero, must: have -identical pname:descriptorType and pname:stageFlags, and must: all either -use immutable samplers or must: all not use immutable samplers. .Valid Usage **** @@ -1648,6 +1644,12 @@ use immutable samplers or must: all not use immutable samplers. specified when pname:dstSet's descriptor set layout was created * pname:dstBinding must: be a binding with a non-zero pname:descriptorCount + * All consecutive bindings updated via a single sname:VkWriteDescriptorSet + structure, except those with a pname:descriptorCount of zero, must: have + identical pname:descriptorType and pname:stageFlags. + * All consecutive bindings updated via a single sname:VkWriteDescriptorSet + structure, except those with a pname:descriptorCount of zero, must: all + either use immutable samplers or must: all not use immutable samplers. * pname:descriptorType must: match the type of pname:dstBinding within pname:dstSet * The sum of pname:dstArrayElement and pname:descriptorCount must: be less @@ -1824,8 +1826,8 @@ include::../api/structs/VkDescriptorImageInfo.txt[] ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, and ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT. - * pname:imageLayout is the layout that the image will be in at the time - this descriptor is accessed. + * pname:imageLayout is the layout that the image subresources accessible + from pname:imageView will be in at the time this descriptor is accessed. pname:imageLayout is used in descriptor updates for types ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE, ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, @@ -1835,6 +1837,14 @@ include::../api/structs/VkDescriptorImageInfo.txt[] Members of sname:VkDescriptorImageInfo that are not used in an update (as described above) are ignored. +ifdef::VK_KHR_maintenance1[] +.Valid Usage +**** + * pname:imageView must: not be 2D or 2D array image view created from a 3D + image +**** +endif::VK_KHR_maintenance1[] + include::../validity/structs/VkDescriptorImageInfo.txt[] // refBegin VkCopyDescriptorSet Structure specifying a copy descriptor set operation @@ -1931,15 +1941,6 @@ This allows large batches of updates to be executed without having to convert application data structures into a strictly-defined Vulkan data structure. -ifdef::editing-notes[] -[NOTE] -.editing-note -================== -(Jon) Can simplify the conditional structure by rearranging the conditional -clause to precede end of sentence. -================== -endif::editing-notes[] - To create a descriptor update template, call: include::../api/protos/vkCreateDescriptorUpdateTemplateKHR.txt[] @@ -1949,11 +1950,10 @@ include::../api/protos/vkCreateDescriptorUpdateTemplateKHR.txt[] * pname:pCreateInfo is a pointer to an instance of the slink:VkDescriptorUpdateTemplateCreateInfoKHR structure specifying the set of descriptors to update with a single call to - flink:vkUpdateDescriptorSetWithTemplateKHR ifdef::VK_KHR_push_descriptor[] - or flink:vkCmdPushDescriptorSetWithTemplateKHR + flink:vkCmdPushDescriptorSetWithTemplateKHR or endif::VK_KHR_push_descriptor[] - . + flink:vkUpdateDescriptorSetWithTemplateKHR. * pname:pAllocator controls host memory allocation as described in the <> chapter. * pname:pDescriptorUpdateTemplate points to a diff --git a/doc/specs/vulkan/chapters/devsandqueues.txt b/doc/specs/vulkan/chapters/devsandqueues.txt index 2a4c2bb6b1..823083000f 100644 --- a/doc/specs/vulkan/chapters/devsandqueues.txt +++ b/doc/specs/vulkan/chapters/devsandqueues.txt @@ -640,8 +640,8 @@ include::../api/structs/VkDeviceGroupDeviceCreateInfoKHX.txt[] The elements of the pname:pPhysicalDevices array are an ordered list of the physical devices that the logical device represents. -These must be a subset of a single device group, and need not be in the same -order as they were enumerated. +These must: be a subset of a single device group, and need not be in the +same order as they were enumerated. The order of the physical devices in the pname:pPhysicalDevices array determines the _device index_ of each physical device, with element [eq]#i# being assigned a device index of [eq]#i#. @@ -852,8 +852,8 @@ implementation-dependent. ==== The general expectation is that a physical device groups all queues of matching capabilities into a single family. -However, this is a recommendation to implementations and it is possible that -a physical device may: return two separate queue families with the same +However, while implementations should: do this, it is possible that a +physical device may: return two separate queue families with the same capabilities. ==== @@ -1000,6 +1000,7 @@ to starve queues on another sname:VkDevice. No specific guarantees are made about higher priority queues receiving more processing time or better quality of service than lower priority queues. + [[devsandqueues-submission]] === Queue Submission diff --git a/doc/specs/vulkan/chapters/dispatch.txt b/doc/specs/vulkan/chapters/dispatch.txt index dfbff3f5e2..090275d9da 100644 --- a/doc/specs/vulkan/chapters/dispatch.txt +++ b/doc/specs/vulkan/chapters/dispatch.txt @@ -292,7 +292,7 @@ vkCmdDispatchBaseKHX(0,0,0,groupCountX,groupCountY,groupCountZ). sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[2] minus pname:baseGroupZ * If any of pname:baseGroupX, pname:baseGroupY, or pname:baseGroupZ are - not zero, then the currently bound compute pipeline must have been + not zero, then the currently bound compute pipeline must: have been created with the ename:VK_PIPELINE_CREATE_DISPATCH_BASE_KHX flag. **** diff --git a/doc/specs/vulkan/chapters/drawing.txt b/doc/specs/vulkan/chapters/drawing.txt index 5f2092fc06..a9f0553a16 100644 --- a/doc/specs/vulkan/chapters/drawing.txt +++ b/doc/specs/vulkan/chapters/drawing.txt @@ -596,7 +596,7 @@ ifdef::VK_IMG_filter_cubic[] endif::VK_IMG_filter_cubic[] ifdef::VK_KHX_multiview[] * If the draw is recorded in a render pass instance with multiview - enabled, the maximum instance index must be less than or equal to + enabled, the maximum instance index must: be less than or equal to slink:VkPhysicalDeviceMultiviewPropertiesKHX::pname:maxMultiviewInstanceIndex. endif::VK_KHX_multiview[] **** @@ -742,7 +742,7 @@ ifdef::VK_IMG_filter_cubic[] endif::VK_IMG_filter_cubic[] ifdef::VK_KHX_multiview[] * If the draw is recorded in a render pass instance with multiview - enabled, the maximum instance index must be less than or equal to + enabled, the maximum instance index must: be less than or equal to slink:VkPhysicalDeviceMultiviewPropertiesKHX::pname:maxMultiviewInstanceIndex. endif::VK_KHX_multiview[] **** @@ -888,7 +888,7 @@ ifdef::VK_IMG_filter_cubic[] endif::VK_IMG_filter_cubic[] ifdef::VK_KHX_multiview[] * If the draw is recorded in a render pass instance with multiview - enabled, the maximum instance index must be less than or equal to + enabled, the maximum instance index must: be less than or equal to slink:VkPhysicalDeviceMultiviewPropertiesKHX::pname:maxMultiviewInstanceIndex. endif::VK_KHX_multiview[] **** @@ -1053,7 +1053,7 @@ located at pname:countBufferOffset and use this as the draw count. fname:vkGetPhysicalDeviceFormatProperties ifdef::VK_KHX_multiview[] * If the draw is recorded in a render pass instance with multiview - enabled, the maximum instance index must be less than or equal to + enabled, the maximum instance index must: be less than or equal to slink:VkPhysicalDeviceMultiviewPropertiesKHX::pname:maxMultiviewInstanceIndex. endif::VK_KHX_multiview[] **** @@ -1203,7 +1203,7 @@ ifdef::VK_IMG_filter_cubic[] endif::VK_IMG_filter_cubic[] ifdef::VK_KHX_multiview[] * If the draw is recorded in a render pass instance with multiview - enabled, the maximum instance index must be less than or equal to + enabled, the maximum instance index must: be less than or equal to slink:VkPhysicalDeviceMultiviewPropertiesKHX::pname:maxMultiviewInstanceIndex. endif::VK_KHX_multiview[] **** @@ -1375,7 +1375,7 @@ located at pname:countBufferOffset and use this as the draw count. fname:vkGetPhysicalDeviceFormatProperties ifdef::VK_KHX_multiview[] * If the draw is recorded in a render pass instance with multiview - enabled, the maximum instance index must be less than or equal to + enabled, the maximum instance index must: be less than or equal to slink:VkPhysicalDeviceMultiviewPropertiesKHX::pname:maxMultiviewInstanceIndex. endif::VK_KHX_multiview[] **** diff --git a/doc/specs/vulkan/chapters/extensions.txt b/doc/specs/vulkan/chapters/extensions.txt index 1e3a909899..441e122c70 100644 --- a/doc/specs/vulkan/chapters/extensions.txt +++ b/doc/specs/vulkan/chapters/extensions.txt @@ -345,12 +345,11 @@ ifdef::VK_KHR_get_physical_device_properties2[] functionality to be implemented as a device extension. endif::VK_KHR_get_physical_device_properties2[] * For a set of global functionality that provides new instance-level and - device-level commands, and can: be enabled for a subset of devices, it - is recommended that the functionality be partitioned across two - extensions--one for the instance-level functionality, and one for the - device-specific functionality. - In this latter case, it is generally recommended that the two extensions - have unique names. + device-level commands, and can: be enabled for a subset of devices, + functionality should: be partitioned across two extensions -- one for + the instance-level functionality, and one for the device-specific + functionality. + In the latter case, the two extensions should: have unique names. Examples of instance extensions include: diff --git a/doc/specs/vulkan/chapters/features.txt b/doc/specs/vulkan/chapters/features.txt index d5b6b83cd2..4a734a742d 100644 --- a/doc/specs/vulkan/chapters/features.txt +++ b/doc/specs/vulkan/chapters/features.txt @@ -806,19 +806,20 @@ The sname:VkPhysicalDeviceLimits structure is defined as: include::../api/structs/VkPhysicalDeviceLimits.txt[] * [[features-limits-maxImageDimension1D]] pname:maxImageDimension1D is the - maximum dimension (pname:width) of an image created with an + maximum dimension (pname:width) supported for all images created with an pname:imageType of ename:VK_IMAGE_TYPE_1D. * [[features-limits-maxImageDimension2D]] pname:maxImageDimension2D is the - maximum dimension (pname:width or pname:height) of an image created with - an pname:imageType of ename:VK_IMAGE_TYPE_2D and without + maximum dimension (pname:width or pname:height) supported for all images + created with an pname:imageType of ename:VK_IMAGE_TYPE_2D and without ename:VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT set in pname:flags. * [[features-limits-maxImageDimension3D]] pname:maxImageDimension3D is the - maximum dimension (pname:width, pname:height, or pname:depth) of an - image created with an pname:imageType of ename:VK_IMAGE_TYPE_3D. + maximum dimension (pname:width, pname:height, or pname:depth) supported + for all images created with an pname:imageType of + ename:VK_IMAGE_TYPE_3D. * [[features-limits-maxImageDimensionCube]] pname:maxImageDimensionCube is - the maximum dimension (pname:width or pname:height) of an image created - with an pname:imageType of ename:VK_IMAGE_TYPE_2D and with - ename:VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT set in pname:flags. + the maximum dimension (pname:width or pname:height) supported for all + images created with an pname:imageType of ename:VK_IMAGE_TYPE_2D and + with ename:VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT set in pname:flags. * [[features-limits-maxImageArrayLayers]] pname:maxImageArrayLayers is the maximum number of layers (pname:arrayLayers) for an image. * [[features-limits-maxTexelBufferElements]] pname:maxTexelBufferElements @@ -1452,16 +1453,16 @@ range. pname:optimalBufferCopyOffsetAlignment is the optimal buffer offset alignment in bytes for fname:vkCmdCopyBufferToImage and fname:vkCmdCopyImageToBuffer. - The per texel alignment requirements are still enforced, this is just an - additional alignment recommendation for optimal performance and power. + The per texel alignment requirements are enforced, but applications + should: use the optimal alignment for optimal performance and power use. * [[features-limits-optimalBufferCopyRowPitchAlignment]] pname:optimalBufferCopyRowPitchAlignment is the optimal buffer row pitch alignment in bytes for fname:vkCmdCopyBufferToImage and fname:vkCmdCopyImageToBuffer. Row pitch is the number of bytes between texels with the same X coordinate in adjacent rows (Y coordinates differ by one). - The per texel alignment requirements are still enforced, this is just an - additional alignment recommendation for optimal performance and power. + The per texel alignment requirements are enforced, but applications + should: use the optimal alignment for optimal performance and power use. * [[features-limits-nonCoherentAtomSize]] pname:nonCoherentAtomSize is the size and alignment in bytes that bounds concurrent access to <>. @@ -1601,6 +1602,7 @@ implementation-dependent limits. endif::VK_NVX_multiview_per_view_attributes[] + [[features-limits-minmax]] === Limit Requirements @@ -3836,7 +3838,7 @@ s| Format ^.^| {downarrow} <<< [[features-formats-mandatory-features-64bit]] -.Mandatory format support: 64-bit/uneven channels and depth/stencil +.Mandatory format support: 64-bit/uneven channels [width="100%",cols="10,^1,^1,^1,^1,^1,^1,^1,^1,^1,^1,^1,^1,^1",options="unbreakable"] |==== 14+>| ename:VK_FORMAT_FEATURE_STORAGE_TEXEL_BUFFER_ATOMIC_BIT @@ -3867,6 +3869,26 @@ s| Format ^.^| {downarrow} | ename:VK_FORMAT_R64G64B64A64_SFLOAT | | | | | | | | | | | | | | ename:VK_FORMAT_B10G11R11_UFLOAT_PACK32 | {sym1} | {sym1} | {sym1} | | | | | | | | {sym1} | | | ename:VK_FORMAT_E5B9G9R9_UFLOAT_PACK32 | {sym1} | {sym1} | {sym1} | | | | | | | | | | +|==== + +[[features-formats-mandatory-features-depth-stencil]] +.Mandatory format support: depth/stencil with elink:VkImageType ename:VK_IMAGE_TYPE_2D +[width="100%",cols="10,^1,^1,^1,^1,^1,^1,^1,^1,^1,^1,^1,^1,^1",options="unbreakable"] +|==== +14+>| ename:VK_FORMAT_FEATURE_STORAGE_TEXEL_BUFFER_ATOMIC_BIT +13+>| ename:VK_FORMAT_FEATURE_STORAGE_TEXEL_BUFFER_BIT .13+^.^| {downarrow} +12+>| ename:VK_FORMAT_FEATURE_UNIFORM_TEXEL_BUFFER_BIT .12+^.^| {downarrow} +11+>| ename:VK_FORMAT_FEATURE_VERTEX_BUFFER_BIT .11+^.^| {downarrow} +10+>| ename:VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT .10+^.^| {downarrow} +9+>| ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BLEND_BIT .9+^.^| {downarrow} +8+>| ename:VK_FORMAT_FEATURE_BLIT_DST_BIT .8+^.^| {downarrow} +7+>| ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT .7+^.^| {downarrow} +6+>| ename:VK_FORMAT_FEATURE_STORAGE_IMAGE_ATOMIC_BIT .6+^.^| {downarrow} +5+>| ename:VK_FORMAT_FEATURE_STORAGE_IMAGE_BIT .5+^.^| {downarrow} +4+>| ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT .4+^.^| {downarrow} +3+>| ename:VK_FORMAT_FEATURE_BLIT_SRC_BIT .3+^.^| {downarrow} +2+>| ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT .2+^.^| {downarrow} +s| Format ^.^| {downarrow} | ename:VK_FORMAT_D16_UNORM | {sym1} | {sym1} | | | | | | | {sym1} | | | | | ename:VK_FORMAT_X8_D24_UNORM_PACK32 | | | | | | | | | {sym2} | | | | | ename:VK_FORMAT_D32_SFLOAT | {sym1} | {sym1} | | | | | | | {sym2} | | | | @@ -4419,28 +4441,52 @@ ename:VK_SAMPLE_COUNT_1_BIT. [[features-extentperimagetype]] === Allowed Extent Values Based On Image Type +Implementations may: support extent values larger than the +<> for certain +types of images subject to the constraints below. + +[NOTE] +.Note +==== +Implementations must: support images with dimensions up to the +<> for all types of +images. +It follows that the query for additional capabilities must: return extent +values that are at least as large as the required values. +==== + For ename:VK_IMAGE_TYPE_1D: - * [eq]#pname:maxExtent.width {leq} + * [eq]#pname:maxExtent.width {geq} slink:VkPhysicalDeviceLimits.pname:maxImageDimension1D# * [eq]#pname:maxExtent.height = 1# * [eq]#pname:maxExtent.depth = 1# -For ename:VK_IMAGE_TYPE_2D: +For ename:VK_IMAGE_TYPE_2D when pname:flags does not contain +ename:VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT: - * [eq]#pname:maxExtent.width {leq} + * [eq]#pname:maxExtent.width {geq} slink:VkPhysicalDeviceLimits.pname:maxImageDimension2D# - * [eq]#pname:maxExtent.height {leq} + * [eq]#pname:maxExtent.height {geq} slink:VkPhysicalDeviceLimits.pname:maxImageDimension2D# * [eq]#pname:maxExtent.depth = 1# +For ename:VK_IMAGE_TYPE_2D when pname:flags contains +ename:VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT: + + * [eq]#pname:maxExtent.width {geq} + slink:VkPhysicalDeviceLimits.pname:maxImageDimensionCube# + * [eq]#pname:maxExtent.height {geq} + slink:VkPhysicalDeviceLimits.pname:maxImageDimensionCube# + * [eq]#pname:maxExtent.depth = 1# + For ename:VK_IMAGE_TYPE_3D: - * [eq]#pname:maxExtent.width {leq} + * [eq]#pname:maxExtent.width {geq} slink:VkPhysicalDeviceLimits.pname:maxImageDimension3D# - * [eq]#pname:maxExtent.height {leq} + * [eq]#pname:maxExtent.height {geq} slink:VkPhysicalDeviceLimits.pname:maxImageDimension3D# - * [eq]#pname:maxExtent.depth {leq} + * [eq]#pname:maxExtent.depth {geq} slink:VkPhysicalDeviceLimits.pname:maxImageDimension3D# @@ -4575,7 +4621,7 @@ include::../api/enums/VkExternalSemaphoreHandleTypeFlagBitsKHX.txt[] descriptor as input. It owns a reference to the underlying synchronization primitive associated with the file descriptor. - Implementations which support importing this handle type must accept + Implementations which support importing this handle type must: accept any type of fence FD supported by the native system they are running on. diff --git a/doc/specs/vulkan/chapters/fragops.txt b/doc/specs/vulkan/chapters/fragops.txt index a48df53437..6ded601309 100644 --- a/doc/specs/vulkan/chapters/fragops.txt +++ b/doc/specs/vulkan/chapters/fragops.txt @@ -115,8 +115,8 @@ pname:discardRectangleCount)#. inclusive * pname:pDiscardRectangles must: be a pointer to an array of pname:discardRectangleCount valid sname:VkRect2D structures - * The pname:x and pname:y members of pname:offset in sname:VkRect2D must b - greater than or equal to `0` + * The pname:x and pname:y members of pname:offset in sname:VkRect2D must: + be greater than or equal to `0` * Evaluation of (pname:offset.x + pname:extent.width) in sname:VkRect2D must: not cause a signed integer addition overflow * Evaluation of (pname:offset.y + pname:extent.height) in sname:VkRect2D diff --git a/doc/specs/vulkan/chapters/fundamentals.txt b/doc/specs/vulkan/chapters/fundamentals.txt index d381f4d2fc..5fbb12eff8 100644 --- a/doc/specs/vulkan/chapters/fundamentals.txt +++ b/doc/specs/vulkan/chapters/fundamentals.txt @@ -738,8 +738,8 @@ of the Specification. // refEnd VkFlags VkColorComponentFlags -Any etext:Vk*Flags member or parameter used in the API must: be a valid -combination of bit flags. +Any etext:Vk*Flags member or parameter used in the API as an input must: be +a valid combination of bit flags. A valid combination is either zero or the bitwise OR of valid bit flags. A bit flag is valid if: @@ -752,6 +752,10 @@ A bit flag is valid if: For example, in some cases, certain bit flags or combinations of bit flags are mutually exclusive. +Any etext:Vk*Flags member or parameter used in the API as an output may: +contain bit flags undefined in its corresponding etext:FlagBits type. +An application cannot: rely on the state of these unspecified bits. + [[fundamentals-validusage-sType]] ==== Valid Usage for Structure Types diff --git a/doc/specs/vulkan/chapters/interfaces.txt b/doc/specs/vulkan/chapters/interfaces.txt index d9134460d1..a3cd2a173e 100644 --- a/doc/specs/vulkan/chapters/interfaces.txt +++ b/doc/specs/vulkan/chapters/interfaces.txt @@ -942,6 +942,9 @@ slink:VkDeviceGroupDeviceCreateInfoKHX. + The code:DeviceIndex decoration can: be used in any shader. + +The variable decorated with code:DeviceIndex must: be declared using the +code:Input storage class. ++ The variable decorated with code:DeviceIndex must: be declared as a scalar 32-bit integer. @@ -1403,7 +1406,7 @@ declared using either the code:Input or code:Output storage class. + In a fragment shader, any variable decorated with code:PrimitiveId must: be declared using the code:Input storage class, and either the code:Geometry or -code:Tessellation capability must also be declared. +code:Tessellation capability must: also be declared. + Any variable decorated with code:PrimitiveId must: be declared as a scalar 32-bit integer. @@ -1745,12 +1748,16 @@ code:ViewIndex:: The code:ViewIndex decoration can: be applied to a shader input which will be filled with the index of the view that is being processed by the current shader invocation. ++ If multiview is enabled in the render pass, this value will be one of the bits set in the view mask of the subpass the pipeline is compiled against. If multiview is not enabled in the render pass, this value will be zero. + The code:ViewIndex decoration must: not be used within compute shaders. + +The variable decorated with code:ViewIndex must: be declared using the +code:Input storage class. ++ The variable decorated with code:ViewIndex must: be declared as a scalar 32-bit integer. diff --git a/doc/specs/vulkan/chapters/introduction.txt b/doc/specs/vulkan/chapters/introduction.txt index 3b7da269cd..785079dae4 100644 --- a/doc/specs/vulkan/chapters/introduction.txt +++ b/doc/specs/vulkan/chapters/introduction.txt @@ -108,7 +108,7 @@ brackets, e.g. ''[Specification]''. [[introduction-terminology]] == Terminology -The key words *must*, *required*, *shall*, *should*, *recommend*, *may*, and +The key words *must*, *required*, *should*, *recommend*, *may*, and *optional* in this document are to be interpreted as described in RFC 2119: http://www.ietf.org/rfc/rfc2119.txt @@ -120,15 +120,17 @@ When followed by *not* ("`must: not`" ), the phrase means that the definition is an absolute prohibition of the specification. *should*:: -When used alone, this word, or the adjective *recommended*, means that there -may exist valid reasons in particular circumstances to ignore a particular -item, but the full implications must be understood and carefully weighed -before choosing a different course. +When used alone, this word means that there may exist valid reasons in +particular circumstances to ignore a particular item, but the full +implications must be understood and carefully weighed before choosing a +different course. When followed by *not* ("`should: not`"), the phrase means that there may exist valid reasons in particular circumstances when the particular behavior is acceptable or even useful, but the full implications should: be understood and the case carefully weighed before implementing any behavior described with this label. +In cases where grammatically appropriate, the terms *recommend* or +*recommendation* may be used instead of *should*. *may*:: This word, or the adjective *optional*, means that an item is truly diff --git a/doc/specs/vulkan/chapters/memory.txt b/doc/specs/vulkan/chapters/memory.txt index fe12b7f96e..4c89536192 100644 --- a/doc/specs/vulkan/chapters/memory.txt +++ b/doc/specs/vulkan/chapters/memory.txt @@ -794,7 +794,7 @@ objects whenever possible. When performing a memory import operation, it is the responsibility of the application to ensure the external handles meet all valid usage requirements. -However, implementations must perform sufficient validation of external +However, implementations must: perform sufficient validation of external handles to ensure that the operation results in a valid memory object which will not cause program termination, device loss, queue stalls, or corruption of other resources when used as allowed according to its allocation @@ -820,7 +820,7 @@ ifdef::VK_KHX_external_memory+VK_NV_dedicated_allocation[] sname:VkExternalImageFormatPropertiesKHX::pname:externalMemoryProperties::pname:externalMemoryFeatures or sname:VkExternalBufferPropertiesKHX::pname:externalMemoryProperties::pname:externalMemoryFeatures, - the pname:pNext extension chain must contain an instance of + the pname:pNext extension chain must: contain an instance of sname:VkDedicatedAllocationMemoryAllocateInfoNV with either its pname:image or pname:buffer field set to a value other than ename:VK_NULL_HANDLE. @@ -923,12 +923,12 @@ ifdef::VK_KHX_external_memory_win32,VK_KHX_external_memory_fd[] * If pname:image is not sname:VK_NULL_HANDLE and slink:VkMemoryAllocateInfo defines a memory import operation, the memory being imported must: also be a dedicated image allocation and - pname:image must be identical to the image associated with the imported + pname:image must: be identical to the image associated with the imported memory. * If pname:buffer is not sname:VK_NULL_HANDLE and slink:VkMemoryAllocateInfo defines a memory import operation, the memory being imported must: also be a dedicated buffer allocation and - pname:buffer must be identical to the buffer associated with the + pname:buffer must: be identical to the buffer associated with the imported memory. endif::VK_KHX_external_memory_win32,VK_KHX_external_memory_fd[] **** @@ -961,7 +961,7 @@ include::../api/structs/VkExportMemoryAllocateInfoKHX.txt[] .Valid Usage **** - * The bits in pname:handleTypes must be supported and compatible, as + * The bits in pname:handleTypes must: be supported and compatible, as reported by slink:VkExternalImageFormatPropertiesKHX or slink:VkExternalBufferPropertiesKHX. **** @@ -1052,14 +1052,14 @@ longer needed. .Valid Usage **** - * If pname:handleType is not `0`, it must be supported for import, as + * If pname:handleType is not `0`, it must: be supported for import, as reported by slink:VkExternalImageFormatPropertiesKHX or slink:VkExternalBufferPropertiesKHX. * The memory from which pname:handle was exported must: have been created on the same underlying physical device as pname:device. * If pname:handleType is not `0`, it must: be defined as an NT handle or a global share handle. - * If pname:handleType is not `0`, pname:handle must be a valid handle of + * If pname:handleType is not `0`, pname:handle must: be a valid handle of the type specified by pname:handleType. **** @@ -1168,14 +1168,14 @@ after a successful import. .Valid Usage **** - * If pname:handleType is not `0`, it must be supported for import, as + * If pname:handleType is not `0`, it must: be supported for import, as reported by slink:VkExternalImageFormatPropertiesKHX or slink:VkExternalBufferPropertiesKHX. * The memory from which pname:fd was exported must: have been created on the same underlying physical device as pname:device. * If pname:handleType is not `0`, it must: be defined as a POSIX file descriptor handle. - * If pname:handleType is not `0`, pname:fd must be a valid handle of the + * If pname:handleType is not `0`, pname:fd must: be a valid handle of the type specified by pname:handleType. **** diff --git a/doc/specs/vulkan/chapters/pipelines.txt b/doc/specs/vulkan/chapters/pipelines.txt index 162c548b0c..ee540b3522 100644 --- a/doc/specs/vulkan/chapters/pipelines.txt +++ b/doc/specs/vulkan/chapters/pipelines.txt @@ -701,8 +701,8 @@ ifdef::VK_NV_clip_space_w_scaling[] * ename:VK_DYANMIC_STATE_VIEWPORT_W_SCALING_NV indicates that the pname:pViewportScalings state in sname:VkPipelineViewportWScalingStateCreateInfoNV will be ignored and - must: be set dynamically with flink:vkCmdSetViewportWScaling before any - draws are performed with a pipeline state with + must: be set dynamically with flink:vkCmdSetViewportWScalingNV before + any draws are performed with a pipeline state with sname:VkPipelineViewportWScalingStateCreateInfo member pname:viewportScalingEnable set to ename:VK_TRUE endif::VK_NV_clip_space_w_scaling[] diff --git a/doc/specs/vulkan/chapters/queries.txt b/doc/specs/vulkan/chapters/queries.txt index d6205115ef..ef44dc55b4 100644 --- a/doc/specs/vulkan/chapters/queries.txt +++ b/doc/specs/vulkan/chapters/queries.txt @@ -243,8 +243,10 @@ include::../api/protos/vkCmdBeginQuery.txt[] that can: be performed. Bits which can: be set include: + +-- // refBegin VkQueryControlFlagBits Bitmask specifying constraints on a query include::../api/enums/VkQueryControlFlagBits.txt[] +-- If the pname:queryType of the pool is ename:VK_QUERY_TYPE_OCCLUSION and pname:flags contains ename:VK_QUERY_CONTROL_PRECISE_BIT, an implementation @@ -379,6 +381,10 @@ include::../api/protos/vkGetQueryPoolResults.txt[] * pname:queryCount is the number of queries. pname:firstQuery and pname:queryCount together define a range of queries. + For pipeline statistics queries, each query index in the pool contains + one integer value for each bit that is enabled in + slink:VkQueryPoolCreateInfo::pname:pipelineStatistics when the pool is + created. * pname:dataSize is the size in bytes of the buffer pointed to by pname:pData. * pname:pData is a pointer to a user-allocated buffer where the results diff --git a/doc/specs/vulkan/chapters/renderpass.txt b/doc/specs/vulkan/chapters/renderpass.txt index bf9d9807dd..3da01778dd 100644 --- a/doc/specs/vulkan/chapters/renderpass.txt +++ b/doc/specs/vulkan/chapters/renderpass.txt @@ -324,7 +324,6 @@ not include the *PerViewNV[] outputs in their interfaces. endif::VK_NVX_multiview_per_view_attributes[] - .Valid Usage **** * If pname:subpassCount is not zero, pname:subpassCount must: be equal to @@ -1054,8 +1053,8 @@ conditions: An attachment used as both an input attachment and a color attachment must: be in the ename:VK_IMAGE_LAYOUT_GENERAL layout. An attachment used as an input attachment and depth/stencil attachment must: -be in either ename:VK_IMAGE_LAYOUT_GENERAL or -ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL. +be in the ename:VK_IMAGE_LAYOUT_GENERAL or +ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL layout. An attachment must: not be used as both a depth/stencil attachment and a color attachment. diff --git a/doc/specs/vulkan/chapters/resources.txt b/doc/specs/vulkan/chapters/resources.txt index bda040edb0..b981f2b657 100644 --- a/doc/specs/vulkan/chapters/resources.txt +++ b/doc/specs/vulkan/chapters/resources.txt @@ -176,10 +176,20 @@ ifdef::VK_KHX_external_memory+VK_NV_dedicated_allocation[] dedicated allocation, as reported by flink:vkGetPhysicalDeviceExternalBufferPropertiesKHX in sname:VkExternalBufferPropertiesKHX::pname:externalMemoryProperties::pname:externalMemoryFeatures, - the pname:pNext extension chain must contain an instance of + the pname:pNext extension chain must: contain an instance of sname:VkDedicatedAllocationBufferCreateInfoNV with its pname:dedicatedAllocation field set to ename:VK_TRUE. endif::VK_KHX_external_memory+VK_NV_dedicated_allocation[] +ifdef::VK_KHX_external_memory[] + * If the pname:pNext extension chain contains an instance of + slink:VkExternalMemoryBufferCreateInfoKHX, its pname:handleTypes member + must: only contain bits that are also in + slink:VkExternalBufferPropertiesKHX::pname:externalMemoryProperties.pname:compatibleHandleTypes, + as returned by flink:vkGetPhysicalDeviceExternalBufferPropertiesKHX with + pname:pExternalBufferInfo->pname:handleType equal to any one of the + handle types specified in + slink:VkExternalMemoryBufferCreateInfoKHX::pname:handleTypes +endif::VK_KHX_external_memory[] **** include::../validity/structs/VkBufferCreateInfo.txt[] @@ -233,13 +243,6 @@ include::../api/structs/VkExternalMemoryBufferCreateInfoKHX.txt[] elink:VkExternalMemoryHandleTypeFlagBitsKHX specifying one or more external memory handle types. -.Valid Usage -**** - * The bits in pname:handleTypes must: be compatible with each other and - the other buffer creation parameters, as reported in - slink:VkExternalBufferPropertiesKHX. -**** - include::../validity/structs/VkExternalMemoryBufferCreateInfoKHX.txt[] endif::VK_KHX_external_memory[] @@ -470,8 +473,6 @@ include::../api/structs/VkImageCreateInfo.txt[] * pname:initialLayout selects the initial elink:VkImageLayout state of all image subresources of the image. See <>. - pname:initialLayout must: be ename:VK_IMAGE_LAYOUT_UNDEFINED or - ename:VK_IMAGE_LAYOUT_PREINITIALIZED. Images created with pname:tiling equal to ename:VK_IMAGE_TILING_LINEAR have further restrictions on their limits and capabilities compared to images @@ -514,15 +515,16 @@ flink:vkGetPhysicalDeviceFormatProperties. * If pname:sharingMode is ename:VK_SHARING_MODE_CONCURRENT, pname:queueFamilyIndexCount must: be greater than `1` * pname:format must: not be ename:VK_FORMAT_UNDEFINED - * The pname:width, pname:height, and pname:depth members of pname:extent - must: all be greater than `0` + * pname:extent::pname:width must: be greater than `0`. + * pname:extent::pname:height must: be greater than `0`. + * pname:extent::pname:depth must: be greater than `0`. * pname:mipLevels must: be greater than `0` * pname:arrayLayers must: be greater than `0` * If pname:flags contains ename:VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT, - pname:imageType must be ename:VK_IMAGE_TYPE_2D + pname:imageType must: be ename:VK_IMAGE_TYPE_2D ifdef::VK_KHR_maintenance1[] * If pname:flags contains - ename:VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT_KHR, pname:imageType must + ename:VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT_KHR, pname:imageType must: be ename:VK_IMAGE_TYPE_3D endif::VK_KHR_maintenance1[] * If pname:imageType is ename:VK_IMAGE_TYPE_1D, pname:extent.width must: @@ -774,16 +776,42 @@ ifdef::VK_KHX_external_memory+VK_NV_dedicated_allocation[] require a dedicated allocation, as reported by flink:vkGetPhysicalDeviceImageFormatProperties2KHR in sname:VkExternalImageFormatPropertiesKHX::pname:externalMemoryProperties::pname:externalMemoryFeatures, - the pname:pNext extension chain must contain an instance of + the pname:pNext extension chain must: contain an instance of sname:VkDedicatedAllocationImageCreateInfoNV with its pname:dedicatedAllocation field set to ename:VK_TRUE. endif::VK_KHX_external_memory+VK_NV_dedicated_allocation[] +ifdef::VK_KHX_external_memory[] + * If the pname:pNext extension chain contains an instance of + slink:VkExternalMemoryImageCreateInfoKHX, its pname:handleTypes member + must: only contain bits that are also in + slink:VkExternalImageFormatPropertiesKHX::pname:externalMemoryProperties::pname:compatibleHandleTypes, + as returned by flink:vkGetPhysicalDeviceImageFormatProperties2KHR with + pname:format, pname:type, pname:tiling, pname:usage, and pname:flags + equal to those in this structure, and with an instance of + slink:VkPhysicalDeviceExternalImageFormatInfoKHX in the pname:pNext + structure chain, with a pname:handleType equal to any one of the handle + types specified in + slink:VkExternalMemoryImageCreateInfoKHX::pname:handleTypes +endif::VK_KHX_external_memory[] +ifdef::VK_NV_external_memory+VK_NV_external_memory_capabilities[] + * If the pname:pNext extension chain contains an instance of + slink:VkExternalMemoryImageCreateInfoNV, its pname:handleTypes member + must: only contain bits that are also in + slink:VkExternalImageFormatPropertiesNV::pname:externalMemoryProperties::pname:compatibleHandleTypes, + as returned by flink:vkGetPhysicalDeviceExternalImageFormatPropertiesNV + with pname:format, pname:type, pname:tiling, pname:usage, and + pname:flags equal to those in this structure, and with + pname:externalHandleType equal to any one of the handle types specified + in slink:VkExternalMemoryImageCreateInfoNV::pname:handleTypes +endif::VK_NV_external_memory+VK_NV_external_memory_capabilities[] ifdef::VK_KHX_device_group[] * If pname:flags contains ename:VK_IMAGE_CREATE_BIND_SFR_BIT_KHX, then pname:mipLevels must: be one, pname:arrayLayers must: be one, pname:imageType must: be ename:VK_IMAGE_TYPE_2D, and pname:tiling must: be ename:VK_IMAGE_TILING_OPTIMAL. endif::VK_KHX_device_group[] + * pname:initialLayout must: be ename:VK_IMAGE_LAYOUT_UNDEFINED or + ename:VK_IMAGE_LAYOUT_PREINITIALIZED. **** include::../validity/structs/VkImageCreateInfo.txt[] @@ -843,13 +871,6 @@ include::../api/structs/VkExternalMemoryImageCreateInfoKHX.txt[] elink:VkExternalMemoryHandleTypeFlagBitsKHX specifying one or more external memory handle types. -.Valid Usage -**** - * The bits in pname:handleTypes must: be compatible with each other and - the other image creation parameters, as reported in - slink:VkExternalImageFormatPropertiesKHX. -**** - include::../validity/structs/VkExternalMemoryImageCreateInfoKHX.txt[] endif::VK_KHX_external_memory[] @@ -871,9 +892,6 @@ include::../api/structs/VkExternalMemoryImageCreateInfoNV.txt[] * pname:handleTypes is a bitmask of elink:VkExternalMemoryHandleTypeFlagBitsNV specifying one or more external memory handle types. - The types must: all be compatible with each other and the other image - creation parameters, as reported by - flink:vkGetPhysicalDeviceExternalImageFormatPropertiesNV. include::../validity/structs/VkExternalMemoryImageCreateInfoNV.txt[] @@ -1418,9 +1436,15 @@ section. pname:depth = ci.pname:extent.depth + pname:arrayLayers = ci.pname:arrayLayers + pname:samples = ci.pname:samples + + pname:flags = ci.pname:flags + where ci is the slink:VkImageCreateInfo used to create pname:image. - | pname:baseArrayLayer and pname:layerCount are members of the - pname:subresourceRange member. +ifndef::VK_KHR_maintenance1[] + | pname:baseArrayLayer, pname:layerCount, and pname:levelCount +endif::VK_KHR_maintenance1[] +ifdef::VK_KHR_maintenance1[] + | pname:baseArrayLayer and pname:layerCount +endif::VK_KHR_maintenance1[] + are members of the pname:subresourceRange member. | 1D, 0, 0 | pname:imageType = ename:VK_IMAGE_TYPE_1D + pname:width {geq} 1 + @@ -1428,7 +1452,7 @@ pname:height = 1 + pname:depth = 1 + pname:arrayLayers {geq} 1 + pname:samples = 1 | -pname:viewType = ename:VK_VIEW_TYPE_1D + +pname:viewType = ename:VK_IMAGE_VIEW_TYPE_1D + pname:baseArrayLayer {geq} 0 + pname:layerCount = 1 | 1D, 1, 0 | @@ -1438,7 +1462,7 @@ pname:height = 1 + pname:depth = 1 + pname:arrayLayers {geq} 1 + pname:samples = 1 | -pname:viewType = ename:VK_VIEW_TYPE_1D_ARRAY + +pname:viewType = ename:VK_IMAGE_VIEW_TYPE_1D_ARRAY + pname:baseArrayLayer {geq} 0 + pname:layerCount {geq} 1 | 2D, 0, 0 | @@ -1448,7 +1472,7 @@ pname:height {geq} 1 + pname:depth = 1 + pname:arrayLayers {geq} 1 + pname:samples = 1 | -pname:viewType = ename:VK_VIEW_TYPE_2D + +pname:viewType = ename:VK_IMAGE_VIEW_TYPE_2D + pname:baseArrayLayer {geq} 0 + pname:layerCount = 1 | 2D, 1, 0 | @@ -1458,7 +1482,7 @@ pname:height {geq} 1 + pname:depth = 1 + pname:arrayLayers {geq} 1 + pname:samples = 1 | -pname:viewType = ename:VK_VIEW_TYPE_2D_ARRAY + +pname:viewType = ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY + pname:baseArrayLayer {geq} 0 + pname:layerCount {geq} 1 | 2D, 0, 1 | @@ -1468,7 +1492,7 @@ pname:height {geq} 1 + pname:depth = 1 + pname:arrayLayers {geq} 1 + pname:samples > 1 | -pname:viewType = ename:VK_VIEW_TYPE_2D + +pname:viewType = ename:VK_IMAGE_VIEW_TYPE_2D + pname:baseArrayLayer {geq} 0 + pname:layerCount = 1 | 2D, 1, 1 | @@ -1478,7 +1502,7 @@ pname:height {geq} 1 + pname:depth = 1 + pname:arrayLayers {geq} 1 + pname:samples > 1 | -pname:viewType = ename:VK_VIEW_TYPE_2D_ARRAY + +pname:viewType = ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY + pname:baseArrayLayer {geq} 0 + pname:layerCount {geq} 1 | CUBE, 0, 0 | @@ -1489,7 +1513,7 @@ pname:depth = 1 + pname:arrayLayers {geq} 6 + pname:samples = 1 + pname:flags includes ename:VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT | -pname:viewType = ename:VK_VIEW_TYPE_CUBE + +pname:viewType = ename:VK_IMAGE_VIEW_TYPE_CUBE + pname:baseArrayLayer {geq} 0 + pname:layerCount = 6 | CUBE, 1, 0 | @@ -1501,7 +1525,7 @@ _N_ {geq} 1 + pname:arrayLayers {geq} 6 {times} _N_ + pname:samples = 1 + pname:flags includes ename:VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT | -pname:viewType = ename:VK_VIEW_TYPE_CUBE_ARRAY + +pname:viewType = ename:VK_IMAGE_VIEW_TYPE_CUBE_ARRAY + pname:baseArrayLayer {geq} 0 + pname:layerCount = 6 {times} _N_, _N_ {geq} 1 | 3D, 0, 0 | @@ -1511,7 +1535,7 @@ pname:height {geq} 1 + pname:depth {geq} 1 + pname:arrayLayers = 1 + pname:samples = 1 | -pname:viewType = ename:VK_VIEW_TYPE_3D + +pname:viewType = ename:VK_IMAGE_VIEW_TYPE_3D + pname:baseArrayLayer = 0 + pname:layerCount = 1 ifdef::VK_KHR_maintenance1[] @@ -1524,7 +1548,7 @@ pname:arrayLayers = 1 + pname:samples = 1 + pname:flags includes ename:VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT + pname:flags does not include VK_IMAGE_CREATE_SPARSE_BINDING_BIT, VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT, and VK_IMAGE_CREATE_SPARSE_ALIASED_BIT | -pname:viewType = ename:VK_VIEW_TYPE_2D + +pname:viewType = ename:VK_IMAGE_VIEW_TYPE_2D + pname:levelCount = 1 + pname:baseArrayLayer {geq} 0 + pname:layerCount = 1 @@ -1537,7 +1561,7 @@ pname:arrayLayers = 1 + pname:samples = 1 + pname:flags includes ename:VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT + pname:flags does not include VK_IMAGE_CREATE_SPARSE_BINDING_BIT, VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT, and VK_IMAGE_CREATE_SPARSE_ALIASED_BIT | -pname:viewType = ename:VK_VIEW_TYPE_2D_ARRAY + +pname:viewType = ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY + pname:levelCount = 1 + pname:baseArrayLayer {geq} 0 + pname:layerCount {geq} 1 @@ -1789,7 +1813,7 @@ ifdef::VK_KHR_maintenance1[] * If the pname:imageType specified in slink:VkImageCreateInfo when the image was created was ename:VK_IMAGE_TYPE_3D and the image view is created with the pname:viewType of slink:VkImageViewCreateInfo set to - ename:VK_VIEW_TYPE_2D_ARRAY then pname:layerCount must: be + ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY then pname:layerCount must: be ename:VK_REMAINING_ARRAY_LAYERS, or [eq]#pname:layerCount# must: be non-zero and [eq]#(pname:baseArrayLayer + pname:layerCount)# must: be less than or equal to the pname:extent.depth specified in @@ -1797,7 +1821,7 @@ ifdef::VK_KHR_maintenance1[] * If the pname:imageType specified in slink:VkImageCreateInfo when the image was created was not ename:VK_IMAGE_TYPE_3D or the image view is not created with the pname:viewType of slink:VkImageViewCreateInfo set - to ename:VK_VIEW_TYPE_2D_ARRAY then pname:layerCount must: be + to ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY then pname:layerCount must: be ename:VK_REMAINING_ARRAY_LAYERS, or [eq]#pname:layerCount# must: be non-zero and [eq]#(pname:baseArrayLayer + pname:layerCount)# must: be less than or equal to the pname:arrayLayers specified in diff --git a/doc/specs/vulkan/chapters/sparsemem.txt b/doc/specs/vulkan/chapters/sparsemem.txt index 20d11c302d..5501e19658 100644 --- a/doc/specs/vulkan/chapters/sparsemem.txt +++ b/doc/specs/vulkan/chapters/sparsemem.txt @@ -1544,6 +1544,7 @@ include::../validity/structs/VkDeviceGroupBindSparseInfoKHX.txt[] endif::VK_KHX_device_group[] + [[sparsememory-examples]] == Examples diff --git a/doc/specs/vulkan/chapters/synchronization.txt b/doc/specs/vulkan/chapters/synchronization.txt index 3fecd6170d..54533a4555 100644 --- a/doc/specs/vulkan/chapters/synchronization.txt +++ b/doc/specs/vulkan/chapters/synchronization.txt @@ -973,12 +973,18 @@ with the following return codes: | Status | Meaning | ename:VK_SUCCESS | The fence specified by pname:fence is signaled. | ename:VK_NOT_READY | The fence specified by pname:fence is unsignaled. +| ename:VK_DEVICE_LOST | The device has been lost. See <>. |==== If a <> command is pending execution, then the value returned by this command may: immediately be out of date. +If the device has been lost (see <>), +fname:vkGetFenceStatus may: return any of the above status codes. +If the device has been lost and fname:vkGetFenceStatus is called repeatedly, +it will eventually return either ename:VK_SUCCESS or ename:VK_DEVICE_LOST. + include::../validity/protos/vkGetFenceStatus.txt[] [[synchronization-fences-unsignaling]] @@ -1071,6 +1077,20 @@ fname:vkWaitForFences returns ename:VK_TIMEOUT. If the condition is satisfied before pname:timeout nanoseconds has expired, fname:vkWaitForFences returns ename:VK_SUCCESS. +If device loss occurs (see <>) before +the timeout has expired, fname:vkWaitForFences must: return in finite time +with either ename:VK_SUCCESS or ename:VK_DEVICE_LOST. + +.Note +[NOTE] +==== +While we guarantee that fname:vkWaitForFences must: return in finite time, +no guarantees are made that it returns immediately upon device loss. +However, the client can reasonably expect that the delay will be on the +order of seconds and that calling fname:vkWaitForFences will not result in a +permanently (or seemingly permanently) dead process. +==== + include::../validity/protos/vkWaitForFences.txt[] [[synchronization-fences-waiting]] @@ -1174,7 +1194,7 @@ include::../api/structs/VkExportSemaphoreCreateInfoKHX.txt[] .Valid Usage **** - * The bits in pname:handleTypes must be supported and compatible, as + * The bits in pname:handleTypes must: be supported and compatible, as reported by slink:VkExternalSemaphorePropertiesKHX. **** @@ -1276,7 +1296,7 @@ using the fname:CloseHandle system call when they are no longer needed. <>, there must: be no queue waiting on pname:semaphore. * If pname:handleType refers to a handle type with temporary import - semantics, pname:semaphore must be signaled, or have an associated + semantics, pname:semaphore must: be signaled, or have an associated <> pending execution. * pname:handleType must: be defined as an NT handle or a global share @@ -1328,7 +1348,7 @@ needed, or by importing Vulkan semaphore state from it. <>, there must: be no queue waiting on pname:semaphore. * If pname:handleType refers to a handle type with temporary import - semantics, pname:semaphore must be signaled, or have an associated + semantics, pname:semaphore must: be signaled, or have an associated <> pending execution. * pname:handleType must: be defined as a POSIX file descriptor handle. @@ -1566,7 +1586,7 @@ endif::VK_KHR_swapchain[] When importing semaphore state, it is the responsibility of the application to ensure the external handles meet all valid usage requirements. -However, implementations must perform sufficient validation of external +However, implementations must: perform sufficient validation of external handles to ensure that the operation results in valid semaphore state which will not cause program termination, device loss, queue stalls, or corruption of other resources when used as allowed according to its import parameters, @@ -2475,11 +2495,11 @@ ifdef::VK_KHX_external_memory[] ename:VK_QUEUE_FAMILY_IGNORED. * If pname:buffer was created with a sharing mode of ename:VK_SHARING_MODE_EXCLUSIVE and pname:srcQueueFamilyIndex is not - ename:VK_QUEUE_FAMILY_IGNORED, it must be a valid queue family or + ename:VK_QUEUE_FAMILY_IGNORED, it must: be a valid queue family or VK_QUEUE_FAMILY_EXTERNAL_KHX (see <>). * If pname:buffer was created with a sharing mode of ename:VK_SHARING_MODE_EXCLUSIVE and pname:dstQueueFamilyIndex is not - ename:VK_QUEUE_FAMILY_IGNORED, it must be a valid queue family or + ename:VK_QUEUE_FAMILY_IGNORED, it must: be a valid queue family or VK_QUEUE_FAMILY_EXTERNAL_KHX (see <>). endif::VK_KHX_external_memory[] * If pname:buffer was created with a sharing mode of @@ -2599,11 +2619,11 @@ ifdef::VK_KHX_external_memory[] ename:VK_QUEUE_FAMILY_IGNORED. * If pname:image was created with a sharing mode of ename:VK_SHARING_MODE_EXCLUSIVE and pname:srcQueueFamilyIndex is not - ename:VK_QUEUE_FAMILY_IGNORED, it must be a valid queue family or + ename:VK_QUEUE_FAMILY_IGNORED, it must: be a valid queue family or VK_QUEUE_FAMILY_EXTERNAL_KHX (see <>). * If pname:image was created with a sharing mode of ename:VK_SHARING_MODE_EXCLUSIVE and pname:dstQueueFamilyIndex is not - ename:VK_QUEUE_FAMILY_IGNORED, it must be a valid queue family or + ename:VK_QUEUE_FAMILY_IGNORED, it must: be a valid queue family or VK_QUEUE_FAMILY_EXTERNAL_KHX (see <>). endif::VK_KHX_external_memory[] * If pname:image was created with a sharing mode of @@ -2743,7 +2763,7 @@ results for future access, so availability of those writes has no practical use. In an earlier version of the specification, these were required to match on both sides - but this was subsequently relaxed. -It is now recommended that these masks are simply set to 0. +These masks should: be set to 0. ==== If the transfer is via an image memory barrier, and an diff --git a/doc/specs/vulkan/config/vulkan-macros.rb b/doc/specs/vulkan/config/vulkan-macros.rb index 7eea966094..ce2959e759 100644 --- a/doc/specs/vulkan/config/vulkan-macros.rb +++ b/doc/specs/vulkan/config/vulkan-macros.rb @@ -20,14 +20,10 @@ inline_macro CanInlineMacro inline_macro CannotInlineMacro inline_macro MayInlineMacro - inline_macro MayNotInlineMacro inline_macro MustInlineMacro - inline_macro MustNotInlineMacro inline_macro OptionalInlineMacro - inline_macro RecommendInlineMacro inline_macro RequiredInlineMacro inline_macro ShouldInlineMacro - inline_macro ShouldNotInlineMacro inline_macro FlinkInlineMacro inline_macro FnameInlineMacro inline_macro FtextInlineMacro diff --git a/doc/specs/vulkan/config/vulkan-macros/extension.rb b/doc/specs/vulkan/config/vulkan-macros/extension.rb index ea67db8a8e..aef3695009 100644 --- a/doc/specs/vulkan/config/vulkan-macros/extension.rb +++ b/doc/specs/vulkan/config/vulkan-macros/extension.rb @@ -86,15 +86,6 @@ def text end end -class MayNotInlineMacro < NormativeInlineMacroBase - named :maynot - match /maynot:(\w*)/ - - def text - 'may not' - end -end - class MustInlineMacro < NormativeInlineMacroBase named :must match /must:(\w*)/ @@ -104,15 +95,6 @@ def text end end -class MustNotInlineMacro < NormativeInlineMacroBase - named :mustnot - match /mustnot:(\w*)/ - - def text - 'must not' - end -end - class OptionalInlineMacro < NormativeInlineMacroBase named :optional match /optional:(\w*)/ @@ -122,15 +104,6 @@ def text end end -class RecommendInlineMacro < NormativeInlineMacroBase - named :recommend - match /recommend:(\w*)/ - - def text - 'recommend' - end -end - class RequiredInlineMacro < NormativeInlineMacroBase named :required match /required:(\w*)/ @@ -149,15 +122,6 @@ def text end end -class ShouldNotInlineMacro < NormativeInlineMacroBase - named :shouldnot - match /shouldnot:(\w*)/ - - def text - 'should not' - end -end - class FlinkInlineMacro < LinkInlineMacroBase named :flink match /flink:(\w+)/ @@ -170,7 +134,7 @@ class FnameInlineMacro < StrongInlineMacroBase class FtextInlineMacro < StrongInlineMacroBase named :ftext - match /ftext:(\w+)/ + match /ftext:([\w\*]+)/ end class SnameInlineMacro < CodeInlineMacroBase @@ -185,7 +149,7 @@ class SlinkInlineMacro < LinkInlineMacroBase class StextInlineMacro < CodeInlineMacroBase named :stext - match /stext:(\w+)/ + match /stext:([\w\*]+)/ end class EnameInlineMacro < CodeInlineMacroBase diff --git a/doc/specs/vulkan/scripts/checkXrefs b/doc/specs/vulkan/scripts/checkXrefs new file mode 100755 index 0000000000..4d66dfbcde --- /dev/null +++ b/doc/specs/vulkan/scripts/checkXrefs @@ -0,0 +1,21 @@ +#!/bin/sh +# checkXrefs - check internal links in a Vulkan HTML spec +# Usage: checkXrefs file.html +# Prints a list of internal hrefs with no corresponding anchors. +# (There are many anchors with no corresponding hrefs - this is OK). + +xrefs=`tempfile` +ids=`tempfile` + +sed -e 's/ href="#/\nhref="#/g' < $1 | \ + grep 'href="#' | \ + sed -e 's/href="#//g' -e 's/"[ >].*//g' | \ + sort | uniq > $xrefs +sed -e 's/ id="/\nid="/g' < $1 | \ + grep 'id="' | \ + sed -e 's/id="//g' -e 's/"[ >].*//g' | \ + sort | uniq > $ids + +comm -23 $xrefs $ids + +rm $xrefs $ids 1>&2 diff --git a/doc/specs/vulkan/style/extensions.txt b/doc/specs/vulkan/style/extensions.txt index 511acba2b7..50036a9118 100644 --- a/doc/specs/vulkan/style/extensions.txt +++ b/doc/specs/vulkan/style/extensions.txt @@ -290,7 +290,7 @@ effort to develop a Vulkan implementation and require one for that purpose. == Registering Extensions and Layers Extensions must be registered with Khronos. -Layers may be registered, and registration is strongly recommended. +Layers should be registered, but registration is not required. Registration means: * Receiving an extension number. @@ -438,6 +438,7 @@ for extensions, which include (but may not be limited to) the following: add: + -- +[source,asciidoc] .Example Markup ---- \ifdef::VK_EXT_debug_marker[] @@ -454,6 +455,7 @@ for extensions, which include (but may not be limited to) the following: in that file: + -- +[source,asciidoc] .Example Markup ---- \ifdef::VK_EXT_debug_marker[] @@ -469,6 +471,7 @@ for extensions, which include (but may not be limited to) the following: section as follows: + -- +[source,asciidoc] .Example Markup ---- ... list of existing error codes @@ -486,6 +489,7 @@ for extensions, which include (but may not be limited to) the following: http://asciidoctor.org/docs/user-manual/#checking-multiple-attributes-ifdef-and-ifndef-only). + -- +[source,asciidoc] .Example Markup ---- \ifdef::VK_KHR_foo[] diff --git a/doc/specs/vulkan/style/markup.txt b/doc/specs/vulkan/style/markup.txt index 68df143e37..1f3b75a5ec 100644 --- a/doc/specs/vulkan/style/markup.txt +++ b/doc/specs/vulkan/style/markup.txt @@ -29,6 +29,7 @@ syntax compatibility mode]. Always precede the anchor by two blank lines (except at the beginning of a file), and follow the title by a blank line, to set off sections visibly. +[source,asciidoc] .Example Markup ---- [[markup]] @@ -136,15 +137,18 @@ long as the colliding numbers are not in the same section. [NOTE] .Example Markup -- +[source,asciidoc] +---- +See reference^2^ -`See reference^2^` -> See reference^2^. - -.... 2:: Reference 2. -.... +---- + -> +See reference^2^ + 2:: Reference 2. -- @@ -176,19 +180,20 @@ itself, or by a blank line, due to limitations of the asciidoc parser. ** Nested lists should align the leftmost list item delimiter (bullet, etc.) with the parent delimiter. +[source,asciidoc] .Example Markup ---- * This is the first item in a bullet list. - * The second item is described with two paragraphs. The second - paragraph is in a continuation block: + * The second item is described with two paragraphs. + The second paragraph is in a continuation block: + -- This is a continuation block containing the second paragraph, -- + - ** This is a nested list item for the second item. Since it - follows a continuation block, it must be separated by a - blank line or `+` from that block. + ** This is a nested list item for the second item. + Since it follows a continuation block, it must be separated by a blank + line or `+` from that block. ---- [[markup-labelled-lists]] @@ -204,12 +209,13 @@ must be alone on a line, followed by the contents of that list entry. For consistency do not use labels ending in three or four colons, or two semicolons, even though these forms are allowed in asciidoc markup. +[source,asciidoc] .Example Markup ---- - Glossary Entry:: +Glossary Entry:: This is a glossary entry. - Last Modified Date:: +Last Modified Date:: 2016-02-16 ---- @@ -227,11 +233,12 @@ period. . In addition, the markup is harder to recognize for scripts and tools (other than asciidoc itself) operating on the document source. +[source,asciidoc] .Example Markup ---- - . First list item. - . Second list item. - . Etc. +. First list item. +. Second list item. +. Etc. ---- @@ -256,6 +263,7 @@ There are several different toolchains followed for various forms of asciidoc output, and not all of them treat anchors without alt-text the same way. +[source,asciidoc] .Example Markup ---- In general, chapters and sections should always have anchors, following the @@ -281,6 +289,7 @@ all appear on a single line. Tables should usually be preceded with a short title. +[source,asciidoc] .Example Markup ---- .Normative Terminology Macros @@ -300,6 +309,7 @@ All figures (images) must be marked up as follows, to ensure there is an anchor and that the figure is given a caption which shows the figure number and is added to the list of figures: +[source,asciidoc] .Example Markup ---- [[fig-anchorname]] @@ -316,6 +326,7 @@ document. If a longer caption is required, follow the figure directive with a sidebar block including the full caption preceded by a link to the figure: +[source,asciidoc] .Example Markup ---- .Caption @@ -447,6 +458,7 @@ This is often done when referring to a particular parameter or member in a part of the document other than the description of the corresponding function or structure. +[source,asciidoc] .Example Markup ---- flink:vkCmdBindIndexBuffer::pname:indexType @@ -461,6 +473,7 @@ Occasional asterisk markup is used for *emphasis*. Underscores are used for _glossary terms_. Backtick markup is used for the C `NULL` macro. +[source,asciidoc] .Example Markup ---- *emphasis* @@ -476,6 +489,7 @@ appendix in the <>. However, we will probably change to using custom macros soon, to enable linkage between the glossary and definitions in the spec body. +[source,asciidoc] .Example Markup ---- _Glossary terms_ @@ -509,7 +523,6 @@ The normative terminology macros are defined in the following table: | must{cl} not | must: not | optional{cl} | optional: | optionally{cl} | optionally: -| recommend{cl} | recommend: | required{cl} | required: | should{cl} | should: | should{cl} not | should: not @@ -537,6 +550,7 @@ _may{cl} not_ to describe it. If functionality (rather than behavior) is optional, it should be described as +[source,asciidoc] .Example Markup ---- not required: @@ -575,6 +589,7 @@ the title _Note_, as in the following example: This is an informative note. ==== +[source,asciidoc] .Example Markup ---- [NOTE] @@ -587,6 +602,7 @@ This is an informative note. If an entire chapter or section is considered informative, it should begin with the sentence: +[source,asciidoc] .Example Markup ---- This chapter/section is Informative. @@ -613,6 +629,7 @@ This is an editing note, marked up as follows: ==== endif::editing-notes[] +[source,asciidoc] .Example Markup ---- \ifdef::editing-notes[] @@ -645,6 +662,7 @@ This is an implementor's note, marked up as follows: ==== endif::implementation-guide[] +[source,asciidoc] .Example Markup ---- \ifdef::implementation-guide[] diff --git a/doc/specs/vulkan/style/naming.txt b/doc/specs/vulkan/style/naming.txt index 894c9580ec..53bf25787d 100644 --- a/doc/specs/vulkan/style/naming.txt +++ b/doc/specs/vulkan/style/naming.txt @@ -428,9 +428,8 @@ A:: [[naming-prefixes]] == Standard Prefixes -Prefixes are used in the API to denote specific semantic meaning of -{apiname} names, or as a label to avoid name clashes, and are explained -here: +Prefixes are used in the API to denote specific semantic meaning of Vulkan +names, or as a label to avoid name clashes, and are explained here: VK/Vk/vk:: Vulkan namespace + diff --git a/doc/specs/vulkan/style/writing.txt b/doc/specs/vulkan/style/writing.txt index 182d7932e7..e7695f71ae 100644 --- a/doc/specs/vulkan/style/writing.txt +++ b/doc/specs/vulkan/style/writing.txt @@ -32,6 +32,7 @@ the month. Never use ambigious formats such as "`09/12/16`". +[source,asciidoc] .Example Markup ---- * 2016-09-12 @@ -49,17 +50,23 @@ It is easy to get this wrong when talking about Vulkan API names tagged with the <>. For example, if you wanted to say: - A VK_ERROR_DEVICE_LOST error +A ename:VK_ERROR_DEVICE_LOST error the correct way to mark this up in asciidoc would be: - A ename:VK_ERROR_DEVICE_LOST error +[source,asciidoc] +---- +A ename:VK_ERROR_DEVICE_LOST error +---- However, on first glance at this it *appears* wrong, because the "`word`" following "`a`" is the macro name, "`ename{cl}`". That starts with a vowel, so the temptation is to say - An ename:VK_ERROR_DEVICE_LOST error may occur. +[source,asciidoc] +---- +An ename:VK_ERROR_DEVICE_LOST error may occur. +---- What matters here is how the *output* document is formatted. @@ -136,11 +143,12 @@ of a structure as a "`color space`" value. ==== Words With "Pre-" Prefixes -// also: premultiply preorder prerotation predefin +// also: premultiply preorder prerotation predefined When using the prefix "`pre`" to indicate "`prior to`", such as in the words "`preinitialized`", "`preprocess`", and "`pretransform`", do not separate the prefix from the word with a hyphen. +This list is not intended to be complete. [[writing-describing]] @@ -292,11 +300,12 @@ For example: * latexmath:[\frac{1 - \frac{x}{2}}{x - 1}] * latexmath:[\mathbf{c} = t \mathbf{c}_1 + (1-t) \mathbf{c}_2.] +[source,asciidoc] .Example Markup ---- - latexmath:[[0,1\]] - latexmath:[\frac{1 - \frac{x}{2}}{x - 1}] - latexmath:[\mathbf{c} = t \mathbf{c}_1 + (1-t) \mathbf{c}_2. ] + * latexmath:[[0,1\]] + * latexmath:[\frac{1 - \frac{x}{2}}{x - 1}] + * latexmath:[\mathbf{c} = t \mathbf{c}_1 + (1-t) \mathbf{c}_2. ] ---- Note the escaped bracket in markup for the first expression, which is @@ -316,6 +325,7 @@ c_{RGB} & = \end{aligned} +++++++++++++++++++ +[source,asciidoc] .Example Markup ---- [latexmath] @@ -387,6 +397,7 @@ V = \end{cases} +++++++++++++++++++ +[source,asciidoc] .Example Markup ---- [latexmath] @@ -412,11 +423,14 @@ When describing an extension structure which is passed to an existing command by placing it in the pname:pNext chain of a structure parameter of that command, introduce the structure description in this fashion: - When *performing an operation described by the extension struct*, add - the slink:VkExtensionStructNameID to the pname:pNext chain of the - slink:VkBaseExtensionStructName structure passed to the - flink:vkBaseFunctionName command *saying what the extension struct - does*. +[source,asciidoc] +---- +When *performing an operation described by the extension struct*, add +the slink:VkExtensionStructNameID to the pname:pNext chain of the +slink:VkBaseExtensionStructName structure passed to the +flink:vkBaseFunctionName command *saying what the extension struct +does*. +---- [[writing-example]] @@ -451,11 +465,14 @@ more passive phrasing like "`A command pool is created by calling:`" or After the description, include the autogenerated prototype for the command from the `../protos/` directory: - // refBegin vkCreateCommandPool Create a new command pool object +[source,asciidoc] +---- +// refBegin vkCreateCommandPool Create a new command pool object - To create a command pool, call: +To create a command pool, call: - include::../api/protos/vkCreateCommandPool.txt[] +\include::../api/protos/vkCreateCommandPool.txt[] +---- Note that each autogenerated command, enumeration, flag, or structure definition include file also defines a corresponding asciidoc anchor which @@ -511,7 +528,10 @@ The fname:vkCreateCommandPool used as an example here has no such explicit language, but the sname:VkCommandPoolCreateInfo used below does have explicit language. - include::../validity/protos/vkCreateCommandPool.txt[] +[source,asciidoc] +---- +\include::../validity/protos/vkCreateCommandPool.txt[] +---- Structures and enumerations first used as parameters of a command are described next. @@ -536,12 +556,15 @@ sname:VkStructureName structure is defined as:`". After the description, include the autogenerated definition for the structure from the `../structs/` directory: - // refBegin VkCommandPoolCreateInfo - Structure specifying parameters of - a newly created command pool +[source,asciidoc] +---- +// refBegin VkCommandPoolCreateInfo - Structure specifying parameters of +a newly created command pool - The sname:VkCommandPoolCreateInfo structure is defined as: +The sname:VkCommandPoolCreateInfo structure is defined as: - include::../api/structs/VkCommandPoolCreateInfo.txt[] +\include::../api/structs/VkCommandPoolCreateInfo.txt[] +---- ==== * pname:sType is the type of this structure. @@ -571,6 +594,7 @@ For the stext:Vk*CreateInfo structures in particular, there is standard boilerplate for the pname:sType and pname:pNext members, followed by the members specific to the structure. +[source,asciidoc] ---- * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to an extension-specific structure. @@ -583,6 +607,7 @@ applied due to limitations of the asciidoc parser. It is usually best to append a continuation block following the first paragraph of such a list item: +[source,asciidoc] ---- * pname:flags is a bitmask indicating usage behavior for the pool and command buffers allocated from it. Bits which can: be set include: @@ -616,12 +641,23 @@ Following the definition of structure members, add explicit validity language, following by including the implicit (automatically generated) validity language include for this structure: - .Valid Usage **** - * pname:queueFamilyIndex must: be the index of a queue family - available in the calling command's pname:device parameter - **** +[source,asciidoc] +---- +.Valid Usage +**** + * pname:queueFamilyIndex must: be the index of a queue family available in + the calling command's pname:device parameter +**** - include::../validity/structs/VkCommandPoolCreateInfo.txt[] +\include::../validity/structs/VkCommandPoolCreateInfo.txt[] +---- + +Each explicit Valid Usage statement should be a single assertion, possibly +involving multiple subexpressions or parameters. +For example, instead of writing "`width, height, and depth must: all be +greater than zero`", write each condition as a separate statement. +In contrast, "`width {times} height must: be less than 1024`" is a single +assertion involving multiple parameters. ==== @@ -643,9 +679,12 @@ page; the general model is: name and the short description used in the title of the corresponding ref page: + +-- +[source,asciidoc] ---- - // refBegin name - description +// refBegin name - description ---- +-- + * A paragraph of text introducing the definition of the interface. If the `refBegin` comment does not exist, this paragraph must be @@ -663,9 +702,12 @@ page; the general model is: empty line in the bullet list section^1^, add a `refBody` comment immediately following the bullet list and preceding this section: + +-- +[source,asciidoc] ---- - // refBody name +// refBody name ---- +-- + * The `include` line for the validity statement of commands and structures. @@ -676,9 +718,12 @@ page; the general model is: page. If the validity `include` is not present, this line must be present: + +-- +[source,asciidoc] ---- - // refEnd name [seeAlsoNames]* +// refEnd name [seeAlsoNames]* ---- +-- 1:: The only example of such markup in the 1.0.28 Vulkan Specification diff --git a/doc/specs/vulkan/styleguide.txt b/doc/specs/vulkan/styleguide.txt index 103c0b6a11..38cbd21509 100644 --- a/doc/specs/vulkan/styleguide.txt +++ b/doc/specs/vulkan/styleguide.txt @@ -55,10 +55,9 @@ Vulkan Working Group processes. [[introduction-terminology]] == Terminology -The key words *must*, *must not*, *required*, *shall*, *shall not*, -*should*, *should not*, *recommend*, *may*, and *optional* in this document -are to be interpreted as described in RFC 2119 and by the Vulkan 1.0 -Specification in the "`Terminology`" section. +The key words *must*, *required*, *should*, *recommend*, *may*, and +*optional* in this document are to be interpreted as described in RFC 2119 +and by the Vulkan 1.0 Specification in the "`Terminology`" section. [[introduction-structure]] diff --git a/src/spec/generator.py b/src/spec/generator.py index 709ac14827..e729b171c8 100644 --- a/src/spec/generator.py +++ b/src/spec/generator.py @@ -14,13 +14,14 @@ # See the License for the specific language governing permissions and # limitations under the License. +from __future__ import unicode_literals import io,os,re,sys def write( *args, **kwargs ): - file = kwargs.pop(u'file',sys.stdout) - end = kwargs.pop( u'end',u'\n') - file.write( u' '.join([str(arg) for arg in args]) ) - file.write( end ) + file = kwargs.pop('file',sys.stdout) + end = kwargs.pop('end','\n') + file.write(' '.join([str(arg) for arg in args])) + file.write(end) # noneStr - returns string argument, or "" if argument is None. # Used in converting etree Elements into text. diff --git a/src/spec/vk.xml b/src/spec/vk.xml index 54f57970ce..50cacce372 100644 --- a/src/spec/vk.xml +++ b/src/spec/vk.xml @@ -112,7 +112,7 @@ maintained in the master branch of the Khronos Vulkan GitHub project. // Vulkan 1.0 version number #define VK_API_VERSION_1_0 VK_MAKE_VERSION(1, 0, 0) // Version of this file -#define VK_HEADER_VERSION 43 +#define VK_HEADER_VERSION 44 #define VK_DEFINE_HANDLE(object) typedef struct object##_T* object; @@ -1474,7 +1474,7 @@ maintained in the master branch of the Khronos Vulkan GitHub project. VkStructureType sType - const void* pNext + const void* pNext VkRect2D srcRect VkRect2D dstRect VkBool32 persistent @@ -2108,7 +2108,7 @@ maintained in the master branch of the Khronos Vulkan GitHub project. VkStructureType sType - const void* pNext + const void* pNext uint32_t swapchainCount const uint32_t* pDeviceMasks VkDeviceGroupPresentModeFlagBitsKHX mode @@ -2176,7 +2176,7 @@ maintained in the master branch of the Khronos Vulkan GitHub project. VkStructureType sType - const void* pNext + const void* pNext uint32_t swapchainCount const VkPresentTimeGOOGLE* pTimes @@ -5678,9 +5678,6 @@ maintained in the master branch of the Khronos Vulkan GitHub project. - - - @@ -6061,7 +6058,7 @@ maintained in the master branch of the Khronos Vulkan GitHub project. - + @@ -6209,10 +6206,10 @@ maintained in the master branch of the Khronos Vulkan GitHub project. - + - + @@ -6221,5 +6218,11 @@ maintained in the master branch of the Khronos Vulkan GitHub project. + + + + + + diff --git a/src/vulkan/vulkan.h b/src/vulkan/vulkan.h index aa858752bd..1ac55dfea4 100644 --- a/src/vulkan/vulkan.h +++ b/src/vulkan/vulkan.h @@ -43,7 +43,7 @@ extern "C" { #define VK_VERSION_MINOR(version) (((uint32_t)(version) >> 12) & 0x3ff) #define VK_VERSION_PATCH(version) ((uint32_t)(version) & 0xfff) // Version of this file -#define VK_HEADER_VERSION 43 +#define VK_HEADER_VERSION 44 #define VK_NULL_HANDLE 0 @@ -261,9 +261,6 @@ typedef enum VkStructureType { VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTERNAL_BUFFER_INFO_KHX = 1000071002, VK_STRUCTURE_TYPE_EXTERNAL_BUFFER_PROPERTIES_KHX = 1000071003, VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_ID_PROPERTIES_KHX = 1000071004, - VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PROPERTIES_2_KHX = 1000071005, - VK_STRUCTURE_TYPE_IMAGE_FORMAT_PROPERTIES_2_KHX = 1000071006, - VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_FORMAT_INFO_2_KHX = 1000071007, VK_STRUCTURE_TYPE_EXTERNAL_MEMORY_BUFFER_CREATE_INFO_KHX = 1000072000, VK_STRUCTURE_TYPE_EXTERNAL_MEMORY_IMAGE_CREATE_INFO_KHX = 1000072001, VK_STRUCTURE_TYPE_EXPORT_MEMORY_ALLOCATE_INFO_KHX = 1000072002, @@ -5688,7 +5685,7 @@ VKAPI_ATTR void VKAPI_CALL vkCmdSetDiscardRectangleEXT( #endif #define VK_EXT_hdr_metadata 1 -#define VK_EXT_HDR_METADATA_SPEC_VERSION 0 +#define VK_EXT_HDR_METADATA_SPEC_VERSION 1 #define VK_EXT_HDR_METADATA_EXTENSION_NAME "VK_EXT_hdr_metadata" typedef struct VkXYColorEXT {