diff --git a/doc/specs/vulkan/Makefile b/doc/specs/vulkan/Makefile index 3a19d459..b53abcbe 100644 --- a/doc/specs/vulkan/Makefile +++ b/doc/specs/vulkan/Makefile @@ -92,7 +92,7 @@ VERBOSE = # $(EXTENSIONS)) # ADOCOPTS options for asciidoc->HTML5 output NOTEOPTS = -a editing-notes -a implementation-guide -SPECREVISION = 1.0.64 +SPECREVISION = 1.0.65 # Spell out ISO 8601 format as not all date commands support --rfc-3339 SPECDATE = $(shell echo `date -u "+%Y-%m-%d %TZ"`) diff --git a/doc/specs/vulkan/appendices/VK_EXT_debug_marker.txt b/doc/specs/vulkan/appendices/VK_EXT_debug_marker.txt index e4476f47..2d792c30 100644 --- a/doc/specs/vulkan/appendices/VK_EXT_debug_marker.txt +++ b/doc/specs/vulkan/appendices/VK_EXT_debug_marker.txt @@ -62,7 +62,7 @@ objects in error messages. PFN_vkDebugMarkerSetObjectNameEXT pfnDebugMarkerSetObjectNameEXT = (PFN_vkDebugMarkerSetObjectNameEXT)vkGetDeviceProcAddr(device, "vkDebugMarkerSetObjectNameEXT"); // Set a name on the image - const VkDeviceCreateInfo imageNameInfo = + const VkDebugMarkerObjectNameInfoEXT imageNameInfo = { VK_STRUCTURE_TYPE_DEBUG_MARKER_OBJECT_NAME_INFO_EXT, // sType NULL, // pNext diff --git a/doc/specs/vulkan/appendices/VK_NV_viewport_swizzle.txt b/doc/specs/vulkan/appendices/VK_NV_viewport_swizzle.txt index e55a05d8..23ea3ec3 100644 --- a/doc/specs/vulkan/appendices/VK_NV_viewport_swizzle.txt +++ b/doc/specs/vulkan/appendices/VK_NV_viewport_swizzle.txt @@ -23,7 +23,8 @@ allows application code to re-orient three-dimensional geometry with a view the "Issues" section below. along any of the *X*, *Y*, or *Z* axes. If a perspective projection and depth buffering is required, [eq]#1/W# -buffering should be used, as described in the single-pass cubemap rendering example in +buffering should be used, as described in the single-pass cubemap rendering +example in === New Object Types diff --git a/doc/specs/vulkan/chapters/VK_KHR_swapchain/wsi.txt b/doc/specs/vulkan/chapters/VK_KHR_swapchain/wsi.txt index d101a154..082fe3b6 100644 --- a/doc/specs/vulkan/chapters/VK_KHR_swapchain/wsi.txt +++ b/doc/specs/vulkan/chapters/VK_KHR_swapchain/wsi.txt @@ -119,8 +119,8 @@ include::../../api/structs/VkSwapchainCreateInfoKHR.txt[] application needs. The implementation will either create the swapchain with at least that many images, or it will fail to create the swapchain. - * pname:imageFormat is a elink:VkFormat value specifying the format - the swapchain image(s) will be created with. + * pname:imageFormat is a elink:VkFormat value specifying the format the + swapchain image(s) will be created with. * pname:imageColorSpace is a slink:VkColorSpaceKHR value specifying the way the swapchain interprets image data. * pname:imageExtent is the size (in pixels) of the swapchain image(s). @@ -170,8 +170,8 @@ is minimized. A swapchain's present mode determines how incoming present requests will be processed and queued internally. * pname:clipped indicates whether the Vulkan implementation is allowed to - discard rendering operations that affect regions of the surface that - are not visible. + discard rendering operations that affect regions of the surface that are + not visible. ** If set to ename:VK_TRUE, the presentable images associated with the swapchain may: not own all of their pixels. Pixels in the presentable images that correspond to regions of the @@ -180,9 +180,8 @@ is minimized. back. Pixel shaders may: not execute for these pixels, and thus any side effects they would have had will not occur. - ename:VK_TRUE value does not guarantee any clipping - will occur, but allows more optimal presentation methods to be used on - some platforms. + ename:VK_TRUE value does not guarantee any clipping will occur, but + allows more optimal presentation methods to be used on some platforms. ** If set to ename:VK_FALSE, presentable images associated with the swapchain will own all of the pixels they contain. @@ -201,16 +200,16 @@ effects that require them to run for all pixels in the presentable image. also allows the application to still present any images that are already acquired from it. -Upon calling fname:vkCreateSwapchainKHR with a pname:oldSwapchain that -is not dlink:VK_NULL_HANDLE, pname:oldSwapchain is retired -- even if -creation of the new swapchain fails. +Upon calling fname:vkCreateSwapchainKHR with a pname:oldSwapchain that is +not dlink:VK_NULL_HANDLE, pname:oldSwapchain is retired -- even if creation +of the new swapchain fails. The new swapchain is created in the non-retired state whether or not pname:oldSwapchain is dlink:VK_NULL_HANDLE. -Upon calling fname:vkCreateSwapchainKHR with a pname:oldSwapchain that -is not dlink:VK_NULL_HANDLE, any images from pname:oldSwapchain that are -not acquired by the application may: be freed by the implementation, -which may: occur even if creation of the new swapchain fails. +Upon calling fname:vkCreateSwapchainKHR with a pname:oldSwapchain that is +not dlink:VK_NULL_HANDLE, any images from pname:oldSwapchain that are not +acquired by the application may: be freed by the implementation, which may: +occur even if creation of the new swapchain fails. The application can: destroy pname:oldSwapchain to free all memory associated with pname:oldSwapchain. diff --git a/doc/specs/vulkan/chapters/clears.txt b/doc/specs/vulkan/chapters/clears.txt index 2a47247f..53499f33 100644 --- a/doc/specs/vulkan/chapters/clears.txt +++ b/doc/specs/vulkan/chapters/clears.txt @@ -88,8 +88,9 @@ endif::VK_KHR_shared_presentable_image[] elements of the pname:pRanges array must: each be less than the pname:mipLevels specified in slink:VkImageCreateInfo when pname:image was created - * For each slink:VkImageSubresourceRange element of pname:pRanges, if - the pname:levelCount member is not ename:VK_REMAINING_MIP_LEVELS, then + * [[VUID-vkCmdClearColorImage-pRanges-01692]] + For each slink:VkImageSubresourceRange element of pname:pRanges, if the + pname:levelCount member is not ename:VK_REMAINING_MIP_LEVELS, then [eq]#pname:baseMipLevel {plus} pname:levelCount# must: be less than the pname:mipLevels specified in slink:VkImageCreateInfo when pname:image was created @@ -98,8 +99,9 @@ endif::VK_KHR_shared_presentable_image[] elements of the pname:pRanges array must: each be less than the pname:arrayLayers specified in slink:VkImageCreateInfo when pname:image was created - * For each slink:VkImageSubresourceRange element of pname:pRanges, if - the pname:layerCount member is not ename:VK_REMAINING_ARRAY_LAYERS, then + * [[VUID-vkCmdClearColorImage-pRanges-01693]] + For each slink:VkImageSubresourceRange element of pname:pRanges, if the + pname:layerCount member is not ename:VK_REMAINING_ARRAY_LAYERS, then [eq]#pname:baseArrayLayer {plus} pname:layerCount# must: be less than the pname:arrayLayers specified in slink:VkImageCreateInfo when pname:image was created @@ -170,8 +172,9 @@ endif::VK_KHR_maintenance1[] elements of the pname:pRanges array must: each be less than the pname:mipLevels specified in slink:VkImageCreateInfo when pname:image was created - * For each slink:VkImageSubresourceRange element of pname:pRanges, if - the pname:levelCount member is not ename:VK_REMAINING_MIP_LEVELS, then + * [[VUID-vkCmdClearDepthStencilImage-pRanges-01694]] + For each slink:VkImageSubresourceRange element of pname:pRanges, if the + pname:levelCount member is not ename:VK_REMAINING_MIP_LEVELS, then [eq]#pname:baseMipLevel {plus} pname:levelCount# must: be less than the pname:mipLevels specified in slink:VkImageCreateInfo when pname:image was created @@ -180,8 +183,9 @@ endif::VK_KHR_maintenance1[] elements of the pname:pRanges array must: each be less than the pname:arrayLayers specified in slink:VkImageCreateInfo when pname:image was created - * For each slink:VkImageSubresourceRange element of pname:pRanges, if - the pname:layerCount member is not ename:VK_REMAINING_ARRAY_LAYERS, then + * [[VUID-vkCmdClearDepthStencilImage-pRanges-01695]] + For each slink:VkImageSubresourceRange element of pname:pRanges, if the + pname:layerCount member is not ename:VK_REMAINING_ARRAY_LAYERS, then [eq]#pname:baseArrayLayer {plus} pname:layerCount# must: be less than the pname:arrayLayers specified in slink:VkImageCreateInfo when pname:image was created diff --git a/doc/specs/vulkan/chapters/copies.txt b/doc/specs/vulkan/chapters/copies.txt index de36b051..a3176939 100644 --- a/doc/specs/vulkan/chapters/copies.txt +++ b/doc/specs/vulkan/chapters/copies.txt @@ -20,15 +20,13 @@ fname:vkCmdResolveImage. == Common Operation -Some rules for valid operation are common to all copy commands: +The following valid usage rules apply to all copy commands: * Copy commands must: be recorded outside of a render pass instance. - * For non-sparse resources, the union of the source regions in a given - buffer or image must: not overlap the union of the destination regions - in the same buffer or image. - * For sparse resources, the set of bytes used by all the source regions - must: not intersect the set of bytes used by all the destination - regions. + * The set of all bytes bound to all the source regions must: not overlap + the set of all bytes bound to the destination regions. + * The set of all bytes bound to each destination region must: not overlap + the set of all bytes bound to another destination region. * Copy regions must: be non-empty. * Regions must: not extend outside the bounds of the buffer or image level, except that regions of compressed images can: extend as far as @@ -436,17 +434,21 @@ ifdef::VK_KHR_sampler_ycbcr_conversion[] endif::VK_KHR_sampler_ycbcr_conversion[] * [[VUID-vkCmdCopyImage-srcImage-00136]] The sample count of pname:srcImage and pname:dstImage must: match - * The pname:srcSubresource.mipLevel member of each element of + * [[VUID-vkCmdCopyImage-srcSubresource-01696]] + The pname:srcSubresource.mipLevel member of each element of pname:pRegions must: be less than the pname:mipLevels specified in slink:VkImageCreateInfo when pname:srcImage was created - * The pname:dstSubresource.mipLevel member of each element of + * [[VUID-vkCmdCopyImage-dstSubresource-01697]] + The pname:dstSubresource.mipLevel member of each element of pname:pRegions must: be less than the pname:mipLevels specified in slink:VkImageCreateInfo when pname:dstImage was created - * The [eq]#pname:srcSubresource.baseArrayLayer {plus} + * [[VUID-vkCmdCopyImage-srcSubresource-01698]] + The [eq]#pname:srcSubresource.baseArrayLayer {plus} pname:srcSubresource.layerCount# of each element of pname:pRegions must: be less than or equal to the pname:arrayLayers specified in slink:VkImageCreateInfo when pname:srcImage was created - * The [eq]#pname:dstSubresource.baseArrayLayer {plus} + * [[VUID-vkCmdCopyImage-dstSubresource-01699]] + The [eq]#pname:dstSubresource.baseArrayLayer {plus} pname:dstSubresource.layerCount# of each element of pname:pRegions must: be less than or equal to the pname:arrayLayers specified in slink:VkImageCreateInfo when pname:dstImage was created @@ -718,7 +720,8 @@ include::../api/structs/VkImageSubresourceLayers.txt[] ename:VK_IMAGE_ASPECT_STENCIL_BIT * [[VUID-VkImageSubresourceLayers-aspectMask-00168]] pname:aspectMask must: not contain ename:VK_IMAGE_ASPECT_METADATA_BIT - * pname:layerCount must: be greater than 0 + * [[VUID-VkImageSubresourceLayers-layerCount-01700]] + pname:layerCount must: be greater than 0 **** include::../validity/structs/VkImageSubresourceLayers.txt[] @@ -826,10 +829,12 @@ ifdef::VK_KHR_shared_presentable_image[] ename:VK_IMAGE_LAYOUT_GENERAL, or ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR endif::VK_KHR_shared_presentable_image[] - * The pname:imageSubresource.mipLevel member of each element of + * [[VUID-vkCmdCopyBufferToImage-imageSubresource-01701]] + The pname:imageSubresource.mipLevel member of each element of pname:pRegions must: be less than the pname:mipLevels specified in slink:VkImageCreateInfo when pname:dstImage was created - * The [eq]#pname:imageSubresource.baseArrayLayer {plus} + * [[VUID-vkCmdCopyBufferToImage-imageSubresource-01702]] + The [eq]#pname:imageSubresource.baseArrayLayer {plus} pname:imageSubresource.layerCount# of each element of pname:pRegions must: be less than or equal to the pname:arrayLayers specified in slink:VkImageCreateInfo when pname:dstImage was created @@ -934,10 +939,12 @@ endif::VK_KHR_shared_presentable_image[] * [[VUID-vkCmdCopyImageToBuffer-dstBuffer-00192]] If pname:dstBuffer is non-sparse then it must: be bound completely and contiguously to a single sname:VkDeviceMemory object - * The pname:imageSubresource.mipLevel member of each element of + * [[VUID-vkCmdCopyImageToBuffer-imageSubresource-01703]] + The pname:imageSubresource.mipLevel member of each element of pname:pRegions must: be less than the pname:mipLevels specified in slink:VkImageCreateInfo when pname:srcImage was created - * The [eq]#pname:imageSubresource.baseArrayLayer {plus} + * [[VUID-vkCmdCopyImageToBuffer-imageSubresource-01704]] + The [eq]#pname:imageSubresource.baseArrayLayer {plus} pname:imageSubresource.layerCount# of each element of pname:pRegions must: be less than or equal to the pname:arrayLayers specified in slink:VkImageCreateInfo when pname:srcImage was created @@ -1472,17 +1479,21 @@ ifdef::VK_IMG_filter_cubic[] If pname:filter is ename:VK_FILTER_CUBIC_IMG, pname:srcImage must: have a elink:VkImageType of ename:VK_IMAGE_TYPE_3D endif::VK_IMG_filter_cubic[] - * The pname:srcSubresource.mipLevel member of each element of + * [[VUID-vkCmdBlitImage-srcSubresource-01705]] + The pname:srcSubresource.mipLevel member of each element of pname:pRegions must: be less than the pname:mipLevels specified in slink:VkImageCreateInfo when pname:srcImage was created - * The pname:dstSubresource.mipLevel member of each element of + * [[VUID-vkCmdBlitImage-dstSubresource-01706]] + The pname:dstSubresource.mipLevel member of each element of pname:pRegions must: be less than the pname:mipLevels specified in slink:VkImageCreateInfo when pname:dstImage was created - * The [eq]#pname:srcSubresource.baseArrayLayer {plus} + * [[VUID-vkCmdBlitImage-srcSubresource-01707]] + The [eq]#pname:srcSubresource.baseArrayLayer {plus} pname:srcSubresource.layerCount# of each element of pname:pRegions must: be less than or equal to the pname:arrayLayers specified in slink:VkImageCreateInfo when pname:srcImage was created - * The [eq]#pname:dstSubresource.baseArrayLayer {plus} + * [[VUID-vkCmdBlitImage-dstSubresource-01708]] + The [eq]#pname:dstSubresource.baseArrayLayer {plus} pname:dstSubresource.layerCount# of each element of pname:pRegions must: be less than or equal to the pname:arrayLayers specified in slink:VkImageCreateInfo when pname:dstImage was created @@ -1686,17 +1697,21 @@ endif::VK_KHR_shared_presentable_image[] * [[VUID-vkCmdResolveImage-srcImage-01386]] pname:srcImage and pname:dstImage must: have been created with the same image format - * The pname:srcSubresource.mipLevel member of each element of + * [[VUID-vkCmdResolveImage-srcSubresource-01709]] + The pname:srcSubresource.mipLevel member of each element of pname:pRegions must: be less than the pname:mipLevels specified in slink:VkImageCreateInfo when pname:srcImage was created - * The pname:dstSubresource.mipLevel member of each element of + * [[VUID-vkCmdResolveImage-dstSubresource-01710]] + The pname:dstSubresource.mipLevel member of each element of pname:pRegions must: be less than the pname:mipLevels specified in slink:VkImageCreateInfo when pname:dstImage was created - * The [eq]#pname:srcSubresource.baseArrayLayer {plus} + * [[VUID-vkCmdResolveImage-srcSubresource-01711]] + The [eq]#pname:srcSubresource.baseArrayLayer {plus} pname:srcSubresource.layerCount# of each element of pname:pRegions must: be less than or equal to the pname:arrayLayers specified in slink:VkImageCreateInfo when pname:srcImage was created - * The [eq]#pname:dstSubresource.baseArrayLayer {plus} + * [[VUID-vkCmdResolveImage-dstSubresource-01712]] + The [eq]#pname:dstSubresource.baseArrayLayer {plus} pname:dstSubresource.layerCount# of each element of pname:pRegions must: be less than or equal to the pname:arrayLayers specified in slink:VkImageCreateInfo when pname:dstImage was created diff --git a/doc/specs/vulkan/chapters/descriptorsets.txt b/doc/specs/vulkan/chapters/descriptorsets.txt index 42d04941..913e341f 100644 --- a/doc/specs/vulkan/chapters/descriptorsets.txt +++ b/doc/specs/vulkan/chapters/descriptorsets.txt @@ -1535,8 +1535,6 @@ include::../api/protos/vkAllocateDescriptorSets.txt[] allocation. * pname:pDescriptorSets is a pointer to an array of sname:VkDescriptorSet handles in which the resulting descriptor set objects are returned. - The array must: be at least the length specified by the - pname:descriptorSetCount member of pname:pAllocateInfo. The allocated descriptor sets are returned in pname:pDescriptorSets. @@ -1555,6 +1553,16 @@ This means applications need not populate unused entries with dummy descriptors. ifdef::VK_KHR_maintenance1[] +If a call to fname:vkAllocateDescriptorSets would cause the total number of +descriptor sets allocated from the pool to exceed the value of +slink:VkDescriptorPoolCreateInfo::pname:maxSets used to create +pname:pAllocateInfo->pname:descriptorPool, then the allocation may: fail due +to lack of space in the descriptor pool. +Similarly, the allocation may: fail due to lack of space if the call to +fname:vkAllocateDescriptorSets would cause the number of any given +descriptor type to exceed the sum of all the pname:descriptorCount members +of each element of slink:VkDescriptorPoolCreateInfo::pname:pPoolSizes with a +pname:member equal to that type. If the allocation fails due to no more space in the descriptor pool, and not because of system or device memory exhaustion, then ename:VK_ERROR_OUT_OF_POOL_MEMORY_KHR must: be returned. diff --git a/doc/specs/vulkan/chapters/features.txt b/doc/specs/vulkan/chapters/features.txt index d8538b04..4e04fcd9 100644 --- a/doc/specs/vulkan/chapters/features.txt +++ b/doc/specs/vulkan/chapters/features.txt @@ -210,13 +210,20 @@ used. ** Out-of-bounds atomics may: modify values within the memory range(s) bound to the buffer, but must: not modify any other memory, and return an undefined value. - ** Vertex input attributes are considered out of bounds if the address of - the attribute plus the size of the attribute is greater than the size - of the bound buffer. - Further, if any vertex input attribute using a specific vertex input - binding is out of bounds, then all vertex input attributes using that - vertex input binding for that vertex shader invocation are considered - out of bounds. + ** Vertex input attributes are considered out of bounds if the offset of + the attribute in the bound vertex buffer range plus the size of the + attribute is greater than either: ++ + *** code:vertexBufferRangeSize, if [eq]#code:bindingStride == 0#; or + *** [eq]#(code:vertexBufferRangeSize - (code:vertexBufferRangeSize % + code:bindingStride))# ++ +where code:vertexBufferRangeSize is the byte size of the memory range bound +to the vertex buffer binding and code:bindingStride is the byte stride of +the corresponding vertex input binding. +Further, if any vertex input attribute using a specific vertex input binding +is out of bounds, then all vertex input attributes using that vertex input +binding for that vertex shader invocation are considered out of bounds. *** If a vertex input attribute is out of bounds, it will be assigned one of the following values: **** Values from anywhere within the memory range(s) bound to the buffer, @@ -372,8 +379,8 @@ used. must: be 0. * [[features-features-samplerAnisotropy]] pname:samplerAnisotropy indicates whether anisotropic filtering is supported. - If this feature is not enabled, the pname:maxAnisotropy member of the - sname:VkSamplerCreateInfo structure must: be 1.0. + If this feature is not enabled, the pname:anisotropyEnable member of the + sname:VkSamplerCreateInfo structure must: be ename:VK_FALSE. * [[features-features-textureCompressionETC2]] pname:textureCompressionETC2 indicates whether all of the ETC2 and EAC compressed texture formats are supported. diff --git a/doc/specs/vulkan/chapters/fundamentals.txt b/doc/specs/vulkan/chapters/fundamentals.txt index cd3698a3..90164f76 100644 --- a/doc/specs/vulkan/chapters/fundamentals.txt +++ b/doc/specs/vulkan/chapters/fundamentals.txt @@ -673,8 +673,24 @@ core layer to an application using the API incorrectly is undefined, and may: include program termination. However, implementations must: ensure that incorrect usage by an application does not affect the integrity of the operating system, the Vulkan -implementation, or other Vulkan client applications in the system, and does -not allow one application to access data belonging to another application. +implementation, or other Vulkan client applications in the system. +In particular, any guarantees made by an operating system about whether +memory from one process can: be visible to another process or not must: not +be violated by a Vulkan implementation for *any memory allocation*. +Vulkan implementations are not required: to make additional security or +integrity guarantees beyond those provided by the OS unless explicitly +directed by the application's use of a particular feature or extension (e.g. +via <>). + +[NOTE] +.Note +==== +For instance, if an operating system guarantees that data in all its memory +allocations are set to zero when newly allocated, the Vulkan implementation +must: make the same guarantees for any allocations it controls (e.g. +slink:VkDeviceMemory). +==== + Applications can: request stronger robustness guarantees by enabling the pname:robustBufferAccess feature as described in <>. diff --git a/doc/specs/vulkan/chapters/fxvertex.txt b/doc/specs/vulkan/chapters/fxvertex.txt index 010220ee..262e7605 100644 --- a/doc/specs/vulkan/chapters/fxvertex.txt +++ b/doc/specs/vulkan/chapters/fxvertex.txt @@ -451,11 +451,11 @@ include::../validity/protos/vkCmdBindVertexBuffers.txt[] The address of each attribute for each code:vertexIndex and code:instanceIndex is calculated as follows: - * Let attribDesc be the member of + * Let code:attribDesc be the member of sname:VkPipelineVertexInputStateCreateInfo::pname:pVertexAttributeDescriptions with sname:VkVertexInputAttributeDescription::pname:location equal to the vertex input attribute number. - * Let bindingDesc be the member of + * Let code:bindingDesc be the member of sname:VkPipelineVertexInputStateCreateInfo::pname:pVertexBindingDescriptions with sname:VkVertexInputAttributeDescription::pname:binding equal to attribDesc.binding. diff --git a/doc/specs/vulkan/chapters/interfaces.txt b/doc/specs/vulkan/chapters/interfaces.txt index 90687bc9..e612807e 100644 --- a/doc/specs/vulkan/chapters/interfaces.txt +++ b/doc/specs/vulkan/chapters/interfaces.txt @@ -1174,8 +1174,8 @@ The variable decorated with code:FragStencilRefEXT must: be declared as a scalar integer value. Only the least significant *s* bits of the integer value of the variable decorated with code:FragStencilRefEXT are considered for stencil testing, -where *s* is the number of bits in the stencil framebuffer attachment, -and higher order bits are discarded. +where *s* is the number of bits in the stencil framebuffer attachment, and +higher order bits are discarded. endif::VK_EXT_shader_stencil_export[] diff --git a/doc/specs/vulkan/chapters/memory.txt b/doc/specs/vulkan/chapters/memory.txt index d2dd2b9a..68e968ff 100644 --- a/doc/specs/vulkan/chapters/memory.txt +++ b/doc/specs/vulkan/chapters/memory.txt @@ -446,9 +446,9 @@ endif::VK_EXT_validation_cache[] [[memory-device]] == Device Memory -_Device memory_ is memory that is visible to the device -- for example -the contents of the image or buffer objects, which can: be natively used by -the device. +_Device memory_ is memory that is visible to the device -- for example the +contents of the image or buffer objects, which can: be natively used by the +device. Memory properties of a physical device describe the memory heaps and memory types available. @@ -569,14 +569,12 @@ There is no ordering requirement between *X* and *Y* elements for the case their pname:propertyFlags members are not in a subset relation. That potentially allows more than one possible way to order the same set of memory types. -Notice that the -<> -is written in the required order. -But if instead -ename:VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT was before +Notice that the <> is written in the required order. +But if instead ename:VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT was before ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | -ename:VK_MEMORY_PROPERTY_HOST_COHERENT_BIT, -the list would still be in the required order. +ename:VK_MEMORY_PROPERTY_HOST_COHERENT_BIT, the list would still be in the +required order. ==== This ordering requirement enables applications to use a simple search loop @@ -805,12 +803,14 @@ the error ename:VK_ERROR_OUT_OF_DEVICE_MEMORY must: be returned. .Valid Usage **** - * pname:pAllocateInfo\->pname:allocationSize must: be less than or equal + * [[VUID-vkAllocateMemory-pAllocateInfo-01713]] + pname:pAllocateInfo\->pname:allocationSize must: be less than or equal to slink:VkPhysicalDeviceMemoryProperties::pname:memoryHeaps[pname:pAllocateInfo\->pname:memoryTypeIndex].pname:size as returned by flink:vkGetPhysicalDeviceMemoryProperties for the slink:VkPhysicalDevice that pname:device was created from. - * pname:pAllocateInfo\->pname:memoryTypeIndex must: be less than + * [[VUID-vkAllocateMemory-pAllocateInfo-01714]] + pname:pAllocateInfo\->pname:memoryTypeIndex must: be less than slink:VkPhysicalDeviceMemoryProperties::pname:memoryTypeCount as returned by flink:vkGetPhysicalDeviceMemoryProperties for the slink:VkPhysicalDevice that pname:device was created from. @@ -1631,8 +1631,8 @@ include::../api/protos/vkFreeMemory.txt[] <> chapter. Before freeing a memory object, an application must: ensure the memory -object is no longer in use by the device--for example by command buffers -in the _pending state_. +object is no longer in use by the device--for example by command buffers in +the _pending state_. The memory can: remain bound to images or buffers at the time the memory object is freed, but any further use of them (on host or device) for anything other than destroying those objects will result in undefined diff --git a/doc/specs/vulkan/chapters/pipelines.txt b/doc/specs/vulkan/chapters/pipelines.txt index 51214103..9c5958e5 100644 --- a/doc/specs/vulkan/chapters/pipelines.txt +++ b/doc/specs/vulkan/chapters/pipelines.txt @@ -772,12 +772,13 @@ endif::VK_KHR_maintenance2[] that is used by the pipeline must: be less than or equal to sname:VkPhysicalDeviceLimits::pname:maxPerStageResources ifdef::VK_NV_clip_space_w_scaling[] - * If no element of the pname:pDynamicStates member of pname:pDynamicState + * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-01715]] + If no element of the pname:pDynamicStates member of pname:pDynamicState is ename:VK_DYNAMIC_STATE_VIEWPORT_W_SCALING_NV, and the pname:viewportWScalingEnable member of a slink:VkPipelineViewportWScalingStateCreateInfoNV structure, chained to - the pname:pNext chain of pname:pViewportState, is ename:VK_TRUE, - the pname:pViewportWScalings member of the + the pname:pNext chain of pname:pViewportState, is ename:VK_TRUE, the + pname:pViewportWScalings member of the slink:VkPipelineViewportWScalingStateCreateInfoNV must: be a pointer to an array of slink:VkPipelineViewportWScalingStateCreateInfoNV::pname:viewportCount diff --git a/doc/specs/vulkan/chapters/renderpass.txt b/doc/specs/vulkan/chapters/renderpass.txt index 97e25bf2..90b6cc2a 100644 --- a/doc/specs/vulkan/chapters/renderpass.txt +++ b/doc/specs/vulkan/chapters/renderpass.txt @@ -1458,16 +1458,20 @@ ifdef::VK_KHX_multiview[] used. endif::VK_KHX_multiview[] -Image subresources used as attachments must: not be accessed in any other -way for the duration of a render pass instance. +Applications must: ensure that all accesses to memory that backs image +subresources used as attachments in a given renderpass instance either +happen-before the <> for those +attachments, or happen-after the <> for those attachments. + ifdef::VK_KHR_maintenance2[] -For depth/stencil attachments, they can: be used as both attachments and -non-attachments as long as the layout of the image subresource is -ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL_KHR and the -non-attachment usage only accesses the depth aspect, or the layout of the -image subresource is -ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL_KHR and the -non-attachment usage only accesses the stencil aspect. +For depth/stencil attachments, each aspect can: be used separately as +attachments and non-attachments as long as the non-attachment accesses are +also via an image subresource in either the +ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL_KHR layout +or the ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL_KHR +layout, and the attachment resource uses whichever of those two layouts the +image accesses do not. Use of non-attachment aspects in this case is only well defined if the attachment is used in the subpass where the non-attachment access is being made, or the layout of the image subresource is constant throughout the diff --git a/doc/specs/vulkan/chapters/resources.txt b/doc/specs/vulkan/chapters/resources.txt index af9622b6..8fe1ff50 100644 --- a/doc/specs/vulkan/chapters/resources.txt +++ b/doc/specs/vulkan/chapters/resources.txt @@ -1343,10 +1343,12 @@ image. * [[VUID-vkGetImageSubresourceLayout-aspectMask-00997]] The pname:aspectMask member of pname:pSubresource must: only have a single bit set - * The pname:mipLevel member of pname:pSubresource must: be less than the + * [[VUID-vkGetImageSubresourceLayout-mipLevel-01716]] + The pname:mipLevel member of pname:pSubresource must: be less than the pname:mipLevels specified in slink:VkImageCreateInfo when pname:image was created - * The pname:arrayLayer member of pname:pSubresource must: be less than the + * [[VUID-vkGetImageSubresourceLayout-arrayLayer-01717]] + The pname:arrayLayer member of pname:pSubresource must: be less than the pname:arrayLayers specified in slink:VkImageCreateInfo when pname:image was created ifdef::VK_KHR_sampler_ycbcr_conversion[] @@ -2142,18 +2144,19 @@ endif::VK_KHR_maintenance1[] pname:subresourceRange.baseMipLevel must: be less than the pname:mipLevels specified in slink:VkImageCreateInfo when pname:image was created - * If pname:subresourceRange.levelCount is not - ename:VK_REMAINING_MIP_LEVELS, - [eq]#pname:subresourceRange.baseMipLevel {plus} - pname:subresourceRange.levelCount# must: be less than or equal to the - pname:mipLevels specified in slink:VkImageCreateInfo when pname:image - was created + * [[VUID-VkImageViewCreateInfo-subresourceRange-01718]] + If pname:subresourceRange.levelCount is not + ename:VK_REMAINING_MIP_LEVELS, [eq]#pname:subresourceRange.baseMipLevel + {plus} pname:subresourceRange.levelCount# must: be less than or equal to + the pname:mipLevels specified in slink:VkImageCreateInfo when + pname:image was created ifndef::VK_KHR_maintenance1[] * [[VUID-VkImageViewCreateInfo-subresourceRange-01480]] pname:subresourceRange.baseArrayLayer must: be less than the pname:arrayLayers specified in slink:VkImageCreateInfo when pname:image was created - * If pname:subresourceRange.layerCount is not + * [[VUID-VkImageViewCreateInfo-subresourceRange-01719]] + If pname:subresourceRange.layerCount is not ename:VK_REMAINING_ARRAY_LAYERS, [eq]#pname:subresourceRange.baseArrayLayer {plus} pname:subresourceRange.layerCount# must: be less than or equal to the @@ -2417,10 +2420,12 @@ endif::VK_KHR_sampler_ycbcr_conversion[] .Valid Usage **** - * If pname:levelCount is not ename:VK_REMAINING_MIP_LEVELS, it must: - be greater than `0` - * If pname:layerCount is not ename:VK_REMAINING_ARRAY_LAYERS, it must: - be greater than `0` + * [[VUID-VkImageSubresourceRange-levelCount-01720]] + If pname:levelCount is not ename:VK_REMAINING_MIP_LEVELS, it must: be + greater than `0` + * [[VUID-VkImageSubresourceRange-layerCount-01721]] + If pname:layerCount is not ename:VK_REMAINING_ARRAY_LAYERS, it must: be + greater than `0` * [[VUID-VkImageSubresourceRange-aspectMask-01670]] If pname:aspectMask includes ename:VK_IMAGE_ASPECT_COLOR_BIT, then it must: not include any of ename:VK_IMAGE_ASPECT_PLANE_0_BIT_KHR, diff --git a/doc/specs/vulkan/chapters/samplers.txt b/doc/specs/vulkan/chapters/samplers.txt index 072968d1..a58d32ef 100644 --- a/doc/specs/vulkan/chapters/samplers.txt +++ b/doc/specs/vulkan/chapters/samplers.txt @@ -68,7 +68,10 @@ include::../api/structs/VkSamplerCreateInfo.txt[] enable anisotropic filtering, as described in the <> section, or ename:VK_FALSE otherwise. - * pname:maxAnisotropy is the anisotropy value clamp. + * pname:maxAnisotropy is the anisotropy value clamp used by the sampler + when pname:anisotropyEnable is ename:VK_TRUE. + If pname:anisotropyEnable is ename:VK_FALSE, pname:maxAnisotropy is + ignored. * pname:compareEnable is ename:VK_TRUE to enable comparison against a reference value during lookups, or ename:VK_FALSE otherwise. ** Note: Some implementations will default to shader state if this member diff --git a/doc/specs/vulkan/chapters/sparsemem.txt b/doc/specs/vulkan/chapters/sparsemem.txt index 7890d063..0441dabd 100644 --- a/doc/specs/vulkan/chapters/sparsemem.txt +++ b/doc/specs/vulkan/chapters/sparsemem.txt @@ -131,7 +131,7 @@ ename:VK_BUFFER_CREATE_SPARSE_BINDING_BIT bits can: be thought of as a linear region of address space. In the sname:VkImage case if ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT is not used, this linear region is entirely opaque, meaning that there is no -application-visible mapping between pixel location and memory offset. +application-visible mapping between texel location and memory offset. Unless ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT or ename:VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT are also used, the entire @@ -180,7 +180,7 @@ Applications can: use these types of images to control LOD based on total memory consumption. If memory pressure becomes an issue the application can: unbind and disable specific mipmap levels of images without having to recreate resources or -modify pixel data of unaffected levels. +modify texel data of unaffected levels. The application can: also use this functionality to access subregions of the image in a "`megatexture`" fashion. @@ -282,7 +282,7 @@ image::images/sparseimage.svg[align="center", title="Sparse Image"] In the absence of ename:VK_SPARSE_IMAGE_FORMAT_ALIGNED_MIP_SIZE_BIT and ename:VK_SPARSE_IMAGE_FORMAT_SINGLE_MIPTAIL_BIT, each array layer contains a -mip tail region containing pixel data for all mip levels smaller than the +mip tail region containing texel data for all mip levels smaller than the sparse image block in any dimension. Mip levels that are as large or larger than a sparse image block in all @@ -305,7 +305,8 @@ image::images/sparseimage_alignedmipsize.svg[align="center", title="Sparse Image The mip tail regions are presented here in 2D arrays simply for figure size reasons. Each mip tail is logically a single array of sparse blocks with an -implementation-dependent mapping of pixels to sparse blocks. +implementation-dependent mapping of texels or compressed texel blocks to +sparse blocks. ==== When ename:VK_SPARSE_IMAGE_FORMAT_ALIGNED_MIP_SIZE_BIT is present the first @@ -324,7 +325,8 @@ image::images/sparseimage_alignedmipsize_singlemiptail.svg[align="center", title The mip tail region is presented here in a 2D array simply for figure size reasons. It is logically a single array of sparse blocks with an -implementation-dependent mapping of pixels to sparse blocks. +implementation-dependent mapping of texels or compressed texel blocks to +sparse blocks. ==== When both ename:VK_SPARSE_IMAGE_FORMAT_ALIGNED_MIP_SIZE_BIT and @@ -337,13 +339,14 @@ from each of these flags are in effect. Standard sparse image block shapes define a standard set of dimensions for sparse image blocks that depend on the format of the image. -Layout of pixels within a sparse image block is implementation dependent. +Layout of texels or compressed texel blocks within a sparse image block is +implementation dependent. All currently defined standard sparse image block shapes are 64 KB in size. For block-compressed formats (e.g. ename:VK_FORMAT_BC5_UNORM_BLOCK), the -pixel size is the size of the compressed texel block (128-bit for etext:BC5) -thus the dimensions of the standard sparse image block shapes apply in terms -of compressed texel blocks. +texel size is the size of the compressed texel block (e.g. 128-bit for +etext:BC5) thus the dimensions of the standard sparse image block shapes +apply in terms of compressed texel blocks. [NOTE] .Note @@ -359,7 +362,7 @@ dimensions by the compressed texel block dimensions. .Standard Sparse Image Block Shapes (Single Sample) [options="header"] |==== -| PIXEL SIZE (bits) | Block Shape (2D) | Block Shape (3D) +| TEXEL SIZE (bits) | Block Shape (2D) | Block Shape (3D) | *8-Bit* | 256 {times} 256 {times} 1 | 64 {times} 32 {times} 32 | *16-Bit* | 256 {times} 128 {times} 1 | 32 {times} 32 {times} 32 | *32-Bit* | 128 {times} 128 {times} 1 | 32 {times} 32 {times} 16 @@ -371,7 +374,7 @@ dimensions by the compressed texel block dimensions. .Standard Sparse Image Block Shapes (MSAA) [options="header"] |==== -| PIXEL SIZE (bits)| Block Shape (2X) | Block Shape (4X) | Block Shape (8X) | Block Shape (16X) +| TEXEL SIZE (bits)| Block Shape (2X) | Block Shape (4X) | Block Shape (8X) | Block Shape (16X) | *8-Bit* | 128 {times} 256 {times} 1 | 128 {times} 128 {times} 1 | 64 {times} 128 {times} 1 | 64 {times} 64 {times} 1 | *16-Bit* | 128 {times} 128 {times} 1 | 128 {times} 64 {times} 1 | 64 {times} 64 {times} 1 | 64 {times} 32 {times} 1 | *32-Bit* | 64 {times} 128 {times} 1 | 64 {times} 64 {times} 1 | 32 {times} 64 {times} 1 | 32 {times} 32 {times} 1 @@ -436,14 +439,15 @@ image::images/sparseimage_multiaspect.svg[align="center",title="Multiple Aspect The mip tail regions are presented here in 2D arrays simply for figure size reasons. Each mip tail is logically a single array of sparse blocks with an -implementation-dependent mapping of pixels to sparse blocks. +implementation-dependent mapping of texels or compressed texel blocks to +sparse blocks. ==== In the figure above the depth, stencil, and metadata aspects all have unique sparse properties. -The per-pixel stencil data is [eq]#{onequarter}# the size of the depth data, +The per-texel stencil data is [eq]#{onequarter}# the size of the depth data, hence the stencil sparse blocks include [eq]#4 {times}# the number of -pixels. +texels. The sparse block size in bytes for all of the aspects is identical and defined by sname:VkMemoryRequirements::pname:alignment. @@ -610,7 +614,7 @@ If the application always uses sname:VkSparseImageMemoryBindInfo to bind memory for the non-tail mip levels, any holes that are present in the resource size may: never be bound. -Since sname:VkSparseImageMemoryBindInfo uses pixel locations to determine +Since sname:VkSparseImageMemoryBindInfo uses texel locations to determine which device virtual addresses to bind, it is impossible to bind device virtual address holes with this operation. ==== @@ -808,7 +812,7 @@ include::../api/enums/VkSparseImageFormatFlagBits.txt[] * ename:VK_SPARSE_IMAGE_FORMAT_NONSTANDARD_BLOCK_SIZE_BIT specifies that the image uses non-standard sparse image block dimensions, and the pname:imageGranularity values do not match the standard sparse image - block dimensions for the given pixel format. + block dimensions for the given format. -- @@ -829,7 +833,7 @@ include::../api/protos/vkGetPhysicalDeviceSparseImageFormatProperties.txt[] sparse image capabilities. * pname:format is the image format. * pname:type is the dimensionality of image. - * pname:samples is the number of samples per pixel as defined in + * pname:samples is the number of samples per texel as defined in elink:VkSampleCountFlagBits. * pname:usage is a bitmask describing the intended usage of the image. * pname:tiling is the tiling arrangement of the data elements in memory. @@ -919,7 +923,7 @@ include::../api/structs/VkPhysicalDeviceSparseImageFormatInfo2KHR.txt[] * pname:pNext is `NULL` or a pointer to an extension-specific structure. * pname:format is the image format. * pname:type is the dimensionality of image. - * pname:samples is the number of samples per pixel as defined in + * pname:samples is the number of samples per texel as defined in elink:VkSampleCountFlagBits. * pname:usage is a bitmask describing the intended usage of the image. * pname:tiling is the tiling arrangement of the data elements in memory. @@ -1038,9 +1042,9 @@ include::../api/structs/VkSparseImageMemoryRequirements.txt[] ename:VK_IMAGE_ASPECT_DEPTH_BIT and ename:VK_IMAGE_ASPECT_STENCIL_BIT would be present. * pname:formatProperties.imageGranularity describes the dimensions of a - single bindable sparse image block in pixel units. + single bindable sparse image block in texel units. For aspect ename:VK_IMAGE_ASPECT_METADATA_BIT, all dimensions will be - zero pixels. + zero. All metadata is located in the mip tail region. * pname:formatProperties.flags is a bitmask of elink:VkSparseImageFormatFlagBits: @@ -1054,7 +1058,7 @@ include::../api/structs/VkSparseImageMemoryRequirements.txt[] image uses non-standard sparse image block dimensions. The pname:formatProperties.imageGranularity values do not match the standard sparse image block dimension corresponding to the image's - pixel format. + format. * pname:imageMipTailFirstLod is the first mip level at which image subresources are included in the mip tail region. * pname:imageMipTailSize is the memory size (in bytes) of the mip tail @@ -1392,10 +1396,12 @@ include::../api/structs/VkSparseImageMemoryBindInfo.txt[] .Valid Usage **** - * The pname:subresource.mipLevel member of each element of pname:pBinds + * [[VUID-VkSparseImageMemoryBindInfo-subresource-01722]] + The pname:subresource.mipLevel member of each element of pname:pBinds must: be less than the pname:mipLevels specified in slink:VkImageCreateInfo when pname:image was created - * The pname:subresource.arrayLayer member of each element of pname:pBinds + * [[VUID-VkSparseImageMemoryBindInfo-subresource-01723]] + The pname:subresource.arrayLayer member of each element of pname:pBinds must: be less than the pname:arrayLayers specified in slink:VkImageCreateInfo when pname:image was created **** diff --git a/doc/specs/vulkan/chapters/synchronization.txt b/doc/specs/vulkan/chapters/synchronization.txt index c581d2c6..b2383278 100644 --- a/doc/specs/vulkan/chapters/synchronization.txt +++ b/doc/specs/vulkan/chapters/synchronization.txt @@ -3788,17 +3788,18 @@ endif::VK_KHR_external_memory[] pname:subresourceRange.baseMipLevel must: be less than the pname:mipLevels specified in slink:VkImageCreateInfo when pname:image was created - * If pname:subresourceRange.levelCount is not - ename:VK_REMAINING_MIP_LEVELS, - [eq]#pname:subresourceRange.baseMipLevel {plus} - pname:subresourceRange.levelCount# must: be less than or equal to the - pname:mipLevels specified in slink:VkImageCreateInfo when pname:image - was created + * [[VUID-VkImageMemoryBarrier-subresourceRange-01724]] + If pname:subresourceRange.levelCount is not + ename:VK_REMAINING_MIP_LEVELS, [eq]#pname:subresourceRange.baseMipLevel + {plus} pname:subresourceRange.levelCount# must: be less than or equal to + the pname:mipLevels specified in slink:VkImageCreateInfo when + pname:image was created * [[VUID-VkImageMemoryBarrier-subresourceRange-01488]] pname:subresourceRange.baseArrayLayer must: be less than the pname:arrayLayers specified in slink:VkImageCreateInfo when pname:image was created - * If pname:subresourceRange.layerCount is not + * [[VUID-VkImageMemoryBarrier-subresourceRange-01725]] + If pname:subresourceRange.layerCount is not ename:VK_REMAINING_ARRAY_LAYERS, [eq]#pname:subresourceRange.baseArrayLayer {plus} pname:subresourceRange.layerCount# must: be less than or equal to the diff --git a/doc/specs/vulkan/chapters/textures.txt b/doc/specs/vulkan/chapters/textures.txt index ea228ef3..f29965de 100644 --- a/doc/specs/vulkan/chapters/textures.txt +++ b/doc/specs/vulkan/chapters/textures.txt @@ -1922,6 +1922,41 @@ offsets [eq]#({DeltaUpper}~i~, {DeltaUpper}~j~, {DeltaUpper}~k~)# are added to [eq]#(i,j,k)# components of the integer texel coordinates. +[[textures-integer-coordinate-operations]] +== Integer Texel Coordinate Operations + +ifdef::VK_AMD_shader_image_load_store_lod[] +Integer texel coordinate operations may: supply a LOD which texels are to be +read from or written to using the optional SPIR-V operand code:Lod. +endif::VK_AMD_shader_image_load_store_lod[] +ifndef::VK_AMD_shader_image_load_store_lod[] +The code:OpImageFetch and code:OpImageFetchSparse SPIR-V instructions may: +supply a LOD from which texels are to be fetched using the optional SPIR-V +operand code:Lod. +Other integer-coordinate operations must: not. +endif::VK_AMD_shader_image_load_store_lod[] +If the code:Lod is provided then it must: be an integer. + +The image level selected is: +[latexmath] +++++++++++++++++++++++++ +\begin{aligned} +d & = level_{base} + + \begin{cases} + Lod & \text{(from optional SPIR-V operand)} \\ + 0 & \text{otherwise} + \end{cases} \\ +\end{aligned} +++++++++++++++++++++++++ + +If [eq]#d# does not lie in the range [eq]#[pname:baseMipLevel, +pname:baseMipLevel {plus} pname:levelCount)# then any values fetched are +ifndef::VK_AMD_shader_image_load_store_lod[undefined.] +ifdef::VK_AMD_shader_image_load_store_lod[] +undefined, and any writes are discarded. +endif::VK_AMD_shader_image_load_store_lod[] + + [[textures-sample-operations]] == Image Sample Operations diff --git a/doc/specs/vulkan/chapters/vertexpostproc.txt b/doc/specs/vulkan/chapters/vertexpostproc.txt index c2494fb1..8295366e 100644 --- a/doc/specs/vulkan/chapters/vertexpostproc.txt +++ b/doc/specs/vulkan/chapters/vertexpostproc.txt @@ -495,7 +495,8 @@ include::../api/structs/VkPipelineViewportStateCreateInfo.txt[] * [[VUID-VkPipelineViewportStateCreateInfo-scissorCount-01220]] pname:scissorCount and pname:viewportCount must: be identical ifdef::VK_NV_clip_space_w_scaling[] - * If the pname:viewportWScalingEnable member of a + * [[VUID-VkPipelineViewportStateCreateInfo-viewportWScalingEnable-01726]] + If the pname:viewportWScalingEnable member of a slink:VkPipelineViewportWScalingStateCreateInfoNV structure chained to the pname:pNext chain is ename:VK_TRUE, the pname:viewportCount member of the slink:VkPipelineViewportWScalingStateCreateInfoNV structure must: diff --git a/doc/specs/vulkan/reflow_count.py b/doc/specs/vulkan/reflow_count.py index 5461e6d9..20b97f75 100644 --- a/doc/specs/vulkan/reflow_count.py +++ b/doc/specs/vulkan/reflow_count.py @@ -1,2 +1,2 @@ # The value to start tagging VU statements at, unless overridden by -nextvu -startVUID = 1690 +startVUID = 1727 diff --git a/doc/specs/vulkan/style/writing.txt b/doc/specs/vulkan/style/writing.txt index fd6f1178..10941d37 100644 --- a/doc/specs/vulkan/style/writing.txt +++ b/doc/specs/vulkan/style/writing.txt @@ -715,7 +715,8 @@ endif::editing-notes[] [source,asciidoc,subs=attributes+] ---- * pname:flags is a bitmask indicating usage behavior for the pool and - command buffers allocated from it. Bits which can: be set include: + command buffers allocated from it. + Bits which can: be set include: + {blank}-- // refBegin VkCommandPoolCreateFlagBits - Bitmask specifying usage behavior for a command pool @@ -790,6 +791,11 @@ statements are not self-contained. This would make it impossible to extract semantically meaningful descriptions for each assigned <>. +Be clear on the distinction between a "`valid pointer`" and a "`pointer to a +valid object`" when writing Valid Usage statements. +See the "`Valid Usage`" section of the Vulkan Specification, and +particularly the "`Valid Usage for Pointers`" section. + Explicit Valid Usage statements must be assigned Valid Usage ID tags before publication. This process is described in the <> @@ -874,17 +880,20 @@ Attributes which can be set on the block are: (command, structure, enumerant, handle, etc.) name. This attribute is required. * *desc* - short description / summary of the page, used in the page - title. This attribute is required. + title. + This attribute is required. * *type* - type of the interface, which must match the directory name following `api/` in the interface `include::` line within the block, and must be one of `basetypes`, `defines`, `enums`, `flags`, `funcpointers`, - `handles`, `protos`, or `structs`. This attribute is required. + `handles`, `protos`, or `structs`. + This attribute is required. * *xrefs* - list of whitespace-separated names of other reference pages - which should be added to the `See Also` section of this page. Most - cross-references are automatically generated based on the immediate + which should be added to the `See Also` section of this page. + Most cross-references are automatically generated based on the immediate dependency information in `vk.xml`, but in some cases, such as referring between `*FlagBits` and `*Flags` types, this additional tagging is - useful. This attribute is optional. + useful. + This attribute is optional. Attributes of the open block must be written in this format, using single quotes as delimiters (even though asciidoc markup also allows double @@ -896,8 +905,8 @@ After the open block is started, the following markup should be provided: * A single paragraph of text describing the definition of the interface. This paragraph is optional, but strongly recommended. * The `include` line for the interface, which must be consistent with the - page name and type in the open block attributes. This paragraph is - required. + page name and type in the open block attributes. + This paragraph is required. * A bullet list describing function parameters, structure members, enumerants in an enumerated type, etc. This list should contain no empty lines, as the extraction script @@ -917,8 +926,9 @@ After the open block is started, the following markup should be provided: // refBody ---- + - * An explicit Valid Usage block. This block is required if the interface - has such Valid Usage constraints. + * An explicit Valid Usage block. + This block is required if the interface has such Valid Usage + constraints. * The `include` line for the implicit valid usage block. This line is required for for commands and structures, but not for interfaces such as enumerated types, which do not have implicit valid diff --git a/doc/specs/vulkan/styleguide.txt b/doc/specs/vulkan/styleguide.txt index aeca3c54..be6eb56f 100644 --- a/doc/specs/vulkan/styleguide.txt +++ b/doc/specs/vulkan/styleguide.txt @@ -157,6 +157,10 @@ include::style/vuid.txt[] = Revision History +* 2017-10-27 - Add language about proper use of "`valid pointer`" and + "`pointer to valid object`" for valid usage statements, in the + <> section (related to public + pull request 547). * 2017-10-15 - Describe how to write <> (internal issue 908). * 2017-10-15 - Add more details of <// Vulkan 1.0 version number #define VK_API_VERSION_1_0 VK_MAKE_VERSION(1, 0, 0)// Patch version should always be set to 0 // Version of this file -#define VK_HEADER_VERSION 64 +#define VK_HEADER_VERSION 65 #define VK_DEFINE_HANDLE(object) typedef struct object##_T* object; diff --git a/src/vulkan/vulkan.h b/src/vulkan/vulkan.h index 048866c4..8e21042a 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 64 +#define VK_HEADER_VERSION 65 #define VK_NULL_HANDLE 0