1// Copyright 2023-2024 The Khronos Group Inc. 2// SPDX-License-Identifier: CC-BY-4.0 3 4= Proposal Template 5:toc: left 6:refpage: https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/ 7:sectnums: 8 9This proposal details and addresses the issues solved by the `VK_KHR_maintenance6` extension. 10 11== Problem Statement 12 13Over time, a collection of minor features, none of which would warrant an 14entire extension of their own, requires the creation of a maintenance 15extension. 16 17The following is a list of issues considered in this proposal: 18 19 * `vkBindBufferMemory2` and `vkBindImageMemory2` accept arrays of memory 20 binding parameters, but the commands only return a single `VkResult` value. 21 This makes it impossible to identify which specific memory binding operation 22 failed, and leaves resources in an indeterminate, unusable state. 23 * Add a property to describe if an implementation clamps the inputs to 24 fragment shading rate combiner operations. 25 * There are some use cases where an index buffer must be bound, even if it is 26 not used, and the specification currently forbids the use of 27 `VK_NULL_HANDLE`. 28 * Need a `maxCombinedImageSamplerDescriptorCount` value, for cases where 29 you need to create a descriptor set layout, but do not know which 30 formats will be used (and therefore cannot query it). 31 * Creating image views with ename:VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT 32 and multiple layers is supported by all modern hardware, so this should be exposed 33 by the API. 34 * `pNext` extensible *2 versions of all descriptor binding commands. 35 36== Proposal 37 38=== New features 39 40The following features are exposed: 41 42[source,c] 43---- 44typedef struct VkPhysicalDeviceMaintenance6FeaturesKHR { 45 VkStructureType sType; 46 void* pNext; 47 VkBool32 maintenance6; 48} VkPhysicalDeviceMaintenance6FeaturesKHR; 49---- 50 51 * The `maintenance6` feature indicates support for the `VK_KHR_maintenance6` extension. 52 53=== New properties 54 55The following device properties are exposed: 56 57[source,c] 58---- 59typedef struct VkPhysicalDeviceMaintenance6PropertiesKHR { 60 VkStructureType sType; 61 void* pNext; 62 VkBool32 blockTexelViewCompatibleMultipleLayers; 63 uint32_t maxCombinedImageSamplerDescriptorCount; 64 VkBool32 fragmentShadingRateClampCombinerInputs; 65} VkPhysicalDeviceMaintenance6PropertiesKHR; 66---- 67 68 * The `blockTexelViewCompatibleMultipleLayers` property indicates whether a `VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT` 69 can be used with a `layerCount` of greater than `1`. 70 * The `maxCombinedImageSamplerDescriptorCount` property indicates the maximum number of descriptors needed for any of the multi-planar formats 71 supported by the implementation that require `YCbCr` conversion . 72 * The `fragmentShadingRateClampCombinerInputs` property indicates if an implementation clamps the inputs to fragment shading rate combiner operations. 73 74=== New binding status structure 75 76[source,c] 77---- 78typedef struct VkBindMemoryStatusKHR { 79 VkStructureType sType; 80 const void* pNext; 81 VkResult* pResult; 82} VkBindMemoryStatusKHR; 83---- 84 85The `VkBindMemoryStatusKHR` structure can be included in the `pNext` chain of `VkBindBufferMemoryInfo` and 86`VkBindImageMemoryInfo`, allowing applications to retrieve `VkResult` values for individual memory binding operations. 87 88=== New index buffer binding functionality 89 90`VK_NULL_HANDLE` can now be used in index buffer binding functions, in place 91of a valid `VkBuffer` handle. When the `nullDescriptor` feature is enabled, 92every index fetched results in a value of zero. 93 94 95=== New functions 96 97The following new functions are added in order to support future extensibility: 98 99[source,c] 100---- 101typedef struct VkBindDescriptorSetsInfoKHR { 102 VkStructureType sType; 103 const void* pNext; 104 VkShaderStageFlags stageFlags; 105 VkPipelineLayout layout; 106 uint32_t firstSet; 107 uint32_t descriptorSetCount; 108 const VkDescriptorSet* pDescriptorSets; 109 uint32_t dynamicOffsetCount; 110 const uint32_t* pDynamicOffsets; 111} VkBindDescriptorSetsInfoKHR; 112 113typedef struct VkPushConstantsInfoKHR { 114 VkStructureType sType; 115 const void* pNext; 116 VkPipelineLayout layout; 117 VkShaderStageFlags stageFlags; 118 uint32_t offset; 119 uint32_t size; 120 const void* pValues; 121} VkPushConstantsInfoKHR; 122 123typedef struct VkPushDescriptorSetInfoKHR { 124 VkStructureType sType; 125 const void* pNext; 126 VkShaderStageFlags stageFlags; 127 VkPipelineLayout layout; 128 uint32_t set; 129 uint32_t descriptorWriteCount; 130 const VkWriteDescriptorSet* pDescriptorWrites; 131} VkPushDescriptorSetInfoKHR; 132 133typedef struct VkPushDescriptorSetWithTemplateInfoKHR { 134 VkStructureType sType; 135 const void* pNext; 136 VkDescriptorUpdateTemplate descriptorUpdateTemplate; 137 VkPipelineLayout layout; 138 uint32_t set; 139 const void* pData; 140} VkPushDescriptorSetWithTemplateInfoKHR; 141 142typedef struct VkSetDescriptorBufferOffsetsInfoEXT { 143 VkStructureType sType; 144 const void* pNext; 145 VkShaderStageFlags stageFlags; 146 VkPipelineLayout layout; 147 uint32_t firstSet; 148 uint32_t setCount; 149 const uint32_t* pBufferIndices; 150 const VkDeviceSize* pOffsets; 151} VkSetDescriptorBufferOffsetsInfoEXT; 152 153typedef struct VkBindDescriptorBufferEmbeddedSamplersInfoEXT { 154 VkStructureType sType; 155 const void* pNext; 156 VkShaderStageFlags stageFlags; 157 VkPipelineLayout layout; 158 uint32_t set; 159} VkBindDescriptorBufferEmbeddedSamplersInfoEXT; 160 161void vkCmdBindDescriptorSets2KHR( 162 VkCommandBuffer commandBuffer, 163 const VkBindDescriptorSetsInfoKHR* pBindDescriptorSetsInfo); 164 165void vkCmdPushConstants2KHR( 166 VkCommandBuffer commandBuffer, 167 const VkPushConstantsInfoKHR* pPushConstantsInfo); 168 169void vkCmdPushDescriptorSet2KHR( 170 VkCommandBuffer commandBuffer, 171 const VkPushDescriptorSetInfoKHR* pPushDescriptorSetInfo); 172 173void vkCmdPushDescriptorSetWithTemplate2KHR( 174 VkCommandBuffer commandBuffer, 175 const VkPushDescriptorSetWithTemplateInfoKHR* pPushDescriptorSetWithTemplateInfo); 176 177void vkCmdSetDescriptorBufferOffsets2EXT( 178 VkCommandBuffer commandBuffer, 179 const VkSetDescriptorBufferOffsetsInfoEXT* pSetDescriptorBufferOffsetsInfo); 180 181void vkCmdBindDescriptorBufferEmbeddedSamplers2EXT( 182 VkCommandBuffer commandBuffer, 183 const VkBindDescriptorBufferEmbeddedSamplersInfoEXT* pBindDescriptorBufferEmbeddedSamplersInfo); 184---- 185 186The parameters of the structures are identical to the arguments of the 187existing functions, except that `VkPipelineBindPoint` is replaced with 188`VkShaderStageFlagBits`. 189 190== Issues 191 192None. 193 194 195== Further Functionality 196 197None. 198