status-im/Vulkan-Docs
2
0
Fork 0
mirror of https://github.com/status-im/Vulkan-Docs.git synced 2025-01-27 06:34:53 +00:00
Code Issues Projects Releases Wiki Activity
Vulkan-Docs/doc/specs/vulkan/chapters/dispatch.txt
Jon Leech fd0e4c3b67 Change log for February 27, 2017 Vulkan 1.0.42 spec update: 
* Bump API patch number and header version number to 42 for this update
    (the first anniversary edition).

Github Issues:

  * Changed asciidoctor macros so cross-page links in the standalone
    reference pages function properly (public issue 462).

Internal Issues:

  * Clarified host visibility discussion for slink:VkMemoryType,
    flink:vkInvalidateMappedMemoryRanges, elink:VkAccessFlagBits, and the
    <<synchronization-framebuffer-regions,Framebuffer Region Dependencies>>
    section, removing duplicated information and adding a central definition
    in the access types section (internal issue 552).
  * Change description of
    slink:vkGetPhysicalDeviceSurfacePresentModesKHR::pname:pPresentModes to
    return an array of values, not structures (internal issue 699).

New Extensions:

  * Add a NOTE to the <<extensions,Layers & Extensions>> chapter describing
    the experimental status of `KHX` extensions.
  * Add new Khronos, Khronos Experimental, and vendor Vulkan extensions for
    release at GDC:
  ** VK_KHR_descriptor_update_template
  ** VK_KHR_push_descriptor
  ** VK_KHX_device_group
  ** VK_KHX_device_group_creation
  ** VK_KHX_external_memory
  ** VK_KHX_external_memory_capabilities
  ** VK_KHX_external_memory_fd
  ** VK_KHX_external_memory_win32
  ** VK_KHX_external_semaphore
  ** VK_KHX_external_semaphore_capabilities
  ** VK_KHX_external_semaphore_fd
  ** VK_KHX_external_semaphore_win32
  ** VK_KHX_multiview
  ** VK_KHX_win32_keyed_mutex
  ** VK_EXT_discard_rectangles
  ** VK_MVK_ios_surface
  ** VK_MVK_macos_surface
  ** VK_NVX_multiview_per_view_attributes
  ** VK_NV_clip_space_w_scaling
  ** VK_NV_geometry_shader_passthrough
  ** VK_NV_sample_mask_override_coverage
  ** VK_NV_viewport_array2
  ** VK_NV_viewport_swizzle
  * Add new GLSL vendor extensions to support new builtin variables:
  ** GL_EXT_device_group
  ** GL_EXT_multiview
2017-02-26 22:54:26 -08:00

302 lines
15 KiB
Plaintext
Raw Blame History

// 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: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
****
* pname:groupCountX must: be less than or equal to
sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[0]
* pname:groupCountY must: be less than or equal to
sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[1]
* pname:groupCountZ 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
<<descriptorsets-compatibility>>
* 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
<<descriptorsets-compatibility>>
* 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 <<features-features-robustBufferAccess,robust buffer access>>
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 <<features-features-robustBufferAccess,robust buffer access>>
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
<<descriptorsets-compatibility>>
* 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
<<descriptorsets-compatibility>>
* 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 <<features-features-robustBufferAccess,robust buffer access>>
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 <<features-features-robustBufferAccess,robust buffer access>>
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 have the same meaning as the
corresponding 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
ifdef::VK_KHX_device_group[]
// refBegin vkCmdDispatchBaseKHX Dispatch compute work items
To record a dispatch using non-zero base values for the components of
code:WorkgroupId, call:
include::../api/protos/vkCmdDispatchBaseKHX.txt[]
* 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
vkCmdDispatchBaseKHX(0,0,0,groupCountX,groupCountY,groupCountZ).
.Valid Usage
****
* All valid usage rules from flink:vkCmdDispatch apply
* pname:baseGroupX must: be less than
sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[0]
* pname:baseGroupX must: be less than
sname:VkPhysicaYDeviceLimits::pname:maxComputeWorkGroupCount[1]
* pname:baseGroupZ must: be less than
sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[2]
* pname:groupCountX must: be less than or equal to
sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[0] minus
pname:baseGroupX
* pname:groupCountY must: be less than or equal to
sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[1] minus
pname:baseGroupY
* pname:groupCountZ must: be less than or equal to
sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[2] minus
pname:baseGroupZ
* If any of pname:baseGroupX, pname:baseGroupY, or pname:baseGroupZ are
not zero, then the currently bound compute pipeline must have been
created with the ename:VK_PIPELINE_CREATE_DISPATCH_BASE_KHX flag.
****
include::../validity/protos/vkCmdDispatchBaseKHX.txt[]
endif::VK_KHX_device_group[]
Reference in New Issue View Git Blame Copy Permalink