mirror of
https://github.com/status-im/Vulkan-Docs.git
synced 2025-01-12 06:54:14 +00:00
348990517c
* Bump API patch number and header version number to 29 for this update.
Github Issues:
* Remove redundant constraint on
slink:VkCommandBufferInheritanceInfo::pname:queryFlags (public issue
224).
* Fix typo and remove link in Note in the
<<extended-functionality-instance-extensions-and-devices, Instance
Extensions and Device Extensions>> section (public issue 359).
* Fix erroneous validation statement for the pname:layout member of
slink:VkComputePipelineCreateInfo (public issue 362).
Internal Issues:
* Restore long figure captions using asciidoc sidebar blocks, due to
restrictions of asciidoc syntax (internal issue 101).
* Replace most latexmath equations with comparable markup in straight
asciidoc, which significantly improves time required to fully load and
process the HTML forms of the Specification. There are known minor font
and alignment inconsistencies with MathJax and PDF rendering of
latexmath equations. Please do not file github issues about these. We
are aware of the inconsistencies and will make refinements over time,
while the performance improvements are compelling in at least some major
browsers (internal issue 313).
* Move handcoded validity statements from +vk.xml+ into the Specification
body, easing work in the single-branch model. Specify the distinction
between these explicit statements, and the implicit validity statements
inferred from vk.xml. Validity statements now appear in two blocks for
each command and structure - handcoded "Valid Usage" and the implicit
"Valid Usage (Implicit)" (internal issue 392).
* Add the +returnedonly="false"+ attribute to WSI output structures,
removing incorrectly generated implicit validity statements for
slink:VkDisplayPropertiesKHR, slink:VkDisplayPlanePropertiesKHR,
slink:VkDisplayModePropertiesKHR, slink:VkDisplayPlaneCapabilitiesKHR,
slink:VkSurfaceCapabilitiesKHR, and slink:VkSurfaceFormatKHR structures
(internal issue 486).
* Update slink:VkImageLayout to require the
ename:VK_IMAGE_USAGE_SAMPLED_BIT be set for sampled depth/stencil images
(internal issue 487).
* Use an explicit format specifier string for the date command invocation
in the +Makefile+ instead of the shorthand -R option, which doesn't work
on BSD and MaxOS X date commands (internal issue 500).
Other Issues:
* Use the terms ``allocation scope'' and ``extension scope'' instead of
just ``scope'', and add them to the glossary.
241 lines
12 KiB
Plaintext
241 lines
12 KiB
Plaintext
// Copyright (c) 2015-2016 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
|
|
<<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
|
|
****
|
|
* 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 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
|