diff --git a/.github/workflows/CI.yml b/.github/workflows/CI.yml index 7488bf2f6..fb6aeb1b2 100644 --- a/.github/workflows/CI.yml +++ b/.github/workflows/CI.yml @@ -25,7 +25,7 @@ jobs: container: khronosgroup/docker-images@sha256:42123ba13792c4e809d037b69152c2230ad97fbf43b677338075ab9c928ab6ed steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 - name: REUSE license checker run: reuse lint @@ -35,7 +35,7 @@ jobs: container: khronosgroup/docker-images@sha256:42123ba13792c4e809d037b69152c2230ad97fbf43b677338075ab9c928ab6ed steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 - name: Internal self-test of the check_spec_links script run: py.test-3 test*.py working-directory: scripts @@ -51,7 +51,7 @@ jobs: container: khronosgroup/docker-images@sha256:42123ba13792c4e809d037b69152c2230ad97fbf43b677338075ab9c928ab6ed steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 - run: ./makeSpec -clean -spec core -genpath gencore QUIET= -j${nproc} -Otarget chunked html spec-generate: @@ -60,7 +60,7 @@ jobs: container: khronosgroup/docker-images@sha256:42123ba13792c4e809d037b69152c2230ad97fbf43b677338075ab9c928ab6ed steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 - name: Build the actual spec (both chunked and single-page HTML), and other common targets run: ./makeSpec -clean -spec all QUIET= -j${nproc} -Otarget manhtmlpages validusage styleguide registry chunked html - name: Check consistency of internal xrefs and anchors in the output, now that an HTML output is available @@ -75,7 +75,7 @@ jobs: # just one large file: run: tar -cvf spec-outputs.tar gen/ - name: Archive generated spec - uses: actions/upload-artifact@v3 + uses: actions/upload-artifact@v4 with: name: spec-outputs path: spec-outputs.tar @@ -87,11 +87,11 @@ jobs: continue-on-error: true steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 # Generate the vulkan C++ header (vulkan.hpp) # Failure (should be) allowed, for now - name: Download generated spec - uses: actions/download-artifact@v3 + uses: actions/download-artifact@v4 with: name: spec-outputs - name: Unpack generated spec @@ -120,7 +120,7 @@ jobs: ./VulkanHppGenerator -f "${SPEC_DIR}"/xml/vk.xml cp /tmp/Vulkan-Hpp/vulkan/*.hpp ${SPEC_DIR}/gen/include/vulkan/ - name: Upload generated hpp - uses: actions/upload-artifact@v3 + uses: actions/upload-artifact@v4 with: name: hpp-outputs path: gen/include/ @@ -135,12 +135,12 @@ jobs: CARGO_TARGET_DIR: ${{ github.workspace }}/ash-target steps: - - uses: actions/checkout@v3 - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 + - uses: actions/checkout@v4 with: repository: ash-rs/ash path: ash - - uses: actions/cache@v3 + - uses: actions/cache@v4 with: path: | ~/.cargo/bin/ @@ -152,7 +152,7 @@ jobs: restore-keys: | ${{ runner.os }}-cargo-ash-generator- - name: Download generated spec - uses: actions/download-artifact@v3 + uses: actions/download-artifact@v4 with: name: spec-outputs - name: Unpack generated spec @@ -175,7 +175,7 @@ jobs: # https://github.com/actions/upload-artifact#limitations, see above run: tar -cvf ash-outputs.tar ash/ - name: Upload generated ash - uses: actions/upload-artifact@v3 + uses: actions/upload-artifact@v4 with: name: ash-outputs path: ash-outputs.tar @@ -189,7 +189,7 @@ jobs: continue-on-error: true steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 - name: Sparse/shallow clone of CTS GitHub repository to pull only relevant parts run: | git clone --sparse --depth 1 --single-branch --branch main https://github.com/KhronosGroup/VK-GL-CTS.git @@ -199,7 +199,7 @@ jobs: # Link the spec project into CTS hierarchy, instead of cloning it mkdir external/vulkan-docs ln -s `cd .. ; pwd` external/vulkan-docs/src - - name: Run the Vulkan-specific tests (from scripts/check_build_sanity.py) + - name: Run the Vulkan-specific tests (from scripts/check_build_sanity.py) # codespell:allow sanity run: | cd VK-GL-CTS python3 external/vulkancts/scripts/gen_framework.py @@ -213,9 +213,9 @@ jobs: needs: spec-generate steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 - name: Download generated files - uses: actions/download-artifact@v3 + uses: actions/download-artifact@v4 with: name: spec-outputs - name: Unpack generated spec @@ -234,15 +234,15 @@ jobs: continue-on-error: true steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 - name: Download generated spec - uses: actions/download-artifact@v3 + uses: actions/download-artifact@v4 with: name: spec-outputs - name: Unpack generated spec run: tar -xvf spec-outputs.tar - name: Download generated hpp - uses: actions/download-artifact@v3 + uses: actions/download-artifact@v4 with: name: hpp-outputs path: gen/include/ @@ -261,12 +261,12 @@ jobs: steps: - name: Download generated files - uses: actions/download-artifact@v3 + uses: actions/download-artifact@v4 with: name: ash-outputs - name: Unpack generated Ash crate run: tar -xvf ash-outputs.tar - - uses: actions/cache@v3 + - uses: actions/cache@v4 with: path: | ~/.cargo/bin/ diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 4f7c3562e..8d8c8291c 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -195,7 +195,7 @@ cts-framework-tests: # Link the spec project into CTS hierarchy, instead of cloning it - mkdir external/vulkan-docs - ln -s `cd .. ; pwd` external/vulkan-docs/src - # Run the Vulkan-specific tests (from scripts/check_build_sanity.py) + # Run the Vulkan-specific tests (from scripts/check_build_sanity.py) # codespell:allow sanity - python3 external/vulkancts/scripts/gen_framework.py - python3 external/vulkancts/scripts/gen_framework_c.py - python3 external/vulkancts/scripts/gen_framework.py --api SC diff --git a/BUILD.adoc b/BUILD.adoc index 8a4c90a57..b9c2b3674 100644 --- a/BUILD.adoc +++ b/BUILD.adoc @@ -30,11 +30,14 @@ The repository is located at https://github.com/KhronosGroup/Vulkan-Docs/. Next, install all the necessary build tools (see <> below). If you are using the <>, -which we strongly recommend, one way to build using the image (assuming a -Linux docker host) is: +which we strongly recommend, two ways to build using the image are: + $ # assuming a Linux docker host $ scripts/runDocker + $ # assuming a Linux podman host + $ scripts/runPodman + executed from the specification repository root. `runDocker` runs the Docker image with the cloned repository mounted under @@ -50,7 +53,7 @@ to build an HTML5 specification output for the core Vulkan 1.3 specification, with no extensions included, or $ cd /vulkan - $ ./makeSpec -spec all all + $ ./makeSpec -spec all alldocs allchecks to build the spec targets `html`, `pdf`, `styleguide`, `registry`, `manhtmlpages`, and `allchecks`, with *all* registered extensions included. @@ -410,6 +413,10 @@ Docker installation is beyond the scope of this document. Refer to link:https://docs.docker.com/get-docker/[the Docker website] for information about installing Docker on Linux, Windows, and MacOS X. +Another way to execute the Docker image is using the open source podman +container tool. See link:https://podman.io/get-started[the Podman website] +for information about installing podman on Linux, Windows, and MacOS X. + The build image is *named* `khronosgroup/docker-images:asciidoctor-spec`. However, due to local and CI caching problems when this image is updated on dockerhub, we use the SHA256 of the latest image update, rather than the @@ -422,9 +429,10 @@ which will print a line like image: khronosgroup/docker-images@sha256:42123ba13792c4e809d037b69152c2230ad97fbf43b677338075ab9c928ab6ed Everything following `image: ` is the to use. The first time you -try to run Docker with this , as is done by the `runDocker` -script described above under <>, the image will -be pulled from Dockerhub and cached locally on your machine. +try to run a container with this , as is done by the `runDocker` +and `runPodman` scripts described above under <>, the image will be pulled from Dockerhub and cached locally on your +machine. This image is used to build Specification output documents or other Makefile targets. @@ -473,7 +481,7 @@ toolchain yourself. [[building-epub-outputs]] === Building EPUB Outputs -The `epub` target will generate an EPUB file in in +The `epub` target will generate an EPUB file in `$(OUTDIR)/epub/vkspec.epub`. Note that the `epub` target is community-contributed, and not supported by Khronos. See https://github.com/KhronosGroup/Vulkan-Docs/pull/2286 for more. diff --git a/ChangeLog.adoc b/ChangeLog.adoc index ee304590b..62ac37b05 100644 --- a/ChangeLog.adoc +++ b/ChangeLog.adoc @@ -14,6 +14,208 @@ appears frequently in the change log. ''' +Change log for May 10, 2024 Vulkan 1.3.285 spec update: + +Public Issues + + * Update VkMemoryMapInfoKHR VUs to not require VK_WHOLE_SIZE with + VK_MEMORY_MAP_PLACED_BIT (public issue 2350). + * Add a <> section and + clarify that fixed-length string buffers in API structures always + include the null terminator (public issue 2351). + * Update refpage short descriptions of VkAttachmentLoad/StoreOp to be + consistent with spec language (public issue 2353). + * Clarify that the KHR and EXT load_store_op_none extensions were not + promoted to Vulkan 1.3 (public PR 2357). + +Internal Issues + + * Add a VkGraphicsPipelineCreateInfo VU banning "`read-only`" input + attachments without VkRenderingInputAttachmentIndexInfoKHR (internal + issue 3862). + * Add explicit reference to RayQueryPositionFetchKHR SPIR-V capability in + the VK_KHR_ray_tracing_position_fetch extension appendix and XML + spirvcapability tags (internal MR 6617). + * Remove MaximallyReconvergesKHR capability (which is not a capability, + but an execution mode) from XML (internal MR 6618). + * Add alias and enum value-> type maps in `reg.py` (internal MR 6620). + * Add missing shader object VU for vkCmdDispatchBase (internal MR 6623). + * Make build tests less sensitive to asciidoctor versions and CSS changes + by just comparing HTML body content (internal MR 6637). + * Do not allow overlapping builtin decorations for an entry point in the + <> section, and add + some related <> VUs (KhronosGroup/SPIRV-Cross issue 2313). + +New Extensions + + * VK_MESA_image_alignment_control + +''' + +Change log for May 5, 2024 Vulkan 1.3.284 spec update: + +Public Issues + + * Refactor "`proposals`" into a separate Antora component "`features`" and + refer to published proposals more consistently as "`feature + descriptions`" (public PR 2361). + +Internal Issues + + * Partial synchronization with OpenXR scripts (internal MR 6419). + * Refactor extensionmetadocgenerator.py to simplify adding new sections + (internal MR 6624). + * Restore structextends="VkPhysicalDeviceProperties2" back for + VkPhysicalDeviceLegacyVertexAttributesPropertiesEXT (internal MR 6631). + +New Extensions + + * VK_EXT_legacy_vertex_attributes + +''' + +Change log for April 19, 2024 Vulkan 1.3.283 spec update: + +Public Issues + + * Add a NOTE to the <> section + explaining how release barrier should be used (public issue 2319). + * Add VkGraphicsPipelineCreateInfo VU to fix partial dynamic state for + VK_EXT_conservative_rasterization (public issue 2344). + * Update Github Actions from @v3 to @v4 (public PR 2352). + +Internal Issues + + * Limit protected VkBuffer creation to Vulkan 1.0 usages in + VkBufferCreateInfo VUs and <> (internal issue 3596). + * Clarify meaning of + VkAccelerationStructureGeometryTrianglesDataKHR::maxVertex (internal + issue 3796). + * Require InputAttachmentIndx for arrayed SubpassData variables in + <> + (internal issue 3837). + * Allow external host memory to <> (internal issue 3841). + * Add pipeline create flag to VK_EXT_legacy_dithering to enable use with + dynamic rendering (internal MR 6491). + * Add missing vkCmdBeginRenderPass VU for VK_EXT_nested_command_buffer + (internal MR 6595). + * Remove redundant common draw vertex binding VU 04912 (internal MR 6604). + +''' + +Change log for April 13, 2024 Vulkan 1.3.282 spec update: + +Public Issues + + * Fix typo and move vkCmdCopyAccelerationStructureNV VU 07792 from the + common copy acceleration structures VUs (based on issues from public + pull request 2144). + * Relax video format image usage flags requirement in the + <> section when + VK_IMAGE_CREATE_EXTENDED_USAGE_BIT is specified (public issue 2329). + * Resolve some duplicate consecutive word typos (public PR 2333) and add a + CI / `allchecks` built target to detect them in the future (public issue + 2338). + * Adjust proposal links to point to the docs site from the Antora build + (Vulkan-Site issue 65). + * Minor fixes to proposal markup and navigation for the Antora build. + +Internal Issues + + * Add unnormalizedCoordinates draw-time ImageView VUs (internal issue + 3632). + * Alias VK_FORMAT_R16G16_S10_5_NV to the more informative + VK_FORMAT_R16G16_SFIXED5_NV, and add a `SFIXED5` `numericFormat` XML + attribute to describe the component format (internal issue 3802). + * Add <> VU to ban use of SPIR-V dimension `Rect` (internal issue + 3812). + * Clarify in the <> + section that queries are undefined for stages not present in pipelines + (internal issue 3816). + * Add VkGraphicsPipelineCreateInfo and vkCreateShadersEXT VUs for + DrawIndex BuiltIn decorations with Task and Mesh shader stages (internal + issue 3833). + * Add CI check to prevent VK_ERROR_UNKNOWN and VK_ERROR_VALIDATION_FAILED + in XML `errorcodes` attributes (internal issue 3836). + * Add the robustBufferAccess feature to common draw vertex binding VU + 02721 (internal issue 3838). + * Enforce American English spelling conventions in CI (as required by the + style guide) using the codespell British->American English dictionary, + fix inconsistencies that discovered, and update some external repository + deep links to include their updated default branch name (internal issue + 3848). + * Add missing VU for using HOST_BIT with vkCmdPipelineBarrier (internal MR + 6217). + * Clarify descriptor set layout support in vkCreateDescriptorSetLayout VU + 09582 (internal MR 6567). + * Add `%unbreakable` asciidoc option to generated API interface blocks, + preventing long structure and enumerant definitions from being split + across PDF page boundaries (internal MR 6571). + * Improve error message from xml_consistency.py (internal MR 6572). + * Fixes to sampleShadingEnable for VkGraphicsPipelineCreateInfo VU 06637 + and VkGraphicsPipelineCreateInfo VU 09567 (internal MR 6575). + * Clarify that subpassLoad does not take a "`layer`" argument in + <> + VU 04660 (internal MR 6581). + * Update VK_EXT_metal_objects by adding an `__unsafe_unretained ownership` + qualifier to all Metal object declarations, to support Automatic + Reference Counting (ARC) (internal MR 6582). + * Add a NOTE to the <> section about conditions + requiring a CTS waiver on some implementations (internal MR 6589). + * Add a common draw vertex binding VU for primitiveRestartEnable list + topology, corresponding to VkPipelinInputAssemblyStateCreateInfo VU + 06252 (public Vulkan-ValidationLayers issue 4413). + +''' + +Change log for March 22, 2024 Vulkan 1.3.281 spec update: + +Public Issues + + * Add matching stride VUs for MultiDraw (public issue 2323). + * Always generate a failure code section, even for commands with no + errorcodes specified in the XML (public PR 2325). + + +Internal Issues + + * Correct issues describing NT handle usage in the + VK_KHR_external_memory_win32 and VK_KHR_external_semaphore_win32 + extension appendices (internal issue 1291). + * Fix refpage layout for Vk*Feature* structures so member descriptions + appear in the right section (internal issue 3314). + * Add vkCmdBeginTransformFeedbackEXT VU statement for max counter buffers + (internal issue 3654). + * Clarify packing of data returned by vkGetRayTracingShaderGroupHandles + (internal issue 3791). + * Fix `depends` attribute for many promoted extensions (internal issue + 3810). + * Clarify OpKill behavior with shader termination (internal issue 3815). + * Require customBorderColors feature support if the + VK_EXT_custom_border_color extension is supported (internal issue 3819). + * Remove explicit VK_ERROR_UNKNOWN errorcodes from XML and add a NOTE not + to do this in the registry schema document (internal issue 3824). + * Clarify AV1 loop restoration size values in the + <> description + (internal MR 6499). + * Fix VkGraphicsPipelineCreateInfo VU 07609 (internal MR 6535). + * Add helper script to run the Khronos Docker image used to build + specifications using podman, instead of docker (internal MR 6538). + * Mark recently ratified EXT extensions in XML (internal MR 6548). + * Relocate a NOTE in the "`WSI Swapchain`" section following the normative + language it refers to (internal MR 6549). + * Clarify and fix sparse memory bind size requirements in the + <>, <>, and VkSparseMemoryBind language (internal MR 6555). + +''' + Change log for March 8, 2024 Vulkan 1.3.280 spec update: Public Issues @@ -89,7 +291,7 @@ Internal Issues * Clarify that VkPhysicalDeviceDriverProperties::conformanceVersion identifies the most recent version of CTS successfully passed (as opposed to requiring the driver to have passed a one-month review period - and have been officially labelled conformant by the Vulkan working + and have been officially labeled conformant by the Vulkan working group) (internal issue 3780). * Provide more detailed description for VK_FORMAT_R16G16_S10_5_NV (internal issue 3788). @@ -2184,7 +2386,7 @@ Internal Issues: * Force applications to specify ename:VK_FORMAT_UNDEFINED for an unused attachment in both slink:VkPipelineRenderingCreateInfoKHR and - slink:VkCommandBufferInheritanceRenderingInfoKHR. The previous behaviour + slink:VkCommandBufferInheritanceRenderingInfoKHR. The previous behavior of allowing unused attachments to have any format is not supported on some conformant implementations that have shipped and cannot be updated. This functionality is intended to be restored via a new extension in the @@ -4595,7 +4797,7 @@ GitHub Issues: flink:vkGetSubpassShadingMaxWorkgroupSizeHUAWEI to flink:vkGetDeviceSubpassShadingMaxWorkgroupSizeHUAWEI and give it a dispatchable slink:VkDevice parameter (public issue 1564). - * Fix labelling of "`Resource`" reference block in pipeline block + * Fix labeling of "`Resource`" reference block in pipeline block diagrams (public issue 1582). Internal Issues: @@ -6015,10 +6217,11 @@ Change log for September 7, 2020 Vulkan 1.2.153 spec update: GitHub Issues: - * Specification default branch for updates and PRs is now `main` instead - of `master`. `master` branch still exists, but is frozen at the 1.2.152 - level. If you are pulling content from this repository, please switch - from `master` to `main` branch (internal issue 1351). + * Specification default branch for updates and PRs is now `main`. + The old default branch still exists, but is frozen at the 1.2.152 + level. + If you are pulling content from this repository, please switch to `main` + branch (internal issue 1351). * Fix slink:VkSubpassDependency2 link from slink:VkRenderPassCreateInfo2 (public issue 1358). @@ -6164,7 +6367,7 @@ Change log for August 10, 2020 Vulkan 1.2.150 spec update: GitHub Issues: * Remove ename:VK_ERROR_TOO_MANY_OBJECTS as a required error code for - flink:vkAllocateMemory and and flink:vkCreateSampler, and note that + flink:vkAllocateMemory and flink:vkCreateSampler, and note that while it may still occur as a historical artifact, exceeding implementation limits will result in undefined behavior (public issue 1295). @@ -6260,7 +6463,7 @@ Internal Issues: 2124). * Do not allow flink:vkWaitForFences or flink:vkWaitSemaphores to return timeouts before the period has expired, even though this is valid in - some other synchronisation APIs (internal issue 2146). + some other synchronization APIs (internal issue 2146). * Add elink:VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D11_FENCE_BIT as an alias of elink:VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D12_FENCE_BIT for clarity when interacting with D3D11 fences (internal issue 2175). @@ -6626,8 +6829,8 @@ Internal Issues: pname:instance (internal issue 2057). * Modify the valid usage statement ID assignment script to track a range of unused IDs for each extension branch under development, instead of - only allowing VUID assignment in `master` and `devel` branches (internal - issue 2100). + only allowing VUID assignment in the default and `devel` branches + (internal issue 2100). * Add `selector` and `selection` attributes for unions in XML, to enable automatic generation of validation code (internal issue 2140). * Fix validity generator for stext:Vk*Flags types that are aliases, @@ -8544,7 +8747,7 @@ Internal Issues: the headers for use by the hpp-generate / hpp-compile CI stages. Targets to generate the headers will not be removed, but keeping these generated files in the repository increased the frequency of conflicts between - branches when merging to master (internal issue 745). + branches when merging to the default branch (internal issue 745). * Reword "`undefined: behavior if *action*" to "`must: not do *action*`" in the places the old terminology was used, and add a new <> section of the @@ -8897,7 +9100,7 @@ Internal Issues: * Clarify the behavior of command aliases described in the <> and <> sections and the registry schema document with respect to - whether they are or are not the same entry point, and what the behaviour + whether they are or are not the same entry point, and what the behavior of the ftext:vkGet*ProcAddr commands is for each alias (internal issue 1462). * Update slink:VkPipelineShaderStageCreateInfo valid usage statements for @@ -9900,7 +10103,7 @@ GitHub Issues: that had previously been removed at the time that ename:VK_IMAGE_CREATE_EXTENDED_USAGE_BIT was introduced. These statements had incorrectly been restored due to an glitch while merging - from the old `1.0` branch to the current `master` branch (public issue + from the old `1.0` branch to the current default branch (public issue 683). Internal Issues: @@ -10107,10 +10310,10 @@ Change log for March 7, 2018 Vulkan 1.1.70 spec update: out with those build targets. However, we will soon generate all three types of documents as part of the regular spec update cycle. - NOTE: The GitHub KhronosGroup/Vulkan-Docs repository now maintains the - current specification in the `master` branch. The `1.0` branch is out of - date and will not be maintained, since we will be generating both 1.1 - and 1.0 specifications from the `master` branch in the future. + NOTE: The GitHub KhronosGroup/Vulkan-Docs repository default branch has + been changed. The old default `1.0` branch is out of date and will not + be maintained, since we will be generating both 1.1 and 1.0 + specifications from the default branch in the future. GitHub Issues: @@ -12311,7 +12514,7 @@ Other Issues: * Expand style guide and make it more self-consistent. * Use ISO 8601 date format everywhere. - * Emphasise the correct way of using + * Emphasize the correct way of using slink:VkSurfaceCapabilitiesKHR::pname:maxImageCount. * Added +VK_EXT_validation_flags+ extension for validation flag mechanism. * Fix an <> to include their current employer. @@ -12996,8 +13199,7 @@ GitHub Issues: * Replaced {apiname} with ``Vulkan'' in XML validity statements (public issue 199). * Fix dead links for WSI handle types (public issue 200). - * Use "signaled" instead of "signalled" spelling everywhere (public issue - 201). + * Use "signaled" spelling everywhere (public issue 201). * Move readme.pdf target directory for XML schema documentation into the target generation directory, instead of leaving it checked into the spec source tree (public issue 203). @@ -13611,43 +13813,3 @@ Change log for February 25, 2015 Vulkan 1.0.4 spec update: February 16, 2016 - Vulkan 1.0 initial public release -Change log for March 8, 2024 Vulkan 1.3.280 spec update: - -Public Issues - - * Use full "`queue family ownership transfer`" terminology consistently - (public PR 2320). - -Internal Issues - - * Add a NOTE to the <> section - warning of setting dynamic state on a static pipeline in older drivers - (internal issue 3675). - * Fix VkGraphicsPipelineCreateInfo VU 09037 related to pColorBlendState - with dynamic rendering (internal issue 3748). - * Add additional vkCmdBeginRendering and common draw dispatch VUs for - image layouts (internal issue 3758). - * Add missing common draw shader compatibility VUs for - VK_KHR_dynamic_rendering_local_read (internal issue 3787). - * Update sampling restrictions for min/max filtering in common draw - dispatch VUs (internal issue 3800). - * Add VkGraphicsPipelineCreateInfo VU requiring stageCount to be zero when - not needed (internal issue 3804). - * Clarify submission order for multiple subpasses in the - <> - section (internal issue 3811). - * Fix miscellaneous minor language and example code issues in the video - extension proposal and specification language (internal MR 6492). - * Properly define <> in the fundamentals chapter (internal MR 6508). - * Add missing VUs for subresource aspectMask to common image layout - transition, VkImageViewCreateInfo, and VkSparseImageMemoryBindInfo - (internal MR 6522). - * fix shader object interaction with dynamic blend states in the - <> section and common draw VUs - (internal MR 6523). - -New Extensions - - * VK_NV_ray_tracing_validation - diff --git a/Makefile b/Makefile index 88a5db9e2..a391c4ef0 100644 --- a/Makefile +++ b/Makefile @@ -74,6 +74,7 @@ CHECK_XREFS = endif allchecks: check-copyright-dates \ check-contractions \ + check-duplicates \ check-spelling \ check-writing \ check-bullets \ @@ -137,7 +138,7 @@ VERBOSE = # ADOCOPTS options for asciidoc->HTML5 output NOTEOPTS = -a editing-notes -a implementation-guide -PATCHVERSION = 280 +PATCHVERSION = 285 BASEOPTS = ifneq (,$(findstring VKSC_VERSION_1_0,$(VERSIONS))) @@ -444,6 +445,14 @@ check-contractions: exit 1 ; \ fi +# Look for duplicate words +CHECK_DUPLICATES = $(PYTHON) $(ROOTDIR)/scripts/find_duplicates.py `find *.adoc appendices chapters config scripts style -name '*.adoc'` +check-duplicates: + if ! $(CHECK_DUPLICATES) ; then \ + echo "Successive duplicate words found that are not allowed" ; \ + exit 1 ; \ + fi + # Look for typos and suggest fixes CODESPELL = codespell --config $(ROOTDIR)/config/CI/codespellrc -S '*.js' -S './antora*/*' -S 'ERRS*,*.pdf,*.html' check-spelling: diff --git a/README.adoc b/README.adoc index 46850ee1c..0cedfce33 100644 --- a/README.adoc +++ b/README.adoc @@ -27,6 +27,7 @@ LICENSE.adoc Summary of licenses used by files in the repository ChangeLog.adoc Change log summary for each public Vulkan spec update ChangeLogSC.adoc Change log summary for each public Vulkan SC spec update Makefile, make* Makefile and helper build scripts (see BUILD.adoc) +antora/ Staging area for the docs.vulkan.org Antora 'proposals' and 'spec' modules appendices/ Specification appendices chapters/ Specification chapters proposals/ Design documents for extensions diff --git a/antora/.gitignore b/antora/.gitignore new file mode 100644 index 000000000..0f17d1816 --- /dev/null +++ b/antora/.gitignore @@ -0,0 +1,8 @@ +# Copyright 2024 The Khronos Group Inc. +# SPDX-License-Identifier: Apache-2.0 + +**/images +**/chapters +**/appendices +**/partials +**/pages/proposals diff --git a/antora/Makefile b/antora/Makefile index d922d1534..999676072 100644 --- a/antora/Makefile +++ b/antora/Makefile @@ -1,7 +1,7 @@ # Copyright 2014-2024 The Khronos Group Inc. # SPDX-License-Identifier: Apache-2.0 -# Configure Vulkan spec Antora tree with generated files and transformed +# Configure Vulkan-Docs Antora tree with generated files and transformed # markup files. # Branch selection will come later. For now it is the current branch. @@ -9,13 +9,13 @@ RMRF = rm -rf JSAPIMAP = ./gen/apimap.cjs XREFMAPS = $(PYXREFMAP) $(JSXREFMAP) -PYXREFMAP = antora/xrefMap.py -JSXREFMAP = antora/xrefMap.cjs -JSPAGEMAP = antora/modules/ROOT/partials/gen/pageMap.cjs +PYXREFMAP = antora/spec/xrefMap.py +JSXREFMAP = antora/spec/xrefMap.cjs +JSPAGEMAP = antora/spec/modules/ROOT/partials/gen/pageMap.cjs -setup: setup_spec setup_proposals +setup: setup_spec setup_features -# Rewrite Vulkan spec sources and images into the module directory, ROOT +# Rewrite Vulkan spec sources and images into the spec/module/ROOT # component # Page headers are added to pull in required attributes # Also creates apimap.cjs, pageMap.cjs, and xrefMap.cjs for use by the @@ -37,8 +37,8 @@ xrefmaps: spec_pages: scripts/antora-prep.py \ -root . \ - -component $(shell realpath antora/modules/ROOT) \ - -xrefpath antora \ + -component $(shell realpath antora/spec/modules/ROOT) \ + -xrefpath antora/spec \ -pageHeaders antora/pageHeaders-spec.adoc \ -pagemappath $(JSPAGEMAP) \ ./config/attribs.adoc \ @@ -48,39 +48,42 @@ spec_pages: `find ./gen ./chapters ./appendices -name '[A-Za-z]*.adoc' | grep -v /vulkanscdeviations.adoc` \ $(JSAPIMAP) -# Rewrite proposals into the module directory, 'proposals' component +# Rewrite feature descriptions into the features/module/features component. # No additional pageHeaders required. -setup_proposals: proposal_nav +setup_features: features_nav scripts/antora-prep.py \ -root . \ - -component $(shell realpath antora/modules/proposals) \ - -xrefpath antora \ + -component $(shell realpath antora/features/modules/features) \ + -xrefpath antora/features \ ./images/tile_image.svg \ `find ./proposals -name '[A-Za-z]*.adoc'` -# Construct the proposals nav.adoc from the current list of -# proposals, so it remains up to date. +# Construct the features nav.adoc from the current list of +# features, so it remains up to date. # This could be merged into antora-prep.py but is very specific -# to the proposals so that is pointless. -proposal_nav: - scripts/antora-nav-proposals.py \ +# to the features module, so that is pointless. +# We no longer include the proposal template. +# To restore it, add +# -templatepath proposals/template.adoc +# and uncomment that option in the script. +features_nav: + scripts/antora-nav-features.py \ -root . \ - -component $(shell realpath antora/modules/proposals) \ + -component $(shell realpath antora/features/modules/features) \ -roadmappath proposals/Roadmap.adoc \ - -templatepath proposals/template.adoc \ `find ./proposals -name 'VK_*.adoc'` # Files generated by 'setup' target ANTORA_GENERATED = \ - antora/modules/ROOT/images \ - antora/modules/ROOT/pages/appendices \ - antora/modules/ROOT/pages/chapters \ - antora/modules/ROOT/pages/gen \ - antora/modules/ROOT/partials \ - antora/modules/proposals/pages/proposals \ - antora/modules/proposals/partials \ - antora/modules/proposals/images \ - antora/modules/proposals/nav.adoc \ + antora/spec/modules/ROOT/images \ + antora/spec/modules/ROOT/pages/appendices \ + antora/spec/modules/ROOT/pages/chapters \ + antora/spec/modules/ROOT/pages/gen \ + antora/spec/modules/ROOT/partials \ + antora/features/modules/features/pages/proposals \ + antora/features/modules/features/partials \ + antora/features/modules/features/images \ + antora/features/modules/features/nav.adoc \ $(JSXREFMAP) \ $(PYXREFMAP) diff --git a/antora/features/antora.yml b/antora/features/antora.yml new file mode 100644 index 000000000..88fb77da6 --- /dev/null +++ b/antora/features/antora.yml @@ -0,0 +1,23 @@ +# Copyright 2022-2024 The Khronos Group Inc. +# SPDX-License-Identifier: Apache-2.0 + +name: features +title: Vulkan Feature Descriptions +version: latest +start_page: features:index.adoc +# stem (latexmath) support is provided by the @djencks/asciidoctor-mathjax +# extension, loaded in the playbook. +asciidoc: + attributes: + stem: latexmath + config: partial$config + chapters: partial$chapters + appendices: partial$appendices + generated: partial$gen + images: image$ +# Not supported for SVG yet - see https://gitlab.com/antora/antora/-/issues/1001 +# imageopts: inline + imageopts: '' + refprefix: '' +nav: +- modules/features/nav.adoc diff --git a/antora/modules/proposals/nav.adoc b/antora/features/modules/features/nav.adoc similarity index 93% rename from antora/modules/proposals/nav.adoc rename to antora/features/modules/features/nav.adoc index 29091237e..de0fb702a 100644 --- a/antora/modules/proposals/nav.adoc +++ b/antora/features/modules/features/nav.adoc @@ -1,12 +1,14 @@ // Copyright 2024 The Khronos Group Inc. // SPDX-License-Identifier: CC-BY-4.0 +// This file is generated by the scripts/antora-nav-features.py script. +// To make changes, modify that script. + :chapters: -* xref:index.adoc[Vulkan Proposals] -* Vulkan Roadmap -** xref:proposals/Roadmap.adoc[] -* Extension Proposals +* xref:index.adoc[Vulkan Roadmap and Feature Descriptions] +* xref:proposals/Roadmap.adoc[Vulkan Roadmap] +* Feature Descriptions ** xref:proposals/VK_AMDX_shader_enqueue.adoc[] ** xref:proposals/VK_AMD_shader_early_and_late_fragment_tests.adoc[] ** xref:proposals/VK_ANDROID_external_format_resolve.adoc[] @@ -76,7 +78,6 @@ ** xref:proposals/VK_KHR_video_queue.adoc[] ** xref:proposals/VK_LUNARG_direct_driver_loading.adoc[] ** xref:proposals/VK_MSFT_layered_driver.adoc[] +** xref:proposals/VK_NV_ray_tracing_validation.adoc[] ** xref:proposals/VK_QCOM_image_processing.adoc[] ** xref:proposals/VK_QCOM_tile_properties.adoc[] -* Extension Proposal Template -** xref:proposals/template.adoc[] diff --git a/antora/features/modules/features/pages/index.adoc b/antora/features/modules/features/pages/index.adoc new file mode 100644 index 000000000..86ba71c09 --- /dev/null +++ b/antora/features/modules/features/pages/index.adoc @@ -0,0 +1,17 @@ +// Copyright 2022-2024 The Khronos Group Inc. +// SPDX-License-Identifier: CC-BY-4.0 + += Vulkan Feature Descriptions + +This component includes all published extension feature descriptions, as +well as the original rationale for the xref:proposals/Roadmap.adoc[Vulkan +Roadmap] process which resulted in the +xref:spec::appendices/roadmap.adoc[Roadmap 2022 and Roadmap 2024] milestones. + +When a Vulkan extension begins development, a "`proposal`" document is +written outlining the proposed API. +The proposal is the basis from which specification language is written. + +When the extension is published, the proposal - now referred to as a +"`feature description`" - is retained to act as supplementary documentation +on that extension. diff --git a/antora/modules/ROOT/pages/index.adoc b/antora/modules/ROOT/pages/index.adoc deleted file mode 100644 index 201a1866b..000000000 --- a/antora/modules/ROOT/pages/index.adoc +++ /dev/null @@ -1,44 +0,0 @@ -// Copyright 2022-2024 The Khronos Group Inc. -// SPDX-License-Identifier: CC-BY-4.0 - -= Vulkan Documentation - -include::{config}/attribs.adoc[] -include::{generated}/specattribs.adoc[] - -== About - -link:https://docs.vulkan.org/[This site] gathers together several key -Vulkan documents including specifications, guides, tutorials and samples -into a single site allowing for easy cross-searching and cross-linking -across documents to help navigate quickly to the information you need -for developing Vulkan-based applications. - -For more details about and resources for using the Vulkan graphics API, -see the Vulkan developer website at https://vulkan.org . - -This build of the site includes the Vulkan {SPECREVISION} API specification -{APITITLE}, generated on {SPECDATE} {SPECREMARK}. - -== Navigation - -The left sidebar links to pages in the current spec. -Proposals are available at the bottom of the sidebar links for the spec. - -The right sidebar is sections within the current page. - -The bottom-left button switches between the various documentation modules and specs. - -The top contains a text searchbar. -It will suggest matches to search terms found in all the modules of the -site. - -== Site Information - -link:https://docs.vulkan.org/[This site] is generated using the -link:https://docs.antora.org/[Antora] static site generator. - -If you need to report a problem or build the site yourself, start with -the -link:https://github.com/KhronosGroup/Vulkan-Site/[Vulkan-Site] -repository on GitHub. diff --git a/antora/modules/proposals/pages/index.adoc b/antora/modules/proposals/pages/index.adoc deleted file mode 100644 index cd48bb7a0..000000000 --- a/antora/modules/proposals/pages/index.adoc +++ /dev/null @@ -1,8 +0,0 @@ -// Copyright 2022-2024 The Khronos Group Inc. -// SPDX-License-Identifier: CC-BY-4.0 - -= Vulkan Proposals Start Page - -The Proposals module includes the Vulkan Roadmap, the Vulkan 2022 Profile -Roadmap, and all published extension proposals. - diff --git a/antora/setup_vulkan b/antora/setup_vulkan deleted file mode 100755 index 2a15a4531..000000000 --- a/antora/setup_vulkan +++ /dev/null @@ -1,57 +0,0 @@ -#!/bin/bash -# Copyright 2014-2024 The Khronos Group Inc. -# SPDX-License-Identifier: Apache-2.0 - -# setup_vulkan - configure Vulkan spec antora tree with generated files - -vkspec=/home/tree/git/vulkan - -cd $vkspec - -# Branch selection may come later. For now, use the current branch -# git checkout antora - -set -x - -if true ; then - # Generate intermediate files (for rewriting) and HTML target (for - #scanning anchors) - makeSpec QUIET=@ -clean -spec all \ - -genpath gen \ - generated jsapi html - - # Generate the map (anchor name -> [ chapter anchor, anchor title ] - # (xrefMap.py / xrefMap.cjs) from spec HTML - scripts/map_html_anchors.py gen/out/html/vkspec.html -pyfile antora/xrefMap.py -jsfile antora/xrefMap.cjs -fi - -# Rewrite spec sources and images into module directory - -# Module directory -dir=modules - -# ROOT component - Vulkan spec -# Page headers are added to pull in required attributes -# Also creates pageMap.cjs for use by the Antora version of the spec macros -component=$vkspec/antora/${dir}/ROOT -scripts/antora-prep.py \ - -root . \ - -component $component \ - -xrefpath antora \ - -pageHeaders antora/pageHeaders-spec.adoc \ - -pagemappath antora/modules/ROOT/partials/gen/pageMap.cjs \ - ./config/attribs.adoc \ - ./config/copyright-ccby.adoc \ - ./config/copyright-spec.adoc \ - ./images/*.svg \ - `find ./gen ./chapters ./appendices -name '[A-Za-z]*.adoc'` \ - ./gen/apimap.cjs - -# proposals component - Vulkan extension proposals -# No pageHeaders required. -component=$vkspec/antora/${dir}/proposals -scripts/antora-prep.py \ - -root . \ - -component $component \ - -xrefpath antora \ - `find ./proposals -name '[A-Za-z]*.adoc'` diff --git a/antora/antora.yml b/antora/spec/antora.yml similarity index 86% rename from antora/antora.yml rename to antora/spec/antora.yml index 5def9916b..e0ca13ca8 100644 --- a/antora/antora.yml +++ b/antora/spec/antora.yml @@ -2,7 +2,7 @@ # SPDX-License-Identifier: Apache-2.0 name: spec -title: Vulkan Specification and Proposals +title: Vulkan Specification version: latest # stem (latexmath) support is provided by the @djencks/asciidoctor-mathjax # extension, loaded in the playbook. @@ -14,10 +14,9 @@ asciidoc: appendices: partial$appendices generated: partial$gen images: image$ -# Not supported for SVG yet - see https://gitlab.com/antora/antora/-/issues/536 +# Not supported for SVG yet - see https://gitlab.com/antora/antora/-/issues/1001 # imageopts: inline imageopts: '' refprefix: '' nav: - modules/ROOT/nav.adoc -- modules/proposals/nav.adoc diff --git a/antora/modules/ROOT/nav.adoc b/antora/spec/modules/ROOT/nav.adoc similarity index 100% rename from antora/modules/ROOT/nav.adoc rename to antora/spec/modules/ROOT/nav.adoc diff --git a/antora/spec/modules/ROOT/pages/index.adoc b/antora/spec/modules/ROOT/pages/index.adoc new file mode 100644 index 000000000..2aea0b3be --- /dev/null +++ b/antora/spec/modules/ROOT/pages/index.adoc @@ -0,0 +1,52 @@ +// Copyright 2022-2024 The Khronos Group Inc. +// SPDX-License-Identifier: CC-BY-4.0 + += Vulkan Documentation + +include::{config}/attribs.adoc[] +include::{generated}/specattribs.adoc[] + + +== About + +link:https://docs.vulkan.org/[This site] gathers together several key Vulkan +documents including specifications, extension proposals, guides, tutorials +and samples into a single site. +This allows searching and cross-linking across documents, to help navigate +quickly to the information you need for developing Vulkan-based +applications. + +For more information about and resources for using the Vulkan graphics API, +see the Vulkan developer website at https://vulkan.org . + +This build of the site includes the Vulkan {SPECREVISION} API specification +{APITITLE}, generated on {SPECDATE} {SPECREMARK}. + + +== Navigation + +The site is organized in "`components`" (Antora terminology for +specifications and other documents), each containing many "`pages`" (Antora +terminology for a chapter of a specification, or other distinct piece of +content for other components). + +The left navigation sidebar links to pages in the current component. + +The right navigation sidebar links to sections in the current page. + +The bottom-left button switches between components. + +The top navigation bar contains a text searchbox. +If the "`In this component`" box is checked, search will be restricted to +the current component. +Otherwise, all components of the site are searched. + + +== Site Information + +link:https://docs.vulkan.org/[This site] is generated using the +link:https://docs.antora.org/[Antora] static site generator. + +If you need to report a problem or build the site yourself, start with the +link:https://github.com/KhronosGroup/Vulkan-Site/[Vulkan-Site] repository on +GitHub. diff --git a/appendices/VK_ARM_scheduling_controls.adoc b/appendices/VK_ARM_scheduling_controls.adoc index cb89d575e..c6d97d235 100644 --- a/appendices/VK_ARM_scheduling_controls.adoc +++ b/appendices/VK_ARM_scheduling_controls.adoc @@ -20,7 +20,7 @@ include::{generated}/meta/{refprefix}VK_ARM_scheduling_controls.adoc[] === Description This extension exposes a collection of controls to modify the scheduling -behaviour of Arm Mali devices. +behavior of Arm Mali devices. include::{generated}/interfaces/VK_ARM_scheduling_controls.adoc[] diff --git a/appendices/VK_ARM_shader_core_builtins.adoc b/appendices/VK_ARM_shader_core_builtins.adoc index 72c5820e1..4a807065d 100644 --- a/appendices/VK_ARM_shader_core_builtins.adoc +++ b/appendices/VK_ARM_shader_core_builtins.adoc @@ -28,8 +28,8 @@ This extension enables support for the SPIR-V code:CoreBuiltinsARM capability. These properties and built-ins can be used for debugging or performance -optimisation purposes. -A typical optimisation example would be to use code:CoreIDARM to select a +optimization purposes. +A typical optimization example would be to use code:CoreIDARM to select a per-shader-core instance of a data structure in algorithms that use atomics so as to reduce contention. diff --git a/appendices/VK_EXT_debug_marker.adoc b/appendices/VK_EXT_debug_marker.adoc index 7e6d9a78b..9d520161d 100644 --- a/appendices/VK_EXT_debug_marker.adoc +++ b/appendices/VK_EXT_debug_marker.adoc @@ -62,7 +62,7 @@ objects in error messages. *Example 2* Annotating regions of a workload with naming information so that offline -analysis tools can display a more usable visualisation of the commands +analysis tools can display a more usable visualization of the commands submitted. [source,c++] @@ -144,7 +144,7 @@ and flink:vkCmdDebugMarkerEndEXT support the ability to specify a color? *RESOLVED*: Yes. The functions have been expanded to take an optional color which can be used at will by implementations consuming the command buffer annotations in their -visualisation. +visualization. 3) Should the functions added in this extension accept an extensible structure as their parameter for a more flexible API, as opposed to direct @@ -166,7 +166,7 @@ information in the same commands. ** Minor language tweaks and edits * Revision 3, 2016-04-23 (Baldur Karlsson) - ** Reorganise spec layout to closer match desired organisation + ** Reorganize spec layout to closer match desired organization ** Added optional color to markers (both regions and inserted labels) ** Changed functions to take extensible structs instead of direct function parameters diff --git a/appendices/VK_EXT_depth_range_unrestricted.adoc b/appendices/VK_EXT_depth_range_unrestricted.adoc index d9ce6f5e1..02b7ba213 100644 --- a/appendices/VK_EXT_depth_range_unrestricted.adoc +++ b/appendices/VK_EXT_depth_range_unrestricted.adoc @@ -45,7 +45,7 @@ the `0.0` to `1.0` range. *RESOLVED*: This situation can also arise without this extension (when fragment shaders replace depth values, for example), and this extension does -not change the behaviour, which is defined in the <> section of the Fragment Operations chapter. === Version History diff --git a/appendices/VK_EXT_device_address_binding_report.adoc b/appendices/VK_EXT_device_address_binding_report.adoc index 8211bccbe..d1f8f9535 100644 --- a/appendices/VK_EXT_device_address_binding_report.adoc +++ b/appendices/VK_EXT_device_address_binding_report.adoc @@ -102,7 +102,7 @@ be bound, and then subregions unbound, resulting in fragmentation? *RESOLVED*: Splitting of virtual address regions, and unmatched bind/unbind callbacks may occur. -Developers should anticipate that sparse memory may exhibit this behaviour. +Developers should anticipate that sparse memory may exhibit this behavior. 10.) The specification mandates that a callback must: be triggered whenever a GPU virtual address range associated with any Vulkan object is bound or diff --git a/appendices/VK_EXT_global_priority.adoc b/appendices/VK_EXT_global_priority.adoc index 80ce3723b..5caad169a 100644 --- a/appendices/VK_EXT_global_priority.adoc +++ b/appendices/VK_EXT_global_priority.adoc @@ -26,7 +26,7 @@ priority. The default queue priority is ename:VK_QUEUE_GLOBAL_PRIORITY_MEDIUM_EXT. The driver implementation will attempt to skew hardware resource allocation -in favour of the higher-priority task. +in favor of the higher-priority task. Therefore, higher-priority work may retain similar latency and throughput characteristics even if the system is congested with lower priority work. diff --git a/appendices/VK_EXT_headless_surface.adoc b/appendices/VK_EXT_headless_surface.adoc index 5c60e2b1b..b04cd05cc 100644 --- a/appendices/VK_EXT_headless_surface.adoc +++ b/appendices/VK_EXT_headless_surface.adoc @@ -22,14 +22,14 @@ The presentation operation for a swapchain created from a headless surface is by default a no-op, resulting in no externally-visible result. Because there is no real presentation target, future extensions can layer on -top of the headless surface to introduce arbitrary or customisable sets of +top of the headless surface to introduce arbitrary or customizable sets of restrictions or features. These could include features like saving to a file or restrictions to emulate a particular presentation target. This functionality is expected to be useful for application and driver development because it allows any platform to expose an arbitrary or -customisable set of restrictions and features of a presentation engine. +customizable set of restrictions and features of a presentation engine. This makes it a useful portable test target for applications targeting a wide range of presentation engines where the actual target presentation engines might be scarce, unavailable or otherwise undesirable or diff --git a/appendices/VK_EXT_legacy_dithering.adoc b/appendices/VK_EXT_legacy_dithering.adoc index d8fe24f1a..e7bfb107f 100644 --- a/appendices/VK_EXT_legacy_dithering.adoc +++ b/appendices/VK_EXT_legacy_dithering.adoc @@ -7,7 +7,7 @@ include::{generated}/meta/{refprefix}VK_EXT_legacy_dithering.adoc[] === Other Extension Metadata *Last Modified Date*:: - 2022-03-31 + 2024-02-22 *Contributors*:: - Shahbaz Youssefi, Google - Graeme Leese, Broadcom @@ -27,6 +27,8 @@ include::{generated}/interfaces/VK_EXT_legacy_dithering.adoc[] * Revision 1, 2022-03-31 (Shahbaz Youssefi) ** Internal revisions + * Revision 2, 2024-02-22 (Shahbaz Youssefi) + ** Added pipeline create flag to support dynamic rendering === Issues diff --git a/appendices/VK_EXT_legacy_vertex_attributes.adoc b/appendices/VK_EXT_legacy_vertex_attributes.adoc new file mode 100644 index 000000000..1c5c062f1 --- /dev/null +++ b/appendices/VK_EXT_legacy_vertex_attributes.adoc @@ -0,0 +1,47 @@ +// Copyright 2023-2024 The Khronos Group Inc. +// +// SPDX-License-Identifier: CC-BY-4.0 + +include::{generated}/meta/{refprefix}VK_EXT_legacy_vertex_attributes.adoc[] + +=== Other Extension Metadata + +*Last Modified Date*:: + 2024-02-23 +*IP Status*:: + No known IP claims. +*Contributors*:: + - Mike Blumenkrantz, Valve + - Piers Daniell, NVIDIA + - Spencer Fricke, LunarG + - Alyssa Rosenzweig, Valve + +=== Description + +This extension adds support for legacy features of (non-64-bit) vertex +attributes as found in OpenGL: + + - Vertex attributes loaded from arbitrary buffer alignments + - Vertex attributes using arbitrary strides + - Vertex attributes where the component data type of the binding does not + match the component numeric type of the shader input + +These features are only usable with dynamic vertex input. +Unaligned loads of vertex attributes may incur performance penalties, +indicated with a property. + +include::{generated}/interfaces/VK_EXT_legacy_vertex_attributes.adoc[] + +=== Issues + +1.) Should implementations convert float/integer values? + +*RESOLVED*: No. +When fetching an integer data type from float values or float data types +from integer values, the resulting shader values are +implementation-dependent. + +=== Version History + + * Revision 1, 2024-02-16 (Mike Blumenkrantz) + ** Initial revision diff --git a/appendices/VK_EXT_load_store_op_none.adoc b/appendices/VK_EXT_load_store_op_none.adoc index 0eebcf844..5e0148452 100644 --- a/appendices/VK_EXT_load_store_op_none.adoc +++ b/appendices/VK_EXT_load_store_op_none.adoc @@ -37,6 +37,15 @@ functionality. include::{generated}/interfaces/VK_EXT_load_store_op_none.adoc[] +[NOTE] +.Note +==== +While ename:VK_ATTACHMENT_STORE_OP_NONE is part of Vulkan 1.3, this +extension was not promoted to core either in whole or in part. +This functionality was promoted from `apiext:VK_KHR_dynamic_rendering`. +==== + + === Version History * Revision 1, 2021-06-06 (Shahbaz Youssefi) diff --git a/appendices/VK_EXT_mesh_shader.adoc b/appendices/VK_EXT_mesh_shader.adoc index d19a86598..70a8842ed 100644 --- a/appendices/VK_EXT_mesh_shader.adoc +++ b/appendices/VK_EXT_mesh_shader.adoc @@ -10,7 +10,7 @@ include::{generated}/meta/{refprefix}VK_EXT_mesh_shader.adoc[] 2022-01-20 *Interactions and External Dependencies*:: - This extension provides API support for - https://github.com/KhronosGroup/GLSL/blob/master/extensions/ext/GLSL_EXT_mesh_shader.txt[`GLSL_EXT_mesh_shader`] + https://github.com/KhronosGroup/GLSL/blob/main/extensions/ext/GLSL_EXT_mesh_shader.txt[`GLSL_EXT_mesh_shader`] - Interacts with Vulkan 1.1 - Interacts with `apiext:VK_KHR_multiview` - Interacts with `apiext:VK_KHR_fragment_shading_rate` diff --git a/appendices/VK_EXT_metal_objects.adoc b/appendices/VK_EXT_metal_objects.adoc index 6d6d1ba9f..e444a52ad 100644 --- a/appendices/VK_EXT_metal_objects.adoc +++ b/appendices/VK_EXT_metal_objects.adoc @@ -7,7 +7,7 @@ include::{generated}/meta/{refprefix}VK_EXT_metal_objects.adoc[] === Other Extension Metadata *Last Modified Date*:: - 2022-05-28 + 2024-04-04 *IP Status*:: No known IP claims. *Contributors*:: @@ -46,3 +46,7 @@ None. VkDeviceMemory, added export of MTLSharedEvent, added import of MTLSharedEvent for VkSemaphore and VkEvent, and changed used bit mask fields to individual bit fields to simplify Valid Usage rules. + * Revision 2, 2024-04-04 (Bill Hollings) + ** Add an code:__unsafe_unretained ownership qualifier to all Metal object + declarations, to support Automatic Reference Counting (ARC) on Apple + devices. diff --git a/appendices/VK_EXT_shader_tile_image.adoc b/appendices/VK_EXT_shader_tile_image.adoc index bfccc4d17..e0d6b9de3 100644 --- a/appendices/VK_EXT_shader_tile_image.adoc +++ b/appendices/VK_EXT_shader_tile_image.adoc @@ -12,7 +12,7 @@ include::{generated}/meta/{refprefix}VK_EXT_shader_tile_image.adoc[] No known IP claims. *Interactions and External Dependencies*:: - This extension provides API support for - https://raw.githubusercontent.com/KhronosGroup/GLSL/master/extensions/ext/GLSL_EXT_shader_tile_image.txt[`GL_EXT_shader_tile_image`] + https://raw.githubusercontent.com/KhronosGroup/GLSL/main/extensions/ext/GLSL_EXT_shader_tile_image.txt[`GL_EXT_shader_tile_image`] *Contributors*:: - Sandeep Kakarlapudi, Arm - Jan-Harald Fredriksen, Arm diff --git a/appendices/VK_EXT_shader_viewport_index_layer.adoc b/appendices/VK_EXT_shader_viewport_index_layer.adoc index 41a39e57e..b4cdcee29 100644 --- a/appendices/VK_EXT_shader_viewport_index_layer.adoc +++ b/appendices/VK_EXT_shader_viewport_index_layer.adoc @@ -36,7 +36,7 @@ shaders, using the code:ShaderViewportIndexLayerEXT capability. When using GLSL source-based shading languages, the code:gl_ViewportIndex and code:gl_Layer built-in variables map to the SPIR-V code:ViewportIndex and code:Layer built-in decorations, respectively. -Behaviour of these variables is extended as described in the +Behavior of these variables is extended as described in the `GL_ARB_shader_viewport_layer_array` (or the precursor `GL_AMD_vertex_shader_layer`, `GL_AMD_vertex_shader_viewport_index`, and `GL_NV_viewport_array2` extensions). diff --git a/appendices/VK_GOOGLE_display_timing.adoc b/appendices/VK_GOOGLE_display_timing.adoc index 442829a65..c41a6a6a2 100644 --- a/appendices/VK_GOOGLE_display_timing.adoc +++ b/appendices/VK_GOOGLE_display_timing.adoc @@ -49,7 +49,7 @@ The example code for the this extension (like the `apiext:VK_KHR_surface` and `VK_GOOGLE_display_timing` extensions) is contained in the cube demo that is shipped with the official Khronos SDK, and is being kept up-to-date in that location (see: -https://github.com/KhronosGroup/Vulkan-Tools/blob/master/cube/cube.c ). +https://github.com/KhronosGroup/Vulkan-Tools/blob/main/cube/cube.c ). ==== === Version History diff --git a/appendices/VK_KHR_deferred_host_operations.adoc b/appendices/VK_KHR_deferred_host_operations.adoc index c898a2cf8..0f3aed2ba 100644 --- a/appendices/VK_KHR_deferred_host_operations.adoc +++ b/appendices/VK_KHR_deferred_host_operations.adoc @@ -135,7 +135,7 @@ VkResult FinishDeferredOperation(VkDeferredOperationKHR hOp) { case VK_SUCCESS: { - // deferred operation has finished. Query its result + // deferred operation has finished. Query its result. result = vkGetDeferredOperationResultKHR(device, hOp); } break; diff --git a/appendices/VK_KHR_display.adoc b/appendices/VK_KHR_display.adoc index 41c2c9e54..e6a8c538b 100644 --- a/appendices/VK_KHR_display.adoc +++ b/appendices/VK_KHR_display.adoc @@ -205,7 +205,7 @@ after revision 1.0.43. The display enumeration example code was ported to the cube demo that is shipped with the official Khronos SDK, and is being kept up-to-date in that location (see: -https://github.com/KhronosGroup/Vulkan-Tools/blob/master/cube/cube.c). +https://github.com/KhronosGroup/Vulkan-Tools/blob/main/cube/cube.c). ==== endif::VKSC_VERSION_1_0[] diff --git a/appendices/VK_KHR_display_swapchain.adoc b/appendices/VK_KHR_display_swapchain.adoc index 51ab59b82..8a1264b7f 100644 --- a/appendices/VK_KHR_display_swapchain.adoc +++ b/appendices/VK_KHR_display_swapchain.adoc @@ -81,7 +81,7 @@ revision 1.0.43. The display swapchain creation example code was ported to the cube demo that is shipped with the official Khronos SDK, and is being kept up-to-date in that location (see: -https://github.com/KhronosGroup/Vulkan-Tools/blob/master/cube/cube.c). +https://github.com/KhronosGroup/Vulkan-Tools/blob/main/cube/cube.c). ==== endif::VKSC_VERSION_1_0[] diff --git a/appendices/VK_KHR_external_memory_win32.adoc b/appendices/VK_KHR_external_memory_win32.adoc index adfdc4a13..88956cf19 100644 --- a/appendices/VK_KHR_external_memory_win32.adoc +++ b/appendices/VK_KHR_external_memory_win32.adoc @@ -33,21 +33,12 @@ include::{generated}/interfaces/VK_KHR_external_memory_win32.adoc[] from flink:vkGetMemoryWin32HandleKHR when pname:handleType is ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT_KHR? -ifdef::editing-notes[] -[NOTE] -.editing-note -==== -(Jon) This issue refers to a token from -`apiext:VK_KHR_external_semaphore_win32`, but there is no dependency or -interaction with that extension defined above. -==== -endif::editing-notes[] - -*RESOLVED*: Yes, unless it is passed back in to another driver instance to -import the object. +*RESOLVED*: Yes. A successful get call transfers ownership of the handle to the application. Destroying the memory object will not destroy the handle or the handle's reference to the underlying memory resource. +Unlike file descriptor opaque handles, win32 opaque handle ownership can not +be transferred back to a driver by an import operation. 2) Should the language regarding KMT/Windows 7 handles be moved to a separate extension so that it can be deprecated over time? diff --git a/appendices/VK_KHR_external_semaphore_win32.adoc b/appendices/VK_KHR_external_semaphore_win32.adoc index 6acd4d286..1a65213d3 100644 --- a/appendices/VK_KHR_external_semaphore_win32.adoc +++ b/appendices/VK_KHR_external_semaphore_win32.adoc @@ -30,11 +30,12 @@ include::{generated}/interfaces/VK_KHR_external_semaphore_win32.adoc[] from flink:vkGetSemaphoreWin32HandleKHR when pname:handleType is ename:VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_BIT_KHR? -*RESOLVED*: Yes, unless it is passed back in to another driver instance to -import the object. +*RESOLVED*: Yes. A successful get call transfers ownership of the handle to the application. Destroying the semaphore object will not destroy the handle or the handle's reference to the underlying semaphore resource. +Unlike file descriptor opaque handles, win32 opaque handle ownership can not +be transferred back to a driver by an import operation. 2) Should the language regarding KMT/Windows 7 handles be moved to a separate extension so that it can be deprecated over time? diff --git a/appendices/VK_KHR_fragment_shader_barycentric.adoc b/appendices/VK_KHR_fragment_shader_barycentric.adoc index 0c25c5d9f..c2b71cdf3 100644 --- a/appendices/VK_KHR_fragment_shader_barycentric.adoc +++ b/appendices/VK_KHR_fragment_shader_barycentric.adoc @@ -12,7 +12,7 @@ include::{generated}/meta/{refprefix}VK_KHR_fragment_shader_barycentric.adoc[] No known IP claims. *Interactions and External Dependencies*:: - This extension provides API support for - https://github.com/KhronosGroup/GLSL/blob/master/extensions/ext/GLSL_EXT_fragment_shader_barycentric.txt[`GL_EXT_fragment_shader_barycentric`] + https://github.com/KhronosGroup/GLSL/blob/main/extensions/ext/GLSL_EXT_fragment_shader_barycentric.txt[`GL_EXT_fragment_shader_barycentric`] *Contributors*:: - Stu Smith, AMD - Tobias Hector, AMD diff --git a/appendices/VK_KHR_global_priority.adoc b/appendices/VK_KHR_global_priority.adoc index 9072f92cf..03102d86b 100644 --- a/appendices/VK_KHR_global_priority.adoc +++ b/appendices/VK_KHR_global_priority.adoc @@ -29,7 +29,7 @@ It is intended primarily for use in system integration along with certain platform-specific priority enforcement rules. The driver implementation will attempt to skew hardware resource allocation -in favour of the higher-priority task. +in favor of the higher-priority task. Therefore, higher-priority work may retain similar latency and throughput characteristics even if the system is congested with lower priority work. diff --git a/appendices/VK_KHR_load_store_op_none.adoc b/appendices/VK_KHR_load_store_op_none.adoc index 586d279ba..77ff77b8a 100644 --- a/appendices/VK_KHR_load_store_op_none.adoc +++ b/appendices/VK_KHR_load_store_op_none.adoc @@ -21,6 +21,14 @@ the `apiext:VK_EXT_load_store_op_none` extension. include::{generated}/interfaces/VK_KHR_load_store_op_none.adoc[] +[NOTE] +.Note +==== +While ename:VK_ATTACHMENT_STORE_OP_NONE is part of Vulkan 1.3, this +extension was not promoted to core either in whole or in part. +This functionality was promoted from `apiext:VK_KHR_dynamic_rendering`. +==== + === Version History * Revision 1, 2023-05-16 (Shahbaz Youssefi) diff --git a/appendices/VK_KHR_portability_subset.adoc b/appendices/VK_KHR_portability_subset.adoc index 7eff69693..9b98648f9 100644 --- a/appendices/VK_KHR_portability_subset.adoc +++ b/appendices/VK_KHR_portability_subset.adoc @@ -30,7 +30,7 @@ fully-conformant native Vulkan implementation. This extension provides Vulkan implementations with the ability to mark otherwise-required capabilities as unsupported, or to establish additional properties and limits that the application should adhere to in order to -guarantee portable behaviour and operation across platforms, including +guarantee portable behavior and operation across platforms, including platforms where Vulkan is not natively supported. The goal of this specification is to document, and make queryable, diff --git a/appendices/VK_KHR_ray_tracing_position_fetch.adoc b/appendices/VK_KHR_ray_tracing_position_fetch.adoc index 2ec9393db..ea5ad60e5 100644 --- a/appendices/VK_KHR_ray_tracing_position_fetch.adoc +++ b/appendices/VK_KHR_ray_tracing_position_fetch.adoc @@ -48,6 +48,7 @@ include::{generated}/interfaces/VK_KHR_ray_tracing_position_fetch.adoc[] === New SPIR-V Capabilities * <> + * <> === Issues diff --git a/appendices/VK_KHR_shader_float_controls.adoc b/appendices/VK_KHR_shader_float_controls.adoc index 83e636839..5f1833774 100644 --- a/appendices/VK_KHR_shader_float_controls.adoc +++ b/appendices/VK_KHR_shader_float_controls.adoc @@ -103,7 +103,7 @@ facet of the extension, we ended up with two different behaviors in the wild, where some implementations worked as written, and others worked based on the naming. As these are hard limits in hardware with reasons for exposure as written, -it was not possible to standardise on a single way to make this work within +it was not possible to standardize on a single way to make this work within the existing API. No known users of this part of the extension exist in the wild, and as such diff --git a/appendices/VK_KHR_shader_float_controls2.adoc b/appendices/VK_KHR_shader_float_controls2.adoc index ecd9d2017..b766e3972 100644 --- a/appendices/VK_KHR_shader_float_controls2.adoc +++ b/appendices/VK_KHR_shader_float_controls2.adoc @@ -18,7 +18,7 @@ include::{generated}/meta/{refprefix}VK_KHR_shader_float_controls2.adoc[] This extension enables use of the more expressive fast floating-point math flags in the SPV_KHR_float_controls2 extension. -These flags give finer- grained control over which optimisations compilers +These flags give finer- grained control over which optimizations compilers may apply, potentially speeding up execution while retaining correct results. diff --git a/appendices/VK_KHR_shader_maximal_reconvergence.adoc b/appendices/VK_KHR_shader_maximal_reconvergence.adoc index b8e7d63e6..77b1ea1de 100644 --- a/appendices/VK_KHR_shader_maximal_reconvergence.adoc +++ b/appendices/VK_KHR_shader_maximal_reconvergence.adoc @@ -36,10 +36,6 @@ other tangled instructions. include::{generated}/interfaces/VK_KHR_shader_maximal_reconvergence.adoc[] -=== New SPIR-V Capabilities - - * <> - === Version History * Revision 1, 2021-11-12 (Alan Baker) diff --git a/appendices/VK_KHR_surface.adoc b/appendices/VK_KHR_surface.adoc index 2332a6b06..273a7c0a0 100644 --- a/appendices/VK_KHR_surface.adoc +++ b/appendices/VK_KHR_surface.adoc @@ -49,7 +49,7 @@ The example code for the `VK_KHR_surface` and `apiext:VK_KHR_swapchain` extensions was removed from the appendix after revision 1.0.29. This WSI example code was ported to the cube demo that is shipped with the official Khronos SDK, and is being kept up-to-date in that location (see: -https://github.com/KhronosGroup/Vulkan-Tools/blob/master/cube/cube.c). +https://github.com/KhronosGroup/Vulkan-Tools/blob/main/cube/cube.c). ==== endif::VKSC_VERSION_1_0[] diff --git a/appendices/VK_KHR_swapchain.adoc b/appendices/VK_KHR_swapchain.adoc index c2990422b..30d9eaa25 100644 --- a/appendices/VK_KHR_swapchain.adoc +++ b/appendices/VK_KHR_swapchain.adoc @@ -417,7 +417,7 @@ The example code for the `apiext:VK_KHR_surface` and `VK_KHR_swapchain` extensions was removed from the appendix after revision 1.0.29. This WSI example code was ported to the cube demo that is shipped with the official Khronos SDK, and is being kept up-to-date in that location (see: -https://github.com/KhronosGroup/Vulkan-Tools/blob/master/cube/cube.c). +https://github.com/KhronosGroup/Vulkan-Tools/blob/main/cube/cube.c). ==== endif::VKSC_VERSION_1_0[] diff --git a/appendices/VK_MESA_image_alignment_control.adoc b/appendices/VK_MESA_image_alignment_control.adoc new file mode 100644 index 000000000..d67ae3f01 --- /dev/null +++ b/appendices/VK_MESA_image_alignment_control.adoc @@ -0,0 +1,46 @@ +// Copyright 2024 The Khronos Group Inc. +// +// SPDX-License-Identifier: CC-BY-4.0 + +include::{generated}/meta/{refprefix}VK_MESA_image_alignment_control.adoc[] + +=== Other Extension Metadata + +*Last Modified Date*:: + 2024-05-03 +*IP Status*:: + No known IP claims. +*Contributors*:: + - Hans-Kristian Arntzen, Valve + +=== Description + +This extension allows applications to request a narrower alignment for +images than an implementation would otherwise require. +Some implementations internally support multiple image layouts in +ename:VK_IMAGE_TILING_OPTIMAL, each with different alignment requirements +and performance trade-offs. +In some API layering use cases such as D3D12, it is beneficial to be able to +control the alignment, since certain alignments for placed resources are +guaranteed to be supported, and emulating that expectation requires +unnecessary padding of allocations. + +slink:VkImageAlignmentControlCreateInfoMESA can: be chained to +slink:VkImageCreateInfo, requesting that the alignment is no more than the +provided alignment. +If the requested alignment is not supported for a given +slink:VkImageCreateInfo, a larger alignment may: be returned. + +While something similar could be achieved with +`apiext:VK_EXT_image_drm_format_modifier` in theory, this is not the +intended way to use that extension. +Format modifiers are generally used for externally shareable images, and +would not be platform portable. +It is also a cumbersome API to use just to lower the alignment. + +include::{generated}/interfaces/VK_MESA_image_alignment_control.adoc[] + +=== Version History + + * Revision 1, 2024-04-05 (Hans-Kristian Arntzen) + ** Initial specification diff --git a/appendices/VK_NV_geometry_shader_passthrough.adoc b/appendices/VK_NV_geometry_shader_passthrough.adoc index c2c067b92..3c398b83d 100644 --- a/appendices/VK_NV_geometry_shader_passthrough.adoc +++ b/appendices/VK_NV_geometry_shader_passthrough.adoc @@ -42,7 +42,7 @@ qualifier from `GL_NV_geometry_shader_passthrough` maps to the code:PassthroughNV decoration. To use the code:passthrough layout, in GLSL the `GL_NV_geometry_shader_passthrough` extension must be enabled. -Behaviour is described in the `GL_NV_geometry_shader_passthrough` extension +Behavior is described in the `GL_NV_geometry_shader_passthrough` extension specification. include::{generated}/interfaces/VK_NV_geometry_shader_passthrough.adoc[] diff --git a/appendices/VK_NV_ray_tracing_invocation_reorder.adoc b/appendices/VK_NV_ray_tracing_invocation_reorder.adoc index a981e371d..6182bd23f 100644 --- a/appendices/VK_NV_ray_tracing_invocation_reorder.adoc +++ b/appendices/VK_NV_ray_tracing_invocation_reorder.adoc @@ -35,7 +35,7 @@ https://github.com/microsoft/DirectXShaderCompiler/wiki/GL_EXT_spirv_intrinsics- Intrinsics]. The codes for shader invocation reorder are obtained from -https://htmlpreview.github.io/?https://github.com/KhronosGroup/SPIRV-Registry/blob/master/extensions/NV/SPV_NV_shader_invocation_reorder.html[this +https://htmlpreview.github.io/?https://github.com/KhronosGroup/SPIRV-Registry/blob/main/extensions/NV/SPV_NV_shader_invocation_reorder.html[this page]: [source,c] diff --git a/appendices/VK_NV_viewport_array2.adoc b/appendices/VK_NV_viewport_array2.adoc index b9b7c0649..e882ebc3f 100644 --- a/appendices/VK_NV_viewport_array2.adoc +++ b/appendices/VK_NV_viewport_array2.adoc @@ -48,7 +48,7 @@ When using GLSL source-based shading languages, the code:gl_ViewportMask[] built-in output variable and code:viewport_relative layout qualifier from `GL_NV_viewport_array2` map to the code:ViewportMaskNV and code:ViewportRelativeNV decorations, respectively. -Behaviour is described in the `GL_NV_viewport_array2` extension +Behavior is described in the `GL_NV_viewport_array2` extension specification. ifdef::VK_EXT_shader_viewport_index_layer[] diff --git a/appendices/VK_QCOM_image_processing.adoc b/appendices/VK_QCOM_image_processing.adoc index cb7246a12..43505d803 100644 --- a/appendices/VK_QCOM_image_processing.adoc +++ b/appendices/VK_QCOM_image_processing.adoc @@ -58,9 +58,9 @@ The instructions do not-support sampling of mipmap, multi-plane, multi-layer, multi-sampled, or depth/stencil images. The instructions can be used in any shader stage. -Implementations of this this extension should support these operations -natively at the HW instruction level, offering potential performance gains -as well as ease of development. +Implementations of this extension should support these operations natively +at the HW instruction level, offering potential performance gains as well as +ease of development. include::{generated}/interfaces/VK_QCOM_image_processing.adoc[] diff --git a/appendices/VK_QCOM_image_processing2.adoc b/appendices/VK_QCOM_image_processing2.adoc index c9f2d0152..131ec3215 100644 --- a/appendices/VK_QCOM_image_processing2.adoc +++ b/appendices/VK_QCOM_image_processing2.adoc @@ -25,7 +25,7 @@ It builds on the functionality of QCOM_image_processing with the addition of * The code:opImageBlockMatchWindowSADQCOM` SPIR-V instruction builds upon the functionality of code:opImageBlockMatchSADQCOM` by repeatedly performing block match operations across a 2D window. - The "`2D windowExtent`" and "`compareMode`" are are specified by + The "`2D windowExtent`" and "`compareMode`" are specified by slink:VkSamplerBlockMatchWindowCreateInfoQCOM in the sampler used to create the _target image_. Like code:OpImageBlockMatchSADQCOM, code:opImageBlockMatchWindowSADQCOM diff --git a/appendices/VK_QCOM_multiview_per_view_viewports.adoc b/appendices/VK_QCOM_multiview_per_view_viewports.adoc index a064e3251..3ffc20434 100644 --- a/appendices/VK_QCOM_multiview_per_view_viewports.adoc +++ b/appendices/VK_QCOM_multiview_per_view_viewports.adoc @@ -36,7 +36,7 @@ include::{generated}/interfaces/VK_QCOM_multiview_per_view_viewports.adoc[] === Issues -1) Is is possible to enable/disable the +1) Is it possible to enable/disable the <> feature for individual render pass instances? @@ -45,16 +45,16 @@ vkCreateDevice, then all created render pass instances (including dynamic render passes from `apiext:VK_KHR_dynamic_rendering`) and all created VkPipelines will have the feature enabled. This approach was chosen because it simplifies application code and there is -no known use case enable/disable the feature for individual render passes or -pipelines. +no known use case to enable/disable the feature for individual render passes +or pipelines. 2) When this extension is used, is the value of code:ViewportIndex implicitly written by the last pre-rasterization shader stage and can the value of code:ViewportIndex be read in the fragment shader? -*RESOLVED*: No, use of the extension extension does not add an implicit -write to code:ViewportIndex in any shader stage, and additionally, the value -of code:ViewportIndex in the fragment shader is undefined. +*RESOLVED*: No, use of the extension does not add an implicit write to +code:ViewportIndex in any shader stage, and additionally, the value of +code:ViewportIndex in the fragment shader is undefined. === Version History diff --git a/appendices/VK_QCOM_render_pass_transform.adoc b/appendices/VK_QCOM_render_pass_transform.adoc index 9d65ecd08..99934b987 100644 --- a/appendices/VK_QCOM_render_pass_transform.adoc +++ b/appendices/VK_QCOM_render_pass_transform.adoc @@ -114,10 +114,10 @@ uint32_t minor = ((driverVersion) >> 12) & 0x3ff); uint32_t patch = ((driverVersion) & 0xfff); ---- -If the Adreno major.minor.patch version is greater than or equal to to +If the Adreno major.minor.patch version is greater than or equal to 512.469.0, then simply use the VK_STRUCTURE_TYPE values as defined in vulkan_core.h. -If the version is less than or equal to to 512.468.0, then use the alternate +If the version is less than or equal to 512.468.0, then use the alternate values for the two VK_STRUCTURE_TYPEs in the table below. .fname:Adreno Driver Requirements diff --git a/appendices/VK_SEC_amigo_profiling.adoc b/appendices/VK_SEC_amigo_profiling.adoc index c8638fd94..489a22893 100644 --- a/appendices/VK_SEC_amigo_profiling.adoc +++ b/appendices/VK_SEC_amigo_profiling.adoc @@ -19,8 +19,8 @@ include::{generated}/meta/{refprefix}VK_SEC_amigo_profiling.adoc[] This extension is intended to communicate information from layered API implementations such as ANGLE to internal proprietary system schedulers. -It has no behavioural implications beyond enabling more intelligent -behaviour from the system scheduler. +It has no behavioral implications beyond enabling more intelligent behavior +from the system scheduler. Application developers should avoid using this extension. It is documented solely for the benefit of tools and layer developers, who diff --git a/appendices/spirvenv.adoc b/appendices/spirvenv.adoc index 9be150968..9ecb51023 100644 --- a/appendices/spirvenv.adoc +++ b/appendices/spirvenv.adoc @@ -296,15 +296,15 @@ or knowledge of runtime information, such as enabled features. code:OpImageQuerySizeLod, code:OpImageQueryLod, and code:OpImageQueryLevels must: only consume an "`Image`" operand whose type has its "`Sampled`" operand set to 1 + * [[VUID-{refpage}-OpTypeImage-09638]] + An code:OpTypeImage must: not have a "`Dim`" operand of code:Rect * [[VUID-{refpage}-OpTypeImage-06214]] An code:OpTypeImage with a "`Dim`" operand of code:SubpassData must: have an "`Arrayed`" operand of 0 (non-arrayed) and a "`Sampled`" operand of 2 (storage image) * [[VUID-{refpage}-SubpassData-04660]] The [eq]#(u,v)# coordinates used for a code:SubpassData must: be the - of a constant vector [eq]#(0,0)#, or if a layer coordinate is used, - must: be a vector that was formed with constant 0 for the [eq]#u# and - [eq]#v# components + of a constant vector [eq]#(0,0)#. * [[VUID-{refpage}-OpTypeImage-06924]] Objects of types code:OpTypeImage, code:OpTypeSampler, code:OpTypeSampledImage, code:OpTypeAccelerationStructureKHR, and arrays @@ -330,6 +330,12 @@ or knowledge of runtime information, such as enabled features. * [[VUID-{refpage}-BuiltIn-04668]] Any code:BuiltIn decoration not listed in <> must: not be used + * [[VUID-{refpage}-OpEntryPoint-09658]] + For a given code:OpEntryPoint, any code:BuiltIn decoration must: not be + used more than once by the code:Input interface. + * [[VUID-{refpage}-OpEntryPoint-09659]] + For a given code:OpEntryPoint, any code:BuiltIn decoration must: not be + used more than once by the code:Output interface. * [[VUID-{refpage}-Location-06672]] The code:Location or code:Component decorations must: only be used with the code:Input, code:Output, code:RayPayloadKHR, @@ -688,12 +694,12 @@ or knowledge of runtime information, such as enabled features. Interface>> * [[VUID-{refpage}-None-08724]] The code:TileImageEXT {StorageClass} must: only be used for declaring - tile image variables. + tile image variables * [[VUID-{refpage}-Pointer-08973]] The {StorageClass} of the code:Pointer operand to code:OpCooperativeMatrixLoadKHR or code:OpCooperativeMatrixStoreKHR must: be limited to code:Workgroup, code:StorageBuffer, or - code:PhysicalStorageBuffer. + code:PhysicalStorageBuffer **** -- @@ -756,6 +762,12 @@ ifndef::VK_KHR_dynamic_rendering_local_read[Any] variable created with a "`Type`" of code:OpTypeImage that has a "`Dim`" operand of code:SubpassData must: be decorated with code:InputAttachmentIndex +ifdef::VK_KHR_dynamic_rendering_local_read[] + * [[VUID-{refpage}-OpTypeImage-09644]] + Any variable created with a "`Type`" of code:OpTypeImage that has a + "`Dim`" operand of code:SubpassData and code:Arrayed=1 must: be + decorated with code:InputAttachmentIndex +endif::VK_KHR_dynamic_rendering_local_read[] ifdef::VK_VERSION_1_3[] ifndef::VK_KHR_format_feature_flags2[] * [[VUID-{refpage}-apiVersion-07952]] @@ -1152,60 +1164,60 @@ ifdef::VK_KHR_cooperative_matrix[] * [[VUID-{refpage}-OpTypeCooperativeMatrixKHR-08974]] For code:OpTypeCooperativeMatrixKHR, the component type, scope, number of rows, and number of columns must: match one of the matrices in any of - the supported slink:VkCooperativeMatrixPropertiesKHR. + the supported slink:VkCooperativeMatrixPropertiesKHR * [[VUID-{refpage}-MSize-08975]] For code:OpCooperativeMatrixMulAddKHR, the type of code:A must: have slink:VkCooperativeMatrixPropertiesKHR::pname:MSize rows and slink:VkCooperativeMatrixPropertiesKHR::pname:KSize columns and have a component type that matches - slink:VkCooperativeMatrixPropertiesKHR::pname:AType. + slink:VkCooperativeMatrixPropertiesKHR::pname:AType * [[VUID-{refpage}-OpCooperativeMatrixMulAddKHR-08976]] For code:OpCooperativeMatrixMulAddKHR, when the component type of code:A is a signed integer type, the code:MatrixASignedComponents cooperative - matrix operand must: be present. + matrix operand must: be present * [[VUID-{refpage}-KSize-08977]] For code:OpCooperativeMatrixMulAddKHR, the type of code:B must: have slink:VkCooperativeMatrixPropertiesKHR::pname:KSize rows and slink:VkCooperativeMatrixPropertiesKHR::pname:NSize columns and have a component type that matches - slink:VkCooperativeMatrixPropertiesKHR::pname:BType. + slink:VkCooperativeMatrixPropertiesKHR::pname:BType * [[VUID-{refpage}-OpCooperativeMatrixMulAddKHR-08978]] For code:OpCooperativeMatrixMulAddKHR, when the component type of code:B is a signed integer type, the code:MatrixBSignedComponents cooperative - matrix operand must: be present. + matrix operand must: be present * [[VUID-{refpage}-MSize-08979]] For code:OpCooperativeMatrixMulAddKHR, the type of code:C must: have slink:VkCooperativeMatrixPropertiesKHR::pname:MSize rows and slink:VkCooperativeMatrixPropertiesKHR::pname:NSize columns and have a component type that matches - slink:VkCooperativeMatrixPropertiesKHR::pname:CType. + slink:VkCooperativeMatrixPropertiesKHR::pname:CType * [[VUID-{refpage}-OpCooperativeMatrixMulAddKHR-08980]] For code:OpCooperativeMatrixMulAddKHR, when the component type of code:C is a signed integer type, the code:MatrixCSignedComponents cooperative - matrix operand must: be present. + matrix operand must: be present * [[VUID-{refpage}-MSize-08981]] For code:OpCooperativeMatrixMulAddKHR, the type of code:Result must: have slink:VkCooperativeMatrixPropertiesKHR::pname:MSize rows and slink:VkCooperativeMatrixPropertiesKHR::pname:NSize columns and have a component type that matches - slink:VkCooperativeMatrixPropertiesKHR::pname:ResultType. + slink:VkCooperativeMatrixPropertiesKHR::pname:ResultType * [[VUID-{refpage}-OpCooperativeMatrixMulAddKHR-08982]] For code:OpCooperativeMatrixMulAddKHR, when the component type of code:Result is a signed integer type, the code:MatrixResultSignedComponents cooperative matrix operand must: be - present. + present * [[VUID-{refpage}-saturatingAccumulation-08983]] For code:OpCooperativeMatrixMulAddKHR, the code:SaturatingAccumulation cooperative matrix operand must: be present if and only if slink:VkCooperativeMatrixPropertiesKHR::pname:saturatingAccumulation is - ename:VK_TRUE. + ename:VK_TRUE * [[VUID-{refpage}-scope-08984]] For code:OpCooperativeMatrixMulAddKHR, the type of code:A, code:B, - code:C, and code:Result must: all have a scope of pname:scope. + code:C, and code:Result must: all have a scope of pname:scope * [[VUID-{refpage}-cooperativeMatrixSupportedStages-08985]] code:OpTypeCooperativeMatrixKHR and code:OpCooperativeMatrix* instructions must: not be used in shader stages not included in - slink:VkPhysicalDeviceCooperativeMatrixPropertiesKHR::pname:cooperativeMatrixSupportedStages. + slink:VkPhysicalDeviceCooperativeMatrixPropertiesKHR::pname:cooperativeMatrixSupportedStages endif::VK_KHR_cooperative_matrix[] * [[VUID-{refpage}-DescriptorSet-06323]] code:DescriptorSet and code:Binding decorations must: obey the @@ -1362,7 +1374,7 @@ ifdef::VK_KHR_cooperative_matrix[] to at least the lesser of 16 bytes or the natural alignment of a row or column (depending on code:ColumnMajor) of the matrix (where the natural alignment is the number of columns/rows multiplied by the component - size). + size) endif::VK_KHR_cooperative_matrix[] ifdef::VK_KHR_portability_subset[] * [[VUID-{refpage}-shaderSampleRateInterpolationFunctions-06325]] @@ -1562,7 +1574,7 @@ endif::VK_VERSION_1_1[] pname:maxInterpolationOffset>> {plus} ULP ) - ULP# + where [eq]#frag~height~# is the height of the current fragment in pixels and [eq]#ULP = 1 / 2^<>^#. + pname:subPixelInterpolationOffsetBits>>^# ifdef::VK_KHR_ray_query[] * [[VUID-{refpage}-OpRayQueryInitializeKHR-06348]] @@ -2074,21 +2086,25 @@ ifdef::VK_QCOM_image_processing2[] If a code:OpImageBlockMatchWindow*QCOM operation is used, then code:target code:sampled code:image must: have been created using asampler object that included - slink:VkSamplerBlockMatchWindowCreateInfoQCOM in the pname:pNext chain. + slink:VkSamplerBlockMatchWindowCreateInfoQCOM in the pname:pNext chain endif::VK_QCOM_image_processing2[] ifdef::VK_KHR_shader_maximal_reconvergence[] * [[VUID-{refpage}-MaximallyReconvergesKHR-09565]] The execution mode code:MaximallyReconvergesKHR must: not be applied to an entry point unless the entry point does not execute any - <>. + <> endif::VK_KHR_shader_maximal_reconvergence[] ifdef::VK_KHR_shader_subgroup_rotate[] * [[VUID-{refpage}-shaderSubgroupRotateClustered-09566]] If <> is ename:VK_FALSE, then the code:ClusterSize operand to code:OpGroupNonUniformRotateKHR must: not be - used. + used endif::VK_KHR_shader_subgroup_rotate[] + * [[VUID-{refpage}-protectedNoFault-09645]] + If <> is not supported, + the {StorageClass} of the code:PhysicalStorageBuffer must: not be used + if the buffer being accessed is <> **** -- diff --git a/appendices/vulkanscdeviations.adoc b/appendices/vulkanscdeviations.adoc index b20acf64a..a4efa00d1 100644 --- a/appendices/vulkanscdeviations.adoc +++ b/appendices/vulkanscdeviations.adoc @@ -181,8 +181,8 @@ a framework for handling deviations. |Directive |4.6: "_typedefs_ that indicate size and signedness should be used in place of the basic numerical types" |Category |Advisory -|Note |This is reported for every `char` and `float` variable used in the - API. +|Note |This is reported for every code:char and code:float variable + used in the API. |Rationale |Vulkan SC maintains the Base Vulkan type conventions for compatibility between APIs. |=== diff --git a/build_tests/README.adoc b/build_tests/README.adoc index aba6cb324..ca5d59477 100644 --- a/build_tests/README.adoc +++ b/build_tests/README.adoc @@ -37,9 +37,9 @@ succeed but the output does not match the expectations, the diff is output for investigation. In some cases, the diff is small enough to be verified. Otherwise, each output -in `gen-/` needs to be manually reviewed to ensure the results are still -correct; for example because the html is styled differently and the differences -are as expected. +in `gen-/out/html/vkspec.html` needs to be manually reviewed to ensure +the results are still correct; for example because the html is styled +differently and the differences are as expected. If the mismatch between the output and expectations is expected, and the output is verified to be correct, update the expectations with: diff --git a/build_tests/expectations/all-1.0.html b/build_tests/expectations/all-1.0.html index 18fd48f75..13a501bc6 100644 --- a/build_tests/expectations/all-1.0.html +++ b/build_tests/expectations/all-1.0.html @@ -1,1052 +1,3 @@ - - - - - - - - -Test® 1.2.3 - (with all registered extensions) - - - - - - - - - - - - - - - - - - - - - - -
-

VK_EXT_host_image_copy

+
+
+

VK_EXT_host_image_copy

Name String
@@ -2113,11 +1066,15 @@

-

VK_KHR_get_physical_device_properties2
-and
-VK_KHR_copy_commands2
-and
-VK_KHR_format_feature_flags2

+

         VK_KHR_get_physical_device_properties2
+         or
+         Version 1.1
+     and
+     VK_KHR_copy_commands2
+     and
+     VK_KHR_format_feature_flags2
+or
+Version 1.3

@@ -2138,7 +1095,6 @@

-

Other Extension Metadata

@@ -2425,4 +1381,3 @@

Version - \ No newline at end of file diff --git a/build_tests/expectations/all.html b/build_tests/expectations/all.html index d8d4c0fa9..54d8b75c3 100644 --- a/build_tests/expectations/all.html +++ b/build_tests/expectations/all.html @@ -1,1052 +1,3 @@ - - - - - - - - -Test® 1.2.3 - (with all registered extensions) - - - - - - - - - - - - - - - - - - - - - - -
-

VK_EXT_host_image_copy

+
+
+

VK_EXT_host_image_copy

Name String
@@ -2147,11 +1100,15 @@

-

VK_KHR_get_physical_device_properties2
-and
-VK_KHR_copy_commands2
-and
-VK_KHR_format_feature_flags2

+

         VK_KHR_get_physical_device_properties2
+         or
+         Version 1.1
+     and
+     VK_KHR_copy_commands2
+     and
+     VK_KHR_format_feature_flags2
+or
+Version 1.3

@@ -2172,7 +1129,6 @@

-

Other Extension Metadata

@@ -2459,4 +1415,3 @@

Version - \ No newline at end of file diff --git a/build_tests/expectations/copy2-1.0.html b/build_tests/expectations/copy2-1.0.html index 31c2dc096..5f04c0b8e 100644 --- a/build_tests/expectations/copy2-1.0.html +++ b/build_tests/expectations/copy2-1.0.html @@ -1,1052 +1,3 @@ - - - - - - - - -Test® 1.2.3 - (with VK_KHR_copy_commands2, VK_KHR_get_physical_device_properties2) - - - - - - - - - - - - - - - - - - - - - -