diff --git a/ChangeLog.adoc b/ChangeLog.adoc index 8d7538814..19256819d 100644 --- a/ChangeLog.adoc +++ b/ChangeLog.adoc @@ -14,6 +14,81 @@ appears frequently in the change log. ''' +Change log for September 26, 2024 Vulkan 1.3.296 spec update: + +Public Issues + + * Fix spelling of StdVideoH264SpsVuiFlags::color_description_present_flag + member in video.xml (public issue 2428). + * Fix copy-paste typo in vkAcquireNextImageKHR VU 07783 (public issue + 2433). + * Document support for the `stride` XML attribute for array pointers in + both command `` and structure `` tags (public issue + 2435). + +Internal Issues + + * Add accuracy and denorm specifications for SPIR-V OpSubgroupAllEqualKHR + and OpGroupNonUniformAllEqual to the <> section (internal issue + 3902). + * Clean up markup and description of the Cube Map Derivative + Transformation equations (internal issue 4010). + * Add new `Required_Limits` refpage containing the tables from the + <> section (internal issue 4014). + * Move the description of VkResult code VK_ERROR_NOT_ENOUGH_SPACE_KHR to + the <> list instead of the Success + Codes list (internal issue 4017). + * Fix some VUs for VK_EXT_swapchain_maintenance1 (internal MR 6199). + * Reword the first synchronization scope description for + <> to be more + clear and explicit (internal MR 6835). + * Coalesce decode output variants in XML `` tags (internal MR + 6850). + * Fix some structure names in new 'require' / 'feature' tags (internal MR + 6852). + * Move VK_KHR_compute_shader_derivatives feature requirement to vk.xml + (internal MR 6854). + * Remove redundant VkDrawIndirectCommand VU 00500 and + VkDrawIndexedIndirectCommand VU 00552 (internal MR 6856). + * Add SPIR-V definition for "`<>`" and use it to not imply rounding for exact operations in the + <> + table (internal MR 6859). + * Remove asciidoctor-generated footer text from spec outputs (internal MR + 6860). + * Require OpFDiv to respect SignedZeroInfNanPreserve in the + <> section (internal MR 6862). + * Add feature tags to vk.xml that were tested in CTS already but not + mentioned in the specification (internal MR 6864). + * Improve API code version refpages by including the + automatically-generated API interface content from the version appendix + of the specification that was previously omitted (internal MR 6865). + * Merge common draw VUs for shader object and pipeline viewport scaling + when VK_NV_clip_space_w_scaling is enabled (internal MR 6871). + * Merge common draw VUs for shader object and pipeline viewport rate + palette when VK_NV_shading_rate_image is enabled (internal MR 6872). + * Merge common draw vertex binding VUs for shader object and pipeline + patch control and update corresponding language in the shader object + <> section (internal MR 6876). + * Fix definition of the built-in variable + <> to specify it + returns bit indexes, not bit values (internal MR 6877). + * Add pipeline coarse sample order to shader object common draw VU 09233 + when VK_NV_shading_rate_image is enabled (internal MR 6882). + * Add missing XML `feature` tags for AMD vendor extensions (internal MR + 6889). + * Fix common draw VU interactions with dynamic rasterization samples state + from VK_EXT_sample_locations (internal MR 6896). + +New Extensions + + * VK_EXT_depth_clamp_control + * VK_EXT_device_generated_commands + +''' + Change log for August 30, 2024 Vulkan 1.3.295 spec update: Public Issues diff --git a/Makefile b/Makefile index 881b63716..67a5bdffb 100644 --- a/Makefile +++ b/Makefile @@ -139,7 +139,7 @@ VERBOSE = # ADOCOPTS options for asciidoc->HTML5 output NOTEOPTS = -a editing-notes -a implementation-guide -PATCHVERSION = 295 +PATCHVERSION = 296 BASEOPTS = ifneq (,$(findstring VKSC_VERSION_1_0,$(VERSIONS))) @@ -201,6 +201,7 @@ ATTRIBOPTS = -a revnumber="$(SPECREVISION)" $(BASEOPTS) \ -a images=$(IMAGEPATH) \ -a generated=$(GENERATED) \ -a refprefix \ + -a nofooter \ $(EXTRAATTRIBS) ADOCMISCOPTS = --failure-level ERROR # Non target-specific Asciidoctor extensions and options diff --git a/antora/spec/modules/ROOT/nav.adoc b/antora/spec/modules/ROOT/nav.adoc index e41640ad0..9c2de61ec 100644 --- a/antora/spec/modules/ROOT/nav.adoc +++ b/antora/spec/modules/ROOT/nav.adoc @@ -38,7 +38,7 @@ ifeval::["{test}"=="0"] * xref:chapters/fragops.adoc[] * xref:chapters/framebuffer.adoc[] * xref:chapters/dispatch.adoc[] -* xref:chapters/VK_NV_device_generated_commands/generatedcommands.adoc[] +* xref:chapters/device_generated_commands/generatedcommands.adoc[] * xref:chapters/sparsemem.adoc[] * xref:chapters/VK_KHR_surface/wsi.adoc[] * xref:chapters/VK_KHR_deferred_host_operations/deferred_host_operations.adoc[] diff --git a/appendices/VK_AMD_draw_indirect_count.adoc b/appendices/VK_AMD_draw_indirect_count.adoc index 1ebc376f7..a20a73f83 100644 --- a/appendices/VK_AMD_draw_indirect_count.adoc +++ b/appendices/VK_AMD_draw_indirect_count.adoc @@ -28,7 +28,7 @@ commands and execute them without host intervention. All functionality in this extension is included in `apiext:VK_KHR_draw_indirect_count`, with the suffix changed to KHR. -The original type, enum and command names are still available as aliases of +The original type, enum, and command names are still available as aliases of the core functionality. include::{generated}/interfaces/VK_AMD_draw_indirect_count.adoc[] diff --git a/appendices/VK_EXT_depth_clamp_control.adoc b/appendices/VK_EXT_depth_clamp_control.adoc new file mode 100644 index 000000000..ff26b4fbc --- /dev/null +++ b/appendices/VK_EXT_depth_clamp_control.adoc @@ -0,0 +1,71 @@ +// Copyright 2021-2024 The Khronos Group Inc. +// +// SPDX-License-Identifier: CC-BY-4.0 + +include::{generated}/meta/{refprefix}VK_EXT_depth_clamp_control.adoc[] + +=== Other Extension Metadata + +*Last Modified Date*:: + 2024-07-15 +*Contributors*:: + - Jules Blok, Independent + +=== Description + +This extension allows the application to control the viewport depth clamp +range separately from the viewport pname:minDepth and pname:maxDepth. +This gives the ability for the application to restrict depth values to an +application-defined range rather than +ifdef::VK_EXT_depth_clamp_zero_one[] +the viewport depth range or the range defined in the +apiext:VK_EXT_depth_clamp_zero_one extension. +endif::VK_EXT_depth_clamp_zero_one[] +ifndef::VK_EXT_depth_clamp_zero_one[] +the viewport depth range. +endif::VK_EXT_depth_clamp_zero_one[] + +It can be used to set a smaller or larger clamping range than the viewport +depth range without affecting the depth mapping of the viewport transform. +ifdef::VK_EXT_depth_clamp_zero_one[] +Another possible use of this extension is to restrict depth values beyond +the viewport depth range to a clamping range other than the [0, 1] range +defined in the apiext:VK_EXT_depth_clamp_zero_one extension. +endif::VK_EXT_depth_clamp_zero_one[] + +include::{generated}/interfaces/VK_EXT_depth_clamp_control.adoc[] + +=== Issues + +1) Should the depth clamp range be a per-viewport parameter? + +*RESOLVED*: No. +Because the depth clamp range was previously defined to be equal to the +viewport depth range, conformant runtimes are already handling the depth +clamp range as a per-viewport parameter. +However because of complexities from interactions with multiple viewports a +per-viewport clamp range is left to a future extensions if a use case +arises. + +2) Should this pipeline state be dynamic? + +*RESOLVED*: Yes. +Since the viewport depth range can already be a dynamic state conformant +runtimes are already able to handle the depth clamp range as a dynamic +state. + +3) Can the depth clamp range be ignored when depth clamping is disabled? + +*RESOLVED*: Yes. +This extension overrides the clamping range used only when depth clamping is +enabled. +The alternative would be highly unintuitive. +ifdef::VK_EXT_depth_clip_enable[] +As a consequence the apiext:VK_EXT_depth_clip_enable extension is required +if depth clipping is desired in combination with this extension. +endif::VK_EXT_depth_clip_enable[] + +=== Version History + + * Revision 1, 2024-02-13 (Jules Blok) + ** Initial draft diff --git a/appendices/VK_EXT_descriptor_indexing.adoc b/appendices/VK_EXT_descriptor_indexing.adoc index a6a4f8fbc..5bcbf4d13 100644 --- a/appendices/VK_EXT_descriptor_indexing.adoc +++ b/appendices/VK_EXT_descriptor_indexing.adoc @@ -69,7 +69,7 @@ Functionality in this extension is included in core Vulkan 1.2, with the EXT suffix omitted. However, if Vulkan 1.2 is supported and this extension is not, the code:descriptorIndexing capability is optional. -The original type, enum and command names are still available as aliases of +The original type, enum, and command names are still available as aliases of the core functionality. === Version History diff --git a/appendices/VK_EXT_device_generated_commands.adoc b/appendices/VK_EXT_device_generated_commands.adoc new file mode 100644 index 000000000..e47b5673a --- /dev/null +++ b/appendices/VK_EXT_device_generated_commands.adoc @@ -0,0 +1,142 @@ +// Copyright (c) 2024 Valve Corporation +// +// SPDX-License-Identifier: CC-BY-4.0 + +include::{generated}/meta/{refprefix}VK_EXT_device_generated_commands.adoc[] + +=== Other Extension Metadata + +*Last Modified Date*:: + 2024-02-23 +*Interactions and External Dependencies*:: + - This extension requires Vulkan 1.1 + - This extension requires `VK_EXT_buffer_device_address` or + `VK_KHR_buffer_device_address` or Vulkan 1.2 for the ability to bind + vertex and index buffers on the device. + - This extension requires `VK_KHR_maintenance5` for the ability to use + VkPipelineCreateFlags2KHR. + - This extension interacts with `VK_NV_mesh_shader`. + If the latter extension is not supported, remove the command tokens to + initiate NV mesh tasks drawing in this extension. + - This extension interacts with `VK_EXT_mesh_shader`. + If the latter extension is not supported, remove the command tokens to + initiate EXT mesh tasks drawing in this extension. + - This extension interacts with `VK_KHR_ray_tracing_pipeline`. + If the latter extension is not supported, remove the command tokens to + initiate ray tracing in this extension. + - This extension interacts with `VK_EXT_shader_object`. + If the latter extension is not supported, remove references to shader + objects in this extension. +*Contributors*:: + - Mike Blumenkrantz, VALVE + - Hans-Kristian Arntzen, VALVE + - Jan-Harald Fredriksen, ARM + - Spencer Fricke, LunarG + - Ricardo Garcia, Igalia + - Tobias Hector, AMD + - Baldur Karlsson, VALVE + - Christoph Kubisch, NVIDIA + - Lionel Landwerlin, INTEL + - Jon Leech, Khronos + - Ting Wei, ARM + - Ken Shanyi Zhang, AMD + - Faith Ekstrand, Collabora + - Vikram Kushwaha, NVIDIA + - Connor Abbott, VALVE + - Samuel Pitoiset, VALVE + +=== Description + +This extension allows the device to generate a number of commands for +command buffers. +It provides a subset of functionality from both +`VK_NV_device_generated_commands` and +`VK_NV_device_generated_commands_compute` as well as some new features. + +When rendering a large number of objects, the device can be leveraged to +implement a number of critical functions, like updating matrices, or +implementing occlusion culling, frustum culling, front to back sorting, etc. +Implementing those on the device does not require any special extension, +since an application is free to define its own data structures, and just +process them using shaders. + +To render objects which have been processed on the device, Vulkan has +several ways to perform indirect rendering, from the most basic +`vkCmdDrawIndirect` with one indirect draw to `vkCmdDrawIndirectCount` which +supports multiple indirect draws batched together, with a way to determine +number of draws at device execution time. + +However, if rendering state needs to change between the indirect draws, then +unextended Vulkan forces the application to speculatively record a +prohibitive number of redundant indirect commands covering all possible +state combinations - +which could end up processing nothing after culling - +or read back the processed stream and issue graphics command from the host. +For very large scenes, the synchronization overhead and cost to generate the +command buffer can become the bottleneck. +This extension allows an application to generate a device side stream of +state changes and commands, and convert it efficiently into a command buffer +without having to read it back to the host. + +Furthermore, it allows incremental changes to such command buffers by +manipulating only partial sections of a command stream -- for example +pipeline and shader object bindings. +Unextended Vulkan requires re-creation of entire command buffers in such a +scenario, or updates synchronized on the host. + +The intended usage for this extension is for the application to: + + * create sname:VkBuffer objects and retrieve physical addresses from them + via flink:vkGetBufferDeviceAddress + * create a sname:VkIndirectExecutionSetEXT for the ability to change + shaders on the device. + * create a slink:VkIndirectCommandsLayoutEXT, which lists the + elink:VkIndirectCommandsTokenTypeEXT it wants to dynamically execute as + an atomic command sequence. + This step likely involves some internal device code compilation, since + the intent is for the GPU to generate the command buffer based on the + layout. + * fill the input stream buffers with the data for each of the inputs it + needs. + Each input is an array that will be filled with token-dependent data. + * set up a preprocess sname:VkBuffer that uses memory according to the + information retrieved via + flink:vkGetGeneratedCommandsMemoryRequirementsEXT. + * optionally preprocess the generated content using + flink:vkCmdPreprocessGeneratedCommandsEXT, for example on an + asynchronous compute queue, or for the purpose of re-using the data in + multiple executions. + * call flink:vkCmdExecuteGeneratedCommandsEXT to create and execute the + actual device commands for all sequences based on the inputs provided. + +For each draw in a sequence, the following can be specified: + + * a number of vertex buffer bindings + * a different index buffer, with an optional dynamic offset and index type + * a number of different push constants + * updates to bound shader stages + +For each dispatch in a sequence, the following can be specified: + + * a number of different push constants + * updates to bound shader stages + +For each trace rays in a sequence, the following can be specified: + * a number of different push constants + * updates to bound shader stages + +While the GPU can be faster than a CPU to generate the commands, it will not +happen asynchronously to the device, therefore the primary use case is +generating "`less`" total work (occlusion culling, classification to use +specialized shaders, etc.). + +include::{generated}/interfaces/VK_EXT_device_generated_commands.adoc[] + +=== Example Code + +TODO + +=== Version History + + * Revision 1, 2024-02-23 (Mike Blumenkrantz) + ** Initial version diff --git a/appendices/VK_EXT_host_query_reset.adoc b/appendices/VK_EXT_host_query_reset.adoc index 63834d0e0..6372ca7be 100644 --- a/appendices/VK_EXT_host_query_reset.adoc +++ b/appendices/VK_EXT_host_query_reset.adoc @@ -24,7 +24,7 @@ This extension adds a new function to reset queries from the host. All functionality in this extension is included in core Vulkan 1.2, with the EXT suffix omitted. -The original type, enum and command names are still available as aliases of +The original type, enum, and command names are still available as aliases of the core functionality. include::{generated}/interfaces/VK_EXT_host_query_reset.adoc[] diff --git a/appendices/VK_EXT_image_robustness.adoc b/appendices/VK_EXT_image_robustness.adoc index 4c49e776c..05b478cc8 100644 --- a/appendices/VK_EXT_image_robustness.adoc +++ b/appendices/VK_EXT_image_robustness.adoc @@ -34,7 +34,7 @@ include::{generated}/interfaces/VK_EXT_image_robustness.adoc[] Functionality in this extension is included in core Vulkan 1.3, with the EXT suffix omitted. -The original type, enum and command names are still available as aliases of +The original type, enum, and command names are still available as aliases of the core functionality. === Issues diff --git a/appendices/VK_EXT_inline_uniform_block.adoc b/appendices/VK_EXT_inline_uniform_block.adoc index 569e01909..04e33b820 100644 --- a/appendices/VK_EXT_inline_uniform_block.adoc +++ b/appendices/VK_EXT_inline_uniform_block.adoc @@ -32,7 +32,7 @@ include::{generated}/interfaces/VK_EXT_inline_uniform_block.adoc[] Functionality in this extension is included in core Vulkan 1.3, with the EXT suffix omitted. -The original type, enum and command names are still available as aliases of +The original type, enum, and command names are still available as aliases of the core functionality. Vulkan 1.3 adds <> feature is made optional. -The original type, enum and command names are still available as aliases of +The original type, enum, and command names are still available as aliases of the core functionality. include::{generated}/interfaces/VK_KHR_variable_pointers.adoc[] diff --git a/appendices/VK_KHR_vulkan_memory_model.adoc b/appendices/VK_KHR_vulkan_memory_model.adoc index f0fd4fb93..5a98a6376 100644 --- a/appendices/VK_KHR_vulkan_memory_model.adoc +++ b/appendices/VK_KHR_vulkan_memory_model.adoc @@ -42,7 +42,7 @@ All functionality in this extension is included in core Vulkan 1.2, with the KHR suffix omitted. However, if Vulkan 1.2 is supported and this extension is not, the code:vulkanMemoryModel capability is optional. -The original type, enum and command names are still available as aliases of +The original type, enum, and command names are still available as aliases of the core functionality. include::{generated}/interfaces/VK_KHR_vulkan_memory_model.adoc[] diff --git a/appendices/VK_KHR_zero_initialize_workgroup_memory.adoc b/appendices/VK_KHR_zero_initialize_workgroup_memory.adoc index c12bfd4e6..086067df9 100644 --- a/appendices/VK_KHR_zero_initialize_workgroup_memory.adoc +++ b/appendices/VK_KHR_zero_initialize_workgroup_memory.adoc @@ -29,7 +29,7 @@ include::{generated}/interfaces/VK_KHR_zero_initialize_workgroup_memory.adoc[] Functionality in this extension is included in core Vulkan 1.3, with the KHR suffix omitted. -The original type, enum and command names are still available as aliases of +The original type, enum, and command names are still available as aliases of the core functionality. === Version History diff --git a/appendices/compressedtex.adoc b/appendices/compressedtex.adoc index be545a314..ae8bc3240 100644 --- a/appendices/compressedtex.adoc +++ b/appendices/compressedtex.adoc @@ -36,7 +36,7 @@ chapter. BC6H and BC7 are described in the "`BPTC Compressed Texture Image Formats`" chapter. -.Mapping of Vulkan BC formats to descriptions +.Mapping of Vulkan BC Formats to Descriptions [width="90%",options="header",cols="5,4"] |==== | elink:VkFormat | <> description @@ -70,7 +70,7 @@ chapter. The following formats are described in the "`ETC2 Compressed Texture Image Formats`" chapter of the <>. -.Mapping of Vulkan ETC formats to descriptions +.Mapping of Vulkan ETC Formats to Descriptions [options="header",cols="1,1"] |==== | elink:VkFormat | <> description @@ -95,7 +95,7 @@ Formats`" chapter of the <>. ASTC formats are described in the "`ASTC Compressed Texture Image Formats`" chapter of the <>. -.Mapping of Vulkan ASTC formats to descriptions +.Mapping of Vulkan ASTC Formats to Descriptions [width="90%",options="header",cols="55%,20%,25%"] |==== | elink:VkFormat ^| Compressed texel block dimensions ^| Requested mode @@ -169,7 +169,7 @@ ifdef::VK_EXT_astc_decode_mode[] If the `VK_EXT_astc_decode_mode` extension is enabled, the decode mode is determined as follows: -.Mapping of Vulkan ASTC decoding format to ASTC decoding modes +.Mapping of Vulkan ASTC Decoding Format to ASTC Decoding Modes [width="75%",options="header",cols="75%,25%"] |==== | elink:VkFormat ^| Decoding mode @@ -200,7 +200,7 @@ ifdef::VK_IMG_format_pvrtc[] PVRTC formats are described in the "`PVRTC Compressed Texture Image Formats`" chapter of the <>. -.Mapping of Vulkan PVRTC formats to descriptions +.Mapping of Vulkan PVRTC Formats to Descriptions [width="75%",options="header",cols="63%,15%,22%"] |==== | elink:VkFormat ^| Compressed texel block dimensions ^| sRGB-encoded diff --git a/appendices/spirvenv.adoc b/appendices/spirvenv.adoc index 2cc89ae4b..6a9dd214f 100644 --- a/appendices/spirvenv.adoc +++ b/appendices/spirvenv.adoc @@ -84,7 +84,7 @@ endif::VKSC_VERSION_1_0[] :captableindent: {nbsp} {nbsp} {nbsp} {nbsp} {nbsp} {nbsp} {nbsp} {nbsp} [[spirvenv-capabilities-table]] -.List of SPIR-V Capabilities and corresponding Vulkan features, extensions, or core version +.List of SPIR-V Capabilities and Corresponding Vulkan Features, Extensions, or Core Version [options="header"] |==== | SPIR-V code:OpCapability + @@ -134,7 +134,7 @@ endif::VKSC_VERSION_1_0[] slink:VkPhysicalDeviceProperties::pname:apiVersion). [[spirvenv-extensions-table]] -.List of SPIR-V Extensions and corresponding Vulkan extensions or core version +.List of SPIR-V Extensions and Corresponding Vulkan Extensions or Core Version [options="header"] |==== | SPIR-V code:OpExtension + @@ -2331,7 +2331,7 @@ ifdef::VK_KHR_shader_float_controls2[] of the operands or to the result type. **** The operation is not a bit-preserving operation and is not one of code:OpFConvert, code:OpFNegate, code:OpFAdd, code:OpFSub, - code:OpFMul, code:OpIsNan, or code:OpIsInf. + code:OpFMul, code:OpFDiv, code:OpIsNan, or code:OpIsInf. **** The operation is an code:OpLoad from the code:Input {StorageClass} in the fragment shader stage. endif::VK_KHR_shader_float_controls2[] @@ -2349,8 +2349,8 @@ ifdef::VK_VERSION_1_2,VK_KHR_shader_float_controls[] code:SignedZeroInfNanPreserve {ExecutionMode}. ** The following core SPIR-V instructions must: respect the code:SignedZeroInfNanPreserve {ExecutionMode}: code:OpFConvert, - code:OpFNegate, code:OpFAdd, code:OpFSub, code:OpFMul, code:OpIsNan, - and code:OpIsInf. + code:OpFNegate, code:OpFAdd, code:OpFSub, code:OpFMul, code:OpFDiv, + code:OpIsNan, and code:OpIsInf. endif::VK_VERSION_1_2,VK_KHR_shader_float_controls[] endif::VK_KHR_shader_float_controls2[] * All bit-preserving operations and the following instructions must: not @@ -2406,12 +2406,15 @@ ifdef::VK_VERSION_1_2,VK_KHR_shader_float_controls[] code:OpFUnordNotEqual, code:OpFOrdLessThan, code:OpFUnordLessThan, code:OpFOrdGreaterThan, code:OpFUnordGreaterThan, code:OpFOrdLessThanEqual, code:OpFUnordLessThanEqual, - code:OpFOrdGreaterThanEqual, code:OpFUnordGreaterThanEqual; and the - following extended instructions for GLSL: code:FAbs, code:FSign, - code:Radians, code:Degrees, code:FMin, code:FMax, code:FClamp, - code:FMix, code:Fma, code:PackHalf2x16, code:PackDouble2x32, - code:UnpackHalf2x16, code:UnpackDouble2x32, code:NMin, code:NMax, and - code:NClamp. + code:OpFOrdGreaterThanEqual, code:OpFUnordGreaterThanEqual, +ifdef::VK_EXT_shader_subgroup_vote[] + code:OpSubgroupAllEqualKHR, +endif::VK_EXT_shader_subgroup_vote[] + code:OpGroupNonUniformAllEqual; and the following extended instructions + for GLSL: code:FAbs, code:FSign, code:Radians, code:Degrees, code:FMin, + code:FMax, code:FClamp, code:FMix, code:Fma, code:PackHalf2x16, + code:PackDouble2x32, code:UnpackHalf2x16, code:UnpackDouble2x32, + code:NMin, code:NMax, and code:NClamp. endif::VK_VERSION_1_2,VK_KHR_shader_float_controls[] The precision of double-precision instructions is at least that of single @@ -2468,6 +2471,12 @@ The precision of individual operations is defined either in terms of rounding (correctly rounded), as an error bound in ULP, or as inherited from a formula as follows: +[[spirvenv-correct-result]] +.Correct Result +Operations that are described as returning the "correct result" will return +the infinitely precise result which, due to the nature of the operation, +will not need rounding. + [[spirvenv-correctly-rounded]] .Correctly Rounded Operations described as "`correctly rounded`" will return the infinitely @@ -2548,7 +2557,7 @@ at least as follows: endif::VK_VERSION_1_2,VK_KHR_shader_float16_int8[] [[spirvenv-precision-core-table]] -.Precision of core SPIR-V Instructions +.Precision of Core SPIR-V Instructions [options="header", cols=",,"] |==== | Instruction @@ -2572,7 +2581,7 @@ endif::VK_VERSION_1_2,VK_KHR_shader_float16_int8[] | code:OpDot(x, y) 2+a| Inherited from latexmath:[\sum_{i = 0}^{n - 1} x_{i} \times y_{i}]. | code:OpIsNan, code:OpIsInf -2+| Correct Result. +2+| Correct result. | code:OpFOrdEqual, code:OpFUnordEqual 2+| Correct result. | code:OpFOrdNotEqual, code:OpFUnordNotEqual @@ -2585,6 +2594,14 @@ endif::VK_VERSION_1_2,VK_KHR_shader_float16_int8[] 2+| Correct result. | code:OpFOrdGreaterThanEqual, code:OpFUnordGreaterThanEqual 2+| Correct result. +ifdef::VK_EXT_shader_subgroup_vote[] +| code:OpSubgroupAllEqualKHR +2+| Correct result. +endif::VK_EXT_shader_subgroup_vote[] +ifdef::VK_VERSION_1_1[] +| code:OpGroupNonUniformAllEqual +2+| Correct result. +endif::VK_VERSION_1_1[] | code:OpFDiv(x,y) | 2.5 ULP for [eq]#{vert}y{vert} = 0# or [eq]#{vert}y{vert}# in the range [2^-126^, 2^126^]. | 2.5 ULP for [eq]#{vert}y{vert} = 0# or [eq]#{vert}y{vert}# in the range [2^-14^, 2^14^]. | code:OpFRem(x,y) @@ -2654,7 +2671,7 @@ different sign than the infinitely precise result. | code:atanh(x) 2+a| Inherited from latexmath:[\log(\frac{1.0 + x}{1.0 - x}) \times 0.5]. | code:frexp() -2+| Correctly rounded. +2+| Correct result. | code:ldexp() 2+| Correctly rounded. | code:length(x) @@ -2678,9 +2695,9 @@ different sign than the infinitely precise result. | code:trunc 2+| Correctly rounded. | code:fabs -2+| Correctly rounded. +2+| Correct result. | code:fsign -2+| Correctly rounded. +2+| Correct result. | code:floor 2+| Correctly rounded. | code:ceil @@ -2690,11 +2707,11 @@ different sign than the infinitely precise result. | code:modf 2+| Correctly rounded. | code:fmin -2+| Correctly rounded. +2+| Correct result. | code:fmax -2+| Correctly rounded. +2+| Correct result. | code:fclamp -2+| Correctly rounded. +2+| Correct result. | code:fmix(x, y, a) 2+a| Inherited from latexmath:[x \times (1.0 - a) + y \times a]. | code:step @@ -2703,11 +2720,11 @@ different sign than the infinitely precise result. 2+a| Inherited from latexmath:[t \times t \times (3.0 - 2.0 \times t)], where latexmath:[t = clamp(\frac{x - edge0}{edge1 - edge0}, 0.0, 1.0)]. | code:nmin -2+| Correctly rounded. +2+| Correct result. | code:nmax -2+| Correctly rounded. +2+| Correct result. | code:nclamp -2+| Correctly rounded. +2+| Correct result. | code:packHalf2x16 2+| Correctly rounded. |==== diff --git a/appendices/versions.adoc b/appendices/versions.adoc index 2c45c2b80..c33177e99 100644 --- a/appendices/versions.adoc +++ b/appendices/versions.adoc @@ -1,5 +1,4 @@ // Copyright 2015-2024 The Khronos Group Inc. -// // SPDX-License-Identifier: CC-BY-4.0 [appendix] @@ -27,36 +26,23 @@ ifdef::VK_VERSION_1_3[] [[versions-1.3]] == Vulkan Version 1.3 -// Unfortunately we cannot include titles in an open refpage block, so this -// is a refpage-specific alternate form of the section. -ifdef::isrefpage[] [open,refpage='VK_VERSION_1_3',desc='Vulkan version 1.3',type='feature',anchor='versions-1.3',xrefs='VK_VERSION_1_0 VK_VERSION_1_1 VK_VERSION_1_2'] -- -Vulkan Version 1.3 <> a -number of key extensions into the core API: - -include::{generated}/meta/promoted_extensions_VK_VERSION_1_3.adoc[] - -All differences in behavior between these extensions and the corresponding -Vulkan 1.3 functionality are summarized in the <>. - -include::{generated}/interfaces/VK_VERSION_1_3.adoc[] --- -endif::isrefpage[] +// This allows the Vulkan refpages to work when built separately from this chapter +ifndef::VKSC_VERSION_1_0[:promoted: {generated}/meta] +ifdef::VKSC_VERSION_1_0[:promoted: {appendices}/sc_static] -// This is the spec-specific form of the section [[versions-1.3-promotions]] Vulkan Version 1.3 <> a number of key extensions into the core API: -include::{generated}/meta/promoted_extensions_VK_VERSION_1_3.adoc[] +include::{promoted}/promoted_extensions_VK_VERSION_1_3.adoc[] All differences in behavior between these extensions and the corresponding Vulkan 1.3 functionality are summarized below. -=== Differences Relative to `VK_EXT_4444_formats` +Differences Relative to `VK_EXT_4444_formats`:: If the `apiext:VK_EXT_4444_formats` extension is not supported, support for all formats defined by it are optional in Vulkan 1.3. @@ -64,7 +50,7 @@ There are no members in the slink:VkPhysicalDeviceVulkan13Features structure corresponding to the slink:VkPhysicalDevice4444FormatsFeaturesEXT structure. -=== Differences Relative to `VK_EXT_extended_dynamic_state` +Differences Relative to `VK_EXT_extended_dynamic_state`:: All dynamic state enumerants and commands defined by `apiext:VK_EXT_extended_dynamic_state` are required in Vulkan 1.3. @@ -73,7 +59,7 @@ corresponding to the slink:VkPhysicalDeviceExtendedDynamicStateFeaturesEXT structure. -=== Differences Relative to `VK_EXT_extended_dynamic_state2` +Differences Relative to `VK_EXT_extended_dynamic_state2`:: The optional dynamic state enumerants and commands defined by `apiext:VK_EXT_extended_dynamic_state2` for patch control points and logic @@ -83,7 +69,7 @@ corresponding to the slink:VkPhysicalDeviceExtendedDynamicState2FeaturesEXT structure. -=== Differences Relative to `VK_EXT_texel_buffer_alignment` +Differences Relative to `VK_EXT_texel_buffer_alignment`:: The more specific alignment requirements defined by slink:VkPhysicalDeviceTexelBufferAlignmentProperties are required in Vulkan @@ -95,7 +81,7 @@ The pname:texelBufferAlignment feature is enabled if using a Vulkan 1.3 instance. -=== Differences Relative to `VK_EXT_texture_compression_astc_hdr` +Differences Relative to `VK_EXT_texture_compression_astc_hdr`:: If the `apiext:VK_EXT_texture_compression_astc_hdr` extension is not supported, support for all formats defined by it are optional in Vulkan 1.3. @@ -105,7 +91,7 @@ slink:VkPhysicalDeviceVulkan13Features indicates whether a Vulkan 1.3 implementation supports these formats. -=== Differences Relative to `VK_EXT_ycbcr_2plane_444_formats` +Differences Relative to `VK_EXT_ycbcr_2plane_444_formats`:: If the `apiext:VK_EXT_ycbcr_2plane_444_formats` extension is not supported, support for all formats defined by it are optional in Vulkan 1.3. @@ -114,8 +100,10 @@ corresponding to the slink:VkPhysicalDeviceYcbcr2Plane444FormatsFeaturesEXT structure. -=== Additional Vulkan 1.3 Feature Support - +Additional Vulkan 1.3 Feature Support:: ++ +[open] +---- [[versions-1.3-new-features]] In addition to the promoted extensions described above, Vulkan 1.3 added required support for: @@ -133,8 +121,20 @@ required support for: * The <> limit is added to provide the total size of all inline uniform block bindings in a pipeline layout. +---- +// This include does not work inside the open block in the spec used to +// delimit refpage content, but does work in the refpage extracted from the +// spec. + +ifdef::isrefpage[] include::{generated}/interfaces/VK_VERSION_1_3.adoc[] +endif::isrefpage[] +-- + +ifndef::isrefpage[] +include::{generated}/interfaces/VK_VERSION_1_3.adoc[] +endif::isrefpage[] endif::VK_VERSION_1_3[] @@ -143,29 +143,12 @@ ifdef::VK_VERSION_1_2[] [[versions-1.2]] == Vulkan Version 1.2 -// Unfortunately we cannot include titles in an open refpage block, so this -// is a refpage-specific alternate form of the section. -ifdef::isrefpage[] [open,refpage='VK_VERSION_1_2',desc='Vulkan version 1.2',type='feature',anchor='versions-1.2',xrefs='VK_VERSION_1_0 VK_VERSION_1_1 VK_VERSION_1_3'] -- -Vulkan Version 1.2 <> a -number of key extensions into the core API: - -// Must be redefined in the refpage content +// This allows the Vulkan refpages to work when built separately from this chapter ifndef::VKSC_VERSION_1_0[:promoted: {generated}/meta] ifdef::VKSC_VERSION_1_0[:promoted: {appendices}/sc_static] -include::{promoted}/promoted_extensions_VK_VERSION_1_2.adoc[] - -All differences in behavior between these extensions and the corresponding -Vulkan 1.2 functionality are summarized in the <>. - -include::{generated}/interfaces/VK_VERSION_1_2.adoc[] --- -endif::isrefpage[] - -// This is the spec-specific form of the section [[versions-1.2-promotions]] Vulkan Version 1.2 <> a number of key extensions into the core API: @@ -176,7 +159,7 @@ All differences in behavior between these extensions and the corresponding Vulkan 1.2 functionality are summarized below. -=== Differences Relative to `VK_KHR_8bit_storage` +Differences Relative to `VK_KHR_8bit_storage`:: If the `apiext:VK_KHR_8bit_storage` extension is not supported, support for the SPIR-V <> @@ -216,7 +199,7 @@ slink:VkPhysicalDeviceVulkan12Features::pname:descriptorIndexing when queried via flink:vkGetPhysicalDeviceFeatures2. -=== Differences Relative to `VK_EXT_scalar_block_layout` +Differences Relative to `VK_EXT_scalar_block_layout`:: If the `apiext:VK_EXT_scalar_block_layout` extension is not supported, support for the <> @@ -226,7 +209,7 @@ slink:VkPhysicalDeviceVulkan12Features::pname:scalarBlockLayout when queried via flink:vkGetPhysicalDeviceFeatures2. -=== Differences Relative to `VK_EXT_shader_viewport_index_layer` +Differences Relative to `VK_EXT_shader_viewport_index_layer`:: The code:ShaderViewportIndexLayerEXT SPIR-V capability was replaced with the code:ShaderViewportIndex and code:ShaderLayer capabilities. @@ -240,7 +223,7 @@ slink:VkPhysicalDeviceVulkan12Features::pname:shaderOutputLayer when queried via flink:vkGetPhysicalDeviceFeatures2. -=== Differences Relative to `VK_KHR_buffer_device_address` +Differences Relative to `VK_KHR_buffer_device_address`:: If the `apiext:VK_KHR_buffer_device_address` extension is not supported, support for the <> @@ -250,7 +233,7 @@ slink:VkPhysicalDeviceVulkan12Features::pname:bufferDeviceAddress when queried via flink:vkGetPhysicalDeviceFeatures2. -=== Differences Relative to `VK_KHR_shader_atomic_int64` +Differences Relative to `VK_KHR_shader_atomic_int64`:: If the `apiext:VK_KHR_shader_atomic_int64` extension is not supported, support for the <> and @@ -271,7 +254,7 @@ slink:VkPhysicalDeviceVulkan12Features::pname:shaderInt8 when queried via flink:vkGetPhysicalDeviceFeatures2. -=== Differences Relative to `VK_KHR_vulkan_memory_model` +Differences Relative to `VK_KHR_vulkan_memory_model`:: If the `apiext:VK_KHR_vulkan_memory_model` extension is not supported, support for the <> @@ -281,8 +264,10 @@ slink:VkPhysicalDeviceVulkan12Features::pname:vulkanMemoryModel when queried via flink:vkGetPhysicalDeviceFeatures2. -=== Additional Vulkan 1.2 Feature Support - +Additional Vulkan 1.2 Feature Support:: ++ +[open] +---- [[versions-1.2-new-features]] In addition to the promoted extensions described above, Vulkan 1.2 added support for: @@ -327,8 +312,20 @@ support for: pname:framebufferIntegerColorSampleCounts>> limit which indicates the color sample counts that are supported for all framebuffer color attachments with integer formats. +---- + +// This include does not work inside the open block in the spec used to +// delimit refpage content, but does work in the refpage extracted from the +// spec. +ifdef::isrefpage[] include::{generated}/interfaces/VK_VERSION_1_2.adoc[] +endif::isrefpage[] +-- + +ifndef::isrefpage[] +include::{generated}/interfaces/VK_VERSION_1_2.adoc[] +endif::isrefpage[] endif::VK_VERSION_1_2[] @@ -337,29 +334,12 @@ ifdef::VK_VERSION_1_1[] [[versions-1.1]] == Vulkan Version 1.1 -// Unfortunately we cannot include titles in an open refpage block, so this -// is a refpage-specific alternate form of the section. -ifdef::isrefpage[] [open,refpage='VK_VERSION_1_1',desc='Vulkan version 1.1',type='feature',anchor='versions-1.1',xrefs='VK_VERSION_1_0 VK_VERSION_1_2 VK_VERSION_1_3'] -- -Vulkan Version 1.1 <> a -number of key extensions into the core API: - -// Must be redefined in the refpage content +// This allows the Vulkan refpages to work when built separately from this chapter ifndef::VKSC_VERSION_1_0[:promoted: {generated}/meta] ifdef::VKSC_VERSION_1_0[:promoted: {appendices}/sc_static] -include::{promoted}/promoted_extensions_VK_VERSION_1_1.adoc[] - -All differences in behavior between these extensions and the corresponding -Vulkan 1.1 functionality are summarized in the <>. - -include::{generated}/interfaces/VK_VERSION_1_1.adoc[] --- -endif::isrefpage[] - -// This is the spec-specific form of the section [[versions-1.1-promotions]] Vulkan Version 1.1 <> a number of key extensions into the core API: @@ -370,7 +350,7 @@ All differences in behavior between these extensions and the corresponding Vulkan 1.1 functionality are summarized below. -=== Differences Relative to `VK_KHR_16bit_storage` +Differences Relative to `VK_KHR_16bit_storage`:: If the `apiext:VK_KHR_16bit_storage` extension is not supported, support for the <> @@ -383,7 +363,7 @@ endif::VK_VERSION_1_2[] when queried via flink:vkGetPhysicalDeviceFeatures2. -=== Differences Relative to `VK_KHR_sampler_ycbcr_conversion` +Differences Relative to `VK_KHR_sampler_ycbcr_conversion`:: If the `apiext:VK_KHR_sampler_ycbcr_conversion` extension is not supported, support for the <Version - diff --git a/build_tests/expectations/all.html b/build_tests/expectations/all.html index c06f7835e..82926d6f3 100644 --- a/build_tests/expectations/all.html +++ b/build_tests/expectations/all.html @@ -1407,11 +1407,6 @@

Version - diff --git a/build_tests/expectations/copy2-1.0.html b/build_tests/expectations/copy2-1.0.html index 5f04c0b8e..29c45d733 100644 --- a/build_tests/expectations/copy2-1.0.html +++ b/build_tests/expectations/copy2-1.0.html @@ -619,11 +619,6 @@

-
-Version 1.2.3
-
- diff --git a/build_tests/expectations/core-1.0.html b/build_tests/expectations/core-1.0.html index 646705e13..4cf7a2a7e 100644 --- a/build_tests/expectations/core-1.0.html +++ b/build_tests/expectations/core-1.0.html @@ -169,11 +169,6 @@

-
-Version 1.2.3
-
- diff --git a/build_tests/expectations/core.html b/build_tests/expectations/core.html index 174cf19e1..c5d62b49f 100644 --- a/build_tests/expectations/core.html +++ b/build_tests/expectations/core.html @@ -625,11 +625,6 @@

-
-Version 1.2.3
-
- diff --git a/build_tests/expectations/hic-1.0.html b/build_tests/expectations/hic-1.0.html index 6ee51b1ed..699260459 100644 --- a/build_tests/expectations/hic-1.0.html +++ b/build_tests/expectations/hic-1.0.html @@ -1334,11 +1334,6 @@

Version - diff --git a/build_tests/expectations/hic.html b/build_tests/expectations/hic.html index cde778d20..279a1462f 100644 --- a/build_tests/expectations/hic.html +++ b/build_tests/expectations/hic.html @@ -1370,11 +1370,6 @@

Version - diff --git a/chapters/VK_EXT_depth_clamp_control/fragops.adoc b/chapters/VK_EXT_depth_clamp_control/fragops.adoc new file mode 100644 index 000000000..b4deb7b70 --- /dev/null +++ b/chapters/VK_EXT_depth_clamp_control/fragops.adoc @@ -0,0 +1,131 @@ +// Copyright 2015-2024 The Khronos Group Inc. +// +// SPDX-License-Identifier: CC-BY-4.0 + +[open,refpage='VkPipelineViewportDepthClampControlCreateInfoEXT',desc='Structure specifying parameters of a newly created pipeline depth clamp control state',type='structs'] +-- +The sname:VkPipelineViewportDepthClampControlCreateInfoEXT structure is +defined as: + +include::{generated}/api/structs/VkPipelineViewportDepthClampControlCreateInfoEXT.adoc[] + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * pname:depthClampMode determines how the clamp range is determined for + each viewport. + * pname:pDepthClampRange sets the depth clamp range for all viewports if + pname:depthClampMode is set to + ename:VK_DEPTH_CLAMP_MODE_USER_DEFINED_RANGE_EXT. + +This structure extends sname:VkPipelineViewportStateCreateInfo and specifies +the depth clamp range used in the pipeline. +If this structure is not provided in the next chain then +pname:depthClampMode defaults to +ename:VK_DEPTH_CLAMP_MODE_VIEWPORT_RANGE_EXT. + +.Valid Usage +**** + * [[VUID-VkPipelineViewportDepthClampControlCreateInfoEXT-pDepthClampRange-09646]] + If pname:depthClampMode is set to + ename:VK_DEPTH_CLAMP_MODE_USER_DEFINED_RANGE_EXT, and the pipeline is + not created with ename:VK_DYNAMIC_STATE_DEPTH_CLAMP_RANGE_EXT, then + pname:pDepthClampRange must be a valid pointer to a valid + sname:VkDepthClampRangeEXT structure. +**** + +include::{generated}/validity/structs/VkPipelineViewportDepthClampControlCreateInfoEXT.adoc[] +-- + +[open,refpage='VkDepthClampModeEXT',desc='Modes that determine the depth clamp range',type='enums'] +-- +Possible values of +slink:VkPipelineViewportDepthClampControlCreateInfoEXT::pname:depthClampMode, +specifying which range should be used for depth clamping, are: + +include::{generated}/api/enums/VkDepthClampModeEXT.adoc[] + + * ename:VK_DEPTH_CLAMP_MODE_VIEWPORT_RANGE_EXT specifies that the depth + clamp range follows the viewport depth range. + The depth clamp range of each viewport will implicitly be set to + [eq]#z~min~ = min(n,f)# and [eq]#z~max~ = max(n,f)#, where [eq]#n# and + [eq]#f# are the pname:minDepth and pname:maxDepth depth range values of + the viewport. + * ename:VK_DEPTH_CLAMP_MODE_USER_DEFINED_RANGE_EXT specifies that a single + user-defined depth clamp range will be used for all viewports. + The user-defined depth clamp range is defined by the pname:minDepthClamp + and pname:maxDepthClamp members of slink:VkDepthClampRangeEXT. +-- + +[open,refpage='vkCmdSetDepthClampRangeEXT',desc='Set the viewport depth clamp range dynamically for a command buffer',type='protos'] +-- +To <> the viewport depth clamp +range parameters, call: + +include::{generated}/api/protos/vkCmdSetDepthClampRangeEXT.adoc[] + + * pname:commandBuffer is the command buffer into which the command will be + recorded. + * pname:depthClampMode determines how the clamp range is determined for + each viewport. + * pname:pDepthClampRange sets the depth clamp range for all viewports if + pname:depthClampMode is set to + ename:VK_DEPTH_CLAMP_MODE_USER_DEFINED_RANGE_EXT. + +This command sets the viewport depth clamp range for subsequent drawing +commands +ifdef::VK_EXT_shader_object[when drawing using <>, or] +when the graphics pipeline is created with +ename:VK_DYNAMIC_STATE_DEPTH_CLAMP_RANGE_EXT set in +slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. +Otherwise, this state is specified by the +slink:VkPipelineViewportDepthClampControlCreateInfoEXT::pname:depthClampMode +value used to create the currently active pipeline. + +.Valid Usage +**** + * [[VUID-vkCmdSetDepthClampRangeEXT-pDepthClampRange-09647]] + If pname:depthClampMode is set to + ename:VK_DEPTH_CLAMP_MODE_USER_DEFINED_RANGE_EXT, then + pname:pDepthClampRange must be a valid pointer to a valid + sname:VkDepthClampRangeEXT structure. +**** + +include::{generated}/validity/protos/vkCmdSetDepthClampRangeEXT.adoc[] +-- + +Both slink:VkPipelineViewportDepthClampControlCreateInfoEXT and +flink:vkCmdSetDepthClampRangeEXT use sname:VkDepthClampRangeEXT to set the +viewport depth clamp range parameters. + +[open,refpage='VkDepthClampRangeEXT',desc='Structure specifying a depth clamp range',type='structs'] +-- +The sname:VkDepthClampRangeEXT structure is defined as: + +include::{generated}/api/structs/VkDepthClampRangeEXT.adoc[] + + * pname:minDepthClamp sets [eq]#z~min~# in the depth clamp range of the + viewport. + * pname:maxDepthClamp sets [eq]#z~max~# in the depth clamp range of the + viewport. + +.Valid Usage +**** + * [[VUID-VkDepthClampRangeEXT-pDepthClampRange-00999]] + pname:minDepthClamp must: be less than or equal to pname:maxDepthClamp + * [[VUID-VkDepthClampRangeEXT-pDepthClampRange-09648]] +ifdef::VK_EXT_depth_range_unrestricted[] + If the `apiext:VK_EXT_depth_range_unrestricted` extension is not + enabled, +endif::VK_EXT_depth_range_unrestricted[] + pname:minDepthClamp must: be greater than or equal to `0.0` + * [[VUID-VkDepthClampRangeEXT-pDepthClampRange-09649]] +ifdef::VK_EXT_depth_range_unrestricted[] + If the `apiext:VK_EXT_depth_range_unrestricted` extension is not + enabled, +endif::VK_EXT_depth_range_unrestricted[] + pname:maxDepthClamp must: be less than or equal to `1.0` +**** + +include::{generated}/validity/structs/VkDepthClampRangeEXT.adoc[] +-- diff --git a/chapters/VK_EXT_swapchain_maintenance1/SwapchainPresentFenceInfo.adoc b/chapters/VK_EXT_swapchain_maintenance1/SwapchainPresentFenceInfo.adoc index 5876d670e..69e4a797d 100644 --- a/chapters/VK_EXT_swapchain_maintenance1/SwapchainPresentFenceInfo.adoc +++ b/chapters/VK_EXT_swapchain_maintenance1/SwapchainPresentFenceInfo.adoc @@ -57,10 +57,12 @@ the slink:VkPresentInfoKHR structure. pname:swapchainCount must: be equal to slink:VkPresentInfoKHR::pname:swapchainCount * [[VUID-VkSwapchainPresentFenceInfoEXT-pFences-07758]] - Each element of pname:pFences must: be unsignaled + Each element of pname:pFences that is not dlink:VK_NULL_HANDLE must: be + unsignaled * [[VUID-VkSwapchainPresentFenceInfoEXT-pFences-07759]] - Each element of pname:pFences must: not be associated with any other - queue command that has not yet completed execution on that queue + Each element of pname:pFences that is not dlink:VK_NULL_HANDLE must: not + be associated with any other queue command that has not yet completed + execution on that queue **** include::{generated}/validity/structs/VkSwapchainPresentFenceInfoEXT.adoc[] diff --git a/chapters/VK_EXT_swapchain_maintenance1/SwapchainPresentScalingCreateInfo.adoc b/chapters/VK_EXT_swapchain_maintenance1/SwapchainPresentScalingCreateInfo.adoc index 70ac875b7..cd073818d 100644 --- a/chapters/VK_EXT_swapchain_maintenance1/SwapchainPresentScalingCreateInfo.adoc +++ b/chapters/VK_EXT_swapchain_maintenance1/SwapchainPresentScalingCreateInfo.adoc @@ -57,47 +57,51 @@ which define surface gravity. * [[VUID-VkSwapchainPresentScalingCreateInfoEXT-presentGravityY-07769]] pname:presentGravityY must: not have more than one bit set * [[VUID-VkSwapchainPresentScalingCreateInfoEXT-scalingBehavior-07770]] - pname:scalingBehavior must: be a valid scaling method for the surface as - returned in + pname:scalingBehavior must: be `0` or a valid scaling method for the + surface as returned in slink:VkSurfacePresentScalingCapabilitiesEXT::pname:supportedPresentScaling, given slink:VkSwapchainCreateInfoKHR::pname:presentMode in slink:VkSurfacePresentModeEXT * [[VUID-VkSwapchainPresentScalingCreateInfoEXT-scalingBehavior-07771]] If the swapchain is created with slink:VkSwapchainPresentModesCreateInfoEXT, pname:scalingBehavior must: - be a valid scaling method for the surface as returned in + be `0` or a valid scaling method for the surface as returned in slink:VkSurfacePresentScalingCapabilitiesEXT::pname:supportedPresentScaling, given each present mode in slink:VkSwapchainPresentModesCreateInfoEXT::pname:pPresentModes in slink:VkSurfacePresentModeEXT * [[VUID-VkSwapchainPresentScalingCreateInfoEXT-presentGravityX-07772]] - pname:presentGravityX must: be a valid x-axis present gravity for the - surface as returned in + pname:presentGravityX must: be `0` or a valid x-axis present gravity for + the surface as returned in slink:VkSurfacePresentScalingCapabilitiesEXT::pname:supportedPresentGravityX, given slink:VkSwapchainCreateInfoKHR::pname:presentMode in slink:VkSurfacePresentModeEXT * [[VUID-VkSwapchainPresentScalingCreateInfoEXT-presentGravityX-07773]] If the swapchain is created with slink:VkSwapchainPresentModesCreateInfoEXT, pname:presentGravityX must: - be a valid x-axis present gravity for the surface as returned in + be `0` or a valid x-axis present gravity for the surface as returned in slink:VkSurfacePresentScalingCapabilitiesEXT::pname:supportedPresentGravityX, given each present mode in slink:VkSwapchainPresentModesCreateInfoEXT::pname:pPresentModes in slink:VkSurfacePresentModeEXT * [[VUID-VkSwapchainPresentScalingCreateInfoEXT-presentGravityY-07774]] - pname:presentGravityY must: be a valid y-axis present gravity for the - surface as returned in + pname:presentGravityY must: be `0` or a valid y-axis present gravity for + the surface as returned in slink:VkSurfacePresentScalingCapabilitiesEXT::pname:supportedPresentGravityY, given slink:VkSwapchainCreateInfoKHR::pname:presentMode in slink:VkSurfacePresentModeEXT * [[VUID-VkSwapchainPresentScalingCreateInfoEXT-presentGravityY-07775]] If the swapchain is created with slink:VkSwapchainPresentModesCreateInfoEXT, pname:presentGravityY must: - be a valid y-axis present gravity for the surface as returned in + be `0` or a valid y-axis present gravity for the surface as returned in slink:VkSurfacePresentScalingCapabilitiesEXT::pname:supportedPresentGravityY, given each present mode in slink:VkSwapchainPresentModesCreateInfoEXT::pname:pPresentModes in slink:VkSurfacePresentModeEXT + * [[VUID-VkSwapchainPresentScalingCreateInfoEXT-swapchainMaintenance1-10154]] + If the <> + feature is not enabled, then pname:presentScaling, + pname:presentGravityX, and pname:presentGravityY must: be `0` **** include::{generated}/validity/structs/VkSwapchainPresentScalingCreateInfoEXT.adoc[] diff --git a/chapters/VK_KHR_surface/wsi.adoc b/chapters/VK_KHR_surface/wsi.adoc index c16dd1b0d..6ac304809 100644 --- a/chapters/VK_KHR_surface/wsi.adoc +++ b/chapters/VK_KHR_surface/wsi.adoc @@ -1604,7 +1604,7 @@ The supported elink:VkImageUsageFlagBits of the presentable images of a swapchain created for a surface may: differ depending on the presentation mode, and can be determined as per the table below: -.Presentable image usage queries +.Presentable Image Usage Queries [width="100%",cols="<50%,<50%",options="header"] |==== | Presentation mode | Image usage flags diff --git a/chapters/VK_KHR_swapchain/wsi.adoc b/chapters/VK_KHR_swapchain/wsi.adoc index cf2c7d89f..e73bec454 100644 --- a/chapters/VK_KHR_swapchain/wsi.adoc +++ b/chapters/VK_KHR_swapchain/wsi.adoc @@ -398,6 +398,16 @@ endif::VKSC_VERSION_1_0[] structure returned by fname:vkGetPhysicalDeviceSurfaceCapabilitiesKHR for the surface if the returned pname:maxImageCount is not zero * [[VUID-VkSwapchainCreateInfoKHR-presentMode-02839]] +ifdef::VK_EXT_swapchain_maintenance1[] + * [[VUID-VkSwapchainCreateInfoKHR-swapchainMaintenance1-10155]] + If the <> + feature is not enabled, then the pname:pNext chain must: not include a + slink:VkSwapchainPresentModesCreateInfoEXT structure + * [[VUID-VkSwapchainCreateInfoKHR-swapchainMaintenance1-10156]] + If the <> + feature is not enabled, then the pname:pNext chain must: not include a + slink:VkSwapchainPresentScalingCreateInfoEXT structure +endif::VK_EXT_swapchain_maintenance1[] ifdef::VK_KHR_shared_presentable_image[] If pname:presentMode is not ename:VK_PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR nor @@ -441,6 +451,10 @@ ifdef::VK_EXT_swapchain_maintenance1[] members of the sname:VkSurfacePresentScalingCapabilitiesEXT structure returned by fname:vkGetPhysicalDeviceSurfaceCapabilities2KHR for the surface and pname:presentMode + * [[VUID-VkSwapchainCreateInfoKHR-swapchainMaintenance1-10157]] + If the <> + feature is not enabled, then pname:flags must: not include + ename:VK_SWAPCHAIN_CREATE_DEFERRED_MEMORY_ALLOCATION_BIT_EXT endif::VK_EXT_swapchain_maintenance1[] * [[VUID-VkSwapchainCreateInfoKHR-imageExtent-01689]] pname:imageExtent members pname:width and pname:height must: both be @@ -945,8 +959,7 @@ include::{chapters}/commonvalidity/no_dynamic_allocations_common.adoc[] * [[VUID-vkAcquireNextImageKHR-surface-07783]] If <> cannot be guaranteed for the pname:surface used to create the pname:swapchain - member of pname:pAcquireInfo, the pname:timeout member of - pname:pAcquireInfo must: not be code:UINT64_MAX + member of pname:pAcquireInfo, pname:timeout must: not be code:UINT64_MAX ifdef::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] * [[VUID-vkAcquireNextImageKHR-semaphore-03265]] pname:semaphore must: have a elink:VkSemaphoreType of @@ -1523,6 +1536,10 @@ ifdef::VK_KHR_present_id[] enabled, each pname:presentIds entry in that structure must: be NULL endif::VK_KHR_present_id[] ifdef::VK_EXT_swapchain_maintenance1[] + * [[VUID-VkPresentInfoKHR-swapchainMaintenance1-10158]] + If the <> + feature is not enabled, then the pname:pNext chain must: not include a + slink:VkSwapchainPresentFenceInfoEXT structure * [[VUID-VkPresentInfoKHR-pSwapchains-09199]] If any element of the pname:pSwapchains array has been created with slink:VkSwapchainPresentModesCreateInfoEXT, all of the elements of this @@ -1687,6 +1704,13 @@ This functionality is useful during swapchain recreation, where acquired images from the old swapchain can be released instead of presented. ==== +.Valid Usage +**** + * [[VUID-vkReleaseSwapchainImagesEXT-swapchainMaintenance1-10159]] + Feature <> + must: be enabled +**** + include::{generated}/validity/protos/vkReleaseSwapchainImagesEXT.adoc[] -- diff --git a/chapters/VK_NV_device_generated_commands/generatedcommands.adoc b/chapters/VK_NV_device_generated_commands/generatedcommands.adoc deleted file mode 100644 index cf9698d17..000000000 --- a/chapters/VK_NV_device_generated_commands/generatedcommands.adoc +++ /dev/null @@ -1,40 +0,0 @@ -// Copyright (c) 2019-2020 NVIDIA Corporation -// -// SPDX-License-Identifier: CC-BY-4.0 - -[[device-generated-commands]] -= Device-Generated Commands - -This chapter discusses the generation of command buffer content on the -device, for which these principle steps are to be taken: - - * Define via sname:VkIndirectCommandsLayoutNV the sequence of commands - which should be generated. - * Optionally make use of <> for graphics pipelines. - * Retrieve device addresses by flink:vkGetBufferDeviceAddressEXT for - setting buffers on the device. -ifdef::VK_NV_device_generated_commands_compute[] - * Retrieve device addresses of compute pipelines by - flink:vkGetPipelineIndirectDeviceAddressNV to be able to bind it in - device generated rendering. -endif::VK_NV_device_generated_commands_compute[] - * Fill one or more sname:VkBuffer with the appropriate content that gets - interpreted by sname:VkIndirectCommandsLayoutNV. - * Create a `preprocess` sname:VkBuffer using the allocation information - from flink:vkGetGeneratedCommandsMemoryRequirementsNV. - * Optionally preprocess the input data using - flink:vkCmdPreprocessGeneratedCommandsNV in a separate action. - * Generate and execute the actual commands via - flink:vkCmdExecuteGeneratedCommandsNV passing all required data. - -flink:vkCmdPreprocessGeneratedCommandsNV executes in a separate logical -pipeline from either graphics or compute. -When preprocessing commands in a separate step they must: be explicitly -synchronized against the command execution. -When not preprocessing, the preprocessing is automatically synchronized -against the command execution. - -include::{chapters}/VK_NV_device_generated_commands/indirectcommands.adoc[] - -include::{chapters}/VK_NV_device_generated_commands/generation.adoc[] diff --git a/chapters/VK_NV_device_generated_commands/generation.adoc b/chapters/VK_NV_device_generated_commands/generation.adoc deleted file mode 100644 index db39856de..000000000 --- a/chapters/VK_NV_device_generated_commands/generation.adoc +++ /dev/null @@ -1,485 +0,0 @@ -// Copyright (c) 2019-2020 NVIDIA Corporation -// -// SPDX-License-Identifier: CC-BY-4.0 - -== Indirect Commands Generation and Execution - -[open,refpage='vkGetGeneratedCommandsMemoryRequirementsNV',desc='Retrieve the buffer allocation requirements for generated commands',type='protos'] --- -The generation of commands on the device requires a `preprocess` buffer. -To retrieve the memory size and alignment requirements of a particular -execution state call: - -include::{generated}/api/protos/vkGetGeneratedCommandsMemoryRequirementsNV.adoc[] - - * pname:device is the logical device that owns the buffer. - * pname:pInfo is a pointer to a - slink:VkGeneratedCommandsMemoryRequirementsInfoNV structure containing - parameters required for the memory requirements query. - * pname:pMemoryRequirements is a pointer to a slink:VkMemoryRequirements2 - structure in which the memory requirements of the buffer object are - returned. - -.Valid Usage -**** - * [[VUID-vkGetGeneratedCommandsMemoryRequirementsNV-deviceGeneratedCommands-02906]] - The <> - feature must: be enabled -ifdef::VK_NV_device_generated_commands_compute[] - * [[VUID-vkGetGeneratedCommandsMemoryRequirementsNV-pInfo-09074]] - If pname:pInfo->pipelineBindPoint is of type - ename:VK_PIPELINE_BIND_POINT_COMPUTE, then the - <> - feature must: be enabled -endif::VK_NV_device_generated_commands_compute[] -**** - -include::{generated}/validity/protos/vkGetGeneratedCommandsMemoryRequirementsNV.adoc[] --- - -[open,refpage='VkGeneratedCommandsMemoryRequirementsInfoNV',desc='Structure specifying parameters for the reservation of preprocess buffer space',type='structs'] --- -include::{generated}/api/structs/VkGeneratedCommandsMemoryRequirementsInfoNV.adoc[] - - * pname:sType is a elink:VkStructureType value identifying this structure. - * pname:pNext is `NULL` or a pointer to a structure extending this - structure. - * pname:pipelineBindPoint is the elink:VkPipelineBindPoint of the - pname:pipeline that this buffer memory is intended to be used with - during the execution. - * pname:pipeline is the slink:VkPipeline that this buffer memory is - intended to be used with during the execution. - * pname:indirectCommandsLayout is the slink:VkIndirectCommandsLayoutNV - that this buffer memory is intended to be used with. - * pname:maxSequencesCount is the maximum number of sequences that this - buffer memory in combination with the other state provided can: be used - with. - -.Valid Usage -**** - * [[VUID-VkGeneratedCommandsMemoryRequirementsInfoNV-maxSequencesCount-02907]] - pname:maxSequencesCount must: be less or equal to - slink:VkPhysicalDeviceDeviceGeneratedCommandsPropertiesNV::pname:maxIndirectSequenceCount - * [[VUID-VkGeneratedCommandsMemoryRequirementsInfoNV-pipelineBindPoint-09075]] - If pname:pipelineBindPoint is of type - ename:VK_PIPELINE_BIND_POINT_GRAPHICS, then pname:pipeline must: be a - valid slink:VkPipeline handle -ifdef::VK_NV_device_generated_commands_compute[] - * [[VUID-VkGeneratedCommandsMemoryRequirementsInfoNV-pipelineBindPoint-09076]] - If pname:pipelineBindPoint is of type - ename:VK_PIPELINE_BIND_POINT_COMPUTE, and the - pname:indirectCommandsLayout was not created with a - ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_PIPELINE_NV token, then the - pname:pipeline must: be a valid slink:VkPipeline handle - * [[VUID-VkGeneratedCommandsMemoryRequirementsInfoNV-pipelineBindPoint-09077]] - If pname:pipelineBindPoint is of type - ename:VK_PIPELINE_BIND_POINT_COMPUTE, and the - pname:indirectCommandsLayout contains a - ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_PIPELINE_NV token, then the - pname:pipeline must: be dlink:VK_NULL_HANDLE -endif::VK_NV_device_generated_commands_compute[] -**** - -include::{generated}/validity/structs/VkGeneratedCommandsMemoryRequirementsInfoNV.adoc[] --- - -ifdef::VK_NV_device_generated_commands_compute[] - -To bind a compute pipeline in <>, an application must: query the pipeline's device address. - -[open,refpage='vkGetPipelineIndirectDeviceAddressNV',desc='Get pipeline\'s 64-bit device address',type='protos'] --- -:refpage: vkGetPipelineIndirectDeviceAddressNV - -To query a compute pipeline's 64-bit device address, call: - -include::{generated}/api/protos/vkGetPipelineIndirectDeviceAddressNV.adoc[] - - * pname:device is the logical device on which the pipeline was created. - * pname:pInfo is a pointer to a - slink:VkPipelineIndirectDeviceAddressInfoNV structure specifying the - pipeline to retrieve the address for. - -.Valid Usage -**** - * [[VUID-vkGetPipelineIndirectDeviceAddressNV-deviceGeneratedComputePipelines-09078]] - The <> - feature must: be enabled -**** - -include::{generated}/validity/protos/vkGetPipelineIndirectDeviceAddressNV.adoc[] --- - -[open,refpage='VkPipelineIndirectDeviceAddressInfoNV',desc='Structure specifying the pipeline to query an address for',type='structs'] --- -:refpage: VkPipelineIndirectDeviceAddressInfoNV - -The sname:VkPipelineIndirectDeviceAddressInfoNV structure is defined as: - -include::{generated}/api/structs/VkPipelineIndirectDeviceAddressInfoNV.adoc[] - - * pname:sType is a elink:VkStructureType value identifying this structure. - * pname:pNext is `NULL` or a pointer to a structure extending this - structure. - * pname:pipelineBindPoint is a elink:VkPipelineBindPoint value specifying - the type of pipeline whose device address is being queried. - * pname:pipeline specifies the pipeline whose device address is being - queried. - -.Valid Usage -**** - * [[VUID-VkPipelineIndirectDeviceAddressInfoNV-pipelineBindPoint-09079]] - The provided pname:pipelineBindPoint must: be of type - ename:VK_PIPELINE_BIND_POINT_COMPUTE - * [[VUID-VkPipelineIndirectDeviceAddressInfoNV-pipeline-09080]] - pname:pipeline must: have been created with flag - ename:VK_PIPELINE_CREATE_INDIRECT_BINDABLE_BIT_NV set - * [[VUID-VkPipelineIndirectDeviceAddressInfoNV-pipeline-09081]] - pname:pipeline must: have been created with a - slink:VkComputePipelineIndirectBufferInfoNV structure specifying a valid - address where its metadata will be saved -**** -include::{generated}/validity/structs/VkPipelineIndirectDeviceAddressInfoNV.adoc[] --- - -[open,refpage='vkGetPipelineIndirectMemoryRequirementsNV',desc='Get the memory requirements for the compute indirect pipeline',type='protos'] --- -:refpage: vkGetPipelineIndirectMemoryRequirementsNV - -To determine the memory requirements for a compute pipeline's metadata, -call: - -include::{generated}/api/protos/vkGetPipelineIndirectMemoryRequirementsNV.adoc[] - - * pname:device is the logical device that owns the buffer. - * pname:pCreateInfo is a slink:VkComputePipelineCreateInfo structure - specifying the creation parameters of the compute pipeline whose memory - requirements are being queried. - * pname:pMemoryRequirements is a pointer to a slink:VkMemoryRequirements2 - structure in which the requested pipeline's memory requirements are - returned. - -If pname:pCreateInfo->pNext chain includes a pointer to a -slink:VkComputePipelineIndirectBufferInfoNV structure, then the contents of -that structure are ignored. - -.Valid Usage -**** - * [[VUID-vkGetPipelineIndirectMemoryRequirementsNV-deviceGeneratedComputePipelines-09082]] - The <> - feature must: be enabled - * [[VUID-vkGetPipelineIndirectMemoryRequirementsNV-pCreateInfo-09083]] - pname:pCreateInfo->flags must: include - ename:VK_PIPELINE_CREATE_INDIRECT_BINDABLE_BIT_NV -**** - -include::{generated}/validity/protos/vkGetPipelineIndirectMemoryRequirementsNV.adoc[] --- -endif::VK_NV_device_generated_commands_compute[] - -[open,refpage='vkCmdExecuteGeneratedCommandsNV',desc='Generate and execute commands on the device',type='protos'] --- -:refpage: vkCmdExecuteGeneratedCommandsNV - -The actual generation of commands as well as their execution on the device -is handled as single action with: - -include::{generated}/api/protos/vkCmdExecuteGeneratedCommandsNV.adoc[] - - * pname:commandBuffer is the command buffer into which the command is - recorded. - * pname:isPreprocessed represents whether the input data has already been - preprocessed on the device. - If it is ename:VK_FALSE this command will implicitly trigger the - preprocessing step, otherwise not. - * pname:pGeneratedCommandsInfo is a pointer to a - slink:VkGeneratedCommandsInfoNV structure containing parameters - affecting the generation of commands. - -If the ename:VK_INDIRECT_COMMANDS_LAYOUT_USAGE_UNORDERED_SEQUENCES_BIT_NV -flag was used to create the -slink:VkGeneratedCommandsInfoNV::pname:indirectCommandsLayout then the order -of execution of individual draws through this command may: execute in any -order, and may: not necessarily be in the same order as specified in -slink:VkGeneratedCommandsInfoNV::pname:pStreams. - -ifdef::VK_NV_device_generated_commands_compute[] -The order of execution of individual dispatches through this command may: -execute in any order and may: not necessarily be in the same order as -specified in slink:VkGeneratedCommandsInfoNV::pname:pStreams. -endif::VK_NV_device_generated_commands_compute[] - -.Valid Usage -**** -include::{chapters}/commonvalidity/draw_common.adoc[] -include::{chapters}/commonvalidity/draw_vertex_binding.adoc[] -ifdef::VK_VERSION_1_1[] - * [[VUID-vkCmdExecuteGeneratedCommandsNV-commandBuffer-02970]] - pname:commandBuffer must: not be a protected command buffer -endif::VK_VERSION_1_1[] - * [[VUID-vkCmdExecuteGeneratedCommandsNV-isPreprocessed-02908]] - If pname:isPreprocessed is ename:VK_TRUE then - flink:vkCmdPreprocessGeneratedCommandsNV must: have already been - executed on the device, using the same pname:pGeneratedCommandsInfo - content as well as the content of the input buffers it references (all - except slink:VkGeneratedCommandsInfoNV::pname:preprocessBuffer). - Furthermore pname:pGeneratedCommandsInfo`s pname:indirectCommandsLayout - must: have been created with the - ename:VK_INDIRECT_COMMANDS_LAYOUT_USAGE_EXPLICIT_PREPROCESS_BIT_NV bit - set - * [[VUID-vkCmdExecuteGeneratedCommandsNV-pipeline-02909]] - slink:VkGeneratedCommandsInfoNV::pname:pipeline must: match the current - bound pipeline at - slink:VkGeneratedCommandsInfoNV::pname:pipelineBindPoint -ifdef::VK_EXT_transform_feedback[] - * [[VUID-vkCmdExecuteGeneratedCommandsNV-None-02910]] - Transform feedback must: not be active -endif::VK_EXT_transform_feedback[] - * [[VUID-vkCmdExecuteGeneratedCommandsNV-deviceGeneratedCommands-02911]] - The <> - feature must: be enabled -**** - -include::{generated}/validity/protos/vkCmdExecuteGeneratedCommandsNV.adoc[] --- - -[open,refpage='VkGeneratedCommandsInfoNV',desc='Structure specifying parameters for the generation of commands',type='structs'] --- -:refpage: - -The sname:VkGeneratedCommandsInfoNV is defined as: - -include::{generated}/api/structs/VkGeneratedCommandsInfoNV.adoc[] - - * pname:sType is a elink:VkStructureType value identifying this structure. - * pname:pNext is `NULL` or a pointer to a structure extending this - structure. - * pname:pipelineBindPoint is the elink:VkPipelineBindPoint used for the - pname:pipeline. - * pname:pipeline is the slink:VkPipeline used in the generation and - execution process. - * pname:indirectCommandsLayout is the slink:VkIndirectCommandsLayoutNV - that provides the command sequence to generate. - * pname:streamCount defines the number of input streams - * pname:pStreams is a pointer to an array of pname:streamCount - slink:VkIndirectCommandsStreamNV structures providing the input data for - the tokens used in pname:indirectCommandsLayout. - * pname:sequencesCount is the maximum number of sequences to reserve. - If pname:sequencesCountBuffer is dlink:VK_NULL_HANDLE, this is also the - actual number of sequences generated. - * pname:preprocessBuffer is the slink:VkBuffer that is used for - preprocessing the input data for execution. - If this structure is used with flink:vkCmdExecuteGeneratedCommandsNV - with its pname:isPreprocessed set to ename:VK_TRUE, then the - preprocessing step is skipped and data in this buffer will not be - modified. - The contents and the layout of this buffer are opaque to applications - and must: not be modified outside functions related to device-generated - commands or copied to another buffer for reuse. - * pname:preprocessOffset is the byte offset into pname:preprocessBuffer - where the preprocessed data is stored. - * pname:preprocessSize is the maximum byte size within the - pname:preprocessBuffer after the pname:preprocessOffset that is - available for preprocessing. - * pname:sequencesCountBuffer is a sname:VkBuffer in which the actual - number of sequences is provided as single code:uint32_t value. - * pname:sequencesCountOffset is the byte offset into - pname:sequencesCountBuffer where the count value is stored. - * pname:sequencesIndexBuffer is a sname:VkBuffer that encodes the used - sequence indices as code:uint32_t array. - * pname:sequencesIndexOffset is the byte offset into - pname:sequencesIndexBuffer where the index values start. - -.Valid Usage -**** - * [[VUID-VkGeneratedCommandsInfoNV-pipeline-02912]] - The provided pname:pipeline must: match the pipeline bound at execution - time - * [[VUID-VkGeneratedCommandsInfoNV-indirectCommandsLayout-02913]] - If the pname:indirectCommandsLayout uses a token of - ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_SHADER_GROUP_NV, then the - pname:pipeline must: have been created with multiple shader groups - * [[VUID-VkGeneratedCommandsInfoNV-indirectCommandsLayout-02914]] - If the pname:indirectCommandsLayout uses a token of - ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_SHADER_GROUP_NV, then the - pname:pipeline must: have been created with - ename:VK_PIPELINE_CREATE_INDIRECT_BINDABLE_BIT_NV set in - sname:VkGraphicsPipelineCreateInfo::pname:flags - * [[VUID-VkGeneratedCommandsInfoNV-indirectCommandsLayout-02915]] - If the pname:indirectCommandsLayout uses a token of - ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_CONSTANT_NV, then the - pname:pipeline's sname:VkPipelineLayout must: match the - slink:VkIndirectCommandsLayoutTokenNV::pname:pushconstantPipelineLayout - * [[VUID-VkGeneratedCommandsInfoNV-streamCount-02916]] - pname:streamCount must: match the pname:indirectCommandsLayout's - pname:streamCount -ifdef::VK_NV_device_generated_commands_compute[] - * [[VUID-VkGeneratedCommandsInfoNV-pipelineBindPoint-09084]] - If pname:pipelineBindPoint is of type - ename:VK_PIPELINE_BIND_POINT_COMPUTE, then the pname:pipeline must: have - been created with the flag - ename:VK_PIPELINE_CREATE_INDIRECT_BINDABLE_BIT_NV - * [[VUID-VkGeneratedCommandsInfoNV-pipelineBindPoint-09085]] - If pname:pipelineBindPoint is of type - ename:VK_PIPELINE_BIND_POINT_COMPUTE, then the pname:pipeline must: have - been created with a slink:VkComputePipelineIndirectBufferInfoNV - structure specifying a valid address where its metadata will be saved - * [[VUID-VkGeneratedCommandsInfoNV-pipelineBindPoint-09086]] - If pname:pipelineBindPoint is of type - ename:VK_PIPELINE_BIND_POINT_COMPUTE, then - flink:vkCmdUpdatePipelineIndirectBufferNV must: have been called on that - pipeline to save its metadata to a device address - * [[VUID-VkGeneratedCommandsInfoNV-pipelineBindPoint-09087]] - If pname:pipelineBindPoint is of type - ename:VK_PIPELINE_BIND_POINT_COMPUTE, and if - ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_PIPELINE_NV is used, then - pname:pipeline must: be dlink:VK_NULL_HANDLE -endif::VK_NV_device_generated_commands_compute[] - * [[VUID-VkGeneratedCommandsInfoNV-sequencesCount-02917]] - pname:sequencesCount must: be less or equal to - slink:VkPhysicalDeviceDeviceGeneratedCommandsPropertiesNV::pname:maxIndirectSequenceCount - and - slink:VkGeneratedCommandsMemoryRequirementsInfoNV::pname:maxSequencesCount - that was used to determine the pname:preprocessSize - * [[VUID-VkGeneratedCommandsInfoNV-preprocessBuffer-02918]] - pname:preprocessBuffer must: have the - ename:VK_BUFFER_USAGE_INDIRECT_BUFFER_BIT bit set in its usage flag - * [[VUID-VkGeneratedCommandsInfoNV-preprocessOffset-02919]] - pname:preprocessOffset must: be aligned to - slink:VkPhysicalDeviceDeviceGeneratedCommandsPropertiesNV::pname:minIndirectCommandsBufferOffsetAlignment - * [[VUID-VkGeneratedCommandsInfoNV-preprocessBuffer-02971]] - If pname:preprocessBuffer is non-sparse then it must: be bound - completely and contiguously to a single sname:VkDeviceMemory object - * [[VUID-VkGeneratedCommandsInfoNV-preprocessSize-02920]] - pname:preprocessSize must: be at least equal to the memory requirement`s - size returned by flink:vkGetGeneratedCommandsMemoryRequirementsNV using - the matching inputs (pname:indirectCommandsLayout, ...) as within this - structure - * [[VUID-VkGeneratedCommandsInfoNV-sequencesCountBuffer-02921]] - pname:sequencesCountBuffer can: be set if the actual used count of - sequences is sourced from the provided buffer. - In that case the pname:sequencesCount serves as upper bound - * [[VUID-VkGeneratedCommandsInfoNV-sequencesCountBuffer-02922]] - If pname:sequencesCountBuffer is not dlink:VK_NULL_HANDLE, its usage - flag must: have the ename:VK_BUFFER_USAGE_INDIRECT_BUFFER_BIT bit set - * [[VUID-VkGeneratedCommandsInfoNV-sequencesCountBuffer-02923]] - If pname:sequencesCountBuffer is not dlink:VK_NULL_HANDLE, - pname:sequencesCountOffset must: be aligned to - sname:VkPhysicalDeviceDeviceGeneratedCommandsPropertiesNV::pname:minSequencesCountBufferOffsetAlignment - * [[VUID-VkGeneratedCommandsInfoNV-sequencesCountBuffer-02972]] - If pname:sequencesCountBuffer is not dlink:VK_NULL_HANDLE and is - non-sparse then it must: be bound completely and contiguously to a - single sname:VkDeviceMemory object - * [[VUID-VkGeneratedCommandsInfoNV-sequencesIndexBuffer-02924]] - If pname:indirectCommandsLayout's - ename:VK_INDIRECT_COMMANDS_LAYOUT_USAGE_INDEXED_SEQUENCES_BIT_NV is set, - pname:sequencesIndexBuffer must: be set otherwise it must: be - dlink:VK_NULL_HANDLE - * [[VUID-VkGeneratedCommandsInfoNV-sequencesIndexBuffer-02925]] - If pname:sequencesIndexBuffer is not dlink:VK_NULL_HANDLE, its usage - flag must: have the ename:VK_BUFFER_USAGE_INDIRECT_BUFFER_BIT bit set - * [[VUID-VkGeneratedCommandsInfoNV-sequencesIndexBuffer-02926]] - If pname:sequencesIndexBuffer is not dlink:VK_NULL_HANDLE, - pname:sequencesIndexOffset must: be aligned to - sname:VkPhysicalDeviceDeviceGeneratedCommandsPropertiesNV::pname:minSequencesIndexBufferOffsetAlignment - * [[VUID-VkGeneratedCommandsInfoNV-sequencesIndexBuffer-02973]] - If pname:sequencesIndexBuffer is not dlink:VK_NULL_HANDLE and is - non-sparse then it must: be bound completely and contiguously to a - single sname:VkDeviceMemory object -ifdef::VK_NV_mesh_shader[] - * [[VUID-VkGeneratedCommandsInfoNV-indirectCommandsLayout-07078]] - If the pname:indirectCommandsLayout uses a token of - ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_TASKS_NV, then the - pname:pipeline must: contain a shader stage using the code:MeshNV - {ExecutionModel} -endif::VK_NV_mesh_shader[] -ifdef::VK_EXT_mesh_shader[] - * [[VUID-VkGeneratedCommandsInfoNV-indirectCommandsLayout-07079]] - If the pname:indirectCommandsLayout uses a token of - ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_NV, then the - pname:pipeline must: contain a shader stage using the code:MeshEXT - {ExecutionModel} -endif::VK_EXT_mesh_shader[] -**** - -include::{generated}/validity/structs/VkGeneratedCommandsInfoNV.adoc[] --- - -Referencing the functions defined in <>, -fname:vkCmdExecuteGeneratedCommandsNV behaves as: - -[source,c] ----- -uint32_t sequencesCount = sequencesCountBuffer ? - min(maxSequencesCount, sequencesCountBuffer.load_uint32(sequencesCountOffset) : - maxSequencesCount; - - -cmdProcessAllSequences(commandBuffer, pipeline, - indirectCommandsLayout, pIndirectCommandsStreams, - sequencesCount, - sequencesIndexBuffer, sequencesIndexOffset); - -// The stateful commands within indirectCommandsLayout will not -// affect the state of subsequent commands in the target -// command buffer (cmd) ----- - -[NOTE] -==== -It is important to note that the values of all state related to the -pname:pipelineBindPoint used are undefined: after this command. -==== - -[open,refpage='vkCmdPreprocessGeneratedCommandsNV',desc='Performs preprocessing for generated commands',type='protos'] --- -Commands can: be preprocessed prior execution using the following command: - -include::{generated}/api/protos/vkCmdPreprocessGeneratedCommandsNV.adoc[] - - * pname:commandBuffer is the command buffer which does the preprocessing. - * pname:pGeneratedCommandsInfo is a pointer to a - slink:VkGeneratedCommandsInfoNV structure containing parameters - affecting the preprocessing step. - -.Valid Usage -**** -ifdef::VK_VERSION_1_1[] - * [[VUID-vkCmdPreprocessGeneratedCommandsNV-commandBuffer-02974]] - pname:commandBuffer must: not be a protected command buffer -endif::VK_VERSION_1_1[] - * [[VUID-vkCmdPreprocessGeneratedCommandsNV-pGeneratedCommandsInfo-02927]] - pname:pGeneratedCommandsInfo`s pname:indirectCommandsLayout must: have - been created with the - ename:VK_INDIRECT_COMMANDS_LAYOUT_USAGE_EXPLICIT_PREPROCESS_BIT_NV bit - set - * [[VUID-vkCmdPreprocessGeneratedCommandsNV-deviceGeneratedCommands-02928]] - The <> - feature must: be enabled -**** - -include::{generated}/validity/protos/vkCmdPreprocessGeneratedCommandsNV.adoc[] --- - -ifdef::VK_NV_device_generated_commands_compute[] -The bound descriptor sets and push constants that will be used with indirect -command generation for the compute pipelines must: already be specified at -the time of preprocessing commands with -flink:vkCmdPreprocessGeneratedCommandsNV. -They must: not change until the execution of indirect commands is submitted -with flink:vkCmdExecuteGeneratedCommandsNV. - -If push constants for the compute pipeline are also specified in the -slink:VkGeneratedCommandsInfoNV::pname:indirectCommandsLayout with -ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_CONSTANT_NV token, then those -values override the push constants that were previously pushed for the -compute pipeline. - -endif::VK_NV_device_generated_commands_compute[] diff --git a/chapters/VK_NV_device_generated_commands/indirectcommands.adoc b/chapters/VK_NV_device_generated_commands/indirectcommands.adoc deleted file mode 100644 index e7f47a1de..000000000 --- a/chapters/VK_NV_device_generated_commands/indirectcommands.adoc +++ /dev/null @@ -1,747 +0,0 @@ -// Copyright (c) 2019-2020 NVIDIA Corporation -// -// SPDX-License-Identifier: CC-BY-4.0 - -[[indirectmdslayout]] -== Indirect Commands Layout - -[open,refpage='VkIndirectCommandsLayoutNV',desc='Opaque handle to an indirect commands layout object',type='handles'] --- -The device-side command generation happens through an iterative processing -of an atomic sequence comprised of command tokens, which are represented by: - -include::{generated}/api/handles/VkIndirectCommandsLayoutNV.adoc[] - -Each indirect command layout must: have exactly one action command token and -it must: be the last token in the sequence. --- - - -=== Creation and Deletion - -[open,refpage='vkCreateIndirectCommandsLayoutNV',desc='Create an indirect command layout object',type='protos'] --- -Indirect command layouts are created by: - -include::{generated}/api/protos/vkCreateIndirectCommandsLayoutNV.adoc[] - - * pname:device is the logical device that creates the indirect command - layout. - * pname:pCreateInfo is a pointer to a - slink:VkIndirectCommandsLayoutCreateInfoNV structure containing - parameters affecting creation of the indirect command layout. - * pname:pAllocator controls host memory allocation as described in the - <> chapter. - * pname:pIndirectCommandsLayout is a pointer to a - sname:VkIndirectCommandsLayoutNV handle in which the resulting indirect - command layout is returned. - -.Valid Usage -**** - * [[VUID-vkCreateIndirectCommandsLayoutNV-deviceGeneratedCommands-02929]] - The <> - feature must: be enabled -**** - -include::{generated}/validity/protos/vkCreateIndirectCommandsLayoutNV.adoc[] --- - -[open,refpage='VkIndirectCommandsLayoutCreateInfoNV',desc='Structure specifying the parameters of a newly created indirect commands layout object',type='structs'] --- -The sname:VkIndirectCommandsLayoutCreateInfoNV structure is defined as: - -include::{generated}/api/structs/VkIndirectCommandsLayoutCreateInfoNV.adoc[] - - * pname:sType is a elink:VkStructureType value identifying this structure. - * pname:pNext is `NULL` or a pointer to a structure extending this - structure. - * pname:pipelineBindPoint is the elink:VkPipelineBindPoint that this - layout targets. - * pname:flags is a bitmask of - elink:VkIndirectCommandsLayoutUsageFlagBitsNV specifying usage hints of - this layout. - * pname:tokenCount is the length of the individual command sequence. - * pname:pTokens is an array describing each command token in detail. - See elink:VkIndirectCommandsTokenTypeNV and - slink:VkIndirectCommandsLayoutTokenNV below for details. - * pname:streamCount is the number of streams used to provide the token - inputs. - * pname:pStreamStrides is an array defining the byte stride for each input - stream. - -The following code illustrates some of the flags: - -[source,c] ----- -void cmdProcessAllSequences(cmd, pipeline, indirectCommandsLayout, pIndirectCommandsTokens, sequencesCount, indexbuffer, indexbufferOffset) -{ - for (s = 0; s < sequencesCount; s++) - { - sUsed = s; - - if (indirectCommandsLayout.flags & VK_INDIRECT_COMMANDS_LAYOUT_USAGE_INDEXED_SEQUENCES_BIT_NV) { - sUsed = indexbuffer.load_uint32( sUsed * sizeof(uint32_t) + indexbufferOffset); - } - - if (indirectCommandsLayout.flags & VK_INDIRECT_COMMANDS_LAYOUT_USAGE_UNORDERED_SEQUENCES_BIT_NV) { - sUsed = incoherent_implementation_dependent_permutation[ sUsed ]; - } - - cmdProcessSequence( cmd, pipeline, indirectCommandsLayout, pIndirectCommandsTokens, sUsed ); - } -} ----- - -When tokens are consumed, an offset is computed based on token offset and -stream stride. -The resulting offset is required to be aligned. -The alignment for a specific token is equal to the scalar alignment of the -data type as defined in <>, or -sname:VkPhysicalDeviceDeviceGeneratedCommandsPropertiesNV::pname:minIndirectCommandsBufferOffsetAlignment, -whichever is lower. - -[NOTE] -==== -A pname:minIndirectCommandsBufferOffsetAlignment of 4 allows -basetype:VkDeviceAddress to be packed as code:uvec2 with scalar layout -instead of code:uint64_t with 8 byte alignment. -This enables direct compatibility with D3D12 command signature layouts. -==== - -.Valid Usage -**** - * [[VUID-VkIndirectCommandsLayoutCreateInfoNV-pipelineBindPoint-02930]] - The pname:pipelineBindPoint must: be - ename:VK_PIPELINE_BIND_POINT_GRAPHICS -ifdef::VK_NV_device_generated_commands_compute[] - or ename:VK_PIPELINE_BIND_POINT_COMPUTE -endif::VK_NV_device_generated_commands_compute[] - * [[VUID-VkIndirectCommandsLayoutCreateInfoNV-tokenCount-02931]] - pname:tokenCount must: be greater than `0` and less than or equal to - sname:VkPhysicalDeviceDeviceGeneratedCommandsPropertiesNV::pname:maxIndirectCommandsTokenCount - * [[VUID-VkIndirectCommandsLayoutCreateInfoNV-pTokens-02932]] - If pname:pTokens contains an entry of - ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_SHADER_GROUP_NV it must: be the - first element of the array and there must: be only a single element of - such token type -ifdef::VK_NV_device_generated_commands_compute[] - * [[VUID-VkIndirectCommandsLayoutCreateInfoNV-pTokens-09585]] - If pname:pTokens contains an entry of - ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_PIPELINE_NV it must: be the first - element of the array and there must: be only a single element of such - token type -endif::VK_NV_device_generated_commands_compute[] - * [[VUID-VkIndirectCommandsLayoutCreateInfoNV-pTokens-02933]] - If pname:pTokens contains an entry of - ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_STATE_FLAGS_NV there must: be only - a single element of such token type - * [[VUID-VkIndirectCommandsLayoutCreateInfoNV-pTokens-02934]] - All state tokens in pname:pTokens must: occur before any action command - tokens (ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_NV, - ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_INDEXED_NV, - ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_TASKS_NV, - ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_NV -ifdef::VK_NV_device_generated_commands_compute[] - , ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_DISPATCH_NV -endif::VK_NV_device_generated_commands_compute[] - ) - * [[VUID-VkIndirectCommandsLayoutCreateInfoNV-pTokens-02935]] - The content of pname:pTokens must: include one single action command - token that is compatible with the pname:pipelineBindPoint - * [[VUID-VkIndirectCommandsLayoutCreateInfoNV-streamCount-02936]] - pname:streamCount must: be greater than `0` and less or equal to - sname:VkPhysicalDeviceDeviceGeneratedCommandsPropertiesNV::pname:maxIndirectCommandsStreamCount - * [[VUID-VkIndirectCommandsLayoutCreateInfoNV-pStreamStrides-02937]] - each element of pname:pStreamStrides must: be greater than `0` and less - than or equal to - sname:VkPhysicalDeviceDeviceGeneratedCommandsPropertiesNV::pname:maxIndirectCommandsStreamStride. - Furthermore the alignment of each token input must: be ensured -ifdef::VK_NV_device_generated_commands_compute[] - * [[VUID-VkIndirectCommandsLayoutCreateInfoNV-pipelineBindPoint-09088]] - If pname:pipelineBindPoint is ename:VK_PIPELINE_BIND_POINT_COMPUTE then - the <> - feature must: be enabled - * [[VUID-VkIndirectCommandsLayoutCreateInfoNV-pipelineBindPoint-09089]] - If pname:pipelineBindPoint is ename:VK_PIPELINE_BIND_POINT_COMPUTE then - the state tokens in pname:pTokens must: only include - ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_DISPATCH_NV, - ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_PIPELINE_NV, or - ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_CONSTANT_NV - * [[VUID-VkIndirectCommandsLayoutCreateInfoNV-pipelineBindPoint-09090]] - If pname:pipelineBindPoint is ename:VK_PIPELINE_BIND_POINT_COMPUTE and - pname:pTokens includes - ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_PIPELINE_NV, then the - <> - feature must: be enabled -endif::VK_NV_device_generated_commands_compute[] -**** - -include::{generated}/validity/structs/VkIndirectCommandsLayoutCreateInfoNV.adoc[] --- - -[open,refpage='VkIndirectCommandsLayoutUsageFlagBitsNV',desc='Bitmask specifying allowed usage of an indirect commands layout',type='enums'] --- -Bits which can: be set in -slink:VkIndirectCommandsLayoutCreateInfoNV::pname:flags, specifying usage -hints of an indirect command layout, are: - -include::{generated}/api/enums/VkIndirectCommandsLayoutUsageFlagBitsNV.adoc[] - - * ename:VK_INDIRECT_COMMANDS_LAYOUT_USAGE_EXPLICIT_PREPROCESS_BIT_NV - specifies that the layout is always used with the manual preprocessing - step through calling flink:vkCmdPreprocessGeneratedCommandsNV and - executed by flink:vkCmdExecuteGeneratedCommandsNV with `isPreprocessed` - set to ename:VK_TRUE. - * ename:VK_INDIRECT_COMMANDS_LAYOUT_USAGE_INDEXED_SEQUENCES_BIT_NV - specifies that the input data for the sequences is not implicitly - indexed from 0..sequencesUsed, but an application-provided - sname:VkBuffer encoding the index is provided. - * ename:VK_INDIRECT_COMMANDS_LAYOUT_USAGE_UNORDERED_SEQUENCES_BIT_NV - specifies that the processing of sequences can: happen at an - implementation-dependent order, which is not: guaranteed to be coherent - using the same input data. -ifdef::VK_NV_device_generated_commands_compute[] - This flag is ignored when the pname:pipelineBindPoint is - ename:VK_PIPELINE_BIND_POINT_COMPUTE as it is implied that the dispatch - sequence is always unordered. -endif::VK_NV_device_generated_commands_compute[] --- - -[open,refpage='VkIndirectCommandsLayoutUsageFlagsNV',desc='Bitmask of VkIndirectCommandsLayoutUsageFlagBitsNV',type='flags'] --- -include::{generated}/api/flags/VkIndirectCommandsLayoutUsageFlagsNV.adoc[] - -tname:VkIndirectCommandsLayoutUsageFlagsNV is a bitmask type for setting a -mask of zero or more elink:VkIndirectCommandsLayoutUsageFlagBitsNV. --- - -[open,refpage='vkDestroyIndirectCommandsLayoutNV',desc='Destroy an indirect commands layout',type='protos'] --- -Indirect command layouts are destroyed by: - -include::{generated}/api/protos/vkDestroyIndirectCommandsLayoutNV.adoc[] - - * pname:device is the logical device that destroys the layout. - * pname:indirectCommandsLayout is the layout to destroy. - * pname:pAllocator controls host memory allocation as described in the - <> chapter. - -.Valid Usage -**** - * [[VUID-vkDestroyIndirectCommandsLayoutNV-indirectCommandsLayout-02938]] - All submitted commands that refer to pname:indirectCommandsLayout must: - have completed execution -ifndef::VKSC_VERSION_1_0[] - * [[VUID-vkDestroyIndirectCommandsLayoutNV-indirectCommandsLayout-02939]] - If sname:VkAllocationCallbacks were provided when - pname:indirectCommandsLayout was created, a compatible set of callbacks - must: be provided here - * [[VUID-vkDestroyIndirectCommandsLayoutNV-indirectCommandsLayout-02940]] - If no sname:VkAllocationCallbacks were provided when - pname:indirectCommandsLayout was created, pname:pAllocator must: be - `NULL` -endif::VKSC_VERSION_1_0[] - * [[VUID-vkDestroyIndirectCommandsLayoutNV-deviceGeneratedCommands-02941]] - The <> - feature must: be enabled -**** - -include::{generated}/validity/protos/vkDestroyIndirectCommandsLayoutNV.adoc[] --- - - -=== Token Input Streams - -[open,refpage='VkIndirectCommandsStreamNV',desc='Structure specifying input streams for generated command tokens',type='structs'] --- -The sname:VkIndirectCommandsStreamNV structure specifies the input data for -one or more tokens at processing time. - -include::{generated}/api/structs/VkIndirectCommandsStreamNV.adoc[] - - * pname:buffer specifies the slink:VkBuffer storing the functional - arguments for each sequence. - These arguments can: be written by the device. - * pname:offset specified an offset into pname:buffer where the arguments - start. - -.Valid Usage -**** - * [[VUID-VkIndirectCommandsStreamNV-buffer-02942]] - The pname:buffer's usage flag must: have the - ename:VK_BUFFER_USAGE_INDIRECT_BUFFER_BIT bit set - * [[VUID-VkIndirectCommandsStreamNV-offset-02943]] - The pname:offset must: be aligned to - sname:VkPhysicalDeviceDeviceGeneratedCommandsPropertiesNV::pname:minIndirectCommandsBufferOffsetAlignment - * [[VUID-VkIndirectCommandsStreamNV-buffer-02975]] - If pname:buffer is non-sparse then it must: be bound completely and - contiguously to a single sname:VkDeviceMemory object -**** - -include::{generated}/validity/structs/VkIndirectCommandsStreamNV.adoc[] --- - -The input streams can: contain raw `uint32_t` values, existing indirect -commands such as: - - * slink:VkDrawIndirectCommand - * slink:VkDrawIndexedIndirectCommand -ifdef::VK_NV_mesh_shader[] - * slink:VkDrawMeshTasksIndirectCommandNV -endif::VK_NV_mesh_shader[] -ifdef::VK_EXT_mesh_shader[] - * slink:VkDrawMeshTasksIndirectCommandEXT -endif::VK_EXT_mesh_shader[] -ifdef::VK_NV_device_generated_commands_compute[] - * slink:VkDispatchIndirectCommand -endif::VK_NV_device_generated_commands_compute[] - -or additional commands as listed below. -How the data is used is described in the next section. - -[open,refpage='VkBindShaderGroupIndirectCommandNV',desc='Structure specifying input data for a single shader group command token',type='structs'] --- -The sname:VkBindShaderGroupIndirectCommandNV structure specifies the input -data for the ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_SHADER_GROUP_NV token. - -include::{generated}/api/structs/VkBindShaderGroupIndirectCommandNV.adoc[] - - * pname:groupIndex specifies which shader group of the current bound - graphics pipeline is used. - -.Valid Usage -**** - * [[VUID-VkBindShaderGroupIndirectCommandNV-None-02944]] - The current bound graphics pipeline, as well as the pipelines it may - reference, must: have been created with - ename:VK_PIPELINE_CREATE_INDIRECT_BINDABLE_BIT_NV - * [[VUID-VkBindShaderGroupIndirectCommandNV-index-02945]] - The pname:index must: be within range of the accessible shader groups of - the current bound graphics pipeline. - See flink:vkCmdBindPipelineShaderGroupNV for further details -**** - -include::{generated}/validity/structs/VkBindShaderGroupIndirectCommandNV.adoc[] --- - -[open,refpage='VkBindIndexBufferIndirectCommandNV',desc='Structure specifying input data for a single index buffer command token',type='structs'] --- -The sname:VkBindIndexBufferIndirectCommandNV structure specifies the input -data for the ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_INDEX_BUFFER_NV token. - -include::{generated}/api/structs/VkBindIndexBufferIndirectCommandNV.adoc[] - - * pname:bufferAddress specifies a physical address of the slink:VkBuffer - used as index buffer. - * pname:size is the byte size range which is available for this operation - from the provided address. - * pname:indexType is a elink:VkIndexType value specifying how indices are - treated. - Instead of the Vulkan enum values, a custom `uint32_t` value can: be - mapped to elink:VkIndexType by specifying the - sname:VkIndirectCommandsLayoutTokenNV::pname:pIndexTypes and - sname:VkIndirectCommandsLayoutTokenNV::pname:pIndexTypeValues arrays. - -.Valid Usage -**** - * [[VUID-VkBindIndexBufferIndirectCommandNV-None-02946]] - The buffer's usage flag from which the address was acquired must: have - the ename:VK_BUFFER_USAGE_INDEX_BUFFER_BIT bit set - * [[VUID-VkBindIndexBufferIndirectCommandNV-bufferAddress-02947]] - The pname:bufferAddress must: be aligned to the pname:indexType used - * [[VUID-VkBindIndexBufferIndirectCommandNV-None-02948]] - Each element of the buffer from which the address was acquired and that - is non-sparse must: be bound completely and contiguously to a single - sname:VkDeviceMemory object -**** - -include::{generated}/validity/structs/VkBindIndexBufferIndirectCommandNV.adoc[] --- - -[open,refpage='VkBindVertexBufferIndirectCommandNV',desc='Structure specifying input data for a single vertex buffer command token',type='structs'] --- -The sname:VkBindVertexBufferIndirectCommandNV structure specifies the input -data for the ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_VERTEX_BUFFER_NV token. - -include::{generated}/api/structs/VkBindVertexBufferIndirectCommandNV.adoc[] - - * pname:bufferAddress specifies a physical address of the slink:VkBuffer - used as vertex input binding. - * pname:size is the byte size range which is available for this operation - from the provided address. - * pname:stride is the byte size stride for this vertex input binding as in - sname:VkVertexInputBindingDescription::pname:stride. - It is only used if - sname:VkIndirectCommandsLayoutTokenNV::pname:vertexDynamicStride was - set, otherwise the stride is inherited from the current bound graphics - pipeline. - -.Valid Usage -**** - * [[VUID-VkBindVertexBufferIndirectCommandNV-None-02949]] - The buffer's usage flag from which the address was acquired must: have - the ename:VK_BUFFER_USAGE_VERTEX_BUFFER_BIT bit set - * [[VUID-VkBindVertexBufferIndirectCommandNV-None-02950]] - Each element of the buffer from which the address was acquired and that - is non-sparse must: be bound completely and contiguously to a single - sname:VkDeviceMemory object -**** - -include::{generated}/validity/structs/VkBindVertexBufferIndirectCommandNV.adoc[] --- - -[open,refpage='VkSetStateFlagsIndirectCommandNV',desc='Structure specifying input data for a single state flag command token',type='structs'] --- -The sname:VkSetStateFlagsIndirectCommandNV structure specifies the input -data for the ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_STATE_FLAGS_NV token. -Which state is changed depends on the elink:VkIndirectStateFlagBitsNV -specified at sname:VkIndirectCommandsLayoutNV creation time. - -include::{generated}/api/structs/VkSetStateFlagsIndirectCommandNV.adoc[] - - * pname:data encodes packed state that this command alters. - ** Bit `0`: If set represents ename:VK_FRONT_FACE_CLOCKWISE, otherwise - ename:VK_FRONT_FACE_COUNTER_CLOCKWISE - -include::{generated}/validity/structs/VkSetStateFlagsIndirectCommandNV.adoc[] --- - -[open,refpage='VkIndirectStateFlagBitsNV',desc='Bitmask specifying state that can be altered on the device',type='enums'] --- -A subset of the graphics pipeline state can: be altered using indirect state -flags: - -include::{generated}/api/enums/VkIndirectStateFlagBitsNV.adoc[] - - * ename:VK_INDIRECT_STATE_FLAG_FRONTFACE_BIT_NV allows to toggle the - elink:VkFrontFace rasterization state for subsequent drawing commands. --- - -[open,refpage='VkIndirectStateFlagsNV',desc='Bitmask of VkIndirectStateFlagBitsNV',type='flags'] --- -include::{generated}/api/flags/VkIndirectStateFlagsNV.adoc[] - -tname:VkIndirectStateFlagsNV is a bitmask type for setting a mask of zero or -more elink:VkIndirectStateFlagBitsNV. --- - -[open,refpage='VkBindPipelineIndirectCommandNV',desc='Structure specifying input data for the compute pipeline dispatch token',type='structs'] --- -The sname:VkBindPipelineIndirectCommandNV structure specifies the input data -for the ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_PIPELINE_NV token. - -include::{generated}/api/structs/VkBindPipelineIndirectCommandNV.adoc[] - - * pname:pipelineAddress specifies the pipeline address of the compute - pipeline that will be used in device generated rendering. - -.Valid Usage -**** - * [[VUID-VkBindPipelineIndirectCommandNV-deviceGeneratedComputePipelines-09091]] - The <> - feature must: be enabled - * [[VUID-VkBindPipelineIndirectCommandNV-None-09092]] - The referenced pipeline must: have been created with - ename:VK_PIPELINE_CREATE_INDIRECT_BINDABLE_BIT_NV - * [[VUID-VkBindPipelineIndirectCommandNV-None-09093]] - The referenced pipeline must: have been updated with - flink:vkCmdUpdatePipelineIndirectBufferNV - * [[VUID-VkBindPipelineIndirectCommandNV-None-09094]] - The referenced pipeline's address must: have been queried with - flink:vkGetPipelineIndirectDeviceAddressNV -**** - -include::{generated}/validity/structs/VkBindPipelineIndirectCommandNV.adoc[] --- - - -=== Tokenized Command Processing - -The processing is in principle illustrated below: - -[source,c] ----- -void cmdProcessSequence(cmd, pipeline, indirectCommandsLayout, pIndirectCommandsStreams, s) -{ - for (t = 0; t < indirectCommandsLayout.tokenCount; t++) - { - uint32_t stream = indirectCommandsLayout.pTokens[t].stream; - uint32_t offset = indirectCommandsLayout.pTokens[t].offset; - uint32_t stride = indirectCommandsLayout.pStreamStrides[stream]; - stream = pIndirectCommandsStreams[stream]; - const void* input = stream.buffer.pointer( stream.offset + stride * s + offset ) - - // further details later - indirectCommandsLayout.pTokens[t].command (cmd, pipeline, input, s); - } -} - -void cmdProcessAllSequences(cmd, pipeline, indirectCommandsLayout, pIndirectCommandsStreams, sequencesCount) -{ - for (s = 0; s < sequencesCount; s++) - { - cmdProcessSequence(cmd, pipeline, indirectCommandsLayout, pIndirectCommandsStreams, s); - } -} ----- - -The processing of each sequence is considered stateless, therefore all state -changes must: occur before any action command tokens within the sequence. -A single sequence is strictly targeting the elink:VkPipelineBindPoint it was -created with. - -The primary input data for each token is provided through sname:VkBuffer -content at preprocessing using flink:vkCmdPreprocessGeneratedCommandsNV or -execution time using flink:vkCmdExecuteGeneratedCommandsNV, however some -functional arguments, for example binding sets, are specified at layout -creation time. -The input size is different for each token. - -[open,refpage='VkIndirectCommandsTokenTypeNV',desc='Enum specifying token commands',type='enums'] --- -Possible values of those elements of the -slink:VkIndirectCommandsLayoutCreateInfoNV::pname:pTokens array specifying -command tokens (other elements of the array specify command parameters) are: - -include::{generated}/api/enums/VkIndirectCommandsTokenTypeNV.adoc[] - -.Supported indirect command tokens -[width="80%",cols="67%,33%",options="header",align="center"] -|==== -|Token type | Equivalent command -|ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_SHADER_GROUP_NV | flink:vkCmdBindPipelineShaderGroupNV -|ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_STATE_FLAGS_NV | - -|ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_INDEX_BUFFER_NV | flink:vkCmdBindIndexBuffer -|ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_VERTEX_BUFFER_NV | flink:vkCmdBindVertexBuffers -|ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_CONSTANT_NV | flink:vkCmdPushConstants -|ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_INDEXED_NV | flink:vkCmdDrawIndexedIndirect -|ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_NV | flink:vkCmdDrawIndirect -ifdef::VK_NV_mesh_shader[] -|ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_TASKS_NV | flink:vkCmdDrawMeshTasksIndirectNV -endif::VK_NV_mesh_shader[] -ifdef::VK_EXT_mesh_shader[] -|ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_NV | flink:vkCmdDrawMeshTasksIndirectEXT -endif::VK_EXT_mesh_shader[] -ifdef::VK_NV_device_generated_commands_compute[] -|ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_PIPELINE_NV | flink:vkCmdBindPipeline -|ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_DISPATCH_NV | flink:vkCmdDispatchIndirect -endif::VK_NV_device_generated_commands_compute[] -|==== --- - -[open,refpage='VkIndirectCommandsLayoutTokenNV',desc='Struct specifying the details of an indirect command layout token',type='structs'] --- -The sname:VkIndirectCommandsLayoutTokenNV structure specifies details to the -function arguments that need to be known at layout creation time: - -include::{generated}/api/structs/VkIndirectCommandsLayoutTokenNV.adoc[] - - * pname:sType is a elink:VkStructureType value identifying this structure. - * pname:pNext is `NULL` or a pointer to a structure extending this - structure. - * pname:tokenType is a elink:VkIndirectCommandsTokenTypeNV specifying the - token command type. - * pname:stream is the index of the input stream containing the token - argument data. - * pname:offset is a relative starting offset within the input stream - memory for the token argument data. - * pname:vertexBindingUnit is used for the vertex buffer binding command. - * pname:vertexDynamicStride sets if the vertex buffer stride is provided - by the binding command rather than the current bound graphics pipeline - state. - * pname:pushconstantPipelineLayout is the sname:VkPipelineLayout used for - the push constant command. - * pname:pushconstantShaderStageFlags are the shader stage flags used for - the push constant command. - * pname:pushconstantOffset is the offset used for the push constant - command. - * pname:pushconstantSize is the size used for the push constant command. - * pname:indirectStateFlags is a tlink:VkIndirectStateFlagsNV bitfield - indicating the active states for the state flag command. - * pname:indexTypeCount is the optional size of the pname:pIndexTypes and - pname:pIndexTypeValues array pairings. - If not zero, it allows to register a custom `uint32_t` value to be - treated as specific elink:VkIndexType. - * pname:pIndexTypes is the used elink:VkIndexType for the corresponding - `uint32_t` value entry in pname:pIndexTypeValues. - -.Valid Usage -**** - * [[VUID-VkIndirectCommandsLayoutTokenNV-stream-02951]] - pname:stream must: be smaller than - sname:VkIndirectCommandsLayoutCreateInfoNV::pname:streamCount - * [[VUID-VkIndirectCommandsLayoutTokenNV-offset-02952]] - pname:offset must: be less than or equal to - sname:VkPhysicalDeviceDeviceGeneratedCommandsPropertiesNV::pname:maxIndirectCommandsTokenOffset - * [[VUID-VkIndirectCommandsLayoutTokenNV-offset-06888]] - pname:offset must: be aligned to the scalar alignment of pname:tokenType - or pname:minIndirectCommandsBufferOffsetAlignment, whichever is lower - * [[VUID-VkIndirectCommandsLayoutTokenNV-tokenType-02976]] - If pname:tokenType is - ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_VERTEX_BUFFER_NV, - pname:vertexBindingUnit must: stay within device supported limits for - the appropriate commands - * [[VUID-VkIndirectCommandsLayoutTokenNV-tokenType-02977]] - If pname:tokenType is - ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_CONSTANT_NV, - pname:pushconstantPipelineLayout must: be valid - * [[VUID-VkIndirectCommandsLayoutTokenNV-tokenType-02978]] - If pname:tokenType is - ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_CONSTANT_NV, - pname:pushconstantOffset must: be a multiple of `4` - * [[VUID-VkIndirectCommandsLayoutTokenNV-tokenType-02979]] - If pname:tokenType is - ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_CONSTANT_NV, - pname:pushconstantSize must: be a multiple of `4` - * [[VUID-VkIndirectCommandsLayoutTokenNV-tokenType-02980]] - If pname:tokenType is - ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_CONSTANT_NV, - pname:pushconstantOffset must: be less than - sname:VkPhysicalDeviceLimits::pname:maxPushConstantsSize - * [[VUID-VkIndirectCommandsLayoutTokenNV-tokenType-02981]] - If pname:tokenType is - ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_CONSTANT_NV, - pname:pushconstantSize must: be less than or equal to - sname:VkPhysicalDeviceLimits::pname:maxPushConstantsSize minus - pname:pushconstantOffset - * [[VUID-VkIndirectCommandsLayoutTokenNV-tokenType-02982]] - If pname:tokenType is - ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_CONSTANT_NV, for each byte in - the range specified by pname:pushconstantOffset and - pname:pushconstantSize and for each shader stage in - pname:pushconstantShaderStageFlags, there must: be a push constant range - in pname:pushconstantPipelineLayout that includes that byte and that - stage - * [[VUID-VkIndirectCommandsLayoutTokenNV-tokenType-02983]] - If pname:tokenType is - ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_CONSTANT_NV, for each byte in - the range specified by pname:pushconstantOffset and - pname:pushconstantSize and for each push constant range that overlaps - that byte, pname:pushconstantShaderStageFlags must: include all stages - in that push constant range's - slink:VkPushConstantRange::pname:stageFlags - * [[VUID-VkIndirectCommandsLayoutTokenNV-tokenType-02984]] - If pname:tokenType is - ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_STATE_FLAGS_NV, - pname:indirectStateFlags must: not be `0` -**** - -include::{generated}/validity/structs/VkIndirectCommandsLayoutTokenNV.adoc[] --- - -The following code provides detailed information on how an individual -sequence is processed. -For valid usage, all restrictions from the regular commands apply. - -[source,c] ----- -void cmdProcessSequence(cmd, pipeline, indirectCommandsLayout, pIndirectCommandsStreams, s) -{ - for (uint32_t t = 0; t < indirectCommandsLayout.tokenCount; t++){ - token = indirectCommandsLayout.pTokens[t]; - - uint32_t stride = indirectCommandsLayout.pStreamStrides[token.stream]; - stream = pIndirectCommandsStreams[token.stream]; - uint32_t offset = stream.offset + stride * s + token.offset; - const void* input = stream.buffer.pointer( offset ) - - switch(input.type){ - case VK_INDIRECT_COMMANDS_TOKEN_TYPE_SHADER_GROUP_NV: - VkBindShaderGroupIndirectCommandNV* bind = input; - - vkCmdBindPipelineShaderGroupNV(cmd, indirectCommandsLayout.pipelineBindPoint, - pipeline, bind->groupIndex); - break; - - case VK_INDIRECT_COMMANDS_TOKEN_TYPE_STATE_FLAGS_NV: - VkSetStateFlagsIndirectCommandNV* state = input; - - if (token.indirectStateFlags & VK_INDIRECT_STATE_FLAG_FRONTFACE_BIT_NV){ - if (state.data & (1 << 0)){ - set VK_FRONT_FACE_CLOCKWISE; - } else { - set VK_FRONT_FACE_COUNTER_CLOCKWISE; - } - } - break; - - case VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_CONSTANT_NV: - uint32_t* data = input; - - vkCmdPushConstants(cmd, - token.pushconstantPipelineLayout - token.pushconstantStageFlags, - token.pushconstantOffset, - token.pushconstantSize, data); - break; - - case VK_INDIRECT_COMMANDS_TOKEN_TYPE_INDEX_BUFFER_NV: - VkBindIndexBufferIndirectCommandNV* data = input; - - // the indexType may optionally be remapped - // from a custom uint32_t value, via - // VkIndirectCommandsLayoutTokenNV::pIndexTypeValues - - vkCmdBindIndexBuffer(cmd, - deriveBuffer(data->bufferAddress), - deriveOffset(data->bufferAddress), - data->indexType); - break; - - case VK_INDIRECT_COMMANDS_TOKEN_TYPE_VERTEX_BUFFER_NV: - VkBindVertexBufferIndirectCommandNV* data = input; - - // if token.vertexDynamicStride is VK_TRUE - // then the stride for this binding is set - // using data->stride as well - - vkCmdBindVertexBuffers(cmd, - token.vertexBindingUnit, 1, - &deriveBuffer(data->bufferAddress), - &deriveOffset(data->bufferAddress)); - break; - - case VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_INDEXED_NV: - vkCmdDrawIndexedIndirect(cmd, - stream.buffer, offset, 1, 0); - break; - - case VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_NV: - vkCmdDrawIndirect(cmd, - stream.buffer, - offset, 1, 0); - break; - - // only available if VK_NV_mesh_shader is supported - case VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_TASKS_NV: - vkCmdDrawMeshTasksIndirectNV(cmd, - stream.buffer, offset, 1, 0); - break; - - // only available if VK_EXT_mesh_shader is supported - case VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_NV: - vkCmdDrawMeshTasksIndirectEXT(cmd, - stream.buffer, offset, 1, 0); - break; - -ifdef::VK_NV_device_generated_commands_compute[] - case VK_INDIRECT_COMMANDS_TOKEN_TYPE_PIPELINE_NV: - VkBindPipelineIndirectCommandNV *data = input; - VkPipeline computePipeline = deriveFromDeviceAddress(data->pipelineAddress); - vkCmdBindPipeline(cmd, VK_PIPELINE_BIND_POINT_COMPUTE, computePipeline); - break; - - case VK_INDIRECT_COMMANDS_TOKEN_TYPE_DISPATCH_NV: - vkCmdDispatchIndirect(cmd, stream.buffer, offset); - break; -endif::VK_NV_device_generated_commands_compute[] - } - } -} ----- diff --git a/chapters/capabilities.adoc b/chapters/capabilities.adoc index 5d0beec49..8d6c63f7e 100644 --- a/chapters/capabilities.adoc +++ b/chapters/capabilities.adoc @@ -536,7 +536,7 @@ underlying physical device and/or the same driver version, as defined in the following table: [[external-memory-handle-types-compatibility]] -.External memory handle types compatibility +.External Memory Handle Types Compatibility |==== | Handle type | sname:VkPhysicalDeviceIDProperties{wbro}::pname:driverUUID | sname:VkPhysicalDeviceIDProperties{wbro}::pname:deviceUUID | ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_FD_BIT | Must match | Must match @@ -1429,7 +1429,7 @@ underlying physical device and/or the same driver version, as defined in the following table: [[external-semaphore-handle-types-compatibility]] -.External semaphore handle types compatibility +.External Semaphore Handle Types Compatibility |==== | Handle type | sname:VkPhysicalDeviceIDProperties{wbro}::pname:driverUUID | sname:VkPhysicalDeviceIDProperties{wbro}::pname:deviceUUID | ename:VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_FD_BIT | Must match | Must match @@ -1660,7 +1660,7 @@ underlying physical device and/or the same driver version, as defined in the following table: [[external-fence-handle-types-compatibility]] -.External fence handle types compatibility +.External Fence Handle Types Compatibility |==== | Handle type | sname:VkPhysicalDeviceIDProperties{wbro}::pname:driverUUID | sname:VkPhysicalDeviceIDProperties{wbro}::pname:deviceUUID | ename:VK_EXTERNAL_FENCE_HANDLE_TYPE_OPAQUE_FD_BIT | Must match | Must match diff --git a/chapters/cmdbuffers.adoc b/chapters/cmdbuffers.adoc index 85edae26e..97f5961c8 100644 --- a/chapters/cmdbuffers.adoc +++ b/chapters/cmdbuffers.adoc @@ -1563,10 +1563,10 @@ Once recording starts, an application records a sequence of commands (ftext:vkCmd*) to set state in the command buffer, draw, dispatch, and other commands. -ifdef::VK_NV_device_generated_commands[] +ifdef::VK_NV_device_generated_commands,VK_EXT_device_generated_commands[] Several commands can also be recorded indirectly from sname:VkBuffer content, see <>. -endif::VK_NV_device_generated_commands[] +endif::VK_NV_device_generated_commands,VK_EXT_device_generated_commands[] [open,refpage='vkEndCommandBuffer',desc='Finish recording a command buffer',type='protos'] -- diff --git a/chapters/commonvalidity/compute_graph_pipeline_create_info_common.adoc b/chapters/commonvalidity/compute_graph_pipeline_create_info_common.adoc index 1369a84f7..27d5f2463 100644 --- a/chapters/commonvalidity/compute_graph_pipeline_create_info_common.adoc +++ b/chapters/commonvalidity/compute_graph_pipeline_create_info_common.adoc @@ -50,6 +50,13 @@ ifdef::VK_NV_device_generated_commands_compute[] the pipeline's metadata will be saved endif::VK_NV_device_generated_commands_compute[] endif::VK_NV_device_generated_commands[] +ifdef::VK_EXT_device_generated_commands[] + * [[VUID-{refpage}-flags-11007]] + If pname:flags includes + ename:VK_PIPELINE_CREATE_2_INDIRECT_BINDABLE_BIT_EXT, then the + <> + feature must: be enabled +endif::VK_EXT_device_generated_commands[] ifdef::VK_VERSION_1_3,VK_EXT_pipeline_creation_cache_control[] * [[VUID-{refpage}-pipelineCreationCacheControl-02875]] If the <> of + pname:viewportWScalingEnable is ename:VK_TRUE, then flink:vkCmdSetViewportWScalingNV must: have been called and not subsequently <> in the current command buffer prior to this drawing command * [[VUID-{refpage}-None-08636]] - If the `apiext:VK_NV_clip_space_w_scaling` extension is enabled, and a - shader object is bound to any graphics stage, and the most recent call - to flink:vkCmdSetViewportWScalingEnableNV in the current command buffer - set pname:viewportWScalingEnable to ename:VK_TRUE, then the + If the `apiext:VK_NV_clip_space_w_scaling` extension is enabled, and +ifdef::VK_EXT_shader_object[] + a shader object is bound to any graphics stage or +endif::VK_EXT_shader_object[] + a graphics pipeline is bound which was created with the + ename:VK_DYNAMIC_STATE_VIEWPORT_WITH_COUNT and + ename:VK_DYNAMIC_STATE_VIEWPORT_W_SCALING_NV dynamic state enabled, the + <> of + pname:viewportWScalingEnable is ename:VK_TRUE, then the pname:viewportCount parameter in the last call to flink:vkCmdSetViewportWScalingNV must: be greater than or equal to the pname:viewportCount parameter in the last call to flink:vkCmdSetViewportWithCount -endif::VK_EXT_shader_object[] endif::VK_NV_clip_space_w_scaling[] ifdef::VK_NV_shading_rate_image[] * [[VUID-{refpage}-viewportCount-04139]] @@ -526,46 +526,52 @@ ifdef::VK_NV_shading_rate_image[] slink:VkPipelineViewportShadingRateImageStateCreateInfoNV::pname:viewportCount greater or equal to the pname:viewportCount parameter in the last call to flink:vkCmdSetViewportWithCount - * [[VUID-{refpage}-viewportCount-04140]] - If the bound graphics pipeline state was created with the - ename:VK_DYNAMIC_STATE_VIEWPORT_WITH_COUNT and - ename:VK_DYNAMIC_STATE_VIEWPORT_SHADING_RATE_PALETTE_NV dynamic states - enabled then the pname:viewportCount parameter in the last call to - flink:vkCmdSetViewportShadingRatePaletteNV must: be greater than or - equal to the pname:viewportCount parameter in the last call to - flink:vkCmdSetViewportWithCount -ifdef::VK_EXT_shader_object[] * [[VUID-{refpage}-shadingRateImage-09233]] If the <> feature is - enabled, and a shader object is bound to any graphics stage, and the - most recent call to flink:vkCmdSetRasterizerDiscardEnable in the current - command buffer set pname:rasterizerDiscardEnable to ename:VK_FALSE, then + enabled, and +ifdef::VK_EXT_shader_object[] + a shader object is bound to any graphics stage or +endif::VK_EXT_shader_object[] + a graphics pipeline is bound which was created with the + ename:VK_DYNAMIC_STATE_VIEWPORT_COARSE_SAMPLE_ORDER_NV and the + <> of + pname:rasterizerDiscardEnable is ename:VK_FALSE, then flink:vkCmdSetCoarseSampleOrderNV must: have been called and not subsequently <> in the current command buffer prior to this drawing command * [[VUID-{refpage}-shadingRateImage-09234]] If the <> feature is - enabled, and a shader object is bound to any graphics stage, and the - most recent call to flink:vkCmdSetRasterizerDiscardEnable in the current - command buffer set pname:rasterizerDiscardEnable to ename:VK_FALSE, and - the most recent call to flink:vkCmdSetShadingRateImageEnableNV in the - current command buffer set pname:shadingRateImageEnable to - ename:VK_TRUE, then flink:vkCmdSetViewportShadingRatePaletteNV must: - have been called and not subsequently <> in the current command buffer prior to this drawing - command + enabled, and +ifdef::VK_EXT_shader_object[] + a shader object is bound to any graphics stage or +endif::VK_EXT_shader_object[] + a graphics pipeline is bound which was created with the + ename:VK_DYNAMIC_STATE_VIEWPORT_WITH_COUNT and + ename:VK_DYNAMIC_STATE_VIEWPORT_SHADING_RATE_PALETTE_NV dynamic state + enabled, the <> of + pname:rasterizerDiscardEnable is ename:VK_FALSE, and the + <> of + pname:shadingRateImageEnable is ename:VK_TRUE, then + flink:vkCmdSetViewportShadingRatePaletteNV must: have been called and + not subsequently <> in the current + command buffer prior to this drawing command * [[VUID-{refpage}-None-08637]] If the <> feature is - enabled, and a shader object is bound to any graphics stage, and the - most recent call to flink:vkCmdSetRasterizerDiscardEnable in the current - command buffer set pname:rasterizerDiscardEnable to ename:VK_FALSE, and - the most recent call to flink:vkCmdSetShadingRateImageEnableNV in the - current command buffer set pname:shadingRateImageEnable to - ename:VK_TRUE, then the pname:viewportCount parameter in the last call - to flink:vkCmdSetViewportShadingRatePaletteNV must: be greater than or + enabled, and +ifdef::VK_EXT_shader_object[] + a shader object is bound to any graphics stage or +endif::VK_EXT_shader_object[] + a graphics pipeline is bound which was created with the + ename:VK_DYNAMIC_STATE_VIEWPORT_WITH_COUNT and + ename:VK_DYNAMIC_STATE_VIEWPORT_SHADING_RATE_PALETTE_NV dynamic state + enabled, the <> of + pname:rasterizerDiscardEnable is ename:VK_FALSE, and the + <> of + pname:shadingRateImageEnable is ename:VK_TRUE, then the + pname:viewportCount parameter in the last call to + flink:vkCmdSetViewportShadingRatePaletteNV must: be greater than or equal to the pname:viewportCount parameter in the last call to flink:vkCmdSetViewportWithCount -endif::VK_EXT_shader_object[] endif::VK_NV_shading_rate_image[] ifdef::VK_NV_viewport_swizzle[] * [[VUID-{refpage}-VkPipelineVieportCreateInfo-04141]] @@ -1746,6 +1752,23 @@ endif::VK_EXT_shader_object[] the current command buffer prior to this drawing command endif::VK_EXT_shader_object,VK_EXT_extended_dynamic_state3[] endif::VK_EXT_depth_clip_control[] +ifdef::VK_EXT_depth_clamp_control[] +ifdef::VK_EXT_shader_object,VK_EXT_extended_dynamic_state3[] + * [[VUID-{refpage}-None-09650]] + If the <> feature + is enabled, and +ifdef::VK_EXT_shader_object[] + a shader object is bound to any graphics stage or +endif::VK_EXT_shader_object[] + a graphics pipeline is bound which was created with the + ename:VK_DYNAMIC_STATE_DEPTH_CLAMP_RANGE_EXT dynamic state enabled, and + the <> of + pname:depthClampEnable is ename:VK_TRUE, then + flink:vkCmdSetDepthClampRangeEXT must: have been called and not + subsequently <> in the current + command buffer prior to this drawing command +endif::VK_EXT_shader_object,VK_EXT_extended_dynamic_state3[] +endif::VK_EXT_depth_clamp_control[] ifdef::VK_NV_clip_space_w_scaling[] ifdef::VK_EXT_shader_object,VK_EXT_extended_dynamic_state3[] * [[VUID-{refpage}-None-07640]] @@ -2065,16 +2088,20 @@ ifdef::VK_EXT_sample_locations[] * [[VUID-{refpage}-sampleLocationsPerPixel-07482]] If the bound graphics pipeline state was created with the ename:VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_EXT state enabled and the - ename:VK_DYNAMIC_STATE_RASTERIZATION_SAMPLES_EXT state disabled, then - the pname:sampleLocationsPerPixel member of pname:pSampleLocationsInfo - in the last call to flink:vkCmdSetSampleLocationsEXT must: equal the + ename:VK_DYNAMIC_STATE_RASTERIZATION_SAMPLES_EXT state disabled, and the + <> of + pname:sampleLocationsEnable is ename:VK_TRUE, then the + pname:sampleLocationsPerPixel member of pname:pSampleLocationsInfo in + the last call to flink:vkCmdSetSampleLocationsEXT must: equal the pname:rasterizationSamples member of the slink:VkPipelineMultisampleStateCreateInfo structure the bound graphics pipeline has been created with * [[VUID-{refpage}-sampleLocationsPerPixel-07483]] If the bound graphics pipeline state was created with the ename:VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_EXT state enabled and the - ename:VK_DYNAMIC_STATE_RASTERIZATION_SAMPLES_EXT state enabled, then the + ename:VK_DYNAMIC_STATE_RASTERIZATION_SAMPLES_EXT state enabled, and the + <> of + pname:sampleLocationsEnable is ename:VK_TRUE, then the pname:sampleLocationsPerPixel member of pname:pSampleLocationsInfo in the last call to flink:vkCmdSetSampleLocationsEXT must: equal the pname:rasterizationSamples parameter of the last call to @@ -2138,11 +2165,9 @@ endif::VK_EXT_shader_object[] * [[VUID-{refpage}-sampleLocationsEnable-07936]] If the bound graphics pipeline state was created with the ename:VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_EXT state disabled and the - ename:VK_DYNAMIC_STATE_RASTERIZATION_SAMPLES_EXT state enabled, the - pname:sampleLocationsEnable member of a - slink:VkPipelineSampleLocationsStateCreateInfoEXT::pname:sampleLocationsEnable - in the bound graphics pipeline is ename:VK_TRUE or - ename:VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_ENABLE_EXT state enabled, then, + ename:VK_DYNAMIC_STATE_RASTERIZATION_SAMPLES_EXT state enabled, and the + <> of + pname:sampleLocationsEnable is ename:VK_TRUE, then pname:sampleLocationsInfo.sampleLocationGridSize.width must: evenly divide slink:VkMultisamplePropertiesEXT::pname:sampleLocationGridSize.width as @@ -2152,11 +2177,9 @@ endif::VK_EXT_shader_object[] * [[VUID-{refpage}-sampleLocationsEnable-07937]] If the bound graphics pipeline state was created with the ename:VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_EXT state disabled and the - ename:VK_DYNAMIC_STATE_RASTERIZATION_SAMPLES_EXT state enabled, the - pname:sampleLocationsEnable member of a - slink:VkPipelineSampleLocationsStateCreateInfoEXT::pname:sampleLocationsEnable - in the bound graphics pipeline is ename:VK_TRUE or - ename:VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_ENABLE_EXT state enabled, then, + ename:VK_DYNAMIC_STATE_RASTERIZATION_SAMPLES_EXT state enabled, and the + <> of + pname:sampleLocationsEnable is ename:VK_TRUE, then pname:sampleLocationsInfo.sampleLocationGridSize.height must: evenly divide slink:VkMultisamplePropertiesEXT::pname:sampleLocationGridSize.height as @@ -2166,11 +2189,9 @@ endif::VK_EXT_shader_object[] * [[VUID-{refpage}-sampleLocationsEnable-07938]] If the bound graphics pipeline state was created with the ename:VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_EXT state disabled and the - ename:VK_DYNAMIC_STATE_RASTERIZATION_SAMPLES_EXT state enabled, the - pname:sampleLocationsEnable member of a - slink:VkPipelineSampleLocationsStateCreateInfoEXT::pname:sampleLocationsEnable - in the bound graphics pipeline is ename:VK_TRUE or - ename:VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_ENABLE_EXT state enabled, then, + ename:VK_DYNAMIC_STATE_RASTERIZATION_SAMPLES_EXT state enabled, and the + <> of + pname:sampleLocationsEnable is ename:VK_TRUE, then pname:sampleLocationsInfo.sampleLocationsPerPixel must: equal pname:rasterizationSamples in the last call to flink:vkCmdSetRasterizationSamplesEXT diff --git a/chapters/commonvalidity/draw_vertex_binding.adoc b/chapters/commonvalidity/draw_vertex_binding.adoc index f21c28007..4b4baf9b2 100644 --- a/chapters/commonvalidity/draw_vertex_binding.adoc +++ b/chapters/commonvalidity/draw_vertex_binding.adoc @@ -52,16 +52,16 @@ endif::VK_EXT_extended_dynamic_state3[] slink:VkPipelineInputAssemblyStateCreateInfo::pname:topology state * [[VUID-{refpage}-pStrides-04913]] If the bound graphics pipeline was created with the - ename:VK_DYNAMIC_STATE_VERTEX_INPUT_BINDING_STRIDE_EXT dynamic state + ename:VK_DYNAMIC_STATE_VERTEX_INPUT_BINDING_STRIDE dynamic state enabled, ifdef::VK_EXT_vertex_input_dynamic_state[] but without the ename:VK_DYNAMIC_STATE_VERTEX_INPUT_EXT dynamic state enabled, endif::VK_EXT_vertex_input_dynamic_state[] - then flink:vkCmdBindVertexBuffers2EXT must: have been called and not + then flink:vkCmdBindVertexBuffers2 must: have been called and not subsequently <> in the current command buffer prior to this draw command, and the pname:pStrides - parameter of flink:vkCmdBindVertexBuffers2EXT must: not be `NULL` + parameter of flink:vkCmdBindVertexBuffers2 must: not be `NULL` endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] ifdef::VK_EXT_vertex_input_dynamic_state,VK_EXT_shader_object[] * [[VUID-{refpage}-None-04914]] @@ -166,17 +166,17 @@ ifdef::VK_EXT_extended_dynamic_state2[] * [[VUID-{refpage}-None-04875]] If ifdef::VK_EXT_shader_object[] - there is a shader object bound to the ename:VK_SHADER_STAGE_VERTEX_BIT - stage and the most recent call to fname:vkCmdSetPrimitiveTopology in the - current command buffer set pname:primitiveTopology to - ename:VK_PRIMITIVE_TOPOLOGY_PATCH_LIST, + there is a shader object bound to the + ename:VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT stage ifdef::VK_EXT_extended_dynamic_state2[or] endif::VK_EXT_shader_object[] ifdef::VK_EXT_extended_dynamic_state2[] the bound graphics pipeline state was created with the - ename:VK_DYNAMIC_STATE_PATCH_CONTROL_POINTS_EXT dynamic state enabled + ename:VK_DYNAMIC_STATE_PATCH_CONTROL_POINTS_EXT dynamic state enabled, endif::VK_EXT_extended_dynamic_state2[] - then flink:vkCmdSetPatchControlPointsEXT must: have been called and not + and the <> of + pname:primitiveTopology is ename:VK_PRIMITIVE_TOPOLOGY_PATCH_LIST, then + flink:vkCmdSetPatchControlPointsEXT must: have been called and not subsequently <> in the current command buffer prior to this drawing command endif::VK_EXT_extended_dynamic_state2[] diff --git a/chapters/commonvalidity/ray_tracing_pipeline_create_info_common.adoc b/chapters/commonvalidity/ray_tracing_pipeline_create_info_common.adoc index fc4058007..b7114fc3b 100644 --- a/chapters/commonvalidity/ray_tracing_pipeline_create_info_common.adoc +++ b/chapters/commonvalidity/ray_tracing_pipeline_create_info_common.adoc @@ -18,6 +18,11 @@ ifdef::VK_NV_device_generated_commands[] pname:flags must: not include ename:VK_PIPELINE_CREATE_INDIRECT_BINDABLE_BIT_NV endif::VK_NV_device_generated_commands[] +ifdef::VK_EXT_device_generated_commands[] + * [[VUID-{refpage}-flags-11008]] + pname:flags must: not include + ename:VK_PIPELINE_CREATE_2_INDIRECT_BINDABLE_BIT_EXT +endif::VK_EXT_device_generated_commands[] ifdef::VK_VERSION_1_3,VK_EXT_pipeline_creation_cache_control[] * [[VUID-{refpage}-pipelineCreationCacheControl-02905]] If the <>). -.API example +.API Example [source,c++] ---- const VkDescriptorSetLayout layouts[] = { layout1, layout2 }; @@ -4838,7 +4838,7 @@ endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] include::{generated}/validity/protos/vkUpdateDescriptorSetWithTemplate.adoc[] -.API example +.API Example [source,c++] ---- struct AppBufferView { @@ -5336,7 +5336,7 @@ include::{chapters}/commonvalidity/push_descriptor_set_with_template_common.adoc include::{generated}/validity/protos/vkCmdPushDescriptorSetWithTemplateKHR.adoc[] -.API example +.API Example [source,c++] ---- @@ -6894,8 +6894,8 @@ include::{generated}/api/protos/vkGetBufferOpaqueCaptureDescriptorDataEXT.adoc[] .Valid Usage **** * [[VUID-vkGetBufferOpaqueCaptureDescriptorDataEXT-None-08072]] - The <> - feature must: be enabled + The <> feature must: be enabled * [[VUID-vkGetBufferOpaqueCaptureDescriptorDataEXT-pData-08073]] pname:pData must: point to a buffer that is at least slink:VkPhysicalDeviceDescriptorBufferPropertiesEXT::pname:bufferCaptureReplayDescriptorDataSize @@ -6949,8 +6949,8 @@ include::{generated}/api/protos/vkGetImageOpaqueCaptureDescriptorDataEXT.adoc[] .Valid Usage **** * [[VUID-vkGetImageOpaqueCaptureDescriptorDataEXT-None-08076]] - The <> - feature must: be enabled + The <> feature must: be enabled * [[VUID-vkGetImageOpaqueCaptureDescriptorDataEXT-pData-08077]] pname:pData must: point to a buffer that is at least slink:VkPhysicalDeviceDescriptorBufferPropertiesEXT::pname:imageCaptureReplayDescriptorDataSize @@ -7004,8 +7004,8 @@ include::{generated}/api/protos/vkGetImageViewOpaqueCaptureDescriptorDataEXT.ado .Valid Usage **** * [[VUID-vkGetImageViewOpaqueCaptureDescriptorDataEXT-None-08080]] - The <> - feature must: be enabled + The <> feature must: be enabled * [[VUID-vkGetImageViewOpaqueCaptureDescriptorDataEXT-pData-08081]] pname:pData must: point to a buffer that is at least slink:VkPhysicalDeviceDescriptorBufferPropertiesEXT::pname:imageViewCaptureReplayDescriptorDataSize @@ -7059,8 +7059,8 @@ include::{generated}/api/protos/vkGetSamplerOpaqueCaptureDescriptorDataEXT.adoc[ .Valid Usage **** * [[VUID-vkGetSamplerOpaqueCaptureDescriptorDataEXT-None-08084]] - The <> - feature must: be enabled + The <> feature must: be enabled * [[VUID-vkGetSamplerOpaqueCaptureDescriptorDataEXT-pData-08085]] pname:pData must: point to a buffer that is at least slink:VkPhysicalDeviceDescriptorBufferPropertiesEXT::pname:samplerCaptureReplayDescriptorDataSize @@ -7116,8 +7116,8 @@ include::{generated}/api/protos/vkGetAccelerationStructureOpaqueCaptureDescripto .Valid Usage **** * [[VUID-vkGetAccelerationStructureOpaqueCaptureDescriptorDataEXT-None-08088]] - The <> - feature must: be enabled + The <> feature must: be enabled * [[VUID-vkGetAccelerationStructureOpaqueCaptureDescriptorDataEXT-pData-08089]] pname:pData must: point to a buffer that is at least slink:VkPhysicalDeviceDescriptorBufferPropertiesEXT::pname:accelerationStructureCaptureReplayDescriptorDataSize diff --git a/chapters/VK_NV_device_generated_commands/cmdProcessAllSequences.adoc b/chapters/device_generated_commands/cmdProcessAllSequences.adoc similarity index 100% rename from chapters/VK_NV_device_generated_commands/cmdProcessAllSequences.adoc rename to chapters/device_generated_commands/cmdProcessAllSequences.adoc diff --git a/chapters/device_generated_commands/generatedcommands.adoc b/chapters/device_generated_commands/generatedcommands.adoc new file mode 100644 index 000000000..3f2b76d50 --- /dev/null +++ b/chapters/device_generated_commands/generatedcommands.adoc @@ -0,0 +1,33 @@ +// Copyright (c) 2019-2020 NVIDIA Corporation +// Copyright (c) 2024 VALVE Corporation +// +// SPDX-License-Identifier: CC-BY-4.0 + +[[device-generated-commands]] += Device-Generated Commands + +This chapter discusses the generation of command buffer content on the +device, for which these principle steps are to be taken: + + * Define a layout describing the sequence of commands which should be + generated. + * Optionally set up device-bindable shaders. + * Retrieve device addresses by flink:vkGetBufferDeviceAddressEXT for + setting buffers on the device. + * Fill one or more sname:VkBuffer with the appropriate content that gets + interpreted by the command layout. + * Create a `preprocess` sname:VkBuffer using the device-queried allocation + information. + * Optionally preprocess the input data in a separate action. + * Generate and execute the actual commands. + +The preprocessing step executes in a separate logical pipeline from either +graphics or compute. +When preprocessing commands in a separate step they must: be explicitly +synchronized against the command execution. +When not preprocessing in a separate step, the preprocessing is +automatically synchronized against the command execution. + +include::{chapters}/device_generated_commands/indirectcommands.adoc[] + +include::{chapters}/device_generated_commands/generation.adoc[] diff --git a/chapters/device_generated_commands/generation.adoc b/chapters/device_generated_commands/generation.adoc new file mode 100644 index 000000000..30fe235f0 --- /dev/null +++ b/chapters/device_generated_commands/generation.adoc @@ -0,0 +1,1561 @@ +// Copyright (c) 2019-2020 NVIDIA Corporation +// Copyright (c) 2024 VALVE Corporation +// +// SPDX-License-Identifier: CC-BY-4.0 + +== Indirect Commands Generation and Execution + +The generation of commands on the device requires a `preprocess` buffer. + +ifdef::VK_EXT_device_generated_commands[] +[open,refpage='vkGetGeneratedCommandsMemoryRequirementsEXT',desc='Retrieve the buffer allocation requirements for generated commands',type='protos'] +-- +With `apiext:VK_EXT_device_generated_commands`, to retrieve the memory size +and alignment requirements of a particular execution state call: + +include::{generated}/api/protos/vkGetGeneratedCommandsMemoryRequirementsEXT.adoc[] + + * pname:device is the logical device that owns the buffer. + * pname:pInfo is a pointer to a + slink:VkGeneratedCommandsMemoryRequirementsInfoEXT structure containing + parameters required for the memory requirements query. + * pname:pMemoryRequirements is a pointer to a slink:VkMemoryRequirements2 + structure in which the memory requirements of the buffer object are + returned. + +If the size returned is zero, the preprocessing step can be skipped for this +layout. + +include::{generated}/validity/protos/vkGetGeneratedCommandsMemoryRequirementsEXT.adoc[] +-- + +[open,refpage='VkGeneratedCommandsMemoryRequirementsInfoEXT',desc='Structure specifying parameters for the reservation of preprocess buffer space',type='structs'] +-- +include::{generated}/api/structs/VkGeneratedCommandsMemoryRequirementsInfoEXT.adoc[] + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * pname:indirectExecutionSet is the indirect execution set to be used for + binding shaders. + * pname:indirectCommandsLayout is the slink:VkIndirectCommandsLayoutEXT + that this buffer memory is intended to be used with. + * pname:maxSequenceCount is the maximum number of sequences that this + buffer memory can be used with. + * pname:maxDrawCount is the maximum number of indirect draws that can be + executed by any COUNT-type multi-draw indirect tokens. + The draw count in the indirect buffer is clamped to this value for these + token types. + +If the action command token for the layout is not a COUNT-type multi-draw +indirect token, pname:maxDrawCount is ignored. + +.Valid Usage +**** + * [[VUID-VkGeneratedCommandsMemoryRequirementsInfoEXT-maxSequencesCount-11009]] + pname:maxSequencesCount must: be less or equal to + slink:VkPhysicalDeviceDeviceGeneratedCommandsPropertiesEXT::pname:maxIndirectSequenceCount + * [[VUID-VkGeneratedCommandsMemoryRequirementsInfoEXT-indirectCommandsLayout-11010]] + If pname:indirectCommandsLayout was created with a token sequence that + contained the ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_EXECUTION_SET_EXT + token, pname:indirectExecutionSet must: not be dlink:VK_NULL_HANDLE + * [[VUID-VkGeneratedCommandsMemoryRequirementsInfoEXT-indirectCommandsLayout-11151]] + If pname:indirectCommandsLayout was created with a token sequence that + contained the ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_EXECUTION_SET_EXT + token, the shader stages used to create the initial shader state of + pname:indirectExecutionSet must: equal the + slink:VkIndirectCommandsExecutionSetTokenEXT::pname:shaderStages used to + create pname:indirectCommandsLayout + * [[VUID-VkGeneratedCommandsMemoryRequirementsInfoEXT-indirectCommandsLayout-11011]] + If pname:indirectCommandsLayout was not created with a token sequence + that contained the + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_EXECUTION_SET_EXT token, + pname:indirectExecutionSet must: be dlink:VK_NULL_HANDLE + * [[VUID-VkGeneratedCommandsMemoryRequirementsInfoEXT-maxDrawCount-11146]] + When not ignored, [eq]#pname:maxDrawCount {times} + pname:maxSequenceCount# must: be less than [eq]#2^24# + * [[VUID-VkGeneratedCommandsMemoryRequirementsInfoEXT-indirectExecutionSet-11012]] + If pname:indirectExecutionSet is dlink:VK_NULL_HANDLE, +ifdef::VK_EXT_shader_object[either] + a slink:VkGeneratedCommandsPipelineInfoEXT +ifdef::VK_EXT_shader_object[or a slink:VkGeneratedCommandsShaderInfoEXT] + must: be included in the pname:pNext chain +**** + +include::{generated}/validity/structs/VkGeneratedCommandsMemoryRequirementsInfoEXT.adoc[] +-- + +[open,refpage='VkGeneratedCommandsPipelineInfoEXT',desc='Structure specifying a pipeline for use with indirect command preprocessing',type='structs'] +-- +include::{generated}/api/structs/VkGeneratedCommandsPipelineInfoEXT.adoc[] + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * pname:pipeline is a valid pipeline object. + +.Valid Usage +**** +**** + +include::{generated}/validity/structs/VkGeneratedCommandsPipelineInfoEXT.adoc[] +-- + +ifdef::VK_EXT_shader_object[] +[open,refpage='VkGeneratedCommandsShaderInfoEXT',desc='Structure specifying shader objects for use with indirect command preprocessing',type='structs'] +-- +include::{generated}/api/structs/VkGeneratedCommandsShaderInfoEXT.adoc[] + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * pname:shaderCount is the size of the pname:pShaders array. + * pname:pShaders is a pointer to an array of shader objects. + +.Valid Usage +**** + * [[VUID-VkGeneratedCommandsShaderInfoEXT-pShaders-11127]] + pname:pShaders must: not contain more than one shader object for a given + elink:VkShaderStageFlagBits stage +**** + +include::{generated}/validity/structs/VkGeneratedCommandsShaderInfoEXT.adoc[] +-- +endif::VK_EXT_shader_object[] +endif::VK_EXT_device_generated_commands[] + +ifdef::VK_NV_device_generated_commands[] +[open,refpage='vkGetGeneratedCommandsMemoryRequirementsNV',desc='Retrieve the buffer allocation requirements for generated commands',type='protos'] +-- +With `apiext:VK_NV_device_generated_commands`, to retrieve the memory size +and alignment requirements of a particular execution state call: + +include::{generated}/api/protos/vkGetGeneratedCommandsMemoryRequirementsNV.adoc[] + + * pname:device is the logical device that owns the buffer. + * pname:pInfo is a pointer to a + slink:VkGeneratedCommandsMemoryRequirementsInfoNV structure containing + parameters required for the memory requirements query. + * pname:pMemoryRequirements is a pointer to a slink:VkMemoryRequirements2 + structure in which the memory requirements of the buffer object are + returned. + +.Valid Usage +**** + * [[VUID-vkGetGeneratedCommandsMemoryRequirementsNV-deviceGeneratedCommands-02906]] + The <> + feature must: be enabled +ifdef::VK_NV_device_generated_commands_compute[] + * [[VUID-vkGetGeneratedCommandsMemoryRequirementsNV-pInfo-09074]] + If pname:pInfo->pipelineBindPoint is of type + ename:VK_PIPELINE_BIND_POINT_COMPUTE, then the + <> + feature must: be enabled +endif::VK_NV_device_generated_commands_compute[] +**** + +include::{generated}/validity/protos/vkGetGeneratedCommandsMemoryRequirementsNV.adoc[] +-- + +[open,refpage='VkGeneratedCommandsMemoryRequirementsInfoNV',desc='Structure specifying parameters for the reservation of preprocess buffer space',type='structs'] +-- +include::{generated}/api/structs/VkGeneratedCommandsMemoryRequirementsInfoNV.adoc[] + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * pname:pipelineBindPoint is the elink:VkPipelineBindPoint of the + pname:pipeline that this buffer memory is intended to be used with + during the execution. + * pname:pipeline is the slink:VkPipeline that this buffer memory is + intended to be used with during the execution. + * pname:indirectCommandsLayout is the slink:VkIndirectCommandsLayoutNV + that this buffer memory is intended to be used with. + * pname:maxSequencesCount is the maximum number of sequences that this + buffer memory in combination with the other state provided can: be used + with. + +.Valid Usage +**** + * [[VUID-VkGeneratedCommandsMemoryRequirementsInfoNV-maxSequencesCount-02907]] + pname:maxSequencesCount must: be less or equal to + slink:VkPhysicalDeviceDeviceGeneratedCommandsPropertiesNV::pname:maxIndirectSequenceCount + * [[VUID-VkGeneratedCommandsMemoryRequirementsInfoNV-pipelineBindPoint-09075]] + If pname:pipelineBindPoint is of type + ename:VK_PIPELINE_BIND_POINT_GRAPHICS, then pname:pipeline must: be a + valid slink:VkPipeline handle +ifdef::VK_NV_device_generated_commands_compute[] + * [[VUID-VkGeneratedCommandsMemoryRequirementsInfoNV-pipelineBindPoint-09076]] + If pname:pipelineBindPoint is of type + ename:VK_PIPELINE_BIND_POINT_COMPUTE, and the + pname:indirectCommandsLayout was not created with a + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_PIPELINE_NV token, then the + pname:pipeline must: be a valid slink:VkPipeline handle + * [[VUID-VkGeneratedCommandsMemoryRequirementsInfoNV-pipelineBindPoint-09077]] + If pname:pipelineBindPoint is of type + ename:VK_PIPELINE_BIND_POINT_COMPUTE, and the + pname:indirectCommandsLayout contains a + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_PIPELINE_NV token, then the + pname:pipeline must: be dlink:VK_NULL_HANDLE +endif::VK_NV_device_generated_commands_compute[] +**** + +include::{generated}/validity/structs/VkGeneratedCommandsMemoryRequirementsInfoNV.adoc[] +-- + +ifdef::VK_NV_device_generated_commands_compute[] + +With `apiext:VK_NV_device_generated_commands`, to bind a compute pipeline in +<>, an application +must: query the pipeline's device address. + +[open,refpage='vkGetPipelineIndirectDeviceAddressNV',desc='Get pipeline\'s 64-bit device address',type='protos'] +-- +:refpage: vkGetPipelineIndirectDeviceAddressNV + +To query a compute pipeline's 64-bit device address, call: + +include::{generated}/api/protos/vkGetPipelineIndirectDeviceAddressNV.adoc[] + + * pname:device is the logical device on which the pipeline was created. + * pname:pInfo is a pointer to a + slink:VkPipelineIndirectDeviceAddressInfoNV structure specifying the + pipeline to retrieve the address for. + +.Valid Usage +**** + * [[VUID-vkGetPipelineIndirectDeviceAddressNV-deviceGeneratedComputePipelines-09078]] + The <> + feature must: be enabled +**** + +include::{generated}/validity/protos/vkGetPipelineIndirectDeviceAddressNV.adoc[] +-- + +[open,refpage='VkPipelineIndirectDeviceAddressInfoNV',desc='Structure specifying the pipeline to query an address for',type='structs'] +-- +:refpage: VkPipelineIndirectDeviceAddressInfoNV + +The sname:VkPipelineIndirectDeviceAddressInfoNV structure is defined as: + +include::{generated}/api/structs/VkPipelineIndirectDeviceAddressInfoNV.adoc[] + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * pname:pipelineBindPoint is a elink:VkPipelineBindPoint value specifying + the type of pipeline whose device address is being queried. + * pname:pipeline specifies the pipeline whose device address is being + queried. + +.Valid Usage +**** + * [[VUID-VkPipelineIndirectDeviceAddressInfoNV-pipelineBindPoint-09079]] + The provided pname:pipelineBindPoint must: be of type + ename:VK_PIPELINE_BIND_POINT_COMPUTE + * [[VUID-VkPipelineIndirectDeviceAddressInfoNV-pipeline-09080]] + pname:pipeline must: have been created with flag + ename:VK_PIPELINE_CREATE_INDIRECT_BINDABLE_BIT_NV set + * [[VUID-VkPipelineIndirectDeviceAddressInfoNV-pipeline-09081]] + pname:pipeline must: have been created with a + slink:VkComputePipelineIndirectBufferInfoNV structure specifying a valid + address where its metadata will be saved +**** +include::{generated}/validity/structs/VkPipelineIndirectDeviceAddressInfoNV.adoc[] +-- + +[open,refpage='vkGetPipelineIndirectMemoryRequirementsNV',desc='Get the memory requirements for the compute indirect pipeline',type='protos'] +-- +:refpage: vkGetPipelineIndirectMemoryRequirementsNV + +To determine the memory requirements for a compute pipeline's metadata, +call: + +include::{generated}/api/protos/vkGetPipelineIndirectMemoryRequirementsNV.adoc[] + + * pname:device is the logical device that owns the buffer. + * pname:pCreateInfo is a slink:VkComputePipelineCreateInfo structure + specifying the creation parameters of the compute pipeline whose memory + requirements are being queried. + * pname:pMemoryRequirements is a pointer to a slink:VkMemoryRequirements2 + structure in which the requested pipeline's memory requirements are + returned. + +If pname:pCreateInfo->pNext chain includes a pointer to a +slink:VkComputePipelineIndirectBufferInfoNV structure, then the contents of +that structure are ignored. + +.Valid Usage +**** + * [[VUID-vkGetPipelineIndirectMemoryRequirementsNV-deviceGeneratedComputePipelines-09082]] + The <> + feature must: be enabled + * [[VUID-vkGetPipelineIndirectMemoryRequirementsNV-pCreateInfo-09083]] + pname:pCreateInfo->flags must: include + ename:VK_PIPELINE_CREATE_INDIRECT_BINDABLE_BIT_NV +**** + +include::{generated}/validity/protos/vkGetPipelineIndirectMemoryRequirementsNV.adoc[] +-- +endif::VK_NV_device_generated_commands_compute[] +endif::VK_NV_device_generated_commands[] + +ifdef::VK_EXT_device_generated_commands[] +[[device-generated-indirect-execution-sets]] +=== Indirect Execution Sets + +[open,refpage='VkIndirectExecutionSetEXT',desc='Opaque handle to an indirect execution set object',type='handles'] +-- +Indirect Execution Sets contain sets of pipelines +ifdef::VK_EXT_shader_object[] +or shader objects +endif::VK_EXT_shader_object[] +which can be bound individually. + +include::{generated}/api/handles/VkIndirectExecutionSetEXT.adoc[] + +Indirect Execution Sets allow the device to bind different shaders and +pipeline states using <>. + +-- + +[open,refpage='vkCreateIndirectExecutionSetEXT',desc='Create an indirect execution set',type='protos'] +-- +:refpage: vkCreateIndirectExecutionSetEXT + +Indirect Execution Sets are created by calling: + +include::{generated}/api/protos/vkCreateIndirectExecutionSetEXT.adoc[] + + * pname:device is the logical device that creates the indirect execution + set. + * pname:pCreateInfo is a pointer to a + slink:VkIndirectExecutionSetCreateInfoEXT structure containing + parameters affecting creation of the indirect execution set. + * pname:pAllocator controls host memory allocation as described in the + <> chapter. + * pname:pIndirectExecutionSet is a pointer to a + slink:VkIndirectExecutionSetEXT handle in which the resulting indirect + execution set is returned. + +.Valid Usage +**** + * [[VUID-vkCreateIndirectExecutionSetEXT-deviceGeneratedCommands-11013]] + The <> + feature must: be enabled +**** + +include::{generated}/validity/protos/vkCreateIndirectExecutionSetEXT.adoc[] +-- + +[open,refpage='VkIndirectExecutionSetCreateInfoEXT',desc='Structure specifying parameters of a newly created indirect execution set',type='structs'] +-- +The sname:VkIndirectExecutionSetCreateInfoEXT structure is defined as: + +include::{generated}/api/structs/VkIndirectExecutionSetCreateInfoEXT.adoc[] + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * pname:type is a elink:VkIndirectExecutionSetInfoTypeEXT describing the + type of set being created and determining which field of the pname:info + union will be used. + * pname:info is a slink:VkIndirectExecutionSetInfoEXT union containing + layout information for the set. + +.Valid Usage +**** + * [[VUID-VkIndirectExecutionSetCreateInfoEXT-maxIndirectShaderObjectCount-11014]] + If + sname:VkPhysicalDeviceDeviceGeneratedCommandsPropertiesEXT::pname:maxIndirectShaderObjectCount + is zero +ifdef::VK_EXT_shader_object[] + or <> is not enabled +endif::VK_EXT_shader_object[] + pname:type must: not be + ename:VK_INDIRECT_EXECUTION_SET_INFO_TYPE_SHADER_OBJECTS_EXT +**** + +include::{generated}/validity/structs/VkIndirectExecutionSetCreateInfoEXT.adoc[] +-- + +[open,refpage='VkIndirectExecutionSetInfoTypeEXT',desc='Enum specifying allowed usage of an indirect execution set',type='enums'] +-- + +Values which can: be set in +slink:VkIndirectExecutionSetCreateInfoEXT::pname:type, specifying contents +of an indirect execution set, are: + +include::{generated}/api/enums/VkIndirectExecutionSetInfoTypeEXT.adoc[] + + * ename:VK_INDIRECT_EXECUTION_SET_INFO_TYPE_PIPELINES_EXT specifies that + the indirect execution set contains slink:VkPipeline objects. +ifdef::VK_EXT_shader_object[] + * ename:VK_INDIRECT_EXECUTION_SET_INFO_TYPE_SHADER_OBJECTS_EXT specifies + that the indirect execution set contains slink:VkShaderEXT objects. +endif::VK_EXT_shader_object[] +ifndef::VK_EXT_shader_object[] + * ename:VK_INDIRECT_EXECUTION_SET_INFO_TYPE_SHADER_OBJECTS_EXT must: not + be used. +endif::VK_EXT_shader_object[] +-- + +[open,refpage='VkIndirectExecutionSetInfoEXT',desc='Union specifying parameters of a newly created indirect execution set',type='structs'] +-- +The sname:VkIndirectExecutionSetInfoEXT union is defined as: + +include::{generated}/api/structs/VkIndirectExecutionSetInfoEXT.adoc[] + + * pname:pPipelineInfo is a pointer to a + slink:VkIndirectExecutionSetPipelineInfoEXT struct containing pipeline + layout information for the set. + * pname:pShaderInfo is a pointer to a + slink:VkIndirectExecutionSetShaderInfoEXT struct containing shader + object layout information for the set. + +include::{generated}/validity/structs/VkIndirectExecutionSetInfoEXT.adoc[] +-- + +[open,refpage='VkIndirectExecutionSetPipelineInfoEXT',desc='Struct specifying parameters of a newly created indirect execution set containing only pipelines',type='structs'] +-- +The sname:VkIndirectExecutionSetPipelineInfoEXT structure is defined as: + +include::{generated}/api/structs/VkIndirectExecutionSetPipelineInfoEXT.adoc[] + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * pname:initialPipeline is the initial pipeline for the set. + This pipeline will be automatically added to the set at index `0`. + * pname:maxPipelineCount is the maximum number of pipelines stored in the + set. + +The characteristics of pname:initialPipeline will be used to validate all +pipelines added to the set even if they are removed from the set or +destroyed. + +When an Indirect Execution Set created with pipelines is used, +pname:initialPipeline constitutes the initial shader state. + +.Valid Usage +**** + * [[VUID-VkIndirectExecutionSetPipelineInfoEXT-supportedIndirectCommandsShaderStagesPipelineBinding-11015]] + If <> + does not contain ename:VK_SHADER_STAGE_COMPUTE_BIT, the + ename:VkPipelineBindPoint of pname:initialPipeline must: not be + ename:VK_PIPELINE_BIND_POINT_COMPUTE + * [[VUID-VkIndirectExecutionSetPipelineInfoEXT-supportedIndirectCommandsShaderStagesPipelineBinding-11016]] + If <> + does not contain ename:VK_SHADER_STAGE_FRAGMENT_BIT, the + ename:VkPipelineBindPoint of pname:initialPipeline must: not be + ename:VK_PIPELINE_BIND_POINT_GRAPHICS +ifdef::VK_KHR_ray_tracing_pipeline[] + * [[VUID-VkIndirectExecutionSetPipelineInfoEXT-supportedIndirectCommandsShaderStagesPipelineBinding-11017]] + If <> + does not contain ray tracing stages, the ename:VkPipelineBindPoint of + pname:initialPipeline must: not be + ename:VK_PIPELINE_BIND_POINT_RAY_TRACING_KHR +endif::VK_KHR_ray_tracing_pipeline[] + * [[VUID-VkIndirectExecutionSetPipelineInfoEXT-maxPipelineCount-11018]] + pname:maxPipelineCount must: be between `1` and + sname:VkPhysicalDeviceDeviceGeneratedCommandsPropertiesEXT::pname:maxIndirectPipelineCount + * [[VUID-VkIndirectExecutionSetPipelineInfoEXT-initialPipeline-11019]] + pname:initialPipeline must: not use descriptors of type + ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC or + ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC + * [[VUID-VkIndirectExecutionSetPipelineInfoEXT-initialPipeline-11153]] + pname:initialPipeline must: have been created with + ename:VK_PIPELINE_CREATE_2_INDIRECT_BINDABLE_BIT_EXT +**** + +include::{generated}/validity/structs/VkIndirectExecutionSetPipelineInfoEXT.adoc[] +-- + +[open,refpage='VkIndirectExecutionSetShaderInfoEXT',desc='Struct specifying parameters of a newly created indirect execution set containing only shader objects',type='structs'] +-- +The sname:VkIndirectExecutionSetShaderInfoEXT structure is defined as: + +include::{generated}/api/structs/VkIndirectExecutionSetShaderInfoEXT.adoc[] + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * pname:shaderCount is the number of members in the pname:pInitialShaders + and pname:pSetLayoutInfos arrays. + * pname:pInitialShaders is a pointer to an array containing a + slink:VkShaderEXT object for each shader stage that will be used in the + set. + These shaders will be automatically added to the set beginning at index + `0`. + * pname:pSetLayoutInfos is a pointer to an array containing a + slink:VkIndirectExecutionSetShaderLayoutInfoEXT used by each + corresponding pname:pInitialShaders shader stage in the set. + * pname:maxShaderCount is the maximum number of shader objects stored in + the set. + * pname:pushConstantRangeCount is the number of members in the + pname:pPushConstantRanges array. + * pname:pPushConstantRanges is a pointer to the array of + slink:VkPushConstantRange ranges used by all shaders in the set. + +The characteristics of pname:pInitialShaders will be used to validate all +shaders added to the set even if they are removed from the set or destroyed. + +When an Indirect Execution Set created with shader objects is used, +pname:pInitialShaders constitutes the initial shader state. + +.Valid Usage +**** + * [[VUID-VkIndirectExecutionSetShaderInfoEXT-pInitialShaders-11020]] + All members of pname:pInitialShaders must: have a pname:stage supported + by <> + * [[VUID-VkIndirectExecutionSetShaderInfoEXT-maxShaderCount-11021]] + pname:maxShaderCount must: not be zero + * [[VUID-VkIndirectExecutionSetShaderInfoEXT-maxShaderCount-11022]] + pname:maxShaderCount must: be less than or equal to + sname:VkPhysicalDeviceDeviceGeneratedCommandsPropertiesEXT::pname:maxIndirectShaderObjectCount + * [[VUID-VkIndirectExecutionSetShaderInfoEXT-maxShaderCount-11036]] + pname:maxShaderCount must: be greater than or equal to pname:shaderCount + * [[VUID-VkIndirectExecutionSetShaderInfoEXT-stage-11023]] + The pname:stage of each element in the pname:pInitialShaders array must: + be unique + * [[VUID-VkIndirectExecutionSetShaderInfoEXT-pInitialShaders-11154]] + Each member of pname:pInitialShaders must: have been created with + ename:VK_SHADER_CREATE_INDIRECT_BINDABLE_BIT_EXT +**** + +include::{generated}/validity/structs/VkIndirectExecutionSetShaderInfoEXT.adoc[] +-- + +[open,refpage='VkIndirectExecutionSetShaderLayoutInfoEXT',desc='Struct specifying descriptor layout parameters of a newly created indirect execution set containing only shader objects',type='structs'] +-- +The sname:VkIndirectExecutionSetShaderLayoutInfoEXT structure is defined as: + +include::{generated}/api/structs/VkIndirectExecutionSetShaderLayoutInfoEXT.adoc[] + + * pname:setLayoutCount is the number of members in the pname:pSetLayouts + array + * pname:pSetLayouts is a pointer to an array containing + slink:VkDescriptorSetLayout objects used by the shader stage. + +.Valid Usage +**** + * [[VUID-VkIndirectExecutionSetShaderLayoutInfoEXT-pSetLayouts-11024]] + All members of pname:pSetLayouts must: not contain descriptors of type + ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC or + ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC +**** + +include::{generated}/validity/structs/VkIndirectExecutionSetShaderLayoutInfoEXT.adoc[] +-- + +[open,refpage='vkDestroyIndirectExecutionSetEXT',desc='Destroy an indirect execution set',type='protos'] +-- +:refpage: vkDestroyIndirectExecutionSetEXT + +Destroy an Indirect Execution Set by calling: + +include::{generated}/api/protos/vkDestroyIndirectExecutionSetEXT.adoc[] + + * pname:device is the logical device that owns the indirect execution set. + * pname:indirectExecutionSet is the indirect execution set to destroy. + * pname:pAllocator controls host memory allocation as described in the + <> chapter. + +.Valid Usage +**** + * [[VUID-vkDestroyIndirectExecutionSetEXT-indirectExecutionSet-11025]] + All submitted commands that refer to pname:indirectExecutionSet must: + have completed execution +**** + +include::{generated}/validity/protos/vkDestroyIndirectExecutionSetEXT.adoc[] +-- + +[open,refpage='VkWriteIndirectExecutionSetPipelineEXT',desc='Struct specifying pipeline update information for an indirect execution set',type='structs'] +-- +The sname:VkWriteIndirectExecutionSetPipelineEXT struct is defined as: + +include::{generated}/api/structs/VkWriteIndirectExecutionSetPipelineEXT.adoc[] + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * pname:index is the element of the set to update + * pname:pipeline is the pipeline to store in the indirect execution set + +.Valid Usage +**** + * [[VUID-VkWriteIndirectExecutionSetPipelineEXT-index-11026]] + pname:index must: be less than the value of + sname:VkIndirectExecutionSetPipelineInfoEXT::pname:maxPipelineCount used + to create the set + * [[VUID-VkWriteIndirectExecutionSetPipelineEXT-pipeline-11027]] + pname:pipeline must: have been created with + ename:VK_PIPELINE_CREATE_2_INDIRECT_BINDABLE_BIT_EXT + * [[VUID-VkWriteIndirectExecutionSetPipelineEXT-pipeline-11028]] + The descriptor layout info used to create pname:pipeline must: be + <> with the descriptor layout + info used to create the indirect execution set + * [[VUID-VkWriteIndirectExecutionSetPipelineEXT-index-11029]] + pname:index must: not be referenced by submitted command buffers + * [[VUID-VkWriteIndirectExecutionSetPipelineEXT-pipeline-11030]] + The shader stages contained in pname:pipeline must: be supported by + <> +**** + +include::{generated}/validity/structs/VkWriteIndirectExecutionSetPipelineEXT.adoc[] +-- + +[open,refpage='VkWriteIndirectExecutionSetShaderEXT',desc='Struct specifying shader object update information for an indirect execution set',type='structs'] +-- +The sname:VkWriteIndirectExecutionSetShaderEXT struct is defined as: + +include::{generated}/api/structs/VkWriteIndirectExecutionSetShaderEXT.adoc[] + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * pname:index is the element of the set to update + * pname:shader is the shader to store in the indirect execution set + +Shaders need not be stored in the Indirect Execution Set according to their +stage. +The only restriction for shader indices within a set is that the value of +the index must: be less than the maximum number of shaders in the set. + +.Valid Usage +**** + * [[VUID-VkWriteIndirectExecutionSetShaderEXT-index-11031]] + pname:index must: be less than + sname:VkIndirectExecutionSetShaderInfoEXT::pname:maxShaderCount + * [[VUID-VkWriteIndirectExecutionSetShaderEXT-shader-11032]] + pname:shader must: have been created with + ename:VK_SHADER_CREATE_INDIRECT_BINDABLE_BIT_EXT + * [[VUID-VkWriteIndirectExecutionSetShaderEXT-pInitialShaders-11033]] + A shader created with the same elink:VkShaderStageFlagBits must: have + been passed in the + sname:VkIndirectExecutionSetShaderInfoEXT::pname:pInitialShaders array + * [[VUID-VkWriteIndirectExecutionSetShaderEXT-index-11034]] + pname:index must: not be in use by submitted command buffers +**** + +include::{generated}/validity/structs/VkWriteIndirectExecutionSetShaderEXT.adoc[] +-- + +[open,refpage='vkUpdateIndirectExecutionSetPipelineEXT',desc='Update the contents of an indirect execution set',type='protos'] +-- +:refpage: vkUpdateIndirectExecutionSetPipelineEXT + +Pipeline elements in an Indirect Execution Set can be updated by calling: + +include::{generated}/api/protos/vkUpdateIndirectExecutionSetPipelineEXT.adoc[] + + * pname:device is the logical device that owns the indirect execution set. + * pname:indirectExecutionSet is the indirect execution set being updated. + * pname:executionSetWriteCount is the number of elements in the + pname:pExecutionSetWrites array. + * pname:pExecutionSetWrites is a pointer to an array of + slink:VkWriteIndirectExecutionSetPipelineEXT structures describing the + elements to update. + +.Valid Usage +**** + * [[VUID-vkUpdateIndirectExecutionSetPipelineEXT-indirectExecutionSet-11035]] + pname:indirectExecutionSet must: have been created with type + ename:VK_INDIRECT_EXECUTION_SET_INFO_TYPE_PIPELINES_EXT + * [[VUID-vkUpdateIndirectExecutionSetPipelineEXT-executionSetWriteCount-11037]] + pname:executionSetWriteCount must: be less than or equal to + sname:VkIndirectExecutionSetPipelineInfoEXT::pname:maxPipelineCount + * [[VUID-vkUpdateIndirectExecutionSetPipelineEXT-pExecutionSetWrites-11042]] + Each element in the pname:pExecutionSetWrites array must have a unique + sname:VkWriteIndirectExecutionSetPipelineEXT::pname:index + * [[VUID-vkUpdateIndirectExecutionSetPipelineEXT-None-11038]] + Each member of the Indirect Execution Set referenced by the update + command must: not be in use by the device + * [[VUID-vkUpdateIndirectExecutionSetPipelineEXT-None-11039]] + The layout of each pipeline in pname:pExecutionSetWrites must: be + <> with the + pname:initialPipeline used to create the Indirect Execution Set + * [[VUID-vkUpdateIndirectExecutionSetPipelineEXT-None-11040]] + Each pipeline in the Indirect Execution Set must: have identically + defined static and dynamic state values to the pname:initialPipeline + used to create the Indirect Execution Set + * [[VUID-vkUpdateIndirectExecutionSetPipelineEXT-initialPipeline-11147]] + Each pipeline in the Indirect Execution Set must: have identically + defined <> to the + pname:initialPipeline used to create the Indirect Execution Set + * [[VUID-vkUpdateIndirectExecutionSetPipelineEXT-initialPipeline-11152]] + Each pipeline in the Indirect Execution Set must: match the + pname:initialPipeline used to create the Indirect Execution Set in its + included shader stages + * [[VUID-vkUpdateIndirectExecutionSetPipelineEXT-initialPipeline-11098]] + Each pipeline in the Indirect Execution Set must: match the + pname:initialPipeline used to create the Indirect Execution Set in its + use of code:FragDepth + * [[VUID-vkUpdateIndirectExecutionSetPipelineEXT-initialPipeline-11086]] + Each pipeline in the Indirect Execution Set must: match the + pname:initialPipeline used to create the Indirect Execution Set in its + use of code:SampleMask +ifdef::VK_EXT_shader_stencil_export[] + * [[VUID-vkUpdateIndirectExecutionSetPipelineEXT-initialPipeline-11085]] + Each pipeline in the Indirect Execution Set must: match the + pname:initialPipeline used to create the Indirect Execution Set in its + use of code:StencilExportEXT +endif::VK_EXT_shader_stencil_export[] +**** + +include::{generated}/validity/protos/vkUpdateIndirectExecutionSetPipelineEXT.adoc[] +-- + +ifdef::VK_EXT_shader_object[] +[open,refpage='vkUpdateIndirectExecutionSetShaderEXT',desc='Update the contents of an indirect execution set',type='protos'] +-- +:refpage: vkUpdateIndirectExecutionSetShaderEXT + +Shader object elements in an Indirect Execution Set can be updated by +calling: + +include::{generated}/api/protos/vkUpdateIndirectExecutionSetShaderEXT.adoc[] + + * pname:device is the logical device that owns the indirect execution set. + * pname:indirectExecutionSet is the indirect execution set being updated. + * pname:executionSetWriteCount is the number of elements in the + pname:pExecutionSetWrites array. + * pname:pExecutionSetWrites is a pointer to an array of + slink:VkWriteIndirectExecutionSetShaderEXT structures describing the + elements to update. + +.Valid Usage +**** + * [[VUID-vkUpdateIndirectExecutionSetShaderEXT-indirectExecutionSet-11041]] + pname:indirectExecutionSet must: have been created with type + ename:VK_INDIRECT_EXECUTION_SET_INFO_TYPE_SHADER_OBJECTS_EXT + * [[VUID-vkUpdateIndirectExecutionSetShaderEXT-pExecutionSetWrites-11043]] + Each element in the pname:pExecutionSetWrites array must have a unique + sname:VkWriteIndirectExecutionSetShaderEXT::pname:index + * [[VUID-vkUpdateIndirectExecutionSetShaderEXT-None-11044]] + Each member of the Indirect Execution Set referenced by the update + command must: not be in use by the device + * [[VUID-vkUpdateIndirectExecutionSetShaderEXT-pExecutionSetWrites-11140]] + The descriptor layout of each shader in pname:pExecutionSetWrites must: + be <> with the initial layout + info used to create the Indirect Execution Set + * [[VUID-vkUpdateIndirectExecutionSetShaderEXT-None-11148]] + Each fragment shader element in the Indirect Execution Set must: have + identically defined <> to the initial shader state used to create the Indirect + Execution Set + * [[VUID-vkUpdateIndirectExecutionSetShaderEXT-FragDepth-11054]] + Each fragment shader element in the Indirect Execution Set must: match + the initial shader state used to create the Indirect Execution Set in + its use of code:FragDepth + * [[VUID-vkUpdateIndirectExecutionSetShaderEXT-SampleMask-11050]] + Each fragment shader element in the Indirect Execution Set must: match + the initial shader state used to create the Indirect Execution Set in + its use of code:SampleMask +ifdef::VK_EXT_shader_stencil_export[] + * [[VUID-vkUpdateIndirectExecutionSetShaderEXT-StencilExportEXT-11003]] + Each fragment shader element in the Indirect Execution Set must: match + the initial shader state used to create the Indirect Execution Set in + its use of code:StencilExportEXT +endif::VK_EXT_shader_stencil_export[] +**** + +include::{generated}/validity/protos/vkUpdateIndirectExecutionSetShaderEXT.adoc[] +-- +endif::VK_EXT_shader_object[] + +It is legal to update an Indirect Execution Set that is in flight as long as +the element indices in pname:pExecutionSetWrites are not in use. +Any change to an indirect execution set requires recalculating memory +requirements by calling flink:vkGetGeneratedCommandsMemoryRequirementsEXT +for commands that use that modified state. +Commands that are in flight or those not using updated elements require no +changes. + +The lifetimes of pipelines +ifdef::VK_EXT_shader_object[and shader objects] +contained in a set must: match or exceed the lifetime of the set. + +endif::VK_EXT_device_generated_commands[] + +ifdef::VK_NV_device_generated_commands[] +[open,refpage='vkCmdExecuteGeneratedCommandsNV',desc='Generate and execute commands on the device',type='protos'] +-- +:refpage: vkCmdExecuteGeneratedCommandsNV + +With `apiext:VK_NV_device_generated_commands`, the actual generation of +commands as well as their execution on the device is handled as single +action with: + +include::{generated}/api/protos/vkCmdExecuteGeneratedCommandsNV.adoc[] + + * pname:commandBuffer is the command buffer into which the command is + recorded. + * pname:isPreprocessed represents whether the input data has already been + preprocessed on the device. + If it is ename:VK_FALSE this command will implicitly trigger the + preprocessing step, otherwise not. + * pname:pGeneratedCommandsInfo is a pointer to a + slink:VkGeneratedCommandsInfoNV structure containing parameters + affecting the generation of commands. + +If the ename:VK_INDIRECT_COMMANDS_LAYOUT_USAGE_UNORDERED_SEQUENCES_BIT_NV +flag was used to create the +slink:VkGeneratedCommandsInfoNV::pname:indirectCommandsLayout then the order +of execution of individual draws through this command may: execute in any +order, and may: not necessarily be in the same order as specified in +slink:VkGeneratedCommandsInfoNV::pname:pStreams. + +ifdef::VK_NV_device_generated_commands_compute[] +The order of execution of individual dispatches through this command may: +execute in any order and may: not necessarily be in the same order as +specified in slink:VkGeneratedCommandsInfoNV::pname:pStreams. +endif::VK_NV_device_generated_commands_compute[] + +.Valid Usage +**** +include::{chapters}/commonvalidity/draw_common.adoc[] +include::{chapters}/commonvalidity/draw_vertex_binding.adoc[] +ifdef::VK_VERSION_1_1[] + * [[VUID-vkCmdExecuteGeneratedCommandsNV-commandBuffer-02970]] + pname:commandBuffer must: not be a protected command buffer +endif::VK_VERSION_1_1[] + * [[VUID-vkCmdExecuteGeneratedCommandsNV-isPreprocessed-02908]] + If pname:isPreprocessed is ename:VK_TRUE then + flink:vkCmdPreprocessGeneratedCommandsNV must: have already been + executed on the device, using the same pname:pGeneratedCommandsInfo + content as well as the content of the input buffers it references (all + except slink:VkGeneratedCommandsInfoNV::pname:preprocessBuffer). + Furthermore pname:pGeneratedCommandsInfo`s pname:indirectCommandsLayout + must: have been created with the + ename:VK_INDIRECT_COMMANDS_LAYOUT_USAGE_EXPLICIT_PREPROCESS_BIT_NV bit + set + * [[VUID-vkCmdExecuteGeneratedCommandsNV-pipeline-02909]] + slink:VkGeneratedCommandsInfoNV::pname:pipeline must: match the current + bound pipeline at + slink:VkGeneratedCommandsInfoNV::pname:pipelineBindPoint +ifdef::VK_EXT_transform_feedback[] + * [[VUID-vkCmdExecuteGeneratedCommandsNV-None-02910]] + Transform feedback must: not be active +endif::VK_EXT_transform_feedback[] + * [[VUID-vkCmdExecuteGeneratedCommandsNV-deviceGeneratedCommands-02911]] + The <> + feature must: be enabled +**** + +include::{generated}/validity/protos/vkCmdExecuteGeneratedCommandsNV.adoc[] +-- + +[open,refpage='VkGeneratedCommandsInfoNV',desc='Structure specifying parameters for the generation of commands',type='structs'] +-- +:refpage: + +The sname:VkGeneratedCommandsInfoNV is defined as: + +include::{generated}/api/structs/VkGeneratedCommandsInfoNV.adoc[] + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * pname:pipelineBindPoint is the elink:VkPipelineBindPoint used for the + pname:pipeline. + * pname:pipeline is the slink:VkPipeline used in the generation and + execution process. + * pname:indirectCommandsLayout is the slink:VkIndirectCommandsLayoutNV + that provides the command sequence to generate. + * pname:streamCount defines the number of input streams + * pname:pStreams is a pointer to an array of pname:streamCount + slink:VkIndirectCommandsStreamNV structures providing the input data for + the tokens used in pname:indirectCommandsLayout. + * pname:sequencesCount is the maximum number of sequences to reserve. + If pname:sequencesCountBuffer is dlink:VK_NULL_HANDLE, this is also the + actual number of sequences generated. + * pname:preprocessBuffer is the slink:VkBuffer that is used for + preprocessing the input data for execution. + If this structure is used with flink:vkCmdExecuteGeneratedCommandsNV + with its pname:isPreprocessed set to ename:VK_TRUE, then the + preprocessing step is skipped and data in this buffer will not be + modified. + The contents and the layout of this buffer are opaque to applications + and must: not be modified outside functions related to device-generated + commands or copied to another buffer for reuse. + * pname:preprocessOffset is the byte offset into pname:preprocessBuffer + where the preprocessed data is stored. + * pname:preprocessSize is the maximum byte size within the + pname:preprocessBuffer after the pname:preprocessOffset that is + available for preprocessing. + * pname:sequencesCountBuffer is a sname:VkBuffer in which the actual + number of sequences is provided as single code:uint32_t value. + * pname:sequencesCountOffset is the byte offset into + pname:sequencesCountBuffer where the count value is stored. + * pname:sequencesIndexBuffer is a sname:VkBuffer that encodes the used + sequence indices as code:uint32_t array. + * pname:sequencesIndexOffset is the byte offset into + pname:sequencesIndexBuffer where the index values start. + +.Valid Usage +**** + * [[VUID-VkGeneratedCommandsInfoNV-pipeline-02912]] + The provided pname:pipeline must: match the pipeline bound at execution + time + * [[VUID-VkGeneratedCommandsInfoNV-indirectCommandsLayout-02913]] + If the pname:indirectCommandsLayout uses a token of + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_SHADER_GROUP_NV, then the + pname:pipeline must: have been created with multiple shader groups + * [[VUID-VkGeneratedCommandsInfoNV-indirectCommandsLayout-02914]] + If the pname:indirectCommandsLayout uses a token of + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_SHADER_GROUP_NV, then the + pname:pipeline must: have been created with + ename:VK_PIPELINE_CREATE_INDIRECT_BINDABLE_BIT_NV set in + sname:VkGraphicsPipelineCreateInfo::pname:flags + * [[VUID-VkGeneratedCommandsInfoNV-indirectCommandsLayout-02915]] + If the pname:indirectCommandsLayout uses a token of + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_CONSTANT_NV, then the + pname:pipeline's sname:VkPipelineLayout must: match the + slink:VkIndirectCommandsLayoutTokenNV::pname:pushconstantPipelineLayout + * [[VUID-VkGeneratedCommandsInfoNV-streamCount-02916]] + pname:streamCount must: match the pname:indirectCommandsLayout's + pname:streamCount +ifdef::VK_NV_device_generated_commands_compute[] + * [[VUID-VkGeneratedCommandsInfoNV-pipelineBindPoint-09084]] + If pname:pipelineBindPoint is of type + ename:VK_PIPELINE_BIND_POINT_COMPUTE, then the pname:pipeline must: have + been created with the flag + ename:VK_PIPELINE_CREATE_INDIRECT_BINDABLE_BIT_NV + * [[VUID-VkGeneratedCommandsInfoNV-pipelineBindPoint-09085]] + If pname:pipelineBindPoint is of type + ename:VK_PIPELINE_BIND_POINT_COMPUTE, then the pname:pipeline must: have + been created with a slink:VkComputePipelineIndirectBufferInfoNV + structure specifying a valid address where its metadata will be saved + * [[VUID-VkGeneratedCommandsInfoNV-pipelineBindPoint-09086]] + If pname:pipelineBindPoint is of type + ename:VK_PIPELINE_BIND_POINT_COMPUTE, then + flink:vkCmdUpdatePipelineIndirectBufferNV must: have been called on that + pipeline to save its metadata to a device address + * [[VUID-VkGeneratedCommandsInfoNV-pipelineBindPoint-09087]] + If pname:pipelineBindPoint is of type + ename:VK_PIPELINE_BIND_POINT_COMPUTE, and if + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_PIPELINE_NV is used, then + pname:pipeline must: be dlink:VK_NULL_HANDLE +endif::VK_NV_device_generated_commands_compute[] + * [[VUID-VkGeneratedCommandsInfoNV-sequencesCount-02917]] + pname:sequencesCount must: be less or equal to + slink:VkPhysicalDeviceDeviceGeneratedCommandsPropertiesNV::pname:maxIndirectSequenceCount + and + slink:VkGeneratedCommandsMemoryRequirementsInfoNV::pname:maxSequencesCount + that was used to determine the pname:preprocessSize + * [[VUID-VkGeneratedCommandsInfoNV-preprocessBuffer-02918]] + pname:preprocessBuffer must: have the + ename:VK_BUFFER_USAGE_INDIRECT_BUFFER_BIT bit set in its usage flag + * [[VUID-VkGeneratedCommandsInfoNV-preprocessOffset-02919]] + pname:preprocessOffset must: be aligned to + slink:VkPhysicalDeviceDeviceGeneratedCommandsPropertiesNV::pname:minIndirectCommandsBufferOffsetAlignment + * [[VUID-VkGeneratedCommandsInfoNV-preprocessBuffer-02971]] + If pname:preprocessBuffer is non-sparse then it must: be bound + completely and contiguously to a single sname:VkDeviceMemory object + * [[VUID-VkGeneratedCommandsInfoNV-preprocessSize-02920]] + pname:preprocessSize must: be at least equal to the memory requirement`s + size returned by flink:vkGetGeneratedCommandsMemoryRequirementsNV using + the matching inputs (pname:indirectCommandsLayout, ...) as within this + structure + * [[VUID-VkGeneratedCommandsInfoNV-sequencesCountBuffer-02921]] + pname:sequencesCountBuffer can: be set if the actual used count of + sequences is sourced from the provided buffer. + In that case the pname:sequencesCount serves as upper bound + * [[VUID-VkGeneratedCommandsInfoNV-sequencesCountBuffer-02922]] + If pname:sequencesCountBuffer is not dlink:VK_NULL_HANDLE, its usage + flag must: have the ename:VK_BUFFER_USAGE_INDIRECT_BUFFER_BIT bit set + * [[VUID-VkGeneratedCommandsInfoNV-sequencesCountBuffer-02923]] + If pname:sequencesCountBuffer is not dlink:VK_NULL_HANDLE, + pname:sequencesCountOffset must: be aligned to + sname:VkPhysicalDeviceDeviceGeneratedCommandsPropertiesNV::pname:minSequencesCountBufferOffsetAlignment + * [[VUID-VkGeneratedCommandsInfoNV-sequencesCountBuffer-02972]] + If pname:sequencesCountBuffer is not dlink:VK_NULL_HANDLE and is + non-sparse then it must: be bound completely and contiguously to a + single sname:VkDeviceMemory object + * [[VUID-VkGeneratedCommandsInfoNV-sequencesIndexBuffer-02924]] + If pname:indirectCommandsLayout's + ename:VK_INDIRECT_COMMANDS_LAYOUT_USAGE_INDEXED_SEQUENCES_BIT_NV is set, + pname:sequencesIndexBuffer must: be set otherwise it must: be + dlink:VK_NULL_HANDLE + * [[VUID-VkGeneratedCommandsInfoNV-sequencesIndexBuffer-02925]] + If pname:sequencesIndexBuffer is not dlink:VK_NULL_HANDLE, its usage + flag must: have the ename:VK_BUFFER_USAGE_INDIRECT_BUFFER_BIT bit set + * [[VUID-VkGeneratedCommandsInfoNV-sequencesIndexBuffer-02926]] + If pname:sequencesIndexBuffer is not dlink:VK_NULL_HANDLE, + pname:sequencesIndexOffset must: be aligned to + sname:VkPhysicalDeviceDeviceGeneratedCommandsPropertiesNV::pname:minSequencesIndexBufferOffsetAlignment + * [[VUID-VkGeneratedCommandsInfoNV-sequencesIndexBuffer-02973]] + If pname:sequencesIndexBuffer is not dlink:VK_NULL_HANDLE and is + non-sparse then it must: be bound completely and contiguously to a + single sname:VkDeviceMemory object +ifdef::VK_NV_mesh_shader[] + * [[VUID-VkGeneratedCommandsInfoNV-indirectCommandsLayout-07078]] + If the pname:indirectCommandsLayout uses a token of + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_TASKS_NV, then the + pname:pipeline must: contain a shader stage using the code:MeshNV + {ExecutionModel} +endif::VK_NV_mesh_shader[] +ifdef::VK_EXT_mesh_shader[] + * [[VUID-VkGeneratedCommandsInfoNV-indirectCommandsLayout-07079]] + If the pname:indirectCommandsLayout uses a token of + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_NV, then the + pname:pipeline must: contain a shader stage using the code:MeshEXT + {ExecutionModel} +endif::VK_EXT_mesh_shader[] +**** + +include::{generated}/validity/structs/VkGeneratedCommandsInfoNV.adoc[] +-- + +Referencing the functions defined in <>, +fname:vkCmdExecuteGeneratedCommandsNV behaves as: + +[source,c] +---- +uint32_t sequencesCount = sequencesCountBuffer ? + min(maxSequencesCount, sequencesCountBuffer.load_uint32(sequencesCountOffset) : + maxSequencesCount; + + +cmdProcessAllSequences(commandBuffer, pipeline, + indirectCommandsLayout, pIndirectCommandsStreams, + sequencesCount, + sequencesIndexBuffer, sequencesIndexOffset); + +// The stateful commands within indirectCommandsLayout will not +// affect the state of subsequent commands in the target +// command buffer (cmd) +---- + +[NOTE] +==== +It is important to note that the values of all state related to the +pname:pipelineBindPoint used are undefined: after this command. +==== + +[open,refpage='vkCmdPreprocessGeneratedCommandsNV',desc='Performs preprocessing for generated commands',type='protos'] +-- +Commands can: be preprocessed prior execution using the following command: + +include::{generated}/api/protos/vkCmdPreprocessGeneratedCommandsNV.adoc[] + + * pname:commandBuffer is the command buffer which does the preprocessing. + * pname:pGeneratedCommandsInfo is a pointer to a + slink:VkGeneratedCommandsInfoNV structure containing parameters + affecting the preprocessing step. + +.Valid Usage +**** +ifdef::VK_VERSION_1_1[] + * [[VUID-vkCmdPreprocessGeneratedCommandsNV-commandBuffer-02974]] + pname:commandBuffer must: not be a protected command buffer +endif::VK_VERSION_1_1[] + * [[VUID-vkCmdPreprocessGeneratedCommandsNV-pGeneratedCommandsInfo-02927]] + pname:pGeneratedCommandsInfo`s pname:indirectCommandsLayout must: have + been created with the + ename:VK_INDIRECT_COMMANDS_LAYOUT_USAGE_EXPLICIT_PREPROCESS_BIT_NV bit + set + * [[VUID-vkCmdPreprocessGeneratedCommandsNV-deviceGeneratedCommands-02928]] + The <> + feature must: be enabled +**** + +include::{generated}/validity/protos/vkCmdPreprocessGeneratedCommandsNV.adoc[] +-- + +ifdef::VK_NV_device_generated_commands_compute[] +The bound descriptor sets and push constants that will be used with indirect +command generation for the compute pipelines must: already be specified at +the time of preprocessing commands with +flink:vkCmdPreprocessGeneratedCommandsNV. +They must: not change until the execution of indirect commands is submitted +with flink:vkCmdExecuteGeneratedCommandsNV. + +If push constants for the compute pipeline are also specified in the +slink:VkGeneratedCommandsInfoNV::pname:indirectCommandsLayout with +ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_CONSTANT_NV token, then those +values override the push constants that were previously pushed for the +compute pipeline. + +endif::VK_NV_device_generated_commands_compute[] +endif::VK_NV_device_generated_commands[] + +ifdef::VK_EXT_device_generated_commands[] +[open,refpage='vkCmdExecuteGeneratedCommandsEXT',desc='Generate and execute commands on the device',type='protos'] +-- +:refpage: vkCmdExecuteGeneratedCommandsEXT + +With `apiext:VK_EXT_device_generated_commands`, the actual generation of +commands as well as their execution on the device is handled as single +action with: + +include::{generated}/api/protos/vkCmdExecuteGeneratedCommandsEXT.adoc[] + + * pname:commandBuffer is the command buffer into which the command is + recorded. + * pname:isPreprocessed represents whether the input data has already been + preprocessed on the device. + If it is ename:VK_FALSE this command will implicitly trigger the + preprocessing step, otherwise not. + * pname:pGeneratedCommandsInfo is a pointer to a + slink:VkGeneratedCommandsInfoEXT structure containing parameters + affecting the generation of commands. + +If the ename:VK_INDIRECT_COMMANDS_LAYOUT_USAGE_UNORDERED_SEQUENCES_BIT_EXT +flag was used to create the +slink:VkGeneratedCommandsInfoEXT::pname:indirectCommandsLayout then the +execution of sequences through this command may: use implementation-defined +ordering which is not guaranteed to be coherent using the same input data. +It does not affect the order of token processing within a sequence. +This is the implied ordering with +ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_DISPATCH_EXT. + +After a call to fname:vkCmdExecuteGeneratedCommandsEXT, command buffer state +will become undefined: according to the tokens executed. +This table specifies the relationship between tokens used and state +invalidation. + +.Indirect Execution State Invalidation +[width="80%",cols="67%,33%",options="header",align="center"] +|=== +|*Common Tokens* | *States Invalidated* +|ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_EXECUTION_SET_EXT | Bound shaders and pipelines +|ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_CONSTANT_EXT | Push constant data +|ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_SEQUENCE_INDEX_EXT | Push constant data +|ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_INDEX_BUFFER_EXT | Index buffer +|ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_VERTEX_BUFFER_EXT | Vertex buffer +|=== + +.Valid Usage +**** +include::{chapters}/commonvalidity/draw_common.adoc[] +ifdef::VK_VERSION_1_1[] + * [[VUID-vkCmdExecuteGeneratedCommandsEXT-commandBuffer-11045]] + pname:commandBuffer must: not be a protected command buffer +endif::VK_VERSION_1_1[] + * [[VUID-vkCmdExecuteGeneratedCommandsEXT-isPreprocessed-11046]] + If pname:isPreprocessed is ename:VK_TRUE and + flink:vkGetGeneratedCommandsMemoryRequirementsEXT did not return a + required size of zero then flink:vkCmdPreprocessGeneratedCommandsEXT + must: have already been executed on the device before this command + executes, and the preprocessing command must: have used the same + pname:pGeneratedCommandsInfo content as well as the content of the input + buffers it references (all except + slink:VkGeneratedCommandsInfoEXT::pname:preprocessBuffer). + * [[VUID-vkCmdExecuteGeneratedCommandsEXT-isPreprocessed-11047]] + If pname:isPreprocessed is ename:VK_TRUE then the + pname:indirectCommandsLayout member of pname:pGeneratedCommandsInfo + must: have been created with the + ename:VK_INDIRECT_COMMANDS_LAYOUT_USAGE_EXPLICIT_PREPROCESS_BIT_EXT bit + set + * [[VUID-vkCmdExecuteGeneratedCommandsEXT-indirectCommandsLayout-11141]] + If the pname:indirectCommandsLayout member of + pname:pGeneratedCommandsInfo was created with the + ename:VK_INDIRECT_COMMANDS_LAYOUT_USAGE_EXPLICIT_PREPROCESS_BIT_EXT bit + set, then pname:isPreprocessed must: be ename:VK_TRUE + * [[VUID-vkCmdExecuteGeneratedCommandsEXT-preprocessAddress-11142]] + The contents of the pname:preprocessAddress member of + pname:pGeneratedCommandsInfo must: not have been previously used to + record another flink:vkCmdExecuteGeneratedCommandsEXT + * [[VUID-vkCmdExecuteGeneratedCommandsEXT-isPreprocessed-11048]] + If pname:isPreprocessed is ename:VK_TRUE then the bound descriptor sets + and push constants must: match identically with those bound during + recording of the corresponding call to + flink:vkCmdPreprocessGeneratedCommandsEXT. + * [[VUID-vkCmdExecuteGeneratedCommandsEXT-isPreprocessed-11049]] + If pname:isPreprocessed is ename:VK_TRUE and the + pname:indirectCommandsLayout member of pname:pGeneratedCommandsInfo + contains a draw token, then the graphics state bound on + pname:commandBuffer must: match identically with the graphics state + bound on the pname:stateCommandBuffer passed to + flink:vkCmdPreprocessGeneratedCommandsEXT + * [[VUID-vkCmdExecuteGeneratedCommandsEXT-isPreprocessed-11149]] + If pname:isPreprocessed is ename:VK_TRUE, then the queue family index of + pname:commandBuffer must: be the same as the queue family index used to + allocate the pname:stateCommandBuffer passed to + flink:vkCmdPreprocessGeneratedCommandsEXT + * [[VUID-vkCmdExecuteGeneratedCommandsEXT-isPreprocessed-11051]] + If pname:isPreprocessed is ename:VK_TRUE and the + pname:indirectCommandsLayout member of pname:pGeneratedCommandsInfo + contains a dispatch token, then the compute state bound on + pname:commandBuffer must: match identically with the compute state bound + on the pname:stateCommandBuffer passed to + flink:vkCmdPreprocessGeneratedCommandsEXT + * [[VUID-vkCmdExecuteGeneratedCommandsEXT-isPreprocessed-11052]] + If pname:isPreprocessed is ename:VK_TRUE and the + pname:indirectCommandsLayout member of pname:pGeneratedCommandsInfo + contains a ray tracing token, then the ray tracing state bound on + pname:commandBuffer must: match identically with the ray tracing state + bound on the pname:stateCommandBuffer passed to + flink:vkCmdPreprocessGeneratedCommandsEXT + * [[VUID-vkCmdExecuteGeneratedCommandsEXT-isPreprocessed-11150]] + If pname:isPreprocessed is ename:VK_TRUE and the + pname:indirectCommandsLayout member of pname:pGeneratedCommandsInfo + contains a ray tracing token, the queue family index pname:commandBuffer + was allocated from must: be the same queue family index used to allocate + the pname:stateCommandBuffer passed to + flink:vkCmdPreprocessGeneratedCommandsEXT + * [[VUID-vkCmdExecuteGeneratedCommandsEXT-indirectCommandsLayout-11053]] + If the token sequence of the passed + slink:VkGeneratedCommandsInfoEXT::pname:indirectCommandsLayout contains + a ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_EXECUTION_SET_EXT token, the + initial shader state of + slink:VkGeneratedCommandsInfoEXT::pname:indirectExecutionSet must: be + bound on pname:commandBuffer +ifdef::VK_EXT_shader_object[] + * [[VUID-vkCmdExecuteGeneratedCommandsEXT-indirectCommandsLayout-11004]] + If pname:indirectCommandsLayout was created with a token sequence that + contained the ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_EXECUTION_SET_EXT + token and pname:indirectExecutionSet was created using + ename:VK_INDIRECT_EXECUTION_SET_INFO_TYPE_SHADER_OBJECTS_EXT, every + executed ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_EXECUTION_SET_EXT token + must: bind all the shader stages set in the + slink:VkIndirectCommandsExecutionSetTokenEXT::pname:shaderStages used to + create pname:indirectCommandsLayout +endif::VK_EXT_shader_object[] + * [[VUID-vkCmdExecuteGeneratedCommandsEXT-isPreprocessed-11055]] + If pname:isPreprocessed is ename:VK_TRUE and the token sequence of the + passed slink:VkGeneratedCommandsInfoEXT::pname:indirectCommandsLayout + contains a ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_EXECUTION_SET_EXT + token, the members of + slink:VkGeneratedCommandsInfoEXT::pname:indirectExecutionSet accessed by + this command must: not have been modified since the preprocess buffer + was generated +ifdef::VK_EXT_fragment_density_map[] + * [[VUID-vkCmdExecuteGeneratedCommandsEXT-indirectCommandsLayout-11056]] + If the pname:indirectCommandsLayout member of + pname:pGeneratedCommandsInfo contains a draw token, then the active + render pass must: not have a specified fragment density map +endif::VK_EXT_fragment_density_map[] +ifdef::VK_EXT_transform_feedback[] + * [[VUID-vkCmdExecuteGeneratedCommandsEXT-deviceGeneratedCommandsTransformFeedback-11057]] + If + <> + is not supported on device, transform feedback must: not be active + * [[VUID-vkCmdExecuteGeneratedCommandsEXT-indirectExecutionSet-11058]] + If transform feedback is active, + slink:VkGeneratedCommandsInfoEXT::pname:indirectExecutionSet must: be + dlink:VK_NULL_HANDLE +endif::VK_EXT_transform_feedback[] + * [[VUID-vkCmdExecuteGeneratedCommandsEXT-deviceGeneratedCommands-11059]] + The <> + feature must: be enabled + * [[VUID-vkCmdExecuteGeneratedCommandsEXT-supportedIndirectCommandsShaderStages-11060]] + The currently bound shader stages must: be supported by + <> + * [[VUID-vkCmdExecuteGeneratedCommandsEXT-supportedIndirectCommandsShaderStages-11061]] + Only stages specified in <> + can: be set in pname:pGeneratedCommandsInfo->shaderStages + * [[VUID-vkCmdExecuteGeneratedCommandsEXT-None-11062]] + If a rendering pass is currently active, the view mask must: be `0`. + * [[VUID-vkCmdExecuteGeneratedCommandsEXT-commandBuffer-11143]] + pname:commandBuffer must: not have been created with + ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT +**** + +include::{generated}/validity/protos/vkCmdExecuteGeneratedCommandsEXT.adoc[] +-- + +[open,refpage='VkGeneratedCommandsInfoEXT',desc='Structure specifying parameters for the generation of commands',type='structs'] +-- +:refpage: + +The sname:VkGeneratedCommandsInfoEXT is defined as: + +include::{generated}/api/structs/VkGeneratedCommandsInfoEXT.adoc[] + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * pname:shaderStages is the mask of shader stages used by the commands. + * pname:indirectExecutionSet is the indirect execution set to be used for + binding shaders. + * pname:indirectCommandsLayout is the slink:VkIndirectCommandsLayoutEXT + that specifies the command sequence data. + * pname:indirectAddress is an address that holds the indirect buffer data. + * pname:indirectAddressSize is the size in bytes of indirect buffer data + starting at pname:indirectAddress. + * pname:preprocessAddress specifies a physical address of the + sname:VkBuffer used for preprocessing the input data for execution. + If this structure is used with flink:vkCmdExecuteGeneratedCommandsEXT + with its pname:isPreprocessed set to ename:VK_TRUE, then the + preprocessing step is skipped but data in this address may: still be + modified. + The contents and the layout of this address are opaque to applications + and must: not be modified outside functions related to device-generated + commands or copied to another buffer for reuse. + * pname:preprocessSize is the maximum byte size within + pname:preprocessAddress that is available for preprocessing. + * pname:maxSequenceCount is used to determine the number of sequences to + execute. + * pname:sequenceCountAddress specifies an optional physical address of a + single code:uint32_t value containing the requested number of sequences + to execute. + * pname:maxDrawCount is the maximum number of indirect draws that can be + executed by any COUNT-type multi-draw indirect tokens. + The draw count in the indirect buffer is clamped to this value for these + token types. + +If pname:sequenceCountAddress is not `NULL`, then pname:maxSequenceCount is +the maximum number of sequences that can be executed. +The actual number is `min(maxSequenceCount, *sequenceCountAddress)`. +If pname:sequenceCountAddress is `NULL`, then pname:maxSequenceCount is the +exact number of sequences to execute. + +If the action command token for the layout is not a COUNT-type multi-draw +indirect token, pname:maxDrawCount is ignored. + +.Valid Usage +**** + * [[VUID-VkGeneratedCommandsInfoEXT-preprocessAddress-11063]] + If flink:vkGetGeneratedCommandsMemoryRequirementsEXT returns a non-zero + size, pname:preprocessAddress must: not be `NULL` + * [[VUID-VkGeneratedCommandsInfoEXT-preprocessAddress-11064]] + sname:VkDeviceMemory objects bound to the underlying buffer for + pname:preprocessAddress must: have been allocated using one of the + memory types allowed in the pname:memoryTypeBits member of the + slink:VkMemoryRequirements structure returned by + flink:vkGetGeneratedCommandsMemoryRequirementsEXT + * [[VUID-VkGeneratedCommandsInfoEXT-indirectCommandsLayout-11065]] + If the pname:indirectCommandsLayout uses a token of + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_CONSTANT_EXT, then the + pname:indirectExecutionSet's push constant layout must: contain the + pname:updateRange specified in + slink:VkIndirectCommandsPushConstantTokenEXT + * [[VUID-VkGeneratedCommandsInfoEXT-indirectCommandsLayout-11066]] + If the pname:indirectCommandsLayout uses a token of + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_SEQUENCE_INDEX_EXT, then the + pname:indirectExecutionSet's push constant layout must: contain the + pname:updateRange specified in + slink:VkIndirectCommandsPushConstantTokenEXT + * [[VUID-VkGeneratedCommandsInfoEXT-maxSequenceCount-11067]] + pname:maxSequenceCount must: be less or equal to + slink:VkPhysicalDeviceDeviceGeneratedCommandsPropertiesEXT::pname:maxIndirectSequenceCount + and + slink:VkGeneratedCommandsMemoryRequirementsInfoEXT::pname:maxSequencesCount + that was used to determine the pname:preprocessSize + * [[VUID-VkGeneratedCommandsInfoEXT-sequenceCountAddress-11068]] + If pname:sequenceCountAddress is not `NULL`, the value contained in the + address must: be less or equal to + slink:VkPhysicalDeviceDeviceGeneratedCommandsPropertiesEXT::pname:maxIndirectSequenceCount + and + slink:VkGeneratedCommandsMemoryRequirementsInfoEXT::pname:maxSequencesCount + that was used to determine the pname:preprocessSize + * [[VUID-VkGeneratedCommandsInfoEXT-preprocessAddress-11069]] + The underlying buffer for pname:preprocessAddress must: have the + ename:VK_BUFFER_USAGE_2_PREPROCESS_BUFFER_BIT_EXT bit set in its usage + flag + * [[VUID-VkGeneratedCommandsInfoEXT-preprocessAddress-11070]] + If the underlying buffer for pname:preprocessAddress is non-sparse then + it must: be bound completely and contiguously to a single + sname:VkDeviceMemory object + * [[VUID-VkGeneratedCommandsInfoEXT-indirectCommandsLayout-11144]] + If the pname:indirectCommandsLayout contains a + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_EXECUTION_SET_EXT token, then the + descriptor and push constant layout info provided either by + pname:pipelineLayout or through a slink:VkPipelineLayoutCreateInfo in + pname:pNext of the slink:VkIndirectCommandsLayoutCreateInfoEXT used to + create pname:indirectCommandsLayout must: be + <> with the descriptor and push + constant layout info used by pname:indirectExecutionSet + * [[VUID-VkGeneratedCommandsInfoEXT-indirectCommandsLayout-11002]] + If pname:indirectCommandsLayout was created with a token sequence that + contained the ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_EXECUTION_SET_EXT + token, the shader stages used to create the initial shader state of + pname:indirectExecutionSet must: equal the + slink:VkIndirectCommandsExecutionSetTokenEXT::pname:shaderStages used to + create pname:indirectCommandsLayout + * [[VUID-VkGeneratedCommandsInfoEXT-preprocessSize-11071]] + pname:preprocessSize must: be greater than or equal to the memory + requirement's size returned by + flink:vkGetGeneratedCommandsMemoryRequirementsEXT using the matching + inputs (pname:indirectCommandsLayout, ...) as within this structure + * [[VUID-VkGeneratedCommandsInfoEXT-sequenceCountAddress-11072]] + The underlying buffer for pname:sequenceCountAddress must: have the + ename:VK_BUFFER_USAGE_2_PREPROCESS_BUFFER_BIT_EXT bit set in its usage + flag + * [[VUID-VkGeneratedCommandsInfoEXT-sequenceCountAddress-11073]] + If pname:sequenceCountAddress is not `NULL`, pname:sequenceCountAddress + must: be aligned to `4` + * [[VUID-VkGeneratedCommandsInfoEXT-indirectAddress-11074]] + pname:indirectAddress must: be aligned to `4` + * [[VUID-VkGeneratedCommandsInfoEXT-sequenceCountAddress-11075]] + If the underlying buffer for pname:sequenceCountAddress is non-sparse + then it must: be bound completely and contiguously to a single + sname:VkDeviceMemory object + * [[VUID-VkGeneratedCommandsInfoEXT-indirectAddress-11076]] + pname:indirectAddress must: not be `NULL` + * [[VUID-VkGeneratedCommandsInfoEXT-indirectAddressSize-11077]] + pname:indirectAddressSize must: be greater than zero + * [[VUID-VkGeneratedCommandsInfoEXT-maxDrawCount-11078]] + When not ignored, [eq]#pname:maxDrawCount {times} + pname:maxSequenceCount# must: be less than [eq]#2^24# + * [[VUID-VkGeneratedCommandsInfoEXT-indirectCommandsLayout-11079]] + If pname:indirectCommandsLayout was created using a + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_VERTEX_BUFFER_EXT token +ifdef::VK_EXT_shader_object[and shader objects are not bound] + then the currently bound graphics pipeline must: have been created with + ename:VK_DYNAMIC_STATE_VERTEX_INPUT_BINDING_STRIDE in + pname:pDynamicStates + * [[VUID-VkGeneratedCommandsInfoEXT-indirectCommandsLayout-11083]] + If the token sequence of the passed pname:indirectCommandsLayout + contains a ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_EXECUTION_SET_EXT + token, the pname:indirectExecutionSet must: not be dlink:VK_NULL_HANDLE + * [[VUID-VkGeneratedCommandsInfoEXT-indirectExecutionSet-11080]] + If pname:indirectExecutionSet is dlink:VK_NULL_HANDLE, a + slink:VkGeneratedCommandsPipelineInfoEXT +ifdef::VK_EXT_shader_object[or slink:VkGeneratedCommandsShaderInfoEXT] + must: be included in the pname:pNext chain +**** + +include::{generated}/validity/structs/VkGeneratedCommandsInfoEXT.adoc[] +-- + +Referencing the functions defined in <>, +fname:vkCmdExecuteGeneratedCommandsEXT behaves as: + +[source,c] +---- +uint32_t sequencesCount = sequenceCountAddress ? + min(maxSequenceCount, sequenceCountAddress.load_uint32()) : + maxSequenceCount; + + +cmdProcessAllSequences(commandBuffer, indirectExecutionSet, + indirectCommandsLayout, indirectAddress, + sequencesCount); + +// The stateful commands within indirectCommandsLayout will not +// affect the state of subsequent commands in the target +// command buffer (cmd) +---- + +[NOTE] +.Note +==== +It is important to note that the affected values of all state related to the +pname:shaderStages used are undefined: after this command. +This means that e.g., if this command indirectly alters push constants, the +push constant state becomes undefined:. +==== + +[open,refpage='vkCmdPreprocessGeneratedCommandsEXT',desc='Performs preprocessing for generated commands',type='protos'] +-- +Commands can: be preprocessed prior execution using the following command: + +include::{generated}/api/protos/vkCmdPreprocessGeneratedCommandsEXT.adoc[] + + * pname:commandBuffer is the command buffer which does the preprocessing. + * pname:pGeneratedCommandsInfo is a pointer to a + slink:VkGeneratedCommandsInfoEXT structure containing parameters + affecting the preprocessing step. + * pname:stateCommandBuffer is a command buffer from which to snapshot + current states affecting the preprocessing step. + When a graphics command action token is used, graphics state is + snapshotted. + When a compute action command token is used, compute state is + snapshotted. + When a ray tracing action command token is used, ray tracing state is + snapshotted. + It can be deleted at any time after this command has been recorded. + +[NOTE] +.Note +==== +pname:stateCommandBuffer access is not synchronized by the driver, meaning +that this command buffer must: not be modified between threads in an unsafe +manner. +==== + +.Valid Usage +**** +ifdef::VK_VERSION_1_1[] + * [[VUID-vkCmdPreprocessGeneratedCommandsEXT-commandBuffer-11081]] + pname:commandBuffer must: not be a protected command buffer +endif::VK_VERSION_1_1[] + * [[VUID-vkCmdPreprocessGeneratedCommandsEXT-pGeneratedCommandsInfo-11082]] + pname:pGeneratedCommandsInfo's pname:indirectCommandsLayout must: have + been created with the + ename:VK_INDIRECT_COMMANDS_LAYOUT_USAGE_EXPLICIT_PREPROCESS_BIT_EXT bit + set + * [[VUID-vkCmdPreprocessGeneratedCommandsEXT-indirectCommandsLayout-11084]] + If the token sequence of the passed + slink:VkGeneratedCommandsInfoEXT::pname:indirectCommandsLayout contains + a ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_EXECUTION_SET_EXT token, the + initial shader state of + slink:VkGeneratedCommandsInfoEXT::pname:indirectExecutionSet must: be + bound on pname:stateCommandBuffer + * [[VUID-vkCmdPreprocessGeneratedCommandsEXT-stateCommandBuffer-11138]] + pname:stateCommandBuffer must: be in the recording state + * [[VUID-vkCmdPreprocessGeneratedCommandsEXT-deviceGeneratedCommands-11087]] + The <> + feature must: be enabled + * [[VUID-vkCmdPreprocessGeneratedCommandsEXT-supportedIndirectCommandsShaderStages-11088]] + Only stages specified in <> + can: be set in pname:pGeneratedCommandsInfo->shaderStages +**** + +include::{generated}/validity/protos/vkCmdPreprocessGeneratedCommandsEXT.adoc[] +-- + +The bound descriptor sets and push constants that will be used with indirect +command generation must: already be specified on pname:stateCommandBuffer at +the time of preprocessing commands with +flink:vkCmdPreprocessGeneratedCommandsEXT. +They must: match the bound descriptor sets and push constants used in the +execution of indirect commands with flink:vkCmdExecuteGeneratedCommandsEXT. + +If push constants for shader stages are also specified in the +slink:VkGeneratedCommandsInfoEXT::pname:indirectCommandsLayout with a +ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_CONSTANT_EXT or +ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_SEQUENCE_INDEX_EXT token, then those +values override the push constants that were previously pushed. + +All state bound on pname:stateCommandBuffer will be used. +All state bound on pname:stateCommandBuffer must: be identical to the state +bound at the time flink:vkCmdExecuteGeneratedCommandsEXT is recorded. +The queue family index pname:stateCommandBuffer was allocated from must: be +the same as the queue family index of the command buffer used in +flink:vkCmdExecuteGeneratedCommandsEXT. + +On some implementations, preprocessing may: have no effect on performance. + +flink:vkCmdExecuteGeneratedCommandsEXT may: write to the preprocess buffer, +no matter the isPreprocess parameter. +In this case, the implementation must: insert appropriate synchronization +automatically, which corresponds to the following pseudocode: + +* Barrier +** srcStageMask = DRAW_INDIRECT +** srcAccesMask = 0 +** dstStageMask = COMMAND_PREPROCESS_BIT +** dstAccessMask = COMMAND_PREPROCESS_WRITE_BIT | + COMMAND_PREPROCESS_READ_BIT +* Do internal writes +* Barrier +** srcStageMask = COMMAND_PREPROCESS_BIT +** srcAccesMask = COMMAND_PREPROCESS_WRITE_BIT +** dstStageMask = DRAW_INDIRECT +** dstAccessMask = INDIRECT_COMMAND_READ_BIT +* Execute + +endif::VK_EXT_device_generated_commands[] diff --git a/chapters/device_generated_commands/indirectcommands.adoc b/chapters/device_generated_commands/indirectcommands.adoc new file mode 100644 index 000000000..98ea88e9f --- /dev/null +++ b/chapters/device_generated_commands/indirectcommands.adoc @@ -0,0 +1,1663 @@ +// Copyright (c) 2019-2020 NVIDIA Corporation +// Copyright (c) 2024 VALVE Corporation +// +// SPDX-License-Identifier: CC-BY-4.0 + +[[indirectmdslayout]] +== Indirect Commands Layout + +The device-side command generation happens through an iterative processing +of an atomic sequence comprised of command tokens, which are represented by: + +ifdef::VK_EXT_device_generated_commands[] +[open,refpage='VkIndirectCommandsLayoutEXT',desc='Opaque handle to an indirect commands layout object',type='handles'] +-- +include::{generated}/api/handles/VkIndirectCommandsLayoutEXT.adoc[] +-- +endif::VK_EXT_device_generated_commands[] + +ifdef::VK_EXT_device_generated_commands+VK_NV_device_generated_commands[or:] + +ifdef::VK_NV_device_generated_commands[] +[open,refpage='VkIndirectCommandsLayoutNV',desc='Opaque handle to an indirect commands layout object',type='handles'] +-- +include::{generated}/api/handles/VkIndirectCommandsLayoutNV.adoc[] +-- +endif::VK_NV_device_generated_commands[] + +Each indirect command layout must: have exactly one action command token and +it must: be the last token in the sequence. + +[NOTE] +==== +If the indirect commands layout contains only 1 token, it will be an action +command token, and the contents of the indirect buffer will be a sequence of +indirect command structures, similar to the ones used for indirect draws and +dispatches. +On some implementations, using indirect draws and dispatches for these cases +will result in increased performance compared to using device-generated +commands, due to the overhead that results from using the latter. +==== + +=== Creation and Deletion + + +ifdef::VK_EXT_device_generated_commands[] +[open,refpage='vkCreateIndirectCommandsLayoutEXT',desc='Create an indirect command layout object',type='protos'] +-- +Indirect command layouts for `apiext:VK_EXT_device_generated_commands` are +created by: + +include::{generated}/api/protos/vkCreateIndirectCommandsLayoutEXT.adoc[] + + * pname:device is the logical device that creates the indirect command + layout. + * pname:pCreateInfo is a pointer to a + slink:VkIndirectCommandsLayoutCreateInfoEXT structure containing + parameters affecting creation of the indirect command layout. + * pname:pAllocator controls host memory allocation as described in the + <> chapter. + * pname:pIndirectCommandsLayout is a pointer to a + sname:VkIndirectCommandsLayoutEXT handle in which the resulting indirect + command layout is returned. + +.Valid Usage +**** + * [[VUID-vkCreateIndirectCommandsLayoutEXT-deviceGeneratedCommands-11089]] + The <> + feature must: be enabled +**** + +include::{generated}/validity/protos/vkCreateIndirectCommandsLayoutEXT.adoc[] +-- + +[open,refpage='VkIndirectCommandsLayoutCreateInfoEXT',desc='Structure specifying the parameters of a newly created indirect commands layout object',type='structs'] +-- +The sname:VkIndirectCommandsLayoutCreateInfoEXT structure is defined as: + +include::{generated}/api/structs/VkIndirectCommandsLayoutCreateInfoEXT.adoc[] + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * pname:flags is a bitmask of + elink:VkIndirectCommandsLayoutUsageFlagBitsEXT specifying usage rules + for this layout. + * pname:shaderStages is the tlink:VkShaderStageFlags that this layout + supports. + * pname:indirectStride is the distance in bytes between sequences in the + indirect buffer + * pname:pipelineLayout is the optional slink:VkPipelineLayout that tokens + in this layout use. + If the <> feature is enabled, + pname:pipelineLayout can: be dlink:VK_NULL_HANDLE and the layout must: + be specified by chaining the slink:VkPipelineLayoutCreateInfo structure + off the pname:pNext + * pname:tokenCount is the length of the individual command sequence. + * pname:pTokens is a pointer to an array of + slink:VkIndirectCommandsLayoutTokenEXT describing each command token in + detail. + +The following code illustrates some of the flags: + +[source,c] +---- +void cmdProcessAllSequences(cmd, indirectExecutionSet, indirectCommandsLayout, indirectAddress, sequencesCount) +{ + for (s = 0; s < sequencesCount; s++) + { + sUsed = s; + + if (indirectCommandsLayout.flags & VK_INDIRECT_COMMANDS_LAYOUT_USAGE_UNORDERED_SEQUENCES_BIT_EXT) { + sUsed = incoherent_implementation_dependent_permutation[ sUsed ]; + } + + cmdProcessSequence( cmd, indirectExecutionSet, indirectCommandsLayout, indirectAddress, sUsed ); + } +} +---- + +When tokens are consumed, an offset is computed based on token offset and +stream stride. +The resulting offset is required to be aligned. +The alignment for a specific token is equal to the scalar alignment of the +data type as defined in <>, or `4`, whichever is lower. + +.Valid Usage +**** + * [[VUID-VkIndirectCommandsLayoutCreateInfoEXT-indirectStride-11090]] + pname:indirectStride must: be less than or equal to + slink:VkPhysicalDeviceDeviceGeneratedCommandsPropertiesEXT::pname:maxIndirectCommandsIndirectStride + * [[VUID-VkIndirectCommandsLayoutCreateInfoEXT-shaderStages-11091]] + pname:shaderStages must: only contain stages supported by + <> + * [[VUID-VkIndirectCommandsLayoutCreateInfoEXT-tokenCount-11092]] + pname:tokenCount must: less than or equal to + slink:VkPhysicalDeviceDeviceGeneratedCommandsPropertiesEXT::pname:maxIndirectCommandsTokenCount + * [[VUID-VkIndirectCommandsLayoutCreateInfoEXT-pTokens-11093]] + The number of tokens in the pname:pTokens array with pname:type equal to + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_EXECUTION_SET_EXT must: be less + than or equal to `1` + * [[VUID-VkIndirectCommandsLayoutCreateInfoEXT-pTokens-11145]] + The number of tokens in the pname:pTokens array with pname:type equal to + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_SEQUENCE_INDEX_EXT must: be less + than or equal to `1` + * [[VUID-VkIndirectCommandsLayoutCreateInfoEXT-pTokens-11094]] + The number of tokens in the pname:pTokens array with pname:type equal to + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_INDEX_BUFFER_EXT must: be less + than or equal to `1` + * [[VUID-VkIndirectCommandsLayoutCreateInfoEXT-pTokens-11095]] + If the action command token in the pname:pTokens array is not an indexed + draw token, then pname:pTokens must: not contain a member with + pname:type set to ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_INDEX_BUFFER_EXT + * [[VUID-VkIndirectCommandsLayoutCreateInfoEXT-pTokens-11096]] + If the action command token in the pname:pTokens array is not a non-mesh + draw token, then pname:pTokens must: not contain a member with + pname:type set to + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_VERTEX_BUFFER_EXT + * [[VUID-VkIndirectCommandsLayoutCreateInfoEXT-pTokens-11097]] + If the pname:pTokens array contains multiple tokens with pname:type + equal to ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_VERTEX_BUFFER_EXT, then + there must: be no duplicate + slink:VkIndirectCommandsVertexBufferTokenEXT::pname:vertexBindingUnit + values + * [[VUID-VkIndirectCommandsLayoutCreateInfoEXT-pTokens-11099]] + For all ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_CONSTANT_EXT and + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_SEQUENCE_INDEX_EXT type tokens in + pname:pTokens, there must: be no overlapping ranges between any + specified push constant ranges + * [[VUID-VkIndirectCommandsLayoutCreateInfoEXT-pTokens-11100]] + The action command token must: be the last token in the pname:pTokens + array + * [[VUID-VkIndirectCommandsLayoutCreateInfoEXT-pTokens-11139]] + If the pname:pTokens array contains a + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_EXECUTION_SET_EXT token, then this + token must: be the first token in the array + * [[VUID-VkIndirectCommandsLayoutCreateInfoEXT-pTokens-11101]] + For any element of pname:pTokens, if pname:type is + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_CONSTANT_EXT or + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_SEQUENCE_INDEX_EXT and the + <> is not enabled, then the + pname:pipelineLayout must: not be dlink:VK_NULL_HANDLE + * [[VUID-VkIndirectCommandsLayoutCreateInfoEXT-pTokens-11102]] + For any element of pname:pTokens, if pname:type is either + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_CONSTANT_EXT or + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_SEQUENCE_INDEX_EXT and + pname:pipelineLayout is dlink:VK_NULL_HANDLE, then the pname:pNext chain + must: include a slink:VkPipelineLayoutCreateInfo struct + * [[VUID-VkIndirectCommandsLayoutCreateInfoEXT-pTokens-11103]] + For any element of pname:pTokens, the pname:offset must: be greater than + or equal to the pname:offset member of the previous tokens + * [[VUID-VkIndirectCommandsLayoutCreateInfoEXT-pTokens-11104]] + For any element of pname:pTokens, if pname:type is + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_INDEX_BUFFER_EXT, + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_VERTEX_BUFFER_EXT, +ifdef::VK_EXT_mesh_shader[] + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_EXT, + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_COUNT_EXT, +endif::VK_EXT_mesh_shader[] +ifdef::VK_NV_mesh_shader[] + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_NV_EXT, + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_COUNT_NV_EXT, +endif::VK_NV_mesh_shader[] + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_INDEXED_COUNT_EXT, + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_INDEXED_EXT, or + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_EXT, then pname:shaderStages + must: contain graphics stages + * [[VUID-VkIndirectCommandsLayoutCreateInfoEXT-pTokens-11105]] + For any element of pname:pTokens, if pname:type is + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_DISPATCH_EXT, then + pname:shaderStages must: be ename:VK_SHADER_STAGE_COMPUTE_BIT +ifdef::VK_EXT_mesh_shader[] + * [[VUID-VkIndirectCommandsLayoutCreateInfoEXT-pTokens-11106]] + For any element of pname:pTokens, if pname:type is + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_EXT or + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_COUNT_EXT, then + pname:shaderStages must: contain ename:VK_SHADER_STAGE_MESH_BIT_EXT +endif::VK_EXT_mesh_shader[] +ifdef::VK_NV_mesh_shader[] + * [[VUID-VkIndirectCommandsLayoutCreateInfoEXT-pTokens-11107]] + For any element of pname:pTokens, if pname:type is + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_NV_EXT or + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_COUNT_NV_EXT, then + the pname:shaderStages must: contain ename:VK_SHADER_STAGE_MESH_BIT_NV +endif::VK_NV_mesh_shader[] +ifdef::VK_KHR_ray_tracing_pipeline[] + * [[VUID-VkIndirectCommandsLayoutCreateInfoEXT-pTokens-11108]] + For any element of pname:pTokens, if pname:type is + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_TRACE_RAYS2_EXT, then + pname:shaderStages must: contain ray tracing stages +endif::VK_KHR_ray_tracing_pipeline[] + * [[VUID-VkIndirectCommandsLayoutCreateInfoEXT-shaderStages-11109]] + If pname:shaderStages contains graphics stages then the state tokens in + pname:pTokens must: not include +ifdef::VK_KHR_ray_tracing_maintenance1[ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_TRACE_RAYS2_EXT,] + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_DISPATCH_EXT + * [[VUID-VkIndirectCommandsLayoutCreateInfoEXT-shaderStages-11110]] + If pname:shaderStages is ename:VK_SHADER_STAGE_COMPUTE_BIT then the + state tokens in pname:pTokens must: only include + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_DISPATCH_EXT, + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_EXECUTION_SET_EXT, + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_CONSTANT_EXT, or + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_SEQUENCE_INDEX_EXT +ifdef::VK_KHR_ray_tracing_maintenance1[] + * [[VUID-VkIndirectCommandsLayoutCreateInfoEXT-shaderStages-11111]] + If pname:shaderStages contains ray tracing stages then the state tokens + in pname:pTokens must: only include + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_TRACE_RAYS2_EXT, + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_EXECUTION_SET_EXT, + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_CONSTANT_EXT, or + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_SEQUENCE_INDEX_EXT +endif::VK_KHR_ray_tracing_maintenance1[] + * [[VUID-VkIndirectCommandsLayoutCreateInfoEXT-shaderStages-11112]] + The pname:shaderStages must: only contain stages from one of the + following: + ** graphics stages + ** ename:VK_SHADER_STAGE_COMPUTE_BIT +ifdef::VK_EXT_mesh_shader,VK_NV_mesh_shader[] + ** mesh stages and ename:VK_SHADER_STAGE_FRAGMENT_BIT +endif::VK_EXT_mesh_shader,VK_NV_mesh_shader[] +ifdef::VK_KHR_ray_tracing_pipeline[] + ** ray tracing stages +endif::VK_KHR_ray_tracing_pipeline[] + * [[VUID-VkIndirectCommandsLayoutCreateInfoEXT-shaderStages-11113]] + If pname:shaderStages contains ename:VK_SHADER_STAGE_FRAGMENT_BIT, then + pname:shaderStages must: also contain ename:VK_SHADER_STAGE_VERTEX_BIT +ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] + or ename:VK_SHADER_STAGE_MESH_BIT_EXT +endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] +**** + +include::{generated}/validity/structs/VkIndirectCommandsLayoutCreateInfoEXT.adoc[] +-- + +[open,refpage='VkIndirectCommandsLayoutUsageFlagBitsEXT',desc='Bitmask specifying allowed usage of an indirect commands layout',type='enums'] +-- +Bits which can: be set in +slink:VkIndirectCommandsLayoutCreateInfoEXT::pname:flags, specifying usage +hints of an indirect command layout, are: + +include::{generated}/api/enums/VkIndirectCommandsLayoutUsageFlagBitsEXT.adoc[] + + * ename:VK_INDIRECT_COMMANDS_LAYOUT_USAGE_EXPLICIT_PREPROCESS_BIT_EXT + specifies that the layout is always used with the manual preprocessing + step through calling flink:vkCmdPreprocessGeneratedCommandsEXT and + executed by flink:vkCmdExecuteGeneratedCommandsEXT with `isPreprocessed` + set to ename:VK_TRUE. + * ename:VK_INDIRECT_COMMANDS_LAYOUT_USAGE_UNORDERED_SEQUENCES_BIT_EXT + specifies that the processing of sequences will happen at an + implementation-dependent order, which is not guaranteed to be + deterministic using the same input data. + This flag is ignored when the pname:shaderStages is + ename:VK_SHADER_STAGE_COMPUTE_BIT as it is implied that the dispatch + sequence is always unordered. +-- + +[open,refpage='VkIndirectCommandsLayoutUsageFlagsEXT',desc='Bitmask of VkIndirectCommandsLayoutUsageFlagBitsEXT',type='flags'] +-- +include::{generated}/api/flags/VkIndirectCommandsLayoutUsageFlagsEXT.adoc[] + +tname:VkIndirectCommandsLayoutUsageFlagsEXT is a bitmask type for setting a +mask of zero or more elink:VkIndirectCommandsLayoutUsageFlagBitsEXT. +-- + +[open,refpage='vkDestroyIndirectCommandsLayoutEXT',desc='Destroy an indirect commands layout',type='protos'] +-- +Indirect command layouts for `apiext:VK_EXT_device_generated_commands` are +destroyed by: + +include::{generated}/api/protos/vkDestroyIndirectCommandsLayoutEXT.adoc[] + + * pname:device is the logical device that destroys the layout. + * pname:indirectCommandsLayout is the layout to destroy. + * pname:pAllocator controls host memory allocation as described in the + <> chapter. + +.Valid Usage +**** + * [[VUID-vkDestroyIndirectCommandsLayoutEXT-indirectCommandsLayout-11114]] + All submitted commands that refer to pname:indirectCommandsLayout must: + have completed execution +ifndef::VKSC_VERSION_1_0[] + * [[VUID-vkDestroyIndirectCommandsLayoutEXT-indirectCommandsLayout-11115]] + If sname:VkAllocationCallbacks were provided when + pname:indirectCommandsLayout was created, a compatible set of callbacks + must: be provided here + * [[VUID-vkDestroyIndirectCommandsLayoutEXT-indirectCommandsLayout-11116]] + If no sname:VkAllocationCallbacks were provided when + pname:indirectCommandsLayout was created, pname:pAllocator must: be + `NULL` +endif::VKSC_VERSION_1_0[] +**** + +include::{generated}/validity/protos/vkDestroyIndirectCommandsLayoutEXT.adoc[] +-- +endif::VK_EXT_device_generated_commands[] + +ifdef::VK_NV_device_generated_commands[] + +[open,refpage='vkCreateIndirectCommandsLayoutNV',desc='Create an indirect command layout object',type='protos'] +-- +Indirect command layouts for `apiext:VK_NV_device_generated_commands` are +created by: + +include::{generated}/api/protos/vkCreateIndirectCommandsLayoutNV.adoc[] + + * pname:device is the logical device that creates the indirect command + layout. + * pname:pCreateInfo is a pointer to a + slink:VkIndirectCommandsLayoutCreateInfoNV structure containing + parameters affecting creation of the indirect command layout. + * pname:pAllocator controls host memory allocation as described in the + <> chapter. + * pname:pIndirectCommandsLayout is a pointer to a + sname:VkIndirectCommandsLayoutNV handle in which the resulting indirect + command layout is returned. + +.Valid Usage +**** + * [[VUID-vkCreateIndirectCommandsLayoutNV-deviceGeneratedCommands-02929]] + The <> + feature must: be enabled +**** + +include::{generated}/validity/protos/vkCreateIndirectCommandsLayoutNV.adoc[] +-- + +[open,refpage='VkIndirectCommandsLayoutCreateInfoNV',desc='Structure specifying the parameters of a newly created indirect commands layout object',type='structs'] +-- +The sname:VkIndirectCommandsLayoutCreateInfoNV structure is defined as: + +include::{generated}/api/structs/VkIndirectCommandsLayoutCreateInfoNV.adoc[] + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * pname:pipelineBindPoint is the elink:VkPipelineBindPoint that this + layout targets. + * pname:flags is a bitmask of + elink:VkIndirectCommandsLayoutUsageFlagBitsNV specifying usage hints of + this layout. + * pname:tokenCount is the length of the individual command sequence. + * pname:pTokens is an array describing each command token in detail. + See elink:VkIndirectCommandsTokenTypeNV and + slink:VkIndirectCommandsLayoutTokenNV below for details. + * pname:streamCount is the number of streams used to provide the token + inputs. + * pname:pStreamStrides is an array defining the byte stride for each input + stream. + +The following code illustrates some of the flags: + +[source,c] +---- +void cmdProcessAllSequences(cmd, pipeline, indirectCommandsLayout, pIndirectCommandsTokens, sequencesCount, indexbuffer, indexbufferOffset) +{ + for (s = 0; s < sequencesCount; s++) + { + sUsed = s; + + if (indirectCommandsLayout.flags & VK_INDIRECT_COMMANDS_LAYOUT_USAGE_INDEXED_SEQUENCES_BIT_NV) { + sUsed = indexbuffer.load_uint32( sUsed * sizeof(uint32_t) + indexbufferOffset); + } + + if (indirectCommandsLayout.flags & VK_INDIRECT_COMMANDS_LAYOUT_USAGE_UNORDERED_SEQUENCES_BIT_NV) { + sUsed = incoherent_implementation_dependent_permutation[ sUsed ]; + } + + cmdProcessSequence( cmd, pipeline, indirectCommandsLayout, pIndirectCommandsTokens, sUsed ); + } +} +---- + +When tokens are consumed, an offset is computed based on token offset and +stream stride. +The resulting offset is required to be aligned. +The alignment for a specific token is equal to the scalar alignment of the +data type as defined in <>, or +sname:VkPhysicalDeviceDeviceGeneratedCommandsPropertiesNV::pname:minIndirectCommandsBufferOffsetAlignment, +whichever is lower. + +[NOTE] +==== +A pname:minIndirectCommandsBufferOffsetAlignment of 4 allows +basetype:VkDeviceAddress to be packed as code:uvec2 with scalar layout +instead of code:uint64_t with 8 byte alignment. +This enables direct compatibility with D3D12 command signature layouts. +==== + +.Valid Usage +**** + * [[VUID-VkIndirectCommandsLayoutCreateInfoNV-pipelineBindPoint-02930]] + The pname:pipelineBindPoint must: be + ename:VK_PIPELINE_BIND_POINT_GRAPHICS +ifdef::VK_NV_device_generated_commands_compute[] + or ename:VK_PIPELINE_BIND_POINT_COMPUTE +endif::VK_NV_device_generated_commands_compute[] + * [[VUID-VkIndirectCommandsLayoutCreateInfoNV-tokenCount-02931]] + pname:tokenCount must: be greater than `0` and less than or equal to + sname:VkPhysicalDeviceDeviceGeneratedCommandsPropertiesNV::pname:maxIndirectCommandsTokenCount + * [[VUID-VkIndirectCommandsLayoutCreateInfoNV-pTokens-02932]] + If pname:pTokens contains an entry of + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_SHADER_GROUP_NV it must: be the + first element of the array and there must: be only a single element of + such token type +ifdef::VK_NV_device_generated_commands_compute[] + * [[VUID-VkIndirectCommandsLayoutCreateInfoNV-pTokens-09585]] + If pname:pTokens contains an entry of + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_PIPELINE_NV it must: be the first + element of the array and there must: be only a single element of such + token type +endif::VK_NV_device_generated_commands_compute[] + * [[VUID-VkIndirectCommandsLayoutCreateInfoNV-pTokens-02933]] + If pname:pTokens contains an entry of + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_STATE_FLAGS_NV there must: be only + a single element of such token type + * [[VUID-VkIndirectCommandsLayoutCreateInfoNV-pTokens-02934]] + All state tokens in pname:pTokens must: occur before any action command + tokens (ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_NV, + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_INDEXED_NV, + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_TASKS_NV, + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_NV +ifdef::VK_NV_device_generated_commands_compute[] + , ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_DISPATCH_NV +endif::VK_NV_device_generated_commands_compute[] + ) + * [[VUID-VkIndirectCommandsLayoutCreateInfoNV-pTokens-02935]] + The content of pname:pTokens must: include one single action command + token that is compatible with the pname:pipelineBindPoint + * [[VUID-VkIndirectCommandsLayoutCreateInfoNV-streamCount-02936]] + pname:streamCount must: be greater than `0` and less or equal to + sname:VkPhysicalDeviceDeviceGeneratedCommandsPropertiesNV::pname:maxIndirectCommandsStreamCount + * [[VUID-VkIndirectCommandsLayoutCreateInfoNV-pStreamStrides-02937]] + each element of pname:pStreamStrides must: be greater than `0` and less + than or equal to + sname:VkPhysicalDeviceDeviceGeneratedCommandsPropertiesNV::pname:maxIndirectCommandsStreamStride. + Furthermore the alignment of each token input must: be ensured +ifdef::VK_NV_device_generated_commands_compute[] + * [[VUID-VkIndirectCommandsLayoutCreateInfoNV-pipelineBindPoint-09088]] + If pname:pipelineBindPoint is ename:VK_PIPELINE_BIND_POINT_COMPUTE then + the <> + feature must: be enabled + * [[VUID-VkIndirectCommandsLayoutCreateInfoNV-pipelineBindPoint-09089]] + If pname:pipelineBindPoint is ename:VK_PIPELINE_BIND_POINT_COMPUTE then + the state tokens in pname:pTokens must: only include + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_DISPATCH_NV, + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_PIPELINE_NV, or + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_CONSTANT_NV + * [[VUID-VkIndirectCommandsLayoutCreateInfoNV-pipelineBindPoint-09090]] + If pname:pipelineBindPoint is ename:VK_PIPELINE_BIND_POINT_COMPUTE and + pname:pTokens includes + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_PIPELINE_NV, then the + <> + feature must: be enabled +endif::VK_NV_device_generated_commands_compute[] +**** + +include::{generated}/validity/structs/VkIndirectCommandsLayoutCreateInfoNV.adoc[] +-- + +[open,refpage='VkIndirectCommandsLayoutUsageFlagBitsNV',desc='Bitmask specifying allowed usage of an indirect commands layout',type='enums'] +-- +Bits which can: be set in +slink:VkIndirectCommandsLayoutCreateInfoNV::pname:flags, specifying usage +hints of an indirect command layout, are: + +include::{generated}/api/enums/VkIndirectCommandsLayoutUsageFlagBitsNV.adoc[] + + * ename:VK_INDIRECT_COMMANDS_LAYOUT_USAGE_EXPLICIT_PREPROCESS_BIT_NV + specifies that the layout is always used with the manual preprocessing + step through calling flink:vkCmdPreprocessGeneratedCommandsNV and + executed by flink:vkCmdExecuteGeneratedCommandsNV with `isPreprocessed` + set to ename:VK_TRUE. + * ename:VK_INDIRECT_COMMANDS_LAYOUT_USAGE_INDEXED_SEQUENCES_BIT_NV + specifies that the input data for the sequences is not implicitly + indexed from 0..sequencesUsed, but an application-provided + sname:VkBuffer encoding the index is provided. + * ename:VK_INDIRECT_COMMANDS_LAYOUT_USAGE_UNORDERED_SEQUENCES_BIT_NV + specifies that the processing of sequences can: happen at an + implementation-dependent order, which is not guaranteed to be coherent + using the same input data. +ifdef::VK_NV_device_generated_commands_compute[] + This flag is ignored when the pname:pipelineBindPoint is + ename:VK_PIPELINE_BIND_POINT_COMPUTE as it is implied that the dispatch + sequence is always unordered. +endif::VK_NV_device_generated_commands_compute[] +-- + +[open,refpage='VkIndirectCommandsLayoutUsageFlagsNV',desc='Bitmask of VkIndirectCommandsLayoutUsageFlagBitsNV',type='flags'] +-- +include::{generated}/api/flags/VkIndirectCommandsLayoutUsageFlagsNV.adoc[] + +tname:VkIndirectCommandsLayoutUsageFlagsNV is a bitmask type for setting a +mask of zero or more elink:VkIndirectCommandsLayoutUsageFlagBitsNV. +-- + +[open,refpage='vkDestroyIndirectCommandsLayoutNV',desc='Destroy an indirect commands layout',type='protos'] +-- +Indirect command layouts for `apiext:VK_NV_device_generated_commands` are +destroyed by: + +include::{generated}/api/protos/vkDestroyIndirectCommandsLayoutNV.adoc[] + + * pname:device is the logical device that destroys the layout. + * pname:indirectCommandsLayout is the layout to destroy. + * pname:pAllocator controls host memory allocation as described in the + <> chapter. + +.Valid Usage +**** + * [[VUID-vkDestroyIndirectCommandsLayoutNV-indirectCommandsLayout-02938]] + All submitted commands that refer to pname:indirectCommandsLayout must: + have completed execution +ifndef::VKSC_VERSION_1_0[] + * [[VUID-vkDestroyIndirectCommandsLayoutNV-indirectCommandsLayout-02939]] + If sname:VkAllocationCallbacks were provided when + pname:indirectCommandsLayout was created, a compatible set of callbacks + must: be provided here + * [[VUID-vkDestroyIndirectCommandsLayoutNV-indirectCommandsLayout-02940]] + If no sname:VkAllocationCallbacks were provided when + pname:indirectCommandsLayout was created, pname:pAllocator must: be + `NULL` +endif::VKSC_VERSION_1_0[] + * [[VUID-vkDestroyIndirectCommandsLayoutNV-deviceGeneratedCommands-02941]] + The <> + feature must: be enabled +**** + +include::{generated}/validity/protos/vkDestroyIndirectCommandsLayoutNV.adoc[] +-- +endif::VK_NV_device_generated_commands[] + +=== Token Input Streams + +ifdef::VK_EXT_device_generated_commands[] +For `apiext:VK_EXT_device_generated_commands`, the input streams can: +contain raw `uint32_t` values, existing indirect commands such as: + + * slink:VkDrawIndirectCommand + * slink:VkDrawIndexedIndirectCommand + * slink:VkDispatchIndirectCommand +ifdef::VK_NV_mesh_shader[] + * slink:VkDrawMeshTasksIndirectCommandNV +endif::VK_NV_mesh_shader[] +ifdef::VK_EXT_mesh_shader[] + * slink:VkDrawMeshTasksIndirectCommandEXT +endif::VK_EXT_mesh_shader[] +ifdef::VK_KHR_ray_tracing_pipeline[] + * slink:VkTraceRaysIndirectCommandKHR +endif::VK_KHR_ray_tracing_pipeline[] +ifdef::VK_KHR_ray_tracing_maintenance1[] + * slink:VkTraceRaysIndirectCommand2KHR +endif::VK_KHR_ray_tracing_maintenance1[] + +or additional commands as listed below. +How the data is used is described in the next section. + +[open,refpage='VkBindIndexBufferIndirectCommandEXT',desc='Structure specifying input data for a single index buffer command token',type='structs'] +-- +The sname:VkBindIndexBufferIndirectCommandEXT structure specifies the input +data for the ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_INDEX_BUFFER_EXT token. + +include::{generated}/api/structs/VkBindIndexBufferIndirectCommandEXT.adoc[] + + * pname:bufferAddress specifies a physical address of the slink:VkBuffer + used as index buffer. + * pname:size is the byte size range which is available for this operation + from the provided address. + * pname:indexType is a elink:VkIndexType value specifying how indices are + treated. + +.Valid Usage +**** + * [[VUID-VkBindIndexBufferIndirectCommandEXT-None-11117]] + The buffer's usage flags from which the address was acquired must: have + the ename:VK_BUFFER_USAGE_INDEX_BUFFER_BIT bit set + * [[VUID-VkBindIndexBufferIndirectCommandEXT-bufferAddress-11118]] + The pname:bufferAddress must: be aligned to the elink:VkIndexType of the + pname:indexType used + * [[VUID-VkBindIndexBufferIndirectCommandEXT-None-11119]] + Each element of the buffer from which the address was acquired and that + is non-sparse must: be bound completely and contiguously to a single + sname:VkDeviceMemory object +**** + +include::{generated}/validity/structs/VkBindIndexBufferIndirectCommandEXT.adoc[] +-- + +[open,refpage='VkBindVertexBufferIndirectCommandEXT',desc='Structure specifying input data for a single vertex buffer command token',type='structs'] +-- +The sname:VkBindVertexBufferIndirectCommandEXT structure specifies the input +data for the ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_VERTEX_BUFFER_EXT token. + +include::{generated}/api/structs/VkBindVertexBufferIndirectCommandEXT.adoc[] + + * pname:bufferAddress specifies a physical address of the slink:VkBuffer + used as vertex input binding. + * pname:size is the byte size range which is available for this operation + from the provided address. + * pname:stride is the byte size stride for this vertex input binding as in + sname:VkVertexInputBindingDescription::pname:stride. + +.Valid Usage +**** + * [[VUID-VkBindVertexBufferIndirectCommandEXT-None-11120]] + The buffer's usage flag from which the address was acquired must: have + the ename:VK_BUFFER_USAGE_VERTEX_BUFFER_BIT bit set + * [[VUID-VkBindVertexBufferIndirectCommandEXT-None-11121]] + Each element of the buffer from which the address was acquired and that + is non-sparse must: be bound completely and contiguously to a single + sname:VkDeviceMemory object +**** + +include::{generated}/validity/structs/VkBindVertexBufferIndirectCommandEXT.adoc[] +-- + +[open,refpage='VkDrawIndirectCountIndirectCommandEXT',desc='Structure specifying input data for a single draw-type command token',type='structs'] +-- +The sname:VkDrawIndirectCountIndirectCommandEXT structure specifies the +input data for all draw-type tokens. + +include::{generated}/api/structs/VkDrawIndirectCountIndirectCommandEXT.adoc[] + + * pname:bufferAddress specifies a physical address of the slink:VkBuffer + used for draw commands. + * pname:stride is the byte size stride for the command arguments + * pname:commandCount is the number of commands to execute + +The corresponding indirect draw struct data will be read from the buffer +address. + +.Valid Usage +**** + * [[VUID-VkDrawIndirectCountIndirectCommandEXT-None-11122]] + The buffer's usage flag from which the address was acquired must: have + the ename:VK_BUFFER_USAGE_INDIRECT_BUFFER_BIT bit set + * [[VUID-VkDrawIndirectCountIndirectCommandEXT-None-11123]] + Each element of the buffer from which the address was acquired and that + is non-sparse must: be bound completely and contiguously to a single + sname:VkDeviceMemory object +**** + +include::{generated}/validity/structs/VkDrawIndirectCountIndirectCommandEXT.adoc[] +-- + +endif::VK_EXT_device_generated_commands[] +ifdef::VK_NV_device_generated_commands[] + +[open,refpage='VkIndirectCommandsStreamNV',desc='Structure specifying input streams for generated command tokens',type='structs'] +-- +The sname:VkIndirectCommandsStreamNV structure specifies the input data for +one or more tokens at processing time. + +include::{generated}/api/structs/VkIndirectCommandsStreamNV.adoc[] + + * pname:buffer specifies the slink:VkBuffer storing the functional + arguments for each sequence. + These arguments can: be written by the device. + * pname:offset specified an offset into pname:buffer where the arguments + start. + +.Valid Usage +**** + * [[VUID-VkIndirectCommandsStreamNV-buffer-02942]] + The pname:buffer's usage flag must: have the + ename:VK_BUFFER_USAGE_INDIRECT_BUFFER_BIT bit set + * [[VUID-VkIndirectCommandsStreamNV-offset-02943]] + The pname:offset must: be aligned to + sname:VkPhysicalDeviceDeviceGeneratedCommandsPropertiesNV::pname:minIndirectCommandsBufferOffsetAlignment + * [[VUID-VkIndirectCommandsStreamNV-buffer-02975]] + If pname:buffer is non-sparse then it must: be bound completely and + contiguously to a single sname:VkDeviceMemory object +**** + +include::{generated}/validity/structs/VkIndirectCommandsStreamNV.adoc[] +-- + +For `apiext:VK_NV_device_generated_commands`, the input streams can: contain +raw `uint32_t` values, existing indirect commands such as: + + * slink:VkDrawIndirectCommand + * slink:VkDrawIndexedIndirectCommand +ifdef::VK_NV_mesh_shader[] + * slink:VkDrawMeshTasksIndirectCommandNV +endif::VK_NV_mesh_shader[] +ifdef::VK_EXT_mesh_shader[] + * slink:VkDrawMeshTasksIndirectCommandEXT +endif::VK_EXT_mesh_shader[] +ifdef::VK_NV_device_generated_commands_compute[] + * slink:VkDispatchIndirectCommand +endif::VK_NV_device_generated_commands_compute[] + +or additional commands as listed below. +How the data is used is described in the next section. + +[open,refpage='VkBindShaderGroupIndirectCommandNV',desc='Structure specifying input data for a single shader group command token',type='structs'] +-- +The sname:VkBindShaderGroupIndirectCommandNV structure specifies the input +data for the ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_SHADER_GROUP_NV token. + +include::{generated}/api/structs/VkBindShaderGroupIndirectCommandNV.adoc[] + + * pname:groupIndex specifies which shader group of the current bound + graphics pipeline is used. + +.Valid Usage +**** + * [[VUID-VkBindShaderGroupIndirectCommandNV-None-02944]] + The current bound graphics pipeline, as well as the pipelines it may + reference, must: have been created with + ename:VK_PIPELINE_CREATE_INDIRECT_BINDABLE_BIT_NV + * [[VUID-VkBindShaderGroupIndirectCommandNV-index-02945]] + The pname:index must: be within range of the accessible shader groups of + the current bound graphics pipeline. + See flink:vkCmdBindPipelineShaderGroupNV for further details +**** + +include::{generated}/validity/structs/VkBindShaderGroupIndirectCommandNV.adoc[] +-- + +[open,refpage='VkBindIndexBufferIndirectCommandNV',desc='Structure specifying input data for a single index buffer command token',type='structs'] +-- +The sname:VkBindIndexBufferIndirectCommandNV structure specifies the input +data for the ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_INDEX_BUFFER_NV token. + +include::{generated}/api/structs/VkBindIndexBufferIndirectCommandNV.adoc[] + + * pname:bufferAddress specifies a physical address of the slink:VkBuffer + used as index buffer. + * pname:size is the byte size range which is available for this operation + from the provided address. + * pname:indexType is a elink:VkIndexType value specifying how indices are + treated. + Instead of the Vulkan enum values, a custom `uint32_t` value can: be + mapped to elink:VkIndexType by specifying the + sname:VkIndirectCommandsLayoutTokenNV::pname:pIndexTypes and + sname:VkIndirectCommandsLayoutTokenNV::pname:pIndexTypeValues arrays. + +.Valid Usage +**** + * [[VUID-VkBindIndexBufferIndirectCommandNV-None-02946]] + The buffer's usage flag from which the address was acquired must: have + the ename:VK_BUFFER_USAGE_INDEX_BUFFER_BIT bit set + * [[VUID-VkBindIndexBufferIndirectCommandNV-bufferAddress-02947]] + The pname:bufferAddress must: be aligned to the pname:indexType used + * [[VUID-VkBindIndexBufferIndirectCommandNV-None-02948]] + Each element of the buffer from which the address was acquired and that + is non-sparse must: be bound completely and contiguously to a single + sname:VkDeviceMemory object +**** + +include::{generated}/validity/structs/VkBindIndexBufferIndirectCommandNV.adoc[] +-- + +[open,refpage='VkBindVertexBufferIndirectCommandNV',desc='Structure specifying input data for a single vertex buffer command token',type='structs'] +-- +The sname:VkBindVertexBufferIndirectCommandNV structure specifies the input +data for the ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_VERTEX_BUFFER_NV token. + +include::{generated}/api/structs/VkBindVertexBufferIndirectCommandNV.adoc[] + + * pname:bufferAddress specifies a physical address of the slink:VkBuffer + used as vertex input binding. + * pname:size is the byte size range which is available for this operation + from the provided address. + * pname:stride is the byte size stride for this vertex input binding as in + sname:VkVertexInputBindingDescription::pname:stride. + It is only used if + sname:VkIndirectCommandsLayoutTokenNV::pname:vertexDynamicStride was + set, otherwise the stride is inherited from the current bound graphics + pipeline. + +.Valid Usage +**** + * [[VUID-VkBindVertexBufferIndirectCommandNV-None-02949]] + The buffer's usage flag from which the address was acquired must: have + the ename:VK_BUFFER_USAGE_VERTEX_BUFFER_BIT bit set + * [[VUID-VkBindVertexBufferIndirectCommandNV-None-02950]] + Each element of the buffer from which the address was acquired and that + is non-sparse must: be bound completely and contiguously to a single + sname:VkDeviceMemory object +**** + +include::{generated}/validity/structs/VkBindVertexBufferIndirectCommandNV.adoc[] +-- + +[open,refpage='VkSetStateFlagsIndirectCommandNV',desc='Structure specifying input data for a single state flag command token',type='structs'] +-- +The sname:VkSetStateFlagsIndirectCommandNV structure specifies the input +data for the ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_STATE_FLAGS_NV token. +Which state is changed depends on the elink:VkIndirectStateFlagBitsNV +specified at sname:VkIndirectCommandsLayoutNV creation time. + +include::{generated}/api/structs/VkSetStateFlagsIndirectCommandNV.adoc[] + + * pname:data encodes packed state that this command alters. + ** Bit `0`: If set represents ename:VK_FRONT_FACE_CLOCKWISE, otherwise + ename:VK_FRONT_FACE_COUNTER_CLOCKWISE + +include::{generated}/validity/structs/VkSetStateFlagsIndirectCommandNV.adoc[] +-- + +[open,refpage='VkIndirectStateFlagBitsNV',desc='Bitmask specifying state that can be altered on the device',type='enums'] +-- +A subset of the graphics pipeline state can: be altered using indirect state +flags: + +include::{generated}/api/enums/VkIndirectStateFlagBitsNV.adoc[] + + * ename:VK_INDIRECT_STATE_FLAG_FRONTFACE_BIT_NV allows to toggle the + elink:VkFrontFace rasterization state for subsequent drawing commands. +-- + +[open,refpage='VkIndirectStateFlagsNV',desc='Bitmask of VkIndirectStateFlagBitsNV',type='flags'] +-- +include::{generated}/api/flags/VkIndirectStateFlagsNV.adoc[] + +tname:VkIndirectStateFlagsNV is a bitmask type for setting a mask of zero or +more elink:VkIndirectStateFlagBitsNV. +-- + +[open,refpage='VkBindPipelineIndirectCommandNV',desc='Structure specifying input data for the compute pipeline dispatch token',type='structs'] +-- +The sname:VkBindPipelineIndirectCommandNV structure specifies the input data +for the ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_PIPELINE_NV token. + +include::{generated}/api/structs/VkBindPipelineIndirectCommandNV.adoc[] + + * pname:pipelineAddress specifies the pipeline address of the compute + pipeline that will be used in device generated rendering. + +.Valid Usage +**** + * [[VUID-VkBindPipelineIndirectCommandNV-deviceGeneratedComputePipelines-09091]] + The <> + feature must: be enabled + * [[VUID-VkBindPipelineIndirectCommandNV-None-09092]] + The referenced pipeline must: have been created with + ename:VK_PIPELINE_CREATE_INDIRECT_BINDABLE_BIT_NV + * [[VUID-VkBindPipelineIndirectCommandNV-None-09093]] + The referenced pipeline must: have been updated with + flink:vkCmdUpdatePipelineIndirectBufferNV + * [[VUID-VkBindPipelineIndirectCommandNV-None-09094]] + The referenced pipeline's address must: have been queried with + flink:vkGetPipelineIndirectDeviceAddressNV +**** + +include::{generated}/validity/structs/VkBindPipelineIndirectCommandNV.adoc[] +-- +endif::VK_NV_device_generated_commands[] + + +=== Tokenized Command Processing + +ifdef::VK_EXT_device_generated_commands[] +The processing for `apiext:VK_EXT_device_generated_commands` is in principle +illustrated below: + +[source,c] +---- +void cmdProcessSequence(cmd, indirectExecutionSet, indirectCommandsLayout, indirectAddress, s) +{ + for (t = 0; t < indirectCommandsLayout.tokenCount; t++) + { + uint32_t offset = indirectCommandsLayout.pTokens[t].offset; + uint32_t stride = indirectCommandsLayout.indirectStride; + VkDeviceAddress streamData = indirectAddress; + const void* input = streamData + stride * s + offset; + + // further details later + indirectCommandsLayout.pTokens[t].command (cmd, indirectExecutionSet, input, s); + } +} + +void cmdProcessAllSequences(cmd, indirectExecutionSet, indirectCommandsLayout, indirectAddress, sequencesCount) +{ + for (s = 0; s < sequencesCount; s++) + { + sUsed = s; + + if (indirectCommandsLayout.flags & VK_INDIRECT_COMMANDS_LAYOUT_USAGE_UNORDERED_SEQUENCES_BIT_EXT) { + sUsed = incoherent_implementation_dependent_permutation[ sUsed ]; + } + + cmdProcessSequence( cmd, indirectExecutionSet, indirectCommandsLayout, indirectAddress, sUsed ); + } +} +---- + +The processing of each sequence is considered stateless, therefore all state +changes must: occur prior to action commands within the sequence. +A single sequence is strictly targeting the tlink:VkShaderStageFlags it was +created with. + +The primary input data for each token is provided through sname:VkBuffer +content at preprocessing using flink:vkCmdPreprocessGeneratedCommandsEXT or +execution time using flink:vkCmdExecuteGeneratedCommandsEXT, however some +functional arguments, for example push constant layouts, are specified at +layout creation time. +The input size is different for each token. + +[open,refpage='VkIndirectCommandsTokenTypeEXT',desc='Enum specifying token commands',type='enums'] +-- +Possible values of those elements of the +slink:VkIndirectCommandsLayoutCreateInfoEXT::pname:pTokens array specifying +command tokens (other elements of the array specify command parameters) are: + +include::{generated}/api/enums/VkIndirectCommandsTokenTypeEXT.adoc[] + +[[indirectmdslayout-command-tokens-ext]] +.Supported Indirect Command Tokens +[width="80%",cols="67%,33%",options="header",align="center"] +|=== +|*Common Tokens* | *Command Data* +ifdef::VK_EXT_shader_object[] +|ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_EXECUTION_SET_EXT | `u32[]` array of indices into the indirect execution set +endif::VK_EXT_shader_object[] +ifndef::VK_EXT_shader_object[] +|ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_EXECUTION_SET_EXT | `u32` index into the indirect execution set +endif::VK_EXT_shader_object[] +|ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_CONSTANT_EXT | `u32[]` raw data +|ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_SEQUENCE_INDEX_EXT | `u32` placeholder data (not accessed by shader) +|*Compute Tokens*| +|ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_DISPATCH_EXT | slink:VkDispatchIndirectCommand +ifdef::VK_KHR_ray_tracing_maintenance1[] +|*Ray Tracing Tokens*| +|ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_TRACE_RAYS2_EXT | slink:VkTraceRaysIndirectCommand2KHR +endif::VK_KHR_ray_tracing_maintenance1[] +|*Graphics State Tokens*| +|ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_INDEX_BUFFER_EXT | slink:VkBindIndexBufferIndirectCommandEXT +|ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_VERTEX_BUFFER_EXT | slink:VkBindVertexBufferIndirectCommandEXT +|*Graphics Draw Tokens*| +|ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_INDEXED_EXT | slink:VkDrawIndexedIndirectCommand +|ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_EXT | slink:VkDrawIndirectCommand +ifdef::VK_EXT_mesh_shader[] +|ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_EXT | slink:VkDrawMeshTasksIndirectCommandEXT +endif::VK_EXT_mesh_shader[] +ifdef::VK_NV_mesh_shader[] +|ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_NV_EXT | slink:VkDrawMeshTasksIndirectCommandNV +endif::VK_NV_mesh_shader[] +|*Graphics Draw Count Tokens*| +|ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_INDEXED_COUNT_EXT | slink:VkDrawIndirectCountIndirectCommandEXT with VkDrawIndexedIndirectCommand +|ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_COUNT_EXT | slink:VkDrawIndirectCountIndirectCommandEXT with VkDrawIndirectCommand +ifdef::VK_EXT_mesh_shader[] +|ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_COUNT_EXT | slink:VkDrawIndirectCountIndirectCommandEXT with VkDrawMeshTasksIndirectCommandEXT +endif::VK_EXT_mesh_shader[] +ifdef::VK_NV_mesh_shader[] +|ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_COUNT_NV_EXT | slink:VkDrawIndirectCountIndirectCommandEXT with VkDrawMeshTasksIndirectCommandNV +endif::VK_NV_mesh_shader[] +|=== + +-- + +[open,refpage='VkIndirectCommandsLayoutTokenEXT',desc='Struct specifying the details of an indirect command layout token',type='structs'] +-- +The sname:VkIndirectCommandsLayoutTokenEXT structure specifies details to +the function arguments that need to be known at layout creation time: + +include::{generated}/api/structs/VkIndirectCommandsLayoutTokenEXT.adoc[] + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * pname:type specifies the elink:VkIndirectCommandsTokenTypeEXT for + pname:data. + * pname:data specifies a slink:VkIndirectCommandsTokenDataEXT containing + token-specific details for command execution. + It is ignored if pname:type does not match any member of the + slink:VkIndirectCommandsTokenDataEXT union. + * pname:offset is the relative byte offset for the token within one + sequence of the indirect buffer. + The data stored at that offset is the command data for the token, e.g. + sname:VkDispatchIndirectCommand. + +.Valid Usage +**** + * [[VUID-VkIndirectCommandsLayoutTokenEXT-offset-11124]] + pname:offset must: be less than or equal to + slink:VkPhysicalDeviceDeviceGeneratedCommandsPropertiesEXT::pname:maxIndirectCommandsTokenOffset + * [[VUID-VkIndirectCommandsLayoutTokenEXT-offset-11125]] + pname:offset must: be aligned to `4` +ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] + * [[VUID-VkIndirectCommandsLayoutTokenEXT-meshShader-11126]] + If <> or <> are not enabled, pname:type must: not be + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_EXT + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_COUNT_EXT, + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_NV_EXT or + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_COUNT_NV_EXT +endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] +ifdef::VK_KHR_ray_tracing_maintenance1[] + * [[VUID-VkIndirectCommandsLayoutTokenEXT-rayTracingMaintenance1-11128]] + If <> is + not enabled, pname:type must: not be + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_TRACE_RAYS2_EXT +endif::VK_KHR_ray_tracing_maintenance1[] + * [[VUID-VkIndirectCommandsLayoutTokenEXT-deviceGeneratedCommandsMultiDrawIndirectCount-11129]] + If <> + is not supported, pname:type must: not be + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_INDEXED_COUNT_EXT or + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_COUNT_EXT +ifdef::VK_EXT_mesh_shader[] + * [[VUID-VkIndirectCommandsLayoutTokenEXT-deviceGeneratedCommandsMultiDrawIndirectCount-11130]] + If <> + is not supported, pname:type must: not be + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_COUNT_EXT +endif::VK_EXT_mesh_shader[] +ifdef::VK_NV_mesh_shader[] + * [[VUID-VkIndirectCommandsLayoutTokenEXT-deviceGeneratedCommandsMultiDrawIndirectCount-11131]] + If <> + is not supported, pname:type must: not be + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_COUNT_NV_EXT +endif::VK_NV_mesh_shader[] +**** + +include::{generated}/validity/structs/VkIndirectCommandsLayoutTokenEXT.adoc[] +-- + +[open,refpage='VkIndirectCommandsTokenDataEXT',desc='Union specifying the token-specific details of an indirect command layout token',type='structs'] +-- +The sname:VkIndirectCommandsTokenDataEXT structure provides token-specific +details used to generate the indirect execution layout. + +include::{generated}/api/structs/VkIndirectCommandsTokenDataEXT.adoc[] + + * pname:pPushConstant is a pointer to a + slink:VkIndirectCommandsPushConstantTokenEXT struct needed for + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_CONSTANT_EXT and + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_SEQUENCE_INDEX_EXT tokens + * pname:pVertexBuffer is a pointer to a + slink:VkIndirectCommandsVertexBufferTokenEXT struct needed for + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_VERTEX_BUFFER_EXT tokens + * pname:pIndexBuffer is a pointer to a + slink:VkIndirectCommandsIndexBufferTokenEXT struct needed for + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_INDEX_BUFFER_EXT tokens + * pname:pExecutionSet is a pointer to a + slink:VkIndirectCommandsExecutionSetTokenEXT struct needed for + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_EXECUTION_SET_EXT tokens + +The appropriate member of the union must: be set for each token. + +The following code provides detailed information on how an individual +sequence is processed. +For valid usage, all restrictions from the regular commands apply. + +include::{generated}/validity/structs/VkIndirectCommandsTokenDataEXT.adoc[] +-- + +[source,c] +---- + +void cmdProcessSequence(cmd, indirectExecutionSet, indirectCommandsLayout, indirectAddress, s) +{ + for (uint32_t t = 0; t < indirectCommandsLayout.tokenCount; t++) { + VkIndirectCommandsLayoutTokenEXT *token = &indirectCommandsLayout.pTokens[t]; + + uint32_t offset = token->offset; + uint32_t stride = indirectCommandsLayout.indirectStride; + VkDeviceAddress streamData = indirectAddress; + const void* input = streamData + stride * s + offset; + + switch (token->tokenType) { + case VK_INDIRECT_COMMANDS_TOKEN_TYPE_EXECUTION_SET_EXT: + uint32_t *bind = input; + VkIndirectCommandsExecutionSetTokenEXT *info = token->data.pExecutionSet; + + if (info->type == VK_INDIRECT_EXECUTION_SET_INFO_TYPE_PIPELINES_EXT) { + vkCmdBindPipeline(cmd, indirectExecutionSet.pipelineBindPoint, indirectExecutionSet.pipelines[*bind]); + } else { + VkShaderStageFlagBits stages[]; + VkShaderEXT shaders[]; + uint32_t i = 0; + IterateBitmaskLSBToMSB(iter, info->shaderStages) { + stages[i] = iter; + shaders[i] = indirectExecutionSet.shaders[bind[i]].shaderObject; + i++; + } + vkCmdBindShadersEXT(cmd, i, stages, shaders); + } + break; + + case VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_CONSTANT_EXT: + uint32_t* data = input; + VkPushConstantsInfoKHR info = { + VK_STRUCTURE_TYPE_PUSH_CONSTANTS_INFO_KHR, + // this can also use `dynamicGeneratedPipelineLayout' to pass a VkPipelineLayoutCreateInfo from pNext + indirectCommandsLayout.pipelineLayout, + token->token.pushConstant.updateRange.shaderStages, + token->token.pushConstant.updateRange.offset, + token->token.pushConstant.updateRange.size, + data + }; + + vkCmdPushConstants2KHR(cmd, &info); + break; + + case VK_INDIRECT_COMMANDS_TOKEN_TYPE_SEQUENCE_INDEX_EXT: + VkPushConstantsInfoKHR info = { + VK_STRUCTURE_TYPE_PUSH_CONSTANTS_INFO_KHR, + // this can also use `dynamicGeneratedPipelineLayout' to pass a VkPipelineLayoutCreateInfo from pNext + indirectCommandsLayout.pipelineLayout, + token->token.pushConstant.updateRange.shaderStages, + token->token.pushConstant.updateRange.offset, + // this must be 4 + token->token.pushConstant.updateRange.size, + // this just updates the sequence index + &s + }; + + vkCmdPushConstants2KHR(cmd, &info); + break; + + case VK_INDIRECT_COMMANDS_TOKEN_TYPE_INDEX_BUFFER_EXT: + VkBindIndexBufferIndirectCommandEXT* data = input; + + vkCmdBindIndexBuffer(cmd, deriveBuffer(data->bufferAddress), deriveOffset(data->bufferAddress), data->indexType); + break; + + case VK_INDIRECT_COMMANDS_TOKEN_TYPE_VERTEX_BUFFER_EXT: + VkBindVertexBufferIndirectCommandEXT* data = input; + + vkCmdBindVertexBuffers2(cmd, token->token.vertexBuffer->vertexBindingUnit, 1, &deriveBuffer(data->bufferAddress), + &deriveOffset(data->bufferAddress), data->size, data->stride); + break; + + case VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_INDEXED_EXT: + VkDrawIndexedIndirectCommand *data = input; + + vkCmdDrawIndexed(cmd, data->indexCount, data->instanceCount, data->firstIndex, data->vertexOffset, data->firstInstance); + break; + case VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_INDEXED_COUNT_EXT: + VkDrawIndirectCountIndirectCommandEXT* data = input; + + vkCmdDrawIndexedIndirect(cmd, deriveBuffer(data->bufferAddress), deriveoffset(data->bufferAddress), min(data->commandCount, indirectCommandsLayout.maxDrawCount), data->stride); + break; + + case VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_EXT: + VkDrawIndirectCommand* data = input; + + vkCmdDraw(cmd, data->vertex_count, data->instanceCount, data->firstVertex, data->firstIndex); + break; + + case VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_COUNT_EXT: + VkDrawIndirectCountIndirectCommandEXT* data = input; + + vkCmdDrawIndirect(cmd, deriveBuffer(data->bufferAddress), deriveoffset(data->bufferAddress), min(data->commandCount, indirectCommandsLayout.maxDrawCount), data->stride); + break; + + // only available if VK_NV_mesh_shader is enabled + case VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_NV_EXT: + VkDrawMeshTasksIndirectCommandNV *data = input; + + vkCmdDrawMeshTasksNV(cmd, data->taskCount, data->firstTask); + break; + + // only available if VK_NV_mesh_shader is enabled + case VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_COUNT_NV_EXT: + VkDrawIndirectCountIndirectCommandEXT* data = input; + + vkCmdDrawMeshTasksIndirectCountNV(cmd, deriveBuffer(data->bufferAddress), deriveoffset(data->bufferAddress), min(data->commandCount, indirectCommandsLayout.maxDrawCount), data->stride); + break; + + // only available if VK_EXT_mesh_shader is enabled + case VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_EXT: + VkDrawMeshTasksIndirectCommandEXT *data = input; + + vkCmdDrawMeshTasksEXT(cmd, data->groupCountX, data->groupCountY, data->groupCountZ); + break; + + // only available if VK_EXT_mesh_shader is enabled + case VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_COUNT_EXT: + VkDrawIndirectCountIndirectCommandEXT* data = input; + + vkCmdDrawMeshTasksIndirectCountEXT(cmd, deriveBuffer(data->bufferAddress), deriveoffset(data->bufferAddress), min(data->commandCount, indirectCommandsLayout.maxDrawCount), data->stride); + break; + + case VK_INDIRECT_COMMANDS_TOKEN_TYPE_DISPATCH_EXT: + VkDispatchIndirectCommand *data = input; + + vkCmdDispatch(cmd, data->x, data->y, data->z); + break; + + // only available if VK_KHR_ray_tracing_maintenance1 is enabled + case VK_INDIRECT_COMMANDS_TOKEN_TYPE_TRACE_RAYS2_EXT: + vkCmdTraceRaysIndirect2KHR(cmd, deriveBuffer(input)); + break; + } + } +} +---- +endif::VK_EXT_device_generated_commands[] + +ifdef::VK_NV_device_generated_commands[] +The processing for `apiext:VK_NV_device_generated_commands` is in principle +illustrated below: + +[source,c] +---- +void cmdProcessSequence(cmd, pipeline, indirectCommandsLayout, pIndirectCommandsStreams, s) +{ + for (t = 0; t < indirectCommandsLayout.tokenCount; t++) + { + uint32_t stream = indirectCommandsLayout.pTokens[t].stream; + uint32_t offset = indirectCommandsLayout.pTokens[t].offset; + uint32_t stride = indirectCommandsLayout.pStreamStrides[stream]; + stream = pIndirectCommandsStreams[stream]; + const void* input = stream.buffer.pointer( stream.offset + stride * s + offset ) + + // further details later + indirectCommandsLayout.pTokens[t].command (cmd, pipeline, input, s); + } +} + +void cmdProcessAllSequences(cmd, pipeline, indirectCommandsLayout, pIndirectCommandsStreams, sequencesCount) +{ + for (s = 0; s < sequencesCount; s++) + { + cmdProcessSequence(cmd, pipeline, indirectCommandsLayout, pIndirectCommandsStreams, s); + } +} +---- + +The processing of each sequence is considered stateless, therefore all state +changes must: occur before any action command tokens within the sequence. +A single sequence is strictly targeting the elink:VkPipelineBindPoint it was +created with. + +The primary input data for each token is provided through sname:VkBuffer +content at preprocessing using flink:vkCmdPreprocessGeneratedCommandsNV or +execution time using flink:vkCmdExecuteGeneratedCommandsNV, however some +functional arguments, for example binding sets, are specified at layout +creation time. +The input size is different for each token. +endif::VK_NV_device_generated_commands[] + +ifdef::VK_EXT_device_generated_commands[] +[open,refpage='VkIndirectCommandsPushConstantTokenEXT',desc='Structure specifying layout token info for a single push constant command token',type='structs'] +-- +The sname:VkIndirectCommandsPushConstantTokenEXT structure specifies the +layout token info for +ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_CONSTANT_EXT and +ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_SEQUENCE_INDEX_EXT tokens. + +include::{generated}/api/structs/VkIndirectCommandsPushConstantTokenEXT.adoc[] + + * pname:updateRange is the push constant range that will be updated by the + token. + +The pname:stageFlags member of pname:updateRange is ignored. + +.Valid Usage +**** + * [[VUID-VkIndirectCommandsPushConstantTokenEXT-updateRange-11132]] + pname:updateRange must: be contained within the push constant info used + by slink:VkIndirectCommandsLayoutCreateInfoEXT + * [[VUID-VkIndirectCommandsPushConstantTokenEXT-size-11133]] + If the token type is + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_SEQUENCE_INDEX_EXT, the pname:size + member of pname:updateRange must: be 4 +**** + +include::{generated}/validity/structs/VkIndirectCommandsPushConstantTokenEXT.adoc[] +-- + +[open,refpage='VkIndirectCommandsVertexBufferTokenEXT',desc='Structure specifying layout token info for a single index buffer command token',type='structs'] +-- +The sname:VkIndirectCommandsVertexBufferTokenEXT structure specifies the +layout token info for the +ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_VERTEX_BUFFER_EXT token. + +include::{generated}/api/structs/VkIndirectCommandsVertexBufferTokenEXT.adoc[] + + * pname:vertexBindingUnit is the vertex input binding number to be bound. + +.Valid Usage +**** + * [[VUID-VkIndirectCommandsVertexBufferTokenEXT-vertexBindingUnit-11134]] + pname:vertexBindingUnit must: be less than the total number of vertex + input bindings in use by the current graphics state. +**** + +include::{generated}/validity/structs/VkIndirectCommandsVertexBufferTokenEXT.adoc[] +-- + +[open,refpage='VkIndirectCommandsIndexBufferTokenEXT',desc='Structure specifying layout token info for a single index buffer command token',type='structs'] +-- +The sname:VkIndirectCommandsIndexBufferTokenEXT structure specifies the +layout token info for the +ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_INDEX_BUFFER_EXT token. + +include::{generated}/api/structs/VkIndirectCommandsIndexBufferTokenEXT.adoc[] + + * pname:mode specifies the mode to use with this token. + +This allows for easy layering of Vulkan atop other APIs. +When ename:VK_INDIRECT_COMMANDS_INPUT_MODE_DXGI_INDEX_BUFFER_EXT is +specified, the indirect buffer can contain a `D3D12_INDEX_BUFFER_VIEW` +instead of slink:VkBindIndexBufferIndirectCommandEXT as D3D's DXGI format +value is mapped to the elink:VkIndexType. +It works as both structs are otherwise binary compatible. + +.Valid Usage +**** + * [[VUID-VkIndirectCommandsIndexBufferTokenEXT-mode-11135]] + pname:mode must: be non-zero + * [[VUID-VkIndirectCommandsIndexBufferTokenEXT-mode-11136]] + pname:mode must: be one of the bits supported in + <> +**** + +include::{generated}/validity/structs/VkIndirectCommandsIndexBufferTokenEXT.adoc[] +-- + +[open,refpage='VkIndirectCommandsInputModeFlagBitsEXT',desc='Bitmask specifying allowed usage of an indirect commands layout',type='enums'] +-- +Bits which are set in +slink:VkIndirectCommandsIndexBufferTokenEXT::pname:mode, specifying how an +index buffer is used, are: + +include::{generated}/api/enums/VkIndirectCommandsInputModeFlagBitsEXT.adoc[] + + * ename:VK_INDIRECT_COMMANDS_INPUT_MODE_VULKAN_INDEX_BUFFER_EXT indicates + that the indirect buffer contains + slink:VkBindIndexBufferIndirectCommandEXT. + * ename:VK_INDIRECT_COMMANDS_INPUT_MODE_DXGI_INDEX_BUFFER_EXT indicates + that the indirect buffer contains `D3D12_INDEX_BUFFER_VIEW`. +-- + +[open,refpage='VkIndirectCommandsInputModeFlagsEXT',desc='Bitmask of VkIndirectCommandsInputModeFlagBitsEXT',type='flags'] +-- +include::{generated}/api/flags/VkIndirectCommandsInputModeFlagsEXT.adoc[] + +tname:VkIndirectCommandsInputModeFlagsEXT is a bitmask type for setting a +mask of zero or more elink:VkIndirectCommandsInputModeFlagBitsEXT. +-- + +[open,refpage='VkIndirectCommandsExecutionSetTokenEXT',desc='Structure specifying input data for a single execution set command token',type='structs'] +-- +The sname:VkIndirectCommandsExecutionSetTokenEXT structure specifies the +input data for the ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_EXECUTION_SET_EXT +token. + +include::{generated}/api/structs/VkIndirectCommandsExecutionSetTokenEXT.adoc[] + + * pname:type describes the type of indirect execution set in use. + * pname:shaderStages specifies the shaders that will be changed by this + token. + +.Valid Usage +**** + * [[VUID-VkIndirectCommandsExecutionSetTokenEXT-shaderStages-11137]] + Each bit in pname:shaderStages must: be supported by + <> +ifdef::VK_EXT_shader_object[] + or <> +endif::VK_EXT_shader_object[] +**** + +include::{generated}/validity/structs/VkIndirectCommandsExecutionSetTokenEXT.adoc[] +-- +endif::VK_EXT_device_generated_commands[] + +ifdef::VK_NV_device_generated_commands[] +[open,refpage='VkIndirectCommandsTokenTypeNV',desc='Enum specifying token commands',type='enums'] +-- +Possible values of those elements of the +slink:VkIndirectCommandsLayoutCreateInfoNV::pname:pTokens array specifying +command tokens (other elements of the array specify command parameters) are: + +include::{generated}/api/enums/VkIndirectCommandsTokenTypeNV.adoc[] + +[[indirectmdslayout-command-tokens-nv]] +.Supported Indirect Command Tokens +[width="80%",cols="67%,33%",options="header",align="center"] +|==== +|Token type | Equivalent command +|ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_SHADER_GROUP_NV | flink:vkCmdBindPipelineShaderGroupNV +|ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_STATE_FLAGS_NV | - +|ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_INDEX_BUFFER_NV | flink:vkCmdBindIndexBuffer +|ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_VERTEX_BUFFER_NV | flink:vkCmdBindVertexBuffers +|ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_CONSTANT_NV | flink:vkCmdPushConstants +|ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_INDEXED_NV | flink:vkCmdDrawIndexedIndirect +|ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_NV | flink:vkCmdDrawIndirect +ifdef::VK_NV_mesh_shader[] +|ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_TASKS_NV | flink:vkCmdDrawMeshTasksIndirectNV +endif::VK_NV_mesh_shader[] +ifdef::VK_EXT_mesh_shader[] +|ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_NV | flink:vkCmdDrawMeshTasksIndirectEXT +endif::VK_EXT_mesh_shader[] +ifdef::VK_NV_device_generated_commands_compute[] +|ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_PIPELINE_NV | flink:vkCmdBindPipeline +|ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_DISPATCH_NV | flink:vkCmdDispatchIndirect +endif::VK_NV_device_generated_commands_compute[] +|==== +-- + +[open,refpage='VkIndirectCommandsLayoutTokenNV',desc='Struct specifying the details of an indirect command layout token',type='structs'] +-- +The sname:VkIndirectCommandsLayoutTokenNV structure specifies details to the +function arguments that need to be known at layout creation time: + +include::{generated}/api/structs/VkIndirectCommandsLayoutTokenNV.adoc[] + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * pname:tokenType is a elink:VkIndirectCommandsTokenTypeNV specifying the + token command type. + * pname:stream is the index of the input stream containing the token + argument data. + * pname:offset is a relative starting offset within the input stream + memory for the token argument data. + * pname:vertexBindingUnit is used for the vertex buffer binding command. + * pname:vertexDynamicStride sets if the vertex buffer stride is provided + by the binding command rather than the current bound graphics pipeline + state. + * pname:pushconstantPipelineLayout is the sname:VkPipelineLayout used for + the push constant command. + * pname:pushconstantShaderStageFlags are the shader stage flags used for + the push constant command. + * pname:pushconstantOffset is the offset used for the push constant + command. + * pname:pushconstantSize is the size used for the push constant command. + * pname:indirectStateFlags is a tlink:VkIndirectStateFlagsNV bitfield + indicating the active states for the state flag command. + * pname:indexTypeCount is the optional size of the pname:pIndexTypes and + pname:pIndexTypeValues array pairings. + If not zero, it allows to register a custom `uint32_t` value to be + treated as specific elink:VkIndexType. + * pname:pIndexTypes is the used elink:VkIndexType for the corresponding + `uint32_t` value entry in pname:pIndexTypeValues. + +.Valid Usage +**** + * [[VUID-VkIndirectCommandsLayoutTokenNV-stream-02951]] + pname:stream must: be smaller than + sname:VkIndirectCommandsLayoutCreateInfoNV::pname:streamCount + * [[VUID-VkIndirectCommandsLayoutTokenNV-offset-02952]] + pname:offset must: be less than or equal to + sname:VkPhysicalDeviceDeviceGeneratedCommandsPropertiesNV::pname:maxIndirectCommandsTokenOffset + * [[VUID-VkIndirectCommandsLayoutTokenNV-offset-06888]] + pname:offset must: be aligned to the scalar alignment of pname:tokenType + or pname:minIndirectCommandsBufferOffsetAlignment, whichever is lower + * [[VUID-VkIndirectCommandsLayoutTokenNV-tokenType-02976]] + If pname:tokenType is + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_VERTEX_BUFFER_NV, + pname:vertexBindingUnit must: stay within device supported limits for + the appropriate commands + * [[VUID-VkIndirectCommandsLayoutTokenNV-tokenType-02977]] + If pname:tokenType is + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_CONSTANT_NV, + pname:pushconstantPipelineLayout must: be valid + * [[VUID-VkIndirectCommandsLayoutTokenNV-tokenType-02978]] + If pname:tokenType is + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_CONSTANT_NV, + pname:pushconstantOffset must: be a multiple of `4` + * [[VUID-VkIndirectCommandsLayoutTokenNV-tokenType-02979]] + If pname:tokenType is + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_CONSTANT_NV, + pname:pushconstantSize must: be a multiple of `4` + * [[VUID-VkIndirectCommandsLayoutTokenNV-tokenType-02980]] + If pname:tokenType is + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_CONSTANT_NV, + pname:pushconstantOffset must: be less than + sname:VkPhysicalDeviceLimits::pname:maxPushConstantsSize + * [[VUID-VkIndirectCommandsLayoutTokenNV-tokenType-02981]] + If pname:tokenType is + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_CONSTANT_NV, + pname:pushconstantSize must: be less than or equal to + sname:VkPhysicalDeviceLimits::pname:maxPushConstantsSize minus + pname:pushconstantOffset + * [[VUID-VkIndirectCommandsLayoutTokenNV-tokenType-02982]] + If pname:tokenType is + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_CONSTANT_NV, for each byte in + the range specified by pname:pushconstantOffset and + pname:pushconstantSize and for each shader stage in + pname:pushconstantShaderStageFlags, there must: be a push constant range + in pname:pushconstantPipelineLayout that includes that byte and that + stage + * [[VUID-VkIndirectCommandsLayoutTokenNV-tokenType-02983]] + If pname:tokenType is + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_CONSTANT_NV, for each byte in + the range specified by pname:pushconstantOffset and + pname:pushconstantSize and for each push constant range that overlaps + that byte, pname:pushconstantShaderStageFlags must: include all stages + in that push constant range's + slink:VkPushConstantRange::pname:stageFlags + * [[VUID-VkIndirectCommandsLayoutTokenNV-tokenType-02984]] + If pname:tokenType is + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_STATE_FLAGS_NV, + pname:indirectStateFlags must: not be `0` +**** + +include::{generated}/validity/structs/VkIndirectCommandsLayoutTokenNV.adoc[] +-- + +The following code provides detailed information on how an individual +sequence is processed. +For valid usage, all restrictions from the regular commands apply. + +[source,c] +---- +void cmdProcessSequence(cmd, pipeline, indirectCommandsLayout, pIndirectCommandsStreams, s) +{ + for (uint32_t t = 0; t < indirectCommandsLayout.tokenCount; t++){ + token = indirectCommandsLayout.pTokens[t]; + + uint32_t stride = indirectCommandsLayout.pStreamStrides[token.stream]; + stream = pIndirectCommandsStreams[token.stream]; + uint32_t offset = stream.offset + stride * s + token.offset; + const void* input = stream.buffer.pointer( offset ) + + switch(input.type){ + case VK_INDIRECT_COMMANDS_TOKEN_TYPE_SHADER_GROUP_NV: + VkBindShaderGroupIndirectCommandNV* bind = input; + + vkCmdBindPipelineShaderGroupNV(cmd, indirectCommandsLayout.pipelineBindPoint, + pipeline, bind->groupIndex); + break; + + case VK_INDIRECT_COMMANDS_TOKEN_TYPE_STATE_FLAGS_NV: + VkSetStateFlagsIndirectCommandNV* state = input; + + if (token.indirectStateFlags & VK_INDIRECT_STATE_FLAG_FRONTFACE_BIT_NV){ + if (state.data & (1 << 0)){ + set VK_FRONT_FACE_CLOCKWISE; + } else { + set VK_FRONT_FACE_COUNTER_CLOCKWISE; + } + } + break; + + case VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_CONSTANT_NV: + uint32_t* data = input; + + vkCmdPushConstants(cmd, + token.pushconstantPipelineLayout + token.pushconstantStageFlags, + token.pushconstantOffset, + token.pushconstantSize, data); + break; + + case VK_INDIRECT_COMMANDS_TOKEN_TYPE_INDEX_BUFFER_NV: + VkBindIndexBufferIndirectCommandNV* data = input; + + // the indexType may optionally be remapped + // from a custom uint32_t value, via + // VkIndirectCommandsLayoutTokenNV::pIndexTypeValues + + vkCmdBindIndexBuffer(cmd, + deriveBuffer(data->bufferAddress), + deriveOffset(data->bufferAddress), + data->indexType); + break; + + case VK_INDIRECT_COMMANDS_TOKEN_TYPE_VERTEX_BUFFER_NV: + VkBindVertexBufferIndirectCommandNV* data = input; + + // if token.vertexDynamicStride is VK_TRUE + // then the stride for this binding is set + // using data->stride as well + + vkCmdBindVertexBuffers(cmd, + token.vertexBindingUnit, 1, + &deriveBuffer(data->bufferAddress), + &deriveOffset(data->bufferAddress)); + break; + + case VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_INDEXED_NV: + vkCmdDrawIndexedIndirect(cmd, + stream.buffer, offset, 1, 0); + break; + + case VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_NV: + vkCmdDrawIndirect(cmd, + stream.buffer, + offset, 1, 0); + break; + + // only available if VK_NV_mesh_shader is supported + case VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_TASKS_NV: + vkCmdDrawMeshTasksIndirectNV(cmd, + stream.buffer, offset, 1, 0); + break; + + // only available if VK_EXT_mesh_shader is supported + case VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_NV: + vkCmdDrawMeshTasksIndirectEXT(cmd, + stream.buffer, offset, 1, 0); + break; + +ifdef::VK_NV_device_generated_commands_compute[] + case VK_INDIRECT_COMMANDS_TOKEN_TYPE_PIPELINE_NV: + VkBindPipelineIndirectCommandNV *data = input; + VkPipeline computePipeline = deriveFromDeviceAddress(data->pipelineAddress); + vkCmdBindPipeline(cmd, VK_PIPELINE_BIND_POINT_COMPUTE, computePipeline); + break; + + case VK_INDIRECT_COMMANDS_TOKEN_TYPE_DISPATCH_NV: + vkCmdDispatchIndirect(cmd, stream.buffer, offset); + break; +endif::VK_NV_device_generated_commands_compute[] + } + } +} +---- +endif::VK_NV_device_generated_commands[] diff --git a/chapters/drawing.adoc b/chapters/drawing.adoc index f2cc0413d..cae1bbc38 100644 --- a/chapters/drawing.adoc +++ b/chapters/drawing.adoc @@ -337,7 +337,7 @@ include::{generated}/validity/protos/vkCmdSetPrimitiveTopology.adoc[] The primitive topologies are grouped into the following topology classes: [[topology-classes]] -.Topology classes +.Topology Classes [options="header"] |=== | Topology Class | Primitive Topology @@ -1272,10 +1272,6 @@ similarly named parameters of flink:vkCmdDraw. .Valid Usage **** include::{chapters}/commonvalidity/draw_instance_common.adoc[] - * [[VUID-VkDrawIndirectCommand-None-00500]] - For a given vertex buffer binding, any attribute data fetched must: be - entirely contained within the corresponding vertex buffer binding, as - described in <> * [[VUID-VkDrawIndirectCommand-firstInstance-00501]] If the <> feature is not enabled, @@ -1435,10 +1431,6 @@ the similarly named parameters of flink:vkCmdDrawIndexed. **** include::{chapters}/commonvalidity/draw_instance_common.adoc[] include::{chapters}/commonvalidity/draw_index_binding.adoc[] - * [[VUID-VkDrawIndexedIndirectCommand-None-00552]] - For a given vertex buffer binding, any attribute data fetched must: be - entirely contained within the corresponding vertex buffer binding, as - described in <> * [[VUID-VkDrawIndexedIndirectCommand-firstInstance-00554]] If the <> feature is not enabled, diff --git a/chapters/features.adoc b/chapters/features.adoc index d0c6bf26a..eac910c66 100644 --- a/chapters/features.adoc +++ b/chapters/features.adoc @@ -3391,7 +3391,7 @@ describe the following features: the stext:NvSciSyncObj. [[features-externalscisync-table]] -.Functionality supported for NvSciSync features +.Functionality Supported for NvSciSync Features |===== | Features | pname:sciSyncImport | pname:sciSyncExport | Always supported^1^ | pname:sciSyncFence @@ -3460,7 +3460,7 @@ structure describe the following features: the stext:NvSciSyncObj. [[features-externalscisync2-table]] -.Functionality supported for NvSciSync features +.Functionality Supported for NvSciSync Features |===== | Features | pname:sciSyncImport | pname:sciSyncExport | Always supported^1^ | pname:sciSyncFence @@ -3521,7 +3521,7 @@ structure describe the following features: the stext:NvSciBufObj. [[features-externalscibuf-table]] -.Functionality supported for NvSciBuf features +.Functionality Supported for NvSciBuf Features |===== | Features | Functionality | pname:sciBufImport | slink:VkImportMemorySciBufInfoNV, flink:vkGetPhysicalDeviceExternalMemorySciBufPropertiesNV @@ -3568,7 +3568,7 @@ describe the following features: of the code:_screen_buffer. [[features-externalscreenbuffer-table]] -.Functionality supported for QNX Screen Buffer features +.Functionality Supported for QNX Screen Buffer Features |===== | Features | Functionality | pname:screenBufferImport | slink:VkImportScreenBufferInfoQNX @@ -4519,6 +4519,36 @@ include::{generated}/validity/structs/VkPhysicalDeviceDeviceGeneratedCommandsCom -- endif::VK_NV_device_generated_commands_compute[] +ifdef::VK_EXT_device_generated_commands[] +[open,refpage='VkPhysicalDeviceDeviceGeneratedCommandsFeaturesEXT',desc='Structure describing the device-generated compute features that can be supported by an implementation',type='structs'] +-- +The sname:VkPhysicalDeviceDeviceGeneratedCommandsFeaturesEXT structure is +defined as: + +include::{generated}/api/structs/VkPhysicalDeviceDeviceGeneratedCommandsFeaturesEXT.adoc[] + +This structure describes the following features: + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * [[features-deviceGeneratedCommandsEXT]] pname:deviceGeneratedCommands + indicates whether the implementation supports functionality to generate + commands on the device. + * [[features-dynamicGeneratedPipelineLayout]] + pname:dynamicGeneratedPipelineLayout indicates the implementation allows + the pname:pipelineLayout member of + slink:VkIndirectCommandsLayoutCreateInfoEXT to be dlink:VK_NULL_HANDLE + and slink:VkPipelineLayoutCreateInfo can: be chained off those + structures' pname:pNext instead. + +:refpage: VkPhysicalDeviceDeviceGeneratedCommandsFeaturesEXT +include::{chapters}/features.adoc[tag=features] + +include::{generated}/validity/structs/VkPhysicalDeviceDeviceGeneratedCommandsFeaturesEXT.adoc[] +-- +endif::VK_EXT_device_generated_commands[] + ifdef::VK_NV_device_diagnostics_config[] [open,refpage='VkPhysicalDeviceDiagnosticsConfigFeaturesNV',desc='Structure describing the device-generated diagnostic configuration features that can be supported by an implementation',type='structs'] -- @@ -5194,6 +5224,31 @@ include::{generated}/validity/structs/VkPhysicalDeviceDepthClipControlFeaturesEX -- endif::VK_EXT_depth_clip_control[] +ifdef::VK_EXT_depth_clamp_control[] +[open,refpage='VkPhysicalDeviceDepthClampControlFeaturesEXT',desc='Structure describing additional depth clamp control supported by an implementation',type='structs'] +-- +The sname:VkPhysicalDeviceDepthClampControlFeaturesEXT structure is defined +as: + +include::{generated}/api/structs/VkPhysicalDeviceDepthClampControlFeaturesEXT.adoc[] + +This structure describes the following feature: + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * [[features-depthClampControl]] pname:depthClampControl indicates that + the implementation supports setting + slink:VkPipelineViewportDepthClampControlCreateInfoEXT::pname:depthClampMode + to ename:VK_DEPTH_CLAMP_MODE_USER_DEFINED_RANGE_EXT. + +:refpage: VkPhysicalDeviceDepthClampControlFeaturesEXT +include::{chapters}/features.adoc[tag=features] + +include::{generated}/validity/structs/VkPhysicalDeviceDepthClampControlFeaturesEXT.adoc[] +-- +endif::VK_EXT_depth_clamp_control[] + ifdef::VK_KHR_workgroup_memory_explicit_layout[] [open,refpage='VkPhysicalDeviceWorkgroupMemoryExplicitLayoutFeaturesKHR',desc='Structure describing the workgroup storage explicit layout features that can be supported by an implementation',type='structs'] -- @@ -8119,11 +8174,6 @@ ifdef::VK_KHR_shader_float16_int8[] <> if `apiext:VK_KHR_shader_float16_int8` is supported. endif::VK_KHR_shader_float16_int8[] -ifdef::VK_KHR_compute_shader_derivatives[] - * <>, if the - `apiext:VK_KHR_compute_shader_derivatives` extension is supported. -endif::VK_KHR_compute_shader_derivatives[] ifdef::VKSC_VERSION_1_0[] ifdef::hidden[] diff --git a/chapters/formats.adoc b/chapters/formats.adoc index 287410c85..2b4406cb0 100644 --- a/chapters/formats.adoc +++ b/chapters/formats.adoc @@ -1460,7 +1460,7 @@ The in-memory ordering of bytes within a component is determined by the host endianness. [[formats-non-packed]] -.Byte mappings for non-packed/compressed color formats +.Byte Mappings for Non-Packed/Compressed Color Formats [options="header",cols="16*1,10",width="100%"] |==== >|0 >|1 >|2 >|3 >|4 >|5 >|6 >|7 >|8 >|9 >|10 >|11 >|12 >|13 >|14 >|15 ^| {leftarrow} Byte @@ -1507,7 +1507,7 @@ The in-memory ordering of bytes comprising the underlying type is determined by the host endianness. [[formats-packed-8-bit]] -.Bit mappings for packed 8-bit formats +.Bit Mappings for Packed 8-Bit Formats [options="header",cols="8*1",width="100%"] |==== 8+^h| Bit @@ -1519,7 +1519,7 @@ by the host endianness. |==== [[formats-packed-16-bit]] -.Bit mappings for packed 16-bit formats +.Bit Mappings for Packed 16-Bit Formats [options="header",cols="16*1",width="100%"] |==== 16+^h| Bit @@ -1602,7 +1602,7 @@ endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |==== [[formats-packed-32-bit]] -.Bit mappings for packed 32-bit formats +.Bit Mappings for Packed 32-Bit Formats [cols="32*1",options="header"] |==== 32+^h|Bit @@ -2763,7 +2763,7 @@ ename:VK_FORMAT_FEATURE_TRANSFER_SRC_BIT and ename:VK_FORMAT_FEATURE_TRANSFER_DST_BIT. endif::VK_VERSION_1_1,VK_KHR_maintenance1[] -.Key for format feature tables +.Key for Format Feature Tables [width="70%",cols="1,10"] |==== ^|{sym1} | This feature must: be supported on the named format @@ -2776,7 +2776,7 @@ preconditions, with more information in the table where the symbol appears preconditions, with more information in the table where the symbol appears |==== -.Feature bits in pname:optimalTilingFeatures +.Feature Bits in pname:optimalTilingFeatures [width="70%"] |==== ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[] @@ -2797,7 +2797,7 @@ ifdef::VK_VERSION_1_2,VK_EXT_sampler_filter_minmax[] endif::VK_VERSION_1_2,VK_EXT_sampler_filter_minmax[] |==== -.Feature bits in pname:bufferFeatures +.Feature Bits in pname:bufferFeatures [width="70%"] |==== |ename:VK_FORMAT_FEATURE_VERTEX_BUFFER_BIT @@ -2809,7 +2809,7 @@ endif::VK_VERSION_1_2,VK_EXT_sampler_filter_minmax[] <<< [[formats-mandatory-features-subbyte]] -.Mandatory format support: sub-byte components +.Mandatory Format Support: Sub-Byte Components [width="100%",cols="12,^1,^1,^1,^1,^1,^1,^1,^1,^1,^1,^1,^1,^1",options="unbreakable"] |==== 13+>| ename:VK_FORMAT_FEATURE_STORAGE_TEXEL_BUFFER_ATOMIC_BIT .14+^.^| {downarrow} @@ -2854,7 +2854,7 @@ endif::VK_VERSION_1_3,VK_EXT_4444_formats[] <<< [[formats-mandatory-features-2byte]] -.Mandatory format support: 1-3 byte-sized components +.Mandatory Format Support: 1-3 Byte-Sized Components [width="100%",cols="12,^1,^1,^1,^1,^1,^1,^1,^1,^1,^1,^1,^1,^1",options="unbreakable"] |==== 13+>| ename:VK_FORMAT_FEATURE_STORAGE_TEXEL_BUFFER_ATOMIC_BIT .14+^.^| {downarrow} @@ -2911,7 +2911,7 @@ pname:shaderStorageImageExtendedFormats>> feature. <<< [[formats-mandatory-features-4byte]] -.Mandatory format support: 4 byte-sized components +.Mandatory Format Support: 4 Byte-Sized Components [width="100%",cols="12,^1,^1,^1,^1,^1,^1,^1,^1,^1,^1,^1,^1,^1",options="unbreakable"] |==== 13+>| ename:VK_FORMAT_FEATURE_STORAGE_TEXEL_BUFFER_ATOMIC_BIT .14+^.^| {downarrow} @@ -2954,7 +2954,7 @@ s| Format <<< [[formats-mandatory-features-10bit]] -.Mandatory format support: 10- and 12-bit components +.Mandatory Format Support: 10- and 12-Bit Components [width="100%",cols="12,^1,^1,^1,^1,^1,^1,^1,^1,^1,^1,^1,^1,^1",options="unbreakable"] |==== 13+>| ename:VK_FORMAT_FEATURE_STORAGE_TEXEL_BUFFER_ATOMIC_BIT .14+^.^| {downarrow} @@ -2998,7 +2998,7 @@ pname:shaderStorageImageExtendedFormats>> feature. <<< [[formats-mandatory-features-16bit]] -.Mandatory format support: 16-bit components +.Mandatory Format Support: 16-bit Components [width="100%",cols="12,^1,^1,^1,^1,^1,^1,^1,^1,^1,^1,^1,^1,^1",options="unbreakable"] |==== 13+>| ename:VK_FORMAT_FEATURE_STORAGE_TEXEL_BUFFER_ATOMIC_BIT .14+^.^| {downarrow} @@ -3058,7 +3058,7 @@ endif::VK_NV_shader_atomic_float16_vector[] <<< [[formats-mandatory-features-32bit]] -.Mandatory format support: 32-bit components +.Mandatory Format Support: 32-bit Components [width="100%",cols="12,^1,^1,^1,^1,^1,^1,^1,^1,^1,^1,^1,^1,^1",options="unbreakable"] |==== 13+>| ename:VK_FORMAT_FEATURE_STORAGE_TEXEL_BUFFER_ATOMIC_BIT .14+^.^| {downarrow} @@ -3105,7 +3105,7 @@ endif::VK_EXT_shader_atomic_float[] <<< [[formats-mandatory-features-64bit]] -.Mandatory format support: 64-bit/uneven components +.Mandatory Format Support: 64-bit/uneven Components [width="100%",cols="12,^1,^1,^1,^1,^1,^1,^1,^1,^1,^1,^1,^1,^1",options="unbreakable"] |==== 13+>| ename:VK_FORMAT_FEATURE_STORAGE_TEXEL_BUFFER_ATOMIC_BIT .14+^.^| {downarrow} @@ -3163,7 +3163,7 @@ endif::VK_EXT_shader_image_atomic_int64[] <<< [[formats-mandatory-features-depth-stencil]] -.Mandatory format support: depth/stencil with `VkImageType` ename:VK_IMAGE_TYPE_2D +.Mandatory Format Support: Depth/Stencil With `VkImageType` ename:VK_IMAGE_TYPE_2D [width="100%",cols="12,^1,^1,^1,^1,^1,^1,^1,^1,^1,^1,^1,^1,^1",options="unbreakable"] |==== 13+>| ename:VK_FORMAT_FEATURE_STORAGE_TEXEL_BUFFER_ATOMIC_BIT .14+^.^| {downarrow} @@ -3197,7 +3197,7 @@ ename:VK_FORMAT_D24_UNORM_S8_UINT and ename:VK_FORMAT_D32_SFLOAT_S8_UINT. <<< [[formats-mandatory-features-bcn]] -.Mandatory format support: BC compressed formats with `VkImageType` ename:VK_IMAGE_TYPE_2D and ename:VK_IMAGE_TYPE_3D +.Mandatory Format Support: BC Compressed Formats With `VkImageType` ename:VK_IMAGE_TYPE_2D and ename:VK_IMAGE_TYPE_3D [width="100%",cols="12,^1,^1,^1,^1,^1,^1,^1,^1,^1,^1,^1,^1,^1",options="unbreakable"] |==== 13+>| ename:VK_FORMAT_FEATURE_STORAGE_TEXEL_BUFFER_ATOMIC_BIT .14+^.^| {downarrow} @@ -3241,7 +3241,7 @@ one of: this table, <>, or <<< [[formats-mandatory-features-etc]] -.Mandatory format support: ETC2 and EAC compressed formats with `VkImageType` ename:VK_IMAGE_TYPE_2D +.Mandatory Format Support: ETC2 and EAC Compressed Formats With `VkImageType` ename:VK_IMAGE_TYPE_2D [width="100%",cols="12,^1,^1,^1,^1,^1,^1,^1,^1,^1,^1,^1,^1,^1",options="unbreakable"] |==== 13+>| ename:VK_FORMAT_FEATURE_STORAGE_TEXEL_BUFFER_ATOMIC_BIT .14+^.^| {downarrow} @@ -3279,7 +3279,7 @@ one of: this table, <>, or <<< [[formats-mandatory-features-astc]] -.Mandatory format support: ASTC LDR compressed formats with `VkImageType` ename:VK_IMAGE_TYPE_2D +.Mandatory Format Support: ASTC LDR Compressed Formats With `VkImageType` ename:VK_IMAGE_TYPE_2D [width="100%",cols="12,^1,^1,^1,^1,^1,^1,^1,^1,^1,^1,^1,^1,^1",options="unbreakable"] |==== 13+>| ename:VK_FORMAT_FEATURE_STORAGE_TEXEL_BUFFER_ATOMIC_BIT .14+^.^| {downarrow} @@ -3403,7 +3403,7 @@ equal to ename:VK_IMAGE_ASPECT_COLOR_BIT, <> must: be enabled for the following formats: [[formats-requiring-sampler-ycbcr-conversion]] -.Formats requiring sampler {YCbCr} conversion for ename:VK_IMAGE_ASPECT_COLOR_BIT image views +.Formats Requiring Sampler {YCbCr} Conversion for ename:VK_IMAGE_ASPECT_COLOR_BIT Image Views [width="100%",cols="18,^3,^1,^1,^1,^1,^1,^1,^1,^1,^1,^1",options="unbreakable"] |==== 11+>| ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_CHROMA_RECONSTRUCTION_EXPLICIT_FORCEABLE_BIT .11+^.^| {downarrow} @@ -3648,7 +3648,7 @@ Additional restrictions, including, but not limited to, further required format feature flags specific to the particular use of the resource may: apply, as described in the respective sections of this specification. -.Format feature dependent buffer usage flags +.Format Feature Dependent Buffer Usage Flags [cols="50%,50%",options="header"] |==== |Buffer usage flag | Required format feature flag @@ -3657,7 +3657,7 @@ apply, as described in the respective sections of this specification. |ename:VK_BUFFER_USAGE_VERTEX_BUFFER_BIT | ename:VK_FORMAT_FEATURE_VERTEX_BUFFER_BIT |==== -.Format feature dependent image usage flags +.Format Feature Dependent Image Usage Flags [cols="50%,50%",options="header"] |==== |Image usage flag | Required format feature flag diff --git a/chapters/fragops.adoc b/chapters/fragops.adoc index 58dff5e02..dd8a0d115 100644 --- a/chapters/fragops.adoc +++ b/chapters/fragops.adoc @@ -1842,9 +1842,17 @@ sections. If slink:VkPipelineRasterizationStateCreateInfo::pname:depthClampEnable is enabled, [eq]#z~f~# is clamped to [eq]#[z~min~, z~max~]#, where [eq]#z~min~ -= min(n,f)#, [eq]#z~max~ = max(n,f)]#, and [eq]#n# and [eq]#f# are the += min(n,f)#, [eq]#z~max~ = max(n,f)#, and [eq]#n# and [eq]#f# are the pname:minDepth and pname:maxDepth depth range values of the viewport used by this fragment, respectively. +ifdef::VK_EXT_depth_clamp_control[] +If <> is enabled and +slink:VkPipelineViewportDepthClampControlCreateInfoEXT::pname:depthClampMode +is set to ename:VK_DEPTH_CLAMP_MODE_USER_DEFINED_RANGE_EXT then [eq]#z~min~# +and [eq]#z~max~# are equal to the pname:minDepthClamp and +pname:maxDepthClamp values of the slink:VkDepthClampRangeEXT structure +pointed to by pname:pDepthClampRange. +endif::VK_EXT_depth_clamp_control[] ifdef::VK_EXT_depth_clamp_zero_one[] If @@ -1875,6 +1883,9 @@ ifdef::VK_EXT_depth_range_unrestricted[] step. endif::VK_EXT_depth_range_unrestricted[] +ifdef::VK_EXT_depth_clamp_control[] +include::{chapters}/VK_EXT_depth_clamp_control/fragops.adoc[] +endif::VK_EXT_depth_clamp_control[] [[fragops-depth-comparison]] === Depth Comparison diff --git a/chapters/fundamentals.adoc b/chapters/fundamentals.adoc index b827c5d3c..d8c5e53e7 100644 --- a/chapters/fundamentals.adoc +++ b/chapters/fundamentals.adoc @@ -369,6 +369,10 @@ endif::VKSC_VERSION_1_0[] ifdef::VK_NV_device_generated_commands[] * sname:VkIndirectCommandsLayoutNV endif::VK_NV_device_generated_commands[] +ifdef::VK_EXT_device_generated_commands[] + * sname:VkIndirectCommandsLayoutEXT + * sname:VkIndirectExecutionSetEXT +endif::VK_EXT_device_generated_commands[] ifdef::VK_NV_ray_tracing[] * sname:VkAccelerationStructureNV endif::VK_NV_ray_tracing[] @@ -407,6 +411,10 @@ ifdef::VK_NV_device_generated_commands[] use of a <> for additional graphics shader groups in another pipeline, endif::VK_NV_device_generated_commands[] +ifdef::VK_EXT_device_generated_commands[] +use of a <> for +additional shader-related states in a set, +endif::VK_EXT_device_generated_commands[] ifdef::VK_KHR_acceleration_structure[] use of a <> in an instance referenced by a @@ -1433,8 +1441,6 @@ ifdef::VK_KHR_pipeline_binary[] * ename:VK_PIPELINE_BINARY_MISSING_KHR The application attempted to create a pipeline binary by querying an internal cache, but the internal cache entry did not exist. - * ename:VK_ERROR_NOT_ENOUGH_SPACE_KHR The application did not provide - enough space to return all the required data. endif::VK_KHR_pipeline_binary[] ifdef::VK_EXT_shader_object[] * ename:VK_INCOMPATIBLE_SHADER_BINARY_EXT The provided binary shader code @@ -1451,7 +1457,7 @@ compatibility with old code. endif::VK_EXT_shader_object[] [[fundamentals-errorcodes]] -.Error codes +.Error Codes * ename:VK_ERROR_OUT_OF_HOST_MEMORY A host memory allocation has failed. * ename:VK_ERROR_OUT_OF_DEVICE_MEMORY A device memory allocation has failed. @@ -1604,6 +1610,10 @@ ifdef::VK_KHR_global_priority,VK_EXT_global_priority[] (ename:VK_QUEUE_GLOBAL_PRIORITY_MEDIUM_EXT) because the application does not have sufficient privileges. endif::VK_KHR_global_priority,VK_EXT_global_priority[] +ifdef::VK_KHR_pipeline_binary[] + * ename:VK_ERROR_NOT_ENOUGH_SPACE_KHR The application did not provide + enough space to return all the required data. +endif::VK_KHR_pipeline_binary[] * ename:VK_ERROR_UNKNOWN An unknown error has occurred; either the application has provided invalid input, or an implementation failure has occurred. diff --git a/chapters/fxvertex.adoc b/chapters/fxvertex.adoc index f153f974b..87b24e0be 100644 --- a/chapters/fxvertex.adoc +++ b/chapters/fxvertex.adoc @@ -38,7 +38,7 @@ attribute number using the code:location layout qualifier. The code:Component layout qualifier associates components of a vertex shader input variable with components of a vertex input attribute. -.GLSL example +.GLSL Example [source,glsl] ---- // Assign location M to variableName @@ -55,7 +55,7 @@ variable with components of a vertex input attribute. The code:Location and code:Component decorations are specified via the code:OpDecorate instruction. -.SPIR-V example +.SPIR-V Example [source,spirv] ---- ... @@ -110,7 +110,7 @@ width of 16 bits. endif::VK_VERSION_1_1,VK_KHR_16bit_storage[] [[fxvertex-attrib-components]] -.Input attribute components accessed by 16-bit and 32-bit input variables +.Input Attribute Components Accessed By 16-Bit and 32-Bit Input Variables [width="65%",cols="<5,<3,<3",options="header"] |==== | 16-bit or 32-bit data type | code:Component decoration | Components consumed @@ -143,7 +143,7 @@ vector. The code:Component decoration must: not be used with matrix types. [[fxvertex-attrib-matrix]] -.Input attributes accessed by 32-bit input matrix variables +.Input Attributes Accessed by 32-Bit Input Matrix Variables [width="100%",cols="<10%,<24%,<21%,<45%",options="header"] |==== | Data type | Column vector type | Locations consumed | Components consumed @@ -175,7 +175,7 @@ Input variables must: not use more components than provided by the attribute. [[fxvertex-attrib-double]] -.Input attribute locations and components accessed by 64-bit input variables +.Input Attribute Locations and Components Accessed by 64-Bit Input Variables [width="100%",cols="<18%,^12%,<25%,^14%,^18%,<13%",options="header"] |==== ^.^| Input format | Locations consumed @@ -943,7 +943,7 @@ ifdef::VK_EXT_vertex_input_dynamic_state,VK_EXT_shader_object[] ** flink:vkCmdSetVertexInputEXT::pname:pVertexBindingDescriptions->stride endif::VK_EXT_vertex_input_dynamic_state,VK_EXT_shader_object[] ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] - ** flink:vkCmdBindVertexBuffers2EXT::pname:pStride, if not `NULL` + ** flink:vkCmdBindVertexBuffers2::pname:pStride, if not `NULL` endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] [source,c] diff --git a/chapters/interfaces.adoc b/chapters/interfaces.adoc index bb8f5d9b7..d23b9bac5 100644 --- a/chapters/interfaces.adoc +++ b/chapters/interfaces.adoc @@ -5005,8 +5005,9 @@ The code:ViewIndex decoration can: be applied to a shader input which will be filled with the index of the view that is being processed by the current shader invocation. + -If multiview is enabled in the render pass, this value will be one of the -bits set in the view mask of the subpass the pipeline is compiled against. +If multiview is enabled in the render pass, this value will be the index of +one of the bits set in the view mask of the subpass the pipeline is compiled +against. If multiview is not enabled in the render pass, this value will be zero. .Valid Usage diff --git a/chapters/limits.adoc b/chapters/limits.adoc index dfe1d48b1..e87c17669 100644 --- a/chapters/limits.adoc +++ b/chapters/limits.adoc @@ -3529,6 +3529,76 @@ include::{generated}/validity/structs/VkPhysicalDeviceDeviceGeneratedCommandsPro endif::VK_NV_device_generated_commands[] +ifdef::VK_EXT_device_generated_commands[] +[open,refpage='VkPhysicalDeviceDeviceGeneratedCommandsPropertiesEXT',desc='Structure describing push descriptor limits that can be supported by an implementation',type='structs'] +-- +The sname:VkPhysicalDeviceDeviceGeneratedCommandsPropertiesEXT structure is +defined as: + +include::{generated}/api/structs/VkPhysicalDeviceDeviceGeneratedCommandsPropertiesEXT.adoc[] + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * [[limits-maxIndirectPipelineCount]] pname:maxIndirectPipelineCount is + the maximum number of pipelines passed to + flink:vkCreateIndirectExecutionSetEXT. +ifdef::VK_EXT_shader_object[] + * [[limits-maxIndirectShaderObjectCount]] + pname:maxIndirectShaderObjectCount is the maximum number of shader + objects passed to flink:vkCreateIndirectExecutionSetEXT. + If this value is zero, binding shader objects indirectly is not + supported. +endif::VK_EXT_shader_object[] + * [[limits-maxIndirectSequenceCount]] pname:maxIndirectSequenceCount is + the maximum number of sequences in slink:VkGeneratedCommandsInfoEXT and + in slink:VkGeneratedCommandsMemoryRequirementsInfoEXT. + * [[limits-maxIndirectCommandsTokenCount]] + pname:maxIndirectCommandsTokenCount is the maximum number of tokens in + slink:VkIndirectCommandsLayoutCreateInfoEXT. + * [[limits-maxIndirectCommandsTokenOffset]] + pname:maxIndirectCommandsTokenOffset is the maximum offset in + slink:VkIndirectCommandsLayoutTokenEXT. + * [[limits-maxIndirectCommandsIndirectStride]] + pname:maxIndirectCommandsIndirectStride is the maximum stream stride in + slink:VkIndirectCommandsLayoutCreateInfoEXT. + * [[limits-supportedIndirectCommandsInputModes]] + pname:supportedIndirectCommandsInputModes indicates the supported input + modes. + * [[limits-supportedIndirectCommandsShaderStages]] + pname:supportedIndirectCommandsShaderStages indicates the stages which + can: be used to generate indirect commands. + Implementations are required to support, at minimum: + ename:VK_SHADER_STAGE_VERTEX_BIT, ename:VK_SHADER_STAGE_FRAGMENT_BIT, + ename:VK_SHADER_STAGE_COMPUTE_BIT. + * [[limits-supportedIndirectCommandsShaderStagesPipelineBinding]] + pname:supportedIndirectCommandsShaderStagesPipelineBinding indicates the + stages which can: be used within indirect execution sets for indirectly + binding shader stages using pipelines. +ifdef::VK_EXT_shader_object[] + * [[limits-supportedIndirectCommandsShaderStagesShaderBinding]] + pname:supportedIndirectCommandsShaderStagesShaderBinding indicates the + stages which can: be used within indirect execution sets for indirectly + binding shader stages using shader objects. +endif::VK_EXT_shader_object[] + * [[limits-deviceGeneratedCommandsTransformFeedback]] + pname:deviceGeneratedCommandsTransformFeedback indicates whether the + implementation supports interactions with + `apiext:VK_EXT_transform_feedback` for pipelines not created with + ename:VK_PIPELINE_CREATE_2_INDIRECT_BINDABLE_BIT_EXT. + * [[limits-deviceGeneratedCommandsMultiDrawIndirectCount]] + pname:deviceGeneratedCommandsMultiDrawIndirectCount indicates whether + the implementation supports COUNT variants of multi-draw indirect + tokens. + +:refpage: VkPhysicalDeviceDeviceGeneratedCommandsPropertiesEXT +include::{chapters}/limits.adoc[tag=limits_desc] + +include::{generated}/validity/structs/VkPhysicalDeviceDeviceGeneratedCommandsPropertiesEXT.adoc[] +-- + +endif::VK_EXT_device_generated_commands[] + ifdef::VK_KHR_portability_subset[] [open,refpage='VkPhysicalDevicePortabilitySubsetPropertiesKHR',desc='Structure describing additional properties supported by a portable implementation',type='structs'] -- @@ -4947,6 +5017,8 @@ endif::VK_MESA_image_alignment_control[] [[limits-minmax]] == Limit Requirements +[open,refpage='Required_Limits',desc='Vulkan required limit tables',type='freeform',anchor='limits-minmax'] +-- The following table specifies the required: minimum/maximum for all Vulkan graphics implementations. Where a limit corresponds to a fine-grained device feature which is @@ -5374,6 +5446,9 @@ ifdef::VK_AMDX_shader_enqueue[] | code:uint32_t | pname:maxExecutionGraphShaderPayloadCount | `<>` | code:uint32_t | pname:executionGraphDispatchAddressAlignment | `<>` endif::VK_AMDX_shader_enqueue[] +ifdef::VK_EXT_device_generated_commands[] +| code:uint32_t | pname:maxIndirectShaderObjectCount | `<>` +endif::VK_EXT_device_generated_commands[] ifdef::VK_NV_extended_sparse_address_space[] | basetype:VkDeviceSize | pname:extendedSparseAddressSpaceSize | pname:sparseBinding, `<>` endif::VK_NV_extended_sparse_address_space[] @@ -5727,15 +5802,32 @@ ifdef::VK_KHR_line_rasterization,VK_EXT_line_rasterization[] endif::VK_KHR_line_rasterization,VK_EXT_line_rasterization[] ifdef::VK_NV_device_generated_commands[] | pname:maxGraphicsShaderGroupCount | - | 2^12^ | min -| pname:maxIndirectSequenceCount | - | 2^20^ | min -| pname:maxIndirectCommandsTokenCount | - | 16 | min -| pname:maxIndirectCommandsStreamCount | - | 16 | min -| pname:maxIndirectCommandsTokenOffset | - | 2047 | min +| pname:maxIndirectCommandsStreamCount + (for NV extension) | - | 2^12^ | min | pname:maxIndirectCommandsStreamStride | - | 2048 | min +| pname:minIndirectCommandsBufferOffsetAlignment | - | 256 | max | pname:minSequencesCountBufferOffsetAlignment | - | 256 | max | pname:minSequencesIndexBufferOffsetAlignment | - | 256 | max -| pname:minIndirectCommandsBufferOffsetAlignment | - | 256 | max endif::VK_NV_device_generated_commands[] +ifdef::VK_NV_device_generated_commands,VK_EXT_device_generated_commands[] +| pname:maxIndirectSequenceCount | - | 2^20^ | min +| pname:maxIndirectCommandsTokenCount | - | 16 | min +| pname:maxIndirectCommandsTokenOffset | - | 2047 | min +endif::VK_NV_device_generated_commands,VK_EXT_device_generated_commands[] +ifdef::VK_EXT_device_generated_commands[] +| pname:maxIndirectPipelineCount | - | 2^12^ | min +| pname:deviceGeneratedCommandsTransformFeedback | - | false | implementation-dependent +| pname:deviceGeneratedCommandsMultiDrawIndirectCount | - | false | implementation-dependent +ifdef::VK_EXT_shader_object[] +| pname:maxIndirectShaderObjectCount | 0 | 2^12^ | implementation-dependent +endif::VK_EXT_shader_object[] +| pname:maxIndirectCommandsIndirectStride | - | 2048 | min +| pname:supportedIndirectCommandsInputModes | - | ename:VK_INDIRECT_COMMANDS_INPUT_MODE_VULKAN_INDEX_BUFFER_EXT | min +| pname:supportedIndirectCommandsShaderStages | - | (ename:VK_SHADER_STAGE_COMPUTE_BIT \| ename:VK_SHADER_STAGE_VERTEX_BIT \| ename:VK_SHADER_STAGE_FRAGMENT_BIT) | min +| pname:supportedIndirectCommandsShaderStagesPipelineBinding | - | 0 | min +ifdef::VK_EXT_shader_object[] +| pname:supportedIndirectCommandsShaderStagesShaderBinding | - | 0 | min +endif::VK_EXT_shader_object[] +endif::VK_EXT_device_generated_commands[] ifdef::VK_EXT_custom_border_color[] | pname:maxCustomBorderColorSamplers | - | 32 | min endif::VK_EXT_custom_border_color[] @@ -5972,6 +6064,7 @@ ifdef::VK_EXT_descriptor_buffer[] pname:inputAttachmentDescriptorSize, and pname:accelerationStructureDescriptorSize. endif::VK_EXT_descriptor_buffer[] +-- ifdef::VK_EXT_sample_locations[] @@ -6103,4 +6196,5 @@ profile must: satisfy the following additional limit requirements: | pname:maxColorAttachments | 8 | min | pname:maxBoundDescriptorSets | 7 | min |==== + endif::VK_VERSION_1_3[] diff --git a/chapters/pipelines.adoc b/chapters/pipelines.adoc index 10f857807..0699a10fc 100644 --- a/chapters/pipelines.adoc +++ b/chapters/pipelines.adoc @@ -2742,6 +2742,18 @@ endif::VK_EXT_graphics_pipeline_library[] slink:VkGraphicsPipelineShaderGroupsCreateInfoNV::pname:groupCount must: be greater than `0` endif::VK_NV_device_generated_commands[] +ifdef::VK_EXT_device_generated_commands[] + * [[VUID-VkGraphicsPipelineCreateInfo-flags-11000]] + If pname:flags includes + ename:VK_PIPELINE_CREATE_2_INDIRECT_BINDABLE_BIT_EXT, then the + <> + feature must: be enabled + * [[VUID-VkGraphicsPipelineCreateInfo-flags-11001]] + If the pipeline requires <> and pname:flags includes + ename:VK_PIPELINE_CREATE_2_INDIRECT_BINDABLE_BIT_EXT, then all stages + must: not specify code:Xfb execution mode +endif::VK_EXT_device_generated_commands[] ifdef::VK_VERSION_1_3,VK_EXT_pipeline_creation_cache_control[] * [[VUID-VkGraphicsPipelineCreateInfo-pipelineCreationCacheControl-02878]] If the <>. endif::VK_NV_device_generated_commands[] +ifdef::VK_EXT_device_generated_commands[] + * ename:VK_PIPELINE_CREATE_2_INDIRECT_BINDABLE_BIT_EXT specifies that the + pipeline can: be used in a sname:VkIndirectExecutionSetEXT. +endif::VK_EXT_device_generated_commands[] ifdef::VK_VERSION_1_3,VK_EXT_pipeline_creation_cache_control[] * ename:VK_PIPELINE_CREATE_2_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT_KHR specifies that pipeline creation will fail if a compile is required for @@ -5004,7 +5020,7 @@ ifdef::VK_KHR_ray_tracing_pipeline[] endif::VK_KHR_ray_tracing_pipeline[] ifdef::VK_NV_device_generated_commands[] * ename:VK_PIPELINE_CREATE_INDIRECT_BINDABLE_BIT_NV specifies that the - pipeline can be used in combination with <>. + pipeline can: be used in combination with <>. endif::VK_NV_device_generated_commands[] ifdef::VK_VERSION_1_3,VK_EXT_pipeline_creation_cache_control[] * ename:VK_PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT specifies @@ -5666,6 +5682,13 @@ ifdef::VK_EXT_depth_clip_control[] and must: be set dynamically with flink:vkCmdSetDepthClipNegativeOneToOneEXT before any draw call. endif::VK_EXT_depth_clip_control[] +ifdef::VK_EXT_depth_clamp_control[] + * ename:VK_DYNAMIC_STATE_DEPTH_CLAMP_RANGE_EXT specifies that the + pname:depthClampMode and pname:pDepthClampRange state in + slink:VkPipelineViewportDepthClampControlCreateInfoEXT will be ignored + and must: be set dynamically with flink:vkCmdSetDepthClampRangeEXT + before any draw call. +endif::VK_EXT_depth_clamp_control[] ifdef::VK_NV_clip_space_w_scaling[] * ename:VK_DYNAMIC_STATE_VIEWPORT_W_SCALING_ENABLE_NV specifies that the pname:viewportWScalingEnable state in @@ -5962,7 +5985,6 @@ include::{generated}/validity/structs/VkGraphicsShaderGroupCreateInfoNV.adoc[] -- endif::VK_NV_device_generated_commands[] - ifdef::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] [[pipelines-ray-tracing]] == Ray Tracing Pipelines diff --git a/chapters/primsrast.adoc b/chapters/primsrast.adoc index 162105358..a06f5af23 100644 --- a/chapters/primsrast.adoc +++ b/chapters/primsrast.adoc @@ -669,9 +669,9 @@ framebuffer location [eq]#(x,y)# and the fragment size [eq]#(f~w~,f~h~)#: {empty}:: [eq]#p~y~ = y % f~h~# {empty}:: [eq]#p = p~x~ + (p~y~ {times} f~w~)# -The table below illustrates the pixel index for multi-pixel fragments: +The tables below illustrate the pixel index for multi-pixel fragments: -.Pixel indices - 1 wide +.Pixel Indices - 1 Wide [align="center"] |==== | 1x1 | 1x2 | 1x4 @@ -681,7 +681,7 @@ The table below illustrates the pixel index for multi-pixel fragments: .>| image:{images}/pixel_index_1x4.svg[pdfwidth=90pt,align="center",opts="{imageopts}"] |==== -.Pixel indices - 2 wide +.Pixel Indices - 2 Wide [align="center"] |==== | 2x1 | 2x2 | 2x4 @@ -691,7 +691,7 @@ The table below illustrates the pixel index for multi-pixel fragments: .>| image:{images}/pixel_index_2x4.svg[pdfwidth=90pt,align="center",opts="{imageopts}"] |==== -.Pixel indices - 4 wide +.Pixel Indices - 4 Wide [align="center"] |==== | 4x1 | 4x2 | 4x4 @@ -724,7 +724,7 @@ fragment. <<< -.Standard sample locations +.Standard Sample Locations [options="header",align="center"] |==== | Sample count 2+| Sample Locations diff --git a/chapters/resources.adoc b/chapters/resources.adoc index 1a540b6c9..69c25800c 100644 --- a/chapters/resources.adoc +++ b/chapters/resources.adoc @@ -461,8 +461,13 @@ ifdef::VK_NV_device_generated_commands[] It is also suitable for passing as the pname:buffer member of sname:VkIndirectCommandsStreamNV, or pname:sequencesCountBuffer or pname:sequencesIndexBuffer or pname:preprocessedBuffer member of - sname:VkGeneratedCommandsInfoNV + sname:VkGeneratedCommandsInfoNV. endif::VK_NV_device_generated_commands[] +ifdef::VK_EXT_device_generated_commands[] + It is also suitable for passing as the underlying buffer of either the + pname:preprocessAddress or pname:sequenceCountAddress members of + sname:VkGeneratedCommandsInfoEXT. +endif::VK_EXT_device_generated_commands[] ifdef::VK_EXT_conditional_rendering[] * ename:VK_BUFFER_USAGE_2_CONDITIONAL_RENDERING_BIT_EXT specifies that the buffer is suitable for passing as the pname:buffer parameter to @@ -533,6 +538,11 @@ ifdef::VK_AMDX_shader_enqueue[] the buffer can: be used for as scratch memory for <>. endif::VK_AMDX_shader_enqueue[] +ifdef::VK_EXT_device_generated_commands[] + * ename:VK_BUFFER_USAGE_2_PREPROCESS_BUFFER_BIT_EXT specifies that the + buffer can: be used as a preprocess buffer for + <>. +endif::VK_EXT_device_generated_commands[] -- [open,refpage='VkBufferUsageFlags2KHR',desc='Bitmask of VkBufferUsageFlagBits2KHR',type='flags'] @@ -604,8 +614,13 @@ ifdef::VK_NV_device_generated_commands[] It is also suitable for passing as the pname:buffer member of sname:VkIndirectCommandsStreamNV, or pname:sequencesCountBuffer or pname:sequencesIndexBuffer or pname:preprocessedBuffer member of - sname:VkGeneratedCommandsInfoNV + sname:VkGeneratedCommandsInfoNV. endif::VK_NV_device_generated_commands[] +ifdef::VK_EXT_device_generated_commands[] + It is also suitable for passing as the underlying buffer of either the + pname:preprocessAddress or pname:sequenceCountAddress members of + sname:VkGeneratedCommandsInfoEXT. +endif::VK_EXT_device_generated_commands[] ifdef::VK_EXT_conditional_rendering[] * ename:VK_BUFFER_USAGE_CONDITIONAL_RENDERING_BIT_EXT specifies that the buffer is suitable for passing as the pname:buffer parameter to @@ -4930,7 +4945,7 @@ reconstruction operations operate on the same (_u~plane~_, _v~plane~_) or endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] [[resources-image-views-compatibility]] -.Image type and image view type compatibility requirements +.Image Type and Image View Type Compatibility Requirements [cols="35%,50%",options="header"] |==== | Image View Type | Compatible Image Types diff --git a/chapters/samplers.adoc b/chapters/samplers.adoc index 8fb81b304..c0a4428f5 100644 --- a/chapters/samplers.adoc +++ b/chapters/samplers.adoc @@ -127,7 +127,7 @@ requirements: ** The functions must: not use offsets. [NOTE] -.Mapping of OpenGL to Vulkan filter modes +.Mapping of OpenGL to Vulkan Filter Modes ==== pname:magFilter values of ename:VK_FILTER_NEAREST and ename:VK_FILTER_LINEAR directly correspond to code:GL_NEAREST and code:GL_LINEAR magnification diff --git a/chapters/shaders.adoc b/chapters/shaders.adoc index 86da4fcec..67525dc27 100644 --- a/chapters/shaders.adoc +++ b/chapters/shaders.adoc @@ -316,6 +316,17 @@ ifdef::VK_VERSION_1_1,VK_EXT_subgroup_size_control[] ename:VK_SHADER_CREATE_REQUIRE_FULL_SUBGROUPS_BIT_EXT, the <> feature must: be enabled +ifdef::VK_EXT_device_generated_commands[] + * [[VUID-VkShaderCreateInfoEXT-flags-11005]] + If pname:flags includes + ename:VK_SHADER_CREATE_INDIRECT_BINDABLE_BIT_EXT, then the + <> + feature must: be enabled + * [[VUID-VkShaderCreateInfoEXT-flags-11006]] + If pname:flags includes + ename:VK_SHADER_CREATE_INDIRECT_BINDABLE_BIT_EXT, then the identified + entry point must: not specify code:Xfb execution mode +endif::VK_EXT_device_generated_commands[] * [[VUID-VkShaderCreateInfoEXT-flags-08992]] If pname:flags includes ename:VK_SHADER_CREATE_REQUIRE_FULL_SUBGROUPS_BIT_EXT, pname:stage must: @@ -598,6 +609,10 @@ ifdef::VK_EXT_fragment_density_map[] that a fragment shader can: be used with a fragment density map attachment. endif::VK_EXT_fragment_density_map[] +ifdef::VK_EXT_device_generated_commands[] + * ename:VK_SHADER_CREATE_INDIRECT_BINDABLE_BIT_EXT specifies that the + shader can: be used in combination with <>. +endif::VK_EXT_device_generated_commands[] -- ifdef::VK_KHR_fragment_shading_rate,VK_EXT_fragment_density_map[] @@ -908,9 +923,14 @@ endif::VK_EXT_mesh_shader,VK_NV_mesh_shader[] * flink:vkCmdSetVertexInputEXT * flink:vkCmdSetPrimitiveTopology + * flink:vkCmdSetPrimitiveRestartEnable + +If a shader is bound to the ename:VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT +stage, the following command must: have been called in the command buffer +prior to drawing: + * flink:vkCmdSetPatchControlPointsEXT, if pname:primitiveTopology is ename:VK_PRIMITIVE_TOPOLOGY_PATCH_LIST - * flink:vkCmdSetPrimitiveRestartEnable If a shader is bound to the ename:VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT stage, the following @@ -1116,6 +1136,15 @@ prior to drawing: ename:VK_TRUE endif::VK_NV_clip_space_w_scaling[] +ifdef::VK_EXT_depth_clamp_control[] +If the <> and <> feature are enabled on the device, and +pname:depthClampEnable is ename:VK_TRUE, the following command must: have +been called in the command buffer prior to drawing: + + * flink:vkCmdSetDepthClampRangeEXT +endif::VK_EXT_depth_clamp_control[] + ifdef::VK_NV_viewport_swizzle[] If the `apiext:VK_NV_viewport_swizzle` extension is enabled on the device, the following command must: have been called in the command buffer prior to @@ -3611,7 +3640,7 @@ To enable applications to detect when previously retrieved data is incompatible with the device, the initial bytes written to pname:pData must: be a header consisting of the following members: -.Layout for validation cache header version ename:VK_VALIDATION_CACHE_HEADER_VERSION_ONE_EXT +.Layout for Validation Cache Header Version ename:VK_VALIDATION_CACHE_HEADER_VERSION_ONE_EXT [width="85%",cols="8%,21%,71%",options="header"] |==== | Offset | Size | Meaning diff --git a/chapters/synchronization.adoc b/chapters/synchronization.adoc index 8cf5a4639..43fbc9193 100644 --- a/chapters/synchronization.adoc +++ b/chapters/synchronization.adoc @@ -347,6 +347,10 @@ ifdef::VK_NV_device_generated_commands[] This stage also includes reading commands written by flink:vkCmdPreprocessGeneratedCommandsNV. endif::VK_NV_device_generated_commands[] +ifdef::VK_EXT_device_generated_commands[] + This stage also includes reading commands written by + flink:vkCmdPreprocessGeneratedCommandsEXT. +endif::VK_EXT_device_generated_commands[] ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] * ename:VK_PIPELINE_STAGE_2_TASK_SHADER_BIT_EXT specifies the task shader stage. @@ -447,6 +451,11 @@ ifdef::VK_NV_device_generated_commands[] of the pipeline where device-side generation of commands via flink:vkCmdPreprocessGeneratedCommandsNV is handled. endif::VK_NV_device_generated_commands[] +ifdef::VK_EXT_device_generated_commands[] + * ename:VK_PIPELINE_STAGE_2_COMMAND_PREPROCESS_BIT_EXT specifies the stage + of the pipeline where device-side generation of commands via + flink:vkCmdPreprocessGeneratedCommandsEXT is handled. +endif::VK_EXT_device_generated_commands[] ifdef::VK_KHR_fragment_shading_rate,VK_NV_shading_rate_image[] * ename:VK_PIPELINE_STAGE_2_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR specifies the stage of the pipeline where the @@ -558,6 +567,10 @@ ifdef::VK_NV_device_generated_commands[] This stage also includes reading commands written by flink:vkCmdExecuteGeneratedCommandsNV. endif::VK_NV_device_generated_commands[] +ifdef::VK_EXT_device_generated_commands[] + This stage also includes reading commands written by + flink:vkCmdExecuteGeneratedCommandsEXT. +endif::VK_EXT_device_generated_commands[] ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] * ename:VK_PIPELINE_STAGE_TASK_SHADER_BIT_EXT specifies the task shader stage. @@ -684,6 +697,11 @@ ifdef::VK_NV_device_generated_commands[] the pipeline where device-side preprocessing for generated commands via flink:vkCmdPreprocessGeneratedCommandsNV is handled. endif::VK_NV_device_generated_commands[] +ifdef::VK_EXT_device_generated_commands[] + * ename:VK_PIPELINE_STAGE_COMMAND_PREPROCESS_BIT_EXT specifies the stage + of the pipeline where device-side preprocessing for generated commands + via flink:vkCmdPreprocessGeneratedCommandsEXT is handled. +endif::VK_EXT_device_generated_commands[] ifdef::VK_KHR_fragment_shading_rate,VK_NV_shading_rate_image[] * ename:VK_PIPELINE_STAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR specifies the stage of the pipeline where the @@ -758,7 +776,7 @@ For further details on queue capabilities see and <>. [[synchronization-pipeline-stages-supported]] -.Supported pipeline stage flags +.Supported Pipeline Stage Flags [cols="70%,30%",options="header"] |==== |Pipeline stage flag | Required queue capability flag @@ -861,12 +879,12 @@ guaranteed: include::{generated}/sync/pipelineOrders/host.adoc[] -ifdef::VK_NV_device_generated_commands[] +ifdef::VK_NV_device_generated_commands,VK_EXT_device_generated_commands[] For the command preprocessing pipeline, the following stages occur in this order: include::{generated}/sync/pipelineOrders/command_preprocessing.adoc[] -endif::VK_NV_device_generated_commands[] +endif::VK_NV_device_generated_commands,VK_EXT_device_generated_commands[] ifdef::VK_NV_ray_tracing,VK_KHR_acceleration_structure[] For acceleration structure build operations, only one pipeline stage occurs, @@ -1121,6 +1139,16 @@ ifdef::VK_NV_device_generated_commands[] Such access occurs in the ename:VK_PIPELINE_STAGE_2_COMMAND_PREPROCESS_BIT_NV pipeline stage. endif::VK_NV_device_generated_commands[] +ifdef::VK_EXT_device_generated_commands[] + * ename:VK_ACCESS_2_COMMAND_PREPROCESS_READ_BIT_EXT specifies reads from + buffer inputs to flink:vkCmdPreprocessGeneratedCommandsEXT. + Such access occurs in the + ename:VK_PIPELINE_STAGE_2_COMMAND_PREPROCESS_BIT_EXT pipeline stage. + * ename:VK_ACCESS_2_COMMAND_PREPROCESS_WRITE_BIT_EXT specifies writes to + the target command buffer preprocess outputs. + Such access occurs in the + ename:VK_PIPELINE_STAGE_2_COMMAND_PREPROCESS_BIT_EXT pipeline stage. +endif::VK_EXT_device_generated_commands[] ifdef::VK_EXT_blend_operation_advanced[] * ename:VK_ACCESS_2_COLOR_ATTACHMENT_READ_NONCOHERENT_BIT_EXT specifies read access to <>, including @@ -1451,6 +1479,17 @@ ifdef::VK_NV_device_generated_commands[] Such access occurs in the ename:VK_PIPELINE_STAGE_COMMAND_PREPROCESS_BIT_NV pipeline stage. endif::VK_NV_device_generated_commands[] +ifdef::VK_EXT_device_generated_commands[] + * ename:VK_ACCESS_COMMAND_PREPROCESS_READ_BIT_EXT specifies reads from + buffer inputs to flink:vkCmdPreprocessGeneratedCommandsEXT. + Such access occurs in the + ename:VK_PIPELINE_STAGE_COMMAND_PREPROCESS_BIT_EXT pipeline stage. + * ename:VK_ACCESS_COMMAND_PREPROCESS_WRITE_BIT_EXT specifies writes to the + target command buffer preprocess outputs in + flink:vkCmdPreprocessGeneratedCommandsEXT. + Such access occurs in the + ename:VK_PIPELINE_STAGE_COMMAND_PREPROCESS_BIT_EXT pipeline stage. +endif::VK_EXT_device_generated_commands[] ifdef::VK_EXT_blend_operation_advanced[] * ename:VK_ACCESS_COLOR_ATTACHMENT_READ_NONCOHERENT_BIT_EXT specifies read access to <>, including @@ -1519,7 +1558,7 @@ The following table lists, for each access flag, which pipeline stages can: perform that type of access. [[synchronization-access-types-supported]] -.Supported access types +.Supported Access Types [cols="50,50",options="header"] |==== |Access flag | Supported pipeline stages @@ -4244,9 +4283,46 @@ signaled with respect to the counter value waited on as specified in slink:VkTimelineSemaphoreSubmitInfo. endif::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] -The first synchronization scope includes all semaphore signal operations -that operate on semaphores waited on in the same batch, and that -happen-before the wait completes. +The first <> +includes one <> for each semaphore waited on by this batch. +The specific signal operation waited on for each semaphore must: meet the +following criteria: + + * {empty} +ifdef::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] + for binary semaphores, +endif::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] + the signal operation is either earlier in + <> on the same queue, + or is submitted by a command whose host operation happens-before this + batch is submitted on the host + * {empty} +ifdef::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] + for binary semaphores, +endif::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] + no wait operation exists that happens-after the signal operation and + happens-before this wait operation + * the signal operation is not guaranteed to happen-after the semaphore + wait operation in this batch +ifdef::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] + * for timeline semaphores, the signal value is greater than or equal to + the wait value +endif::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] + +If multiple semaphore signal operations meet these criteria, any of those +operations may: be included in the first +<>. +When waiting on a binary semaphore, applications must: ensure that exactly +one semaphore signal operation meets these criteria. +ifdef::VK_KHR_timelines_semaphore[] +When waiting on a timeline semaphore, the semaphore wait operation will not +complete until at least one semaphore signal operation meets these criteria. +Multiple timeline semaphore signal operations can: meet these criteria, but +applications must: ensure that other synchronization dependencies exist to +prevent any data races. +endif::VK_KHR_timelines_semaphore[] + The second <> includes every command submitted in the same batch. diff --git a/chapters/textures.adoc b/chapters/textures.adoc index c26d6e448..8b7fadb80 100644 --- a/chapters/textures.adoc +++ b/chapters/textures.adoc @@ -1734,7 +1734,7 @@ selections for [eq]#s~c~#, [eq]#t~c~#, [eq]#r~c~#, and the selection of derivatives, are determined by the major axis direction as specified in the following two tables. -.Cube map face and coordinate selection +.Cube Map Face and Coordinate Selection [width="75%",frame="all",options="header"] |==== | Major Axis Direction | Layer Number | Cube Map Face | [eq]#s~c~# | [eq]#t~c~# | [eq]#r~c~# @@ -1747,7 +1747,7 @@ following two tables. |==== -.Cube map derivative selection +.Cube Map Derivative Selection [width="75%",frame="all",options="header"] |==== | Major Axis Direction | [eq]#{partial}s~c~ / {partial}x# | [eq]#{partial}s~c~ / {partial}y# | [eq]#{partial}t~c~ / {partial}x# | [eq]#{partial}t~c~ / {partial}y# | [eq]#{partial}r~c~ / {partial}x# | [eq]#{partial}r~c~ / {partial}y# @@ -1784,6 +1784,7 @@ following two tables. |==== +[[textures-cube-map-coordinate-transform]] === Cube Map Coordinate Transformation [latexmath] @@ -1799,16 +1800,19 @@ t_{\textit{face}} & = === Cube Map Derivative Transformation +The partial derivatives of the <> can be computed as: + [latexmath] ++++ \begin{aligned} \frac{\partial{s_{\textit{face}}}}{\partial{x}} &= \frac{\partial}{\partial{x}} \left ( \frac{1}{2} \times \frac{s_{c}}{|r_{c}|} + \frac{1}{2}\right ) \\ -\frac{\partial{s_{\textit{face}}}}{\partial{x}} &= + &= \frac{1}{2} \times \frac{\partial}{\partial{x}} \left ( \frac{s_{c}}{|r_{c}|} \right ) \\ -\frac{\partial{s_{\textit{face}}}}{\partial{x}} &= + &= \frac{1}{2} \times \left ( \frac{ @@ -1819,6 +1823,8 @@ t_{\textit{face}} & = \end{aligned} ++++ +The other derivatives are simplified similarly, resulting in + [latexmath] ++++ \begin{aligned} @@ -3070,7 +3076,7 @@ groups used to evaluate the footprint. Each bit in the returned footprint mask corresponds to an aligned block of texels whose size is given by the following table: -.Texel footprint granularity values +.Texel Footprint Granularity Values [width="50%",options="header"] |==== | code:Granularity | code:Dim = 2D | code:Dim = 3D diff --git a/chapters/video/h264_parameter_sets.adoc b/chapters/video/h264_parameter_sets.adoc index 5011f78aa..f6fb700c5 100644 --- a/chapters/video/h264_parameter_sets.adoc +++ b/chapters/video/h264_parameter_sets.adoc @@ -38,6 +38,15 @@ interpreted as follows: as follows: ** code:reserved1 is used only for padding purposes and is otherwise ignored; + ** code:flags.color_description_present_flag is interpreted as the value + of code:colour_description_present_flag, as defined in section E.2.1 of + the <>; ++ +[NOTE] +==== +The name of code:colour_description_present_flag was misspelled in the Video +Std header. +==== ** if code:flags.nal_hrd_parameters_present_flag or code:flags.vcl_hrd_parameters_present_flag is set, then the code:StdVideoH264HrdParameters structure pointed to by diff --git a/config/CI/codespell-allowed b/config/CI/codespell-allowed index 81c63f100..010d72f07 100644 --- a/config/CI/codespell-allowed +++ b/config/CI/codespell-allowed @@ -21,6 +21,7 @@ tesselation # Proper names alis benj +blok calle ser labour diff --git a/images/proposals/VK_EXT_device_generated_commands_overview.svg b/images/proposals/VK_EXT_device_generated_commands_overview.svg new file mode 100644 index 000000000..ef757a063 --- /dev/null +++ b/images/proposals/VK_EXT_device_generated_commands_overview.svg @@ -0,0 +1,57 @@ + + + + Driver computes worse-case pipeline state diff​information, within Indirect Exec Set. + + Indirect Execution Set (like SBT) + + Pipeline(s)/Shader(s) + + + + u32 Set Index + + + IndirectBuffer + + State & DrawIndirect... + + + + + one operation per state + + + IndirectCommandsLayout + + + + Indirect Command Generation + + + + CommandBuffer + + + PreprocessBuffer + + Device cmds... + (preprocess buffer usage is not mandatory,​hardware may interpret indirect buffers directly) + + + + PreprocessBuffer sized for​worst-case state configuration​per draw (via maxSequenceCount,​IndirectPipelineSet and​IndirectCommandsLayout) + + + + + + + + + + + + diff --git a/proposals/VK_EXT_depth_clamp_control.adoc b/proposals/VK_EXT_depth_clamp_control.adoc new file mode 100644 index 000000000..ad90e4b82 --- /dev/null +++ b/proposals/VK_EXT_depth_clamp_control.adoc @@ -0,0 +1,155 @@ +// Copyright 2022-2024 The Khronos Group Inc. +// +// SPDX-License-Identifier: CC-BY-4.0 + += VK_EXT_depth_clamp_control +:toc: left +:refpage: https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/ +:sectnums: + +This document details API design ideas for the `VK_EXT_depth_clamp_control` +extension, which provides functionality for finer control over the behavior +of depth clamping when rendering. + +== Problem Statement + +API layering efforts regularly need to emulate integer depth formats using +floating-point formats such as `VK_FORMAT_D32_SFLOAT_S8_UINT`. +This works well when emulating normalized fixed-point depth format such as +`VK_FORMAT_D24_UNORM_S8_UINT`, however this creates issues when the integer +format is not normalized. + +In a hypothetical `VK_FORMAT_D24_UINT_S8_UINT` format the depth values are +truncated rather than normalized. +Attempting to emulate this format by normalizing the depth values using a +2^n-1 divisor results in floating-point rounding errors compared to a true +unnormalized format. + +Instead of normalizing the depth values the +`VK_EXT_unrestricted_depth_range` extension can be used in combination with +a `VK_FORMAT_D32_SFLOAT_S8_UINT` depth buffer to allow for a [0, 2^n-1] +depth range without requiring any normalization. +The lack of truncation does not present an issue as the truncation can +simply be applied when reading back depth values. + +The unrestricted depth range does present a new issue, because a depth clamp +on the final depth value as specified in `VK_EXT_depth_clamp_zero_one` is +still required to prevent depth values from exceeding the 24-bit integer +range of the emulated depth buffer. +This means a clamp of [0, 2^n-1] needs to be applied on the final depth +value independently of the viewport depth range. + +== Solution Space + + . Normalize depth values using a power-of-two divisor to avoid rounding + errors + + * The application could attempt to normalize depth values using 2^n instead + of 2^n-1. + While this does solve the rounding error without the need for + `VK_EXT_unrestricted_depth_range`, this does not solve the depth clamping + issue as a clamp of [0, 2^n-1 / 2^n] would now be required instead to + ensure the final depth value does not exceed the 24-bit integer range. + + . Solve from the application side with shader-side clamping using + `gl_FragDepth` + + * Another option from the application side is to clamp `gl_FragDepth` + manually in the shader. + This is problematic as it can lead to reduced performance as this + disables early-z optimizations. + It is also breaks compatibility if the application force-enabled early-z. + + . Define a new fixed-point depth format `VK_FORMAT_D24_UINT_S8_UINT` that + is not normalized. + + * This is problematic because the normalization as part of + `VK_FORMAT_D24_UNORM_S8_UINT` is often fixed in hardware with no ability + to turn it off. + It is also unlikely such a format would ever be natively supported in + hardware. + + . Add a method of specifying the depth clamp independently + + * A Vulkan extension could be made to provide functionality to specify the + depth clamp range separately from the viewport transform depth range. + +== Proposal + +Add a new enum, `VkDepthClampModeEXT` that allows switching between the +default per-viewport depth clamp range and a single user-defined range for +all viewports. + +Add a new function, `vkCmdSetDepthClampRangeEXT` that uses +`VkDepthClampModeEXT` and `VkDepthClampRangeEXT` to handle dynamically +changing the depth clamp mode and range for all viewports. + +Add a new structure, `VkPipelineViewportDepthClampControlCreateInfoEXT`, +that can be added to the `pNext` chain of a pipeline's +`VkPipelineViewportStateCreateInfo` that allows setting the depth clamp mode +and range of all viewports in the pipeline. + +It will also have a feature flag to allow implementations to indicate +whether they support setting the depth clamp mode to +VK_DEPTH_CLAMP_MODE_USER_DEFINED_EXT. + +```c +typedef enum VkDepthClampModeEXT { + VK_DEPTH_CLAMP_MODE_VIEWPORT_RANGE_EXT = 0, + VK_DEPTH_CLAMP_MODE_USER_DEFINED_RANGE_EXT = 1, + VK_DEPTH_CLAMP_MODE_MAX_ENUM_EXT = 0x7FFFFFFF +} VkDepthClampModeEXT; +``` + +```c +typedef struct VkDepthClampRangeEXT { + float minDepthClamp; + float maxDepthClamp; +} VkDepthClampRangeEXT; +``` + +```c +VKAPI_ATTR void VKAPI_CALL vkCmdSetDepthClampRangeEXT( + VkCommandBuffer commandBuffer, + VkDepthClampModeEXT depthClampMode, + const VkDepthClampRangeEXT* pDepthClampRange); +``` + +```c +// Part of the pNext chain of a VkPipelineViewportStateCreateInfo. +typedef struct VkPipelineViewportDepthClampControlCreateInfoEXT { + VkStructureType sType; + const void* pNext; + VkDepthClampModeEXT depthClampMode; + const VkDepthClampRangeEXT* pDepthClampRange; +} VkPipelineViewportDepthClampControlCreateInfoEXT; +``` + +== Issues + +1) Should the depth clamp range be a per-viewport parameter? + +*RESOLVED*: No. +Because the depth clamp range was previously defined to be equal to the +viewport depth range, conformant runtimes are already handling the depth +clamp range as a per-viewport parameter. +However since a per-viewport parameter is not necessary to address the +original issue and because of complexities from interactions with +multi-viewport support, this is left to a future extensions if a use case +arises. + +2) Should this pipeline state be dynamic? + +*RESOLVED*: Yes. +Since the viewport depth range can already be a dynamic state conformant +runtimes are already able to handle the depth clamp range as a dynamic +state. + +3) Can the depth clamp range be ignored when depth clamping is disabled? + +*RESOLVED*: Yes. +This extension overrides the clamping range used only when depth clamping is +enabled. +The alternative would be highly unintuitive. +As a consequence the apiext:VK_EXT_depth_clip_enable extension is required +if depth clipping is desired in combination with this extension. diff --git a/proposals/VK_EXT_device_generated_commands.adoc b/proposals/VK_EXT_device_generated_commands.adoc new file mode 100644 index 000000000..702836fc5 --- /dev/null +++ b/proposals/VK_EXT_device_generated_commands.adoc @@ -0,0 +1,1088 @@ +// Copyright 2021-2024 The Khronos Group Inc. +// +// SPDX-License-Identifier: CC-BY-4.0 + += VK_EXT_device_generated_commands +:toc: left +:refpage: https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/ +:sectnums: + +This document details API design for indirect execution of device generated commands, improving performance by eliminating unnecessary host and device work. + +== Problem Statement + +Device-driven rendering is increasingly used to manage large and complex environments. Scene management in particular is well suited for execution on device and is responsible for: + +- Traversing the scene +- Managing LoD +- Performing various culling algorithms +- Generating work to render the visible result + +Graphics APIs differ in their expressiveness but most have limitations for device-driven scene management that result in: + +- Unnecessary state changes +- Wasted memory for worst-case allocations for intermediate results +- Round-tripping through memory instead of staying on chip + +This proposal focuses on reducing unnecessary state changes. For example, enabling a device to use compute shaders to launch other compute shaders rather than requiring explicit dispatch commands to be recorded. + +== Solution Space + +There are several approaches to reduce unnecessary state changes. Here are some potential solutions: + +1. No API changes + - Work is done on the host to determine the set of shaders that are potentially visible. This might be a simpler problem than object/triangle culling. + - Potentially duplicates work done by the device. +2. Work Graphs + - D3D12 supports Work Graphs, which are a more powerful method of moving work generation to the GPU + - Standardization and cross-vendor support of this advanced functionality takes a long time to achieve ecosystem adoption +3. Predicated/Conditional Rendering + - Commands are optionally executed depending on a condition evaluated on the device timeline. + - Exposed in D3D12 as `ID3D12GraphicsCommandList::SetPredication` + - Host encoding overhead of binding the shaders still exists. +4. Indirect Command Buffers (Host) + - Similar to secondary command buffers but with different restrictions and inheritance rules. + - Create multiple indirect command buffers (e.g. one per pipeline). + - Indirect execution of multiple indirect command buffers. + - May require patching/fast updating of objects referenced by the indirect command buffer. +5. Indirect Command Buffers (Device) + - Created in a compute shader. + - Can be re-created every frame avoiding multiple execution complexity or patching. + - Requires extensive shading language support. +6. Enhanced Indirect + - Add support to execute multiple types of operations in a sequence. + - Limited state changes and operations compared to what is available for primary or secondary command buffers. + - Should be able to represent most work in a "pass" (e.g. drawing shadows or opaque geometry) + +Many graphics APIs have more expressive indirect capabilities. This proposal pursues that approach to address both the problem statement and provide an emulation target. + +=== Goals + +These are the primary goals for the proposal: + +- Efficient implementation for many-draws and many-dispatches per set of shaders. +- Device-side binding of shaders. +- Changing shaders for indirect dispatch during application lifetime. +- Emulation of D3D12 indirect execution. +- Emulation of D3D12 work graphs. +- Transition existing uses of `NV_device_generated_commands` and `NV_device_generated_commands_compute`. +- Single framework for all execution-based indirect commands. Other indirect operations (e.g. building acceleration structures) have very different setup and argument management. + +=== Current implementations + +==== Vulkan + +Indirect execution in Vulkan typically support only a single type of command: + +- `vkCmdDrawIndirect` +- `vkCmdDrawIndexedIndirect` +- `vkCmdDispatchIndirect` +- `vkCmdDrawIndirectCount` (Vulkan 1.2) +- `vkCmdDrawIndexedIndirectCount` (Vulkan 1.2) +- `vkCmdDrawMeshTasksIndirectNV` (VK_NV_mesh_shader) +- `vkCmdDrawMeshTasksIndirectCountNV` (VK_NV_mesh_shader) +- `vkCmdBuildAccelerationStructuresIndirectKHR` (VK_KHR_acceleration_structure) +- `vkCmdTraceRaysIndirectKHR` (VK_KHR_ray_tracing_pipeline) +- `vkCmdDrawMeshTasksIndirectEXT` (VK_EXT_mesh_shader) +- `vkCmdDrawMeshTasksIndirectCountEXT` (VK_EXT_mesh_shader) + +The `VK_NV_device_generated_commands` extension enables a more expressive model supporting multiple commands in a sequence that may change the following state: + +- Shaders +- Primitive winding +- Index and vertex buffers +- Push constants + +and perform the following operations: + +- Indexed and non-indexed draws +- Mesh tasks + +==== D3D12 + +D3D12 indirect execution is similar in expressivity to both `VK_NV_device_generated_commands` and `VK_NV_device_generated_commands_compute` but offers no mechanism for changing graphics shaders or pipelines. It is currently possible to emulate D3D12 behavior on top of `VK_NV_device_generated_commands` and other base Vulkan functionality so it is important to not lose any features required for emulation with this proposal. + +D3D12 work graphs are more powerful in certain aspects than indirect execution but are not yet officially supported in Vulkan. + +==== Metal + +Metal is similar in expressivity to `VK_NV_device_generated_commands` and supports full pipeline changes as well as the equivalent of binding descriptor sets. + +Indirect buffer layout is opaque and can be encoded on host through the API or on device using a compute shader. For example: + +```c +​struct arguments { command_buffer cmd_buffer; };​ +​ +kernel void producer(device arguments& args, ushort cmd_idx [[thread_position_in_grid]])​ +{​ + render_command cmd(args.cmd_buffer, cmd_idx);​ + cmd.set_render_pipeline_state(...);​ + cmd.set_vertex_buffer(...);​ + cmd.draw_primitives(...);​ +} +``` + +=== Command representation + +Supporting multiple commands in an indirect buffer can either be done with a homogeneous structure where the layout is fixed and the same pattern of operations is executed. Another alternative is a heterogeneous structure where there is no restriction on command ordering. For heterogeneous layout, the size of the arguments for each command may also vary. + +This proposal uses a homogeneous structure which matches D3D12, Metal, and `VK_NV_device_generated_commands`. This restricted model simplifies construction and interpretation of the data while also introducing an optimization challenge. + +Consider a sequence of `Bind Shaders/Draw` that binds the same shaders multiple times. If the command buffer is constructed on the host, draw calls with the same shaders can be grouped together creating a heterogeneous structure. There are several options to with a homogeneous structure: + +1. On-device optimization. The implementation could detect/remove duplicates during pre-processing or execution. This may be difficult or impractical for a device to implement. +2. Multi-level indirect. One of the indirect operations could be another indirect execution. For example, a two-level solution could be used with low-frequency operations in the first indirect buffer and high-frequency operations in the second indirect buffer. +3. IndirectCount commands. Vulkan has pre-existing indirect commands that execute multiple operations with a device-specified count. This is equivalent to a heavily constrained multi-level indirect solution. + +This proposal does not expect significant on-device optimization and uses IndirectCount commands which are capable of representing many common application scenarios. + +== Proposal + +This proposal targets Vulkan 1.3 building on functionality from `NV_device_generated_commands` to address the problem statement and also provide an emulation target for other APIs. + +Indirect buffers contain work elements (sequences) of uniform structure. The memory layout of a sequence is described by an Indirect Commands Layout that specifies a fixed number of command buffer operations: + +- Shaders +- Push constants +- Index and vertex buffers +- Draws and dispatches +- Multi-draws with device-specified count +- Trace rays + +The extension provides a common framework for all existing and future indirect commands. An implementation does not need to support every command (see the Features section for more detail). + +Sequences of compute commands that change shaders must refer to elements of an Indirect Execution Set, a table that references multiple shaders of similar state. + +Implementations may also require a preprocess buffer to translate to a device-specific format. With Multi-draw commands being available, optimization of the preprocess buffer to remove duplicates is not expected. + +image::{images}/proposals/VK_EXT_device_generated_commands_overview.svg[] + +The generation of device generated commands uses the following principle steps: + +- Define via `VkIndirectCommandsLayoutEXT` the sequence of commands which can be generated. +- Optionally create and update an `VkIndirectExecutionSetEXT` to support changing shaders. +- Retrieve device addresses and handles for objects stored in indirect buffers. +- Fill a `VkBuffer` with the content that matches the indirect command layout. +- Create a preprocess `VkBuffer` that satisfies the allocation information from `vkGetGeneratedCommandsMemoryRequirementsEXT`. +- Optionally preprocess the input data using `vkCmdPreprocessGeneratedCommandsEXT` in a separate action. +- Generate and execute the actual commands via `vkCmdExecuteGeneratedCommandsEXT` passing all required data. + +`vkCmdPreprocessGeneratedCommandsEXT` executes in a separate logical pipeline from either graphics or compute. When preprocessing commands in a separate step they must be explicitly synchronized against the command execution. When not preprocessing, the preprocessing is automatically synchronized against the command execution. + +=== Key differences with `VK_NV_device_generated_commands` + +- Common indirect commands under one unified framework (graphics, compute, and ray tracing) +- Incremental update of shaders available for use +- Adds IndirectCount commands +- Adds compute dispatch support +- Single-interleaved stream +- VK_EXT_shader_object support + +=== Indirect Execution Sets +Indirect buffers that bind shaders reference shaders (pipelines or shader objects) managed by a collection represented by: + +```c +VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkIndirectExecutionSetEXT) +``` + +Indirect execution sets group both pipelines with the same `VkPipelineLayout` and shader stages with matching per-stage descriptor layouts. + +Indirect execution sets contain a maximum number of N execution slots that can be updated when not referenced by indirect buffers currently in flight. Drivers should ensure that updating a set is a pretty cheap operation as it is expected to be modified as application content changes. + +Modifications to an indirect execution set may change the sizing requirements of the preprocess buffer. Applications must call `vkGetGeneratedCommandsMemoryRequirementsEXT` and update the preprocess buffer if needed when modifications are complete. + +==== Creation and Deletion +Indirect execution sets are created by: + +```c +VKAPI_ATTR VkResult VKAPI_CALL vkCreateIndirectExecutionSetEXT( + VkDevice device, + const VkIndirectExecutionSetCreateInfoEXT* pCreateInfo, + const VkAllocationCallbacks* pAllocator, + VkIndirectExecutionSetEXT* pIndirectExecutionSet); +``` + +- `device` is the logical device that creates the indirect execution set. +- `pCreateInfo` is a pointer to a `VkIndirectExecutionSetCreateInfoEXT` structure containing parameters affecting creation of the indirect execution set. +- `pAllocator` controls host memory allocation as described in the Memory Allocation chapter. +- `pIndirectExecutionSet` is a pointer to a `VkIndirectExecutionSetEXT` handle in which the resulting indirect execution set is returned. + + +The `VkIndirectExecutionSetCreateInfoEXT` structure is defined as: + +```c +typedef struct VkIndirectExecutionSetCreateInfoEXT { + VkStructureType sType; + const void* pNext; + VkIndirectExecutionSetInfoTypeEXT type; + VkIndirectExecutionSetInfoEXT info; +} VkIndirectExecutionSetCreateInfoEXT; +``` + +- `flags` must not be `0`. +- `info` is a `VkIndirectExecutionSetInfoEXT` union containing layout information for the indirect execution set. + +The VkIndirectExecutionSetInfoTypeEXT enum is defined as: + +```c +typedef enum VkIndirectExecutionSetInfoTypeEXT +{ + VK_INDIRECT_EXECUTION_SET_INFO_TYPE_PIPELINES_EXT = 0x00000001, + VK_INDIRECT_EXECUTION_SET_INFO_TYPE_SHADER_OBJECTS_EXT = 0x00000002, +} VkIndirectExecutionSetInfoTypeEXT; +``` + +- `VK_INDIRECT_EXECUTION_SET_INFO_TYPE_PIPELINES_EXT` indicates that the `VkIndirectExecutionSetEXT` contains `VkPipeline` objects. +- `VK_INDIRECT_EXECUTION_SET_INFO_TYPE_SHADER_OBJECTS_EXT` indicates that the `VkIndirectExecutionSetEXT` contains `VkShaderEXT` objects. + +The `VkIndirectExecutionSetInfoEXT` union is defined as: + +```c +typedef union VkIndirectExecutionSetInfoEXT { + const VkIndirectExecutionSetPipelineInfoEXT *pPipelineInfo; + const VkIndirectExecutionSetShaderInfoEXT *pShaderInfo; +} +``` + +- `pPipelineInfo` is a pointer to a `VkIndirectExecutionSetPipelineInfoEXT` struct containing pipeline layout information for the indirect execution set. +- `pShaderInfo` is a pointer to a `VkIndirectExecutionSetShaderInfoEXT` struct containing shader object layout information for the indirect execution set. + + +The `VkIndirectExecutionSetPipelineInfoEXT` structure is defined as: + +```c +typedef struct VkIndirectExecutionSetPipelineInfoEXT { + VkStructureType sType; + const void* pNext; + VkPipeline initialPipeline; + uint32_t maxPipelineCount; +} VkIndirectExecutionSetPipelineInfoEXT; +``` + +- `initialPipeline` is the pipeline to validate other pipelines in the set against. Its state will be used for validation even if it is removed from the set. + This pipeline will be automatically added to the set at index `0`. + The bind point must be supported by `VkPhysicalDeviceDeviceGeneratedCommandsPropertiesEXT::supportedIndirectCommandsShaderStagesPipelineBinding`. +- `maxPipelineCount` is the maximum number of pipelines stored in the set. + +The `VkIndirectExecutionSetShaderInfoEXT` structure is defined as: + +```c +typedef struct VkIndirectExecutionSetShaderInfoEXT { + VkStructureType sType; + const void* pNext; + uint32_t shaderCount; + const VkShaderEXT *pInitialShaders; + const VkIndirectExecutionSetShaderLayoutInfoEXT *pSetLayoutInfos; + uint32_t maxShaderCount; + uint32_t pushConstantRangeCount; + const VkPushConstantRange *pPushConstantRanges; +} VkIndirectExecutionSetShaderInfoEXT; +``` + +- `shaderCount` is the number of members in the `pInitialShaders` and `pSetLayoutInfos` arrays. +- `pInitialShaders` is a pointer to an array containing a `VkShaderEXT` object for each shader stage that will be used in the set. + These shaders will be used to validate other shaders in the set against. Their state will be used for validation even if they are removed from the set. + These shaders will be automatically added to the set beginning at index `0`. + The stages of the shaders must be supported by `VkPhysicalDeviceDeviceGeneratedCommandsPropertiesEXT::supportedIndirectCommandsShaderStagesShaderBinding`. +- `pSetLayoutInfos` is a pointer to array containing `VkIndirectExecutionSetShaderLayoutInfoEXT` infos used by each corresponding `pInitialShaders` shader stage in the set. +- `maxShaderCount` is the maximum number of corresponding shader objects stored in the set. +- `pushConstantRangeCount` is the number of members in the `pPushConstantRanges` array. +- `pPushConstantRanges` is a pointer to the array of `VkPushConstantRange` ranges used by all shaders in the set. + + +The `VkIndirectExecutionSetShaderLayoutInfoEXT` structure is defined as: + +```c +typedef struct VkIndirectExecutionSetShaderLayoutInfoEXT { + uint32_t setLayoutCount; + const VkDescriptorSetLayout *pSetLayouts; +} VkIndirectExecutionSetShaderLayoutInfoEXT; +``` + +- `setLayoutCount` is the number of `VkDescriptorSetLayout` in the `pSetLayouts` array. +- `pSetLayouts` is a pointer to an array containing `VkDescriptorSetLayout` objects used by a given shader stage. + + +Indirect execution sets are destroyed by: + +```c +VKAPI_ATTR void VKAPI_CALL vkDestroyIndirectExecutionSetEXT( + VkDevice device, + VkIndirectExecutionSetEXT indirectExecutionSet, + const VkAllocationCallbacks* pAllocator); +``` + +- `device` is the logical device that owns the indirect execution set. +- `indirectExecutionSet` is the indirect execution set to destroy. +- `pAllocator` controls host memory allocation as described in the Memory Allocation chapter. + +==== Updates +Once created, execution slots in indirect execution sets can be updated with one of the following functions depending on how it was created: + +```c +VKAPI_ATTR void VKAPI_CALL vkUpdateIndirectExecutionSetPipelineEXT( + VkDevice device, + VkIndirectExecutionSetEXT indirectExecutionSet, + uint32_t executionSetWriteCount, + const VkWriteIndirectExecutionSetPipelineEXT* pExecutionSetWrites); +``` + +- `device` is the logical device that owns the indirect execution set. +- `indirectExecutionSet` is the indirect execution set to update. +- `executionSetWriteCount` is the number of elements in `pExecutionSetWrites`. +- `pExecutionSetWrites` is a pointer to a `VkWriteIndirectExecutionSetPipelineEXT` structure describing the elements to update. + +```c +VKAPI_ATTR void VKAPI_CALL vkUpdateIndirectExecutionSetShaderEXT( + VkDevice device, + VkIndirectExecutionSetEXT indirectExecutionSet, + uint32_t executionSetWriteCount, + const VkWriteIndirectExecutionSetShaderEXT* pExecutionSetWrites); +``` + +- `device` is the logical device that owns the indirect execution set. +- `indirectExecutionSet` is the indirect execution set to update. +- `executionSetWriteCount` is the number of elements in `pExecutionSetWrites`. +- `pExecutionSetWrites` is a pointer to a `VkWriteIndirectExecutionSetShaderEXT` structure describing the elements to update. + +It is legal to update an indirect execution set that is used in flight as long as the slot indices in `VkWriteIndirectExecutionSetEXT` are not in use. Any change to an indirect execution set requires recalculating memory requirements by calling `vkGetGeneratedCommandsMemoryRequirementsEXT` for commands that use that modified state. Commands that are in flight or those not using the changed state are safe. + +The `VkWriteIndirectExecutionSetPipelineEXT` struct is defined as: + +```c +typedef struct VkWriteIndirectExecutionSetPipelineEXT { + VkStructureType sType; + const void* pNext; + uint32_t index; + VkPipeline pipeline; +} VkWriteIndirectExecutionSetPipelineEXT; +``` + +- `index` is the execution slot to update +- `pipeline` is the pipeline to store in the indirect execution set + +The `VkWriteIndirectExecutionSetShaderEXT` struct is defined as: + +```c +typedef struct VkWriteIndirectExecutionSetShaderEXT { + VkStructureType sType; + const void* pNext; + uint32_t index; + VkShaderEXT shader; +} VkWriteIndirectExecutionSetShaderEXT; +``` + +- `index` is the execution slot to update +- `shader` is the shader object to store in the indirect execution set + +=== Indirect Commands Layout +The device-side command generation happens through an iterative processing of an atomic sequence comprised of command tokens, which are represented by: + +```c +VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkIndirectCommandsLayoutEXT) +``` + +==== Creation and Deletion + +Indirect command layouts are created by: + +```c +VKAPI_ATTR VkResult VKAPI_CALL vkCreateIndirectCommandsLayoutEXT( + VkDevice device, + const VkIndirectCommandsLayoutCreateInfoEXT* pCreateInfo, + const VkAllocationCallbacks* pAllocator, + VkIndirectCommandsLayoutEXT* pIndirectCommandsLayout); +``` + +- `device` is the logical device that creates the indirect command layout. +- `pCreateInfo` is a pointer to a `VkIndirectCommandsLayoutCreateInfoEXT` structure containing parameters affecting creation of the indirect command layout. +- `pAllocator` controls host memory allocation as described in the Memory Allocation chapter. +- `pIndirectCommandsLayout` is a pointer to a `VkIndirectCommandsLayoutEXT` handle in which the resulting indirect command layout is returned. + +The `VkIndirectCommandsLayoutCreateInfoEXT` structure is defined as: + +```c +typedef struct VkIndirectCommandsLayoutCreateInfoEXT { + VkStructureType sType; + const void* pNext; + VkIndirectCommandsLayoutUsageFlagsEXT flags; + VkShaderStageFlags shaderStages; + uint32_t indirectStride; + VkPipelineLayout pipelineLayout; + uint32_t tokenCount; + const VkIndirectCommandsLayoutTokenEXT* pTokens; +} VkIndirectCommandsLayoutCreateInfoEXT; +``` + +- `flags` is a bitmask of `VkIndirectCommandsLayoutUsageFlagBitsEXT` specifying usage rules for this layout. +- `shaderStages` is the `VkShaderStageFlags` that this layout supports. +- `indirectStride` is the stride of the indirect buffer. +- `pipelineLayout` is the `VkPipelineLayout` that this layout supports. If a `VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_CONSTANT_EXT` or `VK_INDIRECT_COMMANDS_TOKEN_TYPE_SEQUENCE_INDEX_EXT` is used by the layout, it must not be `VK_NULL_HANDLE``. +- `tokenCount` is the length of the individual command sequence. +- `pTokens` is an array describing each command token in detail. See `VkIndirectCommandsTokenTypeEXT` and `VkIndirectCommandsLayoutTokenEXT` below for details. + +A `VkPipelineLayoutCreateInfo` can be passed in `pNext` if the `dynamicGeneratedPipelineLayout` feature is enabled. + +Bits which can be set in `VkIndirectCommandsLayoutCreateInfoEXT::flags`, specifying usage rules of an indirect command layout, are: + +```c +typedef enum VkIndirectCommandsLayoutUsageFlagBitsEXT +{ + VK_INDIRECT_COMMANDS_LAYOUT_USAGE_EXPLICIT_PREPROCESS_BIT_EXT = 0x00000001, + VK_INDIRECT_COMMANDS_LAYOUT_USAGE_UNORDERED_SEQUENCES_BIT_EXT = 0x00000002, +} VkIndirectCommandsLayoutUsageFlagBitsEXT; +typedef VkFlags VkIndirectCommandsLayoutUsageFlagsEXT; +``` + +- `VK_INDIRECT_COMMANDS_LAYOUT_USAGE_EXPLICIT_PREPROCESS_BIT_EXT` specifies that the layout is always used with the manual preprocessing step through calling `vkCmdPreprocessGeneratedCommandsEXT` and executed by `vkCmdExecuteGeneratedCommandsEXT` when `isPreprocessed` set to `VK_TRUE`. + +- `VK_INDIRECT_COMMANDS_LAYOUT_USAGE_UNORDERED_SEQUENCES_BIT_EXT` specifies that https://docs.vulkan.org/spec/latest/chapters/synchronization.html#synchronization-submission-order[submission order] is not affected by the ordering of sequences, and sequences may be processed in any order. + +Indirect command layouts are destroyed by: + +```c +VKAPI_ATTR void VKAPI_CALL vkDestroyIndirectCommandsLayoutEXT( + VkDevice device, + VkIndirectCommandsLayoutEXT indirectCommandsLayout, + const VkAllocationCallbacks* pAllocator); +``` + +- `device` is the logical device that owns the layout. +- `indirectCommandsLayout` is the layout to destroy. +- `pAllocator` controls host memory allocation as described in the Memory Allocation chapter. + +==== Token layout + +Each sequence of commands in the indirect buffer has the same memory layout. The data can contain raw `uint32_t` values, existing indirect command such as `VkDrawIndirectCommand`, or additional commands listed in the next section. + +The `VkIndirectCommandsLayoutTokenEXT` structure specifies details to the commands that need to be known at layout creation time: + +```c +typedef struct VkIndirectCommandsLayoutTokenEXT { + VkStructureType sType; + const void* pNext; + VkIndirectCommandsTokenTypeEXT type; + VkIndirectCommandsTokenDataEXT data; + uint32_t offset; +} VkIndirectCommandsLayoutTokenEXT; +``` + +- `type` specifies the token command type. +- `data` specifies token specific details for command execution. +- `offset` is the relative byte offset for the token within one sequence of the indirect buffer. The data stored at that offset is the command data for the token, e.g. `VkDispatchIndirectCommand`. + +Token data is a union of additional information specific to the command: + +```c +typedef union VkIndirectCommandsTokenDataEXT { + const VkIndirectCommandsPushConstantTokenEXT *pPushConstant; + const VkIndirectCommandsVertexBufferTokenEXT *pVertexBuffer; + const VkIndirectCommandsIndexBufferTokenEXT *pIndexBuffer; + const VkIndirectCommandsExecutionSetTokenEXT *pExecutionSet; +} VkIndirectCommandsTokenDataEXT; +``` + +These structures are described in the next section. + +=== Indirect Commands +This extension defines the following commands for state changes and operations: + +[cols="1,1"] +|=== +|*Common Tokens* +|*Command Data* +|`VK_INDIRECT_COMMANDS_TOKEN_TYPE_EXECUTION_SET_EXT` +|`uint32_t[]` array of indices into the indirect execution set +|`VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_CONSTANT_EXT` +|`uint32_t[]` raw data +|*Compute Tokens* +| +|`VK_INDIRECT_COMMANDS_TOKEN_TYPE_DISPATCH_EXT` +|`VkDispatchIndirectCommand` +|*Ray Tracing Tokens* +| +|`VK_INDIRECT_COMMANDS_TOKEN_TYPE_TRACE_RAYS2_EXT` +|`VkTraceRaysIndirectCommand2KHR` +|*Graphics State Tokens* +| +|`VK_INDIRECT_COMMANDS_TOKEN_TYPE_INDEX_BUFFER_EXT` +|`VkBindIndexBufferIndirectCommandEXT` +|`VK_INDIRECT_COMMANDS_TOKEN_TYPE_VERTEX_BUFFER_EXT` +|`VkBindVertexBufferIndirectCommandEXT` +|*Graphics Draw Tokens* +| +|`VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_INDEXED_EXT` +|`VkDrawIndexedIndirectCommand` +|`VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_EXT` +|`VkDrawIndirectCommand` +|`VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_EXT` +|`VkDrawMeshTasksIndirectCommandEXT` +|`VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_NV_EXT` +|`VkDrawMeshTasksIndirectCommandNV` +|*Graphics Draw Count Tokens* +| +|`VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_INDEXED_COUNT_EXT` +|`VkDrawIndirectCountIndirectCommandEXT` with `VkDrawIndexedIndirectCommand` +|`VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_COUNT_EXT` +|`VkDrawIndirectCountIndirectCommandEXT` with `VkDrawIndirectCommand` +|`VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_COUNT_EXT` +|`VkDrawIndirectCountIndirectCommandEXT` with `VkDrawMeshTasksIndirectCommandEXT` +|`VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_COUNT_NV_EXT` +|`VkDrawIndirectCountIndirectCommandEXT` with `VkDrawMeshTasksIndirectCommandNV` +|=== + +All commands can be stored 4-byte aligned, independent of 64-bit alignment of structures due to use of `VkDeviceAddress`. This provides binary compatibility with D3D12. + +The type of tokens in a sequence is specified by `VkIndirectCommandsTokenTypeEXT` which must be one of the values: + +```c +typedef enum VkIndirectCommandsTokenTypeEXT { + VK_INDIRECT_COMMANDS_TOKEN_TYPE_EXECUTION_SET_EXT, + VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_CONSTANT_EXT, + VK_INDIRECT_COMMANDS_TOKEN_TYPE_SEQUENCE_INDEX_EXT, + VK_INDIRECT_COMMANDS_TOKEN_TYPE_INDEX_BUFFER_EXT, + VK_INDIRECT_COMMANDS_TOKEN_TYPE_VERTEX_BUFFER_EXT, + VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_INDEXED_EXT, + VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_EXT, + VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_EXT, + VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_NV_EXT, + VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_INDEXED_COUNT_EXT, + VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_COUNT_EXT, + VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_COUNT_EXT, + VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_COUNT_NV_EXT, + VK_INDIRECT_COMMANDS_TOKEN_TYPE_DISPATCH_EXT, + VK_INDIRECT_COMMANDS_TOKEN_TYPE_TRACE_RAYS2_EXT, +} VkIndirectCommandsTokenTypeEXT; +``` + +==== Bind Execution Command +An array of 32-bit unsigned integer values are the input data for the `VK_INDIRECT_COMMANDS_TOKEN_TYPE_EXECUTION_SET_EXT` token. +Each value is an index, specified in canonical pipeline order, into the Indirect Execution Set. +One index value must be passed for each bit set in VkIndirectCommandsExecutionSetTokenEXT::shaderStages. + +The `VkIndirectCommandsExecutionSetTokenEXT` structure specifies additional info used when creating the layout object: + +```c +struct VkIndirectCommandsExecutionSetTokenEXT { + VkIndirectExecutionSetInfoTypeEXT type; + VkShaderStageFlags shaderStages; +}; +``` + +- `type` must be either `VK_INDIRECT_EXECUTION_SET_INFO_TYPE_PIPELINES_EXT` or `VK_INDIRECT_EXECUTION_SET_INFO_TYPE_SHADER_OBJECTS_EXT`. +- `shaderStages` specifies the shaders that will be changed by this token. + +This must be the first command in a sequence when used. + +Pipelines and shaders bound in indirect buffers must be flagged at creation time: + +```c +#define VK_PIPELINE_CREATE_2_INDIRECT_BINDABLE_BIT_EXT ((VkPipelineCreateFlagBits)0x4000000000ULL) +#define VK_SHADER_CREATE_INDIRECT_BINDABLE_BIT_EXT ((VkShaderCreateFlagBitsEXT)0x00000080) +``` + +==== Push Constants Command +Raw 32-bit values are the input data for the `VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_CONSTANT_EXT` token. + +Interpretation of the data is specified at layout creation time: + +```c +typedef struct VkIndirectCommandsPushConstantTokenEXT { + VkPushConstantRange updateRange; +} VkIndirectCommandsPushConstantTokenEXT; +``` + +- `updateRange` is the range of push constant data to update. + +==== Sequence Index Command +There is a single `uint32_t` of placeholder data for the `VK_INDIRECT_COMMANDS_TOKEN_TYPE_SEQUENCE_INDEX_EXT` token which is not accessed by the shader. It writes a single 32-bit value containing the current sequence index to the specified push constant range. + +Interpretation of the data is specified at layout creation time: + +```c +typedef struct VkIndirectCommandsPushConstantTokenEXT { + VkPushConstantRange updateRange; +} VkIndirectCommandsPushConstantTokenEXT; +``` + +- `updateRange` is the range of push constant data to update. `updateRange.size` must be 4. + +==== Bind Index Buffer Command +The `VkBindIndexBufferIndirectCommandEXT` structure specifies the input data for the `VK_INDIRECT_COMMANDS_TOKEN_TYPE_INDEX_BUFFER_EXT` token. + +```c +typedef struct VkBindIndexBufferIndirectCommandEXT { + VkDeviceAddress bufferAddress; + uint32_t size; + VkIndexType indexType; +} VkBindIndexBufferIndirectCommandEXT; +``` + +- `bufferAddress` specifies a physical address of the `VkBuffer` used as an index buffer. +- `size` is the byte size range which is available for this operation from the provided address. +- `indexType` is a `VkIndexType` value specifying how indices are treated. Instead of the Vulkan enum values, custom `uint32_t` values can be mapped to an `VkIndexType` as described below. + +The index buffer is bound as specified at layout creation time: + +```c +typedef struct VkIndirectCommandsIndexBufferTokenEXT { + VkIndirectCommandsInputModeFlagsEXT mode; +} VkIndirectCommandsIndexBufferTokenEXT; +``` + +- `flags` is a single `VkIndirectCommandsInputModeFlagBitsEXT` value specifying the mode to be used with this token. + +The VkIndirectCommandsInputModeFlagsEXT enum is defined as: + +```c +typedef enum VkIndirectCommandsInputModeFlagBitsEXT +{ + VK_INDIRECT_COMMANDS_INPUT_MODE_VULKAN_INDEX_BUFFER_EXT = 0x00000001, + VK_INDIRECT_COMMANDS_INPUT_MODE_DXGI_INDEX_BUFFER_EXT = 0x00000002, +} VkIndirectCommandsInputModeFlagBitsEXT; +typedef VkFlags VkIndirectCommandsInputModeFlagsEXT; +``` + +- `VK_INDIRECT_COMMANDS_INPUT_MODE_VULKAN_INDEX_BUFFER_EXT` indicates that the indirect buffer contains `VkBindIndexBufferIndirectCommandEXT`. +- `VK_INDIRECT_COMMANDS_INPUT_MODE_DXGI_INDEX_BUFFER_EXT` indicates that the indirect buffer contains `D3D12_INDEX_BUFFER_VIEW`. + +This allows for easy layering of Vulkan atop other APIs. When `VK_INDIRECT_COMMANDS_INPUT_MODE_DXGI_INDEX_BUFFER_EXT` is specified, the indirect buffer can contain a `D3D12_INDEX_BUFFER_VIEW` instead of `VkBindIndexBufferIndirectCommandEXT` as D3D's DXGI format value is mapped to the `VkIndexType`. It works as both structs are otherwise binary compatible. + +==== Bind Vertex Buffer Command +The `VkBindVertexBufferIndirectCommandEXT` structure specifies the input data for the `VK_INDIRECT_COMMANDS_TOKEN_TYPE_VERTEX_BUFFER_EXT` token. + +```c +typedef struct VkBindVertexBufferIndirectCommandEXT { + VkDeviceAddress bufferAddress; + uint32_t size; + uint32_t stride; +} VkBindVertexBufferIndirectCommandEXT; +``` + +- `bufferAddress` specifies a physical address of the `VkBuffer` used as a vertex input binding. +- `size` is the byte size range which is available for this operation from the provided address. +- `stride` is the byte size stride for this vertex input binding as in `VkVertexInputBindingDescription::stride`. + +The vertex buffer is bound as specified at layout creation time: + +```c +typedef struct VkIndirectCommandsVertexBufferTokenEXT { + uint32_t vertexBindingUnit; +} VkIndirectCommandsVertexBufferTokenEXT; +``` + +- `vertexBindingUnit` is the vertex input binding number to be bound. + +Both `VkBindVertexBufferIndirectCommandEXT` and `D3D12_VERTEX_BUFFER_VIEW` structs are binary compatible. + +==== Draw Commands +Draws can be executed with following commands: + +- The `VkDrawIndexedIndirectCommand` structure specifies the inputs data for the `VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_INDEXED_EXT` token. +- The `VkDrawIndirectCommand` structure specifies the input data for the `VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_EXT` token. +- If `EXT_mesh_shader` is enabled, the `VkDrawMeshTasksIndirectCommandEXT` structure specifies the input data for the `VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_EXT` token. +- If `NV_mesh_shader` is enabled, the `VkDrawMeshTasksIndirectCommandNV` structure specifies the input data for the `VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_NV_EXT` token. + +==== Multi-draw Commands +Multiple draws can be executed using the following commands: + +- Indexed draws with the `VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_INDEXED_COUNT_EXT` token. +- Non-indexed draws with the `VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_COUNT_EXT` token. +- If `EXT_mesh_shader` is enabled, mesh tasks with the `VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_COUNT_EXT` token. +- If `NV_mesh_shader` is enabled, mesh tasks with the `VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_COUNT_NV_EXT` token. +- The `DrawIndex` shader variable is zero-indexed for each multi-draw token. + +All multi-draw commands use `VkDrawIndirectCountIndirectCommandEXT` data: + +```c +typedef struct VkDrawIndirectCountIndirectCommandEXT { + VkDeviceAddress bufferAddress; + uint32_t stride; + uint32_t commandCount; +} VkDrawIndirectCountIndirectCommandEXT; +``` + +- `bufferAddress` specifies a physical address of the `VkBuffer` used for draw commands. +- `stride` is the byte size stride for the command arguments +- `commandCount` is the number of commands to execute + +The data in `bufferAddress` depends on the token: + +- `VkDrawIndexedIndirectCommand` for `VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_INDEXED_COUNT_EXT`. +- `VkDrawIndirectCommand` for `VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_COUNT_EXT` . +- `VkDrawMeshTasksIndirectCommandEXT` for `VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_COUNT_EXT`. +- `VkDrawMeshTasksIndirectCommandNV` for `VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_COUNT_NV_EXT`. + +==== Dispatch Command +The `VkDispatchIndirectCommand` structure specifies the input data for the `VK_INDIRECT_COMMANDS_TOKEN_TYPE_DISPATCH_EXT` token. + +==== Trace Rays Command +If `VK_KHR_ray_tracing_maintenance1` is enabled, the `VkTraceRaysIndirectCommand2KHR` structure specifies the input data for the `VK_INDIRECT_COMMANDS_TOKEN_TYPE_TRACE_RAYS2_EXT` token. + +=== Preprocess Buffer +The generation of commands on the device may require a preprocess buffer. Implementations may use this for the storage of device-specific commands or scratch memory. + +To retrieve the memory size and alignment requirements of a particular execution state call: + +```c +VKAPI_ATTR void VKAPI_CALL vkGetGeneratedCommandsMemoryRequirementsEXT( + VkDevice device, + const VkGeneratedCommandsMemoryRequirementsInfoEXT* pInfo, + VkMemoryRequirements2* pMemoryRequirements); +``` + +- `device` is the logical device that will create the buffer. +- `pInfo` is a pointer to a `VkGeneratedCommandsMemoryRequirementsInfoEXT` structure containing parameters required for the memory requirements query. +- `pMemoryRequirements` is a pointer to a `VkMemoryRequirements2` structure in which the memory requirements of the buffer object are returned. + +If `pMemoryRequirements->memoryRequirements.size` is zero then preprocessing is not required. + +The `VkGeneratedCommandsMemoryRequirementsInfoEXT` structure is defined as: + +```c +typedef struct VkGeneratedCommandsMemoryRequirementsInfoEXT { + VkStructureType sType; + const void* pNext; + VkIndirectExecutionSetEXT indirectExecutionSet; + VkIndirectCommandsLayoutEXT indirectCommandsLayout; + uint32_t maxSequenceCount; + uint32_t maxDrawCount; +} VkGeneratedCommandsMemoryRequirementsInfoEXT; +``` + +- `shaderStages` is the mask of shader stages that this buffer memory is intended to be used with during the execution. +- `indirectExecutionSet` is the indirect execution set to be used for binding shaders. If the token sequence will contain a `VK_INDIRECT_COMMANDS_TOKEN_TYPE_EXECUTION_SET_EXT` token, it must not be `VK_NULL_HANDLE`. +- `indirectCommandsLayout` is the `VkIndirectCommandsLayoutEXT` that this buffer memory is intended to be used with. +- `maxSequenceCount` is the maximum number of sequences that this buffer memory can be used with. +- `maxDrawCount` is the maximum number of indirect draws that can be executed by any COUNT-type multi-draw indirect tokens (equivalent to `maxDrawCount` in `vkCmdDrawIndirectCount`) + +Preprocess buffer memory can be recycled with different execution/preprocessing operations, but must be synchronized using barriers with `VK_PIPELINE_STAGE_COMMAND_PREPROCESS_BIT_EXT` and `VK_ACCESS_COMMAND_PREPROCESS_WRITE/READ_BIT_EXT`. + +The contents and the layout of this buffer is opaque to applications and must not be modified or copied to another buffer for reuse. + +If `indirectExecutionSet` is `VK_NULL_HANDLE`, pipeline or shader info must be passed through the pNext pointer using either a `VkGeneratedCommandsPipelineInfoEXT` or `VkGeneratedCommandsShaderInfoEXT` struct. + +The `VkGeneratedCommandsPipelineInfoEXT` structure is defined as: + +```c +typedef struct VkGeneratedCommandsPipelineInfoEXT { + VkStructureType sType; + const void* pNext; + VkPipeline pipeline; +} VkGeneratedCommandsPipelineInfoEXT; +``` + +- `pipeline` is a pipeline comprised of shaders that are compatible with the ones which will be used with the resulting indirect buffer. + +The `VkGeneratedCommandsShaderInfoEXT` structure is defined as: + +```c +typedef struct VkGeneratedCommandsShaderInfoEXT { + VkStructureType sType; + const void* pNext; + uint32_t shaderCount; + const VkShaderExt *pShaders; +} VkGeneratedCommandsShaderInfoEXT; +``` + +- `shaderCount` is the number of members in the `pShaders` array. +- `pShaders` is a pointer to an array of shaders that are compatible with the ones which will be used with the resulting indirect buffer. + +=== Command Buffer +==== Synchronization +Synchronization of preprocessing via `vkCmdPreprocessGeneratedCommandsEXT` and generation/execution via `vkCmdExecuteGeneratedCommandsEXT` is supported with a new stage and access flags: + +```c +#define VK_PIPELINE_STAGE_COMMAND_PREPROCESS_BIT_EXT ((VkPipelineStageFlagBits)0x00020000) + +#define VK_ACCESS_COMMAND_PREPROCESS_READ_BIT_EXT ((VkAccessFlagBits)0x00020000) +#define VK_ACCESS_COMMAND_PREPROCESS_WRITE_BIT_EXT ((VkAccessFlagBits)0x00040000) +``` + +- `VK_PIPELINE_STAGE_COMMAND_PREPROCESS_BIT_EXT` specifies the stage of the pipeline where device-side preprocessing for generated commands via `vkCmdPreprocessGeneratedCommandsEXT` is handled. +- `VK_ACCESS_COMMAND_PREPROCESS_READ_BIT_EXT` specifies reads from buffer inputs to `vkCmdPreprocessGeneratedCommandsEXT`. Such access occurs in the `VK_PIPELINE_STAGE_COMMAND_PREPROCESS_BIT_EXT` pipeline stage. +- `VK_ACCESS_COMMAND_PREPROCESS_WRITE_BIT_EXT` specifies writes to preprocess outputs from `vkCmdPreprocessGeneratedCommandsEXT`. Such access occurs in the `VK_PIPELINE_STAGE_COMMAND_PREPROCESS_BIT_EXT` pipeline stage. + +==== Generated Commands +Device-generated commands are specified by: + +```c +typedef struct VkGeneratedCommandsInfoEXT { + VkStructureType sType; + const void* pNext; + VkShaderStageFlags shaderStages; + VkIndirectExecutionSetEXT indirectExecutionSet; + VkIndirectCommandsLayoutEXT indirectCommandsLayout; + VkDeviceAddress indirectAddress; + VkDeviceSize indirectAddressSize; + VkDeviceAddress preprocessAddress; + VkDeviceSize preprocessSize; + uint32_t maxSequenceCount; + VkDeviceAddress sequenceCountAddress; + uint32_t maxDrawCount; +} VkGeneratedCommandsInfoEXT; +``` + +- `shaderStages` is the mask of shader stages used by the commands. +- `indirectExecutionSet` is the indirect execution set to be used for binding shaders. If the token sequence contains a `VK_INDIRECT_COMMANDS_TOKEN_TYPE_EXECUTION_SET_EXT` token, it must not be `VK_NULL_HANDLE`. +- `indirectCommandsLayout` is the `VkIndirectCommandsLayoutEXT` that specifies the command sequence data. +- `indirectAddress` is an address that holds the indirect buffer data. +- `indirectAddressSize` is the size of the address space that holds the indirect buffer data. +- `preprocessAddress` specifies a physical address of the `VkBuffer` used for preprocessing the input data for execution. It must not be `0` if `vkGetGeneratedCommandsMemoryRequirementsEXT` returns non-zero size. +- `preprocessSize` is the maximum byte size within the `preprocessAddress` that is available for preprocessing. +- `maxSequenceCount` is used to determine the number of sequences to execute. If `sequenceCountAddress` is not `NULL`, then `maxSequenceCount` is the maximum number of sequences that can be executed. The actual number is `min(maxSequenceCount, *sequenceCountAddress)`. Otherwise if `sequenceCountAddress` is `NULL`, then `maxSequenceCount` is the exact number of sequences to execute. +- `sequenceCountAddress` specifies an optional physical address of a single `uint32_t` value containing the requested number of sequences to execute. +- `maxDrawCount` is the maximum number of indirect draws that can be executed by any COUNT-type multi-draw indirect tokens (equivalent to `maxDrawCount` in `vkCmdDrawIndirectCount`) + +When preprocessing, if `indirectExecutionSet` is `VK_NULL_HANDLE` then pipeline or shader info must be passed through the pNext pointer using either a `VkGeneratedCommandsPipelineInfoEXT` or `VkGeneratedCommandsShaderInfoEXT` struct. + +The actual generation of commands as well as their execution on the device is handled as single action with: + +```c +VKAPI_ATTR void VKAPI_CALL vkCmdExecuteGeneratedCommandsEXT( + VkCommandBuffer commandBuffer, + VkBool32 isPreprocessed, + const VkGeneratedCommandsInfoEXT* pGeneratedCommandsInfo); +``` + +- `commandBuffer` is the command buffer into which the command is recorded. +- `isPreprocessed` represents whether the input data has been previously preprocessed on the device. If it is `VK_TRUE`, `vkCmdPreprocessGeneratedCommandsEXT` must have been previously called. If it is `VK_FALSE`, any necessary processing will be performed as part of this command. +- `pGeneratedCommandsInfo` is a pointer to a `VkGeneratedCommandsInfoEXT` structure containing parameters affecting the generation of commands. + +All state affected by executed tokens is undefined after this command. The view mask of an active rendering pass must be zero. + +Commands can be preprocessed prior execution using the following command: + +```c +VKAPI_ATTR void VKAPI_CALL vkCmdPreprocessGeneratedCommandsEXT( + VkCommandBuffer commandBuffer, + const VkGeneratedCommandsInfoEXT* pGeneratedCommandsInfo, + VkCommandBuffer stateCommandBuffer); +``` + +- `commandBuffer` is the command buffer which does the preprocessing. +- `pGeneratedCommandsInfo` is a pointer to a `VkGeneratedCommandsInfoEXT` structure containing parameters affecting the preprocessing step. +- `stateCommandBuffer` is an command buffer from which to pull state affecting the preprocessing step. + +Explicitly preprocessing the indirect buffer provides more control over the scheduling of work. If not performed, the implementation may still have additional work to do that is deferred to execution time. +The bound state in `stateCommandBuffer` must be identical to the state bound at the time `vkCmdExecuteGeneratedCommandsEXT` is recorded. + +=== Features +The following features are exposed by this extension: + +```c +typedef struct VkPhysicalDeviceDeviceGeneratedCommandsFeaturesEXT +{ + VkStructureType sType; + const void* pNext; + VkBool32 deviceGeneratedCommands; + VkBool32 dynamicGeneratedPipelineLayout; +} VkPhysicalDeviceDeviceGeneratedCommandsFeaturesEXT; +``` + +- `deviceGeneratedCommands` is the core feature enabling the extension +- `dynamicGeneratedPipelineLayout` enables passing a `VkPipelineLayoutCreateInfo` in the `pNext` of `VkIndirectCommandsLayoutCreateInfoEXT` with a `VK_NULL_HANDLE` `pipelineLayout` + +=== Properties +The following properties are exposed by this extension: + +```c +typedef struct VkPhysicalDeviceDeviceGeneratedCommandsPropertiesEXT +{ + VkStructureType sType; + const void* pNext; + uint32_t maxIndirectPipelineCount; + uint32_t maxIndirectShaderObjectCount; + uint32_t maxIndirectSequenceCount; + uint32_t maxIndirectCommandsTokenCount; + uint32_t maxIndirectCommandsTokenOffset; + uint32_t maxIndirectCommandsIndirectStride; + VkIndirectCommandsInputModeFlagsEXT supportedIndirectCommandsInputModes; + VkShaderStageFlags supportedIndirectCommandsShaderStages; + VkShaderStageFlags supportedIndirectCommandsShaderStagesPipelineBinding; + VkShaderStageFlags supportedIndirectCommandsShaderStagesShaderBinding; + VkBool32 deviceGeneratedCommandsTransformFeedback; + VkBool32 deviceGeneratedCommandsMultiDrawIndirectCount; +} VkPhysicalDeviceDeviceGeneratedCommandsPropertiesEXT; +``` + +The following limits affect indirect execution set creation: + +- `maxIndirectPipelineCount` indicates the maximum number of pipelines that can be stored in an indirect execution set. +- `maxIndirectShaderObjectCount` indicates the maximum number of shader objects that can be stored in an indirect execution set. +- `supportedIndirectCommandsShaderStagesPipelineBinding` is a bitmask of the shader stages which can be used within indirect execution sets comprised of pipelines. +- `supportedIndirectCommandsShaderStagesShaderBinding` is a bitmask of the shader stages which can be used within indirect execution sets comprised of shader objects. + +The following limits affect indirect command layout creation: + +- `maxIndirectCommandsTokenCount` indicates the maximum number of tokens in a sequence. +- `maxIndirectCommandsTokenOffset` indicates the maximum byte offset of a token within a sequence. +- `supportedIndirectCommandsInputModes` indicates the supported index buffer modes. + +The following limits affect indirect command execution: + +- `maxIndirectSequenceCount` indicates the maximum number of sequences that can executed. +- `maxIndirectCommandsIndirectStride` indicates the maximum stride that can be used for the indirect buffer. + +If `VK_EXT_transform_feedback` is also enabled, `deviceGeneratedCommandsTransformFeedback` enables the use of Transform Feedback with indirect execution. + +`supportedIndirectCommandsShaderStages` is a bitmask of the shader stages which can be active while executing indirect commands as well as the use of certain tokens. + +- `VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_CONSTANT_EXT` and `VK_INDIRECT_COMMANDS_TOKEN_TYPE_SEQUENCE_INDEX_EXT`` are always supported for the specified stages. + +`VK_SHADER_STAGE_VERTEX_BIT | VK_SHADER_STAGE_FRAGMENT_BIT` enables use of these tokens: + +- `VK_INDIRECT_COMMANDS_TOKEN_TYPE_INDEX_BUFFER_EXT` +- `VK_INDIRECT_COMMANDS_TOKEN_TYPE_VERTEX_BUFFER_EXT` +- `VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_INDEXED_EXT` +- `VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_EXT` +- `VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_INDEXED_COUNT_EXT` if `deviceGeneratedCommandsMultiDrawIndirectCount` is supported +- `VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_COUNT_EXT` if `deviceGeneratedCommandsMultiDrawIndirectCount` is supported + +If `EXT_mesh_shader` extension is also enabled, `VK_SHADER_STAGE_FRAGMENT_BIT | VK_SHADER_STAGE_MESH_BIT_EXT` enables use of these tokens: + +- `VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_EXT` +- `VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_COUNT_EXT` if `deviceGeneratedCommandsMultiDrawIndirectCount` is supported + +If `NV_mesh_shader` extension is also enabled, `VK_SHADER_STAGE_FRAGMENT_BIT | VK_SHADER_STAGE_MESH_BIT_NV` enables use of these tokens: + +- `VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_NV_EXT` +- `VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_COUNT_NV_EXT` if `deviceGeneratedCommandsMultiDrawIndirectCount` is supported + +`VK_SHADER_STAGE_COMPUTE_BIT` enables use of these tokens: + +- `VK_INDIRECT_COMMANDS_TOKEN_TYPE_DISPATCH_EXT` + +If `VK_KHR_ray_tracing_maintenance1` is also enabled, the presence of ray tracing stages enables use of these tokens: + +- `VK_INDIRECT_COMMANDS_TOKEN_TYPE_TRACE_RAYS2_EXT` + +=== D3D12 Emulation + +==== Argument Structures + +Most structures have direct equivalents: + +[cols="1,1"] +|=== +|*D3D12 type* +|*Vulkan type* +|`D3D12_DRAW_ARGUMENTS` +|`VkDrawIndirectCommand` +|`D3D12_DRAW_INDEXED_ARGUMENTS` +|`VkDrawIndexedIndirectCommand` +|`D3D12_DISPATCH_ARGUMENTS` +|`VkDispatchIndirectCommand` +|`D3D12_INDEX_BUFFER_VIEW` +|`VkBindIndexBufferIndirectCommandEXT` +|`D3D12_VERTEX_BUFFER_VIEW` +|`VkBindVertexBufferIndirectCommandEXT` +|=== + +Binding of views or constants require translation due to mismatches between the APIs. + +==== Indirect Argument Type + +Maps to `VkIndirectCommandsTokenTypeEXT`: + +[cols="1,1"] +|=== +|*D3D12 value* +|*Vulkan value* +|`D3D12_INDIRECT_ARGUMENT_TYPE_DRAW` +|`VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_EXT` +|`D3D12_INDIRECT_ARGUMENT_TYPE_DRAW_INDEXED` +|`VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_INDEXED_EXT` +|`D3D12_INDIRECT_ARGUMENT_TYPE_DISPATCH` +|`VK_INDIRECT_COMMANDS_TOKEN_TYPE_DISPATCH_EXT` +|`D3D12_INDIRECT_ARGUMENT_TYPE_VERTEX_BUFFER_VIEW` +|`VK_INDIRECT_COMMANDS_TOKEN_TYPE_VERTEX_BUFFER_EXT` +|`D3D12_INDIRECT_ARGUMENT_TYPE_INDEX_BUFFER_VIEW` +|`VK_INDIRECT_COMMANDS_TOKEN_TYPE_INDEX_BUFFER_EXT` +|`D3D12_INDIRECT_ARGUMENT_TYPE_CONSTANT` +|`VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_CONSTANT_EXT` +|`D3D12_INDIRECT_ARGUMENT_TYPE_CONSTANT_BUFFER_VIEW` +|`VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_CONSTANT_EXT` +|`D3D12_INDIRECT_ARGUMENT_TYPE_SHADER_RESOURCE_VIEW` +|`VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_CONSTANT_EXT` +|`D3D12_INDIRECT_ARGUMENT_TYPE_UNORDERED_ACCESS_VIEW` +|`VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_CONSTANT_EXT` +|`D3D12_INDIRECT_ARGUMENT_TYPE_DISPATCH_RAYS` +|`VK_INDIRECT_COMMANDS_TOKEN_TYPE_TRACE_RAYS2_EXT` +|`D3D12_INDIRECT_ARGUMENT_TYPE_DISPATCH_MESH` +|`VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_EXT` +|=== + +A root descriptor in D3D12 is a 64-bit virtual address to a raw buffer. To implement this, `VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_CONSTANT_EXT` tokens can be used to update buffer device addresses stored in push constants rather than interacting with the descriptor binding model. Similar techniques can be used to update non-root descriptors as well. + +`VK_INDIRECT_COMMANDS_TOKEN_TYPE_SEQUENCE_INDEX_EXT` can be used to mimic D3D12 DGC TIER_1_1 support. + +==== Command Signature + +- `ByteStride` is specified at execution time with `VkGeneratedCommandsInfoEXT::indirectAddressRegion.stride`. +- Set `VkIndirectCommandsIndexBufferTokenEXT::mode` to `VK_INDIRECT_COMMANDS_INPUT_MODE_DXGI_INDEX_BUFFER_EXT` to remap `DXGI_FORMAT` values. + +==== Alignment + +Alignment requirements: + +- `ByteStride` is 4 byte aligned +- `CountBufferOffset` is 4 byte aligned +- `ArgumentBufferOffset` is 4 byte aligned +- `tokenOffset` is 4 byte aligned + +== Examples + +TODO + +== Issues + +=== UNRESOLVED: How will future commands be added? + +New pointer members will be added to `VkIndirectCommandsTokenDataEXT`. + +=== RESOLVED: Should additional state be included? + +No additional state changes are permitted in order to enable fast and broad adoption. + +=== RESOLVED: What shader stages or pipeline states should be allowed to change? + +All implementation-supported shader stagess can be changed indirectly. No pipeline state may be changed. Future extensions may expose additional functionality. + +=== UNRESOLVED: Should Indirect execution sets be merged with either Shader Binding Tables or Indirect Object Sets? + +- Significant overlap in functionality with Shader Binding Tables +- Indirect Object Sets would allow for indirect dynamic state groups. + +=== RESOLVED: Should additional alignment properties be added? + +Recent extensions have been using fixed rather than queryable alignment rules. It makes sense to use fixed alignments here too. + +=== RESOLVED: Should index type values be remappable? + +`D3D12_INDEX_BUFFER_VIEW` and `VkBindIndexBufferIndirectCommandEXT` have the same memory layout but `DXGI_FORMAT` and `VkIndexType` do not have equivalent values. Providing the ability to remap index type values in the layout simplifies API emulation. + +There is explicit mapping from data values to `VkIndexType`. + +=== RESOLVED: Should indirect buffers be reusable? + +Yes, indirect buffers can be reused. + +=== RESOLVED: How should commands with less than 32-bits of data be handled? + +No such commands are provided. + +=== RESOLVED: How should applications provide data to the preprocess command in order for drivers to optimize indirect execution? + +A `stateCommandBuffer` is added to `vkCmdPreprocessGeneratedCommandsEXT` with the requirement that all state must match between this command buffer and the one used to record `vkCmdExecuteGeneratedCommandsEXT`. +This guarantees that all pipeline state and, specifically for draw commands, other state (e.g., vertex buffers, index buffers) is available at preprocess time. + +== Further Functionality + +- Support for Multi-dispatch (needs something like `gl_drawID` for compute shaders). +- Multi-level indirect execution through a command that is equivalent to `vkCmdExecuteGeneratedCommandsEXT`. +- Indirect command buffers. + +== TODO + +- Example section diff --git a/proposals/template.adoc b/proposals/template.adoc index a82428788..417eb7136 100644 --- a/proposals/template.adoc +++ b/proposals/template.adoc @@ -7,7 +7,7 @@ :refpage: https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/ :sectnums: -.How to use this document +.How to Use This Document [NOTE] ==== This document outlines the expected flow of a proposal - text in the following sections is there as guidance for how to fill out each section. diff --git a/scripts/check_spec_links.py b/scripts/check_spec_links.py index 64c25262d..39be672e7 100755 --- a/scripts/check_spec_links.py +++ b/scripts/check_spec_links.py @@ -43,6 +43,7 @@ 'VK_VERSION_1_3', 'WSIheaders', 'provisional-headers', + 'Required_Limits', ) # These are marked with the code: macro diff --git a/style/markup.adoc b/style/markup.adoc index cf46550a7..6dcdbe0d4 100644 --- a/style/markup.adoc +++ b/style/markup.adoc @@ -816,7 +816,7 @@ whenever it is followed by an alphabetic character. For example, when writing the {YCbCr} term widely used to describe a color encoding, the obvious markup does not look quite right: -.Prime Attributes (incorrect, with curved prime symbol) +.Prime Attributes (Incorrect, With Curved Prime Symbol) [width="30%",options="header"] |==== | Markup | Output diff --git a/style/writing.adoc b/style/writing.adoc index a1df472f1..3adc42108 100644 --- a/style/writing.adoc +++ b/style/writing.adoc @@ -614,7 +614,7 @@ everything, though does have some support for AMSMath. Some workarounds we use are: -.LaTeX math replacements for KaTeX compatibility +.LaTeX Math Replacements for KaTeX Compatibility [width="70%",options="header",cols="20%,20%,60%"] |==== | Replace | With | Comments diff --git a/vkspec.adoc b/vkspec.adoc index 509f00908..144e113f7 100644 --- a/vkspec.adoc +++ b/vkspec.adoc @@ -134,9 +134,9 @@ include::{chapters}/framebuffer.adoc[] include::{chapters}/dispatch.adoc[] // Device Generated Commands -ifdef::VK_NV_device_generated_commands[] -include::{chapters}/VK_NV_device_generated_commands/generatedcommands.adoc[] -endif::VK_NV_device_generated_commands[] +ifdef::VK_NV_device_generated_commands,VK_EXT_device_generated_commands[] +include::{chapters}/device_generated_commands/generatedcommands.adoc[] +endif::VK_NV_device_generated_commands,VK_EXT_device_generated_commands[] // Sparse include::{chapters}/sparsemem.adoc[] diff --git a/xml/video.xml b/xml/video.xml index 7e52a1b6d..2ac583149 100644 --- a/xml/video.xml +++ b/xml/video.xml @@ -77,7 +77,7 @@ The current public version of video.xml is maintained in the default branch uint32_t overscan_appropriate_flag : 1 uint32_t video_signal_type_present_flag : 1 uint32_t video_full_range_flag : 1 - uint32_t color_description_present_flag : 1 + uint32_t color_description_present_flag : 1colour_description_present_flag uint32_t chroma_loc_info_present_flag : 1 uint32_t timing_info_present_flag : 1 uint32_t fixed_frame_rate_flag : 1 diff --git a/xml/vk.xml b/xml/vk.xml index 7e0bd591b..00d97f14c 100644 --- a/xml/vk.xml +++ b/xml/vk.xml @@ -175,7 +175,7 @@ branch of the member gitlab server. #define VKSC_API_VERSION_1_0 VK_MAKE_API_VERSION(VKSC_API_VARIANT, 1, 0, 0)// Patch version should always be set to 0 // Version of this file -#define VK_HEADER_VERSION 295 +#define VK_HEADER_VERSION 296 // Complete version of this file #define VK_HEADER_VERSION_COMPLETE VK_MAKE_API_VERSION(0, 1, 3, VK_HEADER_VERSION) // Version of this file @@ -389,6 +389,8 @@ typedef void* MTLSharedEvent_id; typedef VkFlags VkBuildMicromapFlagsEXT; typedef VkFlags VkMicromapCreateFlagsEXT; + typedef VkFlags VkIndirectCommandsLayoutUsageFlagsEXT; + typedef VkFlags VkIndirectCommandsInputModeFlagsEXT; typedef VkFlags VkDirectDriverLoadingFlagsLUNARG; typedef VkFlags64 VkPipelineCreateFlags2KHR; typedef VkFlags64 VkBufferUsageFlags2KHR; @@ -552,6 +554,8 @@ typedef void* MTLSharedEvent_id; VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkPipelineCache) VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkPipelineBinaryKHR) VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkIndirectCommandsLayoutNV) + VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkIndirectCommandsLayoutEXT) + VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkIndirectExecutionSetEXT) VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkDescriptorUpdateTemplate) VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkSamplerYcbcrConversion) @@ -629,6 +633,7 @@ typedef void* MTLSharedEvent_id; + @@ -781,6 +786,9 @@ typedef void* MTLSharedEvent_id; + + + @@ -800,6 +808,7 @@ typedef void* MTLSharedEvent_id; + WSI extensions @@ -1717,7 +1726,7 @@ typedef void* MTLSharedEvent_id; VkStructureType sType void* pNext - + VkStructureType sType const void* pNext VkPipelineLayoutCreateFlags flags @@ -6386,11 +6395,172 @@ typedef void* MTLSharedEvent_id; void* pNext VkBool32 depthClipControl + + VkStructureType sType + void* pNext + VkBool32 deviceGeneratedCommands + VkBool32 dynamicGeneratedPipelineLayout + + + VkStructureType sType + void* pNext + uint32_t maxIndirectPipelineCount + uint32_t maxIndirectShaderObjectCount + uint32_t maxIndirectSequenceCount + uint32_t maxIndirectCommandsTokenCount + uint32_t maxIndirectCommandsTokenOffset + uint32_t maxIndirectCommandsIndirectStride + VkIndirectCommandsInputModeFlagsEXT supportedIndirectCommandsInputModes + VkShaderStageFlags supportedIndirectCommandsShaderStages + VkShaderStageFlags supportedIndirectCommandsShaderStagesPipelineBinding + VkShaderStageFlags supportedIndirectCommandsShaderStagesShaderBinding + VkBool32 deviceGeneratedCommandsTransformFeedback + VkBool32 deviceGeneratedCommandsMultiDrawIndirectCount + + + VkStructureType sType + void* pNext + VkPipeline pipeline + + + VkStructureType sType + void* pNext + uint32_t shaderCount + const VkShaderEXT* pShaders + + + VkStructureType sType + void* pNext + VkIndirectExecutionSetEXT indirectExecutionSet + VkIndirectCommandsLayoutEXT indirectCommandsLayout + uint32_t maxSequenceCount + uint32_t maxDrawCount + + + VkStructureType sType + const void* pNext + VkPipeline initialPipeline + uint32_t maxPipelineCount + + + VkStructureType sType + const void* pNext + uint32_t setLayoutCount + const VkDescriptorSetLayout* pSetLayouts + + + VkStructureType sType + const void* pNext + uint32_t shaderCount + const VkShaderEXT* pInitialShaders + const VkIndirectExecutionSetShaderLayoutInfoEXT* pSetLayoutInfos + uint32_t maxShaderCount + uint32_t pushConstantRangeCount + const VkPushConstantRange* pPushConstantRanges + + + const VkIndirectExecutionSetPipelineInfoEXT* pPipelineInfo + const VkIndirectExecutionSetShaderInfoEXT* pShaderInfo + + + VkStructureType sType + const void* pNext + VkIndirectExecutionSetInfoTypeEXT type + VkIndirectExecutionSetInfoEXT info + + + VkStructureType sType + const void* pNext + VkShaderStageFlags shaderStages + VkIndirectExecutionSetEXT indirectExecutionSet + VkIndirectCommandsLayoutEXT indirectCommandsLayout + VkDeviceAddress indirectAddress + VkDeviceSize indirectAddressSize + VkDeviceAddress preprocessAddress + VkDeviceSize preprocessSize + uint32_t maxSequenceCount + VkDeviceAddress sequenceCountAddress + uint32_t maxDrawCount + + + VkStructureType sType + const void* pNext + uint32_t index + VkPipeline pipeline + + + VkStructureType sType + const void* pNext + uint32_t index + VkShaderEXT shader + + + VkStructureType sType + const void* pNext + VkIndirectCommandsLayoutUsageFlagsEXT flags + VkShaderStageFlags shaderStages + uint32_t indirectStride + VkPipelineLayout pipelineLayout + uint32_t tokenCount + const VkIndirectCommandsLayoutTokenEXT* pTokens + + + VkStructureType sType + const void* pNext + VkIndirectCommandsTokenTypeEXT type + VkIndirectCommandsTokenDataEXT data + uint32_t offset + + + VkDeviceAddress bufferAddress + uint32_t stride + uint32_t commandCount + + + uint32_t vertexBindingUnit + + + VkDeviceAddress bufferAddress + uint32_t size + uint32_t stride + + + VkIndirectCommandsInputModeFlagBitsEXT mode + + + VkDeviceAddress bufferAddress + uint32_t size + VkIndexType indexType + + + VkPushConstantRange updateRange + + + VkIndirectExecutionSetInfoTypeEXT type + VkShaderStageFlags shaderStages + + + const VkIndirectCommandsPushConstantTokenEXT* pPushConstant + const VkIndirectCommandsVertexBufferTokenEXT* pVertexBuffer + const VkIndirectCommandsIndexBufferTokenEXT* pIndexBuffer + const VkIndirectCommandsExecutionSetTokenEXT* pExecutionSet + VkStructureType sType const void* pNext VkBool32 negativeOneToOne + + VkStructureType sType + void* pNext + VkBool32 depthClampControl + + + VkStructureType sType + const void* pNext + VkDepthClampModeEXT depthClampMode + const VkDepthClampRangeEXT* pDepthClampRange + VkStructureType sType void* pNext @@ -9240,6 +9410,10 @@ typedef void* MTLSharedEvent_id; void* pNext VkBool32 shaderReplicatedComposites + + float minDepthClamp + float maxDepthClamp + @@ -11326,6 +11500,30 @@ typedef void* MTLSharedEvent_id; + + + + + + + + + + + + + + + + + + + + + + + + @@ -11400,6 +11598,10 @@ typedef void* MTLSharedEvent_id; + + + + @@ -12861,6 +13063,66 @@ typedef void* MTLSharedEvent_id; VkIndirectCommandsLayoutNV indirectCommandsLayout const VkAllocationCallbacks* pAllocator + + + void vkCmdExecuteGeneratedCommandsEXT + VkCommandBuffer commandBuffer + VkBool32 isPreprocessed + const VkGeneratedCommandsInfoEXT* pGeneratedCommandsInfo + + + void vkCmdPreprocessGeneratedCommandsEXT + VkCommandBuffer commandBuffer + const VkGeneratedCommandsInfoEXT* pGeneratedCommandsInfo + VkCommandBuffer stateCommandBuffer + + + void vkGetGeneratedCommandsMemoryRequirementsEXT + VkDevice device + const VkGeneratedCommandsMemoryRequirementsInfoEXT* pInfo + VkMemoryRequirements2* pMemoryRequirements + + + VkResult vkCreateIndirectCommandsLayoutEXT + VkDevice device + const VkIndirectCommandsLayoutCreateInfoEXT* pCreateInfo + const VkAllocationCallbacks* pAllocator + VkIndirectCommandsLayoutEXT* pIndirectCommandsLayout + + + void vkDestroyIndirectCommandsLayoutEXT + VkDevice device + VkIndirectCommandsLayoutEXT indirectCommandsLayout + const VkAllocationCallbacks* pAllocator + + + VkResult vkCreateIndirectExecutionSetEXT + VkDevice device + const VkIndirectExecutionSetCreateInfoEXT* pCreateInfo + const VkAllocationCallbacks* pAllocator + VkIndirectExecutionSetEXT* pIndirectExecutionSet + + + void vkDestroyIndirectExecutionSetEXT + VkDevice device + VkIndirectExecutionSetEXT indirectExecutionSet + const VkAllocationCallbacks* pAllocator + + + void vkUpdateIndirectExecutionSetPipelineEXT + VkDevice device + VkIndirectExecutionSetEXT indirectExecutionSet + uint32_t executionSetWriteCount + const VkWriteIndirectExecutionSetPipelineEXT* pExecutionSetWrites + + + void vkUpdateIndirectExecutionSetShaderEXT + VkDevice device + VkIndirectExecutionSetEXT indirectExecutionSet + uint32_t executionSetWriteCount + const VkWriteIndirectExecutionSetShaderEXT* pExecutionSetWrites + + void vkGetPhysicalDeviceFeatures2 VkPhysicalDevice physicalDevice @@ -15561,6 +15823,12 @@ typedef void* MTLSharedEvent_id; VkCommandBuffer commandBuffer const VkRenderingInputAttachmentIndexInfoKHR* pInputAttachmentIndexInfo + + void vkCmdSetDepthClampRangeEXT + VkCommandBuffer commandBuffer + VkDepthClampModeEXT depthClampMode + const VkDepthClampRangeEXT* pDepthClampRange + @@ -17883,6 +18151,7 @@ typedef void* MTLSharedEvent_id; + @@ -19309,7 +19578,7 @@ typedef void* MTLSharedEvent_id; - + @@ -19593,8 +19862,8 @@ typedef void* MTLSharedEvent_id; - - + + @@ -20134,6 +20403,10 @@ typedef void* MTLSharedEvent_id; + + + + @@ -20459,6 +20732,7 @@ typedef void* MTLSharedEvent_id; + @@ -21114,6 +21388,7 @@ typedef void* MTLSharedEvent_id; + @@ -21665,6 +21940,11 @@ typedef void* MTLSharedEvent_id; + + + + + @@ -21923,6 +22203,10 @@ typedef void* MTLSharedEvent_id; + + + + @@ -21945,6 +22229,7 @@ typedef void* MTLSharedEvent_id; + @@ -22606,6 +22891,9 @@ typedef void* MTLSharedEvent_id; + + + @@ -22884,6 +23172,7 @@ typedef void* MTLSharedEvent_id; + @@ -23763,6 +24052,7 @@ typedef void* MTLSharedEvent_id; + @@ -23926,6 +24216,9 @@ typedef void* MTLSharedEvent_id; + + + @@ -24149,6 +24442,7 @@ typedef void* MTLSharedEvent_id; + @@ -24270,6 +24564,7 @@ typedef void* MTLSharedEvent_id; + @@ -24815,13 +25110,82 @@ typedef void* MTLSharedEvent_id; - + - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + @@ -24889,10 +25253,19 @@ typedef void* MTLSharedEvent_id; - + - - + + + + + + + + + + + @@ -25030,6 +25403,18 @@ typedef void* MTLSharedEvent_id; + + + + + + + + + + + + @@ -27304,6 +27689,9 @@ typedef void* MTLSharedEvent_id; + + + @@ -27444,6 +27832,12 @@ typedef void* MTLSharedEvent_id; + + + + + + @@ -27523,8 +27917,8 @@ typedef void* MTLSharedEvent_id; VK_PIPELINE_STAGE_2_SUBPASS_SHADER_BIT_HUAWEI - - VK_PIPELINE_STAGE_2_COMMAND_PREPROCESS_BIT_NV + + VK_PIPELINE_STAGE_2_COMMAND_PREPROCESS_BIT_EXT VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_BUILD_BIT_KHR @@ -27552,12 +27946,7 @@ typedef void* MTLSharedEvent_id; - - - - - - +