vkCmdDispatch(3)

C Specification

To record a dispatch, call:

// Provided by VK_VERSION_1_0
void vkCmdDispatch(
    VkCommandBuffer                             commandBuffer,
    uint32_t                                    groupCountX,
    uint32_t                                    groupCountY,
    uint32_t                                    groupCountZ);

Parameters

commandBuffer is the command buffer into which the command will be recorded.
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.

Valid Usage

VUID-vkCmdDispatch-magFilter-04553
If a VkSampler created with magFilter or minFilter equal to VK_FILTER_LINEAR, reductionMode equal to VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE, and compareEnable equal to VK_FALSE is used to sample a VkImageView as a result of this command, then the image view’s format features must contain VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT
VUID-vkCmdDispatch-magFilter-09598
If a VkSampler created with magFilter or minFilter equal to VK_FILTER_LINEAR and reductionMode equal to either VK_SAMPLER_REDUCTION_MODE_MIN or VK_SAMPLER_REDUCTION_MODE_MAX is used to sample a VkImageView as a result of this command, then the image view’s format features must contain VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_MINMAX_BIT
VUID-vkCmdDispatch-mipmapMode-04770
If a VkSampler created with mipmapMode equal to VK_SAMPLER_MIPMAP_MODE_LINEAR, reductionMode equal to VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE, and compareEnable equal to VK_FALSE is used to sample a VkImageView as a result of this command, then the image view’s format features must contain VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT
VUID-vkCmdDispatch-mipmapMode-09599
If a VkSampler created with mipmapMode equal to VK_SAMPLER_MIPMAP_MODE_LINEAR and reductionMode equal to either VK_SAMPLER_REDUCTION_MODE_MIN or VK_SAMPLER_REDUCTION_MODE_MAX is used to sample a VkImageView as a result of this command, then the image view’s format features must contain VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_MINMAX_BIT
VUID-vkCmdDispatch-unnormalizedCoordinates-09635
If a VkSampler created with unnormalizedCoordinates equal to VK_TRUE is used to sample a VkImageView as a result of this command, then the image view’s levelCount and layerCount must be 1
VUID-vkCmdDispatch-None-08609
If a VkSampler created with unnormalizedCoordinates equal to VK_TRUE is used to sample a VkImageView as a result of this command, then the image view’s viewType must be VK_IMAGE_VIEW_TYPE_1D or VK_IMAGE_VIEW_TYPE_2D
VUID-vkCmdDispatch-None-08610
If a VkSampler created with unnormalizedCoordinates equal to VK_TRUE is used to sample a VkImageView as a result of this command, then the sampler must not be used with any of the SPIR-V OpImageSample* or OpImageSparseSample* instructions with ImplicitLod, Dref or Proj in their name
VUID-vkCmdDispatch-None-08611
If a VkSampler created with unnormalizedCoordinates equal to VK_TRUE is used to sample a VkImageView as a result of this command, then the sampler must not be used with any of the SPIR-V OpImageSample* or OpImageSparseSample* instructions that includes a LOD bias or any offset values
VUID-vkCmdDispatch-aspectMask-06478
If a VkImageView is sampled with depth comparison, the image view must have been created with an aspectMask that contains VK_IMAGE_ASPECT_DEPTH_BIT
VUID-vkCmdDispatch-None-02691
If a VkImageView is accessed using atomic operations as a result of this command, then the image view’s format features must contain VK_FORMAT_FEATURE_STORAGE_IMAGE_ATOMIC_BIT
VUID-vkCmdDispatch-None-07888
If a VK_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 contain VK_FORMAT_FEATURE_STORAGE_TEXEL_BUFFER_ATOMIC_BIT
VUID-vkCmdDispatch-None-02692
If a VkImageView is sampled with VK_FILTER_CUBIC_EXT as a result of this command, then the image view’s format features must contain VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_CUBIC_BIT_EXT
VUID-vkCmdDispatch-None-02693
If the VK_EXT_filter_cubic extension is not enabled and any VkImageView is sampled with VK_FILTER_CUBIC_EXT as a result of this command, it must not have a VkImageViewType of VK_IMAGE_VIEW_TYPE_3D, VK_IMAGE_VIEW_TYPE_CUBE, or VK_IMAGE_VIEW_TYPE_CUBE_ARRAY
VUID-vkCmdDispatch-filterCubic-02694
Any VkImageView being sampled with VK_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-vkCmdDispatch-filterCubicMinmax-02695
Any VkImageView being sampled with VK_FILTER_CUBIC_EXT with a reduction mode of either VK_SAMPLER_REDUCTION_MODE_MIN or VK_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-vkCmdDispatch-None-08600
If a a bound shader statically uses a set n, 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-vkCmdDispatch-None-08601
If a a bound shader statically uses a push constant value, that 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
VUID-vkCmdDispatch-None-10068
For each array of resources that is used by a bound shader, the indices used to access members of the array must be less than the descriptor count for the identified binding in the descriptor sets used by this command
VUID-vkCmdDispatch-None-08114
Descriptors in each bound descriptor set, specified via vkCmdBindDescriptorSets, must be valid if they are accessed as described by descriptor validity by a bound shader
VUID-vkCmdDispatch-imageLayout-00344
If an image descriptor is accessed by a shader, the VkImageLayout must match the subresource accessible from the VkImageView as defined by the image layout matching rules
VUID-vkCmdDispatch-None-08606
A valid pipeline must be bound to the pipeline bind point used by this command
VUID-vkCmdDispatch-None-08608
There must not have been any calls to dynamic state setting commands for any state specified statically in the VkPipeline object bound to the pipeline bind point used by this command, since that pipeline was bound
VUID-vkCmdDispatch-uniformBuffers-06935
If any stage of the VkPipeline object bound to the pipeline bind point used by this command accesses a uniform buffer, and the robustBufferAccess 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-vkCmdDispatch-storageBuffers-06936
If any stage of the VkPipeline object bound to the pipeline bind point used by this command accesses a storage buffer, and the robustBufferAccess 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-vkCmdDispatch-commandBuffer-02707
If commandBuffer is an unprotected command buffer and protectedNoFault is not supported, any resource accessed by bound shaders must not be a protected resource
VUID-vkCmdDispatch-viewType-07752
If a VkImageView is accessed as a result of this command, then the image view’s viewType must match the Dim operand of the OpTypeImage as described in [spirvenv-image-dimensions]
VUID-vkCmdDispatch-format-07753
If a VkImageView or VkBufferView is accessed as a result of this command, then the numeric type of the view’s format and the Sampled Type operand of the OpTypeImage must match
VUID-vkCmdDispatch-OpImageWrite-08795
If a VkImageView is accessed using OpImageWrite as a result of this command, then the Type of the Texel operand of that instruction must have at least as many components as the image view’s format
VUID-vkCmdDispatch-OpImageWrite-04469
If a VkBufferView is accessed using OpImageWrite as a result of this command, then the Type of the Texel operand of that instruction must have at least as many components as the buffer view’s format
VUID-vkCmdDispatch-SampledType-04470
If a VkImageView with a VkFormat that has a 64-bit component width is accessed as a result of this command, the SampledType of the OpTypeImage operand of that instruction must have a Width of 64
VUID-vkCmdDispatch-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, the SampledType of the OpTypeImage operand of that instruction must have a Width of 32
VUID-vkCmdDispatch-SampledType-04472
If a VkBufferView with a VkFormat that has a 64-bit component width is accessed as a result of this command, the SampledType of the OpTypeImage operand of that instruction must have a Width of 64
VUID-vkCmdDispatch-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, the SampledType of the OpTypeImage operand of that instruction must have a Width of 32
VUID-vkCmdDispatch-sparseImageInt64Atomics-04474
If the sparseImageInt64Atomics feature is not enabled, VkImage objects created with the VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT flag must not be accessed by atomic instructions through an OpTypeImage with a SampledType with a Width of 64 by this command
VUID-vkCmdDispatch-sparseImageInt64Atomics-04475
If the sparseImageInt64Atomics feature is not enabled, VkBuffer objects created with the VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT flag must not be accessed by atomic instructions through an OpTypeImage with a SampledType with a Width of 64 by this command
VUID-vkCmdDispatch-None-07288
Any shader invocation executed by this command must terminate
VUID-vkCmdDispatch-None-09600
If a descriptor with type equal to any of VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE, VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, or VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT is accessed as a result of this command, all image subresources identified by that descriptor must be in the image layout identified when the descriptor was written
VUID-vkCmdDispatch-None-10672
this command must be called outside of a render pass instance

VUID-vkCmdDispatch-commandBuffer-02712
If commandBuffer is a protected command buffer and protectedNoFault is not supported, any resource written to by the VkPipeline object bound to the pipeline bind point used by this command must not be an unprotected resource
VUID-vkCmdDispatch-commandBuffer-02713
If commandBuffer is a protected command buffer and protectedNoFault is not supported, pipeline stages other than the framebuffer-space and compute stages in the VkPipeline object bound to the pipeline bind point used by this command must not write to any resource
VUID-vkCmdDispatch-groupCountX-00386
groupCountX must be less than or equal to VkPhysicalDeviceLimits::maxComputeWorkGroupCount[0]
VUID-vkCmdDispatch-groupCountY-00387
groupCountY must be less than or equal to VkPhysicalDeviceLimits::maxComputeWorkGroupCount[1]
VUID-vkCmdDispatch-groupCountZ-00388
groupCountZ must be less than or equal to VkPhysicalDeviceLimits::maxComputeWorkGroupCount[2]

Valid Usage (Implicit)

VUID-vkCmdDispatch-commandBuffer-parameter
commandBuffer must be a valid VkCommandBuffer handle
VUID-vkCmdDispatch-commandBuffer-recording
commandBuffer must be in the recording state
VUID-vkCmdDispatch-commandBuffer-cmdpool
The VkCommandPool that commandBuffer was allocated from must support VK_QUEUE_COMPUTE_BIT operations

Host Synchronization

Host access to commandBuffer must be externally synchronized
Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized