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