diff --git a/.reuse/dep5 b/.reuse/dep5 index f8d1c43ec4..0d64e3e615 100644 --- a/.reuse/dep5 +++ b/.reuse/dep5 @@ -2,7 +2,7 @@ Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/ Upstream-Name: Vulkan-Docs Source: https://github.com/KhronosGroup/Vulkan-Docs -Files: images/*.svg config/chunkindex/custom.patch config/CI/contractions* +Files: images/*.svg config/chunkindex/custom.patch config/CI/contractions* config/CI/txt-files-allowed Copyright: 2015-2022 The Khronos Group Inc. License: CC-BY-4.0 diff --git a/ChangeLog.adoc b/ChangeLog.adoc index 966619eb96..ca3a31130f 100644 --- a/ChangeLog.adoc +++ b/ChangeLog.adoc @@ -11,6 +11,70 @@ public pull requests that have been accepted. ----------------------------------------------------- +Change log for September 1, 2022 Vulkan 1.3.226 spec update: + +Public Issues: + + * Add missing SPV_KHR_ray_tracing storage class valid usage statement for + code:ShaderRecordBufferKHR (public merge request 1895). + * Add a NOTE to slink:VkAccelerationStructureCreateInfoKHR about + ename:VK_ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR (public issue 1904). + * Add a standalone SPIR-V valid usage statement for code:OpImageWrite + component mismatch (public merge request 1916). + * Generate the "`SPIRV Image Format`" and "`Plane Compatibility Format`" + tables from `vk.xml` (public merge request 1922). + * Add a NOTE to dlink:VK_USE_64_BIT_PTR_DEFINES to define its availability + Vulkan headers starting with VK_HEADER_VERSION 174 (public merge request + 1918). + +Internal Issues: + + * Update issue #2 in the apiext:VK_EXT_depth_range_unrestricted appendix + to match core spec text (internal issue 2445). + * Clarify <> + in pre-rasterization (internal issue 2721). + * Relax implicit layer disabling requirements in slink:VkApplicationInfo + (internal issue 2856). + * Update `extension` attribute in XML to support multiple + extensions with AND/OR connectives (internal issue 2922). + * Update provisional video API queries for usage hint and optimized + implementation settings (internal issue 2986). + * Relax slink:VkImageViewCreateInfo valid usage statement 01584 to allow + layers/levels for compressed format views of compressed format images + (internal issue 3063). + * Remove slink:VkImageViewCreateInfo valid usage statement 04739 (internal + issue 3164). + * Specify that addresses returned by flink:vkGetBufferDeviceAddress must + satisfy the alignment requirements of the device (internal issue 3176). + * Update makeSpec script to properly clean OUTDIR when it's explicitly + specified (internal issue 3194). + * Ensure that a mutable type list is provided in + slink:VkDescriptorSetLayoutCreateInfo when required (internal issue + 3198). + * Update clarity of the Khronos specification copyright statement + regarding normative references to external specifications and the + Khronos Intellectual Property Rights Policy (internal issue 3203). + * Rename '.txt' -> '.adoc' for all asciidoctor markup files in the + repository, and update scripts and tools to match (internal issue 3204) + * Tag apiext:VK_ARM_rasterization_order_attachment_access as promoted to + EXT in XML (internal merge request 5364) + * Fix a typo in the "` Color Sample Coverage`" section (internal merge + request 5367) + * Fix apiext:VK_EXT_fragment_density_map2 appendix to include the correct + extension interface information (internal merge request 5368) + * Remove unwieldy and unnecessary list of copy functions from the + introduction of the <> chapter (merge request + 5373). + * Move asciidoctor attributes enabling version and extension attributes + into a generated file `specattribs.adoc` (internal merge request 5396). + +New Extensions + + * apiext:VK_EXT_depth_clamp_01 + * apiext:VK_EXT_mesh_shader + +----------------------------------------------------- + Change log for August 18, 2022 Vulkan 1.3.225 spec update: * Update release number to 225 for this update. diff --git a/LICENSES/LicenseRef-KhronosSpecCopyright.adoc b/LICENSES/LicenseRef-KhronosSpecCopyright.adoc index 2ec6a39a7f..17424881d0 100644 --- a/LICENSES/LicenseRef-KhronosSpecCopyright.adoc +++ b/LICENSES/LicenseRef-KhronosSpecCopyright.adoc @@ -5,64 +5,82 @@ proprietary to Khronos. Except as described by these terms, it or any components may not be reproduced, republished, distributed, transmitted, displayed, broadcast or otherwise exploited in any manner without the express prior written permission of Khronos. + Khronos grants a conditional copyright license to use and reproduce the unmodified Specification for any purpose, without fee or royalty, EXCEPT no licenses to any patent, trademark or other intellectual property rights are -granted under these terms. +granted under these terms. Parties desiring to implement the Specification +and make use of Khronos trademarks in relation to that implementation, and +receive reciprocal patent license protection under the Khronos IP Policy +must become Adopters and confirm the implementation as conformant under the +process defined by Khronos for this Specification; see +https://www.khronos.org/adopters. Khronos makes no, and expressly disclaims any, representations or warranties, express or implied, regarding this Specification, including, without limitation: merchantability, fitness for a particular purpose, non-infringement of any intellectual property, correctness, accuracy, -completeness, timeliness, and reliability. -Under no circumstances will Khronos, or any of its Promoters, Contributors -or Members, or their respective partners, officers, directors, employees, -agents or representatives be liable for any damages, whether direct, -indirect, special or consequential damages for lost revenues, lost profits, -or otherwise, arising from or in connection with these materials. +completeness, timeliness, and reliability. Under no circumstances will +Khronos, or any of its Promoters, Contributors or Members, or their +respective partners, officers, directors, employees, agents or +representatives be liable for any damages, whether direct, indirect, special +or consequential damages for lost revenues, lost profits, or otherwise, +arising from or in connection with these materials. This Specification has been created under the Khronos Intellectual Property Rights Policy, which is Attachment A of the Khronos Group Membership -Agreement available at https://www.khronos.org/files/member_agreement.pdf, and which -defines the terms 'Scope', 'Compliant Portion', and 'Necessary Patent Claims'. -Parties desiring to implement the Specification and make use of Khronos trademarks -in relation to that implementation, and receive reciprocal patent license protection -under the Khronos Intellectual Property Rights Policy must become Adopters and -confirm the implementation as conformant under the process defined by Khronos for -this Specification; see https://www.khronos.org/adopters. +Agreement available at https://www.khronos.org/files/member_agreement.pdf. + +// "Successor Specification" section + +This Specification contains substantially unmodified functionality from, and +is a successor to, Khronos specifications including OpenGL, OpenGL ES and +OpenCL. + +// End "Successor Specification" section + +// "Normative Wording" section -This Specification contains substantially unmodified functionality from, and is a -successor to, Khronos specifications including OpenGL, OpenGL ES and OpenCL. +The Khronos Intellectual Property Rights defines the terms 'Scope', +'Compliant Portion', and 'Necessary Patent Claims'. Some parts of this Specification are purely informative and so are EXCLUDED from the Scope of this Specification. The <> section of the <> defines how these parts of the Specification are identified. Where this Specification uses <>, defined in the <> or otherwise, that refer to -enabling technologies that are not expressly set forth in this -Specification, those enabling technologies are EXCLUDED from the Scope of -this Specification. -For clarity, enabling technologies not disclosed with particularity in this -Specification (e.g. semiconductor manufacturing technology, hardware -architecture, processor architecture or microarchitecture, memory -architecture, compiler technology, object oriented technology, basic -operating system technology, compression technology, algorithms, and so on) -are NOT to be considered expressly set forth; only those application program -interfaces and data structures disclosed with particularity are included in -the Scope of this Specification. - -For purposes of the Khronos Intellectual Property Rights Policy as it relates -to the definition of Necessary Patent Claims, all recommended or optional -features, behaviors and functionality set forth in this Specification, if -implemented, are considered to be included as Compliant Portions. - -Where this Specification includes <>, only the specifically -identified sections of those external documents are INCLUDED in the Scope of -this Specification. If not created by Khronos, those external documents may -contain contributions from non-members of Khronos not covered by the Khronos -Intellectual Property Rights Policy. +terminology>>, defined in the <> or otherwise, that +refer to enabling technologies that are not expressly set +forth in this Specification, those enabling technologies are EXCLUDED from +the Scope of this Specification. For clarity, enabling technologies not +disclosed with particularity in this Specification (e.g. semiconductor +manufacturing technology, hardware architecture, processor architecture or +microarchitecture, memory architecture, compiler technology, object oriented +technology, basic operating system technology, compression technology, +algorithms, and so on) are NOT to be considered expressly set forth; only +those application program interfaces and data structures disclosed with +particularity are included in the Scope of this Specification. + +For purposes of the Khronos Intellectual Property Rights Policy as it +relates to the definition of Necessary Patent Claims, all recommended or +optional features, behaviors and functionality set forth in this +Specification, if implemented, are considered to be included as Compliant +Portions. + +// End "Normative Wording" section + +// "External References" section + +Where this Specification identifies specific sections of external +references, only those specifically identified sections define +<> +functionality. The Khronos Intellectual Property Rights Policy excludes +external references to materials and associated enabling technology not +created by Khronos from the Scope of this specification, and any licenses +that may be required to implement such referenced materials and associated +technologies must be obtained separately and may involve royalty payments. + +// End "External References" section ifndef::ratified_core_spec[] This document contains extensions which are not ratified by Khronos, and as @@ -75,9 +93,9 @@ https://registry.khronos.org/vulkan/specs/1.2-khr-extensions/html/vkspec.html (core with KHR extensions). endif::ratified_core_spec[] -Vulkan and Khronos are registered trademarks of The Khronos Group Inc. -ASTC is a trademark of ARM Holdings PLC; OpenCL is a trademark of Apple -Inc.; and OpenGL and OpenGL ES are registered trademarks of Hewlett Packard -Enterprise, all used under license by Khronos. All other product names, +Khronos and Vulkan are registered trademarks of The Khronos Group Inc. +OpenCL is a trademark of Apple Inc.; and OpenGL and OpenGL ES are registered +trademarks of Hewlett Packard Enterprise, all used under license by Khronos. +ASTC is a trademark of ARM Holdings PLC. All other product names, trademarks, and/or company names are used solely for identification and belong to their respective owners. diff --git a/Makefile b/Makefile index 92c634da2f..63ac1a0816 100644 --- a/Makefile +++ b/Makefile @@ -8,14 +8,14 @@ # $(VERSIONS) variable on the make command line to a space-separated # list of version names (e.g. VK_VERSION_1_3) *including all previous # versions of the API* (e.g. VK_VERSION_1_1 must also include -# VK_VERSION_1_0). $(VERSIONS) is converted into asciidoc and generator -# script arguments $(VERSIONATTRIBS) and $(VERSIONOPTIONS) +# VK_VERSION_1_0). $(VERSIONS) is converted into generator +# script arguments $(VERSIONOPTIONS) and into $(ATTRIBFILE) # # To build the specification / reference pages (refpages) with optional # extensions included, set the $(EXTENSIONS) variable on the make # command line to a space-separated list of extension names. -# $(EXTENSIONS) is converted into asciidoc and generator script -# arguments $(EXTATTRIBS) and $(EXTOPTIONS). +# $(EXTENSIONS) is converted into generator script +# arguments $(EXTOPTIONS) and into $(ATTRIBFILE) # If a recipe fails, delete its target file. Without this cleanup, the leftover # file from the failed recipe can falsely satisfy dependencies on subsequent @@ -23,11 +23,9 @@ .DELETE_ON_ERROR: VERSIONS := VK_VERSION_1_0 VK_VERSION_1_1 VK_VERSION_1_2 VK_VERSION_1_3 -VERSIONATTRIBS := $(foreach version,$(VERSIONS),-a $(version)) VERSIONOPTIONS := $(foreach version,$(VERSIONS),-feature $(version)) EXTS := $(sort $(EXTENSIONS) $(DIFFEXTENSIONS)) -EXTATTRIBS := $(foreach ext,$(EXTS),-a $(ext)) EXTOPTIONS := $(foreach ext,$(EXTS),-extension $(ext)) # APITITLE can be set to extra text to append to the document title, @@ -70,7 +68,7 @@ check-contractions: fi # Look for typos and suggest fixes -CODESPELL = codespell --config config/CI/codespellrc +CODESPELL = codespell --config config/CI/codespellrc -S '*.js' check-spelling: if ! $(CODESPELL) > /dev/null ; then \ echo "Found probable misspellings. Corrections can be added to config/CI/codespell-allowed:" ; \ @@ -106,7 +104,7 @@ check-undefined: $(SCRIPTS)/ci/check_undefined # Look for '.txt' files, which should almost all be .adoc now -CHECK_TXTFILES = find . -name '*.txt' | egrep -v '^\./LICENSES/' +CHECK_TXTFILES = find . -name '*.txt' | egrep -v -E -f config/CI/txt-files-allowed check-txtfiles: if test `$(CHECK_TXTFILES) | wc -l` != 0 ; then \ echo "*.txt files found that are not allowed (use .adoc):" ; \ @@ -156,17 +154,13 @@ VERBOSE = # NOTEOPTS sets options controlling which NOTEs are generated # PATCHVERSION must equal VK_HEADER_VERSION from vk.xml # ATTRIBOPTS sets the API revision and enables KaTeX generation -# VERSIONATTRIBS sets attributes for enabled API versions (set above -# based on $(VERSIONS)) -# EXTATTRIBS sets attributes for enabled extensions (set above based on -# $(EXTENSIONS)) # EXTRAATTRIBS sets additional attributes, if passed to make # ADOCMISCOPTS miscellaneous options controlling error behavior, etc. # ADOCEXTS asciidoctor extensions to load # ADOCOPTS options for asciidoc->HTML5 output NOTEOPTS = -a editing-notes -a implementation-guide -PATCHVERSION = 225 +PATCHVERSION = 226 ifneq (,$(findstring VK_VERSION_1_3,$(VERSIONS))) SPECMINOR = 3 @@ -219,8 +213,6 @@ ATTRIBOPTS = -a revnumber="$(SPECREVISION)" \ -a images=$(IMAGEPATH) \ -a generated=$(GENERATED) \ -a refprefix \ - $(VERSIONATTRIBS) \ - $(EXTATTRIBS) \ $(EXTRAATTRIBS) ADOCMISCOPTS = --failure-level ERROR # Non target-specific Asciidoctor extensions and options @@ -293,8 +285,9 @@ INTERFACEDEPEND = $(INTERFACEPATH)/timeMarker SPIRVCAPDEPEND = $(SPIRVCAPPATH)/timeMarker FORMATSDEPEND = $(FORMATSPATH)/timeMarker RUBYDEPEND = $(RBAPIMAP) +ATTRIBFILE = $(GENERATED)/specattribs.adoc # All generated dependencies -GENDEPENDS = $(APIDEPEND) $(VALIDITYDEPEND) $(HOSTSYNCDEPEND) $(METADEPEND) $(INTERFACEDEPEND) $(SPIRVCAPDEPEND) $(FORMATSDEPEND) $(RUBYDEPEND) +GENDEPENDS = $(APIDEPEND) $(VALIDITYDEPEND) $(HOSTSYNCDEPEND) $(METADEPEND) $(INTERFACEDEPEND) $(SPIRVCAPDEPEND) $(FORMATSDEPEND) $(RUBYDEPEND) $(ATTRIBFILE) # All non-format-specific dependencies COMMONDOCS = $(SPECFILES) $(GENDEPENDS) @@ -461,7 +454,8 @@ CLEAN_GEN_PATHS = \ $(GENERATED)/__pycache__ \ $(PDFMATHDIR) \ $(PYAPIMAP) \ - $(RBAPIMAP) + $(RBAPIMAP) \ + $(ATTRIBFILE) clean_generated: $(QUIET)$(RMRF) $(CLEAN_GEN_PATHS) @@ -652,5 +646,14 @@ $(FORMATSDEPEND): $(VKXML) $(GENVK) $(QUIET)$(MKDIR) $(FORMATSPATH) $(QUIET)$(PYTHON) $(GENVK) $(GENVKOPTS) -o $(FORMATSPATH) formatsinc +# This generates a single file containing asciidoc attributes for each +# core version and extension in the spec being built. +attribs: $(ATTRIBFILE) + +$(ATTRIBFILE): + for attrib in $(VERSIONS) $(EXTS) ; do \ + echo ":$${attrib}:" ; \ + done > $@ + # Debugging aid - generate all files from registry XML generated: $(PYAPIMAP) $(GENDEPENDS) diff --git a/appendices/VK_EXT_depth_clamp_zero_one.adoc b/appendices/VK_EXT_depth_clamp_zero_one.adoc new file mode 100644 index 0000000000..8304614920 --- /dev/null +++ b/appendices/VK_EXT_depth_clamp_zero_one.adoc @@ -0,0 +1,29 @@ +// Copyright 2017-2022 The Khronos Group Inc. +// +// SPDX-License-Identifier: CC-BY-4.0 + +include::{generated}/meta/{refprefix}VK_EXT_depth_clamp_zero_one.adoc[] + +=== Other Extension Metadata + +*Last Modified Date*:: + 2021-07-29 +*Contributors*:: + - Graeme Leese, Broadcom + +=== Description + +This extension gives defined behavior to fragment depth values which end up +outside the conventional [0, 1] range. +It can be used to ensure portability in edge cases of features like +depthBias. +The particular behavior is chosen to match OpenGL to aid porting or +emulation. + +include::{generated}/interfaces/VK_EXT_depth_clamp_zero_one.adoc[] + + +=== Version History + + * Revision 1, 2021-07-29 (Graeme Leese) + ** Internal revisions diff --git a/appendices/VK_EXT_depth_range_unrestricted.adoc b/appendices/VK_EXT_depth_range_unrestricted.adoc index b5f1c4c4c2..76501a6efa 100644 --- a/appendices/VK_EXT_depth_range_unrestricted.adoc +++ b/appendices/VK_EXT_depth_range_unrestricted.adoc @@ -43,9 +43,10 @@ the `0.0` to `1.0` range. 2) What happens if a resulting depth fragment is outside of the `0.0` to `1.0` range and the depth buffer is fixed-point rather than floating-point? -*RESOLVED*: This situation can also arise without this extension (when fragment -shaders replace depth values, for example), and this extension does not change -the behaviour, which is defined in the <> section of the Fragment Operations chapter. +*RESOLVED*: This situation can also arise without this extension (when +fragment shaders replace depth values, for example), and this extension does +not change the behaviour, which is defined in the <> section of the Fragment Operations chapter. === Version History diff --git a/appendices/VK_EXT_mesh_shader.adoc b/appendices/VK_EXT_mesh_shader.adoc new file mode 100644 index 0000000000..ddb63b3172 --- /dev/null +++ b/appendices/VK_EXT_mesh_shader.adoc @@ -0,0 +1,95 @@ +// Copyright (c) 2018-2020 NVIDIA Corporation +// +// SPDX-License-Identifier: CC-BY-4.0 + +include::{generated}/meta/{refprefix}VK_EXT_mesh_shader.adoc[] + +=== Other Extension Metadata + +*Last Modified Date*:: + 2022-01-20 +*Interactions and External Dependencies*:: + - This extension requires + {spirv}/EXT/SPV_EXT_mesh_shader.html[`SPV_EXT_mesh_shader`] + - This extension provides API support for + https://github.com/KhronosGroup/GLSL/blob/master/extensions/ext/GLSL_EXT_mesh_shader.txt[`GLSL_EXT_mesh_shader`] + - Interacts with Vulkan 1.1 + - Interacts with `apiext:VK_KHR_multiview` + - Interacts with `apiext:VK_KHR_fragment_shading_rate` +*Contributors*:: + - Christoph Kubisch, NVIDIA + - Pat Brown, NVIDIA + - Jeff Bolz, NVIDIA + - Daniel Koch, NVIDIA + - Piers Daniell, NVIDIA + - Pierre Boudier, NVIDIA + - Patrick Mours, NVIDIA + - David Zhao Akeley, NVIDIA + - Kedarnath Thangudu, NVIDIA + - Timur Kristóf, Valve + - Hans-Kristian Arntzen, Valve + - Philip Rebohle, Valve + - Mike Blumenkrantz, Valve + - Slawomir Grajewski, Intel + - Michal Pietrasiuk, Intel + - Mariusz Merecki, Intel + - Tom Olson, ARM + - Jan-Harald Fredriksen, ARM + - Sandeep Kakarlapudi, ARM + - Ruihao Zhang, QUALCOMM + - Ricardo Garcia, Igalia, S.L. + - Tobias Hector, AMD + - Stu Smith, AMD + + +=== Description + +This extension provides a new mechanism allowing applications to generate +collections of geometric primitives via programmable mesh shading. +It is an alternative to the existing programmable primitive shading +pipeline, which relied on generating input primitives by a fixed function +assembler as well as fixed function vertex fetch. + +This extension also adds support for the following SPIR-V extension in +Vulkan: + + * {spirv}/EXT/SPV_EXT_mesh_shader.html[`SPV_EXT_mesh_shader`] + +include::{generated}/interfaces/VK_EXT_mesh_shader.adoc[] + + +=== New or Modified Built-In Variables + + * <> + * <> + * <> + * <> + * (modified)code:Position + * (modified)code:PointSize + * (modified)code:ClipDistance + * (modified)code:CullDistance + * (modified)code:PrimitiveId + * (modified)code:Layer + * (modified)code:ViewportIndex + * (modified)code:NumWorkgroups + * (modified)code:WorkgroupSize + * (modified)code:WorkgroupId + * (modified)code:LocalInvocationId + * (modified)code:GlobalInvocationId + * (modified)code:LocalInvocationIndex + * (modified)code:NumSubgroups + * (modified)code:SubgroupId + * (modified)code:DrawIndex + * (modified)code:PrimitiveShadingRateKHR + * (modified)code:ViewIndex + + +=== New SPIR-V Capability + + * <> + + +=== Version History + + * Revision 1, 2022-03-08 (Christoph Kubisch, Daniel Koch, Patrick Mours) + ** Initial revision diff --git a/appendices/glossary.adoc b/appendices/glossary.adoc index a36cb031eb..45a7070358 100644 --- a/appendices/glossary.adoc +++ b/appendices/glossary.adoc @@ -463,6 +463,9 @@ endif::VK_EXT_multi_draw[] ifdef::VK_NV_mesh_shader[] flink:vkCmdDrawMeshTasksNV, endif::VK_NV_mesh_shader[] +ifdef::VK_EXT_mesh_shader[] + flink:vkCmdDrawMeshTasksEXT, +endif::VK_EXT_mesh_shader[] flink:vkCmdDraw, and flink:vkCmdDrawIndexed. ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] @@ -505,6 +508,10 @@ ifdef::VK_NV_mesh_shader[] flink:vkCmdDrawMeshTasksNV, flink:vkCmdDrawMeshTasksIndirectNV, flink:vkCmdDrawMeshTasksIndirectCountNV, endif::VK_NV_mesh_shader[] +ifdef::VK_EXT_mesh_shader[] + flink:vkCmdDrawMeshTasksEXT, flink:vkCmdDrawMeshTasksIndirectEXT, + flink:vkCmdDrawMeshTasksIndirectCountEXT, +endif::VK_EXT_mesh_shader[] flink:vkCmdDrawIndirect, and flink:vkCmdDrawIndexedIndirect. Duration (Command):: @@ -706,7 +713,7 @@ Global Command:: Global Workgroup:: A collection of local workgroups dispatched by a single dispatching -ifdef::VK_NV_mesh_shader[or single mesh task drawing] +ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[or single mesh task drawing] command. Handle:: @@ -860,6 +867,10 @@ ifdef::VK_NV_mesh_shader[] flink:vkCmdDrawMeshTasksIndirectNV, flink:vkCmdDrawMeshTasksIndirectCountNV, endif::VK_NV_mesh_shader[] +ifdef::VK_EXT_mesh_shader[] + flink:vkCmdDrawMeshTasksIndirectEXT, + flink:vkCmdDrawMeshTasksIndirectCountEXT, +endif::VK_EXT_mesh_shader[] and flink:vkCmdDispatchIndirect. ifdef::VK_NV_device_generated_commands[] @@ -890,6 +901,10 @@ ifdef::VK_NV_mesh_shader[] flink:vkCmdDrawMeshTasksIndirectNV, flink:vkCmdDrawMeshTasksIndirectCountNV, endif::VK_NV_mesh_shader[] +ifdef::VK_EXT_mesh_shader[] + flink:vkCmdDrawMeshTasksIndirectEXT, + flink:vkCmdDrawMeshTasksIndirectCountEXT, +endif::VK_EXT_mesh_shader[] and flink:vkCmdDrawIndexedIndirect. Initial State (Command Buffer):: @@ -1073,21 +1088,27 @@ Memory Type:: An index used to select a set of memory properties (e.g. mappable, cached) for a device memory allocation. -ifdef::VK_NV_mesh_shader[] +ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] Mesh Shading Pipeline:: A graphics pipeline where the primitives are assembled explicitly in the shader stages. In contrast to the primitive shading pipeline where input primitives are assembled by fixed function processing. -endif::VK_NV_mesh_shader[] -ifdef::VK_NV_mesh_shader[] Mesh Tasks Drawing Commands:: _Drawing commands_ which create shader invocations organized in workgroups for drawing mesh tasks. - Includes flink:vkCmdDrawMeshTasksNV, flink:vkCmdDrawMeshTasksIndirectNV, - and flink:vkCmdDrawMeshTasksIndirectCountNV. + Includes +ifdef::VK_NV_mesh_shader[] + flink:vkCmdDrawMeshTasksNV, flink:vkCmdDrawMeshTasksIndirectNV, and + flink:vkCmdDrawMeshTasksIndirectCountNV, endif::VK_NV_mesh_shader[] +ifdef::VK_EXT_mesh_shader[] + flink:vkCmdDrawMeshTasksEXT, flink:vkCmdDrawMeshTasksIndirectEXT, and + flink:vkCmdDrawMeshTasksIndirectCountEXT +endif::VK_EXT_mesh_shader[] + . +endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] Minimum Miplevel Size:: The smallest size that is permitted for a miplevel. @@ -1317,12 +1338,12 @@ Primary Command Buffer:: A command buffer that can: execute secondary command buffers, and can: be submitted directly to a queue. -ifdef::VK_NV_mesh_shader[] +ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] Primitive Shading Pipeline:: A graphics pipeline where input primitives are assembled by fixed function processing. It is the counterpart to mesh shading. -endif::VK_NV_mesh_shader[] +endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] Primitive Topology:: State controlling how vertices are assembled into primitives, e.g. as diff --git a/appendices/spirvenv.adoc b/appendices/spirvenv.adoc index 2c63471859..735827750d 100644 --- a/appendices/spirvenv.adoc +++ b/appendices/spirvenv.adoc @@ -425,10 +425,18 @@ endif::VK_VERSION_1_1[] * [[VUID-{refpage}-OpGroupNonUniformBallotBitCount-04685]] If code:OpGroupNonUniformBallotBitCount is used, the group operation must: be limited to *Reduce*, *InclusiveScan*, or *ExclusiveScan* +ifndef::VK_EXT_mesh_shader[] * [[VUID-{refpage}-None-04686]] The _Pointer_ operand of all atomic instructions must: have a *Storage Class* limited to *Uniform*, *Workgroup*, *Image*, *StorageBuffer*, or *PhysicalStorageBuffer* +endif::VK_EXT_mesh_shader[] +ifdef::VK_EXT_mesh_shader[] + * [[VUID-{refpage}-None-07101]] + The _Pointer_ operand of all atomic instructions must: have a *Storage + Class* limited to *Uniform*, *Workgroup*, *Image*, *StorageBuffer*, + *PhysicalStorageBuffer*, or *TaskPayloadWorkgroupEXT* +endif::VK_EXT_mesh_shader[] * [[VUID-{refpage}-Offset-04687]] Output variables or block members decorated with code:Offset that have a 64-bit type, or a composite type containing a 64-bit type, must: specify @@ -564,6 +572,46 @@ endif::VK_VERSION_1_1[] * [[VUID-{refpage}-Input-06778]] Variables with a storage class of code:Input in a fragment shader stage that are decorated with code:PerVertexKHR must: be declared as arrays +ifdef::VK_NV_mesh_shader+VK_EXT_mesh_shader[] + * [[VUID-{refpage}-MeshEXT-07102]] + The module must: not contain both an entry point that uses the code: + TaskEXT or code:MeshEXT {ExecutionModel} and an entry point that uses + the code:TaskNV or code:MeshNV {ExecutionModel} +endif::VK_NV_mesh_shader+VK_EXT_mesh_shader[] + * [[VUID-{refpage}-PrimitivePointIndicesEXT-07103]] + If a variable decorated with code:PrimitivePointIndicesEXT is used, the + code:OutputPoints code:OpExecutionMode must: be set + * [[VUID-{refpage}-PrimitiveLineIndicesEXT-07104]] + If a variable decorated with code:PrimitiveLineIndicesEXT is used, the + code:OutputLinesEXT code:OpExecutionMode must: be set + * [[VUID-{refpage}-PrimitiveTriangleIndicesEXT-07105]] + If a variable decorated with code:PrimitiveTriangleIndicesEXT is used, + the code:OutputTrianglesEXT code:OpExecutionMode must: be set + * [[VUID-{refpage}-MeshEXT-07106]] + In mesh shaders using the code:MeshEXT {ExecutionModel} + code:OpSetMeshOutputsEXT must: be called before any outputs are written + * [[VUID-{refpage}-MeshEXT-07107]] + In mesh shaders using the code:MeshEXT {ExecutionModel} all variables + declared as output must: not be read from + * [[VUID-{refpage}-MeshEXT-07108]] + In mesh shaders using the code:MeshEXT {ExecutionModel} for + code:OpSetMeshOutputsEXT instructions, the "`Vertex Count`" and + "`Primitive Count`" operands must: not depend on code:ViewIndex + * [[VUID-{refpage}-MeshEXT-07109]] + In mesh shaders using the code:MeshEXT {ExecutionModel} variables + decorated with code:PrimitivePointIndicesEXT, + code:PrimitiveLineIndicesEXT or code:PrimitiveTriangleIndicesEXT + declared as an array must: not be accessed by indices that depend on + code:ViewIndex + * [[VUID-{refpage}-MeshEXT-07110]] + In mesh shaders using the code:MeshEXT {ExecutionModel} any values + stored in variables decorated with code:PrimitivePointIndicesEXT, + code:PrimitiveLineIndicesEXT or code:PrimitiveTriangleIndicesEXT must: + not depend on code:ViewIndex + * [[VUID-{refpage}-MeshEXT-07111]] + In mesh shaders using the code:MeshEXT {ExecutionModel} variables in + workgroup or private storage class declared as or containing a composite + type must: not be accessed by indices that depend on code:ViewIndex **** -- @@ -616,9 +664,10 @@ ifndef::VK_VERSION_1_3,VK_KHR_format_feature_flags2[] operand of 2 and an "`Image Format`" operand of code:Unknown must: be decorated with code:NonReadable. endif::VK_VERSION_1_3,VK_KHR_format_feature_flags2[] - * code:OpImageWrite to any code:Image whose code:Image code:Format is not - code:Unknown must: have the code:Texel operand contain at least - as many components as the corresponding elink:VkFormat as given in the + * [[VUID-{refpage}-OpImageWrite-07112]] + code:OpImageWrite to any code:Image whose code:Image code:Format is not + code:Unknown must: have the code:Texel operand contain at least as many + components as the corresponding elink:VkFormat as given in the <> * [[VUID-{refpage}-Location-06272]] The sum of code:Location and the number of locations the variable it @@ -958,6 +1007,36 @@ ifdef::VK_NV_cooperative_matrix[] alignment is the number of columns/rows multiplied by the component size). endif::VK_NV_cooperative_matrix[] +ifdef::VK_NV_mesh_shader[] + * [[VUID-{refpage}-MeshNV-07113]] + For mesh shaders using the code:MeshNV {ExecutionModel} the + code:OutputVertices code:OpExecutionMode must: be less than or equal to + sname:VkPhysicalDeviceMeshShaderPropertiesNV::pname:maxMeshOutputVertices. + * [[VUID-{refpage}-MeshNV-07114]] + For mesh shaders using the code:MeshNV {ExecutionModel} the + code:OutputPrimitivesNV code:OpExecutionMode must: be less than or equal + to + sname:VkPhysicalDeviceMeshShaderPropertiesNV::pname:maxMeshOutputPrimitives. +endif::VK_NV_mesh_shader[] +ifdef::VK_EXT_mesh_shader[] + * [[VUID-{refpage}-MeshEXT-07115]] + For mesh shaders using the code:MeshEXT {ExecutionModel} the + code:OutputVertices code:OpExecutionMode must: be less than or equal to + sname:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxMeshOutputVertices. + * [[VUID-{refpage}-MeshEXT-07116]] + For mesh shaders using the code:MeshEXT {ExecutionModel} the + code:OutputPrimitivesEXT code:OpExecutionMode must: be less than or + equal to + sname:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxMeshOutputPrimitives. + * [[VUID-{refpage}-TaskEXT-07117]] + In task shaders using the code:TaskEXT {ExecutionModel} + code:OpEmitMeshTasksEXT must: be called exactly once under dynamically + uniform conditions + * [[VUID-{refpage}-MeshEXT-07118]] + In mesh shaders using the code:MeshEXT {ExecutionModel} + code:OpSetMeshOutputsEXT must: be called at most once under dynamically + uniform conditions +endif::VK_EXT_mesh_shader[] ifdef::VK_KHR_portability_subset[] * [[VUID-{refpage}-shaderSampleRateInterpolationFunctions-06325]] If the `apiext:VK_KHR_portability_subset` extension is enabled, and @@ -1935,5 +2014,5 @@ values as defined below: [cols="2*", options="header"] |==== |SPIR-V Image Format |Compatible Vulkan Format -include::{generated}/formats/spirvimageformat.txt[] +include::{generated}/formats/spirvimageformat.adoc[] |==== diff --git a/chapters/VK_NV_device_generated_commands/generation.adoc b/chapters/VK_NV_device_generated_commands/generation.adoc index edb735b3ef..9177086152 100644 --- a/chapters/VK_NV_device_generated_commands/generation.adoc +++ b/chapters/VK_NV_device_generated_commands/generation.adoc @@ -228,6 +228,20 @@ include::{generated}/api/structs/VkGeneratedCommandsInfoNV.adoc[] 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[] diff --git a/chapters/VK_NV_device_generated_commands/indirectcommands.adoc b/chapters/VK_NV_device_generated_commands/indirectcommands.adoc index a5c9ee12ec..0dfd072da2 100644 --- a/chapters/VK_NV_device_generated_commands/indirectcommands.adoc +++ b/chapters/VK_NV_device_generated_commands/indirectcommands.adoc @@ -126,10 +126,11 @@ This enables direct compatibility with D3D12 command signature layouts. 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 prior work provoking + All state tokens in pname:pTokens must: occur before any work provoking 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_TASKS_NV, + ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_NV) * [[VUID-VkIndirectCommandsLayoutCreateInfoNV-pTokens-02935]] The content of pname:pTokens must: include one single work provoking token that is compatible with the pname:pipelineBindPoint @@ -250,6 +251,9 @@ commands such as: ifdef::VK_NV_mesh_shader[] * slink:VkDrawMeshTasksIndirectCommandNV endif::VK_NV_mesh_shader[] +ifdef::VK_EXT_mesh_shader[] +* slink:VkDrawMeshTasksIndirectCommandEXT +endif::VK_EXT_mesh_shader[] or additional commands as listed below. How the data is used is described in the next section. @@ -445,6 +449,9 @@ include::{generated}/api/enums/VkIndirectCommandsTokenTypeNV.adoc[] 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[] |==== -- @@ -631,10 +638,16 @@ void cmdProcessSequence(cmd, pipeline, indirectCommandsLayout, pIndirectCommands break; // only available if VK_NV_mesh_shader is supported - VK_INDIRECT_COMMANDS_TOKEN_TYPE_DISPATCH_NV: + 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 + VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_NV: + vkCmdDrawMeshTasksIndirectEXT(cmd, + stream.buffer, offset, 1, 0); + break; } } } diff --git a/chapters/VK_NV_mesh_shader/drawing.adoc b/chapters/VK_NV_mesh_shader/drawing.adoc index e154fb00bb..f2075a83ad 100644 --- a/chapters/VK_NV_mesh_shader/drawing.adoc +++ b/chapters/VK_NV_mesh_shader/drawing.adoc @@ -9,12 +9,12 @@ In this drawing approach, primitives are assembled by the mesh shader stage. <> operates similarly to <> as the shaders make use of workgroups. - +ifdef::VK_NV_mesh_shader[] [open,refpage='vkCmdDrawMeshTasksNV',desc='Draw mesh task work items',type='protos'] -- :refpage: vkCmdDrawMeshTasksNV -To record a draw that uses the mesh pipeline, call: +To record a mesh tasks drawing command, call: include::{generated}/api/protos/vkCmdDrawMeshTasksNV.adoc[] @@ -35,6 +35,9 @@ include::{chapters}/commonvalidity/draw_mesh_common.adoc[] * [[VUID-vkCmdDrawMeshTasksNV-taskCount-02119]] pname:taskCount must: be less than or equal to sname:VkPhysicalDeviceMeshShaderPropertiesNV::pname:maxDrawMeshTasksCount + * [[VUID-vkCmdDrawMeshTasksNV-MeshNV-07080]] + The current pipeline bound to ename:VK_PIPELINE_BIND_POINT_GRAPHICS + must: contain a shader stage using the code:MeshNV {ExecutionModel}. **** include::{generated}/validity/protos/vkCmdDrawMeshTasksNV.adoc[] @@ -44,7 +47,7 @@ include::{generated}/validity/protos/vkCmdDrawMeshTasksNV.adoc[] -- :refpage: vkCmdDrawMeshTasksIndirectNV -To record an indirect mesh tasks draw, call: +To record an indirect mesh tasks drawing command, call: include::{generated}/api/protos/vkCmdDrawMeshTasksIndirectNV.adoc[] @@ -86,6 +89,9 @@ include::{chapters}/commonvalidity/draw_indirect_drawcount.adoc[] (pname:drawCount - 1) {plus} pname:offset {plus} code:sizeof(slink:VkDrawMeshTasksIndirectCommandNV))# must: be less than or equal to the size of pname:buffer + * [[VUID-vkCmdDrawMeshTasksIndirectNV-MeshNV-07081]] + The current pipeline bound to ename:VK_PIPELINE_BIND_POINT_GRAPHICS + must: contain a shader stage using the code:MeshNV {ExecutionModel}. **** include::{generated}/validity/protos/vkCmdDrawMeshTasksIndirectNV.adoc[] @@ -119,8 +125,8 @@ include::{generated}/validity/structs/VkDrawMeshTasksIndirectCommandNV.adoc[] -- :refpage: vkCmdDrawMeshTasksIndirectCountNV -To record an indirect mesh tasks draw with the draw count sourced from a -buffer, call: +To record an indirect mesh tasks drawing command with the draw count sourced +from a buffer, call: include::{generated}/api/protos/vkCmdDrawMeshTasksIndirectCountNV.adoc[] @@ -169,8 +175,210 @@ include::{chapters}/commonvalidity/draw_indirect_count_common.adoc[] [eq]#(pname:stride {times} (pname:drawCount - 1) {plus} pname:offset {plus} code:sizeof(sname:VkDrawMeshTasksIndirectCommandNV))# must: be less than or equal to the size of pname:buffer + * [[VUID-vkCmdDrawMeshTasksIndirectCountNV-MeshNV-07082]] + The current pipeline bound to ename:VK_PIPELINE_BIND_POINT_GRAPHICS + must: contain a shader stage using the code:MeshNV {ExecutionModel}. **** include::{generated}/validity/protos/vkCmdDrawMeshTasksIndirectCountNV.adoc[] -- +endif::VK_NV_mesh_shader[] +ifdef::VK_EXT_mesh_shader[] +[open,refpage='vkCmdDrawMeshTasksEXT',desc='Draw mesh task work items',type='protos'] +-- +:refpage: vkCmdDrawMeshTasksEXT + +To record a mesh tasks drawing command, call: + +include::{generated}/api/protos/vkCmdDrawMeshTasksEXT.adoc[] + + * pname:commandBuffer is the command buffer into which the command will be + recorded. + * pname:groupCountX is the number of local workgroups to dispatch in the X + dimension. + * pname:groupCountY is the number of local workgroups to dispatch in the Y + dimension. + * pname:groupCountZ is the number of local workgroups to dispatch in the Z + dimension. + +When the command is executed, a global workgroup consisting of +[eq]#pname:groupCountX {times} pname:groupCountY {times} pname:groupCountZ# +local workgroups is assembled. + +.Valid Usage +**** +include::{chapters}/commonvalidity/draw_common.adoc[] + * [[VUID-vkCmdDrawMeshTasksEXT-groupCountX-07083]] + pname:groupCountX must: be less than or equal to + sname:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxTaskWorkGroupCount[0] + * [[VUID-vkCmdDrawMeshTasksEXT-groupCountY-07084]] + pname:groupCountY must: be less than or equal to + sname:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxTaskWorkGroupCount[1] + * [[VUID-vkCmdDrawMeshTasksEXT-groupCountZ-07085]] + pname:groupCountZ must: be less than or equal to + sname:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxTaskWorkGroupCount[2] + * [[VUID-vkCmdDrawMeshTasksEXT-groupCountX-07086]] + The product of pname:groupCountX, pname:groupCountY and + pname:groupCountZ must: be less than or equal to + sname:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxTaskWorkGroupTotalCount + * [[VUID-vkCmdDrawMeshTasksEXT-MeshEXT-07087]] + The current pipeline bound to ename:VK_PIPELINE_BIND_POINT_GRAPHICS + must: contain a shader stage using the code:MeshEXT {ExecutionModel}. +**** + +include::{generated}/validity/protos/vkCmdDrawMeshTasksEXT.adoc[] +-- + +[open,refpage='vkCmdDrawMeshTasksIndirectEXT',desc='Issue an indirect mesh tasks draw into a command buffer',type='protos'] +-- +:refpage: vkCmdDrawMeshTasksIndirectEXT + +To record an indirect mesh tasks drawing command, call: + +include::{generated}/api/protos/vkCmdDrawMeshTasksIndirectEXT.adoc[] + + * pname:commandBuffer is the command buffer into which the command is + recorded. + * pname:buffer is the buffer containing draw parameters. + * pname:offset is the byte offset into pname:buffer where parameters + begin. + * pname:drawCount is the number of draws to execute, and can: be zero. + * pname:stride is the byte stride between successive sets of draw + parameters. + +fname:vkCmdDrawMeshTasksIndirectEXT behaves similarly to +flink:vkCmdDrawMeshTasksEXT except that the parameters are read by the +device from a buffer during execution. +pname:drawCount draws are executed by the command, with parameters taken +from pname:buffer starting at pname:offset and increasing by pname:stride +bytes for each successive draw. +The parameters of each draw are encoded in an array of +slink:VkDrawMeshTasksIndirectCommandEXT structures. +If pname:drawCount is less than or equal to one, pname:stride is ignored. + +.Valid Usage +**** +include::{chapters}/commonvalidity/draw_common.adoc[] +include::{chapters}/commonvalidity/draw_dispatch_indirect_common.adoc[] +include::{chapters}/commonvalidity/draw_indirect_drawcount.adoc[] + * [[VUID-vkCmdDrawMeshTasksIndirectEXT-drawCount-07088]] + If pname:drawCount is greater than `1`, pname:stride must: be a multiple + of `4` and must: be greater than or equal to + code:sizeof(sname:VkDrawMeshTasksIndirectCommandEXT) + * [[VUID-vkCmdDrawMeshTasksIndirectEXT-drawCount-07089]] + If pname:drawCount is equal to `1`, [eq]#(pname:offset {plus} + code:sizeof(slink:VkDrawMeshTasksIndirectCommandEXT))# must: be less + than or equal to the size of pname:buffer + * [[VUID-vkCmdDrawMeshTasksIndirectEXT-drawCount-07090]] + If pname:drawCount is greater than `1`, [eq]#(pname:stride {times} + (pname:drawCount - 1) {plus} pname:offset {plus} + code:sizeof(slink:VkDrawMeshTasksIndirectCommandEXT))# must: be less + than or equal to the size of pname:buffer + * [[VUID-vkCmdDrawMeshTasksIndirectEXT-MeshEXT-07091]] + The current pipeline bound to ename:VK_PIPELINE_BIND_POINT_GRAPHICS + must: contain a shader stage using the code:MeshEXT {ExecutionModel}. +**** + +include::{generated}/validity/protos/vkCmdDrawMeshTasksIndirectEXT.adoc[] +-- + +[open,refpage='VkDrawMeshTasksIndirectCommandEXT',desc='Structure specifying a mesh tasks draw indirect command',type='structs',xrefs='vkCmdDrawMeshTasksIndirectEXT'] +-- + +The sname:VkDrawMeshTasksIndirectCommandEXT structure is defined as: + +include::{generated}/api/structs/VkDrawMeshTasksIndirectCommandEXT.adoc[] + + * pname:groupCountX is the number of local workgroups to dispatch in the X + dimension. + * pname:groupCountY is the number of local workgroups to dispatch in the Y + dimension. + * pname:groupCountZ is the number of local workgroups to dispatch in the Z + dimension. + +The members of sname:VkDrawMeshTasksIndirectCommandEXT have the same meaning +as the similarly named parameters of flink:vkCmdDrawMeshTasksEXT. + +.Valid Usage +**** + * [[VUID-VkDrawMeshTasksIndirectCommandEXT-groupCountX-07092]] + pname:groupCountX must: be less than or equal to + sname:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxTaskWorkGroupCount[0] + * [[VUID-VkDrawMeshTasksIndirectCommandEXT-groupCountY-07093]] + pname:groupCountY must: be less than or equal to + sname:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxTaskWorkGroupCount[1] + * [[VUID-VkDrawMeshTasksIndirectCommandEXT-groupCountZ-07094]] + pname:groupCountZ must: be less than or equal to + sname:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxTaskWorkGroupCount[2] + * [[VUID-VkDrawMeshTasksIndirectCommandEXT-groupCountX-07095]] + The product of pname:groupCountX, pname:groupCountY and + pname:groupCountZ must: be less than or equal to + sname:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxTaskWorkGroupTotalCount +**** + +include::{generated}/validity/structs/VkDrawMeshTasksIndirectCommandEXT.adoc[] +-- + +[open,refpage='vkCmdDrawMeshTasksIndirectCountEXT',desc='Perform an indirect mesh tasks draw with the draw count sourced from a buffer',type='protos'] +-- +:refpage: vkCmdDrawMeshTasksIndirectCountEXT + +To record an indirect mesh tasks drawing command with the draw count sourced +from a buffer, call: + +include::{generated}/api/protos/vkCmdDrawMeshTasksIndirectCountEXT.adoc[] + + * pname:commandBuffer is the command buffer into which the command is + recorded. + * pname:buffer is the buffer containing draw parameters. + * pname:offset is the byte offset into pname:buffer where parameters + begin. + * pname:countBuffer is the buffer containing the draw count. + * pname:countBufferOffset is the byte offset into pname:countBuffer where + the draw count begins. + * pname:maxDrawCount specifies the maximum number of draws that will be + executed. + The actual number of executed draw calls is the minimum of the count + specified in pname:countBuffer and pname:maxDrawCount. + * pname:stride is the byte stride between successive sets of draw + parameters. + +fname:vkCmdDrawMeshTasksIndirectCountEXT behaves similarly to +flink:vkCmdDrawMeshTasksIndirectEXT except that the draw count is read by +the device from a buffer during execution. +The command will read an unsigned 32-bit integer from pname:countBuffer +located at pname:countBufferOffset and use this as the draw count. + +.Valid Usage +**** +include::{chapters}/commonvalidity/draw_common.adoc[] +include::{chapters}/commonvalidity/draw_dispatch_indirect_common.adoc[] +include::{chapters}/commonvalidity/draw_indirect_count_common.adoc[] + * [[VUID-vkCmdDrawMeshTasksIndirectCountEXT-stride-07096]] + pname:stride must: be a multiple of `4` and must: be greater than or + equal to code:sizeof(sname:VkDrawMeshTasksIndirectCommandEXT) + * [[VUID-vkCmdDrawMeshTasksIndirectCountEXT-maxDrawCount-07097]] + If pname:maxDrawCount is greater than or equal to `1`, + [eq]#(pname:stride {times} (pname:maxDrawCount - 1) {plus} pname:offset + {plus} code:sizeof(sname:VkDrawMeshTasksIndirectCommandEXT))# must: be + less than or equal to the size of pname:buffer + * [[VUID-vkCmdDrawMeshTasksIndirectCountEXT-countBuffer-07098]] + If the count stored in pname:countBuffer is equal to `1`, + [eq]#(pname:offset {plus} + code:sizeof(sname:VkDrawMeshTasksIndirectCommandEXT))# must: be less + than or equal to the size of pname:buffer + * [[VUID-vkCmdDrawMeshTasksIndirectCountEXT-countBuffer-07099]] + If the count stored in pname:countBuffer is greater than `1`, + [eq]#(pname:stride {times} (pname:drawCount - 1) {plus} pname:offset + {plus} code:sizeof(sname:VkDrawMeshTasksIndirectCommandEXT))# must: be + less than or equal to the size of pname:buffer + * [[VUID-vkCmdDrawMeshTasksIndirectCountEXT-MeshEXT-07100]] + The current pipeline bound to ename:VK_PIPELINE_BIND_POINT_GRAPHICS + must: contain a shader stage using the code:MeshEXT {ExecutionModel}. +**** + +include::{generated}/validity/protos/vkCmdDrawMeshTasksIndirectCountEXT.adoc[] + +-- +endif::VK_EXT_mesh_shader[] \ No newline at end of file diff --git a/chapters/VK_NV_mesh_shader/mesh.adoc b/chapters/VK_NV_mesh_shader/mesh.adoc index 4a2cf8c2e3..8d3f2c7776 100644 --- a/chapters/VK_NV_mesh_shader/mesh.adoc +++ b/chapters/VK_NV_mesh_shader/mesh.adoc @@ -32,14 +32,36 @@ There are no inputs other than the builtin workgroup identifiers. [[mesh-task-output]] == Task Shader Output -The task shader can emit zero or more mesh workgroups to be generated using -the <> code:TaskCountNV. +The task shader can emit zero or more mesh workgroups to be generated. +ifdef::VK_NV_mesh_shader[] +Shaders using the code:TaskNV {ExecutionModel} can do so using the +<> code:TaskCountNV. This value must: be less than or equal to sname:VkPhysicalDeviceMeshShaderPropertiesNV::pname:maxTaskOutputCount. - -It can also output user-defined data that is passed as input to all mesh -shader invocations that the task creates. -These outputs are decorated as code:PerTaskNV. +endif::VK_NV_mesh_shader[] +ifdef::VK_EXT_mesh_shader[] +Shaders using the code:TaskEXT {ExecutionModel} can do so using the +code:OpEmitMeshTasksEXT instruction. +The code:groupCountX, code:groupCountY and code:groupCountZ arguments passed +to this instruction must: be less than or equal to the respective dimension +within +sname:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxMeshWorkGroupCount. +The product of these arguments must: be less than or equal to +sname:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxMeshWorkGroupTotalCount. +endif::VK_EXT_mesh_shader[] + +The task shader can also pass user-defined data to all mesh shader +invocations that it creates. +ifdef::VK_NV_mesh_shader[] +Shaders using the code:TaskNV {ExecutionModel} can do so by writing to +output variables that are decorated with code:PerTaskNV. +They are available as inputs in mesh shaders. +endif::VK_NV_mesh_shader[] +ifdef::VK_EXT_mesh_shader[] +Shaders using the code:TaskEXT {ExecutionModel} can do so by writing to a +payload variable with code:TaskPayloadWorkgroupEXT storage class that is +passed to the code:OpEmitMeshTasksEXT instruction. +endif::VK_EXT_mesh_shader[] [[mesh-generation]] @@ -53,42 +75,129 @@ invocations directly. [[mesh-input]] == Mesh Shader Input The only inputs available to the mesh shader are variables identifying the -specific workgroup and invocation and, if applicable, any outputs written as -code:PerTaskNV by the task shader that spawned the mesh shader's workgroup. +specific workgroup and invocation and, if applicable, +ifdef::VK_NV_mesh_shader[] +any outputs written as code:PerTaskNV +endif::VK_NV_mesh_shader[] +ifdef::VK_NV_mesh_shader+VK_EXT_mesh_shader[or] +ifdef::VK_EXT_mesh_shader[] +the payload variable passed to the code:OpEmitMeshTasksEXT instruction +endif::VK_EXT_mesh_shader[] +by the task shader that spawned the mesh shader's workgroup. The mesh shader can operate without a task shader as well. [[mesh-output]] -== Mesh Shader Output Primitives +== Mesh Shader Output A mesh shader generates primitives in one of three output modes: points, lines, or triangles. -The primitive mode is specified in the shader using an code:OpExecutionMode -instruction with the code:OutputPoints, code:OutputLinesNV, or -code:OutputTrianglesNV modes, respectively. +ifdef::VK_NV_mesh_shader[] +For shaders using the code:MeshNV {ExecutionModel} the primitive mode is +specified in the shader using an code:OpExecutionMode instruction with the +code:OutputPoints, code:OutputLinesNV, or code:OutputTrianglesNV modes, +respectively. +endif::VK_NV_mesh_shader[] +ifdef::VK_EXT_mesh_shader[] +For shaders using the code:MeshEXT {ExecutionModel} the primitive mode is +specified in the shader using an code:OpExecutionMode instruction with the +code:OutputPoints, code:OutputLinesEXT, or code:OutputTrianglesEXT modes, +respectively. +endif::VK_EXT_mesh_shader[] Each mesh shader must: include exactly one output primitive mode. -The maximum output vertex count is specified as a literal in the shader -using an code:OpExecutionMode instruction with the mode set to -code:OutputVertices and must: be less than or equal to +ifdef::VK_NV_mesh_shader[] +For shaders using the code:MeshNV {ExecutionModel} the maximum output vertex +count is specified as a literal in the shader using an code:OpExecutionMode +instruction with the mode set to code:OutputVertices and must: be less than +or equal to sname:VkPhysicalDeviceMeshShaderPropertiesNV::pname:maxMeshOutputVertices. - -The maximum output primitive count is specified as a literal in the shader -using an code:OpExecutionMode instruction with the mode set to +endif::VK_NV_mesh_shader[] +ifdef::VK_EXT_mesh_shader[] +For shaders using the code:MeshEXT {ExecutionModel} the maximum output +vertex count is specified as a literal in the shader using an +code:OpExecutionMode instruction with the mode set to code:OutputVertices +and must: be less than or equal to +sname:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxMeshOutputVertices. +endif::VK_EXT_mesh_shader[] + +ifdef::VK_NV_mesh_shader[] +For shaders using the code:MeshNV {ExecutionModel} the maximum output +primitive count is specified as a literal in the shader using an +code:OpExecutionMode instruction with the mode set to code:OutputPrimitivesNV and must: be less than or equal to sname:VkPhysicalDeviceMeshShaderPropertiesNV::pname:maxMeshOutputPrimitives. - -The number of primitives output by the mesh shader is provided via writing -to the <> -code:PrimitiveCountNV and must: be less than or equal to the maximum output -primitive count specified in the shader. +endif::VK_NV_mesh_shader[] +ifdef::VK_EXT_mesh_shader[] +For shaders using the code:MeshEXT {ExecutionModel} the maximum output +primitive count is specified as a literal in the shader using an +code:OpExecutionMode instruction with the mode set to +code:OutputPrimitivesEXT, and must: be less than or equal to +sname:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxMeshOutputPrimitives. +endif::VK_EXT_mesh_shader[] + +ifdef::VK_NV_mesh_shader[] +For shaders using the code:MeshNV {ExecutionModel} the number of primitives +output by the mesh shader is provided via writing to the +<> code:PrimitiveCountNV and +must: be less than or equal to the maximum output primitive count specified +in the shader. A variable decorated with code:PrimitiveIndicesNV is an output array of local index values into the vertex output arrays from which primitives are assembled according to the output primitive type. +endif::VK_NV_mesh_shader[] +ifdef::VK_EXT_mesh_shader[] +For shaders using the code:MeshEXT {ExecutionModel} the number of vertices +and primitives output by the mesh shader is provided via calling the +code:OpSetMeshOutputsEXT instruction. +The code:vertexCount argument must: be less than or equal to the maximum +output vertex count specified in the shader. +The code:primitiveCount argument must: be less than or equal to the maximum +output primitive count specified in the shader. + +Depending on the output primitive mode an appropriately-decorated variable +is the output array of local index values into the vertex output arrays from +which primitives are assembled according to the output primitive type: + + * code:OutputPoints uses the code:PrimitivePointIndicesEXT decoration. + * code:OutputLinesEXT uses the code:PrimitiveLineIndicesEXT decoration. + * code:OutputTrianglesEXT uses the code:PrimitiveTriangleIndicesEXT + decoration. +endif::VK_EXT_mesh_shader[] + These resulting primitives are then further processed as described in <>. - +ifdef::VK_EXT_mesh_shader[] +With the exception of primitive indices, all output built-ins and custom +attributes count towards the total storage size occupied by output variables +in mesh shaders. +This size can be calculated as follows, taking into account the fact that +the number of effective scalar attributes is 4 times the number of effective +locations used according to the <>. +Let latexmath:[v] be the number of views, latexmath:[n_v] be the number of +effective scalar per-vertex attributes not dependent on code:ViewIndex, +latexmath:[n_{vpv}] be the number of effective scalar per-vertex attributes +dependent on code:ViewIndex, latexmath:[m_v] be the maximum number of +vertices specified by the code:OutputVertices {ExecutionMode}, +latexmath:[g_v] be pname:meshOutputPerVertexGranularity, latexmath:[n_p] be +the number of effective scalar per-primitive attributes not dependent on +code:ViewIndex, latexmath:[n_{ppv}] be the number of effective scalar +per-primitive attributes dependent on code:ViewIndex, latexmath:[m_p] be the +maximum number of primitives specified by the code:OutputPrimitivesEXT +{ExecutionMode} and latexmath:[g_p] be +pname:meshOutputPerPrimitiveGranularity: + +[latexmath] +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +(n_v + (n_{vpv} \times v)) \times 4 \times \mathrm{align}(m_v, g_v) + +(n_p + (n_{ppv} \times v)) \times 4 \times \mathrm{align}(m_p, g_p) +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +endif::VK_EXT_mesh_shader[] + +ifdef::VK_NV_mesh_shader[] [[mesh-output-perview]] == Mesh Shader Per-View Outputs @@ -114,6 +223,13 @@ input is taken from the element of the per-view output array that corresponds to the view that is currently being processed by the fragment shader. +ifdef::VK_EXT_mesh_shader[] +These _per-view_ outputs are available only in shaders using the code:MeshNV +{ExecutionModel}. +They are not available in shaders using the code:MeshEXT {ExecutionModel}. +endif::VK_EXT_mesh_shader[] + +endif::VK_NV_mesh_shader[] [[mesh-ordering]] == Mesh Shader Primitive Ordering diff --git a/chapters/commonvalidity/draw_common.adoc b/chapters/commonvalidity/draw_common.adoc index b8e3f5545f..8b94b45c38 100644 --- a/chapters/commonvalidity/draw_common.adoc +++ b/chapters/commonvalidity/draw_common.adoc @@ -415,4 +415,15 @@ ifdef::VK_EXT_transform_feedback[] sname:VkPipelineRasterizationStateStreamCreateInfoEXT::pname:rasterizationStream. endif::VK_EXT_transform_feedback[] endif::VK_EXT_primitives_generated_query[] +ifdef::VK_EXT_mesh_shader[] + * [[VUID-{refpage}-stage-07073]] + If the currently bound pipeline was created with the + slink:VkPipelineShaderStageCreateInfo::pname:stage member of an element + of slink:VkGraphicsPipelineCreateInfo::pname:pStages set to + ename:VK_SHADER_STAGE_VERTEX_BIT, + ename:VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT, + ename:VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT or + ename:VK_SHADER_STAGE_GEOMETRY_BIT, then <> must not be active +endif::VK_EXT_mesh_shader[] // Common Valid Usage diff --git a/chapters/commonvalidity/draw_mesh_common.adoc b/chapters/commonvalidity/draw_mesh_common.adoc index d954d23abe..11736fff59 100644 --- a/chapters/commonvalidity/draw_mesh_common.adoc +++ b/chapters/commonvalidity/draw_mesh_common.adoc @@ -4,7 +4,7 @@ // Common Valid Usage // Common to drawing commands for mesh shading -ifdef::VK_NV_mesh_shader[] +ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] * [[VUID-{refpage}-stage-06480]] The bound graphics pipeline must: not have been created with the slink:VkPipelineShaderStageCreateInfo::pname:stage member of an element @@ -13,5 +13,28 @@ ifdef::VK_NV_mesh_shader[] ename:VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT, ename:VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT or ename:VK_SHADER_STAGE_GEOMETRY_BIT -endif::VK_NV_mesh_shader[] +ifdef::VK_EXT_transform_feedback[] + * [[VUID-{refpage}-None-07074]] + <> must: not be + active +endif::VK_EXT_transform_feedback[] +ifdef::VK_EXT_primitives_generated_query[] + * [[VUID-{refpage}-None-07075]] + <> must: not + be active +endif::VK_EXT_primitives_generated_query[] + * [[VUID-{refpage}-pipelineStatistics-07076]] + The pname:pipelineStatistics member used to create any active + <> must: not contain + ename:VK_QUERY_PIPELINE_STATISTIC_INPUT_ASSEMBLY_VERTICES_BIT, + ename:VK_QUERY_PIPELINE_STATISTIC_INPUT_ASSEMBLY_PRIMITIVES_BIT, + ename:VK_QUERY_PIPELINE_STATISTIC_VERTEX_SHADER_INVOCATIONS_BIT, + ename:VK_QUERY_PIPELINE_STATISTIC_GEOMETRY_SHADER_INVOCATIONS_BIT, + ename:VK_QUERY_PIPELINE_STATISTIC_GEOMETRY_SHADER_PRIMITIVES_BIT, + ename:VK_QUERY_PIPELINE_STATISTIC_CLIPPING_INVOCATIONS_BIT, + ename:VK_QUERY_PIPELINE_STATISTIC_CLIPPING_PRIMITIVES_BIT, + ename:VK_QUERY_PIPELINE_STATISTIC_TESSELLATION_CONTROL_SHADER_PATCHES_BIT, + or + ename:VK_QUERY_PIPELINE_STATISTIC_TESSELLATION_EVALUATION_SHADER_INVOCATIONS_BIT +endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] // Common Valid Usage diff --git a/chapters/commonvalidity/draw_vertex_binding.adoc b/chapters/commonvalidity/draw_vertex_binding.adoc index 49201c6df6..7e0a48f20c 100644 --- a/chapters/commonvalidity/draw_vertex_binding.adoc +++ b/chapters/commonvalidity/draw_vertex_binding.adoc @@ -72,11 +72,11 @@ ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state2[] enabled then flink:vkCmdSetPrimitiveRestartEnableEXT must: have been called in the current command buffer prior to this drawing command endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state2[] -ifdef::VK_NV_mesh_shader[] +ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] * [[VUID-{refpage}-stage-06481]] The bound graphics pipeline must: not have been created with the slink:VkPipelineShaderStageCreateInfo::pname:stage member of an element of slink:VkGraphicsPipelineCreateInfo::pname:pStages set to - ename:VK_SHADER_STAGE_TASK_BIT_NV or ename:VK_SHADER_STAGE_MESH_BIT_NV -endif::VK_NV_mesh_shader[] + ename:VK_SHADER_STAGE_TASK_BIT_EXT or ename:VK_SHADER_STAGE_MESH_BIT_EXT +endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] // Common Valid Usage diff --git a/chapters/commonvalidity/pipeline_stage_common.adoc b/chapters/commonvalidity/pipeline_stage_common.adoc index f1530b843e..a11f31833b 100644 --- a/chapters/commonvalidity/pipeline_stage_common.adoc +++ b/chapters/commonvalidity/pipeline_stage_common.adoc @@ -36,13 +36,16 @@ ifdef::VK_EXT_transform_feedback[] is not enabled, pname:pipelineStage must: not be ename:VK_PIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXT endif::VK_EXT_transform_feedback[] -ifdef::VK_NV_mesh_shader[] +ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] * [[VUID-{refpage}-pipelineStage-04080]] If the <> feature is not enabled, pname:pipelineStage must: not be - ename:VK_PIPELINE_STAGE_MESH_SHADER_BIT_NV or - ename:VK_PIPELINE_STAGE_TASK_SHADER_BIT_NV -endif::VK_NV_mesh_shader[] + ename:VK_PIPELINE_STAGE_MESH_SHADER_BIT_EXT + * [[VUID-{refpage}-pipelineStage-07077]] + If the <> feature is not enabled, + pname:pipelineStage must: not be + ename:VK_PIPELINE_STAGE_TASK_SHADER_BIT_EXT +endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] ifdef::VK_NV_shading_rate_image[] * [[VUID-{refpage}-pipelineStage-04081]] If the <> feature is diff --git a/chapters/commonvalidity/stage_mask_2_common.adoc b/chapters/commonvalidity/stage_mask_2_common.adoc index 54b5065eeb..1c016f5c59 100644 --- a/chapters/commonvalidity/stage_mask_2_common.adoc +++ b/chapters/commonvalidity/stage_mask_2_common.adoc @@ -32,16 +32,16 @@ ifdef::VK_EXT_transform_feedback[] is not enabled, pname:{stageMaskName} must: not contain ename:VK_PIPELINE_STAGE_2_TRANSFORM_FEEDBACK_BIT_EXT endif::VK_EXT_transform_feedback[] -ifdef::VK_NV_mesh_shader[] +ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] * [[VUID-{refpage}-{stageMaskName}-03934]] If the <> feature is not enabled, pname:{stageMaskName} must: not contain - ename:VK_PIPELINE_STAGE_2_MESH_SHADER_BIT_NV + ename:VK_PIPELINE_STAGE_2_MESH_SHADER_BIT_EXT * [[VUID-{refpage}-{stageMaskName}-03935]] If the <> feature is not enabled, pname:{stageMaskName} must: not contain - ename:VK_PIPELINE_STAGE_2_TASK_SHADER_BIT_NV -endif::VK_NV_mesh_shader[] + ename:VK_PIPELINE_STAGE_2_TASK_SHADER_BIT_EXT +endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] ifdef::VK_NV_shading_rate_image[] * [[VUID-{refpage}-{stageMaskName}-04956]] If the <> feature is diff --git a/chapters/commonvalidity/stage_mask_common.adoc b/chapters/commonvalidity/stage_mask_common.adoc index 3d74a62f5b..890ef0ee74 100644 --- a/chapters/commonvalidity/stage_mask_common.adoc +++ b/chapters/commonvalidity/stage_mask_common.adoc @@ -32,16 +32,16 @@ ifdef::VK_EXT_transform_feedback[] is not enabled, pname:{stageMaskName} must: not contain ename:VK_PIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXT endif::VK_EXT_transform_feedback[] -ifdef::VK_NV_mesh_shader[] +ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] * [[VUID-{refpage}-{stageMaskName}-04095]] If the <> feature is not enabled, pname:{stageMaskName} must: not contain - ename:VK_PIPELINE_STAGE_MESH_SHADER_BIT_NV + ename:VK_PIPELINE_STAGE_MESH_SHADER_BIT_EXT * [[VUID-{refpage}-{stageMaskName}-04096]] If the <> feature is not enabled, pname:{stageMaskName} must: not contain - ename:VK_PIPELINE_STAGE_TASK_SHADER_BIT_NV -endif::VK_NV_mesh_shader[] + ename:VK_PIPELINE_STAGE_TASK_SHADER_BIT_EXT +endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] ifdef::VK_NV_shading_rate_image[] * [[VUID-{refpage}-{stageMaskName}-04097]] If the <> feature is diff --git a/chapters/copies.adoc b/chapters/copies.adoc index a9e1243212..9fb914c5b5 100644 --- a/chapters/copies.adoc +++ b/chapters/copies.adoc @@ -6,35 +6,7 @@ = Copy Commands An application can: copy buffer and image data using several methods -depending on the type of data transfer. -Data can: be copied between buffer objects with -ifdef::VK_VERSION_1_3,VK_KHR_copy_commands2[] -fname:vkCmdCopyBuffer2 and -endif::VK_VERSION_1_3,VK_KHR_copy_commands2[] -fname:vkCmdCopyBuffer and a portion of an image can: be copied to another -image with -ifdef::VK_VERSION_1_3,VK_KHR_copy_commands2[] -fname:vkCmdCopyImage2 and -endif::VK_VERSION_1_3,VK_KHR_copy_commands2[] -fname:vkCmdCopyImage. -Image data can: also be copied to and from buffer memory using -ifndef::VK_VERSION_1_3,VK_KHR_copy_commands2[] -fname:vkCmdCopyImageToBuffer and fname:vkCmdCopyBufferToImage. -endif::VK_VERSION_1_3,VK_KHR_copy_commands2[] -ifdef::VK_VERSION_1_3,VK_KHR_copy_commands2[] -fname:vkCmdCopyImageToBuffer2, fname:vkCmdCopyImageToBuffer, -fname:vkCmdCopyBufferToImage2, and fname:vkCmdCopyBufferToImage. -endif::VK_VERSION_1_3,VK_KHR_copy_commands2[] -Image data can: be blitted (with or without scaling and filtering) with -ifdef::VK_VERSION_1_3,VK_KHR_copy_commands2[] -fname:vkCmdBlitImage2 and -endif::VK_VERSION_1_3,VK_KHR_copy_commands2[] -fname:vkCmdBlitImage. -Multisampled images can: be resolved to a non-multisampled image with -ifdef::VK_VERSION_1_3,VK_KHR_copy_commands2[] -fname:vkCmdResolveImage2 and -endif::VK_VERSION_1_3,VK_KHR_copy_commands2[] -fname:vkCmdResolveImage. +described in this chapter, depending on the type of data transfer. All copy commands are treated as "`transfer`" operations for the purposes of synchronization barriers. diff --git a/chapters/descriptorsets.adoc b/chapters/descriptorsets.adoc index eff82bf271..49be5869db 100644 --- a/chapters/descriptorsets.adoc +++ b/chapters/descriptorsets.adoc @@ -55,13 +55,16 @@ Storage image loads are supported in all shader stages for image views whose <> contain <>. -Stores to storage images are supported in compute shaders for image views -whose <> contain +Stores to storage images are supported in +ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[task, mesh and] +compute shaders for image views whose +<> contain <>. -Atomic operations on storage images are supported in compute shaders for -image views whose <> -contain +Atomic operations on storage images are supported in +ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[task, mesh and] +compute shaders for image views whose +<> contain <>. When the <> feature via flink:vkGetPhysicalDeviceFormatProperties in slink:VkFormatProperties::pname:bufferFeatures. @@ -619,11 +624,12 @@ ifdef::VK_VALVE_mutable_descriptor_type[] endif::VK_VALVE_mutable_descriptor_type[] endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] ifdef::VK_VALVE_mutable_descriptor_type[] - * [[VUID-VkDescriptorSetLayoutCreateInfo-descriptorType-04593]] - If any binding has a pname:descriptorType of + * [[VUID-VkDescriptorSetLayoutCreateInfo-pBindings-07031]] + If any element pname:pBindings[i] has a pname:descriptorType of ename:VK_DESCRIPTOR_TYPE_MUTABLE_VALVE, then a slink:VkMutableDescriptorTypeCreateInfoVALVE must: be present in the - pname:pNext chain + pname:pNext chain, and pname:mutableDescriptorTypeCount must: be greater + than i. * [[VUID-VkDescriptorSetLayoutCreateInfo-descriptorType-04594]] If a binding has a pname:descriptorType value of ename:VK_DESCRIPTOR_TYPE_MUTABLE_VALVE, then sname:pImmutableSamplers @@ -5059,6 +5065,10 @@ slink:VkBufferDeviceAddressCreateInfoEXT::pname:deviceAddress, endif::VK_EXT_buffer_device_address[] the return value will be the same address that was returned at capture time. +The returned address must: satisfy the alignment requirement specified by +slink:VkMemoryRequirements::pname:alignment for the buffer in +slink:VkBufferDeviceAddressInfo::pname:buffer. + .Valid Usage **** ifdef::VK_EXT_buffer_device_address[] diff --git a/chapters/drawing.adoc b/chapters/drawing.adoc index c8f7da33eb..7c53eea30d 100644 --- a/chapters/drawing.adoc +++ b/chapters/drawing.adoc @@ -15,16 +15,16 @@ commands are recorded in that command buffer. [open,refpage='VkPipelineInputAssemblyStateCreateInfo',desc='Structure specifying parameters of a newly created pipeline input assembly state',type='structs'] -- -ifdef::VK_NV_mesh_shader[] + +ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] Drawing can be achieved in two modes: * <>, the mesh shader assembles primitives, or * <>, the input - primitives are assembled + primitives are assembled as follows. -as follows. -endif::VK_NV_mesh_shader[] +endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] Each draw is made up of zero or more vertices and zero or more instances, which are processed by the device and result in the assembly of primitives. @@ -186,10 +186,10 @@ beginning of the graphics pipeline. The effective topology for later stages of the pipeline is altered by tessellation or geometry shading (if either is in use) and depends on the execution modes of those shaders. -ifdef::VK_NV_mesh_shader[] +ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] In the case of mesh shading the only effective topology is defined by the execution mode of the mesh shader. -endif::VK_NV_mesh_shader[] +endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] [open,refpage='VkPrimitiveTopology',desc='Supported primitive topologies',type='enums'] -- @@ -751,10 +751,10 @@ Primitive order is initially determined in the following way: code:vertexIndex to a higher numbered code:vertexIndex. ** For indexed draws, vertices sourced from a lower index buffer addresses to higher addresses. -ifdef::VK_NV_mesh_shader[] +ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] ** For draws using mesh shaders, the order is provided by <>. -endif::VK_NV_mesh_shader[] +endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] Within this order implementations further sort primitives: @@ -1714,6 +1714,6 @@ include::{generated}/validity/protos/vkCmdEndConditionalRenderingEXT.adoc[] -- endif::VK_EXT_conditional_rendering[] -ifdef::VK_NV_mesh_shader[] +ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] include::{chapters}/VK_NV_mesh_shader/drawing.adoc[] -endif::VK_NV_mesh_shader[] +endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] diff --git a/chapters/features.adoc b/chapters/features.adoc index 0c8ce2c48e..341b9a3487 100644 --- a/chapters/features.adoc +++ b/chapters/features.adoc @@ -1036,17 +1036,23 @@ include::{chapters}/features.adoc[tag=VK_KHR_vulkan_memory_model-features] * [[features-shaderOutputViewportIndex]] pname:shaderOutputViewportIndex indicates whether the implementation supports the code:ShaderViewportIndex SPIR-V capability enabling variables decorated - with the code:ViewportIndex built-in to be exported from vertex or - tessellation evaluation shaders. + with the code:ViewportIndex built-in to be exported from +ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[mesh,] + vertex or tessellation evaluation shaders. If this feature is not enabled, the code:ViewportIndex built-in - decoration must: not be used on outputs in vertex or tessellation - evaluation shaders. + decoration must: not be used on outputs in +ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[mesh,] + vertex or tessellation evaluation shaders. * [[features-shaderOutputLayer]] pname:shaderOutputLayer indicates whether the implementation supports the code:ShaderLayer SPIR-V capability enabling variables decorated with the code:Layer built-in to be exported - from vertex or tessellation evaluation shaders. + from +ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[mesh,] + vertex or tessellation evaluation shaders. If this feature is not enabled, the code:Layer built-in decoration must: - not be used on outputs in vertex or tessellation evaluation shaders. + not be used on outputs in +ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[mesh,] + vertex or tessellation evaluation shaders. * [[features-subgroupBroadcastDynamicId]] If pname:subgroupBroadcastDynamicId is ename:VK_TRUE, the "`Id`" operand of code:OpGroupNonUniformBroadcast can: be dynamically uniform within a @@ -1240,16 +1246,32 @@ This structure describes the following features: perform 64-bit floating-point add atomic operations on storage buffers. * [[features-shaderSharedFloat32Atomics]] pname:shaderSharedFloat32Atomics indicates whether shaders can: perform 32-bit floating-point load, store - and exchange atomic operations on shared memory. + and exchange atomic operations on shared +ifdef::VK_EXT_mesh_shader[] + and payload +endif::VK_EXT_mesh_shader[] + memory. * [[features-shaderSharedFloat32AtomicAdd]] pname:shaderSharedFloat32AtomicAdd indicates whether shaders can: - perform 32-bit floating-point add atomic operations on shared memory. + perform 32-bit floating-point add atomic operations on shared +ifdef::VK_EXT_mesh_shader[] + and payload +endif::VK_EXT_mesh_shader[] + memory. * [[features-shaderSharedFloat64Atomics]] pname:shaderSharedFloat64Atomics indicates whether shaders can: perform 64-bit floating-point load, store - and exchange atomic operations on shared memory. + and exchange atomic operations on shared +ifdef::VK_EXT_mesh_shader[] + and payload +endif::VK_EXT_mesh_shader[] + memory. * [[features-shaderSharedFloat64AtomicAdd]] pname:shaderSharedFloat64AtomicAdd indicates whether shaders can: - perform 64-bit floating-point add atomic operations on shared memory. + perform 64-bit floating-point add atomic operations on shared +ifdef::VK_EXT_mesh_shader[] + and payload +endif::VK_EXT_mesh_shader[] + memory. * [[features-shaderImageFloat32Atomics]] pname:shaderImageFloat32Atomics indicates whether shaders can: perform 32-bit floating-point load, store and exchange atomic image operations. @@ -1306,21 +1328,38 @@ This structure describes the following features: buffers. * [[features-shaderSharedFloat16Atomics]] pname:shaderSharedFloat16Atomics indicates whether shaders can: perform 16-bit floating-point load, store - and exchange atomic operations on shared memory. + and exchange atomic operations on shared +ifdef::VK_EXT_mesh_shader[] + and payload +endif::VK_EXT_mesh_shader[] + memory. * [[features-shaderSharedFloat16AtomicAdd]] pname:shaderSharedFloat16AtomicAdd indicates whether shaders can: - perform 16-bit floating-point add atomic operations on shared memory. + perform 16-bit floating-point add atomic operations on shared +ifdef::VK_EXT_mesh_shader[] + and payload +endif::VK_EXT_mesh_shader[] + memory. * [[features-shaderSharedFloat16AtomicMinMax]] pname:shaderSharedFloat16AtomicMinMax indicates whether shaders can: perform 16-bit floating-point min and max atomic operations on shared +ifdef::VK_EXT_mesh_shader[] + and payload +endif::VK_EXT_mesh_shader[] memory. * [[features-shaderSharedFloat32AtomicMinMax]] pname:shaderSharedFloat32AtomicMinMax indicates whether shaders can: perform 32-bit floating-point min and max atomic operations on shared +ifdef::VK_EXT_mesh_shader[] + and payload +endif::VK_EXT_mesh_shader[] memory. * [[features-shaderSharedFloat64AtomicMinMax]] pname:shaderSharedFloat64AtomicMinMax indicates whether shaders can: perform 64-bit floating-point min and max atomic operations on shared +ifdef::VK_EXT_mesh_shader[] + and payload +endif::VK_EXT_mesh_shader[] memory. * [[features-shaderImageFloat32AtomicMinMax]] pname:shaderImageFloat32AtomicMinMax indicates whether shaders can: @@ -1366,7 +1405,11 @@ ifndef::VK_VERSION_1_2[:anchor-prefix:] 64-bit unsigned and signed integer atomic operations on buffers. * [[{anchor-prefix}features-shaderSharedInt64Atomics]] pname:shaderSharedInt64Atomics indicates whether shaders can: perform - 64-bit unsigned and signed integer atomic operations on shared memory. + 64-bit unsigned and signed integer atomic operations on shared +ifdef::VK_EXT_mesh_shader[] + and payload +endif::VK_EXT_mesh_shader[] + memory. // end::VK_KHR_shader_atomic_int64-features[] :refpage: VkPhysicalDeviceShaderAtomicInt64Features @@ -1799,10 +1842,26 @@ This structure describes the following features: * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. - * [[features-taskShader]] pname:taskShader indicates whether the task - shader stage is supported. - * [[features-meshShader]] pname:meshShader indicates whether the mesh - shader stage is supported. +ifdef::VK_EXT_mesh_shader[] + * pname:taskShader specifies whether task shaders are supported. +endif::VK_EXT_mesh_shader[] +ifndef::VK_EXT_mesh_shader[] + * [[features-taskShader]] pname:taskShader specifies whether task shaders + are supported. +endif::VK_EXT_mesh_shader[] + If this feature is not enabled, the ename:VK_SHADER_STAGE_TASK_BIT_NV + and ename:VK_PIPELINE_STAGE_TASK_SHADER_BIT_NV enum values must: not be + used. +ifdef::VK_EXT_mesh_shader[] + * pname:meshShader specifies whether mesh shaders are supported. +endif::VK_EXT_mesh_shader[] +ifndef::VK_EXT_mesh_shader[] + * [[features-meshShader]] pname:meshShader specifies whether mesh shaders + are supported. +endif::VK_EXT_mesh_shader[] + If this feature is not enabled, the ename:VK_SHADER_STAGE_MESH_BIT_NV + and ename:VK_PIPELINE_STAGE_MESH_SHADER_BIT_NV enum values must: not be + used. :refpage: VkPhysicalDeviceMeshShaderFeaturesNV include::{chapters}/features.adoc[tag=features] @@ -1811,6 +1870,74 @@ include::{generated}/validity/structs/VkPhysicalDeviceMeshShaderFeaturesNV.adoc[ -- endif::VK_NV_mesh_shader[] +ifdef::VK_EXT_mesh_shader[] +[open,refpage='VkPhysicalDeviceMeshShaderFeaturesEXT',desc='Structure describing mesh shading features that can be supported by an implementation',type='structs'] +-- +The sname:VkPhysicalDeviceMeshShaderFeaturesEXT structure is defined as: + +include::{generated}/api/structs/VkPhysicalDeviceMeshShaderFeaturesEXT.adoc[] + + * pname:sType is the type of this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * [[features-taskShader]] pname:taskShader specifies whether task shaders + are supported. + If this feature is not enabled, the ename:VK_SHADER_STAGE_TASK_BIT_EXT + and ename:VK_PIPELINE_STAGE_TASK_SHADER_BIT_EXT enum values must: not be + used. + * [[features-meshShader]] pname:meshShader specifies whether mesh shaders + are supported. + If this feature is not enabled, the ename:VK_SHADER_STAGE_MESH_BIT_EXT + and ename:VK_PIPELINE_STAGE_MESH_SHADER_BIT_EXT enum values must: not be + used. +ifdef::VK_VERSION_1_1,VK_KHR_multiview[] + * [[features-multiview-mesh]] pname:multiviewMeshShader specifies whether + the implementation supports <> rendering + within a render pass, with mesh shaders. + If this feature is not enabled, then a pipeline compiled against a + subpass with a non-zero view mask must: not include a mesh shader. +endif::VK_VERSION_1_1,VK_KHR_multiview[] +ifdef::VK_KHR_fragment_shading_rate[] + * [[features-primitiveFragmentShadingRate-mesh]] + pname:primitiveFragmentShadingRateMeshShader indicates that the + implementation supports the <> in mesh shaders. +endif::VK_KHR_fragment_shading_rate[] + * [[features-meshShaderQueries]] pname:meshShaderQueries indicates that + the implementation supports creating query pools using the + ename:VK_QUERY_TYPE_MESH_PRIMITIVES_GENERATED_EXT query type and + statistic queries containing the + ename:VK_QUERY_PIPELINE_STATISTIC_TASK_SHADER_INVOCATIONS_BIT_EXT and + ename:VK_QUERY_PIPELINE_STATISTIC_MESH_SHADER_INVOCATIONS_BIT_EXT flags + +:refpage: VkPhysicalDeviceMeshShaderFeaturesEXT +include::{chapters}/features.adoc[tag=features] + +ifdef::VK_NV_mesh_shader[] +The corresponding features of the sname:VkPhysicalDeviceMeshShaderFeaturesNV +structure must: match those in sname:VkPhysicalDeviceMeshShaderFeaturesEXT. +endif::VK_NV_mesh_shader[] + +.Valid Usage +**** +ifdef::VK_VERSION_1_1,VK_KHR_multiview[] + * [[VUID-VkPhysicalDeviceMeshShaderFeaturesEXT-multiviewMeshShader-07032]] + If pname:multiviewMeshShader is enabled then + sname:VkPhysicalDeviceMultiviewFeaturesKHR::pname:multiview must: also + be enabled +endif::VK_VERSION_1_1,VK_KHR_multiview[] +ifdef::VK_KHR_fragment_shading_rate[] + * [[VUID-VkPhysicalDeviceMeshShaderFeaturesEXT-primitiveFragmentShadingRateMeshShader-07033]] + If pname:primitiveFragmentShadingRateMeshShader is enabled then + sname:VkPhysicalDeviceFragmentShadingRateFeaturesKHR::pname:primitiveFragmentShadingRate + must: also be enabled +endif::VK_KHR_fragment_shading_rate[] +**** + +include::{generated}/validity/structs/VkPhysicalDeviceMeshShaderFeaturesEXT.adoc[] +-- +endif::VK_EXT_mesh_shader[] + ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] [open,refpage='VkPhysicalDeviceDescriptorIndexingFeatures',desc='Structure describing descriptor indexing features that can be supported by an implementation',type='structs',alias='VkPhysicalDeviceDescriptorIndexingFeaturesEXT'] -- @@ -3410,7 +3537,11 @@ ifndef::VK_VERSION_1_3[:anchor-prefix:] structure. * [[{anchor-prefix}features-computeFullSubgroups]] pname:computeFullSubgroups indicates whether the implementation supports - requiring full subgroups in compute shaders via the + requiring full subgroups in compute +ifdef::VK_NV_mesh_shader[] + , mesh, or task +endif::VK_NV_mesh_shader[] + shaders via the ename:VK_PIPELINE_SHADER_STAGE_CREATE_REQUIRE_FULL_SUBGROUPS_BIT flag. // end::VK_EXT_subgroup_size_control-features[] @@ -5460,6 +5591,29 @@ include::{generated}/validity/structs/VkPhysicalDeviceImageProcessingFeaturesQCO -- endif::VK_QCOM_image_processing[] +ifdef::VK_EXT_depth_clamp_zero_one[] +[open,refpage='VkPhysicalDeviceDepthClampZeroOneFeaturesEXT',desc='Structure describing feature to control zero to one depth clamping',type='structs'] +-- +The sname:VkPhysicalDeviceDepthClampZeroOneFeaturesEXT structure is defined +as: + +include::{generated}/api/structs/VkPhysicalDeviceDepthClampZeroOneFeaturesEXT.adoc[] + +This structure describes the following feature: + + * pname:sType is the type of this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + + * [[features-depthClampZeroOne]] pname:depthClampZeroOne indicates that + the implementation supports clamping the depth to a range of `0` to `1`. + +:refpage: VkPhysicalDeviceDepthClampZeroOneFeaturesEXT +include::{chapters}/features.adoc[tag=features] + +include::{generated}/validity/structs/VkPhysicalDeviceDepthClampZeroOneFeaturesEXT.adoc[] +-- +endif::VK_EXT_depth_clamp_zero_one[] [[features-requirements]] == Feature Requirements @@ -5916,6 +6070,17 @@ ifdef::VK_VERSION_1_3,VK_KHR_dynamic_rendering[] * <>, if Vulkan 1.3 or the `apiext:VK_KHR_dynamic_rendering` extension is supported. endif::VK_VERSION_1_3,VK_KHR_dynamic_rendering[] +ifdef::VK_EXT_mesh_shader[] + * <> and <>, if the `apiext:VK_EXT_mesh_shader` extension is + supported. +endif::VK_EXT_mesh_shader[] +ifdef::VK_EXT_mesh_shader+VK_KHR_fragment_shading_rate[] + * <> if + <> feature is supported. +endif::VK_EXT_mesh_shader+VK_KHR_fragment_shading_rate[] ifdef::VK_EXT_subpass_merge_feedback[] * <>, if the `apiext:VK_EXT_subpass_merge_feedback` extension is supported. @@ -5977,6 +6142,10 @@ ifdef::VK_EXT_attachment_feedback_loop_layout[] pname:attachmentFeedbackLoopLayout>>, if the `apiext:VK_EXT_attachment_feedback_loop_layout` extension is supported. endif::VK_EXT_attachment_feedback_loop_layout[] +ifdef::VK_EXT_depth_clamp_zero_one[] + * <>, if the + `<>` extension is supported. +endif::VK_EXT_depth_clamp_zero_one[] All other features defined in the Specification are optional:. diff --git a/chapters/formats.adoc b/chapters/formats.adoc index 16924acf3f..ebdb3764ee 100644 --- a/chapters/formats.adoc +++ b/chapters/formats.adoc @@ -1301,7 +1301,7 @@ Classes>>. [width="95%",cols="1,6,3,3",options="header"] |==== ^| Plane ^| Compatible format for plane ^| Width relative to the width _w_ of the plane with the largest dimensions ^| Height relative to the height _h_ of the plane with the largest dimensions -include::{generated}/formats/planeformat.txt[] +include::{generated}/formats/planeformat.adoc[] |==== endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] diff --git a/chapters/fragops.adoc b/chapters/fragops.adoc index 24ae3924ab..6362f94e35 100644 --- a/chapters/fragops.adoc +++ b/chapters/fragops.adoc @@ -853,6 +853,8 @@ include::{generated}/validity/structs/VkPipelineDepthStencilStateCreateInfo.adoc [open,refpage='VkPipelineDepthStencilStateCreateFlags',desc='Bitmask of VkPipelineDepthStencilStateCreateFlagBits',type='flags'] -- +include::{generated}/api/flags/VkPipelineDepthStencilStateCreateFlags.adoc[] + ifndef::VK_EXT_rasterization_order_attachment_access,VK_ARM_rasterization_order_attachment_access[] tname:VkPipelineDepthStencilStateCreateFlags is a bitmask type for setting a mask, but is currently reserved for future use. @@ -1337,18 +1339,38 @@ sections. === Depth Clamping and Range Adjustment If slink:VkPipelineRasterizationStateCreateInfo::pname:depthClampEnable is -enabled, before the sample's [eq]#z~f~# is compared to [eq]#z~a~#, -[eq]#z~f~# is clamped to [eq]#[min(n,f),max(n,f)]#, where [eq]#n# and -[eq]#f# are the pname:minDepth and pname:maxDepth depth range values of the -viewport used by this fragment, respectively. +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 +pname:minDepth and pname:maxDepth depth range values of the viewport used by +this fragment, respectively. + +ifdef::VK_EXT_depth_clamp_zero_one[] +If +slink:VkPhysicalDeviceDepthClampZeroOneFeaturesEXT::pname:depthClampZeroOne +is enabled: + +ifdef::VK_EXT_depth_range_unrestricted[] + * If the depth attachment has a floating-point format and + VK_EXT_depth_range_unrestricted is enabled then [eq]#z~f~# is unchanged. + * Otherwise, [eq]#z~f~# is clamped to the range [eq]#[0, 1]#. +endif::VK_EXT_depth_range_unrestricted[] +ifndef::VK_EXT_depth_range_unrestricted[] + * [eq]#z~f~# is clamped to the range [eq]#[0, 1]#. +endif::VK_EXT_depth_range_unrestricted[] + +Otherwise: +endif::VK_EXT_depth_clamp_zero_one[] +ifndef::VK_EXT_depth_clamp_zero_one[] +Following depth clamping: +endif::VK_EXT_depth_clamp_zero_one[] -If depth clamping is not enabled and [eq]#z~f~# is not in the range [eq]#[0, -1]# + * If [eq]#z~f~# is not in the range [eq]#[z~min~, z~max~]#, then + [eq]#z~f~# is undefined: following this step. ifdef::VK_EXT_depth_range_unrestricted[] -and either `apiext:VK_EXT_depth_range_unrestricted` is not enabled, or the -depth attachment has a fixed-point format, + * If the depth attachment has a fixed-point format and [eq]#z~f~# is not + in the range [eq]#[0, 1]#, then [eq]#z~f~# is undefined: following this + step. endif::VK_EXT_depth_range_unrestricted[] -then [eq]#z~f~# is undefined: following this step. [[fragops-depth-comparison]] diff --git a/chapters/initialization.adoc b/chapters/initialization.adoc index b260dab852..3f53d2fd1c 100644 --- a/chapters/initialization.adoc +++ b/chapters/initialization.adoc @@ -505,8 +505,8 @@ physical device that supports Vulkan 1.2. ==== Implicit layers must: be disabled if they do not support a version at least -as high as pname:apiVersion and their version is less than the highest version -of the drivers on the system. +as high as pname:apiVersion and their version is less than the highest +version of the drivers on the system. See the <> document for additional information. diff --git a/chapters/interfaces.adoc b/chapters/interfaces.adoc index 7a4c99307e..7182df6605 100644 --- a/chapters/interfaces.adoc +++ b/chapters/interfaces.adoc @@ -127,11 +127,11 @@ ifdef::VK_VERSION_1_3,VK_KHR_maintenance4[] output has a code:Component code:Count value higher than that of the input but the same code:Component code:Type; or endif::VK_VERSION_1_3,VK_KHR_maintenance4[] -ifdef::VK_NV_mesh_shader[] +ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] ** if the output is declared in a mesh shader as an code:OpTypeArray with an code:Element code:Type equivalent to the code:OpType* declaration of the input, and neither is a structure member; or -endif::VK_NV_mesh_shader[] +endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] ifdef::VK_NV_fragment_shader_barycentric,VK_KHR_fragment_shader_barycentric[] ** if the input is decorated with code:PerVertexKHR, and is declared in a fragment shader as an code:OpTypeArray with an code:Element code:Type @@ -273,10 +273,15 @@ Available`" column in <>. | geometry output | pname:maxGeometryOutputComponents / 4 | fragment input | pname:maxFragmentInputComponents / 4 | fragment output | pname:maxFragmentOutputAttachments +ifdef::VK_EXT_mesh_shader[] +| mesh output | pname:maxMeshOutputComponents / 4 +endif::VK_EXT_mesh_shader[] +ifndef::VK_EXT_mesh_shader[] ifdef::VK_NV_mesh_shader[] // we forgot to add maxMeshOutputComponents | mesh output | pname:maxFragmentInputComponents / 4 endif::VK_NV_mesh_shader[] +endif::VK_EXT_mesh_shader[] |==== @@ -1612,12 +1617,13 @@ contains these linearly interpolated values. **** * [[VUID-{refpage}-ClipDistance-04187]] The code:ClipDistance decoration must: be used only within the - code:MeshNV, code:Vertex, code:Fragment, code:TessellationControl, - code:TessellationEvaluation, or code:Geometry {ExecutionModel} + code:MeshEXT, code:MeshNV, code:Vertex, code:Fragment, + code:TessellationControl, code:TessellationEvaluation, or code:Geometry + {ExecutionModel} * [[VUID-{refpage}-ClipDistance-04188]] - The variable decorated with code:ClipDistance within the code:MeshNV or - code:Vertex {ExecutionModel} must: be declared using the code:Output - {StorageClass} + The variable decorated with code:ClipDistance within the code:MeshEXT, + code:MeshNV, or code:Vertex {ExecutionModel} must: be declared using the + code:Output {StorageClass} * [[VUID-{refpage}-ClipDistance-04189]] The variable decorated with code:ClipDistance within the code:Fragment {ExecutionModel} must: be declared using the code:Input {StorageClass} @@ -1693,12 +1699,13 @@ from the previous shader stage. **** * [[VUID-{refpage}-CullDistance-04196]] The code:CullDistance decoration must: be used only within the - code:MeshNV, code:Vertex, code:Fragment, code:TessellationControl, - code:TessellationEvaluation, or code:Geometry {ExecutionModel} + code:MeshEXT, code:MeshNV, code:Vertex, code:Fragment, + code:TessellationControl, code:TessellationEvaluation, or code:Geometry + {ExecutionModel} * [[VUID-{refpage}-CullDistance-04197]] - The variable decorated with code:CullDistance within the code:MeshNV or - code:Vertex {ExecutionModel} must: be declared using the code:Output - {StorageClass} + The variable decorated with code:CullDistance within the code:MeshEXT, + code:MeshNV or code:Vertex {ExecutionModel} must: be declared using the + code:Output {StorageClass} * [[VUID-{refpage}-CullDistance-04198]] The variable decorated with code:CullDistance within the code:Fragment {ExecutionModel} must: be declared using the code:Input {StorageClass} @@ -1743,6 +1750,41 @@ The per-view cull distances have the same semantics as code:CullDistance. -- endif::VK_NV_mesh_shader[] +ifdef::VK_EXT_mesh_shader[] +[[interfaces-builtin-variables-cullprimitive]] +[open,refpage='CullPrimitiveEXT',desc='Application-specified culling state per primitive',type='builtins'] +-- +:refpage: CullPrimitiveEXT + +code:CullPrimitiveEXT:: ++ +Decorating a variable with the code:CullPrimitiveEXT built-in decoration +will make that variable contain the culling state of output primitives. +If the per-primitive boolean value is code:true, the primitive will be +culled, if it is code:false it will not be culled. + +.Valid Usage +**** + * [[VUID-{refpage}-CullPrimitiveEXT-07034]] + The code:CullPrimitiveEXT decoration must: be used only within the + code:MeshEXT {ExecutionModel} + * [[VUID-{refpage}-CullPrimitiveEXT-07035]] + The variable decorated with code:CullPrimitiveEXT must: be declared + using the code:Output {StorageClass} + * [[VUID-{refpage}-CullPrimitiveEXT-07036]] + The variable decorated with code:CullPrimitiveEXT must: be declared as + an array of boolean values + * [[VUID-{refpage}-CullPrimitiveEXT-07037]] + The size of the array decorated with code:CullPrimitiveEXT must: match + the value specified by code:OutputPrimitivesEXT + * [[VUID-{refpage}-CullPrimitiveEXT-07038]] + The variable decorated with code:CullPrimitiveEXT within the + code:MeshEXT {ExecutionModel} must: also be decorated with the + code:PerPrimitiveEXT decoration +**** +-- +endif::VK_EXT_mesh_shader[] + ifdef::VK_KHR_ray_tracing_pipeline,VK_KHR_ray_tracing_maintenance1[] [[interfaces-builtin-variables-cullmask]] [open,refpage='CullMaskKHR',desc='OpTrace specified ray cull mask',type='builtins'] @@ -1838,9 +1880,7 @@ code:DrawIndex:: Decorating a variable with the code:DrawIndex built-in will make that variable contain the integer value corresponding to the zero-based index of the drawing command that invoked the current -ifdef::VK_NV_mesh_shader[] -task, mesh, or -endif::VK_NV_mesh_shader[] +ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[task, mesh, or] vertex shader invocation. For _indirect drawing commands_, code:DrawIndex begins at zero and increments by one for each drawing command executed. @@ -1855,17 +1895,17 @@ endif::VK_EXT_multi_draw[] code:DrawIndex is always zero. code:DrawIndex is dynamically uniform. -ifdef::VK_NV_mesh_shader[] +ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] When task or mesh shaders are used, only the first active stage will have proper access to the variable. The value read by other stages is undefined:. -endif::VK_NV_mesh_shader[] +endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] .Valid Usage **** * [[VUID-{refpage}-DrawIndex-04207]] The code:DrawIndex decoration must: be used only within the code:Vertex, - code:MeshNV, or code:TaskNV {ExecutionModel} + code:MeshEXT, code:TaskEXT, code:MeshNV, or code:TaskNV {ExecutionModel} * [[VUID-{refpage}-DrawIndex-04208]] The variable decorated with code:DrawIndex must: be declared using the code:Input {StorageClass} @@ -2165,7 +2205,8 @@ the size of the local workgroup plus code:LocalInvocationId. **** * [[VUID-{refpage}-GlobalInvocationId-04236]] The code:GlobalInvocationId decoration must: be used only within the - code:GLCompute, code:MeshNV, or code:TaskNV {ExecutionModel} + code:GLCompute, code:MeshEXT, code:TaskEXT, code:MeshNV, or code:TaskNV + {ExecutionModel} * [[VUID-{refpage}-GlobalInvocationId-04237]] The variable decorated with code:GlobalInvocationId must: be declared using the code:Input {StorageClass} @@ -2512,9 +2553,7 @@ variable contain the select layer of a multi-layer framebuffer attachment. + In a ifdef::VK_VERSION_1_2,VK_EXT_shader_viewport_index_layer,VK_NV_viewport_array2[] -ifdef::VK_NV_mesh_shader[] -mesh, -endif::VK_NV_mesh_shader[] +ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[mesh,] vertex, tessellation evaluation, or endif::VK_VERSION_1_2,VK_EXT_shader_viewport_index_layer,VK_NV_viewport_array2[] geometry shader, any variable decorated with code:Layer can be written with @@ -2541,6 +2580,11 @@ If the code:Layer value is less than 0 or greater than or equal to the number of layers in the framebuffer, then primitives may: still be rasterized, fragment shaders may: be executed, and the framebuffer values for all layers are undefined:. +ifdef::VK_EXT_mesh_shader[] +In a mesh shader this also applies when the code:Layer value is greater than +or equal to the pname:maxMeshOutputLayers limit. +endif::VK_EXT_mesh_shader[] ++ ifdef::VK_NV_viewport_array2[] + If a variable with the code:Layer decoration is also decorated with @@ -2558,8 +2602,8 @@ layer index of the primitive that the fragment invocation belongs to. .Valid Usage **** * [[VUID-{refpage}-Layer-04272]] - The code:Layer decoration must: be used only within the code:MeshNV, - code:Vertex, code:TessellationEvaluation, code:Geometry, or + The code:Layer decoration must: be used only within the code:MeshEXT, + code:MeshNV, code:Vertex, code:TessellationEvaluation, code:Geometry, or code:Fragment {ExecutionModel} ifdef::VK_VERSION_1_2[] * [[VUID-{refpage}-Layer-04273]] @@ -2568,8 +2612,8 @@ ifdef::VK_VERSION_1_2[] the code:Geometry or code:Fragment {ExecutionModel} endif::VK_VERSION_1_2[] * [[VUID-{refpage}-Layer-04274]] - The variable decorated with code:Layer within the code:MeshNV, - code:Vertex, code:TessellationEvaluation, or code:Geometry + The variable decorated with code:Layer within the code:MeshEXT, + code:MeshNV, code:Vertex, code:TessellationEvaluation, or code:Geometry {ExecutionModel} must: be declared using the code:Output {StorageClass} * [[VUID-{refpage}-Layer-04275]] The variable decorated with code:Layer within the code:Fragment @@ -2577,6 +2621,10 @@ endif::VK_VERSION_1_2[] * [[VUID-{refpage}-Layer-04276]] The variable decorated with code:Layer must: be declared as a scalar 32-bit integer value + * [[VUID-{refpage}-Layer-07039]] + The variable decorated with code:Layer within the code:MeshEXT + {ExecutionModel} must: also be decorated with the code:PerPrimitiveEXT + decoration **** -- @@ -2618,9 +2666,7 @@ code:LocalInvocationId:: Decorating a variable with the code:LocalInvocationId built-in decoration will make that variable contain the location of the current -ifdef::VK_NV_mesh_shader[] -task, mesh, or -endif::VK_NV_mesh_shader[] +ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[task, mesh, or] compute shader invocation within the local workgroup. Each component ranges from zero through to the size of the workgroup in that dimension minus one. @@ -2640,7 +2686,8 @@ code:LocalInvocationId.y and code:LocalInvocationId.z will be zero. **** * [[VUID-{refpage}-LocalInvocationId-04281]] The code:LocalInvocationId decoration must: be used only within the - code:GLCompute, code:MeshNV, or code:TaskNV {ExecutionModel} + code:GLCompute, code:MeshEXT, code:TaskEXT, code:MeshNV, or code:TaskNV + {ExecutionModel} * [[VUID-{refpage}-LocalInvocationId-04282]] The variable decorated with code:LocalInvocationId must: be declared using the code:Input {StorageClass} @@ -2673,7 +2720,8 @@ LocalInvocationIndex = **** * [[VUID-{refpage}-LocalInvocationIndex-04284]] The code:LocalInvocationIndex decoration must: be used only within the - code:GLCompute, code:MeshNV, or code:TaskNV {ExecutionModel} + code:GLCompute, code:MeshEXT, code:TaskEXT, code:MeshNV, or code:TaskNV + {ExecutionModel} * [[VUID-{refpage}-LocalInvocationIndex-04285]] The variable decorated with code:LocalInvocationIndex must: be declared using the code:Input {StorageClass} @@ -2756,7 +2804,8 @@ make that variable contain the number of subgroups in the local workgroup. **** * [[VUID-{refpage}-NumSubgroups-04293]] The code:NumSubgroups decoration must: be used only within the - code:GLCompute, code:MeshNV, or code:TaskNV {ExecutionModel} + code:GLCompute, code:MeshEXT, code:TaskEXT, code:MeshNV, or code:TaskNV + {ExecutionModel} * [[VUID-{refpage}-NumSubgroups-04294]] The variable decorated with code:NumSubgroups must: be declared using the code:Input {StorageClass} @@ -2783,7 +2832,7 @@ passed into the dispatching commands. **** * [[VUID-{refpage}-NumWorkgroups-04296]] The code:NumWorkgroups decoration must: be used only within the - code:GLCompute {ExecutionModel} + code:GLCompute, code:MeshEXT, or code:TaskEXT {ExecutionModel} * [[VUID-{refpage}-NumWorkgroups-04297]] The variable decorated with code:NumWorkgroups must: be declared using the code:Input {StorageClass} @@ -2964,13 +3013,13 @@ code:PointSize from the previous shader stage. .Valid Usage **** * [[VUID-{refpage}-PointSize-04314]] - The code:PointSize decoration must: be used only within the code:MeshNV, - code:Vertex, code:TessellationControl, code:TessellationEvaluation, or - code:Geometry {ExecutionModel} + The code:PointSize decoration must: be used only within the + code:MeshEXT, code:MeshNV, code:Vertex, code:TessellationControl, + code:TessellationEvaluation, or code:Geometry {ExecutionModel} * [[VUID-{refpage}-PointSize-04315]] - The variable decorated with code:PointSize within the code:MeshNV or - code:Vertex {ExecutionModel} must: be declared using the code:Output - {StorageClass} + The variable decorated with code:PointSize within the code:MeshEXT, + code:MeshNV, or code:Vertex {ExecutionModel} must: be declared using the + code:Output {StorageClass} * [[VUID-{refpage}-PointSize-04316]] The variable decorated with code:PointSize within the code:TessellationControl, code:TessellationEvaluation, or code:Geometry @@ -3006,15 +3055,15 @@ code:Position from the previous shader stage. .Valid Usage **** * [[VUID-{refpage}-Position-04318]] - The code:Position decoration must: be used only within the code:MeshNV, - code:Vertex, code:TessellationControl, code:TessellationEvaluation, or - code:Geometry {ExecutionModel} + The code:Position decoration must: be used only within the code:MeshEXT, + code:MeshNV, code:Vertex, code:TessellationControl, + code:TessellationEvaluation, or code:Geometry {ExecutionModel} * [[VUID-{refpage}-Position-04319]] - The variable decorated with code:Position within code:MeshNV or - code:Vertex {ExecutionModel} must: be declared using the code:Output - {StorageClass} + The variable decorated with code:Position within the code:MeshEXT, + code:MeshNV, or code:Vertex {ExecutionModel} must: be declared using the + code:Output {StorageClass} * [[VUID-{refpage}-Position-04320]] - The variable decorated with code:Position within + The variable decorated with code:Position within the code:TessellationControl, code:TessellationEvaluation, or code:Geometry {ExecutionModel} must: not be declared using a {StorageClass} other than code:Input or code:Output @@ -3145,10 +3194,10 @@ input to the shader since the current set of rendering primitives was started. + In a fragment shader, it will contain the primitive index written by the -ifdef::VK_NV_mesh_shader[] +ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] mesh shader if a mesh shader is present, or the primitive index written by the -endif::VK_NV_mesh_shader[] +endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] geometry shader if a geometry shader is present, or with the value that would have been presented as input to the geometry shader had it been present. @@ -3162,14 +3211,13 @@ endif::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] .Note ==== When the code:PrimitiveId decoration is applied to an output variable in the -ifdef::VK_NV_mesh_shader[] -mesh shader or -endif::VK_NV_mesh_shader[] +ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[mesh shader or] geometry shader, the resulting value is seen through the code:PrimitiveId decorated input variable in the fragment shader. The fragment shader using code:PrimitiveId will need to declare either the ifdef::VK_NV_mesh_shader[code:MeshShadingNV,] +ifdef::VK_EXT_mesh_shader[code:MeshShadingEXT,] code:Geometry or code:Tessellation capability to satisfy the requirement SPIR-V has to use code:PrimitiveId. ==== @@ -3178,9 +3226,10 @@ SPIR-V has to use code:PrimitiveId. **** * [[VUID-{refpage}-PrimitiveId-04330]] The code:PrimitiveId decoration must: be used only within the - code:MeshNV, code:IntersectionKHR, code:AnyHitKHR, code:ClosestHitKHR, - code:TessellationControl, code:TessellationEvaluation, code:Geometry, or - code:Fragment {ExecutionModel} + code:MeshEXT, code:MeshNV, code:IntersectionKHR, code:AnyHitKHR, + code:ClosestHitKHR, code:TessellationControl, + code:TessellationEvaluation, code:Geometry, or code:Fragment + {ExecutionModel} * [[VUID-{refpage}-Fragment-04331]] If pipeline contains both the code:Fragment and code:Geometry {ExecutionModel} and a variable decorated with code:PrimitiveId is read @@ -3188,15 +3237,16 @@ SPIR-V has to use code:PrimitiveId. the output variables decorated with code:PrimitiveId in all execution paths * [[VUID-{refpage}-Fragment-04332]] - If pipeline contains both the code:Fragment and code:MeshNV - {ExecutionModel} and a variable decorated with code:PrimitiveId is read - from code:Fragment shader, then the code:MeshNV shader must: write to - the output variables decorated with code:PrimitiveId in all execution - paths + If pipeline contains both the code:Fragment and code:MeshEXT or + code:MeshNV {ExecutionModel} and a variable decorated with + code:PrimitiveId is read from code:Fragment shader, then the + code:MeshEXT or code:MeshNV shader must: write to the output variables + decorated with code:PrimitiveId in all execution paths * [[VUID-{refpage}-Fragment-04333]] If code:Fragment {ExecutionModel} contains a variable decorated with - code:PrimitiveId, then either the code:MeshShadingNV, code:Geometry or - code:Tessellation capability must: also be declared + code:PrimitiveId, then either the code:MeshShadingEXT, + code:MeshShadingNV, code:Geometry or code:Tessellation capability must: + also be declared * [[VUID-{refpage}-PrimitiveId-04334]] The variable decorated with code:PrimitiveId within the code:TessellationControl, code:TessellationEvaluation, code:Fragment, @@ -3207,11 +3257,16 @@ SPIR-V has to use code:PrimitiveId. {ExecutionModel} must: be declared using the code:Input or code:Output {StorageClass} * [[VUID-{refpage}-PrimitiveId-04336]] - The variable decorated with code:PrimitiveId within the code:MeshNV - {ExecutionModel} must: be declared using the code:Output {StorageClass} + The variable decorated with code:PrimitiveId within the code:MeshEXT or + code:MeshNV {ExecutionModel} must: be declared using the code:Output + {StorageClass} * [[VUID-{refpage}-PrimitiveId-04337]] The variable decorated with code:PrimitiveId must: be declared as a scalar 32-bit integer value + * [[VUID-{refpage}-PrimitiveId-07040]] + The variable decorated with code:PrimitiveId within the code:MeshEXT + {ExecutionModel} must: also be decorated with the code:PerPrimitiveEXT + decoration **** -- @@ -3261,6 +3316,116 @@ generates a primitive. -- endif::VK_NV_mesh_shader[] +ifdef::VK_EXT_mesh_shader[] +[[interfaces-builtin-variables-primitivepointindices]] +[open,refpage='PrimitivePointIndicesEXT',desc='Indices of point primitives in a mesh shader',type='builtins'] +-- +:refpage: PrimitivePointIndicesEXT + +code:PrimitivePointIndicesEXT:: ++ +Decorating a variable with the code:PrimitivePointIndicesEXT decoration will +make that variable contain the output array of vertex index values for point +primitives. + +.Valid Usage +**** + * [[VUID-{refpage}-PrimitivePointIndicesEXT-07041]] + The code:PrimitivePointIndicesEXT decoration must: be used only within + the code:MeshEXT {ExecutionModel} + * [[VUID-{refpage}-PrimitivePointIndicesEXT-07042]] + The code:PrimitivePointIndicesEXT decoration must: be used only with the + the code:OutputPoints {ExecutionMode} + * [[VUID-{refpage}-PrimitivePointIndicesEXT-07043]] + The variable decorated with code:PrimitivePointIndicesEXT must: be + declared using the code:Output {StorageClass} + * [[VUID-{refpage}-PrimitivePointIndicesEXT-07044]] + The variable decorated with code:PrimitivePointIndicesEXT must: be + declared as an array of scalar 32-bit integer values + * [[VUID-{refpage}-PrimitivePointIndicesEXT-07045]] + All index values of the array decorated with + code:PrimitivePointIndicesEXT must: be in the range [eq]#[0, N-1]#, + where [eq]#N# is the value specified by the code:OutputVertices + {ExecutionMode} + * [[VUID-{refpage}-PrimitivePointIndicesEXT-07046]] + The size of the array decorated with code:PrimitivePointIndicesEXT must: + match the value specified by code:OutputPrimitivesEXT +**** +-- + +[[interfaces-builtin-variables-primitivelineindices]] +[open,refpage='PrimitiveLineIndicesEXT',desc='Indices of line primitives in a mesh shader',type='builtins'] +-- +:refpage: PrimitiveLineIndicesEXT + +code:PrimitiveLineIndicesEXT:: ++ +Decorating a variable with the code:PrimitiveLineIndicesEXT decoration will +make that variable contain the output array of vertex index values for line +primitives. + +.Valid Usage +**** + * [[VUID-{refpage}-PrimitiveLineIndicesEXT-07047]] + The code:PrimitiveLineIndicesEXT decoration must: be used only within + the code:MeshEXT {ExecutionModel} + * [[VUID-{refpage}-PrimitiveLineIndicesEXT-07048]] + The code:PrimitiveLineIndicesEXT decoration must: be used only with the + the code:OutputLinesEXT {ExecutionMode} + * [[VUID-{refpage}-PrimitiveLineIndicesEXT-07049]] + The variable decorated with code:PrimitiveLineIndicesEXT must: be + declared using the code:Output {StorageClass} + * [[VUID-{refpage}-PrimitiveLineIndicesEXT-07050]] + The variable decorated with code:PrimitiveLineIndicesEXT must: be + declared as an array of two component vector 32-bit integer values + * [[VUID-{refpage}-PrimitiveLineIndicesEXT-07051]] + All index values of the array decorated with + code:PrimitiveLineIndicesEXT must: be in the range [eq]#[0, N-1]#, where + [eq]#N# is the value specified by the code:OutputVertices + {ExecutionMode} + * [[VUID-{refpage}-PrimitiveLineIndicesEXT-07052]] + The size of the array decorated with code:PrimitiveLineIndicesEXT must: + match the value specified by code:OutputPrimitivesEXT +**** +-- + +[[interfaces-builtin-variables-primitivetriangleindices]] +[open,refpage='PrimitiveTriangleIndicesEXT',desc='Indices of triangle primitives in a mesh shader',type='builtins'] +-- +:refpage: PrimitiveTriangleIndicesEXT + +code:PrimitiveTriangleIndicesEXT:: ++ +Decorating a variable with the code:PrimitiveTriangleIndicesEXT decoration +will make that variable contain the output array of vertex index values for +triangle primitives. + +.Valid Usage +**** + * [[VUID-{refpage}-PrimitiveTriangleIndicesEXT-07053]] + The code:PrimitiveTriangleIndicesEXT decoration must: be used only + within the code:MeshEXT {ExecutionModel} + * [[VUID-{refpage}-PrimitiveTriangleIndicesEXT-07054]] + The code:PrimitiveTriangleIndicesEXT decoration must: be used only with + the the code:OutputTrianglesEXT {ExecutionMode} + * [[VUID-{refpage}-PrimitiveTriangleIndicesEXT-07055]] + The variable decorated with code:PrimitiveTriangleIndicesEXT must: be + declared using the code:Output {StorageClass} + * [[VUID-{refpage}-PrimitiveTriangleIndicesEXT-07056]] + The variable decorated with code:PrimitiveTriangleIndicesEXT must: be + declared as an array of three component vector 32-bit integer values + * [[VUID-{refpage}-PrimitiveTriangleIndicesEXT-07057]] + All index values of the array decorated with + code:PrimitiveTriangleIndicesEXT must: be in the range [eq]#[0, N-1]#, + where [eq]#N# is the value specified by the code:OutputVertices + {ExecutionMode} + * [[VUID-{refpage}-PrimitiveTriangleIndicesEXT-07058]] + The size of the array decorated with code:PrimitiveTriangleIndicesEXT + must: match the value specified by code:OutputPrimitivesEXT +**** +-- +endif::VK_EXT_mesh_shader[] + ifdef::VK_KHR_fragment_shading_rate[] [[interfaces-builtin-variables-primitiveshadingrate]] [open,refpage='PrimitiveShadingRateKHR',desc='Primitive contribution to fragment shading rate',type='builtins'] @@ -3297,7 +3462,8 @@ value is undefined: for executions of the shader that take that path. **** * [[VUID-{refpage}-PrimitiveShadingRateKHR-04484]] The code:PrimitiveShadingRateKHR decoration must: be used only within - the code:MeshNV, code:Vertex, or code:Geometry {ExecutionModel} + the code:MeshEXT, code:MeshNV, code:Vertex, or code:Geometry + {ExecutionModel} * [[VUID-{refpage}-PrimitiveShadingRateKHR-04485]] The variable decorated with code:PrimitiveShadingRateKHR must: be declared using the code:Output {StorageClass} @@ -3314,6 +3480,10 @@ value is undefined: for executions of the shader that take that path. The value written to code:PrimitiveShadingRateKHR must: not have any bits set other than those defined by *Fragment Shading Rate Flags* enumerants in the SPIR-V specification + * [[VUID-{refpage}-PrimitiveShadingRateKHR-07059]] + The variable decorated with code:PrimitiveShadingRateKHR within the + code:MeshEXT {ExecutionModel} must: also be decorated with the + code:PerPrimitiveEXT decoration **** -- endif::VK_KHR_fragment_shading_rate[] @@ -3636,7 +3806,8 @@ This variable is in range [0, code:NumSubgroups-1]. **** * [[VUID-{refpage}-SubgroupId-04367]] The code:SubgroupId decoration must: be used only within the - code:GLCompute, code:MeshNV, or code:TaskNV {ExecutionModel} + code:GLCompute, code:MeshEXT, code:TaskEXT, code:MeshNV, or code:TaskNV + {ExecutionModel} * [[VUID-{refpage}-SubgroupId-04368]] The variable decorated with code:SubgroupId must: be declared using the code:Input {StorageClass} @@ -4122,8 +4293,9 @@ If multiview is not enabled in the render pass, this value will be zero. .Valid Usage **** * [[VUID-{refpage}-ViewIndex-04401]] - The code:ViewIndex decoration must: not be used within the - code:GLCompute {ExecutionModel} + The code:ViewIndex decoration must: be used only within the + code:MeshEXT, code:Vertex, code:Geometry, code:TessellationControl, + code:TessellationEvaluation or code:Fragment {ExecutionModel} * [[VUID-{refpage}-ViewIndex-04402]] The variable decorated with code:ViewIndex must: be declared using the code:Input {StorageClass} @@ -4146,9 +4318,7 @@ make that variable contain the index of the viewport. + In a ifdef::VK_VERSION_1_2,VK_EXT_shader_viewport_index_layer,VK_NV_viewport_array2[] -ifdef::VK_NV_mesh_shader[] -mesh, -endif::VK_NV_mesh_shader[] +ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[mesh,] vertex, tessellation evaluation, or endif::VK_VERSION_1_2,VK_EXT_shader_viewport_index_layer,VK_NV_viewport_array2[] geometry shader, the variable decorated with code:ViewportIndex can be @@ -4189,8 +4359,8 @@ belongs to. **** * [[VUID-{refpage}-ViewportIndex-04404]] The code:ViewportIndex decoration must: be used only within the - code:MeshNV, code:Vertex, code:TessellationEvaluation, code:Geometry, or - code:Fragment {ExecutionModel} + code:MeshEXT, code:MeshNV, code:Vertex, code:TessellationEvaluation, + code:Geometry, or code:Fragment {ExecutionModel} ifdef::VK_VERSION_1_2[] * [[VUID-{refpage}-ViewportIndex-04405]] If the <>. + * [[limits-maxTaskWorkGroupCount]] pname:maxTaskWorkGroupCount[3] is the + maximum number of local workgroups that can: be launched by a single + mesh tasks drawing command. + These three values represent the maximum number of local workgroups for + the X, Y, and Z dimensions, respectively. + The workgroup count parameters to the drawing commands must: be less + than or equal to the corresponding limit. + The product of these dimensions must: be less than or equal to + pname:maxTaskWorkGroupTotalCount. + * [[limits-maxTaskWorkGroupInvocations]] pname:maxTaskWorkGroupInvocations + is the maximum total number of task shader invocations in a single local + workgroup. + The product of the X, Y, and Z sizes, as specified by the code:LocalSize +ifdef::VK_KHR_maintenance4[or code:LocalSizeId] + execution mode in shader modules or by the object decorated by the + code:WorkgroupSize decoration, must: be less than or equal to this + limit. + * [[limits-maxTaskWorkGroupSize]] pname:maxTaskWorkGroupSize[3] is the + maximum size of a local task workgroup, per dimension. + These three values represent the maximum local workgroup size in the X, + Y, and Z dimensions, respectively. + The pname:x, pname:y, and pname:z sizes, as specified by the + code:LocalSize +ifdef::VK_KHR_maintenance4[or code:LocalSizeId] + execution mode or by the object decorated by the code:WorkgroupSize + decoration in shader modules, must: be less than or equal to the + corresponding limit. + * [[limits-maxTaskPayloadSize]] pname:maxTaskPayloadSize is the maximum + total storage size, in bytes, available for variables declared with the + code:TaskPayloadWorkgroupEXT storage class in shader modules in the task + shader stage. + * [[limits-maxTaskSharedMemorySize]] pname:maxTaskSharedMemorySize is the + maximum total storage size, in bytes, available for variables declared + with the code:Workgroup storage class in shader modules in the task + shader stage. + * [[limits-maxTaskPayloadAndSharedMemorySize]] + pname:maxTaskPayloadAndSharedMemorySize is the maximum total storage + size, in bytes, available for variables that are declared with the + code:TaskPayloadWorkgroupEXT or code:Workgroup storage class, in shader + modules in the task shader stage. + * [[limits-maxMeshWorkGroupTotalCount]] pname:maxMeshWorkGroupTotalCount + is the maximum number of local output tasks a single task shader + workgroup can emit. + * [[limits-maxMeshWorkGroupCount]] pname:maxMeshWorkGroupCount[3] is the + maximum number of local output tasks a single task shader workgroup can + emit, per dimension. + These three values represent the maximum number of local output tasks + for the X, Y, and Z dimensions, respectively. + The workgroup count parameters to the code:OpEmitMeshTasksEXT must: be + less than or equal to the corresponding limit. + The product of these dimensions must: be less than or equal to + pname:maxMeshWorkGroupTotalCount. + * [[limits-maxMeshWorkGroupInvocations]] pname:maxMeshWorkGroupInvocations + is the maximum total number of mesh shader invocations in a single local + workgroup. + The product of the X, Y, and Z sizes, as specified by the code:LocalSize +ifdef::VK_KHR_maintenance4[or code:LocalSizeId] + execution mode in shader modules or by the object decorated by the + code:WorkgroupSize decoration, must: be less than or equal to this + limit. + * [[limits-maxMeshWorkGroupSize]] pname:maxMeshWorkGroupSize[3] is the + maximum size of a local mesh workgroup, per dimension. + These three values represent the maximum local workgroup size in the X, + Y, and Z dimensions, respectively. + The pname:x, pname:y, and pname:z sizes, as specified by the + code:LocalSize +ifdef::VK_KHR_maintenance4[or code:LocalSizeId] + execution mode or by the object decorated by the code:WorkgroupSize + decoration in shader modules, must: be less than or equal to the + corresponding limit. + * [[limits-maxMeshSharedMemorySize]] pname:maxMeshSharedMemorySize is the + maximum total storage size, in bytes, available for variables declared + with the code:Workgroup storage class in shader modules in the mesh + shader stage. + * [[limits-maxMeshPayloadAndSharedMemorySize]] + pname:maxMeshPayloadAndSharedMemorySize is the maximum total storage + size, in bytes, available for variables that are declared with the + code:TaskPayloadWorkgroupEXT or code:Workgroup storage class in shader + modules in the mesh shader stage. + * [[limits-maxMeshOutputMemorySize]] pname:maxMeshOutputMemorySize is the + maximum total storage size, in bytes, available for output variables in + shader modules in the mesh shader stage, according to the formula in + <>. + * [[limits-maxMeshPayloadAndOutputMemorySize]] + pname:maxMeshPayloadAndOutputMemorySize is the maximum total storage + size, in bytes, available for variables that are declared with the + code:TaskPayloadWorkgroupEXT storage class, or output variables in + shader modules in the mesh shader stage, according to the formula in + <>. + * [[limits-maxMeshOutputComponents]] pname:maxMeshOutputComponents is the + maximum number of components of output variables which can: be output + from the mesh shader stage. + * [[limits-maxMeshOutputVertices]] pname:maxMeshOutputVertices is the + maximum number of vertices which can: be emitted by a single mesh shader + workgroup. + * [[limits-maxMeshOutputPrimitives]] pname:maxMeshOutputPrimitives is the + maximum number of primitives which can: be emitted by a single mesh + shader workgroup. + * [[limits-maxMeshOutputLayers]] pname:maxMeshOutputLayers is one greater + than the maximum layer index that can: be output from the mesh shader + stage. + * [[limits-maxMeshMultiviewViewCount]] pname:maxMeshMultiviewViewCount is + one greater than the maximum view index that can: be used by any mesh + shader. + * [[limits-meshOutputPerVertexGranularity]] + pname:meshOutputPerVertexGranularity is the granularity of vertex + allocation. + The number of output vertices allocated for the mesh shader stage is + padded to a multiple of this number. + The value can be used to calculate the required storage size for output + variables in shader modules in the mesh shader stage, which must: be + less than or equal to pname:maxMeshOutputMemorySize. + * [[limits-meshOutputPerPrimitiveGranularity]] + pname:meshOutputPerPrimitiveGranularity is the granularity of primitive + allocation. + The number of output primitives allocated for the mesh shader stage is + padded to a multiple of this number. + The value can be used to calculate the required storage size for output + variables in shader modules in the mesh shader stage, which must: be + less than or equal to pname:maxMeshOutputMemorySize. + * [[limits-maxPreferredTaskWorkGroupInvocations]] + pname:maxPreferredTaskWorkGroupInvocations is the maximum number of task + shader invocations in a single workgroup that is preferred by the + implementation for optimal performance. + The value is guaranteed to be a multiple of a supported subgroup size + for the task shader stage. + * [[limits-maxPreferredMeshWorkGroupInvocations]] + pname:maxPreferredMeshWorkGroupInvocations is the maximum number of mesh + shader invocations in a single workgroup that is preferred by the + implementation for optimal performance. + The value is guaranteed to be a multiple of a supported subgroup size + for the mesh shader stage. + * [[limits-prefersLocalInvocationVertexOutput]] + pname:prefersLocalInvocationVertexOutput specifies whether writes to the + vertex output array in a mesh shader yield best performance when the + array index matches code:LocalInvocationIndex. + * [[limits-prefersLocalInvocationPrimitiveOutput]] + pname:prefersLocalInvocationPrimitiveOutput specifies whether writes to + the primitive output array in a mesh shader yield best performance when + the array index matches code:LocalInvocationIndex. + * [[limits-prefersCompactVertexOutput]] pname:prefersCompactVertexOutput + specifies whether output vertices should be compacted after custom + culling in the mesh shader for best performance, otherwise keeping the + vertices at their original location may be better. + * [[limits-prefersCompactPrimitiveOutput]] + pname:prefersCompactPrimitiveOutput specifies whether output primitives + should be compacted after custom culling in the mesh shader for best + performance, otherwise the use of code:CullPrimitiveEXT may be better. + +If the sname:VkPhysicalDeviceMeshShaderPropertiesEXT structure is included +in the pname:pNext chain of slink:VkPhysicalDeviceProperties2, it is filled +with the implementation-dependent limits. + +include::{generated}/validity/structs/VkPhysicalDeviceMeshShaderPropertiesEXT.adoc[] +-- + +endif::VK_EXT_mesh_shader[] + ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] [open,refpage='VkPhysicalDeviceDescriptorIndexingProperties',desc='Structure describing descriptor indexing properties that can be supported by an implementation',type='structs',alias='VkPhysicalDeviceDescriptorIndexingPropertiesEXT'] -- @@ -3555,20 +3731,50 @@ ifdef::VK_EXT_vertex_attribute_divisor[] | code:uint32_t | pname:maxVertexAttribDivisor | `apiext:VK_EXT_vertex_attribute_divisor` endif::VK_EXT_vertex_attribute_divisor[] ifdef::VK_NV_mesh_shader[] -| code:uint32_t | pname:maxDrawMeshTasksCount | `apiext:VK_NV_mesh_shader` -| code:uint32_t | pname:maxTaskWorkGroupInvocations | `apiext:VK_NV_mesh_shader` -| code:uint32_t | pname:maxTaskWorkGroupSize | `apiext:VK_NV_mesh_shader` -| code:uint32_t | pname:maxTaskTotalMemorySize | `apiext:VK_NV_mesh_shader` -| code:uint32_t | pname:maxTaskOutputCount | `apiext:VK_NV_mesh_shader` -| code:uint32_t | pname:maxMeshWorkGroupInvocations | `apiext:VK_NV_mesh_shader` -| code:uint32_t | pname:maxMeshWorkGroupSize | `apiext:VK_NV_mesh_shader` -| code:uint32_t | pname:maxMeshTotalMemorySize | `apiext:VK_NV_mesh_shader` -| code:uint32_t | pname:maxMeshOutputVertices | `apiext:VK_NV_mesh_shader` -| code:uint32_t | pname:maxMeshOutputPrimitives | `apiext:VK_NV_mesh_shader` -| code:uint32_t | pname:maxMeshMultiviewViewCount | `apiext:VK_NV_mesh_shader` -| code:uint32_t | pname:meshOutputPerVertexGranularity | `apiext:VK_NV_mesh_shader` -| code:uint32_t | pname:meshOutputPerPrimitiveGranularity | `apiext:VK_NV_mesh_shader` +| code:uint32_t | slink:VkPhysicalDeviceMeshShaderPropertiesNV::pname:maxDrawMeshTasksCount | `apiext:VK_NV_mesh_shader` +| code:uint32_t | slink:VkPhysicalDeviceMeshShaderPropertiesNV::pname:maxTaskWorkGroupInvocations | `apiext:VK_NV_mesh_shader` +| 3 {times} code:uint32_t | slink:VkPhysicalDeviceMeshShaderPropertiesNV::pname:maxTaskWorkGroupSize | `apiext:VK_NV_mesh_shader` +| code:uint32_t | slink:VkPhysicalDeviceMeshShaderPropertiesNV::pname:maxTaskTotalMemorySize | `apiext:VK_NV_mesh_shader` +| code:uint32_t | slink:VkPhysicalDeviceMeshShaderPropertiesNV::pname:maxTaskOutputCount | `apiext:VK_NV_mesh_shader` +| code:uint32_t | slink:VkPhysicalDeviceMeshShaderPropertiesNV::pname:maxMeshWorkGroupInvocations | `apiext:VK_NV_mesh_shader` +| 3 {times} code:uint32_t | slink:VkPhysicalDeviceMeshShaderPropertiesNV::pname:maxMeshWorkGroupSize | `apiext:VK_NV_mesh_shader` +| code:uint32_t | slink:VkPhysicalDeviceMeshShaderPropertiesNV::pname:maxMeshTotalMemorySize | `apiext:VK_NV_mesh_shader` +| code:uint32_t | slink:VkPhysicalDeviceMeshShaderPropertiesNV::pname:maxMeshOutputVertices | `apiext:VK_NV_mesh_shader` +| code:uint32_t | slink:VkPhysicalDeviceMeshShaderPropertiesNV::pname:maxMeshOutputPrimitives | `apiext:VK_NV_mesh_shader` +| code:uint32_t | slink:VkPhysicalDeviceMeshShaderPropertiesNV::pname:maxMeshMultiviewViewCount | `apiext:VK_NV_mesh_shader` +| code:uint32_t | slink:VkPhysicalDeviceMeshShaderPropertiesNV::pname:meshOutputPerVertexGranularity | `apiext:VK_NV_mesh_shader` +| code:uint32_t | slink:VkPhysicalDeviceMeshShaderPropertiesNV::pname:meshOutputPerPrimitiveGranularity | `apiext:VK_NV_mesh_shader` endif::VK_NV_mesh_shader[] +ifdef::VK_EXT_mesh_shader[] +| code:uint32_t | slink:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxTaskWorkGroupTotalCount | `apiext:VK_EXT_mesh_shader` +| 3 {times} code:uint32_t | slink:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxTaskWorkGroupCount | `apiext:VK_EXT_mesh_shader` +| code:uint32_t | slink:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxTaskWorkGroupInvocations | `apiext:VK_EXT_mesh_shader` +| 3 {times} code:uint32_t | slink:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxTaskWorkGroupSize | `apiext:VK_EXT_mesh_shader` +| code:uint32_t | slink:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxTaskPayloadSize | `apiext:VK_EXT_mesh_shader` +| code:uint32_t | slink:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxTaskSharedMemorySize | `apiext:VK_EXT_mesh_shader` +| code:uint32_t | slink:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxTaskPayloadAndSharedMemorySize | `apiext:VK_EXT_mesh_shader` +| code:uint32_t | slink:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxMeshWorkGroupTotalCount | `apiext:VK_EXT_mesh_shader` +| 3 {times} code:uint32_t | slink:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxMeshWorkGroupCount | `apiext:VK_EXT_mesh_shader` +| code:uint32_t | slink:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxMeshWorkGroupInvocations | `apiext:VK_EXT_mesh_shader` +| 3 {times} code:uint32_t | slink:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxMeshWorkGroupSize | `apiext:VK_EXT_mesh_shader` +| code:uint32_t | slink:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxMeshSharedMemorySize | `apiext:VK_EXT_mesh_shader` +| code:uint32_t | slink:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxMeshPayloadAndSharedMemorySize | `apiext:VK_EXT_mesh_shader` +| code:uint32_t | slink:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxMeshOutputMemorySize | `apiext:VK_EXT_mesh_shader` +| code:uint32_t | slink:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxMeshPayloadAndOutputMemorySize | `apiext:VK_EXT_mesh_shader` +| code:uint32_t | slink:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxMeshOutputComponents | `apiext:VK_EXT_mesh_shader` +| code:uint32_t | slink:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxMeshOutputVertices | `apiext:VK_EXT_mesh_shader` +| code:uint32_t | slink:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxMeshOutputPrimitives | `apiext:VK_EXT_mesh_shader` +| code:uint32_t | slink:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxMeshOutputLayers | `apiext:VK_EXT_mesh_shader` +| code:uint32_t | slink:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxMeshMultiviewViewCount | `apiext:VK_EXT_mesh_shader` +| code:uint32_t | slink:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:meshOutputPerVertexGranularity | `apiext:VK_EXT_mesh_shader` +| code:uint32_t | slink:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:meshOutputPerPrimitiveGranularity | `apiext:VK_EXT_mesh_shader` +| code:uint32_t | slink:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxPreferredTaskWorkGroupInvocations | `apiext:VK_EXT_mesh_shader` +| code:uint32_t | slink:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxPreferredMeshWorkGroupInvocations | `apiext:VK_EXT_mesh_shader` +| basetype:VkBool32 | slink:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:prefersLocalInvocationVertexOutput | `apiext:VK_EXT_mesh_shader` +| basetype:VkBool32 | slink:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:prefersLocalInvocationPrimitiveOutput | `apiext:VK_EXT_mesh_shader` +| basetype:VkBool32 | slink:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:prefersCompactVertexOutput | `apiext:VK_EXT_mesh_shader` +| basetype:VkBool32 | slink:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:prefersCompactPrimitiveOutput | `apiext:VK_EXT_mesh_shader` +endif::VK_EXT_mesh_shader[] ifdef::VK_EXT_transform_feedback[] | code:uint32_t | pname:maxTransformFeedbackStreams | `apiext:VK_EXT_transform_feedback` | code:uint32_t | pname:maxTransformFeedbackBuffers | `apiext:VK_EXT_transform_feedback` @@ -3892,20 +4098,50 @@ ifdef::VK_EXT_vertex_attribute_divisor[] | pname:maxVertexAttribDivisor | - | 2^16^-1 | min endif::VK_EXT_vertex_attribute_divisor[] ifdef::VK_NV_mesh_shader[] -| pname:maxDrawMeshTasksCount | - | 2^16^-1 | min -| pname:maxTaskWorkGroupInvocations | - | 32 | min -| pname:maxTaskWorkGroupSize | - | (32,1,1) | min -| pname:maxTaskTotalMemorySize | - | 16384 | min -| pname:maxTaskOutputCount | - | 2^16^-1 | min -| pname:maxMeshWorkGroupInvocations | - | 32 | min -| pname:maxMeshWorkGroupSize | - | (32,1,1) | min -| pname:maxMeshTotalMemorySize | - | 16384 | min -| pname:maxMeshOutputVertices | - | 256 | min -| pname:maxMeshOutputPrimitives | - | 256 | min -| pname:maxMeshMultiviewViewCount | - | 1 | min -| pname:meshOutputPerVertexGranularity | - | - | implementation-dependent -| pname:meshOutputPerPrimitiveGranularity | - | - | implementation-dependent +| slink:VkPhysicalDeviceMeshShaderPropertiesNV::pname:maxDrawMeshTasksCount | - | 2^16^-1 | min +| slink:VkPhysicalDeviceMeshShaderPropertiesNV::pname:maxTaskWorkGroupInvocations | - | 32 | min +| slink:VkPhysicalDeviceMeshShaderPropertiesNV::pname:maxTaskWorkGroupSize | - | (32,1,1) | min +| slink:VkPhysicalDeviceMeshShaderPropertiesNV::pname:maxTaskTotalMemorySize | - | 16384 | min +| slink:VkPhysicalDeviceMeshShaderPropertiesNV::pname:maxTaskOutputCount | - | 2^16^-1 | min +| slink:VkPhysicalDeviceMeshShaderPropertiesNV::pname:maxMeshWorkGroupInvocations | - | 32 | min +| slink:VkPhysicalDeviceMeshShaderPropertiesNV::pname:maxMeshWorkGroupSize | - | (32,1,1) | min +| slink:VkPhysicalDeviceMeshShaderPropertiesNV::pname:maxMeshTotalMemorySize | - | 16384 | min +| slink:VkPhysicalDeviceMeshShaderPropertiesNV::pname:maxMeshOutputVertices | - | 256 | min +| slink:VkPhysicalDeviceMeshShaderPropertiesNV::pname:maxMeshOutputPrimitives | - | 256 | min +| slink:VkPhysicalDeviceMeshShaderPropertiesNV::pname:maxMeshMultiviewViewCount | - | 1 | min +| slink:VkPhysicalDeviceMeshShaderPropertiesNV::pname:meshOutputPerVertexGranularity | - | - | implementation-dependent +| slink:VkPhysicalDeviceMeshShaderPropertiesNV::pname:meshOutputPerPrimitiveGranularity | - | - | implementation-dependent endif::VK_NV_mesh_shader[] +ifdef::VK_EXT_mesh_shader[] +| slink:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxTaskWorkGroupTotalCount | - | 2^22 | min +| slink:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxTaskWorkGroupCount | - | (65535,65535,65535) | min +| slink:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxTaskWorkGroupInvocations | - | 128 | min +| slink:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxTaskWorkGroupSize | - | (128,128,128) | min +| slink:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxTaskPayloadSize | - | 16384 | min +| slink:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxTaskSharedMemorySize | - | 32768 | min +| slink:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxTaskPayloadAndSharedMemorySize | - | 32768 | min +| slink:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxMeshWorkGroupTotalCount | - | 2^22 | min +| slink:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxMeshWorkGroupCount | - | (65535,65535,65535) | min +| slink:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxMeshWorkGroupInvocations | - | 128 | min +| slink:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxMeshWorkGroupSize | - | (128,128,128) | min +| slink:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxMeshSharedMemorySize | - | 28672 | min +| slink:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxMeshPayloadAndSharedMemorySize | - | 28672 | min +| slink:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxMeshOutputMemorySize | - | 32768 | min +| slink:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxMeshPayloadAndOutputMemorySize | - | 48128 | min +| slink:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxMeshOutputComponents | - | 128 | min +| slink:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxMeshOutputVertices | - | 256 | min +| slink:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxMeshOutputPrimitives | - | 256 | min +| slink:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxMeshOutputLayers | - | 8 | min +| slink:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxMeshMultiviewViewCount | - | 1 | min +| slink:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:meshOutputPerVertexGranularity | 0 | 32 | max +| slink:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:meshOutputPerPrimitiveGranularity | 0 | 32 | max +| slink:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxPreferredTaskWorkGroupInvocations | - | - | implementation-dependent +| slink:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxPreferredMeshWorkGroupInvocations | - | - | implementation-dependent +| slink:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:prefersLocalInvocationVertexOutput | - | - | implementation-dependent +| slink:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:prefersLocalInvocationPrimitiveOutput | - | - | implementation-dependent +| slink:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:prefersCompactVertexOutput | - | - | implementation-dependent +| slink:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:prefersCompactPrimitiveOutput | - | - | implementation-dependent +endif::VK_EXT_mesh_shader[] ifdef::VK_EXT_transform_feedback[] | pname:maxTransformFeedbackStreams | - | 1 | min | pname:maxTransformFeedbackBuffers | - | 1 | min diff --git a/chapters/pipelines.adoc b/chapters/pipelines.adoc index c85107f1da..d97eca4133 100644 --- a/chapters/pipelines.adoc +++ b/chapters/pipelines.adoc @@ -18,13 +18,13 @@ a _ray tracing pipeline_, endif::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] or a _compute pipeline_. -ifdef::VK_NV_mesh_shader[] +ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] The graphics pipeline can be operated in two modes, as either _primitive shading_ or _mesh shading_ pipeline. *Primitive Shading* -endif::VK_NV_mesh_shader[] +endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] The first stage of the <> (<>) assembles vertices to form geometric @@ -37,7 +37,7 @@ supported, they can: then generate multiple primitives from a single input primitive, possibly changing the primitive topology or generating additional attribute data in the process. -ifdef::VK_NV_mesh_shader[] +ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] *Mesh Shading* When using the <> pipeline input primitives are not @@ -55,7 +55,7 @@ that produces an output mesh with a variable-sized number of primitives assembled from vertices stored in the output mesh. *Common* -endif::VK_NV_mesh_shader[] +endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] The final resulting primitives are <> to a clip volume in preparation for the next stage, <>. @@ -83,12 +83,12 @@ Actual ordering guarantees between pipeline stages are explained in detail in the <>. [[pipelines-block-diagram]] -ifndef::VK_NV_mesh_shader[] +ifndef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] image::{images}/pipeline.svg[title="Block diagram of the Vulkan pipeline",align="center",opts="{imageopts}"] -endif::VK_NV_mesh_shader[] -ifdef::VK_NV_mesh_shader[] +endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] +ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] image::{images}/pipelinemesh.svg[title="Block diagram of the Vulkan pipeline",align="center",opts="{imageopts}"] -endif::VK_NV_mesh_shader[] +endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] Each pipeline is controlled by a monolithic object created from a description of all of the shader stages and any relevant fixed-function @@ -395,14 +395,14 @@ endif::VK_EXT_shader_module_identifier[] is not enabled, pname:stage must: not be ename:VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT or ename:VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT -ifdef::VK_NV_mesh_shader[] +ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] * [[VUID-VkPipelineShaderStageCreateInfo-stage-02091]] - If the <> feature is not enabled, - pname:stage must: not be ename:VK_SHADER_STAGE_MESH_BIT_NV + If the <> feature is not + enabled, pname:stage must: not be ename:VK_SHADER_STAGE_MESH_BIT_EXT * [[VUID-VkPipelineShaderStageCreateInfo-stage-02092]] - If the <> feature is not enabled, - pname:stage must: not be ename:VK_SHADER_STAGE_TASK_BIT_NV -endif::VK_NV_mesh_shader[] + If the <> feature is not + enabled, pname:stage must: not be ename:VK_SHADER_STAGE_TASK_BIT_EXT +endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] * [[VUID-VkPipelineShaderStageCreateInfo-stage-00706]] pname:stage must: not be ename:VK_SHADER_STAGE_ALL_GRAPHICS, or ename:VK_SHADER_STAGE_ALL @@ -452,17 +452,19 @@ endif::VK_NV_mesh_shader[] invocation count that is greater than `0` and less than or equal to sname:VkPhysicalDeviceLimits::pname:maxGeometryShaderInvocations * [[VUID-VkPipelineShaderStageCreateInfo-stage-02596]] - If pname:stage is a - <>, and the identified entry point writes to code:Layer for any - primitive, it must: write the same value to code:Layer for all vertices - of a given primitive + If pname:stage is either ename:VK_SHADER_STAGE_VERTEX_BIT, + ename:VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT, + ename:VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT, or + ename:VK_SHADER_STAGE_GEOMETRY_BIT, and the identified entry point + writes to code:Layer for any primitive, it must: write the same value to + code:Layer for all vertices of a given primitive * [[VUID-VkPipelineShaderStageCreateInfo-stage-02597]] - If pname:stage is a - <>, and the identified entry point writes to code:ViewportIndex for - any primitive, it must: write the same value to code:ViewportIndex for - all vertices of a given primitive + If pname:stage is either ename:VK_SHADER_STAGE_VERTEX_BIT, + ename:VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT, + ename:VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT, or + ename:VK_SHADER_STAGE_GEOMETRY_BIT, and the identified entry point + writes to code:ViewportIndex for any primitive, it must: write the same + value to code:ViewportIndex for all vertices of a given primitive * [[VUID-VkPipelineShaderStageCreateInfo-stage-00718]] If pname:stage is ename:VK_SHADER_STAGE_FRAGMENT_BIT, the identified entry point must: not include any output variables in its interface @@ -483,18 +485,36 @@ ifdef::VK_EXT_shader_stencil_export[] endif::VK_EXT_shader_stencil_export[] ifdef::VK_NV_mesh_shader[] * [[VUID-VkPipelineShaderStageCreateInfo-stage-02093]] - If pname:stage is ename:VK_SHADER_STAGE_MESH_BIT_NV, the identified - entry point must: have an code:OpExecutionMode instruction specifying a - maximum output vertex count, code:OutputVertices, that is greater than - `0` and less than or equal to + If pname:stage is ename:VK_SHADER_STAGE_MESH_BIT_NV and the code:MeshNV + {ExecutionModel} is used, the identified entry point must: have an + code:OpExecutionMode instruction specifying a maximum output vertex + count, code:OutputVertices, that is greater than `0` and less than or + equal to sname:VkPhysicalDeviceMeshShaderPropertiesNV::pname:maxMeshOutputVertices * [[VUID-VkPipelineShaderStageCreateInfo-stage-02094]] - If pname:stage is ename:VK_SHADER_STAGE_MESH_BIT_NV, the identified - entry point must: have an code:OpExecutionMode instruction specifying a - maximum output primitive count, code:OutputPrimitivesNV, that is greater - than `0` and less than or equal to + If pname:stage is ename:VK_SHADER_STAGE_MESH_BIT_NV and the code:MeshNV + {ExecutionModel} is used, the identified entry point must: have an + code:OpExecutionMode instruction specifying a maximum output primitive + count, code:OutputPrimitivesNV, that is greater than `0` and less than + or equal to sname:VkPhysicalDeviceMeshShaderPropertiesNV::pname:maxMeshOutputPrimitives endif::VK_NV_mesh_shader[] +ifdef::VK_EXT_mesh_shader[] + * [[VUID-VkPipelineShaderStageCreateInfo-stage-07061]] + If pname:stage is ename:VK_SHADER_STAGE_MESH_BIT_EXT and the + code:MeshEXT {ExecutionModel} is used, the identified entry point must: + have an code:OpExecutionMode instruction specifying a maximum output + vertex count, code:OutputVertices, that is greater than `0` and less + than or equal to + sname:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxMeshOutputVertices + * [[VUID-VkPipelineShaderStageCreateInfo-stage-07062]] + If pname:stage is ename:VK_SHADER_STAGE_MESH_BIT_EXT and the + code:MeshEXT {ExecutionModel} is used, the identified entry point must: + have an code:OpExecutionMode instruction specifying a maximum output + primitive count, code:OutputPrimitivesEXT, that is greater than `0` and + less than or equal to + sname:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxMeshOutputPrimitives +endif::VK_EXT_mesh_shader[] ifdef::VK_VERSION_1_3,VK_EXT_subgroup_size_control[] * [[VUID-VkPipelineShaderStageCreateInfo-flags-02784]] If pname:flags has the @@ -669,10 +689,10 @@ include::{generated}/api/enums/VkShaderStageFlagBits.adoc[] * ename:VK_SHADER_STAGE_ALL is a combination of bits used as shorthand to specify all shader stages supported by the device, including all additional stages which are introduced by extensions. -ifdef::VK_NV_mesh_shader[] - * ename:VK_SHADER_STAGE_TASK_BIT_NV specifies the task stage. - * ename:VK_SHADER_STAGE_MESH_BIT_NV specifies the mesh stage. -endif::VK_NV_mesh_shader[] +ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] + * ename:VK_SHADER_STAGE_TASK_BIT_EXT specifies the task stage. + * ename:VK_SHADER_STAGE_MESH_BIT_EXT specifies the mesh stage. +endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] ifdef::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] * ename:VK_SHADER_STAGE_RAYGEN_BIT_KHR specifies the ray generation stage. * ename:VK_SHADER_STAGE_ANY_HIT_BIT_KHR specifies the any-hit stage. @@ -1086,8 +1106,20 @@ include::{generated}/api/structs/VkGraphicsPipelineCreateInfo.adoc[] slink:VkPipelineShaderStageCreateInfo structures describing the set of the shader stages to be included in the graphics pipeline. * pname:pVertexInputState is a pointer to a - slink:VkPipelineVertexInputStateCreateInfo structure defining vertex - input state for use with vertex shading. + slink:VkPipelineVertexInputStateCreateInfo structure. +ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] + It is ignored if the pipeline includes a mesh shader stage. +endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] +ifdef::VK_EXT_vertex_input_dynamic_state[] + It is ignored if the pipeline is created with the + ename:VK_DYNAMIC_STATE_VERTEX_INPUT_EXT dynamic state set. +endif::VK_EXT_vertex_input_dynamic_state[] + * pname:pInputAssemblyState is a pointer to a + slink:VkPipelineInputAssemblyStateCreateInfo structure which determines + input assembly behavior, as described in <>. +ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] + It is ignored if the pipeline includes a mesh shader stage. +endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] * pname:pInputAssemblyState is a pointer to a slink:VkPipelineInputAssemblyStateCreateInfo structure which determines input assembly behavior for vertex shading, as described in <> the pname:stage member of one element of pname:pStages must: be ename:VK_SHADER_STAGE_VERTEX_BIT -endif::VK_NV_mesh_shader[] -ifdef::VK_NV_mesh_shader[] +endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] +ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] * [[VUID-VkGraphicsPipelineCreateInfo-pStages-02095]] If the pipeline is being created with <> the geometric shader stages provided in pname:pStages must: be either from the mesh shading pipeline (pname:stage is - ename:VK_SHADER_STAGE_TASK_BIT_NV or ename:VK_SHADER_STAGE_MESH_BIT_NV) - or from the primitive shading pipeline (pname:stage is - ename:VK_SHADER_STAGE_VERTEX_BIT, + ename:VK_SHADER_STAGE_TASK_BIT_EXT or + ename:VK_SHADER_STAGE_MESH_BIT_EXT) or from the primitive shading + pipeline (pname:stage is ename:VK_SHADER_STAGE_VERTEX_BIT, ename:VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT, ename:VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT, or ename:VK_SHADER_STAGE_GEOMETRY_BIT) @@ -1337,8 +1369,15 @@ ifdef::VK_NV_mesh_shader[] <> the pname:stage member of one element of pname:pStages must: be either ename:VK_SHADER_STAGE_VERTEX_BIT or - ename:VK_SHADER_STAGE_MESH_BIT_NV -endif::VK_NV_mesh_shader[] + ename:VK_SHADER_STAGE_MESH_BIT_EXT +endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] +ifdef::VK_NV_mesh_shader+VK_EXT_mesh_shader[] + * [[VUID-VkGraphicsPipelineCreateInfo-TaskNV-07063]] + The shader stages for ename:VK_SHADER_STAGE_TASK_BIT_EXT or + ename:VK_SHADER_STAGE_MESH_BIT_EXT must: use either the code:TaskNV and + code:MeshNV {ExecutionModel} or the code:TaskEXT and code:MeshEXT + {ExecutionModel}, but must: not use both +endif::VK_NV_mesh_shader+VK_EXT_mesh_shader[] * [[VUID-VkGraphicsPipelineCreateInfo-pStages-00729]] If the pipeline is being created with <>, and the pname:renderPass has multiview enabled, then all shaders must: not include variables decorated with the code:Layer built-in decoration in their interfaces +ifdef::VK_EXT_mesh_shader[] + * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-07064]] + If pname:renderPass is a valid renderPass, the pipeline is being created + with <>, and the pname:renderPass has multiview enabled and + pname:subpass has more than one bit set in the view mask and + pname:multiviewMeshShader is not enabled, then pname:pStages must: not + include a mesh shader +endif::VK_EXT_mesh_shader[] endif::VK_VERSION_1_1,VK_KHR_multiview[] ifdef::VK_VERSION_1_1,VK_KHR_device_group[] * [[VUID-VkGraphicsPipelineCreateInfo-flags-00764]] @@ -1855,14 +1903,14 @@ ifdef::VK_EXT_transform_feedback[] code:GeometryStreams capability, then sname:VkPhysicalDeviceTransformFeedbackFeaturesEXT::pname:geometryStreams feature must: be enabled -ifdef::VK_NV_mesh_shader[] +ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] * [[VUID-VkGraphicsPipelineCreateInfo-None-02322]] If the pipeline is being created with <>, and there are any mesh shader stages in the pipeline there must: not be any shader stage in the pipeline with a code:Xfb execution mode -endif::VK_NV_mesh_shader[] +endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] endif::VK_EXT_transform_feedback[] ifdef::VK_EXT_line_rasterization[] * [[VUID-VkGraphicsPipelineCreateInfo-lineRasterizationMode-02766]] @@ -1965,6 +2013,15 @@ endif::VK_VERSION_1_3[] state>>, and ename:VK_DYNAMIC_STATE_SCISSOR_WITH_COUNT is included in the pname:pDynamicStates array then ename:VK_DYNAMIC_STATE_SCISSOR must: not be present +ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] + * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-07065]] + If the pipeline is being created with + <>, and includes a mesh shader, there must: be no element of the + pname:pDynamicStates member of pname:pDynamicState set to + ename:VK_DYNAMIC_STATE_PRIMITIVE_TOPOLOGY, or + ename:VK_DYNAMIC_STATE_VERTEX_INPUT_BINDING_STRIDE +endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state2[] ifndef::VK_VERSION_1_3[] @@ -1987,6 +2044,15 @@ endif::VK_VERSION_1_3[] there must: be no element of the pname:pDynamicStates member of pname:pDynamicState set to ename:VK_DYNAMIC_STATE_PATCH_CONTROL_POINTS_EXT +ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] + * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-07066]] + If the pipeline is being created with + <>, and includes a mesh shader, there must: be no element of the + pname:pDynamicStates member of pname:pDynamicState set to + ename:VK_DYNAMIC_STATE_PRIMITIVE_RESTART_ENABLE, or + ename:VK_DYNAMIC_STATE_PATCH_CONTROL_POINTS_EXT +endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state2[] ifdef::VK_NV_device_generated_commands[] * [[VUID-VkGraphicsPipelineCreateInfo-flags-02877]] @@ -2261,6 +2327,14 @@ ifdef::VK_EXT_vertex_input_dynamic_state[] pname:vertexInputDynamicState>> feature is not enabled, there must: be no element of the pname:pDynamicStates member of pname:pDynamicState set to ename:VK_DYNAMIC_STATE_VERTEX_INPUT_EXT +ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] + * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-07067]] + If the pipeline is being created with + <>, and includes a mesh shader, there must: be no element of the + pname:pDynamicStates member of pname:pDynamicState set to + ename:VK_DYNAMIC_STATE_VERTEX_INPUT_EXT +endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] endif::VK_EXT_vertex_input_dynamic_state[] ifndef::VK_EXT_graphics_pipeline_library[] * [[VUID-VkGraphicsPipelineCreateInfo-None-06573]] @@ -3773,6 +3847,91 @@ endif::VK_EXT_color_write_enable[] -- +=== Valid Combinations of Stages for Graphics Pipelines + +ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] +Primitive processing can be handled either on a per primitive basis by the +vertex, tessellation, and geometry shader stages, or on a per mesh basis +using task and mesh shader stages. +If the pipeline includes a mesh shader stage, it uses the mesh pipeline, +otherwise it uses the primitive pipeline. + +If a task shader is omitted, the task shading stage is skipped. +endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] + +If tessellation shader stages are omitted, the tessellation shading and +fixed-function stages of the pipeline are skipped. + +If a geometry shader is omitted, the geometry shading stage is skipped. + +If a fragment shader is omitted, fragment color outputs have undefined: +values, and the fragment depth value is determined by +<> state. +This can: be useful for depth-only rendering. + +Presence of a shader stage in a pipeline is indicated by including a valid +slink:VkPipelineShaderStageCreateInfo with pname:module and pname:pName +selecting an entry point from a shader module, where that entry point is +valid for the stage specified by pname:stage. + +Presence of some of the fixed-function stages in the pipeline is implicitly +derived from enabled shaders and provided state. +For example, the fixed-function tessellator is always present when the +pipeline has valid Tessellation Control and Tessellation Evaluation shaders. + +.For example: + * Depth/stencil-only rendering in a subpass with no color attachments + ** Active Pipeline Shader Stages + *** Vertex Shader + ** Required: Fixed-Function Pipeline Stages + *** slink:VkPipelineVertexInputStateCreateInfo + *** slink:VkPipelineInputAssemblyStateCreateInfo + *** slink:VkPipelineViewportStateCreateInfo + *** slink:VkPipelineRasterizationStateCreateInfo + *** slink:VkPipelineMultisampleStateCreateInfo + *** slink:VkPipelineDepthStencilStateCreateInfo + * Color-only rendering in a subpass with no depth/stencil attachment + ** Active Pipeline Shader Stages + *** Vertex Shader + *** Fragment Shader + ** Required: Fixed-Function Pipeline Stages + *** slink:VkPipelineVertexInputStateCreateInfo + *** slink:VkPipelineInputAssemblyStateCreateInfo + *** slink:VkPipelineViewportStateCreateInfo + *** slink:VkPipelineRasterizationStateCreateInfo + *** slink:VkPipelineMultisampleStateCreateInfo + *** slink:VkPipelineColorBlendStateCreateInfo + * Rendering pipeline with tessellation and geometry shaders + ** Active Pipeline Shader Stages + *** Vertex Shader + *** Tessellation Control Shader + *** Tessellation Evaluation Shader + *** Geometry Shader + *** Fragment Shader + ** Required: Fixed-Function Pipeline Stages + *** slink:VkPipelineVertexInputStateCreateInfo + *** slink:VkPipelineInputAssemblyStateCreateInfo + *** slink:VkPipelineTessellationStateCreateInfo + *** slink:VkPipelineViewportStateCreateInfo + *** slink:VkPipelineRasterizationStateCreateInfo + *** slink:VkPipelineMultisampleStateCreateInfo + *** slink:VkPipelineDepthStencilStateCreateInfo + *** slink:VkPipelineColorBlendStateCreateInfo +ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] + * Rendering pipeline with task and mesh shaders + ** Active Pipeline Shader Stages + *** Task Shader + *** Mesh Shader + *** Fragment Shader + ** Required: Fixed-Function Pipeline Stages + *** slink:VkPipelineViewportStateCreateInfo + *** slink:VkPipelineRasterizationStateCreateInfo + *** slink:VkPipelineMultisampleStateCreateInfo + *** slink:VkPipelineDepthStencilStateCreateInfo + *** slink:VkPipelineColorBlendStateCreateInfo +endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] + + ifdef::VK_NV_device_generated_commands[] [[graphics-shadergroups]] === Graphics Pipeline Shader Groups @@ -3833,12 +3992,12 @@ based on the pipelines that make use of them. * [[VUID-VkGraphicsPipelineShaderGroupsCreateInfoNV-pGroups-02882]] Each element of pname:pGroups must: in combination with the rest of the pipeline state yield a valid state configuration -ifndef::VK_NV_mesh_shader[] +ifndef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] * [[VUID-VkGraphicsPipelineShaderGroupsCreateInfoNV-pGroups-02883]] All elements of pname:pGroups must: use the same shader stage combinations -endif::VK_NV_mesh_shader[] -ifdef::VK_NV_mesh_shader[] +endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] +ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] * [[VUID-VkGraphicsPipelineShaderGroupsCreateInfoNV-pGroups-02884]] All elements of pname:pGroups must: use the same shader stage combinations unless any mesh shader stage is used, then either @@ -3846,7 +4005,7 @@ ifdef::VK_NV_mesh_shader[] * [[VUID-VkGraphicsPipelineShaderGroupsCreateInfoNV-pGroups-02885]] Mesh and regular primitive shading stages cannot be mixed across pname:pGroups -endif::VK_NV_mesh_shader[] +endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] * [[VUID-VkGraphicsPipelineShaderGroupsCreateInfoNV-pPipelines-02886]] Each element of pname:pPipelines must: have been created with identical state to the pipeline currently created except the state that can be @@ -5809,6 +5968,13 @@ parameter: The state-setting commands must: be recorded after command buffer recording was begun, or after the last command binding a pipeline object with that state specified as static, whichever was the latter. + * If the state is not included (corresponding pointer in + slink:VkGraphicsPipelineCreateInfo was `NULL` or was ignored) in the new + pipeline object, then that command buffer state is not disturbed. +ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] + For example, mesh shading pipelines do not include vertex input state + and therefore do not disturb any such command buffer state. +endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] Dynamic state that does not affect the result of operations can: be left undefined:. diff --git a/chapters/primsrast.adoc b/chapters/primsrast.adoc index 0de4719319..fb7ed5ef8c 100644 --- a/chapters/primsrast.adoc +++ b/chapters/primsrast.adoc @@ -1113,8 +1113,16 @@ The _primitive fragment shading rate_ can: be set via the code:PrimitiveShadingRateKHR>> built-in in the last active <>. -The rate associated with a given primitive is sourced from the value written -to code:PrimitiveShadingRateKHR by that primitive's +ifdef::VK_EXT_mesh_shader[] +If the last <> is using the code:MeshEXT {ExecutionModel}, the rate +associated with a given primitive is sourced from the value written to the +per-primitive code:PrimitiveShadingRateKHR. +Otherwise the +endif::VK_EXT_mesh_shader[] +ifndef::VK_EXT_mesh_shader[The] +rate associated with a given primitive is sourced from the value written to +code:PrimitiveShadingRateKHR by that primitive's <>. @@ -2212,13 +2220,13 @@ This means that the per-vertex values of indices 1 and 2 for point primitives will be equal to those of index 0, and the per-vertex values of index 2 for line primitives will be equal to those of index 1. -ifndef::VK_NV_mesh_shader[] +ifndef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] When <> and <> -endif::VK_NV_mesh_shader[] -ifdef::VK_NV_mesh_shader[] +endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] +ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] When <>, <>, and <> -endif::VK_NV_mesh_shader[] +endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] are not active, fragment shader inputs decorated with code:PerVertexKHR will take values from one of the vertices of the primitive that produced the fragment, identified by the extra index provided in SPIR-V code accessing @@ -2279,14 +2287,10 @@ endif::VK_KHR_fragment_shader_barycentric[] endif::VK_EXT_provoking_vertex[] When geometry -ifdef::VK_NV_mesh_shader[] -or mesh -endif::VK_NV_mesh_shader[] +ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[or mesh] shading is active, primitives processed by fragment shaders are assembled from the vertices emitted by the geometry -ifdef::VK_NV_mesh_shader[] -or mesh -endif::VK_NV_mesh_shader[] +ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[or mesh] shader. In this case, the vertices used for fragment shader inputs decorated with code:PerVertexKHR are derived by treating the primitives produced by the diff --git a/chapters/queries.adoc b/chapters/queries.adoc index f54aa2dddf..7f6d5ccb8c 100644 --- a/chapters/queries.adoc +++ b/chapters/queries.adoc @@ -36,6 +36,10 @@ ifdef::VK_INTEL_performance_query[] <> are supported if the associated extension is available. endif::VK_INTEL_performance_query[] +ifdef::VK_EXT_mesh_shader[] +<> are supported if the associated +extension is available. +endif::VK_EXT_mesh_shader[] ifdef::VK_KHR_acceleration_structure,VK_NV_ray_tracing[] Several additional queries with specific purposes associated with ray @@ -103,6 +107,19 @@ ename:VK_QUERY_TYPE_PIPELINE_STATISTICS. If the <> feature is not enabled, pname:queryType must: not be ename:VK_QUERY_TYPE_PIPELINE_STATISTICS +ifdef::VK_EXT_mesh_shader[] + * [[VUID-VkQueryPoolCreateInfo-meshShaderQueries-07068]] + If the <> feature is + not enabled, pname:queryType must: not be + ename:VK_QUERY_TYPE_MESH_PRIMITIVES_GENERATED_EXT + * [[VUID-VkQueryPoolCreateInfo-meshShaderQueries-07069]] + If the <> feature is + not enabled, and pname:queryType is + ename:VK_QUERY_TYPE_PIPELINE_STATISTICS, pname:pipelineStatistics must: + not contain + ename:VK_QUERY_PIPELINE_STATISTIC_TASK_SHADER_INVOCATIONS_BIT_EXT or + ename:VK_QUERY_PIPELINE_STATISTIC_MESH_SHADER_INVOCATIONS_BIT_EXT +endif::VK_EXT_mesh_shader[] * [[VUID-VkQueryPoolCreateInfo-queryType-00792]] If pname:queryType is ename:VK_QUERY_TYPE_PIPELINE_STATISTICS, pname:pipelineStatistics must: be a valid combination of @@ -229,6 +246,10 @@ ifdef::VK_KHR_video_encode_queue[] <>. endif::VK_KHR_video_encode_queue[] +ifdef::VK_EXT_mesh_shader[] + * ename:VK_QUERY_TYPE_MESH_PRIMITIVES_GENERATED_EXT specifies a + <>. +endif::VK_EXT_mesh_shader[] -- @@ -517,6 +538,13 @@ include::{chapters}/commonvalidity/query_begin_common.adoc[] pname:queryPool must: have been created with a pname:queryType that differs from that of any queries that are <> within pname:commandBuffer +ifdef::VK_EXT_mesh_shader[] + * [[VUID-vkCmdBeginQuery-queryType-07070]] + If the pname:queryType used to create pname:queryPool was + ename:VK_QUERY_TYPE_MESH_PRIMITIVES_GENERATED_EXT the + sname:VkCommandPool that pname:commandBuffer was allocated from must: + support graphics operations +endif::VK_EXT_mesh_shader[] ifdef::VK_EXT_transform_feedback[] * [[VUID-vkCmdBeginQuery-queryType-02327]] If the pname:queryType used to create pname:queryPool was @@ -648,6 +676,11 @@ endif::VK_EXT_primitives_generated_query[] ename:VK_QUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXT then sname:VkPhysicalDeviceTransformFeedbackPropertiesEXT::pname:transformFeedbackQueries must: be supported +ifdef::VK_EXT_mesh_shader[] + * [[VUID-vkCmdBeginQueryIndexedEXT-queryType-07071]] + The pname:queryType used to create pname:queryPool must: not be + ename:VK_QUERY_TYPE_MESH_PRIMITIVES_GENERATED_EXT +endif::VK_EXT_mesh_shader[] include::{chapters}/commonvalidity/performance_query_begin_common.adoc[] **** @@ -855,6 +888,9 @@ endif::VK_EXT_transform_feedback[] ifdef::VK_EXT_primitives_generated_query[] primitives generated queries, endif::VK_EXT_primitives_generated_query[] +ifdef::VK_EXT_mesh_shader[] + mesh shader queries, +endif::VK_EXT_mesh_shader[] and timestamp queries store results in a tightly packed array of unsigned integers, either 32- or 64-bits as requested by the command, storing the numerical results and, if requested, the availability @@ -908,6 +944,9 @@ ifdef::VK_EXT_primitives_generated_query[] This is identical to the second integer of the transform feedback queries if transform feedback is active. endif::VK_EXT_primitives_generated_query[] +ifdef::VK_EXT_mesh_shader[] + Mesh shader queries write a single integer. +endif::VK_EXT_mesh_shader[] * If more than one query is retrieved and pname:stride is not at least as large as the size of the array of values corresponding to a single query, the values written to memory are undefined:. @@ -935,8 +974,11 @@ include::{generated}/api/protos/vkGetQueryPoolResults.adoc[] Any results written for a query are written according to <>. -Results for any query in pname:queryPool identified by pname:firstQuery and -pname:queryCount that is available are copied to pname:pData. +If no bits are set in pname:flags, and all requested queries are in the +available state, results are written as an array of 32-bit unsigned integer +values. +The behavior when not all queries are available, is described +<>. If ename:VK_QUERY_RESULT_WITH_AVAILABILITY_BIT is set, results for all queries in pname:queryPool identified by pname:firstQuery and @@ -1521,6 +1563,18 @@ include::{generated}/api/enums/VkQueryPipelineStatisticFlagBits.adoc[] invocations or execute additional compute shader invocations for implementation-dependent reasons as long as the results of rendering otherwise remain unchanged. +ifdef::VK_EXT_mesh_shader[] + * ename:VK_QUERY_PIPELINE_STATISTIC_TASK_SHADER_INVOCATIONS_BIT_EXT + specifies that queries managed by the pool will count the number of task + shader invocations. + The counter's value is incremented every time the task shader is + invoked. + * ename:VK_QUERY_PIPELINE_STATISTIC_MESH_SHADER_INVOCATIONS_BIT_EXT + specifies that queries managed by the pool will count the number of mesh + shader invocations. + The counter's value is incremented every time the mesh shader is + invoked. +endif::VK_EXT_mesh_shader[] These values are intended to measure relative statistics on one implementation. @@ -1528,6 +1582,11 @@ Various device architectures will count these values differently. Any or all counters may: be affected by the issues described in <>. +ifdef::VK_EXT_mesh_shader,VK_NV_mesh_shader[] +This counting difference is especially true if the pipeline contains mesh or +task shaders, which may affect several of the counters in unexpected ways. +endif::VK_EXT_mesh_shader,VK_NV_mesh_shader[] + [NOTE] .Note ==== @@ -1895,6 +1954,23 @@ multiple times for purposes of clipping. endif::VK_EXT_primitives_generated_query[] +ifdef::VK_EXT_mesh_shader[] + +[[queries-mesh-shader]] +== Mesh Shader Queries + +When a generated mesh primitives query is active, the +mesh-primitives-generated count is incremented every time a primitive +emitted from the mesh shader stage reaches the fragment shader stage. +When a generated mesh primitives query begins, the mesh-primitives-generated +count starts from zero. + +Mesh and task shader pipeline statistics queries function the same way that +invocation queries work for other shader stages, counting the number of +times the respective shader stage has been run. +When the statistics query begins, the invocation counters start from zero. +endif::VK_EXT_mesh_shader[] + ifdef::VK_INTEL_performance_query[] include::{chapters}/VK_INTEL_performance_query/queries.adoc[] endif::VK_INTEL_performance_query[] diff --git a/chapters/renderpass.adoc b/chapters/renderpass.adoc index 42297b7ccf..7e2b9171cb 100644 --- a/chapters/renderpass.adoc +++ b/chapters/renderpass.adoc @@ -1393,6 +1393,7 @@ disabled and all drawing commands execute normally, without this additional broadcasting. Some implementations may: not support multiview in conjunction with +ifdef::VK_EXT_mesh_shader[<>,] <> or <>. diff --git a/chapters/resources.adoc b/chapters/resources.adoc index f042d2c722..0e28ee7ea2 100644 --- a/chapters/resources.adoc +++ b/chapters/resources.adoc @@ -265,6 +265,10 @@ ifdef::VK_NV_mesh_shader[] flink:vkCmdDrawMeshTasksIndirectNV, flink:vkCmdDrawMeshTasksIndirectCountNV, endif::VK_NV_mesh_shader[] +ifdef::VK_EXT_mesh_shader[] + fname:vkCmdDrawMeshTasksIndirectEXT, + fname:vkCmdDrawMeshTasksIndirectCountEXT, +endif::VK_EXT_mesh_shader[] or flink:vkCmdDispatchIndirect. ifdef::VK_NV_device_generated_commands[] It is also suitable for passing as the pname:buffer member of @@ -4127,16 +4131,11 @@ ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] ename:VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT flag, pname:format must: be compatible with, or must: be an uncompressed format that is size-compatible with, the pname:format used to create pname:image - * [[VUID-VkImageViewCreateInfo-image-01584]] - If pname:image was created with the - ename:VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT flag, the - pname:levelCount and pname:layerCount members of pname:subresourceRange - must: both be `1` - * [[VUID-VkImageViewCreateInfo-image-04739]] + * [[VUID-VkImageViewCreateInfo-image-07072]] If pname:image was created with the ename:VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT flag and - pname:format is a non-compressed format, pname:viewType must: not be - ename:VK_IMAGE_VIEW_TYPE_3D + pname:format is a non-compressed format, the pname:levelCount and + pname:layerCount members of pname:subresourceRange must: both be `1` endif::VK_VERSION_1_1,VK_KHR_maintenance2[] ifdef::VK_VERSION_1_2,VK_KHR_image_format_list[] * [[VUID-VkImageViewCreateInfo-pNext-01585]] @@ -5450,8 +5449,8 @@ ename:VK_ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR. [NOTE] .Note ==== -ename:VK_ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR is intended to be used -by API translation layers. +ename:VK_ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR is intended to be used by +API translation layers. This can be used at acceleration structure creation time in cases where the actual acceleration structure type (top or bottom) is not yet known. The actual acceleration structure type must be specified as @@ -5702,8 +5701,8 @@ endif::VK_NV_ray_tracing[] * ename:VK_ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR is an acceleration structure whose type is determined at build time used for special circumstances. - In these cases, the acceleration structure type is not known at creation time, - but must: be specified at build time as either top or bottom. + In these cases, the acceleration structure type is not known at creation + time, but must: be specified at build time as either top or bottom. -- ifdef::VK_KHR_acceleration_structure[] @@ -6341,6 +6340,8 @@ That is, the difference in returned addresses between the two must: be the same as the difference in offsets provided at acceleration structure creation. +The returned address must: be aligned to 256 bytes. + [NOTE] .Note ==== diff --git a/chapters/shaders.adoc b/chapters/shaders.adoc index b08c7c327d..d307ff7d3b 100644 --- a/chapters/shaders.adoc +++ b/chapters/shaders.adoc @@ -492,8 +492,7 @@ shader stages with similar meaning. The specific behavior of variables decorated as code:BuiltIn is documented in the following sections. - -ifdef::VK_NV_mesh_shader[] +ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] [[shaders-task]] == Task Shaders @@ -508,8 +507,15 @@ Task shaders are invoked via the execution of the The task shader has no fixed-function inputs other than variables identifying the specific workgroup and invocation. -The only fixed output of the task shader is a task count, identifying the -number of mesh shader workgroups to create. +ifdef::VK_NV_mesh_shader[] +In the code:TaskNV {ExecutionModel} the number of mesh shader workgroups to +create is specified via a code:TaskCountNV decorated output variable. +endif::VK_NV_mesh_shader[] +ifdef::VK_EXT_mesh_shader[] +In the code:TaskEXT {ExecutionModel} the number of mesh shader workgroups to +create is specified via the code:OpEmitMeshTasksEXT instruction. +endif::VK_EXT_mesh_shader[] + The task shader can write additional outputs to task memory, which can be read by all of the mesh shader workgroups it created. @@ -529,7 +535,12 @@ decoration. An invocation within a local workgroup can: share data with other members of the local workgroup through shared variables and issue memory and control flow barriers to synchronize with other members of the local workgroup. - +ifdef::VK_EXT_mesh_shader[] +ifdef::VK_VERSION_1_1,VK_KHR_multiview[] +If the subpass includes multiple views in its view mask, a Task shader using +code:TaskEXT {ExecutionModel} may: be invoked separately for each view. +endif::VK_VERSION_1_1,VK_KHR_multiview[] +endif::VK_EXT_mesh_shader[] [[shaders-mesh]] == Mesh Shaders @@ -572,10 +583,15 @@ An invocation within a local workgroup can: share data with other members of the local workgroup through shared variables and issue memory and control flow barriers to synchronize with other members of the local workgroup. -The _global workgroups_ may be generated explcitly via the API, or +The _global workgroups_ may be generated explicitly via the API, or implicitly through the task shader's work creation mechanism. -endif::VK_NV_mesh_shader[] - +endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] +ifdef::VK_EXT_mesh_shader[] +ifdef::VK_VERSION_1_1,VK_KHR_multiview[] +If the subpass includes multiple views in its view mask, a Mesh shader using +code:MeshEXT {ExecutionModel} may: be invoked separately for each view. +endif::VK_VERSION_1_1,VK_KHR_multiview[] +endif::VK_EXT_mesh_shader[] [[shaders-vertex]] == Vertex Shaders @@ -583,15 +599,15 @@ endif::VK_NV_mesh_shader[] Each vertex shader invocation operates on one vertex and its associated <> data, and outputs one vertex and associated data. -ifndef::VK_NV_mesh_shader[] +ifndef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] Graphics pipelines must: include a vertex shader, and the vertex shader stage is always the first shader stage in the graphics pipeline. -endif::VK_NV_mesh_shader[] -ifdef::VK_NV_mesh_shader[] +endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] +ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] Graphics pipelines using primitive shading must: include a vertex shader, and the vertex shader stage is always the first shader stage in the graphics pipeline. -endif::VK_NV_mesh_shader[] +endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] [[shaders-vertex-execution]] @@ -923,6 +939,20 @@ Variables in the code:Input storage class in a fragment shader's interface are interpolated from the values specified by the primitive being rasterized. +[NOTE] +.Note +==== +Interpolation decorations can be present on input and output variables in +pre-rasterization shaders but have no effect on the interpolation performed. +ifdef::VK_EXT_graphics_pipeline_libraries[] +However, when linking graphics pipeline libraries, if the +<> limit is +not supported, interpolation qualifiers do need to match between the +fragment shader input and the last pre-rasterization shader output. +endif::VK_EXT_graphics_pipeline_libraries[] +==== + An undecorated input variable will be interpolated with perspective-correct interpolation according to the primitive type being rasterized. <> and @@ -1166,9 +1196,9 @@ Each invocation in a local workgroup must: be in the same <>. Only -ifdef::VK_NV_mesh_shader[] +ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] task, mesh, and -endif::VK_NV_mesh_shader[] +endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] compute shaders have defined workgroups - other shader types cannot: use workgroup functionality. For shaders that have defined workgroups, this set of invocations forms an diff --git a/chapters/synchronization.adoc b/chapters/synchronization.adoc index b112e758d1..b1c8ae37d5 100755 --- a/chapters/synchronization.adoc +++ b/chapters/synchronization.adoc @@ -345,12 +345,12 @@ ifdef::VK_NV_device_generated_commands[] This stage also includes reading commands written by flink:vkCmdPreprocessGeneratedCommandsNV. endif::VK_NV_device_generated_commands[] -ifdef::VK_NV_mesh_shader[] - * ename:VK_PIPELINE_STAGE_2_TASK_SHADER_BIT_NV specifies the task shader +ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] + * ename:VK_PIPELINE_STAGE_2_TASK_SHADER_BIT_EXT specifies the task shader stage. - * ename:VK_PIPELINE_STAGE_2_MESH_SHADER_BIT_NV specifies the mesh shader + * ename:VK_PIPELINE_STAGE_2_MESH_SHADER_BIT_EXT specifies the mesh shader stage. -endif::VK_NV_mesh_shader[] +endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] * ename:VK_PIPELINE_STAGE_2_INDEX_INPUT_BIT specifies the stage of the pipeline where index buffers are consumed. * ename:VK_PIPELINE_STAGE_2_VERTEX_ATTRIBUTE_INPUT_BIT specifies the stage @@ -375,10 +375,10 @@ endif::VK_NV_mesh_shader[] ** ename:VK_PIPELINE_STAGE_2_TESSELLATION_CONTROL_SHADER_BIT ** ename:VK_PIPELINE_STAGE_2_TESSELLATION_EVALUATION_SHADER_BIT ** ename:VK_PIPELINE_STAGE_2_GEOMETRY_SHADER_BIT -ifdef::VK_NV_mesh_shader[] - ** ename:VK_PIPELINE_STAGE_2_TASK_SHADER_BIT_NV - ** ename:VK_PIPELINE_STAGE_2_MESH_SHADER_BIT_NV -endif::VK_NV_mesh_shader[] +ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] + ** ename:VK_PIPELINE_STAGE_2_TASK_SHADER_BIT_EXT + ** ename:VK_PIPELINE_STAGE_2_MESH_SHADER_BIT_EXT +endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] * ename:VK_PIPELINE_STAGE_2_FRAGMENT_SHADER_BIT specifies the fragment shader stage. * ename:VK_PIPELINE_STAGE_2_EARLY_FRAGMENT_TESTS_BIT specifies the stage @@ -441,10 +441,10 @@ endif::VK_KHR_acceleration_structure,VK_NV_ray_tracing[] * ename:VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT specifies the execution of all graphics pipeline stages, and is equivalent to the logical OR of: ** ename:VK_PIPELINE_STAGE_2_DRAW_INDIRECT_BIT -ifdef::VK_NV_mesh_shader[] - ** ename:VK_PIPELINE_STAGE_2_TASK_SHADER_BIT_NV - ** ename:VK_PIPELINE_STAGE_2_MESH_SHADER_BIT_NV -endif::VK_NV_mesh_shader[] +ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] + ** ename:VK_PIPELINE_STAGE_2_TASK_SHADER_BIT_EXT + ** ename:VK_PIPELINE_STAGE_2_MESH_SHADER_BIT_EXT +endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] ** ename:VK_PIPELINE_STAGE_2_VERTEX_INPUT_BIT ** ename:VK_PIPELINE_STAGE_2_VERTEX_SHADER_BIT ** ename:VK_PIPELINE_STAGE_2_TESSELLATION_CONTROL_SHADER_BIT @@ -588,12 +588,12 @@ ifdef::VK_NV_device_generated_commands[] This stage also includes reading commands written by flink:vkCmdExecuteGeneratedCommandsNV. endif::VK_NV_device_generated_commands[] -ifdef::VK_NV_mesh_shader[] - * ename:VK_PIPELINE_STAGE_TASK_SHADER_BIT_NV specifies the task shader +ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] + * ename:VK_PIPELINE_STAGE_TASK_SHADER_BIT_EXT specifies the task shader stage. - * ename:VK_PIPELINE_STAGE_MESH_SHADER_BIT_NV specifies the mesh shader + * ename:VK_PIPELINE_STAGE_MESH_SHADER_BIT_EXT specifies the mesh shader stage. -endif::VK_NV_mesh_shader[] +endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] * ename:VK_PIPELINE_STAGE_VERTEX_INPUT_BIT specifies the stage of the pipeline where vertex and index buffers are consumed. * ename:VK_PIPELINE_STAGE_VERTEX_SHADER_BIT specifies the vertex shader @@ -672,10 +672,10 @@ endif::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] * ename:VK_PIPELINE_STAGE_ALL_GRAPHICS_BIT specifies the execution of all graphics pipeline stages, and is equivalent to the logical OR of: ** ename:VK_PIPELINE_STAGE_DRAW_INDIRECT_BIT -ifdef::VK_NV_mesh_shader[] - ** ename:VK_PIPELINE_STAGE_TASK_SHADER_BIT_NV - ** ename:VK_PIPELINE_STAGE_MESH_SHADER_BIT_NV -endif::VK_NV_mesh_shader[] +ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] + ** ename:VK_PIPELINE_STAGE_TASK_SHADER_BIT_EXT + ** ename:VK_PIPELINE_STAGE_MESH_SHADER_BIT_EXT +endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] ** ename:VK_PIPELINE_STAGE_VERTEX_INPUT_BIT ** ename:VK_PIPELINE_STAGE_VERTEX_SHADER_BIT ** ename:VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT @@ -828,10 +828,10 @@ endif::VK_NV_device_generated_commands[] ifdef::VK_KHR_fragment_shading_rate,VK_NV_shading_rate_image[] |ename:VK_PIPELINE_STAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR | ename:VK_QUEUE_GRAPHICS_BIT endif::VK_KHR_fragment_shading_rate,VK_NV_shading_rate_image[] -ifdef::VK_NV_mesh_shader[] -|ename:VK_PIPELINE_STAGE_TASK_SHADER_BIT_NV | ename:VK_QUEUE_GRAPHICS_BIT -|ename:VK_PIPELINE_STAGE_MESH_SHADER_BIT_NV | ename:VK_QUEUE_GRAPHICS_BIT -endif::VK_NV_mesh_shader[] +ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] +|ename:VK_PIPELINE_STAGE_TASK_SHADER_BIT_EXT | ename:VK_QUEUE_GRAPHICS_BIT +|ename:VK_PIPELINE_STAGE_MESH_SHADER_BIT_EXT | ename:VK_QUEUE_GRAPHICS_BIT +endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] ifdef::VK_NV_ray_tracing,VK_KHR_acceleration_structure[] |ename:VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR | ename:VK_QUEUE_COMPUTE_BIT endif::VK_NV_ray_tracing,VK_KHR_acceleration_structure[] @@ -889,9 +889,9 @@ Stages executed by graphics pipelines can: only be specified in commands recorded for queues supporting ename:VK_QUEUE_GRAPHICS_BIT. The graphics -ifdef::VK_NV_mesh_shader[] +ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] primitive -endif::VK_NV_mesh_shader[] +endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] pipeline executes the following stages, with the logical ordering of the stages matching the order specified here: @@ -918,13 +918,13 @@ endif::VK_KHR_fragment_shading_rate,VK_NV_shading_rate_image[] * ename:VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT * ename:VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT -ifdef::VK_NV_mesh_shader[] +ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] The graphics mesh pipeline executes the following stages, with the logical ordering of the stages matching the order specified here: * ename:VK_PIPELINE_STAGE_DRAW_INDIRECT_BIT - * ename:VK_PIPELINE_STAGE_TASK_SHADER_BIT_NV - * ename:VK_PIPELINE_STAGE_MESH_SHADER_BIT_NV + * ename:VK_PIPELINE_STAGE_TASK_SHADER_BIT_EXT + * ename:VK_PIPELINE_STAGE_MESH_SHADER_BIT_EXT ifdef::VK_KHR_fragment_shading_rate,VK_NV_shading_rate_image[] * ename:VK_PIPELINE_STAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR endif::VK_KHR_fragment_shading_rate,VK_NV_shading_rate_image[] @@ -932,7 +932,7 @@ endif::VK_KHR_fragment_shading_rate,VK_NV_shading_rate_image[] * ename:VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT * ename:VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT * ename:VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT -endif::VK_NV_mesh_shader[] +endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] For the compute pipeline, the following stages occur in this order: @@ -1565,9 +1565,9 @@ endif::VK_KHR_acceleration_structure[] |ename:VK_ACCESS_VERTEX_ATTRIBUTE_READ_BIT | ename:VK_PIPELINE_STAGE_VERTEX_INPUT_BIT |ename:VK_ACCESS_UNIFORM_READ_BIT | -ifdef::VK_NV_mesh_shader[] - ename:VK_PIPELINE_STAGE_TASK_SHADER_BIT_NV, ename:VK_PIPELINE_STAGE_MESH_SHADER_BIT_NV, -endif::VK_NV_mesh_shader[] +ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] + ename:VK_PIPELINE_STAGE_TASK_SHADER_BIT_EXT, ename:VK_PIPELINE_STAGE_MESH_SHADER_BIT_EXT, +endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] ifdef::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] ename:VK_PIPELINE_STAGE_RAY_TRACING_SHADER_BIT_KHR, endif::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] @@ -1577,18 +1577,18 @@ endif::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] ifdef::VK_KHR_acceleration_structure[] ename:VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR, endif::VK_KHR_acceleration_structure[] -ifdef::VK_NV_mesh_shader[] - ename:VK_PIPELINE_STAGE_TASK_SHADER_BIT_NV, ename:VK_PIPELINE_STAGE_MESH_SHADER_BIT_NV, -endif::VK_NV_mesh_shader[] +ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] + ename:VK_PIPELINE_STAGE_TASK_SHADER_BIT_EXT, ename:VK_PIPELINE_STAGE_MESH_SHADER_BIT_EXT, +endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] ifdef::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] ename:VK_PIPELINE_STAGE_RAY_TRACING_SHADER_BIT_KHR, endif::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] ename:VK_PIPELINE_STAGE_VERTEX_SHADER_BIT, ename:VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT, ename:VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT, ename:VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT, ename:VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT, or ename:VK_PIPELINE_STAGE_COMPUTE_SHADER_BIT |ename:VK_ACCESS_SHADER_WRITE_BIT | -ifdef::VK_NV_mesh_shader[] - ename:VK_PIPELINE_STAGE_TASK_SHADER_BIT_NV, ename:VK_PIPELINE_STAGE_MESH_SHADER_BIT_NV, -endif::VK_NV_mesh_shader[] +ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] + ename:VK_PIPELINE_STAGE_TASK_SHADER_BIT_EXT, ename:VK_PIPELINE_STAGE_MESH_SHADER_BIT_EXT, +endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] ifdef::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] ename:VK_PIPELINE_STAGE_RAY_TRACING_SHADER_BIT_KHR, endif::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] @@ -1635,9 +1635,9 @@ endif::VK_EXT_transform_feedback[] ifdef::VK_NV_ray_tracing,VK_KHR_acceleration_structure[] |ename:VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_KHR | ifdef::VK_KHR_ray_query[] -ifdef::VK_NV_mesh_shader[] - ename:VK_PIPELINE_STAGE_TASK_SHADER_BIT_NV, ename:VK_PIPELINE_STAGE_MESH_SHADER_BIT_NV, -endif::VK_NV_mesh_shader[] +ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] + ename:VK_PIPELINE_STAGE_TASK_SHADER_BIT_EXT, ename:VK_PIPELINE_STAGE_MESH_SHADER_BIT_EXT, +endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] ename:VK_PIPELINE_STAGE_VERTEX_SHADER_BIT, ename:VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT, ename:VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT, ename:VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT, ename:VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT, ename:VK_PIPELINE_STAGE_COMPUTE_SHADER_BIT, endif::VK_KHR_ray_query[] ifdef::VK_KHR_ray_tracing_pipeline[] @@ -3128,7 +3128,7 @@ will have a default elink:VkSemaphoreType of ename:VK_SEMAPHORE_TYPE_BINARY. include::{generated}/validity/structs/VkSemaphoreTypeCreateInfo.adoc[] -- -[open,refpage='VkSemaphoreType',desc='Sepcifies the type of a semaphore object',type='enums',alias='VkSemaphoreTypeKHR'] +[open,refpage='VkSemaphoreType',desc='Specifies the type of a semaphore object',type='enums',alias='VkSemaphoreTypeKHR'] -- Possible values of slink:VkSemaphoreTypeCreateInfo::pname:semaphoreType, specifying the type of a semaphore, are: diff --git a/chapters/vertexpostproc.adoc b/chapters/vertexpostproc.adoc index d250f5bb44..ad7782bbc9 100644 --- a/chapters/vertexpostproc.adoc +++ b/chapters/vertexpostproc.adoc @@ -556,12 +556,32 @@ Flat shading is applied to those vertex attributes that <> fragment input attributes which are decorated as code:Flat. -If neither <> nor <> -is active, the provoking vertex is determined by the -<> defined by +If neither +ifdef::VK_EXT_mesh_shader,VK_NV_mesh_shader[] +<>, +endif::VK_EXT_mesh_shader,VK_NV_mesh_shader[] +<> nor <> is active, +the provoking vertex is determined by the <> defined by slink:VkPipelineInputAssemblyStateCreateInfo:pname:topology used to execute the <>. +ifdef::VK_NV_mesh_shader[] +If a shader using code:MeshNV {ExecutionModel} is active, the provoking +vertex is determined by the <> defined by the <>, +<>, or <> execution mode. +endif::VK_NV_mesh_shader[] + +ifdef::VK_EXT_mesh_shader[] +If a shader using code:MeshEXT {ExecutionModel} is active, the provoking +vertex is determined by the <> defined by the <>, +<>, or <> execution mode. +endif::VK_EXT_mesh_shader[] + If <> is active, the provoking vertex is determined by the <> defined by the <>, diff --git a/chapters/video_decode_h264_extensions.adoc b/chapters/video_decode_h264_extensions.adoc index a1a18efb95..8e2a1cdb24 100644 --- a/chapters/video_decode_h264_extensions.adoc +++ b/chapters/video_decode_h264_extensions.adoc @@ -5,13 +5,21 @@ [[decode-h264]] == Video Decode of AVC (ITU-T H.264) -This extension adds H.264 codec specific structures needed for decode -session to execute decode jobs which include H.264 sequence header, picture -parameter header and quantization matrix etc. +The `apiext:VK_EXT_video_decode_h264` extension adds H.264 codec specific +structures needed for decode session to execute decode jobs which include +H.264 sequence header, picture parameter header and quantization matrix etc. Unless otherwise noted, all references to the H.264 specification are to the 2010 edition published by the ITU-T, dated March 2010. This specification is available at https://www.itu.int/rec/T-REC-H.264. +[NOTE] +.Note +==== +Refer to the <> for information on how the Khronos +Intellectual Property Rights Policy relates to normative references to +external materials not created by Khronos. +==== + === H.264 decode profile diff --git a/chapters/video_decode_h265_extensions.adoc b/chapters/video_decode_h265_extensions.adoc index bc8c3621d2..d5a2d20643 100644 --- a/chapters/video_decode_h265_extensions.adoc +++ b/chapters/video_decode_h265_extensions.adoc @@ -5,13 +5,21 @@ [[decode-h265]] == Video Decode of HEVC (ITU-T H.265) -This extension adds H.265 codec specific structures needed for decode -session to execute decode jobs which include H.265 sequence header, picture -parameter header and quantization matrix etc. +The `apiext:VK_EXT_video_decode_h265` extension adds H.265 codec specific +structures needed for decode session to execute decode jobs which include +H.265 sequence header, picture parameter header and quantization matrix etc. Unless otherwise noted, all references to the H.265 specification are to the 2013 edition published by the ITU-T, dated April 2013. This specification is available at https://www.itu.int/rec/T-REC-H.265. +[NOTE] +.Note +==== +Refer to the <> for information on how the Khronos +Intellectual Property Rights Policy relates to normative references to +external materials not created by Khronos. +==== + === H.265 decode profile diff --git a/chapters/video_encode_h264_extensions.adoc b/chapters/video_encode_h264_extensions.adoc index 099ab7c5e1..a3e8c3d0f4 100644 --- a/chapters/video_encode_h264_extensions.adoc +++ b/chapters/video_encode_h264_extensions.adoc @@ -5,12 +5,20 @@ [[encode-h264]] == Encode H.264 -This extension adds H.264 codec specific structures/types needed to support -H.264 encoding. +The `apiext:VK_EXT_video_encode_h264` extension adds H.264 codec specific +structures/types needed to support H.264 encoding. Unless otherwise noted, all references to the H.264 specification are to the 2010 edition published by the ITU-T, dated March 2010. This specification is available at https://www.itu.int/rec/T-REC-H.264. +[NOTE] +.Note +==== +Refer to the <> for information on how the Khronos +Intellectual Property Rights Policy relates to normative references to +external materials not created by Khronos. +==== + === H.264 encode profile diff --git a/chapters/video_encode_h265_extensions.adoc b/chapters/video_encode_h265_extensions.adoc index 62418daab8..e61bbbe920 100644 --- a/chapters/video_encode_h265_extensions.adoc +++ b/chapters/video_encode_h265_extensions.adoc @@ -5,12 +5,20 @@ [[encode-h265]] == Encode H.265 -This extension adds H.265 codec-specific structures/types needed to support -H.265 video encoding. +The `apiext:VK_EXT_video_encode_h265` extension adds H.265 codec-specific +structures/types needed to support H.265 video encoding. Unless otherwise noted, all references to the H.265 specification are to the 2013 edition published by the ITU-T, dated April 2013. This specification is available at https://www.itu.int/rec/T-REC-H.265. +[NOTE] +.Note +==== +Refer to the <> for information on how the Khronos +Intellectual Property Rights Policy relates to normative references to +external materials not created by Khronos. +==== + === H.265 encode profile diff --git a/chapters/video_extensions.adoc b/chapters/video_extensions.adoc index c91cd0bb1c..6a1e921d15 100644 --- a/chapters/video_extensions.adoc +++ b/chapters/video_extensions.adoc @@ -865,9 +865,9 @@ extension. ifdef::VK_KHR_video_decode_queue[] [open,refpage='VkVideoDecodeUsageInfoKHR',desc='Structure specifying video decode usage information',type='structs'] -- -Additional information about the video decode use case can: be provided -by adding a sname:VkVideoDecodeUsageInfoKHR structure to the pname:pNext -chain of slink:VkVideoProfileInfoKHR. +Additional information about the video decode use case can: be provided by +adding a sname:VkVideoDecodeUsageInfoKHR structure to the pname:pNext chain +of slink:VkVideoProfileInfoKHR. The sname:VkVideoDecodeUsageInfoKHR structure is defined as: @@ -876,8 +876,9 @@ include::{generated}/api/structs/VkVideoDecodeUsageInfoKHR.adoc[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. - * pname:videoUsageHints is a bitmask of elink:VkVideoDecodeUsageFlagBitsKHR - specifying hints about the intended use of the video decode profile. + * pname:videoUsageHints is a bitmask of + elink:VkVideoDecodeUsageFlagBitsKHR specifying hints about the intended + use of the video decode profile. include::{generated}/validity/structs/VkVideoDecodeUsageInfoKHR.adoc[] -- @@ -893,19 +894,20 @@ include::{generated}/api/enums/VkVideoDecodeUsageFlagBitsKHR.adoc[] * ename:VK_VIDEO_DECODE_USAGE_TRANSCODING_BIT_KHR specifies that video decoding is intended to be used in conjunction with video encoding to transcode a video bitstream with the same and/or different codecs. - * ename:VK_VIDEO_DECODE_USAGE_OFFLINE_BIT_KHR specifies that video decoding - is intended to be used to consume a local video bitstream. + * ename:VK_VIDEO_DECODE_USAGE_OFFLINE_BIT_KHR specifies that video + decoding is intended to be used to consume a local video bitstream. * ename:VK_VIDEO_DECODE_USAGE_STREAMING_BIT_KHR specifies that video - decoding is intended to be used to consume a video bitstream received - as a continuous flow over network. + decoding is intended to be used to consume a video bitstream received as + a continuous flow over network. [NOTE] .Note ==== -There are no restrictions on the combination of bits that can: be specified by -the application. However, applications should: use reasonable combinations in -order for the implementation to be able to select the most appropriate mode of -operation for the particular use case. +There are no restrictions on the combination of bits that can: be specified +by the application. +However, applications should: use reasonable combinations in order for the +implementation to be able to select the most appropriate mode of operation +for the particular use case. ==== -- @@ -914,17 +916,17 @@ operation for the particular use case. -- include::{generated}/api/flags/VkVideoDecodeUsageFlagsKHR.adoc[] -tlink:VkVideoDecodeUsageFlagsKHR is a bitmask type for setting a mask of zero -or more elink:VkVideoDecodeUsageFlagBitsKHR. +tlink:VkVideoDecodeUsageFlagsKHR is a bitmask type for setting a mask of +zero or more elink:VkVideoDecodeUsageFlagBitsKHR. -- endif::VK_KHR_video_decode_queue[] ifdef::VK_KHR_video_encode_queue[] [open,refpage='VkVideoEncodeUsageInfoKHR',desc='Structure specifying video encode usage information',type='structs'] -- -Additional information about the video encode use case can: be provided -by adding a sname:VkVideoEncodeUsageInfoKHR structure to the pname:pNext -chain of slink:VkVideoProfileInfoKHR. +Additional information about the video encode use case can: be provided by +adding a sname:VkVideoEncodeUsageInfoKHR structure to the pname:pNext chain +of slink:VkVideoProfileInfoKHR. The sname:VkVideoEncodeUsageInfoKHR structure is defined as: @@ -933,8 +935,9 @@ include::{generated}/api/structs/VkVideoEncodeUsageInfoKHR.adoc[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. - * pname:videoUsageHints is a bitmask of elink:VkVideoEncodeUsageFlagBitsKHR - specifying hints about the intended use of the video encode profile. + * pname:videoUsageHints is a bitmask of + elink:VkVideoEncodeUsageFlagBitsKHR specifying hints about the intended + use of the video encode profile. * pname:videoContentHints is a bitmask of elink:VkVideoEncodeContentFlagBitsKHR specifying hints about the content to be encoded using the video encode profile. @@ -967,10 +970,11 @@ include::{generated}/api/enums/VkVideoEncodeUsageFlagBitsKHR.adoc[] [NOTE] .Note ==== -There are no restrictions on the combination of bits that can: be specified by -the application. However, applications should: use reasonable combinations in -order for the implementation to be able to select the most appropriate mode of -operation for the particular use case. +There are no restrictions on the combination of bits that can: be specified +by the application. +However, applications should: use reasonable combinations in order for the +implementation to be able to select the most appropriate mode of operation +for the particular use case. ==== -- @@ -979,8 +983,8 @@ operation for the particular use case. -- include::{generated}/api/flags/VkVideoEncodeUsageFlagsKHR.adoc[] -tlink:VkVideoEncodeUsageFlagsKHR is a bitmask type for setting a mask of zero -or more elink:VkVideoEncodeUsageFlagBitsKHR. +tlink:VkVideoEncodeUsageFlagsKHR is a bitmask type for setting a mask of +zero or more elink:VkVideoEncodeUsageFlagBitsKHR. -- [open,refpage='VkVideoEncodeContentFlagBitsKHR',desc='Video encode content flags',type='enums'] @@ -991,8 +995,8 @@ encoded video content: include::{generated}/api/enums/VkVideoEncodeContentFlagBitsKHR.adoc[] - * ename:VK_VIDEO_ENCODE_CONTENT_CAMERA_BIT_KHR specifies that video encoding - is intended to be used to encode camera content. + * ename:VK_VIDEO_ENCODE_CONTENT_CAMERA_BIT_KHR specifies that video + encoding is intended to be used to encode camera content. * ename:VK_VIDEO_ENCODE_CONTENT_DESKTOP_BIT_KHR specifies that video encoding is intended to be used to encode desktop content. * ename:VK_VIDEO_ENCODE_CONTENT_RENDERED_BIT_KHR specified that video @@ -1001,10 +1005,11 @@ include::{generated}/api/enums/VkVideoEncodeContentFlagBitsKHR.adoc[] [NOTE] .Note ==== -There are no restrictions on the combination of bits that can: be specified by -the application. However, applications should: use reasonable combinations in -order for the implementation to be able to select the most appropriate mode of -operation for the particular content type. +There are no restrictions on the combination of bits that can: be specified +by the application. +However, applications should: use reasonable combinations in order for the +implementation to be able to select the most appropriate mode of operation +for the particular content type. ==== -- @@ -1013,8 +1018,8 @@ operation for the particular content type. -- include::{generated}/api/flags/VkVideoEncodeContentFlagsKHR.adoc[] -tlink:VkVideoEncodeContentFlagsKHR is a bitmask type for setting a mask of zero -or more elink:VkVideoEncodeContentFlagBitsKHR. +tlink:VkVideoEncodeContentFlagsKHR is a bitmask type for setting a mask of +zero or more elink:VkVideoEncodeContentFlagBitsKHR. -- [open,refpage='VkVideoEncodeTuningModeKHR',desc='Video encode tuning mode',type='enums'] @@ -1023,23 +1028,26 @@ Possible video encode tuning mode values are as follows: include::{generated}/api/enums/VkVideoEncodeTuningModeKHR.adoc[] - * ename:VK_VIDEO_ENCODE_TUNING_MODE_DEFAULT_KHR specifies the default tuning - mode. + * ename:VK_VIDEO_ENCODE_TUNING_MODE_DEFAULT_KHR specifies the default + tuning mode. * ename:VK_VIDEO_ENCODE_TUNING_MODE_HIGH_QUALITY_KHR specifies that video - encoding is tuned for high quality. When using this tuning mode, the - implementation may: compromise the latency of video encoding operations - to improve quality. + encoding is tuned for high quality. + When using this tuning mode, the implementation may: compromise the + latency of video encoding operations to improve quality. * ename:VK_VIDEO_ENCODE_TUNING_MODE_LOW_LATENCY_KHR specifies that video - encoding is tuned for low latency. When using this tuning mode, the - implementation may: compromise quality to increase the performance and - lower the latency of video encode operations. + encoding is tuned for low latency. + When using this tuning mode, the implementation may: compromise quality + to increase the performance and lower the latency of video encode + operations. * ename:VK_VIDEO_ENCODE_TUNING_MODE_ULTRA_LOW_LATENCY_KHR specifies that - video encoding is tuned for ultra-low latency. When using this tuning - mode, the implementation may: compromise quality to maximimize the - performance and minimize the latency of video encoding operations. + video encoding is tuned for ultra-low latency. + When using this tuning mode, the implementation may: compromise quality + to maximimize the performance and minimize the latency of video encoding + operations. * ename:VK_VIDEO_ENCODE_TUNING_MODE_LOSSLESS_KHR specifies that video - encoding is tuned for lossless encoding. When using this tuning mode, - video encode operations produce lossless output. + encoding is tuned for lossless encoding. + When using this tuning mode, video encode operations produce lossless + output. -- endif::VK_KHR_video_encode_queue[] diff --git a/config/CI/txt-files-allowed b/config/CI/txt-files-allowed new file mode 100644 index 0000000000..e45884289c --- /dev/null +++ b/config/CI/txt-files-allowed @@ -0,0 +1,3 @@ +^\./LICENSES/ +^\./node_modules/ +^\./git/ diff --git a/copyright-spec.adoc b/copyright-spec.adoc index 2ec6a39a7f..17424881d0 100644 --- a/copyright-spec.adoc +++ b/copyright-spec.adoc @@ -5,64 +5,82 @@ proprietary to Khronos. Except as described by these terms, it or any components may not be reproduced, republished, distributed, transmitted, displayed, broadcast or otherwise exploited in any manner without the express prior written permission of Khronos. + Khronos grants a conditional copyright license to use and reproduce the unmodified Specification for any purpose, without fee or royalty, EXCEPT no licenses to any patent, trademark or other intellectual property rights are -granted under these terms. +granted under these terms. Parties desiring to implement the Specification +and make use of Khronos trademarks in relation to that implementation, and +receive reciprocal patent license protection under the Khronos IP Policy +must become Adopters and confirm the implementation as conformant under the +process defined by Khronos for this Specification; see +https://www.khronos.org/adopters. Khronos makes no, and expressly disclaims any, representations or warranties, express or implied, regarding this Specification, including, without limitation: merchantability, fitness for a particular purpose, non-infringement of any intellectual property, correctness, accuracy, -completeness, timeliness, and reliability. -Under no circumstances will Khronos, or any of its Promoters, Contributors -or Members, or their respective partners, officers, directors, employees, -agents or representatives be liable for any damages, whether direct, -indirect, special or consequential damages for lost revenues, lost profits, -or otherwise, arising from or in connection with these materials. +completeness, timeliness, and reliability. Under no circumstances will +Khronos, or any of its Promoters, Contributors or Members, or their +respective partners, officers, directors, employees, agents or +representatives be liable for any damages, whether direct, indirect, special +or consequential damages for lost revenues, lost profits, or otherwise, +arising from or in connection with these materials. This Specification has been created under the Khronos Intellectual Property Rights Policy, which is Attachment A of the Khronos Group Membership -Agreement available at https://www.khronos.org/files/member_agreement.pdf, and which -defines the terms 'Scope', 'Compliant Portion', and 'Necessary Patent Claims'. -Parties desiring to implement the Specification and make use of Khronos trademarks -in relation to that implementation, and receive reciprocal patent license protection -under the Khronos Intellectual Property Rights Policy must become Adopters and -confirm the implementation as conformant under the process defined by Khronos for -this Specification; see https://www.khronos.org/adopters. +Agreement available at https://www.khronos.org/files/member_agreement.pdf. + +// "Successor Specification" section + +This Specification contains substantially unmodified functionality from, and +is a successor to, Khronos specifications including OpenGL, OpenGL ES and +OpenCL. + +// End "Successor Specification" section + +// "Normative Wording" section -This Specification contains substantially unmodified functionality from, and is a -successor to, Khronos specifications including OpenGL, OpenGL ES and OpenCL. +The Khronos Intellectual Property Rights defines the terms 'Scope', +'Compliant Portion', and 'Necessary Patent Claims'. Some parts of this Specification are purely informative and so are EXCLUDED from the Scope of this Specification. The <> section of the <> defines how these parts of the Specification are identified. Where this Specification uses <>, defined in the <> or otherwise, that refer to -enabling technologies that are not expressly set forth in this -Specification, those enabling technologies are EXCLUDED from the Scope of -this Specification. -For clarity, enabling technologies not disclosed with particularity in this -Specification (e.g. semiconductor manufacturing technology, hardware -architecture, processor architecture or microarchitecture, memory -architecture, compiler technology, object oriented technology, basic -operating system technology, compression technology, algorithms, and so on) -are NOT to be considered expressly set forth; only those application program -interfaces and data structures disclosed with particularity are included in -the Scope of this Specification. - -For purposes of the Khronos Intellectual Property Rights Policy as it relates -to the definition of Necessary Patent Claims, all recommended or optional -features, behaviors and functionality set forth in this Specification, if -implemented, are considered to be included as Compliant Portions. - -Where this Specification includes <>, only the specifically -identified sections of those external documents are INCLUDED in the Scope of -this Specification. If not created by Khronos, those external documents may -contain contributions from non-members of Khronos not covered by the Khronos -Intellectual Property Rights Policy. +terminology>>, defined in the <> or otherwise, that +refer to enabling technologies that are not expressly set +forth in this Specification, those enabling technologies are EXCLUDED from +the Scope of this Specification. For clarity, enabling technologies not +disclosed with particularity in this Specification (e.g. semiconductor +manufacturing technology, hardware architecture, processor architecture or +microarchitecture, memory architecture, compiler technology, object oriented +technology, basic operating system technology, compression technology, +algorithms, and so on) are NOT to be considered expressly set forth; only +those application program interfaces and data structures disclosed with +particularity are included in the Scope of this Specification. + +For purposes of the Khronos Intellectual Property Rights Policy as it +relates to the definition of Necessary Patent Claims, all recommended or +optional features, behaviors and functionality set forth in this +Specification, if implemented, are considered to be included as Compliant +Portions. + +// End "Normative Wording" section + +// "External References" section + +Where this Specification identifies specific sections of external +references, only those specifically identified sections define +<> +functionality. The Khronos Intellectual Property Rights Policy excludes +external references to materials and associated enabling technology not +created by Khronos from the Scope of this specification, and any licenses +that may be required to implement such referenced materials and associated +technologies must be obtained separately and may involve royalty payments. + +// End "External References" section ifndef::ratified_core_spec[] This document contains extensions which are not ratified by Khronos, and as @@ -75,9 +93,9 @@ https://registry.khronos.org/vulkan/specs/1.2-khr-extensions/html/vkspec.html (core with KHR extensions). endif::ratified_core_spec[] -Vulkan and Khronos are registered trademarks of The Khronos Group Inc. -ASTC is a trademark of ARM Holdings PLC; OpenCL is a trademark of Apple -Inc.; and OpenGL and OpenGL ES are registered trademarks of Hewlett Packard -Enterprise, all used under license by Khronos. All other product names, +Khronos and Vulkan are registered trademarks of The Khronos Group Inc. +OpenCL is a trademark of Apple Inc.; and OpenGL and OpenGL ES are registered +trademarks of Hewlett Packard Enterprise, all used under license by Khronos. +ASTC is a trademark of ARM Holdings PLC. All other product names, trademarks, and/or company names are used solely for identification and belong to their respective owners. diff --git a/makeSpec b/makeSpec index e790e0615a..bc3ef4589f 100755 --- a/makeSpec +++ b/makeSpec @@ -124,14 +124,23 @@ if __name__ == '__main__': args = [ 'make', 'GENERATED=' + results.genpath ] if results.clean: - execute(args + ['clean'], results) + # If OUTDIR is set on the command line, pass it to the 'clean' + # target so it is cleaned as well. + cleanopts = ['clean'] + for opt in options: + if opt[:7] == 'OUTDIR=': + cleanopts.append(opt) + try: + execute(args + cleanopts, results) + except: + sys.exit(1) args.append(versions) # The actual target if len(exts) > 0: - args.append('EXTENSIONS={}'.format(' '.join(sorted(exts)))) - args.append('APITITLE={}'.format(title)) + args.append(f'EXTENSIONS={" ".join(sorted(exts))}') + args.append(f'APITITLE={title}') args += options try: diff --git a/proposals/Roadmap.adoc b/proposals/Roadmap.adoc index 20ac7568dc..5f1e2a87f4 100644 --- a/proposals/Roadmap.adoc +++ b/proposals/Roadmap.adoc @@ -4,7 +4,7 @@ # Vulkan Roadmap :toc: left -:refpage: https://registry.khronos.org/vulkan/specs/1.2-extensions/man/html/ +:refpage: https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/ :sectnums: This document proposes the development of a shared public roadmap for features across mid-to-high-end devices in smartphone, tablet, laptop, console, and desktop markets. diff --git a/proposals/VK_AMD_shader_early_and_late_fragment_tests.adoc b/proposals/VK_AMD_shader_early_and_late_fragment_tests.adoc index 44e2447743..94e7f56900 100644 --- a/proposals/VK_AMD_shader_early_and_late_fragment_tests.adoc +++ b/proposals/VK_AMD_shader_early_and_late_fragment_tests.adoc @@ -4,7 +4,7 @@ # VK_AMD_shader_early_and_late_fragment_tests :toc: left -:refpage: https://registry.khronos.org/vulkan/specs/1.2-extensions/man/html/ +:refpage: https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/ :sectnums: This document describes a proposal for a new SPIR-V execution mode that allows fragment shaders to be discarded by early fragment operations, even if they contain writes to storage resources or other side effects. diff --git a/proposals/VK_EXT_attachment_feedback_loop_layout.adoc b/proposals/VK_EXT_attachment_feedback_loop_layout.adoc index 044a7bec75..79ecae8425 100644 --- a/proposals/VK_EXT_attachment_feedback_loop_layout.adoc +++ b/proposals/VK_EXT_attachment_feedback_loop_layout.adoc @@ -4,7 +4,7 @@ = VK_EXT_attachment_feedback_loop_layout :toc: left -:refpage: https://registry.khronos.org/vulkan/specs/1.2-extensions/man/html/ +:refpage: https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/ :sectnums: This document details API design ideas for the `VK_EXT_attachment_feedback_loop_layout` extension, diff --git a/proposals/VK_EXT_graphics_pipeline_library.adoc b/proposals/VK_EXT_graphics_pipeline_library.adoc index 49a71b315f..890833307a 100644 --- a/proposals/VK_EXT_graphics_pipeline_library.adoc +++ b/proposals/VK_EXT_graphics_pipeline_library.adoc @@ -4,7 +4,7 @@ # VK_EXT_graphics_pipeline_library :toc: left -:refpage: https://registry.khronos.org/vulkan/specs/1.2-extensions/man/html/ +:refpage: https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/ :sectnums: This document outlines a proposal to allow partial compilation of portions diff --git a/proposals/VK_EXT_image_2d_array_of_3d.adoc b/proposals/VK_EXT_image_2d_array_of_3d.adoc index 8713bc66f4..612bc9af4d 100644 --- a/proposals/VK_EXT_image_2d_array_of_3d.adoc +++ b/proposals/VK_EXT_image_2d_array_of_3d.adoc @@ -4,7 +4,7 @@ # VK_EXT_image_2d_array_of_3d :toc: left -:refpage: https://registry.khronos.org/vulkan/specs/1.2-extensions/man/html/ +:refpage: https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/ :sectnums: This document proposes adding support for creating 2D views of 3D images. diff --git a/proposals/VK_EXT_image_compression_control.adoc b/proposals/VK_EXT_image_compression_control.adoc index 20d9587cf5..0d3777eef2 100644 --- a/proposals/VK_EXT_image_compression_control.adoc +++ b/proposals/VK_EXT_image_compression_control.adoc @@ -2,9 +2,9 @@ // // SPDX-License-Identifier: CC-BY-4.0 -= Proposal Template += VK_EXT_image_compression_control :toc: left -:refpage: https://registry.khronos.org/vulkan/specs/1.2-extensions/man/html/ +:refpage: https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/ :sectnums: This document proposes adding support for fixed-rate, or 'lossy', image compression. diff --git a/proposals/VK_EXT_mesh_shader.adoc b/proposals/VK_EXT_mesh_shader.adoc new file mode 100644 index 0000000000..6712d6a277 --- /dev/null +++ b/proposals/VK_EXT_mesh_shader.adoc @@ -0,0 +1,560 @@ +// Copyright 2021-2022 The Khronos Group Inc. +// +// SPDX-License-Identifier: CC-BY-4.0 + += VK_EXT_mesh_shader +:toc: left +:refpage: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/ +:spec: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html +:sectnums: + +This extension provides a new mechanism allowing applications to generate collections of geometric primitives via programmable mesh shading. + + +== Problem Statement + +The rasterization pipeline for Vulkan is fairly fixed - a fixed input stage assembles vertex data for the vertex shader, data optionally passes through tessellation and geometry stages, then fixed vertex processing passes the resulting primitives to the rasterizer. +As rendering engines get increasingly complex, the fixed nature of this pipeline has become a bottleneck; many developers are augmenting their rasterization pipelines with compute shaders to make them more flexible. +Using compute shaders comes at a cost though - data has to be piped via global memory, and once there it still has to be optimised for an implementation's vertex caches or face performance penalties. +With compute shaders processing geometry, the role of the vertex shader is also somewhat redundant - transformations could be performed just as easily in compute shaders, and the vertex shader serves merely as a way to get at the fixed rasterization interface. + +This proposal aims to find a way to make the geometry pipeline more flexible, removing the unnecessary cost of an extra shader. + + +== Solution Space + +Making the geometry pipeline more flexible requires rethinking how data is transmitted from buffers to device memory; ideally a solution should allow applications to flexibly modify the set of geometry as a whole in the way developers are currently using compute shaders, and how they may use them in future (e.g. culling, grouping, decompression), without compromising on efficiency. Some considered ways to do this include: + + . Giving vertex shaders defined grouping, and enabling communication via subgroup operations + . Skipping the vertex shader and using geometry or tessellation shaders at the start of the pipeline + . Use compute shaders in place of pre-rasterization shader stages + +While a defined grouping in the vertex shaders would give applications the ability to manipulate sets of vertices, there is very limited ability to cull or remove vertices or primitives within a group, and the groups would be limited by the size of subgroups on the GPU without significant modifications. +Similarly, applications would be largely constrained by fixed input assembly requiring a 1:1 ratio of indices to input vertices, meaning things like decompressing meshes or acting at any granularity other than vertices would be infeasible. +Changing the vertex stage to accommodate this extra flexibility would require significant changes to how the stage works, which could likely better be accommodated by other existing stages. + +Skipping vertex shading and jumping straight to geometry or tessellation stages would provide a level of flexibility that could be interesting - both have access to geometric data at a granularity other than vertices, and are able to remove or add geometric detail before rasterization. +The main issues with these stages is that they are still rather fixed in terms of inputs, output topology, and the granularity they operate at - they are also historically not very efficient across platforms, and removing the vertex shader from the front of the pipeline would not do much to help that. + +The last clear option is to effectively use compute shaders in place of existing rasterization stages, enabling applications to more easily port existing compute shaders to this new extension with all the flexibility intact. +The main difficulty with this is simply defining the interface between the shader and the rasterizer, as existing compute shaders simply write out to buffers, whereas rasterization hardware is highly specialized, and may need to be fed in a particular manner. + +This extension opts for something close to option 3, by replacing all pre-rasterization shaders in the graphics pipeline with two new stages that operate like compute shaders but with output that can be consumed by the rasterizer. + + +== Proposal + +=== New Shaders + +This proposal adds two new shader stages, which can be used in place of the existing pre-rasterization shader stages; <> and <>. + + +==== Mesh Shaders + +Mesh shaders are a new compute-like shader stage that has a primary aim of generating a set of primitives to the rasterizer, which are passed via its new output interface. +For the most part, these map well to compute shaders - they are dispatched in workgroups and have access to shared memory, workgroup barriers, and local IDs, allowing for a lot of flexibility in how they are executed. + +Unlike vertex shaders, they do not use the vertex input interface, and geometry and indices must: be generated by the shader or read from buffers with no requirement for applications to provide the data in a particular way. +As such, this allows applications to read or generate data however they need to, removing the need to prepare data before launching the graphics pipeline. +This allows items such as decompression or decryption of data to be performed within the graphics pipeline directly, avoiding the bandwidth cost typically associated with compute shaders. + +Another key part of mesh shaders is that the number of primitives that a given workgroup can emit is dynamic - there are limits to how much can be emitted, which is advertised by the implementation, but applications can freely emit fewer primitives than the maximum. +This allows things like modifying the level of detail at a fine granularity without the use of tessellation. +Vertex outputs are written via the `Output` storage class and using standard built-ins like `Position` and `PointSize`, but are written as arrays in the same way as a tessellation control shader's outputs. +Additionally, the mesh shader outputs indices per primitive according to the output primitive type (points, lines, or triangles). Indices are emitted as a separate array in a similar fashion to vertex outputs. +Mesh shader output topologies are lists only - there is no support for triangle or line strips or triangle fans; data in these formats must be unpacked by the shader. +Other user data can be emitted at per-vertex or per-primitive rates alongside these built-ins. +Mesh shaders must specify the actual number of primitives and vertices being emitted before writing them, via the `OpSetMeshOutputsEXT` instruction. +Subsequent fragment shaders can retrieve input data at both rates, tied to the vertices and primitive being rasterized. + +Mesh shaders can be dispatched from the API like a compute shader would be, or launched via <>. + + +==== Task Shaders + +Task shaders are an optional shader stage that executes ahead of mesh shaders. A task shader is dispatched like a compute shader, and indirectly dispatches mesh shader workgroups. +This shader is another compute-like stage that is executed in workgroups and has all the other features of compute shaders as well, with the addition of access to a dedicated instruction to launch mesh shaders. + +The primary function of task shaders is to dispatch mesh shaders via code:OpEmitMeshTasksEXT, which takes as input a number of mesh shader groups to emit, and a payload variable that will be visible to all mesh shader invocations launched by this instruction. +This instruction is executed once per workgroup rather than per-invocation, and the payload itself is in a workgroup-wide storage class, similar to shared memory. +Once this instruction is called, the workgroup is terminated immediately, and the mesh shaders are launched. + +Task shaders can be used for functionality like coarse culling of entire meshlets or dynamically generating more or less geometry depending on the level of detail required. +This is notionally similar to the purpose of tessellation shaders, but without the constraint of fixed functionality, and with greater flexibility in how primitives are executed. +Applications can use task shaders to determine the number of launched mesh shader workgroups at whatever input granularity they want, and however they see fit. + + +==== Rasterization Order + +As task and mesh shaders change how primitives are dispatched, a subsequent modification of rasterization order is made. +Within a mesh shader workgroup, primitives are rasterized in the order in which they are defined in the output. +A group of mesh shaders either launched directly by the API, indirectly by the API, +or indirectly from a single task shader workgroup will rasterize their outputs in sequential order based on their flattened global invocation index, +equal to asciimath:[x + y * width + z * width * height], where `x`, `y`, and `z` refer to the components of the code:GlobalInvocationId built-in. +`width` and `height` are equal to code:NumWorkgroups times code:WorkgroupSize for their respective dimensions. +When using task shaders, there is no rasterization order guarantee between mesh shaders launched by separate task shader workgroups, even within the same draw command. + + +=== API Changes + +==== Graphics Pipeline Creation + +Graphics pipelines can now be created using mesh and task shaders in place of vertex, tessellation, and geometry shaders. +This can be achieved by omitting existing pre-rasterization shaders and including a mesh shader stage, and optionally a task shader stage. +When present, a graphics pipeline is complete without the inclusion of the link:{spec}#pipeline-graphics-subsets-vertex-input[vertex input state subset], as this state does not participate in mesh pipelines. +No other modifications to graphics pipelines are necessary. +Two new shader stages are added to the API to describe the new shader stages: + +```c +VK_SHADER_STAGE_TASK_BIT = 0x40, +VK_SHADER_STAGE_MESH_BIT = 0x80, +``` +Note that `VK_SHADER_STAGE_ALL_GRAPHICS_BIT` was defined as a mask of existing bits during Vulkan 1.0 development, and thus cannot include these new bits; modifying it would break compatibility. + +==== Synchronization + +New pipeline stages are added for synchronization of these new stages: + +```c +VK_PIPELINE_STAGE_TASK_SHADER_BIT_EXT = 0x80000, +VK_PIPELINE_STAGE_MESH_SHADER_BIT_EXT = 0x100000, +``` + +```c +static const VkPipelineStageFlagBits2KHR VK_PIPELINE_STAGE_TASK_SHADER_BIT_2_EXT = 0x00080000ULL; +static const VkPipelineStageFlagBits2KHR VK_PIPELINE_STAGE_MESH_SHADER_BIT_2_EXT = 0x00100000ULL; +``` + +These new pipeline stages interact similarly to compute shaders, with all the same access types and operations. +They are also logically ordered before fragment shading, but have no logical ordering compared to existing pre-rasterization shader stages. +The `VK_PIPELINE_STAGE_2_PRE_RASTERIZATION_SHADERS_BIT` stage added by link:{refpage}VK_KHR_synchronization2.html[VK_KHR_synchronization2] includes these new shader stages, and can be used identically. + + +==== Queries + +Pipeline statistics queries are updated with new bits to count mesh and task shader invocations, in a similar manner to how other shader invocations are counted: + +```c +VK_QUERY_PIPELINE_STATISTIC_TASK_SHADER_INVOCATIONS_BIT_EXT = 0x800, +VK_QUERY_PIPELINE_STATISTIC_MESH_SHADER_INVOCATIONS_BIT_EXT = 0x1000, +``` + +An additional standalone query counting the number of mesh primitives generated is added: + +```c +VK_QUERY_TYPE_MESH_PRIMITIVES_GENERATED_EXT = 1000328000, +``` + +An active query of this type will generate a count of every individual primitive emitted from any mesh shader workgroup that is not culled by fixed function culling. + + +==== Draw Calls + +Three new draw calls are added to the API to dispatch mesh pipelines: + +```c +void vkCmdDrawMeshTasksEXT( + VkCommandBuffer commandBuffer, + uint32_t groupCountX, + uint32_t groupCountY, + uint32_t groupCountZ); + +VKAPI_ATTR void VKAPI_CALL vkCmdDrawMeshTasksIndirectEXT( + VkCommandBuffer commandBuffer, + VkBuffer buffer, + VkDeviceSize offset, + uint32_t drawCount, + uint32_t stride); + +VKAPI_ATTR void VKAPI_CALL vkCmdDrawMeshTasksIndirectCountEXT( + VkCommandBuffer commandBuffer, + VkBuffer buffer, + VkDeviceSize offset, + VkBuffer countBuffer, + VkDeviceSize countBufferOffset, + uint32_t maxDrawCount, + uint32_t stride); + +typedef struct VkDrawMeshTasksIndirectCommandEXT { + uint32_t x; + uint32_t y; + uint32_t z; +} VkDrawMeshTasksIndirectCommandEXT; +``` + +`vkCmdDrawMeshTasksEXT` is the simplest as it functions the same as link:{refpage}vkCmdDispatch.html[vkCmdDispatch], but dispatches the mesh or task shader in a graphics pipeline with the specified workgroup counts, rather than a compute shader. + +`vkCmdDrawMeshTasksIndirectEXT` functions similarly to link:{refpage}vkCmdDispatchIndirect.html[vkCmdDispatchIndirect], but with the draw count functionality from other draw commands. +Multiple draws are dispatched according to the `drawCount` parameter, with data in buffer being consumed as a strided array of `VkDrawMeshTasksIndirectCommandEXT` structures, with stride equal to `stride`. +Each element of this array defines a separate draw call's workgroup counts in each dimension, and dispatches mesh or task shaders for the current pipeline accordingly. + +`vkCmdDrawMeshTasksIndirectCountEXT` functions as `vkCmdDrawMeshTasksIndirectEXT`, but takes its draw count from the device as well. +The draw count is read from `countBuffer` at an offset of `countBufferOffset`, and must be lower than `maxDrawCount`. + + +==== Properties + +Several new properties are added to the API - some dictating hard limits, and others indicating performance considerations: + +```c +typedef struct VkPhysicalDeviceMeshShaderPropertiesEXT { + VkStructureType sType; + void* pNext; + uint32_t maxTaskWorkGroupTotalCount; + uint32_t maxTaskWorkGroupCount[3]; + uint32_t maxTaskWorkGroupInvocations; + uint32_t maxTaskWorkGroupSize[3]; + uint32_t maxTaskPayloadSize; + uint32_t maxTaskSharedMemorySize; + uint32_t maxTaskPayloadAndSharedMemorySize; + uint32_t maxMeshWorkGroupTotalCount; + uint32_t maxMeshWorkGroupCount[3]; + uint32_t maxMeshWorkGroupInvocations; + uint32_t maxMeshWorkGroupSize[3]; + uint32_t maxMeshSharedMemorySize; + uint32_t maxMeshPayloadAndSharedMemorySize; + uint32_t maxMeshOutputMemorySize; + uint32_t maxMeshPayloadAndOutputMemorySize; + uint32_t maxMeshOutputComponents; + uint32_t maxMeshOutputVertices; + uint32_t maxMeshOutputPrimitives; + uint32_t maxMeshOutputLayers; + uint32_t maxMeshMultiviewViewCount; + uint32_t meshOutputPerVertexGranularity; + uint32_t meshOutputPerPrimitiveGranularity; + uint32_t maxPreferredTaskWorkGroupInvocations; + uint32_t maxPreferredMeshWorkGroupInvocations; + VkBool32 prefersLocalInvocationVertexOutput; + VkBool32 prefersLocalInvocationPrimitiveOutput; + VkBool32 prefersCompactVertexOutput; + VkBool32 prefersCompactPrimitiveOutput; +} VkPhysicalDeviceMeshShaderPropertiesEXT; +``` + +The following limits affect task shader execution: + + * `maxTaskWorkGroupTotalCount` indicates the total number of workgroups that can be launched for a task shader. + * `maxTaskWorkGroupCount` indicates the number of workgroups that can be launched for a task shader in each given dimension. + * `maxTaskWorkGroupInvocations` indicates the total number of invocations that can be launched for a task shader in a single workgroup. + * `maxTaskWorkGroupSize` indicates the maximum number of invocations for a task shader in each dimension for a single workgroup. + * `maxTaskPayloadSize` indicates the maximum total size of task shader output payloads. + * `maxTaskSharedMemorySize` indicates the maximum total size of task shader shared memory variables. + * `maxTaskPayloadAndSharedMemorySize` indicates the maximum total combined size of task shader output payloads and shared memory variables. + +Similar limits affect task shader execution: + + * `maxMeshWorkGroupTotalCount` indicates the total number of workgroups that can be launched for a mesh shader. + * `maxMeshWorkGroupCount` indicates the number of workgroups that can be launched for a mesh shader in each given dimension. + * `maxMeshWorkGroupInvocations` indicates the total number of invocations that can be launched for a mesh shader in a single workgroup. + * `maxMeshWorkGroupSize` indicates the maximum number of invocations for a mesh shader in each dimension for a single workgroup. + * `maxMeshSharedMemorySize` indicates the maximum total size of mesh shader shared memory variables. + * `maxMeshPayloadAndSharedMemorySize` indicates the maximum total combined size of mesh shader input payloads and shared memory variables. + * `maxMeshSharedMemorySize` indicates the maximum total size of mesh shader output variables. + * `maxMeshPayloadAndOutputMemorySize` indicates the maximum total combined size of mesh shader input payloads and output variables. + * `maxMeshOutputComponents` is the maximum number of components of mesh shader output variables. + * `maxMeshOutputVertices` is the maximum number of vertices a mesh shader can emit. + * `maxMeshOutputPrimitives` is the maximum number of primitives a mesh shader can emit. + * `maxMeshOutputLayers` is the maximum number of layers that a mesh shader can render to. + * `maxMeshMultiviewViewCount` is the maximum number of views that a mesh shader can render to. + +When considering the above properties, the number of mesh shader outputs a shader uses are rounded up to implementation-defined numbers defined by the following properties: + + * `meshOutputPerVertexGranularity` is the alignment of each per-vertex mesh shader output. + * `meshOutputPerPrimitiveGranularity` is the alignment of each per-primitive mesh shader output. + +The following properties are implementation preferences. +Violating these limits will not result in validation errors, but it is strongly recommended that applications adhere to them in order to maximize performance on each implementation. + + * `maxPreferredTaskWorkGroupInvocations` indicates the maximum preferred number of task shader invocations in a single workgroup. + * `maxPreferredMeshWorkGroupInvocations` indicates the maximum preferred number of mesh shader invocations in a single workgroup. + * If `prefersLocalInvocationVertexOutput` is `VK_TRUE`, the implementation will perform best when each invocation writes to an array index in the per-vertex output matching code:LocalInvocationIndex. + * If `prefersLocalInvocationPrimitiveOutput` is `VK_TRUE`, the implementation will perform best when each invocation writes to an array index in the per-primitive output matching code:LocalInvocationIndex. + * If `prefersCompactVertexOutput` is `VK_TRUE`, the implementation will perform best if there are no unused vertices in the output array. + * If `prefersCompactPrimitiveOutput` is `VK_TRUE`, the implementation will perform best if there are no unused primitives in the output array. + +Note that even if some of the above values are false, the implementation can still perform just as well whether or not the corresponding preferences are followed. It is recommended to follow these preferences unless the performance cost of doing so outweighs the gains of hitting the optimal paths in the implementation. + + +==== Features + +A few new features are introduced by this extension: + +```c +typedef struct VkPhysicalDeviceMeshShaderFeaturesEXT { + VkStructureType sType; + void* pNext; + VkBool32 taskShader; + VkBool32 meshShader; + VkBool32 multiviewMeshShader; + VkBool32 primitiveFragmentShadingRateMeshShader; + VkBool32 meshShaderQueries; +} VkPhysicalDeviceMeshShaderFeaturesEXT; +``` + + * `taskShader` indicates support for task shaders and associated features - if not supported, only mesh shaders can be used. + * `meshShader` indicates support for mesh shaders and associated features - if not supported, none of the features in this extension can be used. + * `multiviewMeshShader` indicates support for the use of multi-view with mesh shaders. + * `primitiveFragmentShadingRateMeshShader` indicates whether the per-primitive fragment shading rate can be written by mesh shaders when fragment shading rates are supported. + * `meshShaderQueries` indicates support for the new queries added by this extension. + + +=== SPIR-V Changes + +One new capability is added gating all of the new functionality: + +``` +MeshShadingEXT +``` + +Two new execution models are added, corresponding to the two <> added by this extension: + +``` +TaskEXT +MeshEXT +``` + +Task shader output/mesh shader input payloads are declared in a new storage class: + +``` +TaskPayloadWorkgroupEXT +``` + +Variables in this storage class are accessible by all invocations in a workgroup in a task shader, and is broadcast to all invocations in workgroups dispatched by the same task shader workgroup where it is read-only. + +In task shaders, code:TaskPayloadWorkgroupEXT is a hybrid of code:Output and code:Workgroup storage classes. It supports all usual operations code:Workgroup supports, with the caveats of: + + . No explicit memory layout support with `VK_KHR_workgroup_memory_explicit_layout` + . Can be declared independently of code:Workgroup, meaning local scratch workgroup memory can still be used with `VK_KHR_workgroup_memory_explicit_layout` + . Has two separate limits for size, `maxTaskPayloadSize` for its size in isolation, and `maxTaskPayloadAndSharedMemorySize` for the combined size + +Mesh shaders declare the type of primitive being output by way of three new execution modes: + +``` +OutputLinesEXT +OutputTrianglesEXT +OutputPrimitivesEXT +``` + +A new decoration is added to for mesh shader outputs/fragment shader inputs to indicate per-primitive data rather than per-vertex data: + +``` +PerPrimitiveEXT +``` + +New per-primitive built-ins are added: + +``` +PrimitivePointIndicesEXT +PrimitiveLineIndicesEXT +PrimitiveTriangleIndicesEXT +CullPrimitiveEXT +``` + +Each of the `Primitive*IndicesEXT` built-ins is used when the corresponding execution mode is specified, declared as scalars or vectors with a number of components equal to the number of vertices in the primitive type. +`CullPrimitiveEXT` is a per-primitive boolean value indicating to the implementation that its corresponding primitive must not be rasterized and is instead discarded with no further processing once emitted. + +A new instruction is added to task shaders to launch mesh shader workgroups: + + +[cols="1,1,2,2,2*2",width="100%"] +|===== +5+|[[OpEmitMeshTasksEXT]]*OpEmitMeshTasksEXT* + + + +Defines the grid size of subsequent mesh shader workgroups to generate +upon completion of the task shader workgroup. + + + +'Group Count X Y Z' must each be a 32-bit unsigned integer value. +They configure the number of local workgroups in each respective dimensions +for the launch of child mesh tasks. See Vulkan API specification for more detail. + + + +'Payload' is an optional pointer to the payload structure to pass to the generated mesh shader invocations. +'Payload' must be the result of an *OpVariable* with a storage class of *TaskPayloadWorkgroupEXT*. + + + +The arguments are taken from the first invocation in each workgroup. +Any invocation must execute this instruction exactly once and under uniform +control flow. +This instruction also serves as an *OpControlBarrier* instruction, and also +performs and adheres to the description and semantics of an *OpControlBarrier* +instruction with the 'Execution' and 'Memory' operands set to *Workgroup* and +the 'Semantics' operand set to a combination of *WorkgroupMemory* and +*AcquireRelease*. +Ceases all further processing: Only instructions executed before +*OpEmitMeshTasksEXT* have observable side effects. + + + +This instruction must be the last instruction in a block. + + + +This instruction is only valid in the *TaskEXT* Execution Model. +|<>: + +*MeshShadingEXT* +| 4 + variable | 5294 | '' + +'Group Count X' | '' + +'Group Count Y' | '' + +'Group Count Z' | Optional + +'' + +'Payload' +|===== + +A new mesh shader instruction is added to set the number of actual primitives and vertices that a mesh shader writes, avoiding unnecessary allocations or processing by the implementation: + +[cols="1,1,2*3",width="100%"] +|===== +3+|[[OpSetMeshOutputsEXT]]*OpSetMeshOutputsEXT* + + + +Sets the actual output size of the primitives and vertices that the mesh shader +workgroup will emit upon completion. + + + +'Vertex Count' must be a 32-bit unsigned integer value. +It defines the array size of per-vertex outputs. + + + +'Primitive Count' must a 32-bit unsigned integer value. +It defines the array size of per-primitive outputs. + + + +The arguments are taken from the first invocation in each workgroup. +Any invocation must execute this instruction no more than once and under +uniform control flow. +There must not be any control flow path to an output write that is not preceded +by this instruction. + + + +This instruction is only valid in the *MeshEXT* Execution Model. +|<>: + +*MeshShadingEXT* +| 3 | 5295 | '' + +'Vertex Count' | '' + +'Primitive Count' +|===== + +This instruction must be called before writing to mesh shader outputs. + + +=== GLSL Changes + +Mesh shaders defined in GLSL the same as compute shaders, with the addition of access to shader outputs normally available in vertex shaders and the following new features: + +```glsl +out uint gl_PrimitivePointIndicesEXT[]; +out uvec2 gl_PrimitiveLineIndicesEXT[]; +out uvec3 gl_PrimitiveTriangleIndicesEXT[]; +``` + +These built-ins correspond to the identically named SPIR-V constructs, and are written in the same way. +Applications should access only the index output corresponding to the primitive type declared by the following layout qualifiers: + +```glsl +points +lines +triangles +``` + +Each layout qualifier is declared as `layout() out;`. + +A new auxiliary storage qualifier can be added to interface variables to indicate that they are per-primitive rate: + +```glsl +perprimitiveEXT +``` + +New write-only output blocks are defined for built-in output values from mesh shaders: + +```glsl +out gl_MeshPerVertexEXT { + vec4 gl_Position; + float gl_PointSize; + float gl_ClipDistance[]; + float gl_CullDistance[]; +} gl_MeshVerticesEXT[]; + +perprimitiveEXT out gl_MeshPerPrimitiveEXT { + int gl_PrimitiveID; + int gl_Layer; + int gl_ViewportIndex; + bool gl_CullPrimitiveEXT; + int gl_PrimitiveShadingRateEXT; +} gl_MeshPrimitivesEXT[]; +``` + +Note that some existing outputs that previously were associated by provoking vertices are now directly declared as per-primitive variables. + +Finally a new mesh-shader function is added: + +```glsl + void SetMeshOutputsEXT(uint vertexCount, + uint primitiveCount) +``` + +This function maps exactly to the `OpSetMeshOutputsEXT` instruction - setting the number of valid vertices and primitives that are output by the mesh shader workgroup. + +Task shader payloads can be declared in task and mesh shaders using the new `taskPayloadSharedEXT` storage qualifier as follows: + +```glsl +taskPayloadSharedEXT MyPayloadStruct { + ... +} payload; +``` + +Finally a new function corresponding to `OpEmitMeshTasksEXT` is added to launch mesh workgroups: + +```glsl + void EmitMeshTasksEXT(uint groupCountX, + uint groupCountY, + uint groupCountZ) +``` + + +=== HLSL Changes + +The HLSL specification for mesh shaders is defined by Microsoft® here: https://microsoft.github.io/DirectX-Specs/d3d/MeshShader.html. + +Everything in that specification should work directly as described, with the exception of linking per-primitive interface variables between pixel and mesh shaders. +Microsoft defined the fragment/mesh interface to effectively be fixed up at link time - making no distinction between per-vertex and per-primitive variables in the pixel shader. +This works okay with monolithic pipeline construction, but with the addition of things like link:{refpage}VK_EXT_graphics_pipeline_library.html[VK_EXT_graphics_pipeline_library], modifying this at link time would cause undesirable slowdown. +As a result, the Vulkan version of this feature requires the `\[[vk::perprimitive]]` attribute on pixel shader inputs in order to generate a match with mesh shader outputs denoted with the `primitives` qualifier. + +Mapping to SPIR-V is largely performed identically to any other shader for both mesh and task shaders, with most new functionality mapping 1:1. +One outlier is in index generation - the primitive index outputs are denoted by a variable in the function signature preceded by `out indices ...`. +The HLSL compiler should map this variable to the appropriate built-in value based on the selected `outputtopology` qualifier. + +Another outlier is the groupshared task payload. In HLSL this is declared as groupshared, but must be declared in the code:TaskPayloadWorkgroupEXT storage class in SPIR-V. +The call to `DispatchMesh()` can inform the compiler which groupshared variable to promote to code:TaskPayloadWorkgroupEXT. + + +== Issues + +=== What are the differences to VK_NV_mesh_shader? + +The following changes have been made to the API: + + * Drawing mesh tasks can now be done with a three-dimensional number of workgroups, rather than just one-dimensional. + * There are new device queries for the number of mesh primitives generated, and the number of shader invocations for the new shader stages. + * A new command token is added when interacting with VK_NV_device_generated_commands, as mesh shaders from each extension are incompatible. + * New optional features have been added for interactions with multiview, primitive fragment shading rate specification, and the new queries. + * Several more device properties are expressed to enable app developers to use mesh shaders optimally across vendors (see <> for details of how these are expressed and used). + +Note that the SPIR-V and GLSL expression of these extensions have changed, details of which are outlined in those extensions. +These changes aim to make the extension more portable across multiple vendors, and increase compatibility with the similar feature in Microsoft® DirectX®. + +=== What are the differences to DirectX® 12's Mesh shaders? + +From the shader side, declaring mesh or amplification shaders in HLSL will have no meaningful differences - HLSL code written for DirectX should also work fine in Vulkan, with all the expected limits and features available. +One difference is present in pixel shaders though - any user-declared attributes with the "primitive" keyword in the mesh shader will need to be declared in the fragment shader with the `\[[vk::perprimitive]]` attribute to facilitate linking. +This makes it so that the shader can be compiled without modifying the input interface, which is particularly important for interactions with extensions like link:{refpage}VK_EXT_graphics_pipeline_library.html[VK_EXT_graphics_pipeline_library]. + +Some amount of massaging by the HLSL compiler will be required to the shader interfaces as DirectX does linking by name rather than location between mesh and pixel shaders, but the requirement to use `\[[vk::perprimitive]]` allows the different attributes to continue using locations in Vulkan. + +The only notable difference on the API side is that Vulkan provides additional device properties that allow developers to tune their shaders to different vendors' fast paths, should they wish to. +Details of how these are expressed are detailed <>. + +=== Can there be more than one output payload in a task shader? + +There can only be one output payload per task shader; one declaration in HLSL or GLSL, and only one in the interface declaration for SPIR-V. +More would have no effect anyway, as only one payload can be emitted for mesh shader consumption. + +=== Should developers port everything to mesh shading? + +Mesh shaders are not necessarily a performance win compared to the existing pipeline - their purpose is to offer greater flexibility at decent performance, but this flexibility may come at a cost, and that cost is likely platform dependent. +What task and mesh shading offer is a way to perform novel techniques efficiently compared to the hoops developers would previously have to jump through. +Task and mesh shaders are a tool that should be used when it makes sense to do so - if a developer has a novel technique that would be easier to implement using task and mesh shaders, then they are likely the appropriate tool. +Moving from an existing optimized pipeline without this consideration may lead to decreased performance. + +=== Does vertex input interface state interact with task/mesh shaders? + +No, topology information is specified within the mesh shader, and data must be read or generated these shader stages programmatically. diff --git a/proposals/VK_EXT_metal_objects.adoc b/proposals/VK_EXT_metal_objects.adoc index 152ae31881..fb197b1f65 100644 --- a/proposals/VK_EXT_metal_objects.adoc +++ b/proposals/VK_EXT_metal_objects.adoc @@ -4,7 +4,7 @@ = VK_EXT_metal_objects :toc: left -:refpage: https://registry.khronos.org/vulkan/specs/1.2-extensions/man/html/ +:refpage: https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/ :sectnums: This document details API design ideas for the `VK_EXT_metal_objects` extension, diff --git a/proposals/VK_EXT_multisampled_render_to_single_sampled.adoc b/proposals/VK_EXT_multisampled_render_to_single_sampled.adoc index c19112e2f2..4e71972140 100644 --- a/proposals/VK_EXT_multisampled_render_to_single_sampled.adoc +++ b/proposals/VK_EXT_multisampled_render_to_single_sampled.adoc @@ -4,7 +4,7 @@ # VK_EXT_multisampled_render_to_single_sampled :toc: left -:refpage: https://registry.khronos.org/vulkan/specs/1.2-extensions/man/html/ +:refpage: https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/ :sectnums: This document identifies difficulties with efficient multisampled rendering on diff --git a/proposals/VK_EXT_non_seamless_cube_map.adoc b/proposals/VK_EXT_non_seamless_cube_map.adoc index b8a6c83500..ac4165ec62 100644 --- a/proposals/VK_EXT_non_seamless_cube_map.adoc +++ b/proposals/VK_EXT_non_seamless_cube_map.adoc @@ -4,7 +4,7 @@ = VK_EXT_non_seamless_cube_map :toc: left -:refpage: https://registry.khronos.org/vulkan/specs/1.2-extensions/man/html/ +:refpage: https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/ :sectnums: == Problem Statement diff --git a/proposals/VK_EXT_primitives_generated_query.adoc b/proposals/VK_EXT_primitives_generated_query.adoc index 958cbe6124..4a6e4951b6 100644 --- a/proposals/VK_EXT_primitives_generated_query.adoc +++ b/proposals/VK_EXT_primitives_generated_query.adoc @@ -4,7 +4,7 @@ = VK_EXT_primitives_generated_query :toc: left -:refpage: https://registry.khronos.org/vulkan/specs/1.2-extensions/man/html/ +:refpage: https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/ :sectnums: This proposal regards layering OpenGL over Vulkan, and provides a convenience diff --git a/proposals/VK_EXT_rasterization_order_attachment_access.adoc b/proposals/VK_EXT_rasterization_order_attachment_access.adoc index 473aef4d0e..3f23828929 100644 --- a/proposals/VK_EXT_rasterization_order_attachment_access.adoc +++ b/proposals/VK_EXT_rasterization_order_attachment_access.adoc @@ -2,9 +2,9 @@ // // SPDX-License-Identifier: CC-BY-4.0 -= Proposal Template += VK_EXT_rasterization_order_attachment_access :toc: left -:refpage: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/ +:refpage: https://www.khronos.org/registry/vulkan/specs/1.3-extensions/man/html/ :sectnums: This proposal extends the mechanism of input attachments to allow access to framebuffer attachments that are used both as input and as @@ -16,7 +16,7 @@ Renderpasses, and specifically subpass self-dependencies enable much of the same fetch and pixel local storage extensions did for OpenGL ES. But certain techniques such as programmable blending are awkward or impractical to implement with these alone, in part because a self-dependency is required every time a fragment will read a value at a given sample coordinate. -For these use-cases, a mechanisms that more closely matches framebuffer fetch is useful. +For these use-cases, a mechanisms that more closely matches framebuffer fetch is useful. == Solution Space diff --git a/proposals/VK_GOOGLE_surfaceless_query.adoc b/proposals/VK_GOOGLE_surfaceless_query.adoc index 3abe55461d..b70e28dc67 100644 --- a/proposals/VK_GOOGLE_surfaceless_query.adoc +++ b/proposals/VK_GOOGLE_surfaceless_query.adoc @@ -4,7 +4,7 @@ = VK_GOOGLE_surfaceless_query :toc: left -:refpage: https://registry.khronos.org/vulkan/specs/1.2-extensions/man/html/ +:refpage: https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/ :sectnums: This proposal regards layering OpenGL over Vulkan, and addresses a discrepancy diff --git a/proposals/VK_HUAWEI_invocation_mask.adoc b/proposals/VK_HUAWEI_invocation_mask.adoc index 602f7fbc5a..1d8a9ee54e 100644 --- a/proposals/VK_HUAWEI_invocation_mask.adoc +++ b/proposals/VK_HUAWEI_invocation_mask.adoc @@ -5,7 +5,7 @@ = VK_HUAWEI_invocation_mask :toc: left -:refpage: https://registry.khronos.org/vulkan/specs/1.2-extensions/man/html/ +:refpage: https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/ diff --git a/proposals/VK_KHR_dynamic_rendering.adoc b/proposals/VK_KHR_dynamic_rendering.adoc index b4837f4364..b11adfe42d 100644 --- a/proposals/VK_KHR_dynamic_rendering.adoc +++ b/proposals/VK_KHR_dynamic_rendering.adoc @@ -4,7 +4,7 @@ = VK_KHR_dynamic_rendering :toc: left -:refpage: https://registry.khronos.org/vulkan/specs/1.2-extensions/man/html/ +:refpage: https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/ :sectnums: This document details API design ideas for the VK_KHR_dynamic_rendering extension, which adds a more dynamic and flexible way to use draw commands, as a straightforward replacement for single pass render passes. @@ -275,7 +275,7 @@ If either `depthAttachmentFormat` or `stencilAttachmentFormat` are not `VK_FORMA The value of `viewMask` must match the value of the `viewMask` member of `VkRenderingInfoKHR`. -===== Multiview Per-View Attributes +==== Multiview Per-View Attributes If link:{refpage}VK_NVX_multiview_per_view_attributes.html[VK_NVX_multiview_per_view_attributes] is enabled, the multiview per-view attributes can be specified by including the `VkMultiviewPerViewAttributesInfoNVX` structure in the same `pNext` chain. diff --git a/proposals/VK_KHR_fragment_shader_barycentric.adoc b/proposals/VK_KHR_fragment_shader_barycentric.adoc index f3051e37b7..bd6aeae886 100644 --- a/proposals/VK_KHR_fragment_shader_barycentric.adoc +++ b/proposals/VK_KHR_fragment_shader_barycentric.adoc @@ -2,9 +2,9 @@ // // SPDX-License-Identifier: CC-BY-4.0 -= Proposal Template += VK_KHR_fragment_shader_barycentric :toc: left -:refpage: https://registry.khronos.org/vulkan/specs/1.2-extensions/man/html/ +:refpage: https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/ :sectnums: This document details the VK_KHR_fragment_shader_barcentric extension, which adds a cross-vendor way to access barycentric coordinates in a fragment shader. @@ -55,8 +55,8 @@ Vertices are numbered as follows: [cols="10,10,10,10",options="header",width = "80%"] |==== -| Primitive Topology | Vertex 0 | Vertex 1 | Vertex 2 -| `VK_PRIMITIVE_TOPOLOGY_POINT_LIST` | i | i | i +| Primitive Topology | Vertex 0 | Vertex 1 | Vertex 2 +| `VK_PRIMITIVE_TOPOLOGY_POINT_LIST` | i | i | i | `VK_PRIMITIVE_TOPOLOGY_LINE_LIST` | 2i | 2i+1 | 2i+1 | `VK_PRIMITIVE_TOPOLOGY_LINE_STRIP` | i | i+1 | i+1 | `VK_PRIMITIVE_TOPOLOGY_TRIANGLE_LIST` | 3i | 3i+1 | 3i+2 @@ -74,7 +74,7 @@ When the provoking vertex mode is `VK_PROVOKING_VERTEX_MODE_LAST_VERTEX_EXT`, th [cols="10,10,10,10",options="header",width = "80%"] |==== -| Primitive Topology | Vertex 0 | Vertex 1 | Vertex 2 +| Primitive Topology | Vertex 0 | Vertex 1 | Vertex 2 | VK_PRIMITIVE_TOPOLOGY_TRIANGLE_STRIP (odd, and `triStripVertexOrderIndependentOfProvokingVertex` is `VK_FALSE`) | i+1 | i | i+2 | VK_PRIMITIVE_TOPOLOGY_TRIANGLE_FAN | 0 | i+1 | i+2 | VK_PRIMITIVE_TOPOLOGY_TRIANGLE_STRIP_WITH_ADJACENCY (odd) | 2i+2 | 2i | 2i+4 diff --git a/proposals/VK_KHR_fragment_shading_rate.adoc b/proposals/VK_KHR_fragment_shading_rate.adoc index 66d45e7e23..1f003e3bf8 100644 --- a/proposals/VK_KHR_fragment_shading_rate.adoc +++ b/proposals/VK_KHR_fragment_shading_rate.adoc @@ -4,7 +4,7 @@ = VK_KHR_fragment_shading_rate :toc: left -:refpage: https://registry.khronos.org/vulkan/specs/1.2-extensions/man/html/ +:refpage: https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/ :sectnums: This extension adds the ability to change the rate at which fragments are shaded. Rather than the usual single fragment invocation for each pixel covered by a primitive, multiple pixels can be shaded by a single fragment shader invocation. diff --git a/proposals/VK_KHR_shader_integer_dot_product.adoc b/proposals/VK_KHR_shader_integer_dot_product.adoc index 94dc7cb5c2..bd5cf662ca 100644 --- a/proposals/VK_KHR_shader_integer_dot_product.adoc +++ b/proposals/VK_KHR_shader_integer_dot_product.adoc @@ -4,7 +4,7 @@ = VK_KHR_shader_integer_dot_product :toc: left -:refpage: https://registry.khronos.org/vulkan/specs/1.2-extensions/man/html/ +:refpage: https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/ :sectnums: This document proposes adding support for shader integer dot product instructions. diff --git a/proposals/VK_QCOM_image_processing.adoc b/proposals/VK_QCOM_image_processing.adoc index 1fbac20b08..cf94fb01b4 100644 --- a/proposals/VK_QCOM_image_processing.adoc +++ b/proposals/VK_QCOM_image_processing.adoc @@ -4,7 +4,7 @@ # VK_QCOM_image_processing :toc: left -:refpage: https://registry.khronos.org/vulkan/specs/1.2-extensions/man/html/ +:refpage: https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/ :sectnums: diff --git a/proposals/VK_QCOM_tile_properties.adoc b/proposals/VK_QCOM_tile_properties.adoc index 23839f6995..b80450632a 100644 --- a/proposals/VK_QCOM_tile_properties.adoc +++ b/proposals/VK_QCOM_tile_properties.adoc @@ -4,7 +4,7 @@ = VK_QCOM_tile_properties :toc: left -:refpage: https://registry.khronos.org/vulkan/specs/1.2-extensions/man/html/ +:refpage: https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/ :sectnums: This document details API design ideas for the VK_QCOM_tile_properties extension, which allows application to query the tile properties. This extension supports both renderpasses and dynamic rendering. diff --git a/proposals/template.adoc b/proposals/template.adoc index c2947befc5..1977b27fc7 100644 --- a/proposals/template.adoc +++ b/proposals/template.adoc @@ -4,7 +4,7 @@ = Proposal Template :toc: left -:refpage: https://registry.khronos.org/vulkan/specs/1.2-extensions/man/html/ +:refpage: https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/ :sectnums: .How to use this document diff --git a/registry.adoc b/registry.adoc index 178ee7db77..59ff67a3dc 100644 --- a/registry.adoc +++ b/registry.adoc @@ -19,6 +19,9 @@ Jon Leech // Various special / math symbols. This is easier to edit with than Unicode. include::{config}/attribs.adoc[] +// Core versions and extensions to enable +include::{generated}/specattribs.adoc[] + :leveloffset: 1 <<<< @@ -1533,9 +1536,13 @@ tag:feature tags already define a specific API. These attributes are allowed only for a tag:require tag. * attr:extension - optional, and only for tag:require tags. - String containing an API extension name. - Interfaces in the tag are only required if the string matches the - attr:name of an tag:extension tag, and that extension is enabled. + String containing one or more API extension names separated by `,` or + `+`. + Interfaces in the tag are only required if enabled extensions satisfy + the logical expression in the string, where `,` is interpreted as a + logical OR and '+' as a logical AND. + Each extension name in the string must match the attr:name of a + tag:extension tag. * attr:feature - optional, and only for tag:require tags. String containing an API feature name. Interfaces in the tag are only required if the string matches the @@ -2864,6 +2871,9 @@ Changes to the `.xml` files and Python scripts are logged in Github history. [[changelog]] = Change Log + * 2022-08-12 - update tag:requires attr:extension syntax to support + logical OR and AND constructs for multiple extensions (internal issue + 2922). * 2022-07-11 - Add attr:videocoding attribute to <> tags to indicate whether a command buffer command can be recorded inside, outside, or both inside and outside of a video coding scope. diff --git a/roadmap/Roadmap 2022.adoc b/roadmap/Roadmap 2022.adoc index 9b7221d88c..9fe2018a54 100644 --- a/roadmap/Roadmap 2022.adoc +++ b/roadmap/Roadmap 2022.adoc @@ -2,6 +2,8 @@ // // SPDX-License-Identifier: CC-BY-4.0 +:times: × + [[roadmap-2022]] = Roadmap 2022 diff --git a/scripts/docgenerator.py b/scripts/docgenerator.py index 2247ce7c52..b48f3aa303 100644 --- a/scripts/docgenerator.py +++ b/scripts/docgenerator.py @@ -7,6 +7,7 @@ from pathlib import Path from generator import GeneratorOptions, OutputGenerator, noneStr, write +from parse_dependency import dependencyLanguage _ENUM_TABLE_PREFIX = """ [cols=",",options="header",] @@ -207,12 +208,28 @@ def genRequirements(self, name, mustBeFound = True): # To simplify this, sort the (base,dependency) requirements # and put them in a set to ensure they are unique. features = set() + # 'dependency' may be a boolean expression of extension names for (base,dependency) in self.apidict.requiredBy[name]: if dependency is not None: - l = sorted( - sorted((base, dependency)), - key=orgLevelKey) - features.add(' with '.join(l)) + # 'dependency' may be a boolean expression of extension + # names, in which case the sorting will not work well. + + # First, convert it from asciidoctor markup to language. + depLanguage = dependencyLanguage(dependency, specmacros=False) + + # If they are the same, the dependency is only a + # single extension, and sorting them works. + # Otherwise, skip it. + if depLanguage == dependency: + deps = sorted( + sorted((base, dependency)), + key=orgLevelKey) + depString = ' with '.join(deps) + else: + # An expression with multiple extensions + depString = f'{base} with {depLanguage}' + + features.add(depString) else: features.add(base) # Sort the overall dependencies so core versions are first diff --git a/scripts/formatsgenerator.py b/scripts/formatsgenerator.py index f2fe2f113c..10735eb813 100644 --- a/scripts/formatsgenerator.py +++ b/scripts/formatsgenerator.py @@ -116,7 +116,7 @@ def endFile(self): spirv_image_format_table.append('|code:Unknown|Any') for vk_format, spirv_format in self.spirv_image_format.items(): spirv_image_format_table.append('|code:{}|ename:{}'.format(spirv_format, vk_format)) - self.writeBlock('spirvimageformat.txt', spirv_image_format_table) + self.writeBlock(f'spirvimageformat{self.file_suffix}', spirv_image_format_table) # Generate Plane Format Compatibility Table plane_format_table = [] @@ -144,7 +144,7 @@ def endFile(self): height_divisor)) if add_condition: plane_format_table.append('endif::{}[]'.format(format_condition)) - self.writeBlock('planeformat.txt', plane_format_table) + self.writeBlock(f'planeformat{self.file_suffix}', plane_format_table) # Finish processing in superclass OutputGenerator.endFile(self) diff --git a/scripts/genRef.py b/scripts/genRef.py index b9171a470d..e4b960bcc6 100755 --- a/scripts/genRef.py +++ b/scripts/genRef.py @@ -18,6 +18,7 @@ printPageInfo, setLogFile) from reg import Registry from generator import GeneratorOptions +from parse_dependency import dependencyNames from apiconventions import APIConventions @@ -171,7 +172,11 @@ def seeAlsoList(apiName, explicitRefs=None, apiAliases=[]): for (base,dependency) in api.requiredBy[name]: refs.add(base) if dependency is not None: - refs.add(dependency) + # 'dependency' may be a boolean expression of extension + # names. + # Extract them for use in cross-references. + for extname in dependencyNames(dependency): + refs.add(extname) if len(refs) == 0: return None @@ -235,6 +240,8 @@ def refPageShell(pageName, pageDesc, fp, head_content = None, sections=None, tai s = '{}({})'.format(pageName, man_section) print('= ' + s, + '', + conventions.extra_refpage_body, '', sep='\n', file=fp) if pageDesc.strip() == '': diff --git a/scripts/genvk.py b/scripts/genvk.py index 1b473aca80..4cd362f02e 100755 --- a/scripts/genvk.py +++ b/scripts/genvk.py @@ -550,8 +550,8 @@ def makeGenOpts(args): # These are not Vulkan extensions, or a part of the Vulkan API at all, # but are treated in a similar fashion for generation purposes. # - # Each element of the videoStd[] array is an 'extension' name defining - # an interface, and is also the basis for the generated header file name. + # Each element of the videoStd[] array is an extension name defining an + # interface, and is also the basis for the generated header file name. videoStd = [ 'vulkan_video_codecs_common', diff --git a/scripts/interfacedocgenerator.py b/scripts/interfacedocgenerator.py index 1509061929..6c3a50fd47 100644 --- a/scripts/interfacedocgenerator.py +++ b/scripts/interfacedocgenerator.py @@ -6,6 +6,7 @@ import re from generator import OutputGenerator, write +from parse_dependency import dependencyLanguage def interfaceDocSortKey(item): if item == None: @@ -51,17 +52,22 @@ def writeNewInterfaces(self, feature, key, title, markup, fp): # Loop through required blocks, sorted so they start with "core" features for required in sorted(dict, key = interfaceDocSortKey): + # 'required' may be a boolean expression of extension + # names. + # Currently this syntax is the same as asciidoc conditional + # syntax, but will eventually become more complex. if required is not None: - requiredlink = 'apiext:' + required - match = re.search("[A-Z]+_VERSION_([0-9]+)_([0-9]+)",required) - if match is not None: - major = match.group(1) - minor = match.group(2) - version = major + '.' + minor - requiredlink = '<>' - + # Rewrite with spec macros and xrefs applied to names + requiredlink = dependencyLanguage(required, specmacros=True) + + # @@ A better approach would be to actually evaluate the + # logical expression at generation time. + # If the extensions required are not in the spec build, + # then do not include these requirements. + # This would support arbitrarily complex expressions, + # unlike asciidoc ifdef syntax. write('ifdef::' + required + '[]', file=fp) - write('If ' + requiredlink + ' is supported:', file=fp) + write(f'If {requiredlink} is supported:', file=fp) write('',file=fp) # Commands are relatively straightforward diff --git a/scripts/parse_dependency.py b/scripts/parse_dependency.py new file mode 100644 index 0000000000..b21edd97cc --- /dev/null +++ b/scripts/parse_dependency.py @@ -0,0 +1,209 @@ +# Copyright 2022 The Khronos Group Inc. +# Copyright 2003-2019 Paul McGuire +# SPDX-License-Identifier: MIT + +# apirequirements.py - parse 'depends' / 'extension' expressions in API XML +# Supported expressions at present: +# - extension names +# - '+' as AND connector +# - ',' as OR connector +# - parenthesization for grouping (not used yet) +# + +# Based on https://github.com/pyparsing/pyparsing/blob/master/examples/fourFn.py + +from pyparsing import ( + Literal, + Word, + Group, + Forward, + alphas, + alphanums, + Regex, + ParseException, + CaselessKeyword, + Suppress, + delimitedList, +) +import math +import operator +import re + +exprStack = [] + +def push_first(toks): + # print(f'push_first(toks = {toks}): |exprStack| = {len(exprStack)} exprStack = {exprStack}') + + exprStack.append(toks[0]) + +bnf = None + +def dependencyBNF(): + """ + boolop :: '+' | ',' + extname :: Char(alphas) + atom :: extname | '(' expr ')' + expr :: atom [ boolop atom ]* + """ + global bnf + if not bnf: + ident = Word(alphanums + '_') + + and_, or_ = map(Literal, '+,') + lpar, rpar = map(Suppress, '()') + boolop = and_ | or_ + + expr = Forward() + expr_list = delimitedList(Group(expr)) + atom = ( + boolop[...] + + ( + (ident).setParseAction(push_first) + | Group(lpar + expr + rpar) + ) + ) + + expr <<= atom + (boolop + atom).setParseAction(push_first)[...] + bnf = expr + return bnf + + +# map operator symbols to corresponding arithmetic operations +opn = { + '+': operator.and_, + ',': operator.or_, +} + +# map operator symbols to corresponding words +opname = { + '+': 'and', + ',': 'or', +} + +def extensionIsSupported(extname): + return True + +def evaluate_stack(s): + op, num_args = s.pop(), 0 + # print(f'evaluate_stack: op = {op} num_args {num_args}') + if isinstance(op, tuple): + op, num_args = op + if op in '+,': + # note: operands are pushed onto the stack in reverse order + op2 = evaluate_stack(s) + op1 = evaluate_stack(s) + return opn[op](op1, op2) + elif op[0].isalpha(): + # print(f'extname {op} => {supported(op)}') + return extensionIsSupported(op) + else: + raise Exception(f'invalid op: {op}') + +def evalDependencyLanguage(s, specmacros): + """Evaluate an expression stack, returning an English equivalent + + - s - the stack + - specmacros - if True, prepare the language for spec inclusion""" + + op, num_args = s.pop(), 0 + # print(f'evalDependencyLanguage: op = {op} num_args {num_args}') + if isinstance(op, tuple): + op, num_args = op + if op in '+,': + # @@ Should parenthesize, not needed yet + rhs = evalDependencyLanguage(s, specmacros) + return evalDependencyLanguage(s, specmacros) + f' {opname[op]} ' + rhs + elif op[0].isalpha(): + # This is an extension or feature name + if specmacros: + match = re.search("[A-Z]+_VERSION_([0-9]+)_([0-9]+)", op) + if match is not None: + major = match.group(1) + minor = match.group(2) + version = major + '.' + minor + return f'<>' + else: + return 'apiext:' + op + else: + return op + else: + raise Exception(f'invalid op: {op}') + +def dependencyLanguage(dependency, specmacros = False): + """Return an API dependency expression translated to natural language. + + - dependency - the expression + - specmacros - if True, prepare the language for spec inclusion with + macros and xrefs included""" + + global exprStack + exprStack = [] + results = dependencyBNF().parseString(dependency, parseAll=True) + # print(f'language(): stack = {exprStack}') + return evalDependencyLanguage(exprStack, specmacros) + +def evalDependencyNames(s): + """Evaluate an expression stack, returning a set of names + + - s - the stack""" + + op, num_args = s.pop(), 0 + # print(f'evalDependencyNames: op = {op} num_args {num_args}') + if isinstance(op, tuple): + op, num_args = op + if op in '+,': + # The operation itself is not evaluated, since all we care about is + # the names + return evalDependencyNames(s) | evalDependencyNames(s) + elif op[0].isalpha(): + return { op } + else: + raise Exception(f'invalid op: {op}') + +def dependencyNames(dependency): + """Return a set of the extension and version names in an API dependency + expression + + - dependency - the expression""" + + global exprStack + exprStack = [] + results = dependencyBNF().parseString(dependency, parseAll=True) + # print(f'names(): stack = {exprStack}') + return evalDependencyNames(exprStack) + +if __name__ == "__main__": + + def test(dependency, expected): + global exprStack + exprStack = [] + + try: + results = dependencyBNF().parseString(dependency, parseAll=True) + # print('test(): stack =', exprStack) + val = evaluate_stack(exprStack[:]) + except ParseException as pe: + print(dependency, "failed parse:", str(pe)) + except Exception as e: + print(dependency, "failed eval:", str(e), exprStack) + else: + print(dependency, "failed eval:", str(e), exprStack) + if val == expected: + print(f'{dependency} = {val} {results} => {exprStack}') + else: + print(f'{dependency} !!! {val} != {expected} {results} => {exprStack}') + + e = 'VK_VERSION_1_1+(bar,spam)' + # test(e, False) + print(f'{e} -> {dependencyNames(e)}') + print('\n------------\n') + print(f'{e} -> {dependencyLanguage(e, False)}') + print('\n------------\n') + print(f'{e} -> {dependencyLanguage(e, True)}') + + # test('true', True) + # test('(True)', True) + # test('false,false', False) + # test('false,true', True) + # test('false+true', False) + # test('VK_foo_bar+true', True) diff --git a/scripts/reg.py b/scripts/reg.py index 335b6b21fa..2aad56fa22 100644 --- a/scripts/reg.py +++ b/scripts/reg.py @@ -996,6 +996,11 @@ def fillFeatureDictionary(self, interface, featurename, api, profile): # Determine the required extension or version needed for a require block # Assumes that only one of these is specified + # 'extension', and therefore 'required_key', may be a boolean + # expression of extension names. + # 'required_key' is used only as a dictionary key at + # present, and passed through to the script generators, so + # they must be prepared to parse that expression. required_key = require.get('feature') if required_key is None: required_key = require.get('extension') diff --git a/scripts/scriptgenerator.py b/scripts/scriptgenerator.py index aaf02a5406..34ee9d6d05 100644 --- a/scripts/scriptgenerator.py +++ b/scripts/scriptgenerator.py @@ -79,7 +79,9 @@ def addInterfaceMapping(self, api, feature, required): - api - name of the API - feature - name of the feature requiring it - required - None, or an additional feature dependency within - 'feature' """ + 'feature'. The additional dependency is a boolean expression of + one or more extension and/or core version names, which is passed + through to the output script intact.""" # Each entry in self.apimap contains one or more # ( feature, required ) tuples. diff --git a/scripts/spec_tools/conventions.py b/scripts/spec_tools/conventions.py index 0b0f985003..b314ee72f5 100644 --- a/scripts/spec_tools/conventions.py +++ b/scripts/spec_tools/conventions.py @@ -430,3 +430,16 @@ def protectProtoComment(self): """Return True if generated #endif should have a comment matching the protection symbol used in the opening #ifdef/#ifndef.""" return False + + @property + def extra_refpage_headers(self): + """Return any extra headers (preceding the title) for generated + reference pages.""" + return '' + + @property + def extra_refpage_body(self): + """Return any extra text (following the title) for generated + reference pages.""" + return '' + diff --git a/scripts/vkconventions.py b/scripts/vkconventions.py index 6c585f5d1e..c8ee937c68 100644 --- a/scripts/vkconventions.py +++ b/scripts/vkconventions.py @@ -201,11 +201,6 @@ def special_use_section_anchor(self): section describing extension special uses in detail.""" return 'extendingvulkan-compatibility-specialuse' - @property - def extra_refpage_headers(self): - """Return any extra text to add to refpage headers.""" - return 'include::{config}/attribs.adoc[]' - @property def extension_index_prefixes(self): """Return a list of extension prefixes used to group extension refpages.""" @@ -269,3 +264,14 @@ def valid_flag_bit(self, bitpos): cause Vk*FlagBits values with bit 31 set to result in a 64 bit enumerated type, so disallows such flags.""" return bitpos >= 0 and bitpos < 31 + + @property + def extra_refpage_headers(self): + """Return any extra text to add to refpage headers.""" + return 'include::{config}/attribs.adoc[]' + + @property + def extra_refpage_body(self): + """Return any extra text (following the title) for generated + reference pages.""" + return 'include::{generated}/specattribs.adoc[]' diff --git a/style/extensions.adoc b/style/extensions.adoc index 4eb4d249b0..8820c14287 100644 --- a/style/extensions.adoc +++ b/style/extensions.adoc @@ -618,9 +618,9 @@ sed -i -E 's/`?<<(VK_[A-Za-z0-9_]*)>>`?/`apiext:\1`/g' chapters/{*.adoc,*/*.adoc extension name and place the new files there. For example, instead of `chapters/VK_KHR_android_surface.adoc`, there is `chapters/VK_KHR_android_surface/platformCreateSurface_android.adoc` and - `chapters/VK_KHR_android_surface/platformQuerySupport_android.adoc`, both - of which are conditionally included elsewhere in the core specification - files. + `chapters/VK_KHR_android_surface/platformQuerySupport_android.adoc`, + both of which are conditionally included elsewhere in the core + specification files. * Valid usage statements referring to interactions between structures in a pname:pNext chain must be described in the parent structure's language, as specified <>. @@ -732,8 +732,8 @@ Group. changes to existing language, to new commands and structures, to adding entire new chapters. New chapters must be defined in separate files under the `chapters/` - directory, and included at an appropriate point in `vkspec.adoc` or other - specification source files. + directory, and included at an appropriate point in `vkspec.adoc` or + other specification source files. Other changes and additions are included inline in existing chapters. * All changes that are specific to the new version must be protected by the asciidoctor conditional (e.g. the version name). diff --git a/style/writing.adoc b/style/writing.adoc index ecdcb3ebd6..68d42c44d6 100644 --- a/style/writing.adoc +++ b/style/writing.adoc @@ -1078,9 +1078,9 @@ was inserted by a script, not the original author. If the same set of valid usage statements are going to be common to multiple commands or structures, these should be extracted into a separate file under `chapters/commonvalidity/`. -The file name should be short but to the point (e.g. `draw_common.adoc`), and -then the file can be included in the relevant API features using standard -include syntax: +The file name should be short but to the point (e.g. `draw_common.adoc`), +and then the file can be included in the relevant API features using +standard include syntax: [source,asciidoc,subs=attributes+] ~~~~ diff --git a/styleguide.adoc b/styleguide.adoc index 3297a1bf29..ee262af1ae 100644 --- a/styleguide.adoc +++ b/styleguide.adoc @@ -19,6 +19,9 @@ Jon Leech, Tobias Hector // Various special / math symbols. This is easier to edit with than Unicode. include::{config}/attribs.adoc[] +// Core versions and extensions to enable +include::{generated}/specattribs.adoc[] + // Where the current Asciidoctor documentation is found. :docguide: https://docs.asciidoctor.org/asciidoc/latest diff --git a/vkspec.adoc b/vkspec.adoc index 9620e4009e..d4bfbda6eb 100644 --- a/vkspec.adoc +++ b/vkspec.adoc @@ -18,6 +18,9 @@ The Khronos{regtitle} Vulkan Working Group // Various special / math symbols. This is easier to edit with than Unicode. include::config/attribs.adoc[] +// Core versions and extensions to enable +include::{generated}/specattribs.adoc[] + // Table of contents is inserted here toc::[] @@ -91,9 +94,9 @@ include::chapters/tessellation.adoc[] include::chapters/geometry.adoc[] -ifdef::VK_NV_mesh_shader[] +ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] include::chapters/VK_NV_mesh_shader/mesh.adoc[] -endif::VK_NV_mesh_shader[] +endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] include::chapters/vertexpostproc.adoc[] diff --git a/xml/vk.xml b/xml/vk.xml index 5a184437c1..1fb4e0398a 100644 --- a/xml/vk.xml +++ b/xml/vk.xml @@ -159,7 +159,7 @@ branch of the member gitlab server. // Vulkan 1.3 version number #define VK_API_VERSION_1_3 VK_MAKE_API_VERSION(0, 1, 3, 0)// Patch version should always be set to 0 // Version of this file -#define VK_HEADER_VERSION 225 +#define VK_HEADER_VERSION 226 // Complete version of this file #define VK_HEADER_VERSION_COMPLETE VK_MAKE_API_VERSION(0, 1, 3, VK_HEADER_VERSION) @@ -4126,6 +4126,52 @@ typedef void* MTLSharedEvent_id; uint32_t taskCount uint32_t firstTask + + VkStructureType sType + void* pNext + VkBool32 taskShader + VkBool32 meshShader + VkBool32 multiviewMeshShader + VkBool32 primitiveFragmentShadingRateMeshShader + VkBool32 meshShaderQueries + + + VkStructureType sType + void* pNext + uint32_t maxTaskWorkGroupTotalCount + uint32_t maxTaskWorkGroupCount[3] + uint32_t maxTaskWorkGroupInvocations + uint32_t maxTaskWorkGroupSize[3] + uint32_t maxTaskPayloadSize + uint32_t maxTaskSharedMemorySize + uint32_t maxTaskPayloadAndSharedMemorySize + uint32_t maxMeshWorkGroupTotalCount + uint32_t maxMeshWorkGroupCount[3] + uint32_t maxMeshWorkGroupInvocations + uint32_t maxMeshWorkGroupSize[3] + uint32_t maxMeshSharedMemorySize + uint32_t maxMeshPayloadAndSharedMemorySize + uint32_t maxMeshOutputMemorySize + uint32_t maxMeshPayloadAndOutputMemorySize + uint32_t maxMeshOutputComponents + uint32_t maxMeshOutputVertices + uint32_t maxMeshOutputPrimitives + uint32_t maxMeshOutputLayers + uint32_t maxMeshMultiviewViewCount + uint32_t meshOutputPerVertexGranularity + uint32_t meshOutputPerPrimitiveGranularity + uint32_t maxPreferredTaskWorkGroupInvocations + uint32_t maxPreferredMeshWorkGroupInvocations + VkBool32 prefersLocalInvocationVertexOutput + VkBool32 prefersLocalInvocationPrimitiveOutput + VkBool32 prefersCompactVertexOutput + VkBool32 prefersCompactPrimitiveOutput + + + uint32_t groupCountX + uint32_t groupCountY + uint32_t groupCountZ + VkStructureType sType const void* pNext @@ -7119,6 +7165,11 @@ typedef void* MTLSharedEvent_id; void* pNext VkBool32 attachmentFeedbackLoopLayout + + VkStructureType sType + void* pNext + VkBool32 depthClampZeroOne + Vulkan enumerant (token) definitions @@ -11230,6 +11281,31 @@ typedef void* MTLSharedEvent_id; uint32_t maxDrawCount uint32_t stride + + void vkCmdDrawMeshTasksEXT + VkCommandBuffer commandBuffer + uint32_t groupCountX + uint32_t groupCountY + uint32_t groupCountZ + + + void vkCmdDrawMeshTasksIndirectEXT + VkCommandBuffer commandBuffer + VkBuffer buffer + VkDeviceSize offset + uint32_t drawCount + uint32_t stride + + + void vkCmdDrawMeshTasksIndirectCountEXT + VkCommandBuffer commandBuffer + VkBuffer buffer + VkDeviceSize offset + VkBuffer countBuffer + VkDeviceSize countBufferOffset + uint32_t maxDrawCount + uint32_t stride + VkResult vkCompileDeferredNV VkDevice device @@ -16479,10 +16555,10 @@ typedef void* MTLSharedEvent_id; - - - - + + + + @@ -17846,8 +17922,8 @@ typedef void* MTLSharedEvent_id; - - + + @@ -17859,6 +17935,10 @@ typedef void* MTLSharedEvent_id; + + + + @@ -17999,10 +18079,28 @@ typedef void* MTLSharedEvent_id; - - - - + + + + + + + + + + + + + + + + + + + + + + @@ -18594,7 +18692,7 @@ typedef void* MTLSharedEvent_id; - + @@ -18870,10 +18968,12 @@ typedef void* MTLSharedEvent_id; - + - - + + + + @@ -19375,6 +19475,42 @@ typedef void* MTLSharedEvent_id; + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + @@ -20949,6 +21085,9 @@ typedef void* MTLSharedEvent_id; + + + @@ -21405,5 +21544,8 @@ typedef void* MTLSharedEvent_id; + + +