status-im
/
Vulkan-Docs
mirror of https://github.com/status-im/Vulkan-Docs.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity
Vulkan-Docs/doc/specs/vulkan/chapters/dispatch.txt

241 lines
12 KiB
Plaintext
Raw Normal View History

Vulkan 1.0 branch 1.0 for release
2016-02-16 09:53:44 +00:00
// Copyright (c) 2015-2016 The Khronos Group Inc.
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
[[dispatch]]
= Dispatching Commands
Change log for September 23, 2016 Vulkan 1.0.28 spec update: * Bump API patch number and header version number to 28 for this update. Github Issues: * Minor spelling and typography cleanup, add definitions of ename:VK_FALSE and ename:VK_TRUE as just what their names say (public issues 220, 318, 325, 365; internal issues 451, 496) * Clarify that the pname:maxDescriptorSet limits in the <<features-limits-required,Required Limits>> table are n * maxPerStage limit (where n=number of supported stages) (public issue 254). * Minor cleanup to <<boilerplate-platform-macros,Platform-Specific Macro Definitions>> appendix (public issue 314). * Add valid usage statement to slink:VkPipelineLayoutCreateInfo disallowing multiple push constant ranges for the same shader stage (public issue 340). * Clarify the elink:VkSharingMode description of what executing the "same" barriers means in case of ownership transfer (public issue 347). * Rename copyright.txt and add COPYING.md to try and reduce confusion about applicable copyrights (public issue 350). * Extend the table in the <<boilerplate-wsi-header, Window System-Specific Header Control>> section to describe the external headers included when each etext:VK_USE_PLATFORM_* macro is defined (public issue 376). Internal Issues: * Add "Revision History" to the PDF outputs following the table of contents, to match HTML outputs (internal issue 43). * Clarified that flink:vkMapMemory may fail due to virtual address space limitations (internal issue 346). * Add +refBody+ comment markup for ref page autoextraction when required (internal issue 400). * Document proper use of "mipmap" and "mip" in the style guide API naming rules, matching the spelling rules (internal issue 471). * Tweak the <<extensions,Layers and Extensions>> appendix to note that the Specification may be built with arbitrary combinations of extensions (internal issue 483). * Remove incorrect statement allowing slink:VkClearAttachment::pname:colorAttachment to be >= slink:VkSubpassDescription::pname:colorAttachmentCount (internal issue 488). * The <<features-limits-viewportboundsrange,viewportBoundsRange>> is expressed in terms of the pname:maxViewportDimensions but this is actually two values. Clarify that it's based on the larger of the two (if they differ) (internal issue 499). Other Issues: * Reflowed text of the entire spec using the 'reflow' Makefile gater, to (hopefully) reduce future internal git churn as edits are made and extensions added in return for one-time pain. This has no perceptible change on the spec outputs but considerable changes on the asciidoc source (internal issue 367).
2016-09-24 07:58:11 +00:00
_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.
Vulkan 1.0 branch 1.0 for release
2016-02-16 09:53:44 +00:00
Change log for September 16, 2016 Vulkan 1.0.27 spec update: * Bump API patch number and header version number to 27 for this update. Github Issues: * Weaken flink:vkGetPipelineCacheData invariance conditions; previous conditions were stronger than agreed and can't be guaranteed (public issue 280). * Add link to "Vulkan Loader Specification and Architecture Overview" document to Normative References section (public issue 359). Internal Issues: * Be more clear in the <<interfaces-resources-layout-std140, uniform buffer layout>> section that block offsets can be out of order (internal issue 396). * Document that extension authors should add support for their extensions to the validation layers (internal issue 398). * Clarify that the valid range of depth clear values should be limited to the 0..1 range and that copies to depth aspect must also be in this range (internal issue 412). * Specify ``a'' vs. ``an'' use in the style guide (internal issue 432). * Increase the maximum pname:nonCoherentAtomSize value in the <<features-limits-required,Required Limits>> section from 128 to 256 (internal issue 435). * Fix vk_platform.h for compiler errors on some Android platforms (internal issue 441). * Clarify that slink:VkPhysicalDeviceFeatures::pname:pEnabledFeatures == `NULL` disables all features, including the "required" feature pname:robustBufferAccess (internal issue 479). Other Issues: * Expand style guide and make it more self-consistent. * Use ISO 8601 date format everywhere. * Emphasise the correct way of using slink:VkSurfaceCapabilitiesKHR::pname:maxImageCount. * Added +VK_EXT_validation_flags+ extension for validation flag mechanism. * Fix an <<credits,author credit>> to include their current employer.
2016-09-17 04:22:17 +00:00
// refBegin vkCmdDispatch Dispatch compute work items
Change log for July 10, 2016 Vulkan 1.0.20 spec update: * Bump API patch number and header version number to 20 for this update. Github Issues: * Replaced existing reference pages by text automatically extracted from the specification source, or generated from vk.xml in some cases. This isn't a complete solution for the reference pages, but puts them in a much better state. The ref pages (only) are now placed under a CC BY open source license, which is more current than the obsolete license previously used. Further improvements to the pages should not edit them directly, but instead concentrate on the specification source from which the ref pages are being extracted (public issues 44, 55, 160; internal issue 389).
2016-07-11 01:13:41 +00:00
Vulkan 1.0 branch 1.0 for release
2016-02-16 09:53:44 +00:00
To record a dispatch, call:
Change log for July 22, 2016 Vulkan 1.0.22 spec update: * Bump API patch number and header version number to 22 for this update. Github Issues: * Translate the subpass self-dependency language into concrete validity statements, and added a validity statement about the restrictions on layout parameters (public issue 267). * Add validity requirement that slink:VkAttachmentDescription::pname:finalLayout and slink:VkAttachmentReference::pname:layout must not be ename:VK_IMAGE_LAYOUT_UNDEFINED or ename:VK_IMAGE_LAYOUT_PREINITIALIZED (public issue 268). * Clarify that slink:VkSubpassDescription::pname:pResolveAttachments layouts are used. Make language consistent with other attachment arrays (public issue 270). * Changed 64-bit definition for dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE to work for x32 platform in +vk.xml+ and the resulting +vulkan.h+ (public issue 282). * Add missing error return code for flink:vkEnumerateInstanceExtensionProperties and flink:vkEnumerateDeviceExtensionProperties (public issue 285) * Fix several cases of stext::VkStructName.memberName markup to stext::VkStructName::pname:memberName, to match other usage in the spec, and describe this markup in the style guide (public issue 286). * Modified validity language generation script to avoid redundant common ancestor language if covered by generic parent language, and used `Both' instead of `Each' when appropriate (public issue 288). Internal Issues: * Add language about behavior of flink:vkAllocateDescriptorSets when allocation fails due to fragmentation, a new error ename:VK_ERROR_FRAGMENTED_POOL, and a Note explaining the situation (internal issue 309). * For the features of code:PointSize, code:ClipDistance, and code:CullDistance, the SPIR-V capability is required to be declared on use (read or write) rather than on decoration (internal issue 359). * Have desktop versions of GLSL respect precision qualification (code:mediump and code:lowp) when compiling for Vulkan. These will get translated to SPIR-V's code:RelaxedPrecision decoration as they do with OpenGL ES versions of GLSL (ESSL). The default precision of all types is code:highp when using a desktop version (internal issue 360). * Add validity statement for slink:VkImageCreateInfo specifying that multisampled images must be two-dimensional, optimally tiled, and with a single mipmap level (internal issue 369). * Add validity statements to slink:VkImageViewCreateInfo disallowing creation of images or image views with no supported features. Made some slink:VkImageViewCreateInfo validity statements more precise and consistent. Added a Note to the <<features,features>> chapter about formats with no features (internal issue 371). * Remove +manpages+ from default build targets. Nroff outputs containing imbedded latexmath will not render properly. Fixing this is a lot of work for limited use cases (internal issue 401). Other Commits: * Fix flink:vkRenderPassBeginInfo::pname:clearValueCount validity statement to be based on attachment indices rather than the number of cleared attachments (Vulkan-LoaderAndValidationLayers/issues/601). * Convert registry documentation from LaTeX to asciidoc source and rename from +src/spec/readme.tex+ to +src/spec/registry.txt+. * Fix lack of Oxford commas in validity language. * Lots of cleanup of generator scripts and Makefiles to move extension list for generator into the script arguments instead of the body of genvk.py, and express better dependencies between XML, scripts, and generated files.
2016-07-23 10:15:48 +00:00
include::../api/protos/vkCmdDispatch.txt[]
Vulkan 1.0 branch 1.0 for release
2016-02-16 09:53:44 +00:00
* pname:commandBuffer is the command buffer into which the command will be
recorded.
Change log for September 23, 2016 Vulkan 1.0.28 spec update: * Bump API patch number and header version number to 28 for this update. Github Issues: * Minor spelling and typography cleanup, add definitions of ename:VK_FALSE and ename:VK_TRUE as just what their names say (public issues 220, 318, 325, 365; internal issues 451, 496) * Clarify that the pname:maxDescriptorSet limits in the <<features-limits-required,Required Limits>> table are n * maxPerStage limit (where n=number of supported stages) (public issue 254). * Minor cleanup to <<boilerplate-platform-macros,Platform-Specific Macro Definitions>> appendix (public issue 314). * Add valid usage statement to slink:VkPipelineLayoutCreateInfo disallowing multiple push constant ranges for the same shader stage (public issue 340). * Clarify the elink:VkSharingMode description of what executing the "same" barriers means in case of ownership transfer (public issue 347). * Rename copyright.txt and add COPYING.md to try and reduce confusion about applicable copyrights (public issue 350). * Extend the table in the <<boilerplate-wsi-header, Window System-Specific Header Control>> section to describe the external headers included when each etext:VK_USE_PLATFORM_* macro is defined (public issue 376). Internal Issues: * Add "Revision History" to the PDF outputs following the table of contents, to match HTML outputs (internal issue 43). * Clarified that flink:vkMapMemory may fail due to virtual address space limitations (internal issue 346). * Add +refBody+ comment markup for ref page autoextraction when required (internal issue 400). * Document proper use of "mipmap" and "mip" in the style guide API naming rules, matching the spelling rules (internal issue 471). * Tweak the <<extensions,Layers and Extensions>> appendix to note that the Specification may be built with arbitrary combinations of extensions (internal issue 483). * Remove incorrect statement allowing slink:VkClearAttachment::pname:colorAttachment to be >= slink:VkSubpassDescription::pname:colorAttachmentCount (internal issue 488). * The <<features-limits-viewportboundsrange,viewportBoundsRange>> is expressed in terms of the pname:maxViewportDimensions but this is actually two values. Clarify that it's based on the larger of the two (if they differ) (internal issue 499). Other Issues: * Reflowed text of the entire spec using the 'reflow' Makefile gater, to (hopefully) reduce future internal git churn as edits are made and extensions added in return for one-time pain. This has no perceptible change on the spec outputs but considerable changes on the asciidoc source (internal issue 367).
2016-09-24 07:58:11 +00:00
* 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.
Vulkan 1.0 branch 1.0 for release
2016-02-16 09:53:44 +00:00
Change log for September 30, 2016 Vulkan 1.0.29 spec update: * 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.
2016-10-01 04:13:37 +00:00
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[]
****
Vulkan 1.0 branch 1.0 for release
2016-02-16 09:53:44 +00:00
include::../validity/protos/vkCmdDispatch.txt[]
Change log for September 16, 2016 Vulkan 1.0.27 spec update: * Bump API patch number and header version number to 27 for this update. Github Issues: * Weaken flink:vkGetPipelineCacheData invariance conditions; previous conditions were stronger than agreed and can't be guaranteed (public issue 280). * Add link to "Vulkan Loader Specification and Architecture Overview" document to Normative References section (public issue 359). Internal Issues: * Be more clear in the <<interfaces-resources-layout-std140, uniform buffer layout>> section that block offsets can be out of order (internal issue 396). * Document that extension authors should add support for their extensions to the validation layers (internal issue 398). * Clarify that the valid range of depth clear values should be limited to the 0..1 range and that copies to depth aspect must also be in this range (internal issue 412). * Specify ``a'' vs. ``an'' use in the style guide (internal issue 432). * Increase the maximum pname:nonCoherentAtomSize value in the <<features-limits-required,Required Limits>> section from 128 to 256 (internal issue 435). * Fix vk_platform.h for compiler errors on some Android platforms (internal issue 441). * Clarify that slink:VkPhysicalDeviceFeatures::pname:pEnabledFeatures == `NULL` disables all features, including the "required" feature pname:robustBufferAccess (internal issue 479). Other Issues: * Expand style guide and make it more self-consistent. * Use ISO 8601 date format everywhere. * Emphasise the correct way of using slink:VkSurfaceCapabilitiesKHR::pname:maxImageCount. * Added +VK_EXT_validation_flags+ extension for validation flag mechanism. * Fix an <<credits,author credit>> to include their current employer.
2016-09-17 04:22:17 +00:00
// refBegin vkCmdDispatchIndirect Dispatch compute work items using indirect parameters
Change log for July 10, 2016 Vulkan 1.0.20 spec update: * Bump API patch number and header version number to 20 for this update. Github Issues: * Replaced existing reference pages by text automatically extracted from the specification source, or generated from vk.xml in some cases. This isn't a complete solution for the reference pages, but puts them in a much better state. The ref pages (only) are now placed under a CC BY open source license, which is more current than the obsolete license previously used. Further improvements to the pages should not edit them directly, but instead concentrate on the specification source from which the ref pages are being extracted (public issues 44, 55, 160; internal issue 389).
2016-07-11 01:13:41 +00:00
To record an indirect command dispatch, call:
Vulkan 1.0 branch 1.0 for release
2016-02-16 09:53:44 +00:00
Change log for July 22, 2016 Vulkan 1.0.22 spec update: * Bump API patch number and header version number to 22 for this update. Github Issues: * Translate the subpass self-dependency language into concrete validity statements, and added a validity statement about the restrictions on layout parameters (public issue 267). * Add validity requirement that slink:VkAttachmentDescription::pname:finalLayout and slink:VkAttachmentReference::pname:layout must not be ename:VK_IMAGE_LAYOUT_UNDEFINED or ename:VK_IMAGE_LAYOUT_PREINITIALIZED (public issue 268). * Clarify that slink:VkSubpassDescription::pname:pResolveAttachments layouts are used. Make language consistent with other attachment arrays (public issue 270). * Changed 64-bit definition for dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE to work for x32 platform in +vk.xml+ and the resulting +vulkan.h+ (public issue 282). * Add missing error return code for flink:vkEnumerateInstanceExtensionProperties and flink:vkEnumerateDeviceExtensionProperties (public issue 285) * Fix several cases of stext::VkStructName.memberName markup to stext::VkStructName::pname:memberName, to match other usage in the spec, and describe this markup in the style guide (public issue 286). * Modified validity language generation script to avoid redundant common ancestor language if covered by generic parent language, and used `Both' instead of `Each' when appropriate (public issue 288). Internal Issues: * Add language about behavior of flink:vkAllocateDescriptorSets when allocation fails due to fragmentation, a new error ename:VK_ERROR_FRAGMENTED_POOL, and a Note explaining the situation (internal issue 309). * For the features of code:PointSize, code:ClipDistance, and code:CullDistance, the SPIR-V capability is required to be declared on use (read or write) rather than on decoration (internal issue 359). * Have desktop versions of GLSL respect precision qualification (code:mediump and code:lowp) when compiling for Vulkan. These will get translated to SPIR-V's code:RelaxedPrecision decoration as they do with OpenGL ES versions of GLSL (ESSL). The default precision of all types is code:highp when using a desktop version (internal issue 360). * Add validity statement for slink:VkImageCreateInfo specifying that multisampled images must be two-dimensional, optimally tiled, and with a single mipmap level (internal issue 369). * Add validity statements to slink:VkImageViewCreateInfo disallowing creation of images or image views with no supported features. Made some slink:VkImageViewCreateInfo validity statements more precise and consistent. Added a Note to the <<features,features>> chapter about formats with no features (internal issue 371). * Remove +manpages+ from default build targets. Nroff outputs containing imbedded latexmath will not render properly. Fixing this is a lot of work for limited use cases (internal issue 401). Other Commits: * Fix flink:vkRenderPassBeginInfo::pname:clearValueCount validity statement to be based on attachment indices rather than the number of cleared attachments (Vulkan-LoaderAndValidationLayers/issues/601). * Convert registry documentation from LaTeX to asciidoc source and rename from +src/spec/readme.tex+ to +src/spec/registry.txt+. * Fix lack of Oxford commas in validity language. * Lots of cleanup of generator scripts and Makefiles to move extension list for generator into the script arguments instead of the body of genvk.py, and express better dependencies between XML, scripts, and generated files.
2016-07-23 10:15:48 +00:00
include::../api/protos/vkCmdDispatchIndirect.txt[]
Vulkan 1.0 branch 1.0 for release
2016-02-16 09:53:44 +00:00
* 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.
Change log for September 30, 2016 Vulkan 1.0.29 spec update: * 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.
2016-10-01 04:13:37 +00:00
.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[]
****
Vulkan 1.0 branch 1.0 for release
2016-02-16 09:53:44 +00:00
include::../validity/protos/vkCmdDispatchIndirect.txt[]
Change log for September 16, 2016 Vulkan 1.0.27 spec update: * Bump API patch number and header version number to 27 for this update. Github Issues: * Weaken flink:vkGetPipelineCacheData invariance conditions; previous conditions were stronger than agreed and can't be guaranteed (public issue 280). * Add link to "Vulkan Loader Specification and Architecture Overview" document to Normative References section (public issue 359). Internal Issues: * Be more clear in the <<interfaces-resources-layout-std140, uniform buffer layout>> section that block offsets can be out of order (internal issue 396). * Document that extension authors should add support for their extensions to the validation layers (internal issue 398). * Clarify that the valid range of depth clear values should be limited to the 0..1 range and that copies to depth aspect must also be in this range (internal issue 412). * Specify ``a'' vs. ``an'' use in the style guide (internal issue 432). * Increase the maximum pname:nonCoherentAtomSize value in the <<features-limits-required,Required Limits>> section from 128 to 256 (internal issue 435). * Fix vk_platform.h for compiler errors on some Android platforms (internal issue 441). * Clarify that slink:VkPhysicalDeviceFeatures::pname:pEnabledFeatures == `NULL` disables all features, including the "required" feature pname:robustBufferAccess (internal issue 479). Other Issues: * Expand style guide and make it more self-consistent. * Use ISO 8601 date format everywhere. * Emphasise the correct way of using slink:VkSurfaceCapabilitiesKHR::pname:maxImageCount. * Added +VK_EXT_validation_flags+ extension for validation flag mechanism. * Fix an <<credits,author credit>> to include their current employer.
2016-09-17 04:22:17 +00:00
// refBegin VkDispatchIndirectCommand Structure specifying a dispatch indirect command
Change log for July 10, 2016 Vulkan 1.0.20 spec update: * Bump API patch number and header version number to 20 for this update. Github Issues: * Replaced existing reference pages by text automatically extracted from the specification source, or generated from vk.xml in some cases. This isn't a complete solution for the reference pages, but puts them in a much better state. The ref pages (only) are now placed under a CC BY open source license, which is more current than the obsolete license previously used. Further improvements to the pages should not edit them directly, but instead concentrate on the specification source from which the ref pages are being extracted (public issues 44, 55, 160; internal issue 389).
2016-07-11 01:13:41 +00:00
Change log for April 22, 2016 Vulkan 1.0.11 spec update: * Bump API patch number and header version number to 11 for this update. Github Issues: * Clarify the WSI extension language by switching from the fuzzier "ownership" language to more-consistent "acquire" language (public issue 117). * Clarify that memory barriers apply to all commands in the dependency chains in the flink:vkGetRenderAreaGranularity command and the <<synchronization-execution-and-memory-dependencies,Execution And Memory Dependencies>> section (public issue 132). * Clarify that a queue family is a set of queues in the <<fundamentals-execmodel,Execution Model>> section (public issue 166). * Removed requirement from valid usage language that VkPresentInfoKHR::waitSemaphoreCount must be greater than 0 (public issue 171). * Fix broken internal links, describe structures consistently, use consistent style for SPIR-V codewords, and tag normative terms that were missing asciidoc tags (public issue 183 and ancillary markup/normative language fixes). * Fix typos for slink:VkPhysicalDeviceLimits member names in slink:VkImageCreateInfo validity language (public issue 184). Internal Issues: * Document that the requested patch version number specified as part of slink:VkApplicationInfo::pname:apiVersion is ignored when creating an instance (internal issue 176). * Clarify handling of extension structs in the <<fundamentals-validusageValid Usage>> section (internal issue 254). * Update required slink:VkImageFormatProperties::pname:maxMipLevels to be limited to the maximum allowed mipmap pyramid size corresponding to the actual maximum supported size for the format (internal issue 256). * Modify the <<features-extentperimagetype,Allowed Extent Values Based On Image Type>> section so the allowed maximum extent is the maximum image dimension supported for each dimension of the type of texture being queried (internal issue 257). * Clarify in the <<spirvenv-module-validation,Validation Rules within a Module>> section that at least one of the code:LocalSize execution mode or code:WorkgroupSize decoration is required for each compute shader entry point in a shader module (internal issue 279). * Add validity rules for formats in flink:vkCmdClearColorImage and flink:vkCmdClearDepthStencilImage (internal issue 283). * Clarify that slink:VkImageFormatProperties::pname:maxResourceSize is an upper bound, and that it may not be possible to create an image anywhere near that size (internal issue 284). Other Commits: * Fix various minor markup errors reported by validation scripts. * Change copyright from Khronos Free Use License to Apache 2.0 license on relevant script/XML/header files. This does not affect the specification source copyright.
2016-04-21 08:08:38 +00:00
The sname:VkDispatchIndirectCommand structure is defined as:
Vulkan 1.0 branch 1.0 for release
2016-02-16 09:53:44 +00:00
Change log for July 22, 2016 Vulkan 1.0.22 spec update: * Bump API patch number and header version number to 22 for this update. Github Issues: * Translate the subpass self-dependency language into concrete validity statements, and added a validity statement about the restrictions on layout parameters (public issue 267). * Add validity requirement that slink:VkAttachmentDescription::pname:finalLayout and slink:VkAttachmentReference::pname:layout must not be ename:VK_IMAGE_LAYOUT_UNDEFINED or ename:VK_IMAGE_LAYOUT_PREINITIALIZED (public issue 268). * Clarify that slink:VkSubpassDescription::pname:pResolveAttachments layouts are used. Make language consistent with other attachment arrays (public issue 270). * Changed 64-bit definition for dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE to work for x32 platform in +vk.xml+ and the resulting +vulkan.h+ (public issue 282). * Add missing error return code for flink:vkEnumerateInstanceExtensionProperties and flink:vkEnumerateDeviceExtensionProperties (public issue 285) * Fix several cases of stext::VkStructName.memberName markup to stext::VkStructName::pname:memberName, to match other usage in the spec, and describe this markup in the style guide (public issue 286). * Modified validity language generation script to avoid redundant common ancestor language if covered by generic parent language, and used `Both' instead of `Each' when appropriate (public issue 288). Internal Issues: * Add language about behavior of flink:vkAllocateDescriptorSets when allocation fails due to fragmentation, a new error ename:VK_ERROR_FRAGMENTED_POOL, and a Note explaining the situation (internal issue 309). * For the features of code:PointSize, code:ClipDistance, and code:CullDistance, the SPIR-V capability is required to be declared on use (read or write) rather than on decoration (internal issue 359). * Have desktop versions of GLSL respect precision qualification (code:mediump and code:lowp) when compiling for Vulkan. These will get translated to SPIR-V's code:RelaxedPrecision decoration as they do with OpenGL ES versions of GLSL (ESSL). The default precision of all types is code:highp when using a desktop version (internal issue 360). * Add validity statement for slink:VkImageCreateInfo specifying that multisampled images must be two-dimensional, optimally tiled, and with a single mipmap level (internal issue 369). * Add validity statements to slink:VkImageViewCreateInfo disallowing creation of images or image views with no supported features. Made some slink:VkImageViewCreateInfo validity statements more precise and consistent. Added a Note to the <<features,features>> chapter about formats with no features (internal issue 371). * Remove +manpages+ from default build targets. Nroff outputs containing imbedded latexmath will not render properly. Fixing this is a lot of work for limited use cases (internal issue 401). Other Commits: * Fix flink:vkRenderPassBeginInfo::pname:clearValueCount validity statement to be based on attachment indices rather than the number of cleared attachments (Vulkan-LoaderAndValidationLayers/issues/601). * Convert registry documentation from LaTeX to asciidoc source and rename from +src/spec/readme.tex+ to +src/spec/registry.txt+. * Fix lack of Oxford commas in validity language. * Lots of cleanup of generator scripts and Makefiles to move extension list for generator into the script arguments instead of the body of genvk.py, and express better dependencies between XML, scripts, and generated files.
2016-07-23 10:15:48 +00:00
include::../api/structs/VkDispatchIndirectCommand.txt[]
Vulkan 1.0 branch 1.0 for release
2016-02-16 09:53:44 +00:00
Change log for September 23, 2016 Vulkan 1.0.28 spec update: * Bump API patch number and header version number to 28 for this update. Github Issues: * Minor spelling and typography cleanup, add definitions of ename:VK_FALSE and ename:VK_TRUE as just what their names say (public issues 220, 318, 325, 365; internal issues 451, 496) * Clarify that the pname:maxDescriptorSet limits in the <<features-limits-required,Required Limits>> table are n * maxPerStage limit (where n=number of supported stages) (public issue 254). * Minor cleanup to <<boilerplate-platform-macros,Platform-Specific Macro Definitions>> appendix (public issue 314). * Add valid usage statement to slink:VkPipelineLayoutCreateInfo disallowing multiple push constant ranges for the same shader stage (public issue 340). * Clarify the elink:VkSharingMode description of what executing the "same" barriers means in case of ownership transfer (public issue 347). * Rename copyright.txt and add COPYING.md to try and reduce confusion about applicable copyrights (public issue 350). * Extend the table in the <<boilerplate-wsi-header, Window System-Specific Header Control>> section to describe the external headers included when each etext:VK_USE_PLATFORM_* macro is defined (public issue 376). Internal Issues: * Add "Revision History" to the PDF outputs following the table of contents, to match HTML outputs (internal issue 43). * Clarified that flink:vkMapMemory may fail due to virtual address space limitations (internal issue 346). * Add +refBody+ comment markup for ref page autoextraction when required (internal issue 400). * Document proper use of "mipmap" and "mip" in the style guide API naming rules, matching the spelling rules (internal issue 471). * Tweak the <<extensions,Layers and Extensions>> appendix to note that the Specification may be built with arbitrary combinations of extensions (internal issue 483). * Remove incorrect statement allowing slink:VkClearAttachment::pname:colorAttachment to be >= slink:VkSubpassDescription::pname:colorAttachmentCount (internal issue 488). * The <<features-limits-viewportboundsrange,viewportBoundsRange>> is expressed in terms of the pname:maxViewportDimensions but this is actually two values. Clarify that it's based on the larger of the two (if they differ) (internal issue 499). Other Issues: * Reflowed text of the entire spec using the 'reflow' Makefile gater, to (hopefully) reduce future internal git churn as edits are made and extensions added in return for one-time pain. This has no perceptible change on the spec outputs but considerable changes on the asciidoc source (internal issue 367).
2016-09-24 07:58:11 +00:00
* 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.
Change log for July 10, 2016 Vulkan 1.0.20 spec update: * Bump API patch number and header version number to 20 for this update. Github Issues: * Replaced existing reference pages by text automatically extracted from the specification source, or generated from vk.xml in some cases. This isn't a complete solution for the reference pages, but puts them in a much better state. The ref pages (only) are now placed under a CC BY open source license, which is more current than the obsolete license previously used. Further improvements to the pages should not edit them directly, but instead concentrate on the specification source from which the ref pages are being extracted (public issues 44, 55, 160; internal issue 389).
2016-07-11 01:13:41 +00:00
Vulkan 1.0 branch 1.0 for release
2016-02-16 09:53:44 +00:00
The members of sname:VkDispatchIndirectCommand structure have the same
meaning as the similarly named parameters of flink:vkCmdDispatch.
Change log for September 30, 2016 Vulkan 1.0.29 spec update: * 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.
2016-10-01 04:13:37 +00:00
.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]
****
Vulkan 1.0 branch 1.0 for release
2016-02-16 09:53:44 +00:00
include::../validity/structs/VkDispatchIndirectCommand.txt[]
Change log for July 10, 2016 Vulkan 1.0.20 spec update: * Bump API patch number and header version number to 20 for this update. Github Issues: * Replaced existing reference pages by text automatically extracted from the specification source, or generated from vk.xml in some cases. This isn't a complete solution for the reference pages, but puts them in a much better state. The ref pages (only) are now placed under a CC BY open source license, which is more current than the obsolete license previously used. Further improvements to the pages should not edit them directly, but instead concentrate on the specification source from which the ref pages are being extracted (public issues 44, 55, 160; internal issue 389).
2016-07-11 01:13:41 +00:00
// refEnd VkDispatchIndirectCommand vkCmdDispatchIndirect