C Specification
To record a dispatch using non-zero base values for the components of
WorkgroupId
, call:
// Provided by VK_VERSION_1_1
void vkCmdDispatchBase(
VkCommandBuffer commandBuffer,
uint32_t baseGroupX,
uint32_t baseGroupY,
uint32_t baseGroupZ,
uint32_t groupCountX,
uint32_t groupCountY,
uint32_t groupCountZ);
Parameters
-
commandBuffer
is the command buffer into which the command will be recorded. -
baseGroupX
is the start value for the X component ofWorkgroupId
. -
baseGroupY
is the start value for the Y component ofWorkgroupId
. -
baseGroupZ
is the start value for the Z component ofWorkgroupId
. -
groupCountX
is the number of local workgroups to dispatch in the X dimension. -
groupCountY
is the number of local workgroups to dispatch in the Y dimension. -
groupCountZ
is the number of local workgroups to dispatch in the Z dimension.
Description
When the command is executed, a global workgroup consisting of
groupCountX
× groupCountY
× groupCountZ
local workgroups is assembled, with WorkgroupId
values ranging from
[baseGroup*
, baseGroup*
+ groupCount*
) in each
component.
vkCmdDispatch is equivalent to
vkCmdDispatchBase(0,0,0,groupCountX,groupCountY,groupCountZ)
.
-
VUID-vkCmdDispatchBase-magFilter-04553
If a VkSampler created withmagFilter
orminFilter
equal toVK_FILTER_LINEAR
andcompareEnable
equal toVK_FALSE
is used to sample a VkImageView as a result of this command, then the image view’s format features must containVK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT
-
VUID-vkCmdDispatchBase-mipmapMode-04770
If a VkSampler created withmipmapMode
equal toVK_SAMPLER_MIPMAP_MODE_LINEAR
andcompareEnable
equal toVK_FALSE
is used to sample a VkImageView as a result of this command, then the image view’s format features must containVK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT
-
VUID-vkCmdDispatchBase-aspectMask-06478
If a VkImageView is sampled with depth comparison, the image view must have been created with anaspectMask
that containsVK_IMAGE_ASPECT_DEPTH_BIT
-
VUID-vkCmdDispatchBase-None-02691
If a VkImageView is accessed using atomic operations as a result of this command, then the image view’s format features must containVK_FORMAT_FEATURE_STORAGE_IMAGE_ATOMIC_BIT
-
VUID-vkCmdDispatchBase-None-07888
If aVK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER
descriptor is accessed using atomic operations as a result of this command, then the storage texel buffer’s format features must containVK_FORMAT_FEATURE_STORAGE_TEXEL_BUFFER_ATOMIC_BIT
-
VUID-vkCmdDispatchBase-None-02692
If a VkImageView is sampled withVK_FILTER_CUBIC_EXT
as a result of this command, then the image view’s format features must containVK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_CUBIC_BIT_EXT
-
VUID-vkCmdDispatchBase-None-02693
If the VK_EXT_filter_cubic extension is not enabled and any VkImageView is sampled withVK_FILTER_CUBIC_EXT
as a result of this command, it must not have a VkImageViewType ofVK_IMAGE_VIEW_TYPE_3D
,VK_IMAGE_VIEW_TYPE_CUBE
, orVK_IMAGE_VIEW_TYPE_CUBE_ARRAY
-
VUID-vkCmdDispatchBase-filterCubic-02694
Any VkImageView being sampled withVK_FILTER_CUBIC_EXT
as a result of this command must have a VkImageViewType and format that supports cubic filtering, as specified by VkFilterCubicImageViewImageFormatPropertiesEXT::filterCubic
returned by vkGetPhysicalDeviceImageFormatProperties2 -
VUID-vkCmdDispatchBase-filterCubicMinmax-02695
Any VkImageView being sampled withVK_FILTER_CUBIC_EXT
with a reduction mode of eitherVK_SAMPLER_REDUCTION_MODE_MIN
orVK_SAMPLER_REDUCTION_MODE_MAX
as a result of this command must have a VkImageViewType and format that supports cubic filtering together with minmax filtering, as specified by VkFilterCubicImageViewImageFormatPropertiesEXT::filterCubicMinmax
returned by vkGetPhysicalDeviceImageFormatProperties2 -
VUID-vkCmdDispatchBase-None-08600
For each set n that is statically used by a bound shader, a descriptor set must have been bound to n at the same pipeline bind point, with a VkPipelineLayout that is compatible for set n, with the VkPipelineLayout used to create the current VkPipeline , as described in [descriptorsets-compatibility] -
VUID-vkCmdDispatchBase-None-08601
For each push constant that is statically used by a bound shader, a push constant value must have been set for the same pipeline bind point, with a VkPipelineLayout that is compatible for push constants, with the VkPipelineLayout used to create the current VkPipeline , as described in [descriptorsets-compatibility] -
VUID-vkCmdDispatchBase-None-08114
Descriptors in each bound descriptor set, specified via vkCmdBindDescriptorSets, must be valid as described by descriptor validity if they are statically used by a bound shader -
VUID-vkCmdDispatchBase-None-08606
A valid pipeline must be bound to the pipeline bind point used by this command -
VUID-vkCmdDispatchBase-None-08608
There must not have been any calls to dynamic state setting commands for any state not specified as dynamic in the VkPipeline object bound to the pipeline bind point used by this command, since that pipeline was bound -
VUID-vkCmdDispatchBase-None-08609
If the VkPipeline object bound to the pipeline bind point used by this command accesses a VkSampler object that uses unnormalized coordinates, that sampler must not be used to sample from any VkImage with a VkImageView of the typeVK_IMAGE_VIEW_TYPE_3D
,VK_IMAGE_VIEW_TYPE_CUBE
,VK_IMAGE_VIEW_TYPE_1D_ARRAY
,VK_IMAGE_VIEW_TYPE_2D_ARRAY
orVK_IMAGE_VIEW_TYPE_CUBE_ARRAY
, in any shader stage -
VUID-vkCmdDispatchBase-None-08610
If the VkPipeline object bound to the pipeline bind point used by this command accesses a VkSampler object that uses unnormalized coordinates, that sampler must not be used with any of the SPIR-VOpImageSample*
orOpImageSparseSample*
instructions withImplicitLod
,Dref
orProj
in their name, in any shader stage -
VUID-vkCmdDispatchBase-None-08611
If the VkPipeline object bound to the pipeline bind point used by this command accesses a VkSampler object that uses unnormalized coordinates, that sampler must not be used with any of the SPIR-VOpImageSample*
orOpImageSparseSample*
instructions that includes a LOD bias or any offset values, in any shader stage -
VUID-vkCmdDispatchBase-uniformBuffers-06935
If any stage of the VkPipeline object bound to the pipeline bind point used by this command accesses a uniform buffer, and therobustBufferAccess
feature is not enabled, that stage must not access values outside of the range of the buffer as specified in the descriptor set bound to the same pipeline bind point -
VUID-vkCmdDispatchBase-storageBuffers-06936
If any stage of the VkPipeline object bound to the pipeline bind point used by this command accesses a storage buffer, and therobustBufferAccess
feature is not enabled, that stage must not access values outside of the range of the buffer as specified in the descriptor set bound to the same pipeline bind point -
VUID-vkCmdDispatchBase-commandBuffer-02707
IfcommandBuffer
is an unprotected command buffer andprotectedNoFault
is not supported, any resource accessed by bound shaders must not be a protected resource -
VUID-vkCmdDispatchBase-None-06550
If a bound shader accesses a VkSampler or VkImageView object that enables sampler Y′CBCR conversion, that object must only be used withOpImageSample*
orOpImageSparseSample*
instructions -
VUID-vkCmdDispatchBase-ConstOffset-06551
If a bound shader accesses a VkSampler or VkImageView object that enables sampler Y′CBCR conversion, that object must not use theConstOffset
andOffset
operands -
VUID-vkCmdDispatchBase-viewType-07752
If a VkImageView is accessed as a result of this command, then the image view’sviewType
must match theDim
operand of theOpTypeImage
as described in [textures-operation-validation] -
VUID-vkCmdDispatchBase-format-07753
If a VkImageView is accessed as a result of this command, then the numeric type of the image view’sformat
and theSampled
Type
operand of theOpTypeImage
must match -
VUID-vkCmdDispatchBase-OpImageWrite-08795
If a VkImageView is accessed usingOpImageWrite
as a result of this command, then theType
of theTexel
operand of that instruction must have at least as many components as the image view’s format -
VUID-vkCmdDispatchBase-OpImageWrite-04469
If a VkBufferView is accessed usingOpImageWrite
as a result of this command, then theType
of theTexel
operand of that instruction must have at least as many components as the buffer view’s format -
VUID-vkCmdDispatchBase-SampledType-04470
If a VkImageView with a VkFormat that has a 64-bit component width is accessed as a result of this command, theSampledType
of theOpTypeImage
operand of that instruction must have aWidth
of 64 -
VUID-vkCmdDispatchBase-SampledType-04471
If a VkImageView with a VkFormat that has a component width less than 64-bit is accessed as a result of this command, theSampledType
of theOpTypeImage
operand of that instruction must have aWidth
of 32 -
VUID-vkCmdDispatchBase-SampledType-04472
If a VkBufferView with a VkFormat that has a 64-bit component width is accessed as a result of this command, theSampledType
of theOpTypeImage
operand of that instruction must have aWidth
of 64 -
VUID-vkCmdDispatchBase-SampledType-04473
If a VkBufferView with a VkFormat that has a component width less than 64-bit is accessed as a result of this command, theSampledType
of theOpTypeImage
operand of that instruction must have aWidth
of 32 -
VUID-vkCmdDispatchBase-sparseImageInt64Atomics-04474
If thesparseImageInt64Atomics
feature is not enabled, VkImage objects created with theVK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT
flag must not be accessed by atomic instructions through anOpTypeImage
with aSampledType
with aWidth
of 64 by this command -
VUID-vkCmdDispatchBase-sparseImageInt64Atomics-04475
If thesparseImageInt64Atomics
feature is not enabled, VkBuffer objects created with theVK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT
flag must not be accessed by atomic instructions through anOpTypeImage
with aSampledType
with aWidth
of 64 by this command -
VUID-vkCmdDispatchBase-None-07288
Any shader invocation executed by this command must terminate
-
VUID-vkCmdDispatchBase-commandBuffer-02712
IfcommandBuffer
is a protected command buffer andprotectedNoFault
is not supported, any resource written to by theVkPipeline
object bound to the pipeline bind point used by this command must not be an unprotected resource -
VUID-vkCmdDispatchBase-commandBuffer-02713
IfcommandBuffer
is a protected command buffer andprotectedNoFault
is not supported, pipeline stages other than the framebuffer-space and compute stages in theVkPipeline
object bound to the pipeline bind point used by this command must not write to any resource -
VUID-vkCmdDispatchBase-baseGroupX-00421
baseGroupX
must be less thanVkPhysicalDeviceLimits
::maxComputeWorkGroupCount
[0] -
VUID-vkCmdDispatchBase-baseGroupX-00422
baseGroupY
must be less thanVkPhysicalDeviceLimits
::maxComputeWorkGroupCount
[1] -
VUID-vkCmdDispatchBase-baseGroupZ-00423
baseGroupZ
must be less thanVkPhysicalDeviceLimits
::maxComputeWorkGroupCount
[2] -
VUID-vkCmdDispatchBase-groupCountX-00424
groupCountX
must be less than or equal toVkPhysicalDeviceLimits
::maxComputeWorkGroupCount
[0] minusbaseGroupX
-
VUID-vkCmdDispatchBase-groupCountY-00425
groupCountY
must be less than or equal toVkPhysicalDeviceLimits
::maxComputeWorkGroupCount
[1] minusbaseGroupY
-
VUID-vkCmdDispatchBase-groupCountZ-00426
groupCountZ
must be less than or equal toVkPhysicalDeviceLimits
::maxComputeWorkGroupCount
[2] minusbaseGroupZ
-
VUID-vkCmdDispatchBase-baseGroupX-00427
If any ofbaseGroupX
,baseGroupY
, orbaseGroupZ
are not zero, then the bound compute pipeline must have been created with theVK_PIPELINE_CREATE_DISPATCH_BASE
flag
-
VUID-vkCmdDispatchBase-commandBuffer-parameter
commandBuffer
must be a valid VkCommandBuffer handle -
VUID-vkCmdDispatchBase-commandBuffer-recording
commandBuffer
must be in the recording state -
VUID-vkCmdDispatchBase-commandBuffer-cmdpool
TheVkCommandPool
thatcommandBuffer
was allocated from must support compute operations -
VUID-vkCmdDispatchBase-renderpass
This command must only be called outside of a render pass instance
-
Host access to
commandBuffer
must be externally synchronized -
Host access to the
VkCommandPool
thatcommandBuffer
was allocated from must be externally synchronized
Command Buffer Levels | Render Pass Scope | Supported Queue Types | Command Type |
---|---|---|---|
Primary |
Outside |
Compute |
Action |
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.