From f8d76125ca22ec65dfcaedc7177e204f11ad7c7b Mon Sep 17 00:00:00 2001 From: Jon Leech Date: Fri, 8 Dec 2023 05:45:53 -0800 Subject: [PATCH] Change log for December 8, 2023 Vulkan 1.3.273 spec update: Github Issues * Add missing `bitwidth` attribute for elink:VkPhysicalDeviceSchedulingControlsFlagBitsARM (public issue 2277). Internal Issues * Use the new <> term to refer to trace ray instructions, instead of the too-specific code:OpTraceRayKHR (internal issue 3284). * Improve description of <>, refer to it from each ftext:vkCreate*Pipelines command, and add style guide language to follow this pattern for future multiple creation commands (internal issue 3707). * Add common blit image and copy image VU that copying an image with the same subresource must: be ename:VK_IMAGE_LAYOUT_GENERAL or ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR (internal MR 6143). * Markup improvements and correct use of normative must: for flink:vkGetPhysicalDeviceOpticalFlowImageFormatsNV (internal MR 6315). * Refer to "`shader calls`" in the <> chapter refers to them as such, rather than "`invocation repacks`" (internal MR 6316). * Make some flink:vkAcquireImageANDROID parameters `optional` in XML (internal MR 6325). New Extensions * apiext:VK_KHR_calibrated_timestamps * apiext:VK_KHR_vertex_attribute_divisor --- .gitlab-ci.yml | 4 +- ChangeLog.adoc | 38 ++++- Makefile | 2 +- appendices/VK_EXT_calibrated_timestamps.adoc | 7 + ...VK_EXT_pipeline_library_group_handles.adoc | 2 +- appendices/VK_KHR_calibrated_timestamps.adoc | 31 ++++ appendices/VK_KHR_draw_indirect_count.adoc | 4 +- appendices/VK_KHR_external_memory.adoc | 2 +- .../VK_KHR_vertex_attribute_divisor.adoc | 31 ++++ .../VK_NV_inherited_viewport_scissor.adoc | 2 +- appendices/glossary.adoc | 29 +++- appendices/memorymodel.adoc | 6 +- .../generation.adoc | 2 +- chapters/VK_NV_optical_flow/optical_flow.adoc | 4 +- chapters/capabilities.adoc | 24 ++- .../commonvalidity/blit_image_common.adoc | 9 ++ .../commonvalidity/copy_image_common.adoc | 9 ++ .../commonvalidity/draw_instance_common.adoc | 33 ++++ chapters/drawing.adoc | 9 ++ chapters/executiongraphs.adoc | 13 +- chapters/features.adoc | 31 ++-- chapters/fxvertex.adoc | 99 +++++++----- chapters/interfaces.adoc | 16 +- chapters/limits.adoc | 52 ++++++- chapters/pipelines.adoc | 118 +++++++------- chapters/primsrast.adoc | 4 +- chapters/queries.adoc | 70 +++++---- chapters/raytracing.adoc | 37 ++--- chapters/raytraversal.adoc | 69 +++++---- chapters/shaders.adoc | 13 +- chapters/synchronization.adoc | 67 +++++--- chapters/textures.adoc | 4 +- config/CI/codespell-allowed | 5 +- config/CI/codespellrc | 2 +- .../VK_KHR_vertex_attribute_divisor.adoc | 145 ++++++++++++++++++ proposals/VK_KHR_video_queue.adoc | 2 +- proposals/VK_QCOM_image_processing.adoc | 6 +- scripts/extensionmetadocgenerator.py | 2 + scripts/htmldiff/htmldiff.pl | 2 +- scripts/spec_tools/macro_checker_file.py | 2 +- scripts/spec_tools/main.py | 2 +- scripts/syncgenerator.py | 2 +- style/revisions.adoc | 3 + style/writing.adoc | 11 ++ xml/vk.xml | 101 +++++++----- 45 files changed, 810 insertions(+), 316 deletions(-) create mode 100644 appendices/VK_KHR_calibrated_timestamps.adoc create mode 100644 appendices/VK_KHR_vertex_attribute_divisor.adoc create mode 100644 chapters/commonvalidity/draw_instance_common.adoc create mode 100644 proposals/VK_KHR_vertex_attribute_divisor.adoc diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index fa926ee645..963d067abd 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -144,7 +144,7 @@ hpp-generate: # Regenerate Rust bindings (Ash crate) ash-generate: - image: khronosgroup/docker-images@sha256:9e0beda7d46d7a2f72526bac80b4ccb7a860486b09f00d513e24c6676fdd8de1 + image: khronosgroup/docker-images@sha256:cf554c9cf5d0322e022f0be32efad9bff44ada4b32653bfdc8033cba22972fa2 stage: build needs: - spec-generate # For the full include/ directory @@ -230,7 +230,7 @@ hpp-compile: # Build-test Rust bindings (Ash crate) ash-compile: - image: khronosgroup/docker-images@sha256:9e0beda7d46d7a2f72526bac80b4ccb7a860486b09f00d513e24c6676fdd8de1 + image: khronosgroup/docker-images@sha256:cf554c9cf5d0322e022f0be32efad9bff44ada4b32653bfdc8033cba22972fa2 stage: test needs: - ash-generate diff --git a/ChangeLog.adoc b/ChangeLog.adoc index f4c501a4de..6aef5e5d7f 100644 --- a/ChangeLog.adoc +++ b/ChangeLog.adoc @@ -14,6 +14,40 @@ appears frequently in the change log. ----------------------------------------------------- +Change log for December 8, 2023 Vulkan 1.3.273 spec update: + +Github Issues + + * Add missing `bitwidth` attribute for + elink:VkPhysicalDeviceSchedulingControlsFlagBitsARM (public issue 2277). + +Internal Issues + + * Use the new <> term to + refer to trace ray instructions, instead of the too-specific + code:OpTraceRayKHR (internal issue 3284). + * Improve description of <>, refer to it from each ftext:vkCreate*Pipelines command, and + add style guide language to follow this pattern for future multiple + creation commands (internal issue 3707). + * Add common blit image and copy image VU that copying an image with the + same subresource must: be ename:VK_IMAGE_LAYOUT_GENERAL or + ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR (internal MR 6143). + * Markup improvements and correct use of normative must: for + flink:vkGetPhysicalDeviceOpticalFlowImageFormatsNV (internal MR 6315). + * Refer to "`shader calls`" in the <> chapter + refers to them as such, rather than "`invocation repacks`" (internal MR + 6316). + * Make some flink:vkAcquireImageANDROID parameters `optional` in XML + (internal MR 6325). + +New Extensions + + * apiext:VK_KHR_calibrated_timestamps + * apiext:VK_KHR_vertex_attribute_divisor + +----------------------------------------------------- + Change log for December 1, 2023 Vulkan 1.3.272 spec update: Internal Issues @@ -355,7 +389,7 @@ Github Issues specifications (public issue 2193). * Explicitly state that VkDeviceOrHostAddressConstKHR is also ignored (public PR 2205). - * Fix parameter typo "`cordinates`" and correct markup (public PR 2206). + * Fix parameter typo "`coordinates`" and correct markup (public PR 2206). * Cleanup slink:VkGraphicspipelineCreateInfo VUs for code:PointSize in the context of apiext:VK_KHR_maintenance5 (public Vulkan-ValidationLayers issue 6382). @@ -3516,7 +3550,7 @@ Internal Issues: VU 06271 (internal issue 2917). * Use etext:VK_VERSION_m_n instead of etext:VK_API_VERSION_m_n in `` and `` XML tags for consistency with - other version / extension reqiurements. Note that there is a possibility + other version / extension requirements. Note that there is a possibility of this change affecting downstream consumers of the XML (internal issue 2896). * Add refpage cross-reference from slink:VkSwapchainKHR to diff --git a/Makefile b/Makefile index f98753ecf6..dfcb2d8f13 100644 --- a/Makefile +++ b/Makefile @@ -136,7 +136,7 @@ VERBOSE = # ADOCOPTS options for asciidoc->HTML5 output NOTEOPTS = -a editing-notes -a implementation-guide -PATCHVERSION = 272 +PATCHVERSION = 273 BASEOPTS = ifneq (,$(findstring VKSC_VERSION_1_0,$(VERSIONS))) diff --git a/appendices/VK_EXT_calibrated_timestamps.adoc b/appendices/VK_EXT_calibrated_timestamps.adoc index 4c2ea5e6a8..0a40f507ab 100644 --- a/appendices/VK_EXT_calibrated_timestamps.adoc +++ b/appendices/VK_EXT_calibrated_timestamps.adoc @@ -23,6 +23,13 @@ include::{generated}/meta/{refprefix}VK_EXT_calibrated_timestamps.adoc[] This extension provides an interface to query calibrated timestamps obtained quasi simultaneously from two time domains. +=== Promotion to `VK_KHR_calibrated_timestamps` + +All functionality in this extension is included in +`apiext:VK_KHR_calibrated_timestamps`, with the suffix changed to KHR. +The original enum names are still available as aliases of the KHR +functionality. + include::{generated}/interfaces/VK_EXT_calibrated_timestamps.adoc[] === Version History diff --git a/appendices/VK_EXT_pipeline_library_group_handles.adoc b/appendices/VK_EXT_pipeline_library_group_handles.adoc index 3dc9da0a9d..723a0d7fc8 100644 --- a/appendices/VK_EXT_pipeline_library_group_handles.adoc +++ b/appendices/VK_EXT_pipeline_library_group_handles.adoc @@ -24,7 +24,7 @@ include::{generated}/meta/{refprefix}VK_EXT_pipeline_library_group_handles.adoc[ When using pipeline libraries in ray tracing pipelines, a library might get linked into different pipelines in an incremental way. An application can have a strategy where a ray tracing pipeline is comprised -of N pipeline libraries and is later augumented by creating a new pipeline +of N pipeline libraries and is later augmented by creating a new pipeline with N + 1 libraries. Without this extension, all group handles must be re-queried as the group handle is tied to the pipeline, not the library. diff --git a/appendices/VK_KHR_calibrated_timestamps.adoc b/appendices/VK_KHR_calibrated_timestamps.adoc new file mode 100644 index 0000000000..f7f09f10ae --- /dev/null +++ b/appendices/VK_KHR_calibrated_timestamps.adoc @@ -0,0 +1,31 @@ +// Copyright 2018-2023 The Khronos Group Inc. +// +// SPDX-License-Identifier: CC-BY-4.0 + +include::{generated}/meta/{refprefix}VK_KHR_calibrated_timestamps.adoc[] + +=== Other Extension Metadata + +*Last Modified Date*:: + 2023-07-12 +*IP Status*:: + No known IP claims. +*Contributors*:: + - Matthaeus G. Chajdas, AMD + - Alan Harrison, AMD + - Derrick Owens, AMD + - Daniel Rakos, RasterGrid + - Faith Ekstrand, Intel + - Keith Packard, Valve + +=== Description + +This extension provides an interface to query calibrated timestamps obtained +quasi simultaneously from two time domains. + +include::{generated}/interfaces/VK_KHR_calibrated_timestamps.adoc[] + +=== Version History + + * Revision 1, 2023-07-12 (Daniel Rakos) + ** Initial draft. diff --git a/appendices/VK_KHR_draw_indirect_count.adoc b/appendices/VK_KHR_draw_indirect_count.adoc index 6ffe49d849..1f4a8691d9 100644 --- a/appendices/VK_KHR_draw_indirect_count.adoc +++ b/appendices/VK_KHR_draw_indirect_count.adoc @@ -20,7 +20,7 @@ include::{generated}/meta/{refprefix}VK_KHR_draw_indirect_count.adoc[] === Description -This extension is based off the `apiext:VK_AMD_draw_indirect_count` +This extension is based on the `apiext:VK_AMD_draw_indirect_count` extension. This extension allows an application to source the number of draws for indirect drawing calls from a buffer. @@ -45,4 +45,4 @@ include::{generated}/interfaces/VK_KHR_draw_indirect_count.adoc[] === Version History * Revision 1, 2017-08-25 (Piers Daniell) - ** Initial draft based off VK_AMD_draw_indirect_count + ** Initial draft based on VK_AMD_draw_indirect_count diff --git a/appendices/VK_KHR_external_memory.adoc b/appendices/VK_KHR_external_memory.adoc index 3b19ec9ad3..3e527a3fcd 100644 --- a/appendices/VK_KHR_external_memory.adoc +++ b/appendices/VK_KHR_external_memory.adoc @@ -228,7 +228,7 @@ transfer any information between the exporting and importing instances and APIs other than that required to share the data contained in the memory objects explicitly shared. As specific examples, data from previously freed memory objects that used -the same underlying physical memory, and data from memory obects using +the same underlying physical memory, and data from memory objects using adjacent physical memory must not be visible to applications importing an exported memory object. diff --git a/appendices/VK_KHR_vertex_attribute_divisor.adoc b/appendices/VK_KHR_vertex_attribute_divisor.adoc new file mode 100644 index 0000000000..69384bd570 --- /dev/null +++ b/appendices/VK_KHR_vertex_attribute_divisor.adoc @@ -0,0 +1,31 @@ +// Copyright 2017-2023 The Khronos Group Inc. +// +// SPDX-License-Identifier: CC-BY-4.0 + +include::{generated}/meta/{refprefix}VK_KHR_vertex_attribute_divisor.adoc[] + +=== Other Extension Metadata + +*Last Modified Date*:: + 2023-09-20 +*IP Status*:: + No known IP claims. +*Contributors*:: + - Shahbaz Youssefi, Google + - Contributors to `apiext:VK_EXT_vertex_attribute_divisor` + +=== Description + +This extension is based on the `apiext:VK_EXT_vertex_attribute_divisor` +extension. +The only difference is the new property pname:supportsNonZeroFirstInstance, +which indicates support for non-zero values in pname:firstInstance. +This allows the extension to be supported on implementations that have +traditionally only supported OpenGL ES. + +include::{generated}/interfaces/VK_KHR_vertex_attribute_divisor.adoc[] + +=== Version History + + * Revision 1, 2023-09-20 (Shahbaz Youssefi) + ** First Version, based on `apiext:VK_EXT_vertex_attribute_divisor` diff --git a/appendices/VK_NV_inherited_viewport_scissor.adoc b/appendices/VK_NV_inherited_viewport_scissor.adoc index 710a680f3c..066d9f4537 100644 --- a/appendices/VK_NV_inherited_viewport_scissor.adoc +++ b/appendices/VK_NV_inherited_viewport_scissor.adoc @@ -21,7 +21,7 @@ the dynamic viewport and scissor state from a primary command buffer, or a previous secondary command buffer executed within the same flink:vkCmdExecuteCommands call. It addresses a frequent scenario in applications that deal with window -resizing and want to improve utilization of re-usable secondary command +resizing and want to improve utilization of reusable secondary command buffers. The functionality is provided through slink:VkCommandBufferInheritanceViewportScissorInfoNV. diff --git a/appendices/glossary.adoc b/appendices/glossary.adoc index 15c1bce71a..46b3355104 100644 --- a/appendices/glossary.adoc +++ b/appendices/glossary.adoc @@ -1007,7 +1007,7 @@ Invocation Group:: ifdef::VK_KHR_ray_tracing_pipeline,VK_NV_ray_tracing[] Invocation Repack Instruction:: - A ray tracing shader call <> where the + A ray tracing <> where the implementation may: change the set of invocations that are executing. endif::VK_KHR_ray_tracing_pipeline,VK_NV_ray_tracing[] @@ -1329,14 +1329,31 @@ Pipeline Identifier:: endif::VKSC_VERSION_1_0[] ifdef::VK_KHR_ray_tracing_pipeline,VK_NV_ray_tracing[] +[[glossary-pipeline-trace-ray]] Pipeline Trace Ray Instruction:: A ray tracing instruction which traces a ray into an acceleration structure when using ray tracing pipelines. - One of -ifdef::VK_NV_ray_tracing[code:OpTraceNV,] -ifdef::VK_NV_ray_tracing_motion_blur[code:OpTraceRayMotionNV, code:OpTraceMotionNV,] -ifdef::VK_KHR_ray_tracing_pipeline[code:OpTraceRayKHR] - . + One of: + +ifdef::VK_NV_ray_tracing[] + * code:OpTraceNV +endif::VK_NV_ray_tracing[] +ifdef::VK_KHR_ray_tracing_pipeline[] + * code:OpTraceRayKHR +endif::VK_KHR_ray_tracing_pipeline[] +ifdef::VK_NV_ray_tracing_motion_blur[] + * code:OpTraceRayMotionNV +ifdef::VK_NV_ray_tracing[] + * code:OpTraceMotionNV +endif::VK_NV_ray_tracing[] +endif::VK_NV_ray_tracing_motion_blur[] +ifdef::VK_NV_ray_tracing_invocation_reorder[] + * code:OpHitObjectTraceRayNV +ifdef::VK_NV_ray_tracing_motion_blur[] + * code:OpHitObjectTraceRayMotionNV +endif::VK_NV_ray_tracing_motion_blur[] +endif::VK_NV_ray_tracing_invocation_reorder[] + endif::VK_KHR_ray_tracing_pipeline,VK_NV_ray_tracing[] pname:pNext Chain:: diff --git a/appendices/memorymodel.adoc b/appendices/memorymodel.adoc index 6666fa32b8..e4622eaa23 100644 --- a/appendices/memorymodel.adoc +++ b/appendices/memorymodel.adoc @@ -176,7 +176,7 @@ Shader-call-related is an equivalence relation on invocations defined as the symmetric and transitive closure of: * A is shader-call-related to B if A is created by an - <> instruction executed by B. + <> instruction executed by B. [[shader-call-order]] @@ -188,11 +188,11 @@ executed by invocations that are shader-call-related: * (Program order): If dynamic instance A is program-ordered before B, then A is shader-call-ordered before B. * (Shader call entry): If A is a dynamic instance of an - <> instruction and B is a dynamic + <> instruction and B is a dynamic instance executed by an invocation that is created by A, then A is shader-call-ordered before B. * (Shader call exit): If A is a dynamic instance of an - <> instruction, B is the next + <> instruction, B is the next dynamic instance executed by the same invocation, and C is a dynamic instance executed by an invocation that is created by A, then C is shader-call-ordered before B. diff --git a/chapters/VK_NV_device_generated_commands/generation.adoc b/chapters/VK_NV_device_generated_commands/generation.adoc index dcc238eccb..ebba816bfa 100644 --- a/chapters/VK_NV_device_generated_commands/generation.adoc +++ b/chapters/VK_NV_device_generated_commands/generation.adoc @@ -469,7 +469,7 @@ include::{generated}/validity/protos/vkCmdPreprocessGeneratedCommandsNV.adoc[] ifdef::VK_NV_device_generated_commands_compute[] The bound descriptor sets and push constants that will be used with indirect -command generation for the compute piplines must: already be specified at +command generation for the compute pipelines must: already be specified at the time of preprocessing commands with flink:vkCmdPreprocessGeneratedCommandsNV. They must: not change until the execution of indirect commands is submitted diff --git a/chapters/VK_NV_optical_flow/optical_flow.adoc b/chapters/VK_NV_optical_flow/optical_flow.adoc index e81e984e07..3578714fc8 100644 --- a/chapters/VK_NV_optical_flow/optical_flow.adoc +++ b/chapters/VK_NV_optical_flow/optical_flow.adoc @@ -55,16 +55,18 @@ properties supported, at most pname:pFormatCount values will be written to pname:pImageFormatProperties, and ename:VK_INCOMPLETE will be returned instead of ename:VK_SUCCESS, to indicate that not all the available values were returned. + Before creating an image to be used as a optical flow frame, obtain the supported image creation parameters by querying with flink:vkGetPhysicalDeviceFormatProperties2 and flink:vkGetPhysicalDeviceImageFormatProperties2 using one of the reported formats and adding slink:VkOpticalFlowImageFormatInfoNV to the pname:pNext chain of slink:VkPhysicalDeviceImageFormatInfo2. + When querying the parameters with flink:vkGetPhysicalDeviceImageFormatProperties2 for images used for optical flow operations, the slink:VkOpticalFlowImageFormatInfoNV::pname:usage field -should contain one or more of the bits defined in +must: contain one or more of the bits defined in elink:VkOpticalFlowUsageFlagBitsNV. include::{generated}/validity/protos/vkGetPhysicalDeviceOpticalFlowImageFormatsNV.adoc[] diff --git a/chapters/capabilities.adoc b/chapters/capabilities.adoc index 490c0bca9d..019c773bea 100644 --- a/chapters/capabilities.adoc +++ b/chapters/capabilities.adoc @@ -19,9 +19,9 @@ endif::VK_VERSION_1_1,VK_KHR_external_semaphore_capabilities[] ifdef::VK_VERSION_1_1,VK_KHR_external_fence_capabilities[] * <> endif::VK_VERSION_1_1,VK_KHR_external_fence_capabilities[] -ifdef::VK_EXT_calibrated_timestamps[] +ifdef::VK_KHR_calibrated_timestamps,VK_EXT_calibrated_timestamps[] * <> -endif::VK_EXT_calibrated_timestamps[] +endif::VK_KHR_calibrated_timestamps,VK_EXT_calibrated_timestamps[] [[capabilities-image]] @@ -1756,25 +1756,33 @@ zero or more elink:VkExternalFenceFeatureFlagBits. endif::VK_VERSION_1_1,VK_KHR_external_fence_capabilities[] -ifdef::VK_EXT_calibrated_timestamps[] +ifdef::VK_KHR_calibrated_timestamps,VK_EXT_calibrated_timestamps[] [[features-timestamp-calibration]] == Timestamp Calibration Capabilities -[open,refpage='vkGetPhysicalDeviceCalibrateableTimeDomainsEXT',desc='Query calibrateable time domains',type='protos'] +[open,refpage='vkGetPhysicalDeviceCalibrateableTimeDomainsKHR',desc='Query calibrateable time domains',type='protos',alias='vkGetPhysicalDeviceCalibrateableTimeDomainsEXT'] -- -:refpage: vkGetPhysicalDeviceCalibrateableTimeDomainsEXT +:refpage: vkGetPhysicalDeviceCalibrateableTimeDomainsKHR To query the set of time domains for which a physical device supports timestamp calibration, call: +ifdef::VK_KHR_calibrated_timestamps[] +include::{generated}/api/protos/vkGetPhysicalDeviceCalibrateableTimeDomainsKHR.adoc[] +endif::VK_KHR_calibrated_timestamps[] + +ifdef::VK_KHR_calibrated_timestamps+VK_EXT_calibrated_timestamps[or the equivalent command] + +ifdef::VK_EXT_calibrated_timestamps[] include::{generated}/api/protos/vkGetPhysicalDeviceCalibrateableTimeDomainsEXT.adoc[] +endif::VK_EXT_calibrated_timestamps[] * pname:physicalDevice is the physical device from which to query the set of calibrateable time domains. * pname:pTimeDomainCount is a pointer to an integer related to the number of calibrateable time domains available or queried, as described below. * pname:pTimeDomains is either `NULL` or a pointer to an array of - elink:VkTimeDomainEXT values, indicating the supported calibrateable + elink:VkTimeDomainKHR values, indicating the supported calibrateable time domains. If pname:pTimeDomains is `NULL`, then the number of calibrateable time @@ -1792,9 +1800,9 @@ time domains were returned. include::{chapters}/commonvalidity/no_dynamic_allocations_common.adoc[] -include::{generated}/validity/protos/vkGetPhysicalDeviceCalibrateableTimeDomainsEXT.adoc[] +include::{generated}/validity/protos/vkGetPhysicalDeviceCalibrateableTimeDomainsKHR.adoc[] -- -endif::VK_EXT_calibrated_timestamps[] +endif::VK_KHR_calibrated_timestamps,VK_EXT_calibrated_timestamps[] ifdef::VK_KHR_object_refresh[] include::{chapters}/VK_KHR_object_refresh/capabilities.adoc[] diff --git a/chapters/commonvalidity/blit_image_common.adoc b/chapters/commonvalidity/blit_image_common.adoc index e2dae1a36c..20fc420a6f 100644 --- a/chapters/commonvalidity/blit_image_common.adoc +++ b/chapters/commonvalidity/blit_image_common.adoc @@ -43,6 +43,15 @@ ifdef::VK_KHR_shared_presentable_image[] pname:srcImageLayout must: be ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR, ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL or ename:VK_IMAGE_LAYOUT_GENERAL +endif::VK_KHR_shared_presentable_image[] + * [[VUID-{refpage}-srcImage-09459]] + If pname:srcImage and pname:dstImage are the same, and an elements of + pname:pRegions contains the pname:srcSubresource and + pname:dstSubresource with matching pname:mipLevel and overlapping array + layers, then the pname:srcImageLayout and pname:dstImageLayout must: be + ename:VK_IMAGE_LAYOUT_GENERAL +ifdef::VK_KHR_shared_presentable_image[] + or ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR endif::VK_KHR_shared_presentable_image[] * [[VUID-{refpage}-dstImage-02000]] The <> of diff --git a/chapters/commonvalidity/copy_image_common.adoc b/chapters/commonvalidity/copy_image_common.adoc index 4baf459d68..c94d010dc8 100644 --- a/chapters/commonvalidity/copy_image_common.adoc +++ b/chapters/commonvalidity/copy_image_common.adoc @@ -24,6 +24,15 @@ ifdef::VK_KHR_shared_presentable_image[] endif::VK_KHR_shared_presentable_image[] ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL, or ename:VK_IMAGE_LAYOUT_GENERAL + * [[VUID-{refpage}-srcImage-09460]] + If pname:srcImage and pname:dstImage are the same, and any elements of + pname:pRegions contains the pname:srcSubresource and + pname:dstSubresource with matching pname:mipLevel and overlapping array + layers, then the pname:srcImageLayout and pname:dstImageLayout must: be + ename:VK_IMAGE_LAYOUT_GENERAL +ifdef::VK_KHR_shared_presentable_image[] + or ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR +endif::VK_KHR_shared_presentable_image[] ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[] * [[VUID-{refpage}-dstImage-01996]] The <> of diff --git a/chapters/commonvalidity/draw_instance_common.adoc b/chapters/commonvalidity/draw_instance_common.adoc new file mode 100644 index 0000000000..338c3d203b --- /dev/null +++ b/chapters/commonvalidity/draw_instance_common.adoc @@ -0,0 +1,33 @@ +// Copyright 2019-2023 The Khronos Group Inc. +// +// SPDX-License-Identifier: CC-BY-4.0 + +// Common Valid Usage +// Common to all drawing commands that have a firstInstance parameter. For +// indirect commands, these VUs pertain to VkDrawIndirectCommand. + +ifdef::VK_KHR_vertex_attribute_divisor[] + * [[VUID-{refpage}-pNext-09461]] + If the bound graphics pipeline state was created with + slink:VkPipelineVertexInputDivisorStateCreateInfoKHR in the pname:pNext + chain of slink:VkGraphicsPipelineCreateInfo::pname:pVertexInputState, + any member of + slink:VkPipelineVertexInputDivisorStateCreateInfoKHR::pname:pVertexBindingDivisors + has a value other than `1` in pname:divisor, and + slink:VkPhysicalDeviceVertexAttributeDivisorPropertiesKHR::pname:supportsNonZeroFirstInstance + is ename:VK_FALSE, then pname:firstInstance must: be `0` + * [[VUID-{refpage}-None-09462]] + If +ifdef::VK_EXT_shader_object[] + <> are used for drawing or +endif::VK_EXT_shader_object[] + the bound graphics pipeline state was created with the + ename:VK_DYNAMIC_STATE_VERTEX_INPUT_EXT dynamic state enabled, any + member of the pname:pVertexBindingDescriptions parameter to the + flink:vkCmdSetVertexInputEXT call that sets this dynamic state has a + value other than `1` in pname:divisor, and + slink:VkPhysicalDeviceVertexAttributeDivisorPropertiesKHR::pname:supportsNonZeroFirstInstance + is ename:VK_FALSE, then pname:firstInstance must: be `0` +endif::VK_KHR_vertex_attribute_divisor[] + +// Common Valid Usage diff --git a/chapters/drawing.adoc b/chapters/drawing.adoc index 414b13fa98..d6d2ca728f 100644 --- a/chapters/drawing.adoc +++ b/chapters/drawing.adoc @@ -971,6 +971,7 @@ The assembled primitives execute the bound graphics pipeline. include::{chapters}/commonvalidity/draw_common.adoc[] include::{chapters}/commonvalidity/draw_dispatch_nonindirect_common.adoc[] include::{chapters}/commonvalidity/draw_vertex_binding.adoc[] +include::{chapters}/commonvalidity/draw_instance_common.adoc[] **** include::{generated}/validity/protos/vkCmdDraw.adoc[] @@ -1029,6 +1030,7 @@ include::{chapters}/commonvalidity/draw_common.adoc[] include::{chapters}/commonvalidity/draw_dispatch_nonindirect_common.adoc[] include::{chapters}/commonvalidity/draw_vertex_binding.adoc[] include::{chapters}/commonvalidity/draw_indexed_common.adoc[] +include::{chapters}/commonvalidity/draw_instance_common.adoc[] include::{chapters}/commonvalidity/draw_index_binding.adoc[] **** @@ -1068,6 +1070,7 @@ pname:firstInstance and sequentially for each instance. include::{chapters}/commonvalidity/draw_common.adoc[] include::{chapters}/commonvalidity/draw_dispatch_nonindirect_common.adoc[] include::{chapters}/commonvalidity/draw_vertex_binding.adoc[] +include::{chapters}/commonvalidity/draw_instance_common.adoc[] * [[VUID-vkCmdDrawMultiEXT-None-04933]] The <> feature must: be enabled * [[VUID-vkCmdDrawMultiEXT-drawCount-04934]] @@ -1125,6 +1128,7 @@ include::{chapters}/commonvalidity/draw_common.adoc[] include::{chapters}/commonvalidity/draw_dispatch_nonindirect_common.adoc[] include::{chapters}/commonvalidity/draw_vertex_binding.adoc[] include::{chapters}/commonvalidity/draw_indexed_common.adoc[] +include::{chapters}/commonvalidity/draw_instance_common.adoc[] include::{chapters}/commonvalidity/draw_index_binding.adoc[] * [[VUID-vkCmdDrawMultiIndexedEXT-None-04937]] The <> feature must: be enabled @@ -1230,6 +1234,8 @@ include::{generated}/validity/protos/vkCmdDrawIndirect.adoc[] [open,refpage='VkDrawIndirectCommand',desc='Structure specifying a indirect drawing command',type='structs',xrefs='vkCmdDrawIndirect'] -- +:refpage: VkDrawIndirectCommand + The sname:VkDrawIndirectCommand structure is defined as: include::{generated}/api/structs/VkDrawIndirectCommand.adoc[] @@ -1244,6 +1250,7 @@ similarly named parameters of flink:vkCmdDraw. .Valid Usage **** +include::{chapters}/commonvalidity/draw_instance_common.adoc[] * [[VUID-VkDrawIndirectCommand-None-00500]] For a given vertex buffer binding, any attribute data fetched must: be entirely contained within the corresponding vertex buffer binding, as @@ -1405,6 +1412,7 @@ the similarly named parameters of flink:vkCmdDrawIndexed. .Valid Usage **** +include::{chapters}/commonvalidity/draw_instance_common.adoc[] include::{chapters}/commonvalidity/draw_index_binding.adoc[] * [[VUID-VkDrawIndexedIndirectCommand-None-00552]] For a given vertex buffer binding, any attribute data fetched must: be @@ -1568,6 +1576,7 @@ The effective pname:firstVertex is zero. **** include::{chapters}/commonvalidity/draw_common.adoc[] include::{chapters}/commonvalidity/draw_vertex_binding.adoc[] +include::{chapters}/commonvalidity/draw_instance_common.adoc[] * [[VUID-vkCmdDrawIndirectByteCountEXT-transformFeedback-02287]] sname:VkPhysicalDeviceTransformFeedbackFeaturesEXT::pname:transformFeedback must: be enabled diff --git a/chapters/executiongraphs.adoc b/chapters/executiongraphs.adoc index 197070905e..8f11ba93ec 100644 --- a/chapters/executiongraphs.adoc +++ b/chapters/executiongraphs.adoc @@ -40,17 +40,8 @@ include::{generated}/api/protos/vkCreateExecutionGraphPipelinesAMDX.adoc[] * pname:pPipelines is a pointer to an array of slink:VkPipeline handles in which the resulting execution graph pipeline objects are returned. -The implementation will create a pipeline in each element of -pname:pPipelines from the corresponding element of pname:pCreateInfos. -If creation of any pipeline fails, that pipeline will be set to -dlink:VK_NULL_HANDLE. - -ifdef::VK_VERSION_1_3,VK_EXT_pipeline_creation_cache_control[] -If creation fails for a pipeline create info with a -slink:VkExecutionGraphPipelineCreateInfoAMDX::pname:flags value that -included ename:VK_PIPELINE_CREATE_EARLY_RETURN_ON_FAILURE_BIT, all pipelines -at a greater index all automatically fail. -endif::VK_VERSION_1_3,VK_EXT_pipeline_creation_cache_control[] +Pipelines are created and returned as described for <>. .Valid Usage **** diff --git a/chapters/features.adoc b/chapters/features.adoc index ebeb3c9c54..03df0222d1 100644 --- a/chapters/features.adoc +++ b/chapters/features.adoc @@ -2243,13 +2243,19 @@ include::{generated}/validity/structs/VkPhysicalDeviceCopyMemoryIndirectFeatures -- endif::VK_NV_copy_memory_indirect[] -ifdef::VK_EXT_vertex_attribute_divisor[] -[open,refpage='VkPhysicalDeviceVertexAttributeDivisorFeaturesEXT',desc='Structure describing if fetching of vertex attribute may be repeated for instanced rendering',type='structs'] +ifdef::VK_KHR_vertex_attribute_divisor,VK_EXT_vertex_attribute_divisor[] +[open,refpage='VkPhysicalDeviceVertexAttributeDivisorFeaturesKHR',desc='Structure describing if fetching of vertex attribute may be repeated for instanced rendering',type='structs',alias='VkPhysicalDeviceVertexAttributeDivisorFeaturesEXT'] -- -The sname:VkPhysicalDeviceVertexAttributeDivisorFeaturesEXT structure is +The sname:VkPhysicalDeviceVertexAttributeDivisorFeaturesKHR structure is defined as: +include::{generated}/api/structs/VkPhysicalDeviceVertexAttributeDivisorFeaturesKHR.adoc[] + +ifdef::VK_EXT_vertex_attribute_divisor[] +or the equivalent + include::{generated}/api/structs/VkPhysicalDeviceVertexAttributeDivisorFeaturesEXT.adoc[] +endif::VK_EXT_vertex_attribute_divisor[] This structure describes the following features: @@ -2258,18 +2264,18 @@ This structure describes the following features: structure. * [[features-vertexAttributeInstanceRateDivisor]] pname:vertexAttributeInstanceRateDivisor specifies whether vertex - attribute fetching may be repeated in case of instanced rendering. + attribute fetching may be repeated in the case of instanced rendering. * [[features-vertexAttributeInstanceRateZeroDivisor]] pname:vertexAttributeInstanceRateZeroDivisor specifies whether a zero - value for sname:VkVertexInputBindingDivisorDescriptionEXT::pname:divisor + value for slink:VkVertexInputBindingDivisorDescriptionEXT::pname:divisor is supported. -:refpage: VkPhysicalDeviceVertexAttributeDivisorFeaturesEXT +:refpage: VkPhysicalDeviceVertexAttributeDivisorFeaturesKHR include::{chapters}/features.adoc[tag=features] -include::{generated}/validity/structs/VkPhysicalDeviceVertexAttributeDivisorFeaturesEXT.adoc[] +include::{generated}/validity/structs/VkPhysicalDeviceVertexAttributeDivisorFeaturesKHR.adoc[] -- -endif::VK_EXT_vertex_attribute_divisor[] +endif::VK_KHR_vertex_attribute_divisor,VK_EXT_vertex_attribute_divisor[] ifdef::VK_EXT_astc_decode_mode[] [open,refpage='VkPhysicalDeviceASTCDecodeFeaturesEXT',desc='Structure describing ASTC decode mode features',type='structs'] @@ -7562,11 +7568,14 @@ ifdef::VK_EXT_conditional_rendering[] * <>, if the `apiext:VK_EXT_conditional_rendering` extension is supported. endif::VK_EXT_conditional_rendering[] -ifdef::VK_EXT_vertex_attribute_divisor[] +ifdef::VK_KHR_vertex_attribute_divisor,VK_EXT_vertex_attribute_divisor[] * <>, if the - `apiext:VK_EXT_vertex_attribute_divisor` extension is supported. + pname:vertexAttributeInstanceRateDivisor>>, if +ifdef::VK_EXT_vertex_attribute_divisor[] + the `apiext:VK_EXT_vertex_attribute_divisor` extension or endif::VK_EXT_vertex_attribute_divisor[] + the `apiext:VK_KHR_vertex_attribute_divisor` extension is supported. +endif::VK_KHR_vertex_attribute_divisor,VK_EXT_vertex_attribute_divisor[] ifdef::VK_EXT_fragment_density_map[] * <>, if the `apiext:VK_EXT_fragment_density_map` extension is supported. diff --git a/chapters/fxvertex.adoc b/chapters/fxvertex.adoc index 639509a2fd..9a986b986a 100644 --- a/chapters/fxvertex.adoc +++ b/chapters/fxvertex.adoc @@ -267,11 +267,11 @@ include::{generated}/api/structs/VkPipelineVertexInputStateCreateInfo.adoc[] * pname:vertexBindingDescriptionCount is the number of vertex binding descriptions provided in pname:pVertexBindingDescriptions. * pname:pVertexBindingDescriptions is a pointer to an array of - sname:VkVertexInputBindingDescription structures. + slink:VkVertexInputBindingDescription structures. * pname:vertexAttributeDescriptionCount is the number of vertex attribute descriptions provided in pname:pVertexAttributeDescriptions. * pname:pVertexAttributeDescriptions is a pointer to an array of - sname:VkVertexInputAttributeDescription structures. + slink:VkVertexInputAttributeDescription structures. .Valid Usage **** @@ -284,7 +284,7 @@ include::{generated}/api/structs/VkPipelineVertexInputStateCreateInfo.adoc[] * [[VUID-VkPipelineVertexInputStateCreateInfo-binding-00615]] For every pname:binding specified by each element of pname:pVertexAttributeDescriptions, a - sname:VkVertexInputBindingDescription must: exist in + slink:VkVertexInputBindingDescription must: exist in pname:pVertexBindingDescriptions with the same value of pname:binding * [[VUID-VkPipelineVertexInputStateCreateInfo-pVertexBindingDescriptions-00616]] All elements of pname:pVertexBindingDescriptions must: describe distinct @@ -406,11 +406,11 @@ include::{generated}/api/protos/vkCmdSetVertexInputEXT.adoc[] * pname:vertexBindingDescriptionCount is the number of vertex binding descriptions provided in pname:pVertexBindingDescriptions. * pname:pVertexBindingDescriptions is a pointer to an array of - sname:VkVertexInputBindingDescription2EXT structures. + slink:VkVertexInputBindingDescription2EXT structures. * pname:vertexAttributeDescriptionCount is the number of vertex attribute descriptions provided in pname:pVertexAttributeDescriptions. * pname:pVertexAttributeDescriptions is a pointer to an array of - sname:VkVertexInputAttributeDescription2EXT structures. + slink:VkVertexInputAttributeDescription2EXT structures. This command sets the vertex input attribute and vertex input binding descriptions state for subsequent drawing commands @@ -470,7 +470,7 @@ endif::VK_EXT_shader_object[] * [[VUID-vkCmdSetVertexInputEXT-binding-04793]] For every pname:binding specified by each element of pname:pVertexAttributeDescriptions, a - sname:VkVertexInputBindingDescription2EXT must: exist in + slink:VkVertexInputBindingDescription2EXT must: exist in pname:pVertexBindingDescriptions with the same value of pname:binding * [[VUID-vkCmdSetVertexInputEXT-pVertexBindingDescriptions-04794]] All elements of pname:pVertexBindingDescriptions must: describe distinct @@ -498,7 +498,7 @@ include::{generated}/api/structs/VkVertexInputBindingDescription2EXT.adoc[] * pname:inputRate is a elink:VkVertexInputRate value specifying whether vertex attribute addressing is a function of the vertex index or of the instance index. -ifdef::VK_EXT_vertex_attribute_divisor[] +ifdef::VK_EXT_vertex_attribute_divisor,VK_KHR_vertex_attribute_divisor[] * pname:divisor is the number of successive instances that will use the same value of the vertex attribute when instanced rendering is enabled. This member can: be set to a value other than `1` if the @@ -515,10 +515,10 @@ ifdef::VK_EXT_vertex_attribute_divisor[] pname:vertexAttributeInstanceRateZeroDivisor>> feature is enabled. In this case, the same vertex attribute will be applied to all instances. -endif::VK_EXT_vertex_attribute_divisor[] -ifndef::VK_EXT_vertex_attribute_divisor[] +endif::VK_EXT_vertex_attribute_divisor,VK_KHR_vertex_attribute_divisor[] +ifndef::VK_EXT_vertex_attribute_divisor,VK_KHR_vertex_attribute_divisor[] * pname:divisor must: be set to `1` -endif::VK_EXT_vertex_attribute_divisor[] +endif::VK_EXT_vertex_attribute_divisor,VK_KHR_vertex_attribute_divisor[] .Valid Usage **** @@ -727,7 +727,7 @@ ename:VK_DYNAMIC_STATE_VERTEX_INPUT_BINDING_STRIDE set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] Otherwise, strides are specified by the -sname:VkVertexInputBindingDescription::pname:stride values used to create +slink:VkVertexInputBindingDescription::pname:stride values used to create the currently active pipeline. ifdef::VK_EXT_vertex_input_dynamic_state,VK_EXT_shader_object[] @@ -805,23 +805,29 @@ include::{generated}/validity/protos/vkCmdBindVertexBuffers2.adoc[] endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] -ifdef::VK_EXT_vertex_attribute_divisor[] +ifdef::VK_EXT_vertex_attribute_divisor,VK_KHR_vertex_attribute_divisor[] [[fxvertex-attribute_divisor]] == Vertex Attribute Divisor in Instanced Rendering -[open,refpage='VkPipelineVertexInputDivisorStateCreateInfoEXT',desc='Structure specifying vertex attributes assignment during instanced rendering',type='structs'] +[open,refpage='VkPipelineVertexInputDivisorStateCreateInfoKHR',desc='Structure specifying vertex attributes assignment during instanced rendering',type='structs',alias='VkPipelineVertexInputDivisorStateCreateInfoEXT'] -- If the <> feature is enabled and the pname:pNext chain of slink:VkPipelineVertexInputStateCreateInfo includes a -sname:VkPipelineVertexInputDivisorStateCreateInfoEXT structure, then that +sname:VkPipelineVertexInputDivisorStateCreateInfoKHR structure, then that structure controls how vertex attributes are assigned to an instance when instanced rendering is enabled. -The sname:VkPipelineVertexInputDivisorStateCreateInfoEXT structure is +The sname:VkPipelineVertexInputDivisorStateCreateInfoKHR structure is defined as: +include::{generated}/api/structs/VkPipelineVertexInputDivisorStateCreateInfoKHR.adoc[] + +ifdef::VK_EXT_vertex_attribute_divisor[] +or the equivalent + include::{generated}/api/structs/VkPipelineVertexInputDivisorStateCreateInfoEXT.adoc[] +endif::VK_EXT_vertex_attribute_divisor[] * pname:sType is a elink:VkStructureType value identifying this structure. * pname:pNext is `NULL` or a pointer to a structure extending this @@ -829,19 +835,25 @@ include::{generated}/api/structs/VkPipelineVertexInputDivisorStateCreateInfoEXT. * pname:vertexBindingDivisorCount is the number of elements in the pname:pVertexBindingDivisors array. * pname:pVertexBindingDivisors is a pointer to an array of - sname:VkVertexInputBindingDivisorDescriptionEXT structures specifying + slink:VkVertexInputBindingDivisorDescriptionKHR structures specifying the divisor value for each binding. -include::{generated}/validity/structs/VkPipelineVertexInputDivisorStateCreateInfoEXT.adoc[] +include::{generated}/validity/structs/VkPipelineVertexInputDivisorStateCreateInfoKHR.adoc[] -- -[open,refpage='VkVertexInputBindingDivisorDescriptionEXT',desc='Structure specifying a divisor used in instanced rendering',type='structs'] +[open,refpage='VkVertexInputBindingDivisorDescriptionKHR',desc='Structure specifying a divisor used in instanced rendering',type='structs',alias='VkVertexInputBindingDivisorDescriptionEXT'] -- The individual divisor values per binding are specified using the -sname:VkVertexInputBindingDivisorDescriptionEXT structure which is defined +sname:VkVertexInputBindingDivisorDescriptionKHR structure which is defined as: +include::{generated}/api/structs/VkVertexInputBindingDivisorDescriptionKHR.adoc[] + +ifdef::VK_EXT_vertex_attribute_divisor[] +or the equivalent + include::{generated}/api/structs/VkVertexInputBindingDivisorDescriptionEXT.adoc[] +endif::VK_EXT_vertex_attribute_divisor[] * pname:binding is the binding number for which the divisor is specified. * pname:divisor is the number of successive instances that will use the @@ -851,7 +863,7 @@ include::{generated}/api/structs/VkVertexInputBindingDivisorDescriptionEXT.adoc[ attribute. The maximum value of pname:divisor is implementation-dependent and can be queried using - sname:VkPhysicalDeviceVertexAttributeDivisorPropertiesEXT::pname:maxVertexAttribDivisor. + slink:VkPhysicalDeviceVertexAttributeDivisorPropertiesKHR::pname:maxVertexAttribDivisor. A value of `0` can: be used for the divisor if the <> feature is enabled. @@ -863,27 +875,27 @@ then the divisor has a logical default value of 1. .Valid Usage **** - * [[VUID-VkVertexInputBindingDivisorDescriptionEXT-binding-01869]] + * [[VUID-VkVertexInputBindingDivisorDescriptionKHR-binding-01869]] pname:binding must: be less than - sname:VkPhysicalDeviceLimits::pname:maxVertexInputBindings - * [[VUID-VkVertexInputBindingDivisorDescriptionEXT-vertexAttributeInstanceRateZeroDivisor-02228]] + slink:VkPhysicalDeviceLimits::pname:maxVertexInputBindings + * [[VUID-VkVertexInputBindingDivisorDescriptionKHR-vertexAttributeInstanceRateZeroDivisor-02228]] If the pname:vertexAttributeInstanceRateZeroDivisor feature is not enabled, pname:divisor must: not be `0` - * [[VUID-VkVertexInputBindingDivisorDescriptionEXT-vertexAttributeInstanceRateDivisor-02229]] + * [[VUID-VkVertexInputBindingDivisorDescriptionKHR-vertexAttributeInstanceRateDivisor-02229]] If the pname:vertexAttributeInstanceRateDivisor feature is not enabled, pname:divisor must: be `1` - * [[VUID-VkVertexInputBindingDivisorDescriptionEXT-divisor-01870]] + * [[VUID-VkVertexInputBindingDivisorDescriptionKHR-divisor-01870]] pname:divisor must: be a value between `0` and - sname:VkPhysicalDeviceVertexAttributeDivisorPropertiesEXT::pname:maxVertexAttribDivisor, + slink:VkPhysicalDeviceVertexAttributeDivisorPropertiesKHR::pname:maxVertexAttribDivisor, inclusive - * [[VUID-VkVertexInputBindingDivisorDescriptionEXT-inputRate-01871]] + * [[VUID-VkVertexInputBindingDivisorDescriptionKHR-inputRate-01871]] slink:VkVertexInputBindingDescription::pname:inputRate must: be of type ename:VK_VERTEX_INPUT_RATE_INSTANCE for this pname:binding **** -include::{generated}/validity/structs/VkVertexInputBindingDivisorDescriptionEXT.adoc[] +include::{generated}/validity/structs/VkVertexInputBindingDivisorDescriptionKHR.adoc[] -- -endif::VK_EXT_vertex_attribute_divisor[] +endif::VK_EXT_vertex_attribute_divisor,VK_KHR_vertex_attribute_divisor[] [[fxvertex-input-address-calculation]] @@ -893,11 +905,11 @@ code:instanceIndex is calculated as follows: * Let code:attribDesc be the member of slink:VkPipelineVertexInputStateCreateInfo::pname:pVertexAttributeDescriptions - with sname:VkVertexInputAttributeDescription::pname:location equal to + with slink:VkVertexInputAttributeDescription::pname:location equal to the vertex input attribute number. * Let code:bindingDesc be the member of slink:VkPipelineVertexInputStateCreateInfo::pname:pVertexBindingDescriptions - with sname:VkVertexInputAttributeDescription::pname:binding equal to + with slink:VkVertexInputAttributeDescription::pname:binding equal to code:attribDesc.binding. * Let code:vertexIndex be the index of the vertex within the draw (a value between pname:firstVertex and pname:firstVertex+pname:vertexCount for @@ -909,12 +921,19 @@ code:instanceIndex is calculated as follows: buffers specified during fname:vkCmdBindVertexBuffers ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[or fname:vkCmdBindVertexBuffers2] with pname:pOffsets. -ifdef::VK_EXT_vertex_attribute_divisor[] +ifdef::VK_EXT_vertex_attribute_divisor,VK_KHR_vertex_attribute_divisor[] * Let code:divisor be the member of - slink:VkPipelineVertexInputDivisorStateCreateInfoEXT::pname:pVertexBindingDivisors - with sname:VkVertexInputBindingDivisorDescriptionEXT::pname:binding + slink:VkPipelineVertexInputDivisorStateCreateInfoKHR::pname:pVertexBindingDivisors + with slink:VkVertexInputBindingDivisorDescriptionKHR::pname:binding equal to code:attribDesc.binding. -endif::VK_EXT_vertex_attribute_divisor[] +ifdef::VK_EXT_vertex_input_dynamic_state,VK_EXT_shader_object[] + If the vertex binding state is dynamically set, instead let code:divisor + be the member of the pname:pVertexBindingDescriptions parameter to the + flink:vkCmdSetVertexInputEXT call with + slink:VkVertexInputBindingDescription2EXT::pname:binding equal to + code:attribDesc.binding. +endif::VK_EXT_vertex_input_dynamic_state,VK_EXT_shader_object[] +endif::VK_EXT_vertex_attribute_divisor,VK_KHR_vertex_attribute_divisor[] [source,c] ---- @@ -923,15 +942,15 @@ bufferBindingAddress = buffer[binding].baseAddress + offset[binding]; if (bindingDesc.inputRate == VK_VERTEX_INPUT_RATE_VERTEX) effectiveVertexOffset = vertexIndex * bindingDesc.stride; else -ifndef::VK_EXT_vertex_attribute_divisor[] +ifndef::VK_EXT_vertex_attribute_divisor,VK_KHR_vertex_attribute_divisor[] effectiveVertexOffset = instanceIndex * bindingDesc.stride; -endif::VK_EXT_vertex_attribute_divisor[] -ifdef::VK_EXT_vertex_attribute_divisor[] +endif::VK_EXT_vertex_attribute_divisor,VK_KHR_vertex_attribute_divisor[] +ifdef::VK_EXT_vertex_attribute_divisor,VK_KHR_vertex_attribute_divisor[] if (divisor == 0) effectiveVertexOffset = firstInstance * bindingDesc.stride; else effectiveVertexOffset = (firstInstance + ((instanceIndex - firstInstance) / divisor)) * bindingDesc.stride; -endif::VK_EXT_vertex_attribute_divisor[] +endif::VK_EXT_vertex_attribute_divisor,VK_KHR_vertex_attribute_divisor[] attribAddress = bufferBindingAddress + effectiveVertexOffset + attribDesc.offset; ---- @@ -941,7 +960,7 @@ attribAddress = bufferBindingAddress + effectiveVertexOffset + attribDesc.offset === Vertex Input Extraction For each attribute, raw data is extracted starting at `attribAddress` and is -converted from the sname:VkVertexInputAttributeDescription's pname:format to +converted from the slink:VkVertexInputAttributeDescription's pname:format to either floating-point, unsigned integer, or signed integer based on the <> of pname:format. The numeric type of pname:format must: match the numeric type of the input diff --git a/chapters/interfaces.adoc b/chapters/interfaces.adoc index 3c2ca1126b..3c45b51af8 100644 --- a/chapters/interfaces.adoc +++ b/chapters/interfaces.adoc @@ -3901,7 +3901,8 @@ A variable decorated with the code:RayTmaxKHR decoration will contain the parametric [eq]#t~max~# value of the ray being processed. The value is independent of the space in which the ray origin and direction exist. -The value is initialized to the parameter passed into code:OpTraceRayKHR. +The value is initialized to the parameter passed into the +<> instruction. + The [eq]#t~max~# value changes throughout the lifetime of the ray that produced the intersection. @@ -3914,8 +3915,8 @@ primitive intersected so far or the initial value. The value can change in the intersection shader after calling code:OpReportIntersectionKHR if the corresponding any-hit shader does not ignore the intersection. -In a miss shader, the value is identical to the parameter passed into -code:OpTraceRayKHR. +In a miss shader, the value is identical to the parameter passed into the +<> instruction. .Valid Usage **** @@ -3943,7 +3944,8 @@ A variable decorated with the code:RayTminKHR decoration will contain the parametric [eq]#t~min~# value of the ray being processed. The value is independent of the space in which the ray origin and direction exist. -The value is the parameter passed into code:OpTraceRayKHR. +The value is the parameter passed into the <> instruction. + The [eq]#t~min~# value remains constant for the duration of the ray query. @@ -5110,7 +5112,8 @@ code:WorldRayDirectionKHR:: A variable decorated with the code:WorldRayDirectionKHR decoration will specify the direction of the ray being processed, in world space. -The value is the parameter passed into code:OpTraceRayKHR. +The value is the parameter passed into the <> instruction. .Valid Usage **** @@ -5136,7 +5139,8 @@ code:WorldRayOriginKHR:: A variable decorated with the code:WorldRayOriginKHR decoration will specify the origin of the ray being processed, in world space. -The value is the parameter passed into code:OpTraceRayKHR. +The value is the parameter passed into the <> instruction. .Valid Usage **** diff --git a/chapters/limits.adoc b/chapters/limits.adoc index 6fedb235b3..06d50928d4 100644 --- a/chapters/limits.adoc +++ b/chapters/limits.adoc @@ -1475,9 +1475,15 @@ include::{generated}/api/structs/VkPhysicalDeviceVertexAttributeDivisorPropertie * pname:sType is a elink:VkStructureType value identifying this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. - * [[limits-maxVertexAttribDivisor]] pname:maxVertexAttribDivisor is the - maximum value of the number of instances that will repeat the value of - vertex attribute data when instanced rendering is enabled. + +// Must have preceding whitespace +ifdef::VK_KHR_vertex_attribute_divisor[:anchor-prefix: extension-] +ifndef::VK_KHR_vertex_attribute_divisor[:anchor-prefix:] +// tag::VK_KHR_vertex_attribute_divisor-properties[] + * [[{anchor-prefix}limits-maxVertexAttribDivisor]] + pname:maxVertexAttribDivisor is the maximum value of the number of + instances that will repeat the value of vertex attribute data when + instanced rendering is enabled. :refpage: VkPhysicalDeviceVertexAttributeDivisorPropertiesEXT include::{chapters}/limits.adoc[tag=limits_desc] @@ -1486,6 +1492,34 @@ include::{generated}/validity/structs/VkPhysicalDeviceVertexAttributeDivisorProp -- endif::VK_EXT_vertex_attribute_divisor[] +ifdef::VK_KHR_vertex_attribute_divisor[] +[open,refpage='VkPhysicalDeviceVertexAttributeDivisorPropertiesKHR',desc='Structure describing max value of vertex attribute divisor that can be supported by an implementation',type='structs'] +-- +The sname:VkPhysicalDeviceVertexAttributeDivisorPropertiesKHR structure is +defined as: + +include::{generated}/api/structs/VkPhysicalDeviceVertexAttributeDivisorPropertiesKHR.adoc[] + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * [[limits-maxVertexAttribDivisor]] pname:maxVertexAttribDivisor is the + maximum value of the number of instances that will repeat the value of + vertex attribute data when instanced rendering is enabled. + * [[limits-supportsNonZeroFirstInstance]] + pname:supportsNonZeroFirstInstance specifies whether a non-zero value + for the pname:firstInstance parameter of <> + is supported when + slink:VkVertexInputBindingDivisorDescriptionKHR::pname:divisor is not + `1`. + +:refpage: VkPhysicalDeviceVertexAttributeDivisorPropertiesKHR +include::{chapters}/limits.adoc[tag=limits_desc] + +include::{generated}/validity/structs/VkPhysicalDeviceVertexAttributeDivisorPropertiesKHR.adoc[] +-- +endif::VK_KHR_vertex_attribute_divisor[] + ifdef::VK_VERSION_1_2,VK_EXT_sampler_filter_minmax[] [open,refpage='VkPhysicalDeviceSamplerFilterMinmaxProperties',desc='Structure describing sampler filter minmax limits that can be supported by an implementation',type='structs',alias='VkPhysicalDeviceSamplerFilterMinmaxPropertiesEXT'] -- @@ -4636,9 +4670,11 @@ endif::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] ifdef::VK_VERSION_1_3[] | code:uint32_t | pname:maxInlineUniformTotalSize |`<>` endif::VK_VERSION_1_3[] -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_EXT_vertex_attribute_divisor,VK_KHR_vertex_attribute_divisor[] +| code:uint32_t | pname:maxVertexAttribDivisor | +ifdef::VK_KHR_vertex_attribute_divisor[`apiext:VK_KHR_vertex_attribute_divisor`] +ifndef::VK_KHR_vertex_attribute_divisor[`apiext:VK_EXT_vertex_attribute_divisor`] +endif::VK_EXT_vertex_attribute_divisor,VK_KHR_vertex_attribute_divisor[] ifdef::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` @@ -5094,9 +5130,9 @@ endif::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] ifdef::VK_VERSION_1_3[] | pname:maxInlineUniformTotalSize | - | 256 | min endif::VK_VERSION_1_3[] -ifdef::VK_EXT_vertex_attribute_divisor[] +ifdef::VK_EXT_vertex_attribute_divisor,VK_KHR_vertex_attribute_divisor[] | pname:maxVertexAttribDivisor | - | 2^16^-1 | min -endif::VK_EXT_vertex_attribute_divisor[] +endif::VK_EXT_vertex_attribute_divisor,VK_KHR_vertex_attribute_divisor[] ifdef::VK_NV_mesh_shader[] | slink:VkPhysicalDeviceMeshShaderPropertiesNV::pname:maxDrawMeshTasksCount | - | 2^16^-1 | min | slink:VkPhysicalDeviceMeshShaderPropertiesNV::pname:maxTaskWorkGroupInvocations | - | 32 | min diff --git a/chapters/pipelines.adoc b/chapters/pipelines.adoc index b5b1c1e2e6..1f9ed6aaf0 100644 --- a/chapters/pipelines.adoc +++ b/chapters/pipelines.adoc @@ -131,6 +131,54 @@ include::{generated}/api/handles/VkPipeline.adoc[] -- +[[pipelines-multiple]] +== Multiple Pipeline Creation + +Multiple pipelines can: be created in a single call by commands such as +ifdef::VK_AMDX_shader_enqueue[flink:vkCreateExecutionGraphPipelinesAMDX,] +ifdef::VK_KHR_ray_tracing_pipeline[flink:vkCreateRayTracingPipelinesKHR,] +ifdef::VK_NV_ray_tracing[flink:vkCreateRayTracingPipelinesNV,] +flink:vkCreateComputePipelines, and flink:vkCreateGraphicsPipelines. + +The creation commands are passed an array pname:pCreateInfos of +sname:Vk*PipelineCreateInfo structures specifying parameters of each +pipeline to be created, and return a corresponding array of handles in +pname:pPipelines. +Each element index _i_ of pname:pPipelines is created based on the +corresponding element _i_ of pname:pCreateInfos. + +Applications can: group together similar pipelines to be created in a single +call, and implementations are encouraged to look for reuse opportunities +when creating a group. + +When attempting to create many pipelines in a single command, it is possible +that creation may: fail for a subset of them. +In this case, the corresponding elements of pname:pPipelines will be set to +dlink:VK_NULL_HANDLE. +If creation fails for a pipeline despite valid arguments (for example, due +to out of memory errors), the elink:VkResult code returned by the pipeline +creation command will indicate why. +The implementation will attempt to create all pipelines, and only return +dlink:VK_NULL_HANDLE values for those that actually failed. + +ifdef::VK_VERSION_1_3,VK_EXT_pipeline_creation_cache_control[] +If creation fails for a pipeline that has the +ename:VK_PIPELINE_CREATE_EARLY_RETURN_ON_FAILURE_BIT set in its +sname:Vk*PipelineCreateInfo, pipelines at an index in the pname:pPipelines +array greater than or equal to that of the failing pipeline will be set to +dlink:VK_NULL_HANDLE. +endif::VK_VERSION_1_3,VK_EXT_pipeline_creation_cache_control[] + +If creation fails for multiple pipelines, the returned elink:VkResult must: +be the return value of any one of the pipelines which did not succeed. +An application can: reliably clean up from a failed call by iterating over +the pname:pPipelines array and destroying every element that is not +dlink:VK_NULL_HANDLE. + +If the entire command fails and no pipelines are created, all elements of +pname:pPipelines will be set to dlink:VK_NULL_HANDLE. + + [[pipelines-compute]] == Compute Pipelines @@ -182,16 +230,9 @@ endif::VKSC_VERSION_1_0[] <> chapter. * pname:pPipelines is a pointer to an array of slink:VkPipeline handles in which the resulting compute pipeline objects are returned. -ifdef::editing-notes[] -+ -[NOTE] -.editing-note -==== -TODO (Jon) - Should we say something like "`the i'th element of the -pname:pPipelines array is created based on the corresponding element of the -pname:pCreateInfos array`"? Also for flink:vkCreateGraphicsPipelines below. -==== -endif::editing-notes[] + +Pipelines are created and returned as described for <>. ifdef::VKSC_VERSION_1_0[] If a pipeline creation fails due to: @@ -1267,6 +1308,9 @@ slink:VkPipelineShaderStageCreateInfo structures for each of the desired active shader stages, as well as creation information for all relevant fixed-function stages, and a pipeline layout. +Pipelines are created and returned as described for <>. + ifdef::VKSC_VERSION_1_0[] If a pipeline creation fails due to: @@ -1480,7 +1524,6 @@ The parameters pname:basePipelineHandle and pname:basePipelineIndex are described in more detail in <>. - ifdef::VK_NV_glsl_shader[] If any shader stage fails to compile, ifdef::VK_EXT_debug_report[] @@ -4593,10 +4636,10 @@ ifdef::VK_KHR_ray_tracing_pipeline[] consisting entirely of zeros. * ename:VK_PIPELINE_CREATE_2_RAY_TRACING_SKIP_TRIANGLES_BIT_KHR specifies that triangle primitives will be skipped during traversal using - code:OpTraceRayKHR. + <> instructions. * ename:VK_PIPELINE_CREATE_2_RAY_TRACING_SKIP_AABBS_BIT_KHR specifies that AABB primitives will be skipped during traversal using - code:OpTraceRayKHR. + <> instructions. * ename:VK_PIPELINE_CREATE_2_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR specifies that the shader group handles can: be saved and reused on a subsequent run (e.g. for trace capture and replay). @@ -4835,10 +4878,10 @@ ifdef::VK_KHR_ray_tracing_pipeline[] consisting entirely of zeros. * ename:VK_PIPELINE_CREATE_RAY_TRACING_SKIP_TRIANGLES_BIT_KHR specifies that triangle primitives will be skipped during traversal using - code:OpTraceRayKHR. + <> instructions. * ename:VK_PIPELINE_CREATE_RAY_TRACING_SKIP_AABBS_BIT_KHR specifies that AABB primitives will be skipped during traversal using - code:OpTraceRayKHR. + <> instructions. * ename:VK_PIPELINE_CREATE_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR specifies that the shader group handles can: be saved and reused on a subsequent run (e.g. for trace capture and replay). @@ -5804,6 +5847,9 @@ endif::VKSC_VERSION_1_0[] * pname:pPipelines is a pointer to an array in which the resulting ray tracing pipeline objects are returned. +Pipelines are created and returned as described for <>. + ifdef::VKSC_VERSION_1_0[] If a pipeline creation fails due to: @@ -5885,6 +5931,9 @@ when slink:VkPhysicalDeviceRayTracingPipelineFeaturesKHR::pname:rayTracingPipelineShaderGroupHandleCaptureReplay is enabled. +Pipelines are created and returned as described for <>. + ifdef::VKSC_VERSION_1_0[] If a pipeline creation fails due to: @@ -6910,43 +6959,6 @@ include::{generated}/validity/protos/vkDestroyPipeline.adoc[] -- -[[pipelines-multiple]] -== Multiple Pipeline Creation - -Multiple pipelines can: be created simultaneously by passing an array of -slink:VkGraphicsPipelineCreateInfo, -ifdef::VK_KHR_ray_tracing_pipeline[slink:VkRayTracingPipelineCreateInfoKHR,] -ifdef::VK_NV_ray_tracing[slink:VkRayTracingPipelineCreateInfoNV,] -or slink:VkComputePipelineCreateInfo structures into the -flink:vkCreateGraphicsPipelines, -ifdef::VK_KHR_ray_tracing_pipeline[flink:vkCreateRayTracingPipelinesKHR,] -ifdef::VK_NV_ray_tracing[flink:vkCreateRayTracingPipelinesNV,] -and flink:vkCreateComputePipelines commands, respectively. -Applications can: group together similar pipelines to be created in a single -call, and implementations are encouraged to look for reuse opportunities -within a group-create. - -When an application attempts to create many pipelines in a single command, -it is possible that some subset may: fail creation. -In that case, the corresponding entries in the pname:pPipelines output array -will be filled with dlink:VK_NULL_HANDLE values. -If any pipeline fails creation despite valid arguments (for example, due to -out of memory errors), the elink:VkResult code returned by -ftext:vkCreate*Pipelines will indicate why. -The implementation will attempt to create all pipelines, and only return -dlink:VK_NULL_HANDLE values for those that actually failed. - -ifdef::VK_VERSION_1_3,VK_EXT_pipeline_creation_cache_control[] -If creation fails for a pipeline that had -ename:VK_PIPELINE_CREATE_EARLY_RETURN_ON_FAILURE_BIT set, pipelines at an -index in the pname:pPipelines array greater than or equal to that of the -failing pipeline must: be set to dlink:VK_NULL_HANDLE. -endif::VK_VERSION_1_3,VK_EXT_pipeline_creation_cache_control[] - -If multiple pipelines fail to be created, the elink:VkResult must: be the -return value of any of the pipelines which did not return ename:VK_SUCCESS. - - [[pipelines-pipeline-derivatives]] == Pipeline Derivatives @@ -7510,7 +7522,7 @@ stored with each entry, or for future extensibility. ==== Because the pipeline cache index is keyed by pipeline identifier, applications and offline compilers must ensure that there are no pipelines -with identical pipeline indentifiers in the same pipeline cache. +with identical pipeline identifiers in the same pipeline cache. ==== Unlike most structures declared by the Vulkan API, all fields of this diff --git a/chapters/primsrast.adoc b/chapters/primsrast.adoc index 1a4146afdf..f51283c9fe 100644 --- a/chapters/primsrast.adoc +++ b/chapters/primsrast.adoc @@ -55,14 +55,14 @@ ifdef::VK_EXT_depth_clip_enable[] If the pipeline is not created with slink:VkPipelineRasterizationDepthClipStateCreateInfoEXT present then enabling depth clamp will also disable clipping primitives to the z - planes of the frustrum as described in <>. Otherwise depth clipping is controlled by the state set in slink:VkPipelineRasterizationDepthClipStateCreateInfoEXT. endif::VK_EXT_depth_clip_enable[] ifndef::VK_EXT_depth_clip_enable[] Enabling depth clamp will also disable clipping primitives to the z - planes of the frustrum as described in <>. endif::VK_EXT_depth_clip_enable[] * pname:rasterizerDiscardEnable controls whether primitives are discarded diff --git a/chapters/queries.adoc b/chapters/queries.adoc index 3c370e4422..8230f09bb7 100644 --- a/chapters/queries.adoc +++ b/chapters/queries.adoc @@ -1783,15 +1783,21 @@ Any timestamp write that <> another timestamp write in the same submission must: not have a lower value unless its value overflows the maximum supported integer bit width of the query. -ifdef::VK_EXT_calibrated_timestamps[] -If `apiext:VK_EXT_calibrated_timestamps` is enabled, this extends to -timestamp writes across all submissions on the same logical device: any -timestamp write that <> another must: not have a lower value unless its value -overflows the maximum supported integer bit width of the query. +ifdef::VK_KHR_calibrated_timestamps,VK_EXT_calibrated_timestamps[] +If +ifdef::VK_KHR_calibrated_timestamps[`apiext:VK_KHR_calibrated_timestamps`] +ifdef::VK_KHR_calibrated_timestamps+VK_EXT_calibrated_timestamps[or] +ifdef::VK_EXT_calibrated_timestamps[`apiext:VK_EXT_calibrated_timestamps`] +is enabled, this extends to timestamp writes across all submissions on the +same logical device: any timestamp write that +<> another must: not +have a lower value unless its value overflows the maximum supported integer +bit width of the query. Timestamps written by this command must: be in the -ename:VK_TIME_DOMAIN_DEVICE_EXT <>. -endif::VK_EXT_calibrated_timestamps[] +ifdef::VK_KHR_calibrated_timestamps[ename:VK_TIME_DOMAIN_DEVICE_KHR] +ifndef::VK_KHR_calibrated_timestamps[ename:VK_TIME_DOMAIN_DEVICE_EXT] +<>. +endif::VK_KHR_calibrated_timestamps,VK_EXT_calibrated_timestamps[] If an overflow occurs, the timestamp value must: wrap back to zero. [NOTE] @@ -1802,13 +1808,16 @@ are guaranteed to not decrease. For example, subtracting an older timestamp from a newer one to determine the execution time of a sequence of commands is only a reliable measurement if the two timestamp writes were performed in the same -ifdef::VK_EXT_calibrated_timestamps[] +ifdef::VK_KHR_calibrated_timestamps,VK_EXT_calibrated_timestamps[] submission, or if the writes were performed on the same logical device and -`apiext:VK_EXT_calibrated_timestamps` is enabled. -endif::VK_EXT_calibrated_timestamps[] -ifndef::VK_EXT_calibrated_timestamps[] +ifdef::VK_KHR_calibrated_timestamps[`apiext:VK_KHR_calibrated_timestamps`] +ifdef::VK_KHR_calibrated_timestamps+VK_EXT_calibrated_timestamps[or] +ifdef::VK_EXT_calibrated_timestamps[`apiext:VK_EXT_calibrated_timestamps`] +is enabled. +endif::VK_KHR_calibrated_timestamps,VK_EXT_calibrated_timestamps[] +ifndef::VK_KHR_calibrated_timestamps,VK_EXT_calibrated_timestamps[] submission. -endif::VK_EXT_calibrated_timestamps[] +endif::VK_KHR_calibrated_timestamps,VK_EXT_calibrated_timestamps[] ==== ifdef::VK_VERSION_1_1,VK_KHR_multiview[] @@ -1914,15 +1923,21 @@ Any timestamp write that <> another timestamp write in the same submission must: not have a lower value unless its value overflows the maximum supported integer bit width of the query. -ifdef::VK_EXT_calibrated_timestamps[] -If `apiext:VK_EXT_calibrated_timestamps` is enabled, this extends to -timestamp writes across all submissions on the same logical device: any -timestamp write that <> another must: not have a lower value unless its value -overflows the maximum supported integer bit width of the query. +ifdef::VK_KHR_calibrated_timestamps,VK_EXT_calibrated_timestamps[] +If +ifdef::VK_KHR_calibrated_timestamps[`apiext:VK_KHR_calibrated_timestamps`] +ifdef::VK_KHR_calibrated_timestamps+VK_EXT_calibrated_timestamps[or] +ifdef::VK_EXT_calibrated_timestamps[`apiext:VK_EXT_calibrated_timestamps`] +is enabled, this extends to timestamp writes across all submissions on the +same logical device: any timestamp write that +<> another must: not +have a lower value unless its value overflows the maximum supported integer +bit width of the query. Timestamps written by this command must: be in the -ename:VK_TIME_DOMAIN_DEVICE_EXT <>. -endif::VK_EXT_calibrated_timestamps[] +ifdef::VK_KHR_calibrated_timestamps[ename:VK_TIME_DOMAIN_DEVICE_KHR] +ifndef::VK_KHR_calibrated_timestamps[ename:VK_TIME_DOMAIN_DEVICE_EXT] +<>. +endif::VK_KHR_calibrated_timestamps,VK_EXT_calibrated_timestamps[] If an overflow occurs, the timestamp value must: wrap back to zero. [NOTE] @@ -1933,13 +1948,16 @@ are guaranteed to not decrease. For example, subtracting an older timestamp from a newer one to determine the execution time of a sequence of commands is only a reliable measurement if the two timestamp writes were performed in the same -ifdef::VK_EXT_calibrated_timestamps[] +ifdef::VK_KHR_calibrated_timestamps,VK_EXT_calibrated_timestamps[] submission, or if the writes were performed on the same logical device and -`apiext:VK_EXT_calibrated_timestamps` is enabled. -endif::VK_EXT_calibrated_timestamps[] -ifndef::VK_EXT_calibrated_timestamps[] +ifdef::VK_KHR_calibrated_timestamps[`apiext:VK_KHR_calibrated_timestamps`] +ifdef::VK_KHR_calibrated_timestamps+VK_EXT_calibrated_timestamps[or] +ifdef::VK_EXT_calibrated_timestamps[`apiext:VK_EXT_calibrated_timestamps`] +is enabled. +endif::VK_KHR_calibrated_timestamps,VK_EXT_calibrated_timestamps[] +ifndef::VK_KHR_calibrated_timestamps,VK_EXT_calibrated_timestamps[] submission. -endif::VK_EXT_calibrated_timestamps[] +endif::VK_KHR_calibrated_timestamps,VK_EXT_calibrated_timestamps[] ==== diff --git a/chapters/raytracing.adoc b/chapters/raytracing.adoc index c69ff0a724..e0e8613e80 100644 --- a/chapters/raytracing.adoc +++ b/chapters/raytracing.adoc @@ -16,12 +16,10 @@ image::{images}/ray_tracing_execution.svg[align="center",title="Ray tracing pipe Interaction between the different shader stages in the ray tracing pipeline **** -Within the ray tracing pipeline, code:OpTraceRayKHR -ifdef::VK_NV_ray_tracing_motion_blur[] -or code:OpTraceRayMotionNV -endif::VK_NV_ray_tracing_motion_blur[] -can: be called to perform a <> that invokes the -various ray tracing shader stages during its execution. +Within the ray tracing pipeline, a <> instruction can: be called to perform a <> that invokes the various ray tracing shader stages during its +execution. The relationship between the ray tracing pipeline object and the geometries present in the acceleration structure traversed is passed into the ray tracing command in a slink:VkBuffer object known as a _shader binding @@ -99,9 +97,8 @@ which may recurse (e.g. code:OpExecuteCallableKHR) but there is an upper bound determined by the <>. [[ray-tracing-repack]] -An _invocation repack instruction_ is a ray tracing shader call instruction -where the implementation may: change the set of invocations that are -executing. +An _invocation repack instruction_ is a ray tracing instruction where the +implementation may: change the set of invocations that are executing. When a repack instruction is encountered, the invocation is suspended and a new invocation begins and executes the instruction. After executing the repack instruction (which may: result in other ray @@ -124,8 +121,8 @@ invocation repack instructions. ifdef::VK_VERSION_1_1[] ifdef::VK_VERSION_1_2,VK_KHR_vulkan_memory_model[] -The invocations that are executing before an invocation repack instruction, -after the instruction, or are created by the instruction, are +The invocations that are executing before a shader call instruction, after +the instruction, or are created by the instruction, are <>. endif::VK_VERSION_1_2,VK_KHR_vulkan_memory_model[] @@ -195,8 +192,8 @@ ifndef::VK_KHR_ray_tracing_pipeline[code:Device or code:QueueFamily] storage classes are <> and no application availability and visibility operations are required. - * memory operations within a single invocation before and after the - invocation repack instruction are ordered by + * memory operations within a single invocation before and after the shader + call instruction are ordered by <> and do not require explicit synchronization. endif::VK_VERSION_1_2,VK_KHR_vulkan_memory_model[] @@ -772,12 +769,8 @@ calls made in the shaders. See Section 8.19 (Ray Tracing Functions) of the OpenGL Shading Language Specification for more details. In SPIR-V, these correspond to the code:SBTOffset and code:SBTStride -parameters to the -ifdef::VK_NV_ray_tracing[code:OpTraceRayNV] -ifdef::VK_NV_ray_tracing+VK_KHR_ray_tracing_pipeline[ or ] -ifdef::VK_KHR_ray_tracing_pipeline[code:OpTraceRayKHR] -ifdef::VK_NV_ray_tracing_motion_blur[ or code:OpTraceRayMotionNV] -instruction. +parameters to the <> +instructions. The result of this computation is then added to ifdef::VK_KHR_ray_tracing_pipeline[] @@ -844,11 +837,7 @@ calls made in the shaders. See Section 8.19 (Ray Tracing Functions) of the OpenGL Shading Language Specification for more details. In SPIR-V, this corresponds to the code:MissIndex parameter to the -ifdef::VK_NV_ray_tracing[code:OpTraceRayNV] -ifdef::VK_NV_ray_tracing+VK_KHR_ray_tracing_pipeline[ or ] -ifdef::VK_KHR_ray_tracing_pipeline[code:OpTraceRayKHR] -ifdef::VK_NV_ray_tracing_motion_blur[ or code:OpTraceRayMotionNV] -instruction. +<> instructions. ifdef::VK_KHR_ray_tracing_pipeline[] For flink:vkCmdTraceRaysKHR, the complete rule to compute a miss shader diff --git a/chapters/raytraversal.adoc b/chapters/raytraversal.adoc index f6426c203a..17037ab02c 100644 --- a/chapters/raytraversal.adoc +++ b/chapters/raytraversal.adoc @@ -12,7 +12,7 @@ Ray traversal cannot be started by a Vulkan API command directly - a shader must execute ifdef::VK_KHR_ray_query[code:OpRayQueryProceedKHR] ifdef::VK_KHR_ray_query+VK_KHR_ray_tracing_pipeline[or] -ifdef::VK_KHR_ray_tracing_pipeline[code:OpTraceRayKHR] +ifdef::VK_KHR_ray_tracing_pipeline[a <> instruction] . ifdef::VK_KHR_ray_tracing_pipeline[] When the <> feature @@ -205,9 +205,9 @@ For triangle intersection candidates, the [eq]#b# and [eq]#c# <> on the triangle where the above condition is met are made available to future shading. ifdef::VK_KHR_ray_tracing_pipeline[] -If the ray was traced with code:OpTraceRayKHR, these values are available as -a vector of 2 32-bit floating point values in the code:HitAttributeKHR -storage class. +If the ray was traced with a <> instruction, these values are available as a vector of 2 32-bit +floating point values in the code:HitAttributeKHR storage class. endif::VK_KHR_ray_tracing_pipeline[] Once an intersection candidate is determined, it proceeds through the @@ -273,16 +273,18 @@ trace instruction, and the intersection is with a triangle primitive, the intersection is dropped, and no further processing of this intersection occurs. If ename:VK_PIPELINE_CREATE_RAY_TRACING_SKIP_TRIANGLES_BIT_KHR was included -in the pipeline, traversal with code:OpTraceRayKHR calls will all behave as -if code:SkipTrianglesKHR was included in its `Ray Flags` operand. +in the pipeline, traversal with <> instructions will all behave as if code:SkipTrianglesKHR was +included in their `Ray Flags` operand. If code:SkipAABBsKHR was included in the `Ray Flags` operand of the ray trace instruction, and the intersection is with an AABB primitive, the intersection is dropped, and no further processing of this intersection occurs. If ename:VK_PIPELINE_CREATE_RAY_TRACING_SKIP_AABBS_BIT_KHR was included in -the pipeline, traversal with code:OpTraceRayKHR calls will all behave as if -code:SkipAABBsKHR was included in its `Ray Flags` operand. +the pipeline, traversal with <> instructions will all behave as if code:SkipAABBsKHR was included in +their `Ray Flags` operand. === Ray Mask Culling @@ -351,11 +353,11 @@ of this. ==== ifdef::VK_KHR_ray_tracing_pipeline[] -If the ray was traced with code:OpTraceRayKHR, the code:HitKindKHR built-in -is set to code:HitKindFrontFacingTriangleKHR if the intersection is with -front-facing geometry, and code:HitKindBackFacingTriangleKHR if the -intersection is with back-facing geometry, for shader stages considering -this intersection. +If the ray was traced with a <> instruction, the code:HitKindKHR built-in is set to +code:HitKindFrontFacingTriangleKHR if the intersection is with front-facing +geometry, and code:HitKindBackFacingTriangleKHR if the intersection is with +back-facing geometry, for shader stages considering this intersection. endif::VK_KHR_ray_tracing_pipeline[] ifdef::VK_KHR_ray_query[] @@ -544,9 +546,10 @@ To avoid propagating false intersections the application should: verify the intersection candidate before reporting any hits. ifdef::VK_KHR_ray_tracing_pipeline[] -If the ray was traced with code:OpTraceRayKHR, an <> is invoked from the <> according -to the <> for the +If the ray was traced with a <> instruction, an <> is +invoked from the <> according to the +<> for the intersected geometry. If this shader calls code:OpReportIntersectionKHR, a new intersection candidate is generated as described @@ -581,9 +584,10 @@ code:OpRayQueryProceedKHR with the same ray query, or intersection can: be terminated with code:OpRayQueryTerminateKHR. endif::VK_KHR_ray_query[] ifdef::VK_KHR_ray_tracing_pipeline+VK_KHR_ray_query[] -Unlike rays traced with code:OpTraceRayKHR, candidates generated in this way -skip generated intersection candidate confirmation; applications should: -make this determination before generating the intersection. +Unlike rays traced with a <> instruction, candidates generated in this way skip generated +intersection candidate confirmation; applications should: make this +determination before generating the intersection. endif::VK_KHR_ray_tracing_pipeline+VK_KHR_ray_query[] This operation may: be executed multiple times for the same intersection @@ -604,9 +608,9 @@ For non-opaque intersection candidates, shader code is executed to determine whether a hit occurred or not. ifdef::VK_KHR_ray_tracing_pipeline[] -If the ray was traced with code:OpTraceRayKHR, an <> is invoked from the <> according to the -specified indexing. +If the ray was traced with a <> instruction, an <> is invoked from +the <> according to the specified indexing. If this shader calls code:OpIgnoreIntersectionKHR, the candidate is dropped and no further processing of the candidate occurs. If the <> identified is @@ -667,22 +671,25 @@ If a closest hit result was identified by <>, a closest hit has occurred, otherwise the final result is a miss. ifdef::VK_KHR_ray_tracing_pipeline[] -For rays traced with code:OpTraceRayKHR, if a closest hit result was -identified, a <> is invoked from -the <> according to the +For rays traced with <> +instructions which can: invoke a closest hit shader, if a closest hit result +was identified, a <> is invoked +from the <> according to the <> for the intersected geometry. -Control returns to the shader that executed code:OpTraceRayKHR once this +Control returns to the shader that executed the +<> instruction once this shader returns. This shader is skipped if either the ray flags included code:SkipClosestHitShaderKHR, or if the <> identified is ename:VK_SHADER_UNUSED_KHR. -For rays traced with code:OpTraceRayKHR where no hit result was identified, -the <> identified by the `Miss Index` parameter -of code:OpTraceRayKHR is invoked. -Control returns to the shader that executed code:OpTraceRayKHR once this -shader returns. +For rays traced with a <> +instruction where no hit result was identified, the <> identified by the `Miss Index` parameter of the instruction is +invoked. +Control returns to the shader that executed the pipeline trace ray +instruction once this shader returns. This shader is skipped if the miss shader identified is ename:VK_SHADER_UNUSED_KHR. endif::VK_KHR_ray_tracing_pipeline[] diff --git a/chapters/shaders.adoc b/chapters/shaders.adoc index 80087073a8..ad1fb2236a 100644 --- a/chapters/shaders.adoc +++ b/chapters/shaders.adoc @@ -2134,8 +2134,9 @@ ifdef::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] == Ray Generation Shaders A ray generation shader is similar to a compute shader. -Its main purpose is to execute ray tracing queries using code:OpTraceRayKHR -instructions and process the results. +Its main purpose is to execute ray tracing queries using +<> instructions (such as +code:OpTraceRayKHR) and process the results. [[shaders-ray-generation-execution]] @@ -2215,7 +2216,8 @@ point during traversal, unless the ray is forcibly terminated. Closest hit shaders have read-only access to the attributes generated by the corresponding intersection shader, and can: read or modify the ray payload. They also have access to a number of system-generated values. -Closest hit shaders can: call code:OpTraceRayKHR to recursively trace rays. +Closest hit shaders can: call <> instructions to recursively trace rays. [[shaders-closest-hit-execution]] @@ -2229,8 +2231,9 @@ intersection has been found and accepted. == Miss Shaders Miss shaders can: access the ray payload and can: trace new rays through the -code:OpTraceRayKHR instruction, but cannot: access attributes since they are -not associated with an intersection. +<> instructions, but +cannot: access attributes since they are not associated with an +intersection. [[shaders-miss-execution]] diff --git a/chapters/synchronization.adoc b/chapters/synchronization.adoc index 2ad024edb4..91bb2e6298 100644 --- a/chapters/synchronization.adoc +++ b/chapters/synchronization.adoc @@ -7606,13 +7606,13 @@ An event can: only be waited on by the same physical device that signaled it endif::VK_VERSION_1_1,VK_KHR_device_group[] -ifdef::VK_EXT_calibrated_timestamps[] +ifdef::VK_KHR_calibrated_timestamps,VK_EXT_calibrated_timestamps[] [[calibrated-timestamps]] == Calibrated Timestamps -[open,refpage='vkGetCalibratedTimestampsEXT',desc='Query calibrated timestamps',type='protos'] +[open,refpage='vkGetCalibratedTimestampsKHR',desc='Query calibrated timestamps',type='protos',alias='vkGetCalibratedTimestampsEXT'] -- -:refpage: vkGetCalibratedTimestampsEXT +:refpage: vkGetCalibratedTimestampsKHR In order to be able to correlate the time a particular operation took place at on timelines of different time domains (e.g. a device operation vs. a @@ -7621,12 +7621,20 @@ time domains. To query calibrated timestamps from a set of time domains, call: +ifdef::VK_KHR_calibrated_timestamps[] +include::{generated}/api/protos/vkGetCalibratedTimestampsKHR.adoc[] +endif::VK_KHR_calibrated_timestamps[] + +ifdef::VK_KHR_calibrated_timestamps+VK_EXT_calibrated_timestamps[or the equivalent command] + +ifdef::VK_EXT_calibrated_timestamps[] include::{generated}/api/protos/vkGetCalibratedTimestampsEXT.adoc[] +endif::VK_EXT_calibrated_timestamps[] * pname:device is the logical device used to perform the query. * pname:timestampCount is the number of timestamps to query. * pname:pTimestampInfos is a pointer to an array of pname:timestampCount - slink:VkCalibratedTimestampInfoEXT structures, describing the time + slink:VkCalibratedTimestampInfoKHR structures, describing the time domains the calibrated timestamps should be captured from. * pname:pTimestamps is a pointer to an array of pname:timestampCount 64-bit unsigned integer values in which the requested calibrated @@ -7639,7 +7647,7 @@ include::{generated}/api/protos/vkGetCalibratedTimestampsEXT.adoc[] .Note ==== The maximum deviation may: vary between calls to -fname:vkGetCalibratedTimestampsEXT even for the same set of time domains due +fname:vkGetCalibratedTimestampsKHR even for the same set of time domains due to implementation and platform specific reasons. It is the application's responsibility to assess whether the returned maximum deviation makes the timestamp values suitable for any particular @@ -7663,37 +7671,49 @@ timestamps on a regular basis. include::{chapters}/commonvalidity/no_dynamic_allocations_common.adoc[] -include::{generated}/validity/protos/vkGetCalibratedTimestampsEXT.adoc[] +include::{generated}/validity/protos/vkGetCalibratedTimestampsKHR.adoc[] -- -[open,refpage='VkCalibratedTimestampInfoEXT',desc='Structure specifying the input parameters of a calibrated timestamp query',type='structs'] +[open,refpage='VkCalibratedTimestampInfoKHR',desc='Structure specifying the input parameters of a calibrated timestamp query',type='structs',alias='VkCalibratedTimestampInfoEXT'] -- -The sname:VkCalibratedTimestampInfoEXT structure is defined as: +The sname:VkCalibratedTimestampInfoKHR structure is defined as: + +include::{generated}/api/structs/VkCalibratedTimestampInfoKHR.adoc[] + +ifdef::VK_EXT_calibrated_timestamps[] +or the equivalent include::{generated}/api/structs/VkCalibratedTimestampInfoEXT.adoc[] +endif::VK_EXT_calibrated_timestamps[] * pname:sType is a elink:VkStructureType value identifying this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. - * pname:timeDomain is a elink:VkTimeDomainEXT value specifying the time + * pname:timeDomain is a elink:VkTimeDomainKHR value specifying the time domain from which the calibrated timestamp value should be returned. .Valid Usage **** * [[VUID-VkCalibratedTimestampInfoEXT-timeDomain-02354]] - pname:timeDomain must: be one of the elink:VkTimeDomainEXT values - returned by flink:vkGetPhysicalDeviceCalibrateableTimeDomainsEXT + pname:timeDomain must: be one of the elink:VkTimeDomainKHR values + returned by flink:vkGetPhysicalDeviceCalibrateableTimeDomainsKHR **** -include::{generated}/validity/structs/VkCalibratedTimestampInfoEXT.adoc[] +include::{generated}/validity/structs/VkCalibratedTimestampInfoKHR.adoc[] -- -[open,refpage='VkTimeDomainEXT',desc='Supported time domains',type='enums'] +[open,refpage='VkTimeDomainKHR',desc='Supported time domains',type='enums',alias='VkTimeDomainEXT'] -- The set of supported time domains consists of: +include::{generated}/api/enums/VkTimeDomainKHR.adoc[] + +ifdef::VK_EXT_calibrated_timestamps[] +or the equivalent + include::{generated}/api/enums/VkTimeDomainEXT.adoc[] +endif::VK_EXT_calibrated_timestamps[] - * ename:VK_TIME_DOMAIN_DEVICE_EXT specifies the device time domain. + * ename:VK_TIME_DOMAIN_DEVICE_KHR specifies the device time domain. Timestamp values in this time domain use the same units and are comparable with device timestamp values captured using flink:vkCmdWriteTimestamp @@ -7703,7 +7723,7 @@ endif::VK_VERSION_1_3,VK_KHR_synchronization2[] and are defined to be incrementing according to the <> of the device. - * ename:VK_TIME_DOMAIN_CLOCK_MONOTONIC_EXT specifies the CLOCK_MONOTONIC + * ename:VK_TIME_DOMAIN_CLOCK_MONOTONIC_KHR specifies the CLOCK_MONOTONIC time domain available on POSIX platforms. Timestamp values in this time domain are in units of nanoseconds and are comparable with platform timestamp values captured using the POSIX @@ -7712,10 +7732,13 @@ endif::VK_VERSION_1_3,VK_KHR_synchronization2[] [NOTE] .Note ==== -An implementation supporting `apiext:VK_EXT_calibrated_timestamps` will use -the same time domain for all its slink:VkQueue so that timestamp values -reported for ename:VK_TIME_DOMAIN_DEVICE_EXT can be matched to any timestamp -captured through flink:vkCmdWriteTimestamp +An implementation supporting +ifdef::VK_KHR_calibrated_timestamps[`apiext:VK_KHR_calibrated_timestamps`] +ifdef::VK_KHR_calibrated_timestamps+VK_EXT_calibrated_timestamps[or] +ifdef::VK_EXT_calibrated_timestamps[`apiext:VK_EXT_calibrated_timestamps`] +will use the same time domain for all its slink:VkQueue so that timestamp +values reported for ename:VK_TIME_DOMAIN_DEVICE_KHR can be matched to any +timestamp captured through flink:vkCmdWriteTimestamp ifdef::VK_VERSION_1_3,VK_KHR_synchronization2[] or flink:vkCmdWriteTimestamp2 endif::VK_VERSION_1_3,VK_KHR_synchronization2[] @@ -7729,7 +7752,7 @@ clock_gettime(CLOCK_MONOTONIC, &tv); return tv.tv_nsec + tv.tv_sec*1000000000ull; ---- - * ename:VK_TIME_DOMAIN_CLOCK_MONOTONIC_RAW_EXT specifies the + * ename:VK_TIME_DOMAIN_CLOCK_MONOTONIC_RAW_KHR specifies the CLOCK_MONOTONIC_RAW time domain available on POSIX platforms. Timestamp values in this time domain are in units of nanoseconds and are comparable with platform timestamp values captured using the POSIX @@ -7742,7 +7765,7 @@ clock_gettime(CLOCK_MONOTONIC_RAW, &tv); return tv.tv_nsec + tv.tv_sec*1000000000ull; ---- - * ename:VK_TIME_DOMAIN_QUERY_PERFORMANCE_COUNTER_EXT specifies the + * ename:VK_TIME_DOMAIN_QUERY_PERFORMANCE_COUNTER_KHR specifies the performance counter (QPC) time domain available on Windows. Timestamp values in this time domain are in the same units as those provided by the Windows QueryPerformanceCounter API and are comparable @@ -7756,4 +7779,4 @@ QueryPerformanceCounter(&counter); return counter.QuadPart; ---- -- -endif::VK_EXT_calibrated_timestamps[] +endif::VK_KHR_calibrated_timestamps,VK_EXT_calibrated_timestamps[] diff --git a/chapters/textures.adoc b/chapters/textures.adoc index 777f8a2c79..c2e15b66c7 100644 --- a/chapters/textures.adoc +++ b/chapters/textures.adoc @@ -3783,7 +3783,7 @@ The A component is 0. The minimum or maximum behavior is selected by slink:VkSamplerBlockMatchWindowCreateInfoQCOM::pname:windowCompareMode. -The following psuedocode describes the operation +The following pseudocode describes the operation code:opImageBlockMatchWindowSAD. The pseudocode for code:opImageBlockMatchWindowSSD follows an identical pattern. @@ -3849,7 +3849,7 @@ For each block match operation, the reference coordinate is latexmath:[(s,t)]. For each block match operation, only the R component of the target and reference images are compared. -The following psuedocode describes the operation opImageBlockMatchGatherSAD. +The following pseudocode describes the operation opImageBlockMatchGatherSAD. The pseudocode for opImageBlockMatchGatherSSD follows an identical pattern. [source,c] diff --git a/config/CI/codespell-allowed b/config/CI/codespell-allowed index 1d0698464e..859b1a9ebe 100644 --- a/config/CI/codespell-allowed +++ b/config/CI/codespell-allowed @@ -13,14 +13,17 @@ uscaled # Markup/script/style guide words captable crate +implementor +implementors rouge shouldnot tesselation # Proper names +alis +benj calle ser # proposals/ words -esponding pares # vk.xml words halfs diff --git a/config/CI/codespellrc b/config/CI/codespellrc index dba7accaaa..943ace5a29 100644 --- a/config/CI/codespellrc +++ b/config/CI/codespellrc @@ -1,5 +1,5 @@ # Copyright 2022-2023 The Khronos Group Inc. # SPDX-License-Identifier: CC-BY-4.0 [codespell] -skip=#*,katex,.git,.github,LICENSES,NOTES*,./style/markup.adoc,asciidoctor-chunker.js,lunr.js,rouge-extend-css.rb,sample_count*.svg,./node_modules/*,./gen/*,./old/*,./oldGen/*,./new/*,./scripts/reflow-tests/*,./build_tests/*.adoc,./build_tests/* +skip=#*,katex,.git,.github,LICENSES,NOTES*,./style/markup.adoc,./style/writing.adoc,asciidoctor-chunker.js,lunr.js,rouge-extend-css.rb,sample_count*.svg,./node_modules/*,./gen/*,./old/*,./oldGen/*,./new/*,./scripts/reflow-tests/*,./build_tests/*.adoc,./build_tests/* ignore-words=config/CI/codespell-allowed diff --git a/proposals/VK_KHR_vertex_attribute_divisor.adoc b/proposals/VK_KHR_vertex_attribute_divisor.adoc new file mode 100644 index 0000000000..8bc8b51859 --- /dev/null +++ b/proposals/VK_KHR_vertex_attribute_divisor.adoc @@ -0,0 +1,145 @@ +// Copyright 2021-2023 The Khronos Group Inc. +// +// SPDX-License-Identifier: CC-BY-4.0 + += VK_KHR_vertex_attribute_divisor +:toc: left +:refpage: https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/ +:sectnums: + +Promoted from `VK_EXT_vertex_attribute_divisor`, this extension allows +instance-rate vertex attributes to be repeated for certain number of instances +instead of advancing for every instance when instanced rendering is enabled. + +== Problem Statement + +In other APIs such as OpenGL, it is possible to use the same values of vertex +attributes for a number of successive instances when instanced rendering is +enabled. +This is commonly referred to as "vertex attribute divisor". +For example, if the divisor is `N`, the same vertex attribute will be applied +to `N` successive instances before moving on to the next vertex attribute. +A value of `0` allows the same vertex attribute to be applied to all instances. + +This functionality was originally introduced in Vulkan with the +`VK_EXT_vertex_attribute_divisor` extension. + +== Proposal + +The API in `VK_EXT_vertex_attribute_divisor` is promoted to KHR with the +following exception: + +The `VkPhysicalDeviceVertexAttributeDivisorPropertiesKHR` struct contains +an additional property `supportsNonZeroFirstInstance`, compared to +`VkPhysicalDeviceVertexAttributeDivisorPropertiesEXT`. + +The vertex attribute divisor can be specified with: + +[source,c] +---- +typedef struct VkVertexInputBindingDivisorDescriptionKHR { + uint32_t binding; + uint32_t divisor; +} VkVertexInputBindingDivisorDescriptionKHR; +---- + +which specifies a divisor value for the given vertex binding. +`divisor` is the number of successive instances that will use the same value of +the vertex attribute when instanced rendering is enabled. +For example, if the divisor is `N`, the same vertex attribute will be applied +to `N` successive instances before moving on to the next vertex attribute. + +The above is specified once per vertex binding in: + +[source,c] +---- +typedef struct VkPipelineVertexInputDivisorStateCreateInfoKHR { + VkStructureType sType; + const void* pNext; + uint32_t vertexBindingDivisorCount; + const VkVertexInputBindingDivisorDescriptionKHR* pVertexBindingDivisors; +} VkPipelineVertexInputDivisorStateCreateInfoKHR; +---- + +The maximum allowed divisor value can be queried with the following struct when +chained to `VkPhysicalDeviceProperties2`: + +[source,c] +---- +typedef struct VkPhysicalDeviceVertexAttributeDivisorPropertiesKHR { + VkStructureType sType; + void* pNext; + uint32_t maxVertexAttribDivisor; + VkBool32 supportsNonZeroFirstInstance; +} VkPhysicalDeviceVertexAttributeDivisorPropertiesKHR; +---- + +In the above, `supportsNonZeroFirstInstance` specifies whether a non-zero value +for the `firstInstance` parameter of drawing commands is supported when +`VkVertexInputBindingDivisorDescriptionKHR::divisor` (or the equivalent +dynamically set state) is not `1`. Note that this property is new compared to +`VkPhysicalDeviceVertexAttributeDivisorPropertiesEXT`. + +The `VK_EXT_vertex_input_dynamic_state` and `VK_EXT_shader_object` extensions +provide the `vkCmdSetVertexInputEXT` function, allowing the vertex attribute +divisor state to be dynamically set. + +The functionality of this extension is controlled by the following features: + +[source,c] +---- +typedef struct VkPhysicalDeviceVertexAttributeDivisorFeaturesKHR { + VkStructureType sType; + void* pNext; + VkBool32 vertexAttributeInstanceRateDivisor; + VkBool32 vertexAttributeInstanceRateZeroDivisor; +} VkPhysicalDeviceVertexAttributeDivisorFeaturesKHR; +---- + + * `vertexAttributeInstanceRateDivisor` specifies whether the functionality in + the extension is supported. + * `vertexAttributeInstanceRateZeroDivisor` specifies whether a zero + value for `VkVertexInputBindingDivisorDescriptionKHR::divisor` is + supported. + +== Examples + +The vertex attribute divisor can be specified when creating a graphics pipeline as such: + +[source,c] +---- +const VkVertexInputBindingDivisorDescriptionKHR divisorDesc = +{ + .binding = 0, + .divisor = 4, +}; + +const VkPipelineVertexInputDivisorStateCreateInfoKHR divisorInfo = +{ + .sType = VK_STRUCTURE_TYPE_PIPELINE_VERTEX_INPUT_DIVISOR_STATE_CREATE_INFO_KHR, + .vertexBindingDivisorCount = 1, + .pVertexBindingDivisors = &divisorDesc, +} + +const VkVertexInputBindingDescription binding = +{ + .binding = 0, + .stride = sizeof(Vertex), + .inputRate = VK_VERTEX_INPUT_RATE_INSTANCE, +}; + +const VkPipelineVertexInputStateCreateInfo viInfo = +{ + .sType = VK_STRUCTURE_TYPE_PIPELINE_VERTEX_INPUT_CREATE_INFO, + .pNext = &divisorInfo, + ... +}; +---- + +== Issues + +1) What is the effect of a non-zero value for `firstInstance`? + +*RESOLVED*: The Vulkan API should follow the OpenGL convention and offset +attribute fetching by `firstInstance` while computing vertex attribute offsets. + diff --git a/proposals/VK_KHR_video_queue.adoc b/proposals/VK_KHR_video_queue.adoc index 584c828bdf..2fd4e9a567 100644 --- a/proposals/VK_KHR_video_queue.adoc +++ b/proposals/VK_KHR_video_queue.adoc @@ -427,7 +427,7 @@ typedef struct VkQueueFamilyQueryResultStatusPropertiesKHR { } VkQueueFamilyQueryResultStatusPropertiesKHR; ---- -Quries also work slightly differently within a video coding scope due to the special behavior of video coding operations. Instead of a query being bound to the scope determined by the corresponding `vkCmdBeginQuery` and `vkCmdEndQuery` calls, in case of video coding each video coding operation consumes its own query slot. Thus if a command issues multiple video coding operations, then those may consume multiple subsequent query slots within the query pool. However, as no new commands are introduced by this extension to start queries with multiple activatable query slots, currently only a single video coding operation is allowed between a `vkCmdBeginQuery` and `vkCmdEndQuery` call. +Queries also work slightly differently within a video coding scope due to the special behavior of video coding operations. Instead of a query being bound to the scope determined by the corresponding `vkCmdBeginQuery` and `vkCmdEndQuery` calls, in case of video coding each video coding operation consumes its own query slot. Thus if a command issues multiple video coding operations, then those may consume multiple subsequent query slots within the query pool. However, as no new commands are introduced by this extension to start queries with multiple activatable query slots, currently only a single video coding operation is allowed between a `vkCmdBeginQuery` and `vkCmdEndQuery` call. An unsuccessfully completed video coding operation may also have an effect on subsequently executed video coding operations against the same video session. In particular, if a video coding operation requests the setup (activation) of a DPB slot with a reference picture and that video coding operation completes unsuccessfully, then the corresponding DPB slot will end up having an invalid picture reference. This will cause subsequent video coding operations using reference pictures associated with that DPB slot to produce unexpected results, and may even cause such dependent video coding operations themselves to complete unsuccessfully in response to the invalid input data. diff --git a/proposals/VK_QCOM_image_processing.adoc b/proposals/VK_QCOM_image_processing.adoc index 2012695104..7aa76f9fb1 100644 --- a/proposals/VK_QCOM_image_processing.adoc +++ b/proposals/VK_QCOM_image_processing.adoc @@ -197,8 +197,8 @@ The following summarizes how the built-ins are exposed in GLSL: | Syntax | Description | +------------------------------------+--------------------------------------------+ | vec4 textureWeightedQCOM( | weighted sample operation multiplies | - | sampler2D tex, | a 2D kernel of filter weights with a corr- | - | vec2 P, | esponding region of sampled texels and | + | sampler2D tex, | a 2D kernel of filter weights with a | + | vec2 P, | corresponding region of sampled texels and | | sampler2DArray weight) | sums the results to produce the output | | | value. | +------------------------------------+--------------------------------------------+ @@ -661,7 +661,7 @@ Formats supported by _weight image_ parameter to `OpImageSampleWeightedQCOM` VK_FORMAT_R16_SFLOAT ---- -Formats supported by _target image_ or _referenence image_ parameter to `OpImageBlockMatchSADQCOM` and `OpImageBlockMatchSSDQCOM` +Formats supported by _target image_ or _reference image_ parameter to `OpImageBlockMatchSADQCOM` and `OpImageBlockMatchSSDQCOM` [source,c] ---- VK_FORMAT_R8_UNORM diff --git a/scripts/extensionmetadocgenerator.py b/scripts/extensionmetadocgenerator.py index 1dbb22e364..3709258ddd 100644 --- a/scripts/extensionmetadocgenerator.py +++ b/scripts/extensionmetadocgenerator.py @@ -333,6 +333,8 @@ def versionKey(name): for spvname in SPV_deps[self.name]: write(f' * {self.conventions.formatSPIRVlink(spvname)}', file=fp) + write('', file=fp) + if self.deprecationType: self.writeTag('Deprecation State', None, isRefpage, fp) diff --git a/scripts/htmldiff/htmldiff.pl b/scripts/htmldiff/htmldiff.pl index af2a6cd290..1daaf1f399 100755 --- a/scripts/htmldiff/htmldiff.pl +++ b/scripts/htmldiff/htmldiff.pl @@ -50,7 +50,7 @@ # also requires the perl modules Getopt::Std # # NOTE: The markup created by htmldiff may not validate against the HTML 4.0 -# DTD. This is because the algorithm is realtively simple, and there are +# DTD. This is because the algorithm is relatively simple, and there are # places in the markup content model where the span element is not allowed. # Htmldiff is NOT aware of these places. # diff --git a/scripts/spec_tools/macro_checker_file.py b/scripts/spec_tools/macro_checker_file.py index ec73062166..f2d6784b63 100644 --- a/scripts/spec_tools/macro_checker_file.py +++ b/scripts/spec_tools/macro_checker_file.py @@ -955,7 +955,7 @@ def checkPname(self, pname_context): if entity not in members: self.warning(MessageId.UNKNOWN_MEMBER, ["Could not find member/param named '{}' in {}".format(entity, pname_context), - 'Known {} mamber/param names are: {}'.format( + 'Known {} member/param names are: {}'.format( pname_context, ', '.join(members))], group='entity_name') def checkIncludeRefPageRelation(self, entity, generated_type): diff --git a/scripts/spec_tools/main.py b/scripts/spec_tools/main.py index 2cd4f69c04..e035ce36dd 100644 --- a/scripts/spec_tools/main.py +++ b/scripts/spec_tools/main.py @@ -1,4 +1,4 @@ -"""Provides a re-usable command-line interface to a MacroChecker.""" +"""Provides a reusable command-line interface to a MacroChecker.""" # Copyright (c) 2018-2019 Collabora, Ltd. # diff --git a/scripts/syncgenerator.py b/scripts/syncgenerator.py index d8f282154e..feed51dae9 100644 --- a/scripts/syncgenerator.py +++ b/scripts/syncgenerator.py @@ -37,7 +37,7 @@ def __init__(self, *args, **kwargs): # self.pipeline_stage_condition = dict() - # + # self.access_flag_condition = dict() # diff --git a/style/revisions.adoc b/style/revisions.adoc index 988e611a53..734c1784d7 100644 --- a/style/revisions.adoc +++ b/style/revisions.adoc @@ -5,6 +5,9 @@ [[revisions]] = Revision History +* 2023-11-30 - Update introduction of the <> chapter + to recommend following existing language and API design patterms when + creating new specification language (internal issue 3707). * 2023-10-22 - Update <>, since some are now being ratified. * 2023-10-11 - Add rules for <VKSC_API_VERSION_1_0 VK_MAKE_API_VERSION(VKSC_API_VARIANT, 1, 0, 0)// Patch version should always be set to 0 // Version of this file -#define VK_HEADER_VERSION 272 +#define VK_HEADER_VERSION 273 // Complete version of this file #define VK_HEADER_VERSION_COMPLETE VK_MAKE_API_VERSION(0, 1, 3, VK_HEADER_VERSION) // Version of this file @@ -686,7 +686,8 @@ typedef void* MTLSharedEvent_id; - + + @@ -3929,11 +3930,12 @@ typedef void* MTLSharedEvent_id; VkBool32 fullyCoveredFragmentShaderInputVariabletrue if the implementation supports the FullyCoveredEXT SPIR-V builtin fragment shader input variable VkBool32 conservativeRasterizationPostDepthCoveragetrue if the implementation supports both conservative rasterization and post depth coverage sample coverage mask - - VkStructureType sType + + VkStructureType sType const void* pNext - VkTimeDomainEXT timeDomain + VkTimeDomainKHR timeDomain + VkStructureType sType void* pNext @@ -4158,21 +4160,29 @@ typedef void* MTLSharedEvent_id; uint64_t value - + uint32_t binding uint32_t divisor - - VkStructureType sType + + + VkStructureType sType const void* pNext uint32_t vertexBindingDivisorCount - const VkVertexInputBindingDivisorDescriptionEXT* pVertexBindingDivisors + const VkVertexInputBindingDivisorDescriptionKHR* pVertexBindingDivisors + VkStructureType sType void* pNext uint32_t maxVertexAttribDivisormax value of vertex attribute divisor + + VkStructureType sType + void* pNext + uint32_t maxVertexAttribDivisormax value of vertex attribute divisor + VkBool32 supportsNonZeroFirstInstance + VkStructureType sType void* pNext @@ -4285,12 +4295,13 @@ typedef void* MTLSharedEvent_id; VkBool32 shaderImageFloat32AtomicMinMax VkBool32 sparseImageFloat32AtomicMinMax - - VkStructureType sType + + VkStructureType sType void* pNext VkBool32 vertexAttributeInstanceRateDivisor VkBool32 vertexAttributeInstanceRateZeroDivisor + VkStructureType sType void* pNext @@ -9760,11 +9771,11 @@ typedef void* MTLSharedEvent_id; - - - - - + + + + + @@ -13104,8 +13115,8 @@ typedef void* MTLSharedEvent_id; VkDevice device VkImage image int nativeFenceFd - VkSemaphore semaphore - VkFence fence + VkSemaphore semaphore + VkFence fence VkResult vkQueueSignalReleaseImageANDROID @@ -13131,19 +13142,21 @@ typedef void* MTLSharedEvent_id; VkBool32 localDimmingEnable - VkResult vkGetPhysicalDeviceCalibrateableTimeDomainsEXT + VkResult vkGetPhysicalDeviceCalibrateableTimeDomainsKHR VkPhysicalDevice physicalDevice uint32_t* pTimeDomainCount - VkTimeDomainEXT* pTimeDomains + VkTimeDomainKHR* pTimeDomains + - VkResult vkGetCalibratedTimestampsEXT + VkResult vkGetCalibratedTimestampsKHR VkDevice device uint32_t timestampCount - const VkCalibratedTimestampInfoEXT* pTimestampInfos + const VkCalibratedTimestampInfoKHR* pTimestampInfos uint64_t* pTimestamps uint64_t* pMaxDeviation + VkResult vkSetDebugUtilsObjectNameEXT VkDevice device @@ -19347,11 +19360,15 @@ typedef void* MTLSharedEvent_id; - + - + + + + + @@ -19417,13 +19434,13 @@ typedef void* MTLSharedEvent_id; - + - - - - - + + + + + @@ -23593,10 +23610,17 @@ typedef void* MTLSharedEvent_id; - + - - + + + + + + + + + @@ -23716,10 +23740,15 @@ typedef void* MTLSharedEvent_id; - + - - + + + + + + +