// Copyright (c) 2015-2017 The Khronos Group Inc. // Copyright notice at https://www.khronos.org/registry/speccopyright.html [[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 currently bound compute pipeline. A compute pipeline must: be bound to a command buffer before any dispatch commands are recorded in that command buffer. // refBegin vkCmdDispatch Dispatch compute work items To record a dispatch, call: include::../api/protos/vkCmdDispatch.txt[] * pname:commandBuffer is the command buffer into which the command will be recorded. * 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. When the command is executed, a global workgroup consisting of [eq]#x {times} y {times} z# local workgroups is assembled. .Valid Usage **** * pname:x must: be less than or equal to sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[0] * pname:y must: be less than or equal to sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[1] * pname:z must: be less than or equal to sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[2] * For each set _n_ that is statically used by the sname:VkPipeline currently 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 <> * Descriptors in each bound descriptor set, specified via fname:vkCmdBindDescriptorSets, must: be valid if they are statically used by the currently bound sname:VkPipeline object, specified via fname:vkCmdBindPipeline * A valid compute pipeline must: be bound to the current command buffer with ename:VK_PIPELINE_BIND_POINT_COMPUTE * For each push constant that is statically used by the sname:VkPipeline currently 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 <> * If any sname:VkSampler object that is accessed from a shader by the sname:VkPipeline currently 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 * If any sname:VkSampler object that is accessed from a shader by the sname:VkPipeline currently 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 * If any sname:VkSampler object that is accessed from a shader by the sname:VkPipeline currently 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 * If the <> feature is not enabled, and any shader stage in the sname:VkPipeline object currently 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 currently bound descriptor set * If the <> feature is not enabled, and any shader stage in the sname:VkPipeline object currently 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 currently bound descriptor set * 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 (for a linear image) or sname:VkFormatProperties::pname:optimalTilingFeatures(for an optimally tiled image) returned by fname:vkGetPhysicalDeviceFormatProperties ifdef::VK_IMG_filter_cubic[] * 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 (for a linear image) or sname:VkFormatProperties::pname:optimalTilingFeatures(for an optimally tiled image) returned by fname:vkGetPhysicalDeviceFormatProperties * 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[] **** include::../validity/protos/vkCmdDispatch.txt[] // refBegin vkCmdDispatchIndirect Dispatch compute work items using indirect parameters 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 **** * If pname:buffer is non-sparse then it must: be bound completely and contiguously to a single sname:VkDeviceMemory object * For each set _n_ that is statically used by the sname:VkPipeline currently 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 <> * Descriptors in each bound descriptor set, specified via fname:vkCmdBindDescriptorSets, must: be valid if they are statically used by the currently bound sname:VkPipeline object, specified via fname:vkCmdBindPipeline * A valid compute pipeline must: be bound to the current command buffer with ename:VK_PIPELINE_BIND_POINT_COMPUTE * pname:buffer must: have been created with the ename:VK_BUFFER_USAGE_INDIRECT_BUFFER_BIT bit set * pname:offset must: be a multiple of `4` * The sum of pname:offset and the size of sname:VkDispatchIndirectCommand must: be less than or equal to the size of pname:buffer * For each push constant that is statically used by the sname:VkPipeline currently 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 <> * If any sname:VkSampler object that is accessed from a shader by the sname:VkPipeline currently 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 * If any sname:VkSampler object that is accessed from a shader by the sname:VkPipeline currently 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 * If any sname:VkSampler object that is accessed from a shader by the sname:VkPipeline currently 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 * If the <> feature is not enabled, and any shader stage in the sname:VkPipeline object currently 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 currently bound descriptor set * If the <> feature is not enabled, and any shader stage in the sname:VkPipeline object currently 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 currently bound descriptor set * 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 (for a linear image) or sname:VkFormatProperties::pname:optimalTilingFeatures(for an optimally tiled image) returned by fname:vkGetPhysicalDeviceFormatProperties ifdef::VK_IMG_filter_cubic[] * 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 (for a linear image) or sname:VkFormatProperties::pname:optimalTilingFeatures(for an optimally tiled image) returned by fname:vkGetPhysicalDeviceFormatProperties * 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[] **** include::../validity/protos/vkCmdDispatchIndirect.txt[] // refBegin VkDispatchIndirectCommand Structure specifying a dispatch indirect command 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 structure have the same meaning as the similarly named parameters of flink:vkCmdDispatch. .Valid Usage **** * pname:x must: be less than or equal to sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[0] * pname:y must: be less than or equal to sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[1] * pname:z must: be less than or equal to sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[2] **** include::../validity/structs/VkDispatchIndirectCommand.txt[] // refEnd VkDispatchIndirectCommand vkCmdDispatchIndirect