// Copyright (c) 2015-2018 Khronos Group. This work is licensed under a // Creative Commons Attribution 4.0 International License; see // http://creativecommons.org/licenses/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 dispatch commands are recorded in that command buffer. [open,refpage='vkCmdDispatch',desc='Dispatch compute work items',type='protos'] -- To record a dispatch, call: include::../api/protos/vkCmdDispatch.txt[] * 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]#groupCountX {times} groupCountY {times} groupCountZ# local workgroups is assembled. .Valid Usage **** * [[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] * [[VUID-vkCmdDispatch-None-00389]] For each set _n_ that is statically used by the sname:VkPipeline bound to ename:VK_PIPELINE_BIND_POINT_COMPUTE, a descriptor set must: have been bound to _n_ at ename:VK_PIPELINE_BIND_POINT_COMPUTE, with a sname:VkPipelineLayout that is compatible for set _n_, with the sname:VkPipelineLayout used to create the current sname:VkPipeline, as described in <> * [[VUID-vkCmdDispatch-None-00390]] Descriptors in each bound descriptor set, specified via fname:vkCmdBindDescriptorSets, must: be valid if they are statically used by the bound sname:VkPipeline object, specified via fname:vkCmdBindPipeline * [[VUID-vkCmdDispatch-None-00391]] A valid compute pipeline must: be bound to the current command buffer with ename:VK_PIPELINE_BIND_POINT_COMPUTE * [[VUID-vkCmdDispatch-None-00392]] For each push constant that is statically used by the sname:VkPipeline bound to ename:VK_PIPELINE_BIND_POINT_COMPUTE, a push constant value must: have been set for ename:VK_PIPELINE_BIND_POINT_COMPUTE, with a sname:VkPipelineLayout that is compatible for push constants with the one used to create the current sname:VkPipeline, as described in <> * [[VUID-vkCmdDispatch-None-00393]] If any sname:VkSampler object that is accessed from a shader by the sname:VkPipeline bound to ename:VK_PIPELINE_BIND_POINT_COMPUTE uses unnormalized coordinates, it must: not be used to sample from any sname:VkImage with a sname:VkImageView of the type ename:VK_IMAGE_VIEW_TYPE_3D, ename:VK_IMAGE_VIEW_TYPE_CUBE, ename:VK_IMAGE_VIEW_TYPE_1D_ARRAY, ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY or ename:VK_IMAGE_VIEW_TYPE_CUBE_ARRAY, in any shader stage * [[VUID-vkCmdDispatch-None-00394]] If any sname:VkSampler object that is accessed from a shader by the sname:VkPipeline bound to ename:VK_PIPELINE_BIND_POINT_COMPUTE uses unnormalized coordinates, it must: not be used with any of the SPIR-V `OpImageSample*` or `OpImageSparseSample*` instructions with code:ImplicitLod, code:Dref or code:Proj in their name, in any shader stage * [[VUID-vkCmdDispatch-None-00395]] If any sname:VkSampler object that is accessed from a shader by the sname:VkPipeline bound to ename: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 * [[VUID-vkCmdDispatch-None-00396]] If the <> feature is not enabled, and any shader stage in the sname:VkPipeline object bound to ename:VK_PIPELINE_BIND_POINT_COMPUTE accesses a uniform buffer, it must: not access values outside of the range of that buffer specified in the bound descriptor set * [[VUID-vkCmdDispatch-None-00397]] If the <> feature is not enabled, and any shader stage in the sname:VkPipeline object bound to ename:VK_PIPELINE_BIND_POINT_COMPUTE accesses a storage buffer, it must: not access values outside of the range of that buffer specified in the bound descriptor set ifndef::VK_ANDROID_external_memory_android_hardware_buffer[] * [[VUID-vkCmdDispatch-linearTilingFeatures-00398]] Any sname:VkImageView being sampled with ename:VK_FILTER_LINEAR as a result of this command must: be of a format which supports linear filtering, as specified by the ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT flag in sname:VkFormatProperties::pname:linearTilingFeatures or sname:VkFormatProperties::pname:optimalTilingFeatures returned by fname:vkGetPhysicalDeviceFormatProperties for linearly or optimally tiled images, respectively endif::VK_ANDROID_external_memory_android_hardware_buffer[] ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] * [[VUID-vkCmdDispatch-formatFeatures-01949]] Any sname:VkImageView being sampled with ename:VK_FILTER_LINEAR as a result of this command must: be of a format which supports linear filtering, as specified by the ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT flag in sname:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:formatFeatures returned by vkGetAndroidHardwareBufferPropertiesANDROID for external format images, or by sname:VkFormatProperties::pname:linearTilingFeatures or sname:VkFormatProperties::pname:optimalTilingFeatures returned by fname:vkGetPhysicalDeviceFormatProperties for non-external format linearly or optimally tiled images, respectively endif::VK_ANDROID_external_memory_android_hardware_buffer[] ifdef::VK_IMG_filter_cubic[] ifndef::VK_ANDROID_external_memory_android_hardware_buffer[] * [[VUID-vkCmdDispatch-linearTilingFeatures-00399]] Any slink:VkImageView being sampled with ename:VK_FILTER_CUBIC_IMG as a result of this command must: be of a format which supports cubic filtering, as specified by the ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_CUBIC_BIT_IMG flag in sname:VkFormatProperties::pname:linearTilingFeatures or sname:VkFormatProperties::pname:optimalTilingFeatures returned by fname:vkGetPhysicalDeviceFormatProperties for linearly or optimally tiled images, respectively endif::VK_ANDROID_external_memory_android_hardware_buffer[] ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] * [[VUID-vkCmdDispatch-formatFeatures-01950]] Any slink:VkImageView being sampled with ename:VK_FILTER_CUBIC_IMG as a result of this command must: be of a format which supports cubic filtering, as specified by the ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_CUBIC_BIT_IMG flag in sname:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:formatFeatures returned by vkGetAndroidHardwareBufferPropertiesANDROID for external format images, or by sname:VkFormatProperties::pname:linearTilingFeatures or sname:VkFormatProperties::pname:optimalTilingFeatures returned by fname:vkGetPhysicalDeviceFormatProperties for non-external format linearly or optimally tiled images, respectively endif::VK_ANDROID_external_memory_android_hardware_buffer[] * [[VUID-vkCmdDispatch-None-00400]] Any slink:VkImageView being sampled with ename:VK_FILTER_CUBIC_IMG as a result of this command must: not have a elink:VkImageViewType of ename:VK_IMAGE_VIEW_TYPE_3D, ename:VK_IMAGE_VIEW_TYPE_CUBE, or ename:VK_IMAGE_VIEW_TYPE_CUBE_ARRAY endif::VK_IMG_filter_cubic[] ifdef::VK_VERSION_1_1[] * [[VUID-vkCmdDispatch-commandBuffer-01844]] If pname:commandBuffer is an unprotected command buffer, and any pipeline stage in the sname:VkPipeline object bound to ename:VK_PIPELINE_BIND_POINT_COMPUTE reads from or writes to any image or buffer, that image or buffer must: not be a protected image or protected buffer. * [[VUID-vkCmdDispatch-commandBuffer-01845]] If pname:commandBuffer is a protected command buffer, and any pipeline stage in the sname:VkPipeline object bound to ename:VK_PIPELINE_POINT_COMPUTE writes to any image or buffer, that image or buffer must: not be an unprotected image or unprotected buffer. * [[VUID-vkCmdDispatch-commandBuffer-01846]] If pname:commandBuffer is a protected command buffer, and any pipeline stage other than the compute pipeline stage in the sname:VkPipeline object bound to ename:VK_PIPELINE_POINT_COMPUTE reads from any image or buffer, the image or buffer must: not be a protected image or protected buffer. endif::VK_VERSION_1_1[] **** include::../validity/protos/vkCmdDispatch.txt[] -- [open,refpage='vkCmdDispatchIndirect',desc='Dispatch compute work items using indirect parameters',type='protos'] -- To record an indirect command dispatch, call: include::../api/protos/vkCmdDispatchIndirect.txt[] * 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 **** * [[VUID-vkCmdDispatchIndirect-buffer-00401]] If pname:buffer is non-sparse then it must: be bound completely and contiguously to a single sname:VkDeviceMemory object * [[VUID-vkCmdDispatchIndirect-None-00402]] For each set _n_ that is statically used by the sname:VkPipeline bound to ename:VK_PIPELINE_BIND_POINT_COMPUTE, a descriptor set must: have been bound to _n_ at ename:VK_PIPELINE_BIND_POINT_COMPUTE, with a sname:VkPipelineLayout that is compatible for set _n_, with the sname:VkPipelineLayout used to create the current sname:VkPipeline, as described in <> * [[VUID-vkCmdDispatchIndirect-None-00403]] Descriptors in each bound descriptor set, specified via fname:vkCmdBindDescriptorSets, must: be valid if they are statically used by the bound sname:VkPipeline object, specified via fname:vkCmdBindPipeline * [[VUID-vkCmdDispatchIndirect-None-00404]] A valid compute pipeline must: be bound to the current command buffer with ename:VK_PIPELINE_BIND_POINT_COMPUTE * [[VUID-vkCmdDispatchIndirect-buffer-00405]] pname:buffer must: have been created with the ename:VK_BUFFER_USAGE_INDIRECT_BUFFER_BIT bit set * [[VUID-vkCmdDispatchIndirect-offset-00406]] pname:offset must: be a multiple of `4` * [[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 * [[VUID-vkCmdDispatchIndirect-None-00408]] For each push constant that is statically used by the sname:VkPipeline bound to ename:VK_PIPELINE_BIND_POINT_COMPUTE, a push constant value must: have been set for ename:VK_PIPELINE_BIND_POINT_COMPUTE, with a sname:VkPipelineLayout that is compatible for push constants with the one used to create the current sname:VkPipeline, as described in <> * [[VUID-vkCmdDispatchIndirect-None-00409]] If any sname:VkSampler object that is accessed from a shader by the sname:VkPipeline bound to ename:VK_PIPELINE_BIND_POINT_COMPUTE uses unnormalized coordinates, it must: not be used to sample from any sname:VkImage with a sname:VkImageView of the type ename:VK_IMAGE_VIEW_TYPE_3D, ename:VK_IMAGE_VIEW_TYPE_CUBE, ename:VK_IMAGE_VIEW_TYPE_1D_ARRAY, ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY or ename:VK_IMAGE_VIEW_TYPE_CUBE_ARRAY, in any shader stage * [[VUID-vkCmdDispatchIndirect-None-00410]] If any sname:VkSampler object that is accessed from a shader by the sname:VkPipeline bound to ename:VK_PIPELINE_BIND_POINT_COMPUTE uses unnormalized coordinates, it must: not be used with any of the SPIR-V `OpImageSample*` or `OpImageSparseSample*` instructions with code:ImplicitLod, code:Dref or code:Proj in their name, in any shader stage * [[VUID-vkCmdDispatchIndirect-None-00411]] If any sname:VkSampler object that is accessed from a shader by the sname:VkPipeline bound to ename: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 * [[VUID-vkCmdDispatchIndirect-None-00412]] If the <> feature is not enabled, and any shader stage in the sname:VkPipeline object bound to ename:VK_PIPELINE_BIND_POINT_COMPUTE accesses a uniform buffer, it must: not access values outside of the range of that buffer specified in the bound descriptor set * [[VUID-vkCmdDispatchIndirect-None-00413]] If the <> feature is not enabled, and any shader stage in the sname:VkPipeline object bound to ename:VK_PIPELINE_BIND_POINT_COMPUTE accesses a storage buffer, it must: not access values outside of the range of that buffer specified in the bound descriptor set ifndef::VK_ANDROID_external_memory_android_hardware_buffer[] * [[VUID-vkCmdDispatchIndirect-linearTilingFeatures-00414]] Any sname:VkImageView being sampled with ename:VK_FILTER_LINEAR as a result of this command must: be of a format which supports linear filtering, as specified by the ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT flag in sname:VkFormatProperties::pname:linearTilingFeatures or sname:VkFormatProperties::pname:optimalTilingFeatures returned by fname:vkGetPhysicalDeviceFormatProperties for linearly or optimally tiled images, respectively endif::VK_ANDROID_external_memory_android_hardware_buffer[] ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] * [[VUID-vkCmdDispatchIndirect-formatFeatures-01951]] Any sname:VkImageView being sampled with ename:VK_FILTER_LINEAR as a result of this command must: be of a format which supports linear filtering, as specified by the ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT flag in sname:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:formatFeatures returned by vkGetAndroidHardwareBufferPropertiesANDROID for external format images, or by sname:VkFormatProperties::pname:linearTilingFeatures or sname:VkFormatProperties::pname:optimalTilingFeatures returned by fname:vkGetPhysicalDeviceFormatProperties for non-external format linearly or optimally tiled images, respectively endif::VK_ANDROID_external_memory_android_hardware_buffer[] ifdef::VK_IMG_filter_cubic[] ifndef::VK_ANDROID_external_memory_android_hardware_buffer[] * [[VUID-vkCmdDispatchIndirect-linearTilingFeatures-00415]] Any slink:VkImageView being sampled with ename:VK_FILTER_CUBIC_IMG as a result of this command must: be of a format which supports cubic filtering, as specified by the ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_CUBIC_BIT_IMG flag in sname:VkFormatProperties::pname:linearTilingFeatures or sname:VkFormatProperties::pname:optimalTilingFeatures returned by fname:vkGetPhysicalDeviceFormatProperties for linearly or optimally tiled images, respectively endif::VK_ANDROID_external_memory_android_hardware_buffer[] ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] * [[VUID-vkCmdDispatchIndirect-formatFeatures-01952]] Any slink:VkImageView being sampled with ename:VK_FILTER_CUBIC_IMG as a result of this command must: be of a format which supports cubic filtering, as specified by the ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_CUBIC_BIT_IMG flag in sname:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:formatFeatures returned by vkGetAndroidHardwareBufferPropertiesANDROID for external format images, or by sname:VkFormatProperties::pname:linearTilingFeatures or sname:VkFormatProperties::pname:optimalTilingFeatures returned by fname:vkGetPhysicalDeviceFormatProperties for non-external format linearly or optimally tiled images, respectively endif::VK_ANDROID_external_memory_android_hardware_buffer[] * [[VUID-vkCmdDispatchIndirect-None-00416]] Any slink:VkImageView being sampled with ename:VK_FILTER_CUBIC_IMG as a result of this command must: not have a elink:VkImageViewType of ename:VK_IMAGE_VIEW_TYPE_3D, ename:VK_IMAGE_VIEW_TYPE_CUBE, or ename:VK_IMAGE_VIEW_TYPE_CUBE_ARRAY endif::VK_IMG_filter_cubic[] ifdef::VK_VERSION_1_1[] * [[VUID-vkCmdDispatchIndirect-commandBuffer-01847]] If pname:commandBuffer is an unprotected command buffer, and any pipeline stage in the sname:VkPipeline object bound to ename:VK_PIPELINE_BIND_POINT_COMPUTE reads from or writes to any image or buffer, that image or buffer must: not be a protected image or protected buffer. * [[VUID-vkCmdDispatchIndirect-commandBuffer-01848]] If pname:commandBuffer is a protected command buffer, and any pipeline stage in the sname:VkPipeline object bound to ename:VK_PIPELINE_POINT_COMPUTE writes to any image or buffer, that image or buffer must: not be an unprotected image or unprotected buffer. * [[VUID-vkCmdDispatchIndirect-commandBuffer-01849]] If pname:commandBuffer is a protected command buffer, and any pipeline stage other than the compute pipeline stage in the sname:VkPipeline object bound to ename:VK_PIPELINE_POINT_COMPUTE reads from any image or buffer, the image or buffer must: not be a protected image or protected buffer. endif::VK_VERSION_1_1[] **** include::../validity/protos/vkCmdDispatchIndirect.txt[] -- [open,refpage='VkDispatchIndirectCommand',desc='Structure specifying a dispatch indirect command',type='structs',xrefs='vkCmdDispatchIndirect'] -- The sname:VkDispatchIndirectCommand structure is defined as: include::../api/structs/VkDispatchIndirectCommand.txt[] * 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::../validity/structs/VkDispatchIndirectCommand.txt[] -- ifdef::VK_VERSION_1_1,VK_KHR_device_group[] [open,refpage='vkCmdDispatchBase',desc='Dispatch compute work items',type='protos'] -- To record a dispatch using non-zero base values for the components of code:WorkgroupId, call: ifdef::VK_VERSION_1_1[] include::../api/protos/vkCmdDispatchBase.txt[] endif::VK_VERSION_1_1[] ifdef::VK_VERSION_1_1+VK_KHR_device_group[or the equivalent command] ifdef::VK_KHR_device_group[] include::../api/protos/vkCmdDispatchBaseKHR.txt[] 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]#groupCountX {times} groupCountY {times} groupCountZ# local workgroups is assembled, with code:WorkgroupId values ranging from [eq]#[baseGroup, baseGroup {plus} groupCount)# in each component. flink:vkCmdDispatch is equivalent to vkCmdDispatchBase(0,0,0,groupCountX,groupCountY,groupCountZ). .Valid Usage **** * [[VUID-vkCmdDispatchBase-None-00420]] All valid usage rules from flink:vkCmdDispatch apply * [[VUID-vkCmdDispatchBase-baseGroupX-00421]] pname:baseGroupX must: be less than sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[0] * [[VUID-vkCmdDispatchBase-baseGroupX-00422]] pname:baseGroupX 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::../validity/protos/vkCmdDispatchBase.txt[] -- endif::VK_VERSION_1_1,VK_KHR_device_group[]