1// Copyright (c) 2019-2020 NVIDIA Corporation 2// 3// SPDX-License-Identifier: CC-BY-4.0 4 5== Indirect Commands Generation And Execution 6 7[open,refpage='vkGetGeneratedCommandsMemoryRequirementsNV',desc='Retrieve the buffer allocation requirements for generated commands',type='protos'] 8-- 9The generation of commands on the device requires a `preprocess` buffer. 10To retrieve the memory size and alignment requirements of a particular 11execution state call: 12 13include::{generated}/api/protos/vkGetGeneratedCommandsMemoryRequirementsNV.txt[] 14 15 * pname:device is the logical device that owns the buffer. 16 * pname:pInfo is a pointer to a 17 sname:VkGeneratedCommandsMemoryRequirementsInfoNV structure containing 18 parameters required for the memory requirements query. 19 * pname:pMemoryRequirements is a pointer to a slink:VkMemoryRequirements2 20 structure in which the memory requirements of the buffer object are 21 returned. 22 23.Valid Usage 24**** 25 * [[VUID-vkGetGeneratedCommandsMemoryRequirementsNV-deviceGeneratedCommands-02906]] 26 The <<features-deviceGeneratedCommands, 27 sname:VkPhysicalDeviceDeviceGeneratedCommandsFeaturesNV::pname:deviceGeneratedCommands>> 28 feature must: be enabled 29**** 30 31include::{generated}/validity/protos/vkGetGeneratedCommandsMemoryRequirementsNV.txt[] 32-- 33 34[open,refpage='VkGeneratedCommandsMemoryRequirementsInfoNV',desc='Structure specifying parameters for the reservation of preprocess buffer space',type='structs'] 35-- 36include::{generated}/api/structs/VkGeneratedCommandsMemoryRequirementsInfoNV.txt[] 37 38 * pname:sType is the type of this structure. 39 * pname:pNext is `NULL` or a pointer to a structure extending this 40 structure. 41 * pname:pipelineBindPoint is the elink:VkPipelineBindPoint of the 42 pname:pipeline that this buffer memory is intended to be used with 43 during the execution. 44 * pname:pipeline is the slink:VkPipeline that this buffer memory is 45 intended to be used with during the execution. 46 * pname:indirectCommandsLayout is the slink:VkIndirectCommandsLayoutNV 47 that this buffer memory is intended to be used with. 48 * pname:maxSequencesCount is the maximum number of sequences that this 49 buffer memory in combination with the other state provided can: be used 50 with. 51 52.Valid Usage 53**** 54 * [[VUID-VkGeneratedCommandsMemoryRequirementsInfoNV-maxSequencesCount-02907]] 55 pname:maxSequencesCount must: be less or equal to 56 slink:VkPhysicalDeviceDeviceGeneratedCommandsPropertiesNV::pname:maxIndirectSequenceCount 57**** 58 59include::{generated}/validity/structs/VkGeneratedCommandsMemoryRequirementsInfoNV.txt[] 60-- 61 62[open,refpage='vkCmdExecuteGeneratedCommandsNV',desc='Generate and execute commands on the device',type='protos'] 63-- 64:refpage: vkCmdExecuteGeneratedCommandsNV 65 66The actual generation of commands as well as their execution on the device 67is handled as single action with: 68 69include::{generated}/api/protos/vkCmdExecuteGeneratedCommandsNV.txt[] 70 71 * pname:commandBuffer is the command buffer into which the command is 72 recorded. 73 * pname:isPreprocessed represents whether the input data has already been 74 preprocessed on the device. 75 If it is ename:VK_FALSE this command will implicitly trigger the 76 preprocessing step, otherwise not. 77 * pname:pGeneratedCommandsInfo is a pointer to a 78 slink:VkGeneratedCommandsInfoNV structure containing parameters 79 affecting the generation of commands. 80 81.Valid Usage 82**** 83include::{chapters}/commonvalidity/draw_common.txt[] 84include::{chapters}/commonvalidity/draw_vertex_binding.txt[] 85ifdef::VK_VERSION_1_1[] 86 * [[VUID-vkCmdExecuteGeneratedCommandsNV-commandBuffer-02970]] 87 pname:commandBuffer must: not be a protected command buffer 88endif::VK_VERSION_1_1[] 89 * [[VUID-vkCmdExecuteGeneratedCommandsNV-isPreprocessed-02908]] 90 If pname:isPreprocessed is ename:VK_TRUE then 91 flink:vkCmdPreprocessGeneratedCommandsNV must: have already been 92 executed on the device, using the same pname:pGeneratedCommandsInfo 93 content as well as the content of the input buffers it references (all 94 except slink:VkGeneratedCommandsInfoNV::pname:preprocessBuffer). 95 Furthermore pname:pGeneratedCommandsInfo`s pname:indirectCommandsLayout 96 must: have been created with the 97 ename:VK_INDIRECT_COMMANDS_LAYOUT_USAGE_EXPLICIT_PREPROCESS_BIT_NV bit 98 set 99 * [[VUID-vkCmdExecuteGeneratedCommandsNV-pipeline-02909]] 100 sname:VkGeneratedCommandsInfoNV::pname:pipeline must: match the current 101 bound pipeline at 102 sname:VkGeneratedCommandsInfoNV::pname:pipelineBindPoint 103ifdef::VK_EXT_transform_feedback[] 104 * [[VUID-vkCmdExecuteGeneratedCommandsNV-None-02910]] 105 Transform feedback must: not be active 106endif::VK_EXT_transform_feedback[] 107 * [[VUID-vkCmdExecuteGeneratedCommandsNV-deviceGeneratedCommands-02911]] 108 The <<features-deviceGeneratedCommands, 109 sname:VkPhysicalDeviceDeviceGeneratedCommandsFeaturesNV::pname:deviceGeneratedCommands>> 110 feature must: be enabled 111**** 112 113include::{generated}/validity/protos/vkCmdExecuteGeneratedCommandsNV.txt[] 114-- 115 116[open,refpage='VkGeneratedCommandsInfoNV',desc='Structure specifying parameters for the generation of commands',type='structs'] 117-- 118include::{generated}/api/structs/VkGeneratedCommandsInfoNV.txt[] 119 120 * pname:sType is the type of this structure. 121 * pname:pNext is `NULL` or a pointer to a structure extending this 122 structure. 123 * pname:pipelineBindPoint is the elink:VkPipelineBindPoint used for the 124 pname:pipeline. 125 * pname:pipeline is the slink:VkPipeline used in the generation and 126 execution process. 127 * pname:indirectCommandsLayout is the slink:VkIndirectCommandsLayoutNV 128 that provides the command sequence to generate. 129 * pname:streamCount defines the number of input streams 130 * pname:pStreams is a pointer to an array of pname:streamCount 131 slink:VkIndirectCommandsStreamNV structures providing the input data for 132 the tokens used in pname:indirectCommandsLayout. 133 * pname:sequencesCount is the maximum number of sequences to reserve. 134 If pname:sequencesCountBuffer is dlink:VK_NULL_HANDLE, this is also the 135 actual number of sequences generated. 136 * pname:preprocessBuffer is the slink:VkBuffer that is used for 137 preprocessing the input data for execution. 138 If this structure is used with flink:vkCmdExecuteGeneratedCommandsNV 139 with its pname:isPreprocessed set to `VK_TRUE`, then the preprocessing 140 step is skipped and data is only read from this buffer. 141 * pname:preprocessOffset is the byte offset into pname:preprocessBuffer 142 where the preprocessed data is stored. 143 * pname:preprocessSize is the maximum byte size within the 144 pname:preprocessBuffer after the pname:preprocessOffset that is 145 available for preprocessing. 146 * pname:sequencesCountBuffer is a sname:VkBuffer in which the actual 147 number of sequences is provided as single code:uint32_t value. 148 * pname:sequencesCountOffset is the byte offset into 149 pname:sequencesCountBuffer where the count value is stored. 150 * pname:sequencesIndexBuffer is a sname:VkBuffer that encodes the used 151 sequence indices as code:uint32_t array. 152 * pname:sequencesIndexOffset is the byte offset into 153 pname:sequencesIndexBuffer where the index values start. 154 155.Valid Usage 156**** 157 * [[VUID-VkGeneratedCommandsInfoNV-pipeline-02912]] 158 The provided pname:pipeline must: match the pipeline bound at execution 159 time 160 * [[VUID-VkGeneratedCommandsInfoNV-indirectCommandsLayout-02913]] 161 If the pname:indirectCommandsLayout uses a token of 162 ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_SHADER_GROUP_NV, then the 163 pname:pipeline must: have been created with multiple shader groups 164 * [[VUID-VkGeneratedCommandsInfoNV-indirectCommandsLayout-02914]] 165 If the pname:indirectCommandsLayout uses a token of 166 ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_SHADER_GROUP_NV, then the 167 pname:pipeline must: have been created with 168 ename:VK_PIPELINE_CREATE_INDIRECT_BINDABLE_BIT_NV set in 169 sname:VkGraphicsPipelineCreateInfo::pname:flags 170 * [[VUID-VkGeneratedCommandsInfoNV-indirectCommandsLayout-02915]] 171 If the pname:indirectCommandsLayout uses a token of 172 ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_CONSTANT_NV, then the 173 pname:pipeline`s sname:VkPipelineLayout must: match the 174 slink:VkIndirectCommandsLayoutTokenNV::pname:pushconstantPipelineLayout 175 * [[VUID-VkGeneratedCommandsInfoNV-streamCount-02916]] 176 pname:streamCount must: match the pname:indirectCommandsLayout's 177 pname:streamCount 178 * [[VUID-VkGeneratedCommandsInfoNV-sequencesCount-02917]] 179 pname:sequencesCount must: be less or equal to 180 slink:VkPhysicalDeviceDeviceGeneratedCommandsPropertiesNV::pname:maxIndirectSequenceCount 181 and 182 slink:VkGeneratedCommandsMemoryRequirementsInfoNV::pname:maxSequencesCount 183 that was used to determine the pname:preprocessSize 184 * [[VUID-VkGeneratedCommandsInfoNV-preprocessBuffer-02918]] 185 pname:preprocessBuffer must: have the 186 ename:VK_BUFFER_USAGE_INDIRECT_BUFFER_BIT bit set in its usage flag 187 * [[VUID-VkGeneratedCommandsInfoNV-preprocessOffset-02919]] 188 pname:preprocessOffset must: be aligned to 189 slink:VkPhysicalDeviceDeviceGeneratedCommandsPropertiesNV::pname:minIndirectCommandsBufferOffsetAlignment 190 * [[VUID-VkGeneratedCommandsInfoNV-preprocessBuffer-02971]] 191 If pname:preprocessBuffer is non-sparse then it must: be bound 192 completely and contiguously to a single sname:VkDeviceMemory object 193 * [[VUID-VkGeneratedCommandsInfoNV-preprocessSize-02920]] 194 pname:preprocessSize must: be at least equal to the memory requirement`s 195 size returned by flink:vkGetGeneratedCommandsMemoryRequirementsNV using 196 the matching inputs (pname:indirectCommandsLayout, ...) as within this 197 structure 198 * [[VUID-VkGeneratedCommandsInfoNV-sequencesCountBuffer-02921]] 199 pname:sequencesCountBuffer can: be set if the actual used count of 200 sequences is sourced from the provided buffer. 201 In that case the pname:sequencesCount serves as upper bound 202 * [[VUID-VkGeneratedCommandsInfoNV-sequencesCountBuffer-02922]] 203 If pname:sequencesCountBuffer is not dlink:VK_NULL_HANDLE, its usage 204 flag must: have the ename:VK_BUFFER_USAGE_INDIRECT_BUFFER_BIT bit set 205 * [[VUID-VkGeneratedCommandsInfoNV-sequencesCountBuffer-02923]] 206 If pname:sequencesCountBuffer is not dlink:VK_NULL_HANDLE, 207 pname:sequencesCountOffset must: be aligned to 208 sname:VkPhysicalDeviceDeviceGeneratedCommandsPropertiesNV::pname:minSequencesCountBufferOffsetAlignment 209 * [[VUID-VkGeneratedCommandsInfoNV-sequencesCountBuffer-02972]] 210 If pname:sequencesCountBuffer is not dlink:VK_NULL_HANDLE and is 211 non-sparse then it must: be bound completely and contiguously to a 212 single sname:VkDeviceMemory object 213 * [[VUID-VkGeneratedCommandsInfoNV-sequencesIndexBuffer-02924]] 214 If pname:indirectCommandsLayout's 215 ename:VK_INDIRECT_COMMANDS_LAYOUT_USAGE_INDEXED_SEQUENCES_BIT_NV is set, 216 pname:sequencesIndexBuffer must: be set otherwise it must: be 217 dlink:VK_NULL_HANDLE 218 * [[VUID-VkGeneratedCommandsInfoNV-sequencesIndexBuffer-02925]] 219 If pname:sequencesIndexBuffer is not dlink:VK_NULL_HANDLE, its usage 220 flag must: have the ename:VK_BUFFER_USAGE_INDIRECT_BUFFER_BIT bit set 221 * [[VUID-VkGeneratedCommandsInfoNV-sequencesIndexBuffer-02926]] 222 If pname:sequencesIndexBuffer is not dlink:VK_NULL_HANDLE, 223 pname:sequencesIndexOffset must: be aligned to 224 sname:VkPhysicalDeviceDeviceGeneratedCommandsPropertiesNV::pname:minSequencesIndexBufferOffsetAlignment 225 * [[VUID-VkGeneratedCommandsInfoNV-sequencesIndexBuffer-02973]] 226 If pname:sequencesIndexBuffer is not dlink:VK_NULL_HANDLE and is 227 non-sparse then it must: be bound completely and contiguously to a 228 single sname:VkDeviceMemory object 229**** 230 231include::{generated}/validity/structs/VkGeneratedCommandsInfoNV.txt[] 232-- 233 234Referencing the functions defined in <<indirectmdslayout>>, 235fname:vkCmdExecuteGeneratedCommandsNV behaves as: 236 237[source,c] 238--------------------------------------------------- 239uint32_t sequencesCount = sequencesCountBuffer ? 240 min(maxSequencesCount, sequencesCountBuffer.load_uint32(sequencesCountOffset) : 241 maxSequencesCount; 242 243 244cmdProcessAllSequences(commandBuffer, pipeline, 245 indirectCommandsLayout, pIndirectCommandsStreams, 246 sequencesCount, 247 sequencesIndexBuffer, sequencesIndexOffset); 248 249// The stateful commands within indirectCommandsLayout will not 250// affect the state of subsequent commands in the target 251// command buffer (cmd) 252--------------------------------------------------- 253 254[NOTE] 255.Note 256==== 257It is important to note that the values of all state related to the 258pname:pipelineBindPoint used are undefined: after this command. 259==== 260 261[open,refpage='vkCmdPreprocessGeneratedCommandsNV',desc='Performs preprocessing for generated commands',type='protos'] 262-- 263Commands can: be preprocessed prior execution using the following command: 264 265include::{generated}/api/protos/vkCmdPreprocessGeneratedCommandsNV.txt[] 266 267 * pname:commandBuffer is the command buffer which does the preprocessing. 268 * pname:pGeneratedCommandsInfo is a pointer to a 269 slink:VkGeneratedCommandsInfoNV structure containing parameters 270 affecting the preprocessing step. 271 272.Valid Usage 273**** 274ifdef::VK_VERSION_1_1[] 275 * [[VUID-vkCmdPreprocessGeneratedCommandsNV-commandBuffer-02974]] 276 pname:commandBuffer must: not be a protected command buffer 277endif::VK_VERSION_1_1[] 278 * [[VUID-vkCmdPreprocessGeneratedCommandsNV-pGeneratedCommandsInfo-02927]] 279 pname:pGeneratedCommandsInfo`s pname:indirectCommandsLayout must: have 280 been created with the 281 ename:VK_INDIRECT_COMMANDS_LAYOUT_USAGE_EXPLICIT_PREPROCESS_BIT_NV bit 282 set 283 * [[VUID-vkCmdPreprocessGeneratedCommandsNV-deviceGeneratedCommands-02928]] 284 The <<features-deviceGeneratedCommands, 285 sname:VkPhysicalDeviceDeviceGeneratedCommandsFeaturesNV::pname:deviceGeneratedCommands>> 286 feature must: be enabled 287**** 288 289include::{generated}/validity/protos/vkCmdPreprocessGeneratedCommandsNV.txt[] 290-- 291 292