VKCMDDISPATCH(3)

NAME
vkCmdDispatch - Dispatch compute work items.

C SPECIFICATION

    void vkCmdDispatch(
        VkCommandBuffer                             commandBuffer,
        uint32_t                                    x,
        uint32_t                                    y,
        uint32_t                                    z);

PARAMETERS

commandBuffer
    Command buffer upon which to execute the command.

x
    Number of workgroups to dispatch in the X dimension.

y
    Number of workgroups to dispatch in the Y dimension.

z
    Number of workgroups to dispatch in the Z dimension.

DESCRIPTION

vkCmdDispatch dispatches a x by y by z group of compute workgroups. Two- and one-dimensional work groups can be dispatched by setting the z, or y and z parameters to 1, respectively. The size of each workgroup is determined by the pipeline bound to the VK_PIPELINE_BIND_POINT_COMPUTE bind point on the command buffer specified by commandBuffer.

VALID USAGE

    • commandBuffer must be a valid VkCommandBuffer handle

    • commandBuffer must be in the recording state

    • The VkCommandPool that commandBuffer was allocated from must support compute operations

    • This command must only be called outside of a render pass instance

    • x must be less than or equal to VkPhysicalDeviceLimits::maxComputeWorkGroupCount[0]

    • y must be less than or equal to VkPhysicalDeviceLimits::maxComputeWorkGroupCount[1]

    • z must be less than or equal to VkPhysicalDeviceLimits::maxComputeWorkGroupCount[2]

    • For each set n that is statically used by the VkPipeline currently bound to VK_PIPELINE_BIND_POINT_COMPUTE, a descriptor set must have been bound to n at VK_PIPELINE_BIND_POINT_COMPUTE, with a VkPipelineLayout that is compatible for set n, with the VkPipelineLayout used to create the current VkPipeline, as described in ???

    • Descriptors in each bound descriptor set, specified via vkCmdBindDescriptorSets, must be valid if they are statically used by the currently bound VkPipeline object, specified via vkCmdBindPipeline

    • A valid compute pipeline must be bound to the current command buffer with VK_PIPELINE_BIND_POINT_COMPUTE

    • For each push constant that is statically used by the VkPipeline currently bound to VK_PIPELINE_BIND_POINT_COMPUTE, a push constant value must have been set for VK_PIPELINE_BIND_POINT_COMPUTE, with a VkPipelineLayout that is compatible for push constants with the one used to create the current VkPipeline, as described in ???

    • If any VkSampler object that is accessed from a shader by the VkPipeline currently bound to VK_PIPELINE_BIND_POINT_COMPUTE uses unnormalized coordinates, it must not be used to sample from any VkImage with a VkImageView of the type VK_IMAGE_VIEW_TYPE_3D, VK_IMAGE_VIEW_TYPE_CUBE, VK_IMAGE_VIEW_TYPE_1D_ARRAY, VK_IMAGE_VIEW_TYPE_2D_ARRAY or VK_IMAGE_VIEW_TYPE_CUBE_ARRAY, in any shader stage

    • If any VkSampler object that is accessed from a shader by the VkPipeline currently bound to VK_PIPELINE_BIND_POINT_COMPUTE uses unnormalized coordinates, it must not be used with any of the SPIR-V OpImageSample* or OpImageSparseSample* instructions with ImplicitLod, Dref or Proj in their name, in any shader stage

    • If any VkSampler object that is accessed from a shader by the VkPipeline currently bound to VK_PIPELINE_BIND_POINT_COMPUTE uses unnormalized coordinates, it must not be used with any of the SPIR-V OpImageSample* or OpImageSparseSample* instructions that includes a lod bias or any offset values, in any shader stage

    • If the robust buffer access feature is not enabled, and any shader stage in the VkPipeline object currently bound to VK_PIPELINE_BIND_POINT_COMPUTE accesses a uniform buffer, it must not access values outside of the range of that buffer specified in the currently bound descriptor set

    • If the robust buffer access feature is not enabled, and any shader stage in the VkPipeline object currently bound to VK_PIPELINE_BIND_POINT_COMPUTE accesses a storage buffer, it must not access values outside of the range of that buffer specified in the currently bound descriptor set

    • Any VkImageView being sampled with VK_FILTER_LINEAR as a result of this command must be of a format which supports linear filtering, as specified by the VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT flag in VkFormatProperties::linearTilingFeatures (for a linear image) or VkFormatProperties::optimalTilingFeatures(for an optimally tiled image) returned by vkGetPhysicalDeviceFormatProperties

HOST SYNCHRONIZATION

    • Host access to commandBuffer must be externally synchronized

COMMAND PROPERTIES
Command Buffer Levels | Render Pass Scope | Supported Queue Types
Primary Secondary | Outside | COMPUTE

NOTES

Although vkCmdDispatch does not generate errors or return a value, enabled validation layers may detect possible error conditions or potentially undefined behavior and report this via some other means.

SEE ALSO

vkCmdDispatchIndirect

COPYRIGHT

Copyright © 2014-2016 Khronos Group. This material may be distributed subject to the terms and conditions set forth in the Open Publication License, v 1.0, 8 June 1999. http://opencontent.org/openpub/.

AUTHOR

Khronos Group
    Author.