dispatch.txt
1 // Copyright (c) 2015-2019 Khronos Group. This work is licensed under a 2 // Creative Commons Attribution 4.0 International License; see 3 // http://creativecommons.org/licenses/by/4.0/ 4 5 [[dispatch]] 6 = Dispatching Commands 7 8 _Dispatching commands_ (commands with ftext:Dispatch in the name) provoke 9 work in a compute pipeline. 10 Dispatching commands are recorded into a command buffer and when executed by 11 a queue, will produce work which executes according to the bound compute 12 pipeline. 13 A compute pipeline must: be bound to a command buffer before any dispatch 14 commands are recorded in that command buffer. 15 16 [open,refpage='vkCmdDispatch',desc='Dispatch compute work items',type='protos'] 17 -- 18 :refpage: vkCmdDispatch 19 20 To record a dispatch, call: 21 22 include::{generated}/api/protos/vkCmdDispatch.txt[] 23 24 * pname:commandBuffer is the command buffer into which the command will be 25 recorded. 26 * pname:groupCountX is the number of local workgroups to dispatch in the X 27 dimension. 28 * pname:groupCountY is the number of local workgroups to dispatch in the Y 29 dimension. 30 * pname:groupCountZ is the number of local workgroups to dispatch in the Z 31 dimension. 32 33 When the command is executed, a global workgroup consisting of 34 [eq]#pname:groupCountX {times} pname:groupCountY {times} pname:groupCountZ# 35 local workgroups is assembled. 36 37 .Valid Usage 38 **** 39 include::{chapters}/commonvalidity/draw_dispatch_common.txt[] 40 include::{chapters}/commonvalidity/draw_dispatch_nonindirect_common.txt[] 41 * [[VUID-vkCmdDispatch-groupCountX-00386]] 42 pname:groupCountX must: be less than or equal to 43 sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[0] 44 * [[VUID-vkCmdDispatch-groupCountY-00387]] 45 pname:groupCountY must: be less than or equal to 46 sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[1] 47 * [[VUID-vkCmdDispatch-groupCountZ-00388]] 48 pname:groupCountZ must: be less than or equal to 49 sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[2] 50 **** 51 52 include::{generated}/validity/protos/vkCmdDispatch.txt[] 53 -- 54 55 [open,refpage='vkCmdDispatchIndirect',desc='Dispatch compute work items using indirect parameters',type='protos'] 56 -- 57 :refpage: vkCmdDispatchIndirect 58 59 To record an indirect command dispatch, call: 60 61 include::{generated}/api/protos/vkCmdDispatchIndirect.txt[] 62 63 * pname:commandBuffer is the command buffer into which the command will be 64 recorded. 65 * pname:buffer is the buffer containing dispatch parameters. 66 * pname:offset is the byte offset into pname:buffer where parameters 67 begin. 68 69 fname:vkCmdDispatchIndirect behaves similarly to flink:vkCmdDispatch except 70 that the parameters are read by the device from a buffer during execution. 71 The parameters of the dispatch are encoded in a 72 slink:VkDispatchIndirectCommand structure taken from pname:buffer starting 73 at pname:offset. 74 75 .Valid Usage 76 **** 77 include::{chapters}/commonvalidity/draw_dispatch_common.txt[] 78 include::{chapters}/commonvalidity/draw_dispatch_indirect_common.txt[] 79 * [[VUID-vkCmdDispatchIndirect-offset-00407]] 80 The sum of pname:offset and the size of sname:VkDispatchIndirectCommand 81 must: be less than or equal to the size of pname:buffer 82 **** 83 84 include::{generated}/validity/protos/vkCmdDispatchIndirect.txt[] 85 -- 86 87 [open,refpage='VkDispatchIndirectCommand',desc='Structure specifying a dispatch indirect command',type='structs',xrefs='vkCmdDispatchIndirect'] 88 -- 89 90 The sname:VkDispatchIndirectCommand structure is defined as: 91 92 include::{generated}/api/structs/VkDispatchIndirectCommand.txt[] 93 94 * pname:x is the number of local workgroups to dispatch in the X 95 dimension. 96 * pname:y is the number of local workgroups to dispatch in the Y 97 dimension. 98 * pname:z is the number of local workgroups to dispatch in the Z 99 dimension. 100 101 The members of sname:VkDispatchIndirectCommand have the same meaning as the 102 corresponding parameters of flink:vkCmdDispatch. 103 104 .Valid Usage 105 **** 106 * [[VUID-VkDispatchIndirectCommand-x-00417]] 107 pname:x must: be less than or equal to 108 sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[0] 109 * [[VUID-VkDispatchIndirectCommand-y-00418]] 110 pname:y must: be less than or equal to 111 sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[1] 112 * [[VUID-VkDispatchIndirectCommand-z-00419]] 113 pname:z must: be less than or equal to 114 sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[2] 115 **** 116 117 include::{generated}/validity/structs/VkDispatchIndirectCommand.txt[] 118 119 -- 120 121 ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 122 123 [open,refpage='vkCmdDispatchBase',desc='Dispatch compute work items',type='protos'] 124 -- 125 :refpage: vkCmdDispatchBase 126 127 To record a dispatch using non-zero base values for the components of 128 code:WorkgroupId, call: 129 130 ifdef::VK_VERSION_1_1[] 131 include::{generated}/api/protos/vkCmdDispatchBase.txt[] 132 endif::VK_VERSION_1_1[] 133 134 ifdef::VK_VERSION_1_1+VK_KHR_device_group[or the equivalent command] 135 136 ifdef::VK_KHR_device_group[] 137 include::{generated}/api/protos/vkCmdDispatchBaseKHR.txt[] 138 endif::VK_KHR_device_group[] 139 140 * pname:commandBuffer is the command buffer into which the command will be 141 recorded. 142 * pname:baseGroupX is the start value for the X component of 143 code:WorkgroupId. 144 * pname:baseGroupY is the start value for the Y component of 145 code:WorkgroupId. 146 * pname:baseGroupZ is the start value for the Z component of 147 code:WorkgroupId. 148 * pname:groupCountX is the number of local workgroups to dispatch in the X 149 dimension. 150 * pname:groupCountY is the number of local workgroups to dispatch in the Y 151 dimension. 152 * pname:groupCountZ is the number of local workgroups to dispatch in the Z 153 dimension. 154 155 When the command is executed, a global workgroup consisting of 156 [eq]#pname:groupCountX {times} pname:groupCountY {times} pname:groupCountZ# 157 local workgroups is assembled, with code:WorkgroupId values ranging from 158 [eq]#[ptext:baseGroup*, ptext:baseGroup* {plus} ptext:groupCount*)# in each 159 component. 160 flink:vkCmdDispatch is equivalent to 161 `vkCmdDispatchBase(0,0,0,groupCountX,groupCountY,groupCountZ)`. 162 163 .Valid Usage 164 **** 165 include::{chapters}/commonvalidity/draw_dispatch_common.txt[] 166 * [[VUID-vkCmdDispatchBase-baseGroupX-00421]] 167 pname:baseGroupX must: be less than 168 sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[0] 169 * [[VUID-vkCmdDispatchBase-baseGroupX-00422]] 170 pname:baseGroupX must: be less than 171 sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[1] 172 * [[VUID-vkCmdDispatchBase-baseGroupZ-00423]] 173 pname:baseGroupZ must: be less than 174 sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[2] 175 * [[VUID-vkCmdDispatchBase-groupCountX-00424]] 176 pname:groupCountX must: be less than or equal to 177 sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[0] minus 178 pname:baseGroupX 179 * [[VUID-vkCmdDispatchBase-groupCountY-00425]] 180 pname:groupCountY must: be less than or equal to 181 sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[1] minus 182 pname:baseGroupY 183 * [[VUID-vkCmdDispatchBase-groupCountZ-00426]] 184 pname:groupCountZ must: be less than or equal to 185 sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[2] minus 186 pname:baseGroupZ 187 * [[VUID-vkCmdDispatchBase-baseGroupX-00427]] 188 If any of pname:baseGroupX, pname:baseGroupY, or pname:baseGroupZ are 189 not zero, then the bound compute pipeline must: have been created with 190 the ename:VK_PIPELINE_CREATE_DISPATCH_BASE flag. 191 **** 192 193 include::{generated}/validity/protos/vkCmdDispatchBase.txt[] 194 -- 195 196 endif::VK_VERSION_1_1,VK_KHR_device_group[]