mirror of
https://github.com/status-im/Vulkan-Docs.git
synced 2025-02-18 17:28:16 +00:00
43f1fd5550
* Bump API patch number and header version number to 44 for this update.
Github Issues:
* Fix description of <<features-extentperimagetype, Allowed Extent Values
Based On Image Type>> (public issue 290).
* Better specify VK_DEVICE_LOST behavior around flink:vkQueueSubmit,
flink:vkWaitForFences, and flink:vkGetFenceStatus (public issue 423).
* Clarify definition of flink:vkGetQueryPoolResults::pname:queryCount
(public issue 441).
* Simplify and clean up normative language. Remove shall and replace
recommend and variants with should wherever possible (public issue 448).
* Fix all dangling internal cross-references in the 1.0-extensions
specification, and add scripts/checkXrefs to find these in the future
(public issue 456).
* Reverse order of ChangeLog.txt entries so the most recent version is
documented first (public issue 463)
* Removes "become invalid" which clashes with invalid state for command
buffers. (public issue 467)
* Disallowed pending state in spec text for vkResetCommandBuffer, matching
valid usage (public issue 468)
* Removes sentence describing invalid state "like initial state". (public
issue 469)
* Disallows begin command buffer from resetting command buffers in the
"recording" state. (public issue 470)
* Removes mention of state from description of
VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT (public issue 471)
* Removed extra valid usage statement in VkSubmitInfo (public issue 472)
Internal Issues:
* Clarify description of the pname:imageLayout member of
sname:VkDescriptorImageInfo.
* Fix typos where etext:VK_VIEW_TYPE* was used instead of
etext:VK_IMAGE_VIEW_TYPE.
* Removed the <<VK_KHR_display>> and <<VK_KHR_display_swapchain>> example
code from the specification and noted it has been moved to the Vulkan
SDK cube demo (internal issue 179).
* Reorder VkExternalMemoryHandleTypeFlagBitsNV description (internal issue
480).
* Clarify than an implementation is
<<fundamentals-validusage-flags,permitted to return 'undefined' bit
flags>> in a bitfield (internal issue 640).
* Break Valid Usage statements describing unrelated parameters into
separate statements, and add a style guide entry to follow this approach
(internal issue 685).
* Move valid usage statement for slink:VkImageCreateInfo from spec body to
the explicit valid usage block (internal issue 693).
* Fix typos in the descriptions of slink:VkDisplaySurfaceCreateInfoKHR,
flink:vkCreateDisplayModeKHR, and
flink:vkGetDisplayPlaneSupportedDisplaysKHR in the <<display,Presenting
Directly to Display Devices>> section (internal issue 698, 704, 716).
* Clarified that mandatory depth/stencil formats are only a requirement
for 2D images (internal issue 719).
* Clarify that variables decorated with DeviceIndex/ViewIndex must be in
the Input storage class (internal issue 733).
* Work around generator script problem with removal of Unicode literals
from Python 3.0-3.2 using `future` package (internal issue 737).
* Remove nonexistent structure type enums from vk.xml (internal issue
738).
* Fix validextensionstructs attributes for structures in the pname:pNext
chain for VkPresentInfoKHR, fixing implicit valid usage statements for
those structures (internal issue 740).
New Extensions:
302 lines
15 KiB
Plaintext
302 lines
15 KiB
Plaintext
// 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[]
|