diff --git a/Makefile b/Makefile index 021c9482c..765206f7c 100644 --- a/Makefile +++ b/Makefile @@ -472,7 +472,7 @@ MARKUP_SPEC_SOURCES = $(SPECDIR)/[a-z]*.adoc $(SPECDIR)/chapters $(SPECDIR)/appe # Look for disallowed contractions CHECK_CONTRACTIONS = git grep -n -i -F -f $(ROOTDIR)/config/CI/contractions | grep -v -E -f $(ROOTDIR)/config/CI/contractions-allowed check-contractions: - if test `$(CHECK_CONTRACTIONS) | wc -l` != 0 ; then \ + $(QUIET) if test `$(CHECK_CONTRACTIONS) | wc -l` != 0 ; then \ echo "Contractions found that are not allowed:" ; \ $(CHECK_CONTRACTIONS) ; \ exit 1 ; \ @@ -481,8 +481,9 @@ check-contractions: # 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 \ + $(QUIET) if ! $(CHECK_DUPLICATES) ; then \ echo "Successive duplicate words found that are not allowed" ; \ + $(CHECK_DUPLICATES) ; \ exit 1 ; \ fi @@ -491,7 +492,7 @@ check-duplicates: # check-writing target below. CODESPELL = codespell --config $(ROOTDIR)/config/CI/codespellrc check-spelling: - if ! $(CODESPELL) > /dev/null ; then \ + $(QUIET) if ! $(CODESPELL) > /dev/null ; then \ echo "Found probable misspellings. Corrections can be added to config/CI/codespell-allowed, or files excluded in config/CI/codespellrc if there is no other option:" ; \ $(CODESPELL) ; \ exit 1 ; \ @@ -502,7 +503,7 @@ check-spelling: # made in outstanding extension branches for new text. CHECK_WRITING = git grep -n -E -f $(ROOTDIR)/config/CI/writing $(SPECDIR)/[a-z]*.adoc $(SPECDIR)/chapters $(SPECDIR)/appendices check-writing: - if test `$(CHECK_WRITING) | wc -l` != 0 ; then \ + $(QUIET) if test `$(CHECK_WRITING) | wc -l` != 0 ; then \ echo "Found old style writing. Please refer to the style guide or similar language in current main branch for fixes:" ; \ $(CHECK_WRITING) ; \ exit 1 ; \ @@ -511,7 +512,7 @@ check-writing: # Look for bullet list items not preceded by exactly two spaces, per styleguide CHECK_BULLETS = git grep -n -E '^( | +)[-*]+ ' $(MARKUP_SPEC_SOURCES) check-bullets: - if test `$(CHECK_BULLETS) | wc -l` != 0 ; then \ + $(QUIET) if test `$(CHECK_BULLETS) | wc -l` != 0 ; then \ echo "Bullet list item found not preceded by exactly two spaces:" ; \ $(CHECK_BULLETS) ; \ exit 1 ; \ @@ -520,7 +521,7 @@ check-bullets: # Look for VU text ending in a period CHECK_VUPERIOD = ag --nocolor --asciidoc '\* \[\[VUID[^.]+\.\n( {2}\* \[\[VUID|\*\*\*\*)' $(MARKUP_SPEC_SOURCES) check-vuperiod: - if test `$(CHECK_VUPERIOD) | wc -l` != 0 ; then \ + $(QUIET) if test `$(CHECK_VUPERIOD) | wc -l` != 0 ; then \ echo "VU rule ending with a disallowed period found. Note that the matched text may be very long:" ; \ $(CHECK_VUPERIOD) ; \ exit 1 ; \ @@ -529,7 +530,7 @@ check-vuperiod: # Look for common macro markup errors CHECK_MARKUP = git grep -n -E -f $(ROOTDIR)/config/CI/markup $(MARKUP_SPEC_SOURCES) check-markup: - if test `$(CHECK_MARKUP) | wc -l` != 0 ; then \ + $(QUIET) if test `$(CHECK_MARKUP) | wc -l` != 0 ; then \ echo "Common macro markup errors found. Please refer to the style guide or similar markup in current main branch for fixes:" ; \ $(CHECK_MARKUP) ; \ exit 1 ; \ @@ -538,14 +539,14 @@ check-markup: # Look for asciidoctor conditionals inside VU statements; and for # duplicated VUID numbers, but only in spec sources. check-reflow: - $(PYTHON) $(SCRIPTS)/reflow.py -nowrite -noflow -check FAIL -checkVUID FAIL $(SPECFILES) + $(QUIET) $(PYTHON) $(SCRIPTS)/reflow.py -nowrite -noflow -check FAIL -checkVUID FAIL $(SPECFILES) # Look for files whose Khronos copyright has not been updated to the # current year DATE_YEAR = $(shell date +%Y) CHECK_DATES = git grep -z -l 'Copyright.*The Khronos' | xargs -0 git grep -L 'Copyright.*$(DATE_YEAR).*The Khronos' check-copyright-dates: - if test `$(CHECK_DATES) | wc -l` != 0 ; then \ + $(QUIET) if test `$(CHECK_DATES) | wc -l` != 0 ; then \ echo "Files with out-of-date Khronos copyrights (must be updated to $(DATE_YEAR):" ; \ $(CHECK_DATES) ; \ exit 1 ; \ @@ -554,14 +555,14 @@ check-copyright-dates: # Look for proper use of custom markup macros # --ignore_count 0 can be incremented if there are unfixable errors check-links: - $(PYTHON) $(SCRIPTS)/check_spec_links.py -Werror --ignore_count 0 + $(QUIET) $(PYTHON) $(SCRIPTS)/check_spec_links.py -Werror --ignore_count 0 # Perform XML consistency checks # Use '-warn' option to display warnings as well as errors CHECK_UGLY_TYPE_DECL = git grep -E '\*+' $(VKXML) check-consistency: - $(PYTHON) $(SCRIPTS)/xml_consistency.py - if test `$(CHECK_UGLY_TYPE_DECL) | wc -l` != 0 ; then \ + $(QUIET) $(PYTHON) $(SCRIPTS)/xml_consistency.py + $(QUIET) if test `$(CHECK_UGLY_TYPE_DECL) | wc -l` != 0 ; then \ echo "XML contains declarations lacking whitespace:" ; \ $(CHECK_UGLY_TYPE_DECL) ; \ exit 1 ; \ @@ -569,20 +570,24 @@ check-consistency: # Look for untagged use of 'undefined' in spec sources check-undefined: - $(SCRIPTS)/ci/check_undefined + $(QUIET) $(SCRIPTS)/ci/check_undefined # Look for use of custom macros in the proposals and other # non-Specification document (except for the ChangeLog*.adoc) markup CHECK_CUSTOM_MACROS = git grep -n -E -f $(ROOTDIR)/config/CI/custom-macros [A-Z][A-Z]*.adoc proposals/ CHECK_PROPOSALS = git grep -n -E -f $(ROOTDIR)/config/CI/proposals-disallowed proposals/ check-custom-macros: - if test `$(CHECK_CUSTOM_MACROS) | wc -l` != 0 ; then \ + $(QUIET) if test `$(CHECK_CUSTOM_MACROS) | wc -l` != 0 ; then \ echo "Found use of specification macros in proposal or repository metadocumentation, where they are not allowed. Please use straight asciidoc markup like *must* for fixes:" ; \ $(CHECK_CUSTOM_MACROS) ; \ exit 1 ; \ fi - if test `$(CHECK_PROPOSALS) | wc -l` != 0 ; then \ - echo "Found use of {refpage} attribute in proposals (use {docs} or {extensions}, see proposals/template.adoc); or of asciidoctor markup which cannot be rendered on github, such as include: or asciimath: directives:" ; \ + $(QUIET) if test `$(CHECK_PROPOSALS) | wc -l` != 0 ; then \ + echo "Found use of one or more of:" ; \ + echo " - {extensions} attribute in proposals (use xref:{docs} or xref:{refpages})" ; \ + echo " - link: used with {docs} or {extensions} (use xref:)" ; \ + echo " - asciidoctor markup which cannot be rendered on github, such as include: or asciimath: directives" ; \ + echo "(see proposals/template.adoc) for examples" ; \ $(CHECK_PROPOSALS) ; \ exit 1 ; \ fi @@ -590,7 +595,7 @@ check-custom-macros: # Look for '.txt' and '.asciidoc' files, which should almost all be .adoc now CHECK_TXTFILES = find . -name '*.txt' -o -name '*.asciidoc' | grep -v -E -f $(ROOTDIR)/config/CI/txt-files-allowed check-txtfiles: - if test `$(CHECK_TXTFILES) | wc -l` != 0 ; then \ + $(QUIET) if test `$(CHECK_TXTFILES) | wc -l` != 0 ; then \ echo "*.txt and/or .asciidoc files found that are not allowed (use .adoc):" ; \ $(CHECK_TXTFILES) ; \ exit 1 ; \ @@ -598,7 +603,7 @@ check-txtfiles: # Check for valid xrefs in the output html check-xrefs: $(HTMLDIR)/vkspec.html - $(PYTHON) $(SCRIPTS)/check_html_xrefs.py $(HTMLDIR)/vkspec.html + $(QUIET) $(PYTHON) $(SCRIPTS)/check_html_xrefs.py $(HTMLDIR)/vkspec.html # Check for stuff that should not be published. # This is not part of 'allchecks' since it would fail in most new @@ -608,7 +613,7 @@ check-internal-phrasing: check-proposed check-gitlab # Check for UNRESOLVED or PROPOSED issues in extension appendices CHECK_PROPOSED = git grep -n -E 'PROPOSED|UNRESOLVED' $(SPECDIR)/appendices/ check-proposed: - if test `$(CHECK_PROPOSED) | wc -l` != 0 ; then \ + $(QUIET) if test `$(CHECK_PROPOSED) | wc -l` != 0 ; then \ echo "PROPOSED or UNRESOLVED issues should not be published in extension appendices:" ; \ $(CHECK_PROPOSED) ; \ exit 1 ; \ @@ -617,7 +622,7 @@ check-proposed: # Check for internal gitlab links anywhere in markup sources CHECK_GITLAB = git grep -n 'gitlab.khronos.org' $(MARKUP_SPEC_SOURCES) proposals/ check-gitlab: - if test `$(CHECK_GITLAB) | wc -l` != 0 ; then \ + $(QUIET) if test `$(CHECK_GITLAB) | wc -l` != 0 ; then \ echo "Internal gitlab.khronos.org links should not be published, use corresponding github links instead:" ; \ $(CHECK_GITLAB) ; \ exit 1 ; \ @@ -957,7 +962,7 @@ generated: $(PYAPIMAP) $(GENDEPENDS) clean: clean_html clean_pdf clean_man clean_generated clean_antora clean_validusage clean_html: - $(QUIET)$(RMRF) $(HTMLDIR) $(OUTDIR)/katex + $(QUIET)$(RMRF) $(HTMLDIR) $(OUTDIR)/katex $(PROPOSALDIR) $(QUIET)$(RM) $(OUTDIR)/styleguide.html $(OUTDIR)/registry.html clean_pdf: diff --git a/config/CI/proposals-disallowed b/config/CI/proposals-disallowed index 0ade720b2..dac4c2309 100644 --- a/config/CI/proposals-disallowed +++ b/config/CI/proposals-disallowed @@ -1,4 +1,4 @@ -:refpage: -\{refpage\} +link:\{(docs|refpages)\} +\{extensions\} (^|[^-_.&:<>\[[:alnum:]])(asciimath|latexmath|stem): ^include:: diff --git a/proposals/Roadmap.adoc b/proposals/Roadmap.adoc index bea253e96..5d36fb54a 100644 --- a/proposals/Roadmap.adoc +++ b/proposals/Roadmap.adoc @@ -5,7 +5,7 @@ = Vulkan Roadmap :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This document proposes the development of a shared public roadmap for features across mid-to-high-end devices in smartphone, tablet, laptop, console, and desktop markets. diff --git a/proposals/VK_AMDX_dense_geometry_format.adoc b/proposals/VK_AMDX_dense_geometry_format.adoc index 12e84ba77..889d25007 100644 --- a/proposals/VK_AMDX_dense_geometry_format.adoc +++ b/proposals/VK_AMDX_dense_geometry_format.adoc @@ -5,7 +5,7 @@ = VK_AMDX_dense_geometry_format :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: // Required so images render in github ifndef::images[:images: ../images] @@ -38,7 +38,7 @@ A new geometry type is introduced for supplying pre-compressed geometry data to The <> structure provides a compressed bit-stream to the acceleration structure build. The number of encoded triangles is also available for use by the implementation. This enables the existence of a "fallback layer" which decodes the geometry and maps it to a conventional acceleration structure. It is expected that native support will ultimately evolve, but acknowledged that on-the-fly translation may be a necessary intermediate step. -For link:{docs}chapters/resources.html#vkGetAccelerationStructureBuildSizesKHR[vkGetAccelerationStructureBuildSizesKHR] the application must supply both the total number of triangles and the expected size of the compressed data. The latter is required so that implementations can use a 1:1 mapping between compressed blocks and acceleration structure nodes. +For xref:{refpages}vkGetAccelerationStructureBuildSizesKHR.html[vkGetAccelerationStructureBuildSizesKHR] the application must supply both the total number of triangles and the expected size of the compressed data. The latter is required so that implementations can use a 1:1 mapping between compressed blocks and acceleration structure nodes. === Bottom-level Acceleration Structure Update Constraints @@ -52,9 +52,9 @@ Additional constraints apply depending on the compression format: When pre-compressed geometry is in use, the geometry indices for the triangles are directly encoded in the input data on a per-triangle basis. The number of <> structures supplied at BLAS build has no effect on shader table indexing or the results of the `GeometryIndex()` intrinsic. -The `OPAQUE` flag is also supplied on a per-triangle basis. The `VK_GEOMETRY_OPAQUE_BIT_KHR` flag on the link:{docs}chapters/accelstructures.html#VkAccelerationStructureGeometryKHR[VkAccelerationStructureGeometryKHR] structure has no effect for compressed geometry. +The `OPAQUE` flag is also supplied on a per-triangle basis. The `VK_GEOMETRY_OPAQUE_BIT_KHR` flag on the xref:{refpages}VkAccelerationStructureGeometryKHR.html[VkAccelerationStructureGeometryKHR] structure has no effect for compressed geometry. -Multiple link:{docs}chapters/accelstructures.html#VkAccelerationStructureGeometryKHR[VkAccelerationStructureGeometryKHR] structures can be used to glue disconnected blobs of compressed data together into a larger acceleration structure, or for specifying different values for `VK_GEOMETRY_NO_DUPLICATE_ANY_HIT_INVOCATION_BIT_KHR` for different sets of DGF blocks. +Multiple xref:{refpages}VkAccelerationStructureGeometryKHR.html[VkAccelerationStructureGeometryKHR] structures can be used to glue disconnected blobs of compressed data together into a larger acceleration structure, or for specifying different values for `VK_GEOMETRY_NO_DUPLICATE_ANY_HIT_INVOCATION_BIT_KHR` for different sets of DGF blocks. The values returned by the `PrimitiveIndex()` intrinsic are also directly encoded in the input, and may be sparsely specified or even duplicated, if the application finds some use for this. There is no relationship between the value of <> and the maximum primitive index. @@ -154,7 +154,7 @@ The indirect method achieve the lowest memory overhead unless vertex data are ve === API Changes -To build acceleration structures using pre-compressed triangle data, the link:{docs}chapters/accelstructures.html#VkAccelerationStructureGeometryKHR[VkAccelerationStructureGeometryKHR] structure is extended using a new enum value in link:{docs}chapters/resources.html#VkGeometryTypeKHR[VkGeometryTypeKHR]: +To build acceleration structures using pre-compressed triangle data, the xref:{refpages}VkAccelerationStructureGeometryKHR.html[VkAccelerationStructureGeometryKHR] structure is extended using a new enum value in xref:{refpages}VkGeometryTypeKHR.html[VkGeometryTypeKHR]: [source,c] ---- @@ -164,7 +164,7 @@ typedef enum VkGeometryTypeKHR { } VkGeometryTypeKHR; ---- -When the `geometryType` member of link:{docs}chapters/accelstructures.html#VkAccelerationStructureGeometryKHR[VkAccelerationStructureGeometryKHR] is set to `VK_GEOMETRY_TYPE_DENSE_GEOMETRY_FORMAT_TRIANGLES_AMDX`, a `VkAccelerationStructureDenseGeometryFormatTrianglesDataAMDX` structure in its `pNext` chain describes pre-compressed triangle geometry: +When the `geometryType` member of xref:{refpages}VkAccelerationStructureGeometryKHR.html[VkAccelerationStructureGeometryKHR] is set to `VK_GEOMETRY_TYPE_DENSE_GEOMETRY_FORMAT_TRIANGLES_AMDX`, a `VkAccelerationStructureDenseGeometryFormatTrianglesDataAMDX` structure in its `pNext` chain describes pre-compressed triangle geometry: [[VkAccelerationStructureDenseGeometryFormatTrianglesDataAMDX-struct]] [source,c] @@ -208,9 +208,9 @@ Two defines are added that specify the alignment and stride requirements of the #define VK_COMPRESSED_TRIANGLE_FORMAT_DGF1_BYTE_STRIDE_AMDX 128U ---- -Note that a host builds are not supported, and a link:{docs}chapters/accelstructures.html#VkAccelerationStructureBuildRangeInfoKHR[VkAccelerationStructureBuildRangeInfoKHR] structure is not used when building an acceleration structure with a geometry type of `VK_GEOMETRY_TYPE_DENSE_GEOMETRY_FORMAT_TRIANGLES_AMDX`. +Note that a host builds are not supported, and a xref:{refpages}VkAccelerationStructureBuildRangeInfoKHR.html[VkAccelerationStructureBuildRangeInfoKHR] structure is not used when building an acceleration structure with a geometry type of `VK_GEOMETRY_TYPE_DENSE_GEOMETRY_FORMAT_TRIANGLES_AMDX`. -To use an link:{docs}chapters/VK_EXT_opacity_micromap/micromaps.html[Opacity Micromap] with the compressed triangle data, a link:{docs}chapters/accelstructures.html#VkAccelerationStructureTrianglesOpacityMicromapEXT[VkAccelerationStructureTrianglesOpacityMicromapEXT] structure can be added to the `pNext` chain of `VkAccelerationStructureDenseGeometryFormatTrianglesDataAMDX`. +To use an xref:{docs}chapters/VK_EXT_opacity_micromap/micromaps.html[Opacity Micromap] with the compressed triangle data, a xref:{refpages}VkAccelerationStructureTrianglesOpacityMicromapEXT.html[VkAccelerationStructureTrianglesOpacityMicromapEXT] structure can be added to the `pNext` chain of `VkAccelerationStructureDenseGeometryFormatTrianglesDataAMDX`. ==== Features diff --git a/proposals/VK_AMDX_shader_enqueue.adoc b/proposals/VK_AMDX_shader_enqueue.adoc index 4898a8103..46361c661 100644 --- a/proposals/VK_AMDX_shader_enqueue.adoc +++ b/proposals/VK_AMDX_shader_enqueue.adoc @@ -5,7 +5,7 @@ = VK_AMDX_shader_enqueue :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This extension adds the ability for developers to enqueue mesh pipelines and compute shader workgroups from other compute shaders. @@ -90,7 +90,7 @@ VK_PIPELINE_CREATE_2_EXECUTION_GRAPH_BIT_AMDX = 0x100000000ULL ---- Each shader in an execution graph is associated with a name and an index, which are used to identify the target shader when dispatching a payload. -The `VkPipelineShaderStageNodeCreateInfoAMDX` provides options for specifying how the shader is specified with regards to its entry point name and index, and can be chained to the link:{docs}chapters/pipelines.html#VkPipelineShaderStageCreateInfo[VkPipelineShaderStageCreateInfo] structure. +The `VkPipelineShaderStageNodeCreateInfoAMDX` provides options for specifying how the shader is specified with regards to its entry point name and index, and can be chained to the xref:{refpages}VkPipelineShaderStageCreateInfo.html[VkPipelineShaderStageCreateInfo] structure. [source,c] ---- @@ -124,7 +124,7 @@ Additionally, if an input payload is declared in the dispatched shader, the inpu When adding a graphics pipeline to an execution graph pipeline, applications must specify a graphics pipeline with a complete set of state, and the `VK_PIPELINE_CREATE_2_LIBRARY_BIT_KHR` and `VK_PIPELINE_CREATE_2_EXECUTION_GRAPH_BIT_AMDX` flags set. Graphics pipelines must only include mesh shaders; vertex shader pipelines or mesh pipelines with task shaders are not supported. -When creating such a graphics pipeline from libraries as an interaction with link:{extensions}VK_EXT_graphics_pipeline_library[VK_EXT_graphics_pipeline_library], those libraries must also have been created with those flags. +When creating such a graphics pipeline from libraries as an interaction with xref:{refpages}VK_EXT_graphics_pipeline_library.html[VK_EXT_graphics_pipeline_library], those libraries must also have been created with those flags. For graphics pipelines defined in this way, only the following dynamic state is allowed: @@ -450,9 +450,9 @@ An application must not dispatch the shader with a number of workgroups in any d `StaticNumWorkgroupsAMDX` allows the declaration of the number of workgroups to dispatch to be coded into the shader itself, which can be useful for optimizing some algorithms. When a compute shader is dispatched using existing `vkCmdDispatchGraph*` commands, the workgroup counts specified there are overridden. When enqueuing such shaders with a payload, these arguments will not be consumed from the payload before application-specified data begins. -The values of `MaxNumWorkgroupsAMDX` and `StaticNumWorkgroupsAMDX` must be less than or equal to `link:{docs}chapters/limits.html#VkPhysicalDeviceShaderEnqueuePropertiesAMDX[VkPhysicalDeviceShaderEnqueuePropertiesAMDX]::maxExecutionGraphWorkgroupCount`. +The values of `MaxNumWorkgroupsAMDX` and `StaticNumWorkgroupsAMDX` must be less than or equal to `xref:{refpages}VkPhysicalDeviceShaderEnqueuePropertiesAMDX.html[VkPhysicalDeviceShaderEnqueuePropertiesAMDX]::maxExecutionGraphWorkgroupCount`. -The product of the X, Y, and Z values of `MaxNumWorkgroupsAMDX` and `StaticNumWorkgroupsAMDX` must be less than or equal to `link:{docs}chapters/limits.html#VkPhysicalDeviceShaderEnqueuePropertiesAMDX[VkPhysicalDeviceShaderEnqueuePropertiesAMDX]::maxExecutionGraphWorkgroups`. +The product of the X, Y, and Z values of `MaxNumWorkgroupsAMDX` and `StaticNumWorkgroupsAMDX` must be less than or equal to `xref:{refpages}VkPhysicalDeviceShaderEnqueuePropertiesAMDX.html[VkPhysicalDeviceShaderEnqueuePropertiesAMDX]::maxExecutionGraphWorkgroups`. The arguments to each of these execution modes must be a constant 32-bit integer value, and may be supplied via specialization constants. diff --git a/proposals/VK_AMD_anti_lag.adoc b/proposals/VK_AMD_anti_lag.adoc index 150d67af9..88f073f72 100644 --- a/proposals/VK_AMD_anti_lag.adoc +++ b/proposals/VK_AMD_anti_lag.adoc @@ -5,7 +5,7 @@ = VK_AMD_anti_lag :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This document describes a proposal for a new AMD function that allows the precision of AntiLag to be improved. diff --git a/proposals/VK_AMD_shader_early_and_late_fragment_tests.adoc b/proposals/VK_AMD_shader_early_and_late_fragment_tests.adoc index a8a5ca1c4..b99781905 100644 --- a/proposals/VK_AMD_shader_early_and_late_fragment_tests.adoc +++ b/proposals/VK_AMD_shader_early_and_late_fragment_tests.adoc @@ -5,7 +5,7 @@ = VK_AMD_shader_early_and_late_fragment_tests :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This document describes a proposal for a new SPIR-V execution mode that allows fragment shaders to be discarded by early fragment operations, even if they contain writes to storage resources or other side effects. diff --git a/proposals/VK_ANDROID_external_format_resolve.adoc b/proposals/VK_ANDROID_external_format_resolve.adoc index aa8e63e46..1ea3d8280 100644 --- a/proposals/VK_ANDROID_external_format_resolve.adoc +++ b/proposals/VK_ANDROID_external_format_resolve.adoc @@ -5,7 +5,7 @@ = VK_ANDROID_external_format_resolve :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This extension enables rendering to Android Hardware Buffers with external formats which cannot be directly represented as renderable in Vulkan, including YC~B~C~R~ formats. @@ -51,7 +51,7 @@ When using dynamic rendering, a new resolve mode is added to specify that the re VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_BIT_ANDROID; ---- -When this resolve mode is specified, the `resolveImageView` member of link:{docs}chapters/renderpass.html#VkRenderingAttachmentInfo[VkRenderingAttachmentInfo] used as a color attachment must be set to a `VkImageView` created with an image with a non-zero external format. +When this resolve mode is specified, the `resolveImageView` member of xref:{refpages}VkRenderingAttachmentInfo.html[VkRenderingAttachmentInfo] used as a color attachment must be set to a `VkImageView` created with an image with a non-zero external format. If chroma planes of the external format are subsampled, the implementation will reduce the relevant planes by either averaging the corresponding values in the color attachment, or by simply selecting one of the values as representative. Implementations may resolve a color attachment to an external format resolve attachment at any time, or bypass writing to a color attachment altogether. @@ -60,26 +60,26 @@ With the resolve mode set to `VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_BIT_AND * If `nullColorAttachmentWithExternalFormatResolve` property is `VK_TRUE`, `imageView` must be `VK_NULL_HANDLE`. ** Values in the color attachment during rendering are loaded from the external format attachment, resampling to the fragment rate as necessary. * If `imageView` is not `NULL`, it must be a single sampled image with a layer count of `1`. - * The `layerCount` and `colorAttachmentCount` members of link:{docs}chapters/renderpass.html#VkRenderingInfo[VkRenderingInfo] must be 1. - * The `viewMask` member of link:{docs}chapters/renderpass.html#VkRenderingInfo[VkRenderingInfo] must be 0. + * The `layerCount` and `colorAttachmentCount` members of xref:{refpages}VkRenderingInfo.html[VkRenderingInfo] must be 1. + * The `viewMask` member of xref:{refpages}VkRenderingInfo.html[VkRenderingInfo] must be 0. * There must not be a fragment density map image * There must not be a fragment shading rate image * The fragment shading rate must be 1x1 -Implementations may need to know that an external format YC~B~C~R~ format is being used when creating a pipeline, so when dynamic rendering is used, link:{docs}chapters/resources.html#VkExternalFormatANDROID[VkExternalFormatANDROID] can be chained to `VkGraphicsPipelineCreateInfo`, indicating the format of the resolve image. +Implementations may need to know that an external format YC~B~C~R~ format is being used when creating a pipeline, so when dynamic rendering is used, xref:{refpages}VkExternalFormatANDROID.html[VkExternalFormatANDROID] can be chained to `VkGraphicsPipelineCreateInfo`, indicating the format of the resolve image. When rendering, the format of the resolve image specified here and the actual image view used for that color resolve attachment must be the same. -Graphics pipelines that include a link:{docs}chapters/resources.html#VkExternalFormatANDROID[VkExternalFormatANDROID] structure with a non-zero value must only write to a single color attachment, must not export depth or stencil from the fragment shader, and must disable blending. +Graphics pipelines that include a xref:{refpages}VkExternalFormatANDROID.html[VkExternalFormatANDROID] structure with a non-zero value must only write to a single color attachment, must not export depth or stencil from the fragment shader, and must disable blending. ==== Inheritance Info -When dynamic rendering is used with secondary command buffer inheritance, the external format *must* be made known to the secondary command buffers by including link:{docs}chapters/resources.html#VkExternalFormatANDROID[VkExternalFormatANDROID] in the `pNext` chain of link:{docs}chapters/cmdbuffers.html#VkCommandBufferInheritanceInfo[VkCommandBufferInheritanceInfo], and the external format must match that in the render pass instance. +When dynamic rendering is used with secondary command buffer inheritance, the external format *must* be made known to the secondary command buffers by including xref:{refpages}VkExternalFormatANDROID.html[VkExternalFormatANDROID] in the `pNext` chain of xref:{refpages}VkCommandBufferInheritanceInfo.html[VkCommandBufferInheritanceInfo], and the external format must match that in the render pass instance. === Render Pass Objects For render pass objects, color resolve attachments can similarly be repurposed for external YC~B~C~R~ format resolves by setting a color resolve attachment in a subpass to an attachment with an external format. -These can only be used with link:{docs}chapters/renderpass.html#VkSubpassDescription2[VkSubpassDescription2], and similar restrictions apply to this as they do to dynamic rendering: +These can only be used with xref:{refpages}VkSubpassDescription2.html[VkSubpassDescription2], and similar restrictions apply to this as they do to dynamic rendering: - * The resolve attachment must be an attachment that has a format of `VK_FORMAT_UNDEFINED` and includes a link:{docs}chapters/resources.html#VkExternalFormatANDROID[VkExternalFormatANDROID] structure in its `pNext` chain + * The resolve attachment must be an attachment that has a format of `VK_FORMAT_UNDEFINED` and includes a xref:{refpages}VkExternalFormatANDROID.html[VkExternalFormatANDROID] structure in its `pNext` chain ** This format must match that for the image view bound via the framebuffer * If `nullColorAttachmentWithExternalFormatResolve` property is `VK_TRUE`, the `attachment` member of the corresponding color attachment must be `VK_ATTACHMENT_UNUSED`. * If the color attachment is not `VK_ATTACHMENT_UNUSED`, it must be a single sampled attachment. @@ -92,12 +92,12 @@ Color attachment values written during rendering are resolved in the same manner === Input Attachments If the `nullColorAttachmentWithExternalFormatResolve` property is `VK_FALSE`, applications can bind the color attachment as they normally would with any other color attachment, with value reads working as expected. -Using an external format image as an input attachment is only valid when the feature bits queried via link:{docs}chapters/memory.html#vkGetAndroidHardwareBufferPropertiesANDROID[vkGetAndroidHardwareBufferPropertiesANDROID] advertise this functionality. +Using an external format image as an input attachment is only valid when the feature bits queried via xref:{refpages}vkGetAndroidHardwareBufferPropertiesANDROID.html[vkGetAndroidHardwareBufferPropertiesANDROID] advertise this functionality. However, if the `nullColorAttachmentWithExternalFormatResolve` property is `VK_TRUE`, applications cannot do that as there is no attachment to use. Instead, the resolve attachment itself should be bound as the input attachment (both the attachment reference and the descriptor). When using a resolve attachment in this specific configuration, it can be synchronized as if it were actually the color attachment, allowing for subpass self-dependencies. -If the implementation supports this property, an external format image can be used as an input attachment without the typically required feature bits advertised by link:{docs}chapters/memory.html#vkGetAndroidHardwareBufferPropertiesANDROID[vkGetAndroidHardwareBufferPropertiesANDROID]. +If the implementation supports this property, an external format image can be used as an input attachment without the typically required feature bits advertised by xref:{refpages}vkGetAndroidHardwareBufferPropertiesANDROID.html[vkGetAndroidHardwareBufferPropertiesANDROID]. If an external format resolve image is read as an input attachment and has subsampled chroma planes, these are resampled per above to provide values at the expected rate. Their values are not converted via color space transforms - as with resolves the application must transform these themselves. @@ -339,7 +339,7 @@ For example, images with four components are treated as R = Cr, G = Y, and B = C * Clear color given to begin rendering/render pass are taken as (R, G, B, A) for color components and (V, Y, U, A) for yuv components Implementations must not expose an external formats representing a depth or stencil format. -Applications must import depth images with link:{docs}chapters/formats.html#VkFormat[VkFormat] in order to render to them. +Applications must import depth images with xref:{refpages}VkFormat.html[VkFormat] in order to render to them. Images without depth, color, or yuv components are beyond the scope of Vulkan interface and are defined by the format for which effective color components it should be used as, such as for the RAW10 format. ==== diff --git a/proposals/VK_ARM_performance_counters_by_region.adoc b/proposals/VK_ARM_performance_counters_by_region.adoc index d4e05df31..e0ce5df49 100644 --- a/proposals/VK_ARM_performance_counters_by_region.adoc +++ b/proposals/VK_ARM_performance_counters_by_region.adoc @@ -5,7 +5,7 @@ = VK_ARM_performance_counters_by_region :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This document describes a proposal for a new extension that allows diff --git a/proposals/VK_ARM_pipeline_opacity_micromap.adoc b/proposals/VK_ARM_pipeline_opacity_micromap.adoc index af84c02f1..4682f5d2c 100644 --- a/proposals/VK_ARM_pipeline_opacity_micromap.adoc +++ b/proposals/VK_ARM_pipeline_opacity_micromap.adoc @@ -5,7 +5,7 @@ = VK_ARM_pipeline_opacity_micromap :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This document outlines functionality to allow applications to specify that diff --git a/proposals/VK_ARM_render_pass_striped.adoc b/proposals/VK_ARM_render_pass_striped.adoc index f41edbf7b..251956fb4 100644 --- a/proposals/VK_ARM_render_pass_striped.adoc +++ b/proposals/VK_ARM_render_pass_striped.adoc @@ -5,7 +5,7 @@ = VK_ARM_render_pass_striped :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This document describes a proposal for a new extension that allows the diff --git a/proposals/VK_ARM_shader_instrumentation.adoc b/proposals/VK_ARM_shader_instrumentation.adoc index d20e494d7..60aeb018a 100644 --- a/proposals/VK_ARM_shader_instrumentation.adoc +++ b/proposals/VK_ARM_shader_instrumentation.adoc @@ -5,7 +5,7 @@ = VK_ARM_shader_instrumentation :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: // Required so images render in github ifndef::images[:images: ../images] @@ -18,7 +18,7 @@ Developers consistently rank the lack of attributable performance feedback as on Today, the primary tool we use for shader costing is the Mali Offline Compiler. It is a static analysis tool which works well for simple shaders, but cannot accurately cost any shader with data-driven control flow because it does not know the actual data used for a draw call. Today's content commonly involves shaders with divergent control flow, dynamic indexing, and bindless descriptors which necessitates a more complex way of giving users performance feedback. -link:{extensions}VK_KHR_pipeline_executable_properties[VK_KHR_pipeline_executable_properties] is insufficient to address these concerns since the metrics returned here can only cover values known or estimated at compile time. +xref:{refpages}VK_KHR_pipeline_executable_properties.html[VK_KHR_pipeline_executable_properties] is insufficient to address these concerns since the metrics returned here can only cover values known or estimated at compile time. Use cases for this kind of performance feedback are: @@ -76,12 +76,12 @@ Options that have been considered for retrieving the data are: - Pros: Simple to implement and handle (both for the user and the driver). - Cons: If we want to introduce more counters down the line, we need to create a new extension. -3. Something that matches how link:{extensions}VK_KHR_pipeline_executable_properties[VK_KHR_pipeline_executable_properties] exposes data to the user, but make it apply to an instrumentation object rather than a pipeline/shader object. +3. Something that matches how xref:{refpages}VK_KHR_pipeline_executable_properties.html[VK_KHR_pipeline_executable_properties] exposes data to the user, but make it apply to an instrumentation object rather than a pipeline/shader object. - In short: Populates an array of structs which contain {name, description, value_type (u64, i64 etc), value}. - Pros: Easy to extend to cover basic blocks (name could for example be "FMA.vert.BB0"), vendor agnostic, uses a paradigm that already exists in Vulkan. - Cons: Duplicates a lot of structs/functionality. -4. One struct/entry point for describing the data that contains a unique ID and a description. The struct used for reading out data contains that same unique ID, which can then be used to look up the description. Similar to what is done in link:{extensions}VK_ARM_performance_counter_by_region[VK_ARM_performance_counter_by_region]. Also similar to (3) but extracts the "name" and "description" from the data struct which requires less memory. +4. One struct/entry point for describing the data that contains a unique ID and a description. The struct used for reading out data contains that same unique ID, which can then be used to look up the description. Similar to what is done in xref:{refpages}VK_ARM_performance_counters_by_region.html[VK_ARM_performance_counters_by_region]. Also similar to (3) but extracts the "name" and "description" from the data struct which requires less memory. - Pros: Easy to extend, uses a paradigm that already exists in Vulkan, descriptive with far less memory requirements than (3). - Cons: To support basic block counts and shader stage distinction, we would need to include basicBlockIndex and shaderStage in either the data output or the metric info struct. This would result in a lot of data duplication as we would duplicate shaderStage and basicBlockIndex information for all the counters. diff --git a/proposals/VK_ARM_tensors.adoc b/proposals/VK_ARM_tensors.adoc index bbc96ec51..95573dc4f 100644 --- a/proposals/VK_ARM_tensors.adoc +++ b/proposals/VK_ARM_tensors.adoc @@ -5,7 +5,7 @@ = VK_ARM_tensors :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This document describes a proposal for a new type of resource to represent diff --git a/proposals/VK_EXT_attachment_feedback_loop_dynamic_state.adoc b/proposals/VK_EXT_attachment_feedback_loop_dynamic_state.adoc index a56d7969e..594aa9e19 100644 --- a/proposals/VK_EXT_attachment_feedback_loop_dynamic_state.adoc +++ b/proposals/VK_EXT_attachment_feedback_loop_dynamic_state.adoc @@ -5,7 +5,7 @@ = VK_EXT_attachment_feedback_loop_dynamic_state :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This document proposes adding support for setting attachment feedback loops dynamically. diff --git a/proposals/VK_EXT_attachment_feedback_loop_layout.adoc b/proposals/VK_EXT_attachment_feedback_loop_layout.adoc index dcc919f99..b724ac85c 100644 --- a/proposals/VK_EXT_attachment_feedback_loop_layout.adoc +++ b/proposals/VK_EXT_attachment_feedback_loop_layout.adoc @@ -5,7 +5,7 @@ = VK_EXT_attachment_feedback_loop_layout :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This document details API design ideas for the `VK_EXT_attachment_feedback_loop_layout` extension, diff --git a/proposals/VK_EXT_calibrated_timestamps.adoc b/proposals/VK_EXT_calibrated_timestamps.adoc index 687d05675..6b0a647bd 100644 --- a/proposals/VK_EXT_calibrated_timestamps.adoc +++ b/proposals/VK_EXT_calibrated_timestamps.adoc @@ -5,7 +5,7 @@ = VK_EXT_calibrated_timestamps :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This extension provides a way to calibrate timestamps captured from different devices in the same system and guarantees monotonicity of captured timestamps. @@ -78,7 +78,7 @@ Similarly, on Linux and Linux-derived systems that support it, `VK_TIME_DOMAIN_C For Windows systems, `VK_TIME_DOMAIN_QUERY_PERFORMANCE_COUNTER_EXT` corresponds to the time domain used by https://learn.microsoft.com/en-us/windows/win32/api/profileapi/nf-profileapi-queryperformancecounter[QueryPerformanceCounter]. -Finally, the `VK_TIME_DOMAIN_DEVICE_EXT` is the time domain used by the device for all link:{docs}chapters/queries.html#vkCmdWriteTimestamp[vkCmdWriteTimestamp] commands on any queue that supports timestamps. +Finally, the `VK_TIME_DOMAIN_DEVICE_EXT` is the time domain used by the device for all xref:{refpages}vkCmdWriteTimestamp.html[vkCmdWriteTimestamp] commands on any queue that supports timestamps. Implementations must always expose the device domain and at least one other domain when this extension is supported. diff --git a/proposals/VK_EXT_custom_resolve.adoc b/proposals/VK_EXT_custom_resolve.adoc index fb1bf0770..8f7827c6d 100644 --- a/proposals/VK_EXT_custom_resolve.adoc +++ b/proposals/VK_EXT_custom_resolve.adoc @@ -5,13 +5,13 @@ = VK_EXT_custom_resolve :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This extension builds upon -link:{extensions}VK_QCOM_render_pass_shader_resolve[VK_QCOM_render_pass_shader_resolve] to +xref:{refpages}VK_QCOM_render_pass_shader_resolve.html[VK_QCOM_render_pass_shader_resolve] to allow for replacing fixed-function resolve with shader-based resolves inside render pass instances. -It additionally adds support for link:{extensions}VK_KHR_dynamic_rendering[dynamic rendering]. +It additionally adds support for xref:{refpages}VK_KHR_dynamic_rendering.html[dynamic rendering]. == Problem Statement @@ -48,7 +48,7 @@ so that a framebuffer-region dependency can replace a framebuffer-global depende == Proposal In addition to existing functionality from -link:{extensions}VK_QCOM_render_pass_shader_resolve[VK_QCOM_render_pass_shader_resolve], +xref:{refpages}VK_QCOM_render_pass_shader_resolve.html[VK_QCOM_render_pass_shader_resolve], new flags are added along with a new command to enable the same functionality with dynamic rendering. The ability to resolve to a different format from the original image is also added. @@ -85,7 +85,7 @@ color attachments. ==== Dynamic Rendering shader resolves Dynamic rendering support has been added since the original -link:{extensions}VK_QCOM_render_pass_shader_resolve[VK_QCOM_render_pass_shader_resolve] +xref:{refpages}VK_QCOM_render_pass_shader_resolve.html[VK_QCOM_render_pass_shader_resolve] extension was released. Different mechanics are used for this type of render pass. Unlike legacy render passes, the setups for dynamic rendering shader-based @@ -99,7 +99,7 @@ changes occur: * Writes to any resolving fragment shader output will write to the associated single sampled resolve attachment It is expected that users will draw a single quad with no overdraw and use -link:{extensions}VK_KHR_dynamic_rendering_local_read[VK_KHR_dynamic_rendering_local_read] +xref:{refpages}VK_KHR_dynamic_rendering_local_read.html[VK_KHR_dynamic_rendering_local_read] to read from the multisampled color or depth attachments in the shader. Overdraw will produce undefined behavior. [source,c] @@ -173,7 +173,7 @@ end of the rendering pass will output to the resolve attachments. The contents o undefined upon recording this command. `VK_SUBPASS_DESCRIPTION_FRAGMENT_REGION_BIT_EXT` is also promoted from -link:{extensions}VK_QCOM_render_pass_shader_resolve[VK_QCOM_render_pass_shader_resolve], +xref:{refpages}VK_QCOM_render_pass_shader_resolve.html[VK_QCOM_render_pass_shader_resolve], and support is added for dynamic rendering too. [source,c] @@ -203,7 +203,7 @@ No. There is no known use case for this functionality, and adding it to the spec On some implementations, in particular when using non-subsampled images, it may not be possible to have a fragment area larger than [eq]#(1,1)# while also writing directly to memory. In -link:{extensions}VK_QCOM_render_pass_shader_resolve[VK_QCOM_render_pass_shader_resolve], +xref:{refpages}VK_QCOM_render_pass_shader_resolve.html[VK_QCOM_render_pass_shader_resolve], when this occurred it was expected for the implementation to pretend that it was rendering multiple samples within the original fragment area during the custom resolve operation. However this meant that trying to compute per-pixel diff --git a/proposals/VK_EXT_depth_bias_control.adoc b/proposals/VK_EXT_depth_bias_control.adoc index 943ad5ff4..a954c7702 100644 --- a/proposals/VK_EXT_depth_bias_control.adoc +++ b/proposals/VK_EXT_depth_bias_control.adoc @@ -5,7 +5,7 @@ = VK_EXT_depth_bias_control :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This document details API design ideas for the `VK_EXT_depth_bias_control` extension, diff --git a/proposals/VK_EXT_depth_clamp_control.adoc b/proposals/VK_EXT_depth_clamp_control.adoc index ba795afef..452ee39f3 100644 --- a/proposals/VK_EXT_depth_clamp_control.adoc +++ b/proposals/VK_EXT_depth_clamp_control.adoc @@ -5,7 +5,7 @@ = VK_EXT_depth_clamp_control :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This document details API design ideas for the `VK_EXT_depth_clamp_control` @@ -157,6 +157,6 @@ This extension overrides the clamping range used only when depth clamping is enabled. The alternative would be highly unintuitive. As a consequence the -link:{extensions}VK_EXT_depth_clamp_control[VK_EXT_depth_clamp_control] +xref:{refpages}VK_EXT_depth_clamp_control.html[VK_EXT_depth_clamp_control] extension is required if depth clipping is desired in combination with this extension. diff --git a/proposals/VK_EXT_descriptor_buffer.adoc b/proposals/VK_EXT_descriptor_buffer.adoc index 4ffcc367b..cb2411fe4 100644 --- a/proposals/VK_EXT_descriptor_buffer.adoc +++ b/proposals/VK_EXT_descriptor_buffer.adoc @@ -5,7 +5,7 @@ = VK_EXT_descriptor_buffer :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This document outlines a proposal to make the management of descriptor memory more explicit, allowing descriptors to be present in buffer memory, allowing the data and memory to be managed alongside other buffer objects. @@ -42,7 +42,7 @@ There are several more-or-less invasive options that could work here: . Bypass descriptor sets, and use descriptor set layouts in buffers . Bypass descriptor set layouts, and use blobs of memory in buffers that shaders access with explicit layouts -link:{extensions}VK_VALVE_mutable_descriptor_type[VK_VALVE_mutable_descriptor_type] includes support for option 1, +xref:{refpages}VK_VALVE_mutable_descriptor_type.html[VK_VALVE_mutable_descriptor_type] includes support for option 1, through the use of `VK_DESCRIPTOR_SET_LAYOUT_CREATE_HOST_ONLY_POOL_BIT_VALVE` and `VK_DESCRIPTOR_POOL_CREATE_HOST_ONLY_BIT_VALVE`. However, this does not fully solve the problem of memory management since we can only *avoid* allocating device memory for descriptors. Being able to control where shader-accessible descriptors are allocated is still unavailable to applications. @@ -91,7 +91,7 @@ This is essentially the same model as `VkBuffer` and `VkImage` allocation. When we call `vkCmdBindDescriptorSets`, what we are really doing is binding a buffer of a certain size. The shader compiler looks at `VkPipelineLayout` and based on the `DescriptorSet` and `Binding` decorations, it can look up that a descriptor can be read from the bound descriptor set at a specific offset. -As link:{extensions}VK_EXT_descriptor_indexing[VK_EXT_descriptor_indexing] is required, its descriptor limits apply. +As xref:{refpages}VK_EXT_descriptor_indexing.html[VK_EXT_descriptor_indexing] is required, its descriptor limits apply. ==== Next level update-after-bind @@ -148,7 +148,7 @@ In terms of state invalidation, whenever a descriptor buffer offset is bound, it This extension introduces new commands to put shader-accessible descriptors directly in memory. Properties of descriptor set layouts may vary based on enabled device features, so new device-level functions are added to query the properties of layouts. -These calls are invariant across the lifetime of the device, and between link:{docs}chapters/devsandqueues.html#VkDevice[VkDevice] objects created from the same physical device(s), with the same creation parameters. +These calls are invariant across the lifetime of the device, and between xref:{refpages}VkDevice.html[VkDevice] objects created from the same physical device(s), with the same creation parameters. [source,c] ---- @@ -184,7 +184,7 @@ Descriptor set layouts used for this purpose must be created with a new create f VK_DESCRIPTOR_SET_LAYOUT_CREATE_DESCRIPTOR_BUFFER_BIT_EXT = 0x00000010 ---- -Layouts created with this flag must not be used to create a link:{docs}chapters/descriptorsets.html#VkDescriptorSet[VkDescriptorSet] and must not include dynamic uniform buffers or dynamic storage buffers. +Layouts created with this flag must not be used to create a xref:{refpages}VkDescriptorSet.html[VkDescriptorSet] and must not include dynamic uniform buffers or dynamic storage buffers. Applications can achieve the same dynamic offsetting by either updating a descriptor buffer, using push constants, or by using push descriptors. The blob of memory corresponding to a descriptor is obtained from resource views directly. How applications get that data into device memory is entirely up to them, but the offset must match that obtained from the layout. @@ -229,7 +229,7 @@ void vkGetDescriptorEXT( These APIs extract raw descriptor blob data from objects. The data obtained from these calls can be freely copied around. Note that these calls do not know anything about descriptor set layouts. It is the application's responsibility to write descriptors to a suitable location. -A notable change here is that there is no longer any need for link:{docs}chapters/resources.html#VkBufferView[VkBufferView] objects. +A notable change here is that there is no longer any need for xref:{refpages}VkBufferView.html[VkBufferView] objects. Texel buffers are built from buffer device addresses and format instead. This improvement is motivated by DX12 portability. In some use cases, texel buffers are linearly allocated and having to create and manage a large number of unique view objects is problematic. @@ -248,7 +248,7 @@ As such, applications are required to provide these samplers as if they were not These samplers must have identical parameters to the immutable samplers in the descriptor set layout. Alternatively, applications can use dedicated descriptor sets for immutable samplers that do not require app-managed memory, by <>. -If the `descriptorBufferImageLayoutIgnored` feature is enabled, the `imageLayout` in link:{docs}chapters/resources.html#VkDescriptorImageInfo[VkDescriptorImageInfo] is ignored, otherwise it specifies the layout that the descriptor will be used with. +If the `descriptorBufferImageLayoutIgnored` feature is enabled, the `imageLayout` in xref:{refpages}VkDescriptorImageInfo.html[VkDescriptorImageInfo] is ignored, otherwise it specifies the layout that the descriptor will be used with. `type` must not be `VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC` or `VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC`. 'format' in `VkDescriptorAddressInfoEXT` is ignored for non-texel buffers. @@ -514,7 +514,7 @@ typedef struct VkOpaqueCaptureDescriptorDataCreateInfoEXT { In each case, the size of the capture data is sized to the `bufferCaptureReplayDescriptorDataSize`, `imageCaptureReplayDescriptorDataSize`, `imageViewCaptureReplayDescriptorDataSize`, `samplerCaptureReplayDescriptorDataSize`, or `accelerationStructureCaptureReplayDescriptorDataSize` limits as appropriate. -In addition, link:{docs}chapters/memory.html#vkGetDeviceMemoryOpaqueCaptureAddress[vkGetDeviceMemoryOpaqueCaptureAddress] must be used to capture the opaque address and replay it with link:{docs}chapters/memory.html#VkMemoryOpaqueCaptureAddressAllocateInfo[VkMemoryOpaqueCaptureAddressAllocateInfo], for any memory used by resources with these handles. +In addition, xref:{refpages}vkGetDeviceMemoryOpaqueCaptureAddress.html[vkGetDeviceMemoryOpaqueCaptureAddress] must be used to capture the opaque address and replay it with xref:{refpages}VkMemoryOpaqueCaptureAddressAllocateInfo.html[VkMemoryOpaqueCaptureAddressAllocateInfo], for any memory used by resources with these handles. === Device Features @@ -533,7 +533,7 @@ typedef struct VkPhysicalDeviceDescriptorBufferFeaturesEXT { } VkPhysicalDeviceDescriptorBufferFeaturesEXT; ---- -If the `descriptorBuffer` feature is enabled, link:{extensions}VK_AMD_shader_fragment_mask[VK_AMD_shader_fragment_mask] must not be enabled. +If the `descriptorBuffer` feature is enabled, xref:{refpages}VK_AMD_shader_fragment_mask.html[VK_AMD_shader_fragment_mask] must not be enabled. If the `descriptorBufferImageLayoutIgnored` feature is enabled, the image layout provided when getting a descriptor is ignored. The `descriptorBufferCaptureReplay` feature is primarily for capture replay tools, and allows opaque data to be captured and replayed, allowing the same descriptor handles to be used on replay. If the `descriptorBufferPushDescriptors` features is enabled push descriptors can be used with descriptor buffers. @@ -614,7 +614,7 @@ typedef struct VkPhysicalDeviceDescriptorBufferPropertiesEXT { * `resourceDescriptorBufferAddressSpaceSize` describes the total amount of address space available, in bytes, for descriptor buffers containing resources. * `descriptorBufferAddressSpaceSize` describes the total amount of address space available, in bytes, for all descriptor buffers. -If link:{extensions}VK_VALVE_mutable_descriptor_type[VK_VALVE_mutable_descriptor_type] is used, +If xref:{refpages}VK_VALVE_mutable_descriptor_type.html[VK_VALVE_mutable_descriptor_type] is used, a descriptor is considered to be a union of all the enabled types, so the size of a descriptor is the maximum of all enabled types. [source,c] @@ -626,7 +626,7 @@ typedef struct VkPhysicalDeviceDescriptorBufferDensityMapPropertiesEXT { } VkPhysicalDeviceDescriptorBufferDensityMapPropertiesEXT; ---- -* `combinedImageSamplerDensityMapDescriptorSize` describes the size, in bytes, of a VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER descriptor when using the VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT flag of the link:{extensions}VK_EXT_fragment_density_map[VK_EXT_fragment_density_map] extension. +* `combinedImageSamplerDensityMapDescriptorSize` describes the size, in bytes, of a VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER descriptor when using the VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT flag of the xref:{refpages}VK_EXT_fragment_density_map.html[VK_EXT_fragment_density_map] extension. == Mapping to DirectX® 12 Descriptor Heaps @@ -660,7 +660,7 @@ HRESULT CreateDescriptorHeap( Implementing the equivalent functionality in Vulkan would mean the following operations: * Create a `VkDescriptorSetLayout` with `VK_DESCRIPTOR_BINDING_VARIABLE_DESCRIPTOR_COUNT_BIT`. The count would be up to 1000000 for resources, and 2048 for samplers. - ** If link:{extensions}VK_VALVE_mutable_descriptor_type[VK_VALVE_mutable_descriptor_type] is supported, we only need one descriptor set layout which supports all descriptor types for the heap type. + ** If xref:{refpages}VK_VALVE_mutable_descriptor_type.html[VK_VALVE_mutable_descriptor_type] is supported, we only need one descriptor set layout which supports all descriptor types for the heap type. ** Otherwise, there are two alternatives: *** Create up to 6 descriptor set layouts of the relevant descriptor types the application cares about (`STORAGE_BUFFER`, `UNIFORM_BUFFER`, `SAMPLED_IMAGE`, `STORAGE_IMAGE`, `UNIFORM_TEXEL_BUFFER`, `STORAGE_TEXEL_BUFFER`). *** Create one descriptor set layout with 6 fixed-size arrays instead of using variable descriptor counts. This means `NumDescriptors` is effectively ignored. diff --git a/proposals/VK_EXT_descriptor_heap.adoc b/proposals/VK_EXT_descriptor_heap.adoc index 8f04258d5..9958f3f63 100644 --- a/proposals/VK_EXT_descriptor_heap.adoc +++ b/proposals/VK_EXT_descriptor_heap.adoc @@ -5,9 +5,9 @@ = VK_EXT_descriptor_heap :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :spirvextensions: https://github.khronos.org/SPIRV-Registry/extensions/ -:VK_EXT_descriptor_buffer: link:{extensions}VK_EXT_descriptor_buffer[VK_EXT_descriptor_buffer] +:VK_EXT_descriptor_buffer: xref:{refpages}VK_EXT_descriptor_buffer.html[VK_EXT_descriptor_buffer] :sectnums: // Required so images render in github ifndef::images[:images: ../images] @@ -23,7 +23,7 @@ This expands on {VK_EXT_descriptor_buffer} to solve a number of identified issue * While buffer view creation is no longer required, image view creation is - meaning an additional object must be managed by applications. ** Ideally, descriptors could be created directly from images to avoid this. * There are several ways to provide constant data to shaders, and it is unclear which of those should be preferred in a given situation. -** link:{extensions}VK_EXT_inline_uniform_block[VK_EXT_inline_uniform_block] added one more (embedding constants in descriptor sets), but this method is not necessarily a universal fast path. +** xref:{refpages}VK_EXT_inline_uniform_block.html[VK_EXT_inline_uniform_block] added one more (embedding constants in descriptor sets), but this method is not necessarily a universal fast path. ** If a consistent fast path can be established, it would greatly simplify the developer experience and allow us to have definitive portable guidelines * Consistency between vendors is low - multiple vendors have dedicated image and sampler heaps, but descriptor buffers were initially advertised as general purpose, and only reined in by usage bits. ** This led to some dispute about how best to implement these - whether descriptor buffers should contain indexes (similar to link:https://registry.khronos.org/OpenGL/extensions/ARB/ARB_bindless_texture.txt[GL_ARB_bindless_texture]), or if they should be real descriptors. Subsequently, performance portability is lower than ideal. @@ -57,7 +57,7 @@ There are several other bits of information in this post that have been used to This proposal assumes, but does not require, an understanding of {VK_EXT_descriptor_buffer}; it is recommended that you read the background information in its proposal document before reading this. -This extension requires link:{extensions}VK_KHR_buffer_device_address[VK_KHR_buffer_device_address] or Vulkan 1.2, and link:{extensions}VK_KHR_shader_untyped_pointers[VK_KHR_shader_untyped_pointers]. +This extension requires xref:{refpages}VK_KHR_buffer_device_address.html[VK_KHR_buffer_device_address] or Vulkan 1.2, and xref:{refpages}VK_KHR_shader_untyped_pointers.html[VK_KHR_shader_untyped_pointers]. === Overview @@ -138,7 +138,7 @@ VkResult vkWriteResourceDescriptorsEXT( const VkHostAddressRangeEXT* pDescriptors); ---- -Unlike link:{docs}descriptorsets.html#vkGetDescriptorEXT[vkGetDescriptorEXT], multiple descriptors can be written at once, allowing for more rapid execution. +Unlike xref:{refpages}vkGetDescriptorEXT.html[vkGetDescriptorEXT], multiple descriptors can be written at once, allowing for more rapid execution. When implementing {VK_EXT_descriptor_buffer}, Virtual Machine (VM) implementations noted that this was a high frequency call with immediate return needed; which meant significant latency going through the VM to the native driver for each call and waiting for the result. Allowing this operation to be arrayed allows this call traffic to be significantly reduced. The functions are also renamed to `vkWrite*` to reflect this change, and the expectation is that applications will write descriptors directly into memory used as a local heap. @@ -189,7 +189,7 @@ Descriptors created from a fully identical `Vk*DescriptorInfoEXT` structure on t When writing image descriptors for formats that can be used with YC~B~C~R~ conversion, additional constraints apply to writing those descriptors to accommodate the fact that each such resource may require multiple descriptors. -For `vkWriteResourceDescriptorsEXT`, if `pResources[i]` has a `type` of `VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE` and `VkSamplerYcbcrConversionInfo` is included in the `pNext` chain of `data.pImage->pView`, `pDescriptors[i]->size` must be greater than or equal to the size of `imageDescriptorSize` multiplied by the value of link:{docs}capabilities.html#VkSamplerYcbcrConversionImageFormatProperties[VkSamplerYcbcrConversionImageFormatProperties::combinedImageSamplerDescriptorCount] for the format of that image. +For `vkWriteResourceDescriptorsEXT`, if `pResources[i]` has a `type` of `VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE` and `VkSamplerYcbcrConversionInfo` is included in the `pNext` chain of `data.pImage->pView`, `pDescriptors[i]->size` must be greater than or equal to the size of `imageDescriptorSize` multiplied by the value of xref:{refpages}VkSamplerYcbcrConversionImageFormatProperties.html[VkSamplerYcbcrConversionImageFormatProperties::combinedImageSamplerDescriptorCount] for the format of that image. YC~B~C~R~ samplers cannot be written by `vkWriteSamplerDescriptorsEXT`, and instead must be embedded using the mapping APIs. @@ -231,10 +231,14 @@ Rather than having "generic" looking descriptor buffers like {VK_EXT_descriptor_ This approach makes code written against this extension more readily portable, as no querying is involved to figure this out. If any applications want descriptor access from generic buffers, the portable method for doing so is to store indices in those generic buffers, leaving real descriptors in the heaps and doing an indirection (e.g. similar to https://blog.traverseresearch.nl/bindless-rendering-setup-afeb678d77fc[Traverse's bindless resource scheme]). +// The blog link above cannot be directly opened by the link checker - +// apparently you have to go through the blog host and click on it there. +// This is probably OK for the intended use case of proposals. + [NOTE] ==== There may be a high synchronization cost for binding a new heap on some implementations, or switching between heaps and descriptor sets - applications should generally stick to the same heap throughout the lifetime of the application, only swapping to a new heap if absolutely necessary. -This mirrors the advice given in {VK_EXT_descriptor_buffer} for link:{docs}descriptorsets.html#vkCmdBindDescriptorBuffersEXT[vkCmdBindDescriptorBuffersEXT], or for heap bindings in DirectX® 12. +This mirrors the advice given in {VK_EXT_descriptor_buffer} for xref:{refpages}vkCmdBindDescriptorBuffersEXT.html[vkCmdBindDescriptorBuffersEXT], or for heap bindings in DirectX® 12. The implementation is wholly responsible for ensuring this synchronization is performed, including any initialization to the implementation reserved range. ==== @@ -260,7 +264,7 @@ Each of these commands takes a single `VkBindHeapInfoEXT` structure, which has t In each heap range, bytes from `reservedRangeOffset` up to `reservedRangeSize` must be fully backed by physical memory, and must not be accessed or modified by the application once bound. For a sampler heap, if it is going to be used with pipelines or shaders that include embedded samplers, this range must be sized according to `minSamplerHeapReservedRangeWithEmbedded` for the sampler heap instead. Applications must not modify the memory or memory bindings for any bound reserved range until all command buffers with that bound range are freed or reset. -The implementation manages these bytes for internal descriptors needed to ensure correct operation of things like embedded samplers and fixed operations (e.g. link:{docs}copies.html#vkCmdBlitImage[vkCmdBlitImage]). +The implementation manages these bytes for internal descriptors needed to ensure correct operation of things like embedded samplers and fixed operations (e.g. xref:{refpages}vkCmdBlitImage.html[vkCmdBlitImage]). Applications may reuse the same range of reserved bytes in multiple command buffers, but must not use a _partially_ overlapping range of reserved bytes in multiple command buffers simultaneously - doing so will result in undefined behavior. Binding the sampler and resource heaps to overlapping address ranges is allowed, but the reserved ranges for each heap must not overlap with each other. @@ -295,7 +299,7 @@ static const VkPipelineCreateFlagBits2KHR VK_PIPELINE_CREATE_2_DESCRIPTOR_HEAP_B When a pipeline is created with this flag, the pipeline layout must be `NULL`, and resources used by its shaders will be sourced from a descriptor heap. Shaders using heaps can access resources without `Binding` and `DescriptorSet` decorations, instead accessing the heaps directly as memory via new built-in pointers to the base of each heap - see <> for more information. -When link:{extensions}VK_EXT_shader_object[VK_EXT_shader_object] is supported, a shader create flag is similarly provided: +When xref:{refpages}VK_EXT_shader_object.html[VK_EXT_shader_object] is supported, a shader create flag is similarly provided: [source,c] ---- @@ -331,7 +335,7 @@ This command does not distinguish between data types, instead storing them all a Push constants in this data can be accessed in the same way as before via the `PushConstant` storage class, it is now simply unnecessary to construct a pipeline layout to do that. -`vkCmdPushDataEXT` will invalidate, and be invalidated by, any state set by link:{docs}descriptorsets.html#vkCmdPushConstants[vkCmdPushConstants], link:{docs}descriptorsets.html#vkCmdPushDescriptorSetKHR[vkCmdPushDescriptorSetKHR], or link:{docs}descriptorsets.html#vkCmdPushDescriptorSetWithTemplateKHR[vkCmdPushDescriptorSetWithTemplateKHR]. +`vkCmdPushDataEXT` will invalidate, and be invalidated by, any state set by xref:{refpages}vkCmdPushConstants.html[vkCmdPushConstants], xref:{refpages}vkCmdPushDescriptorSetKHR.html[vkCmdPushDescriptorSetKHR], or xref:{refpages}vkCmdPushDescriptorSetWithTemplateKHR.html[vkCmdPushDescriptorSetWithTemplateKHR]. Applications are advised to put device addresses into push data for larger amounts of data; implementations with pre-fetch paths will be able to pre-fetch these if they are statically referenced in the shader, providing an optimal path for larger data sets. @@ -493,7 +497,7 @@ typedef struct VkShaderDescriptorSetAndBindingMappingInfoEXT { } VkShaderDescriptorSetAndBindingMappingInfoEXT; ---- -`VkShaderDescriptorSetAndBindingMappingInfoEXT` can be chained to the `pNext` chain of link:{docs}pipelines.html#VkPipelineShaderStageCreateInfo[VkPipelineShaderStageCreateInfo] or link:{docs}shaders.html#VkShaderCreateInfoEXT[VkShaderCreateInfoEXT] to indicate where resources with `DescriptorSet` and `Binding` decorations should be sourced from for that shader. +`VkShaderDescriptorSetAndBindingMappingInfoEXT` can be chained to the `pNext` chain of xref:{refpages}VkPipelineShaderStageCreateInfo.html[VkPipelineShaderStageCreateInfo] or xref:{refpages}VkShaderCreateInfoEXT.html[VkShaderCreateInfoEXT] to indicate where resources with `DescriptorSet` and `Binding` decorations should be sourced from for that shader. If the shader declares any resource variables with set and binding values, this structure must specify mappings for them. Elements of `pMappings` define for a single `DescriptorSet` value and a range of `Binding` values where the resources at those bindings are sourced from. @@ -720,12 +724,12 @@ Bindings must be respecified in the primary command buffer after === Null Descriptors -When the `nullDescriptor` feature added by link:{extensions}VK_EXT_robustness2[VK_EXT_robustness2] is supported, null descriptors can be written by setting the corresponding element of `VkResourceDescriptorDataEXT` to `NULL` when writing a resource descriptor. +When the `nullDescriptor` feature added by xref:{refpages}VK_EXT_robustness2.html[VK_EXT_robustness2] is supported, null descriptors can be written by setting the corresponding element of `VkResourceDescriptorDataEXT` to `NULL` when writing a resource descriptor. === Custom Border Color -When the `customBorderColors` feature added by link:{extensions}VK_EXT_custom_border_color[VK_EXT_custom_border_color] is used, applications using samplers with custom border colors must explicitly register and unregister border colors with the device: +When the `customBorderColors` feature added by xref:{refpages}VK_EXT_custom_border_color.html[VK_EXT_custom_border_color] is used, applications using samplers with custom border colors must explicitly register and unregister border colors with the device: [source,c] ---- @@ -740,7 +744,7 @@ void vkUnregisterCustomBorderColorEXT( uint32_t index); ---- -Up to link:{docs}limits.html#VkPhysicalDeviceCustomBorderColorPropertiesEXT[`VkPhysicalDeviceCustomBorderColorPropertiesEXT::maxCustomBorderColorSamplers`] border colors can be registered; if too many are already registered, `vkRegisterCustomBorderColorEXT` will return `VK_ERROR_TOO_MANY_OBJECTS`. +Up to xref:{refpages}VkPhysicalDeviceCustomBorderColorPropertiesEXT.html[`VkPhysicalDeviceCustomBorderColorPropertiesEXT::maxCustomBorderColorSamplers`] border colors can be registered; if too many are already registered, `vkRegisterCustomBorderColorEXT` will return `VK_ERROR_TOO_MANY_OBJECTS`. `vkUnregisterCustomBorderColorEXT` will remove one registration, freeing it up for a new registration. `vkRegisterCustomBorderColorEXT` is not subject to fragmentation - these functions will always correctly update the number of registrations, and `vkRegisterCustomBorderColorEXT` will always succeed if there are free slots. `vkRegisterCustomBorderColorEXT` will not automatically de-duplicate identical custom border colors, but an application is free to use the same index for multiple samplers with the same border color. @@ -772,7 +776,7 @@ There are no absolute guarantees that replay will succeed, as system updates, me Implementations are expected to provide a best effort to ensure captured descriptors can be replayed, but are not expected to work around exceptional circumstances, or across driver versions or devices. For the best chance of success, applications should replay in a separate process, using the same system, driver, and device, without any updates since the replay. -Additionally, tools must capture some data from the implementation during capture to give the implementation the information to recreate identical descriptors during replay, should use an identically created link:{repage}VkDevice.html[VkDevice] and link:{repage}VkInstance.html[VkInstance], and should create all captured descriptors before creating any others for use in the tool. +Additionally, tools must capture some data from the implementation during capture to give the implementation the information to recreate identical descriptors during replay, should use an identically created xref:{refpages}VkDevice.html[VkDevice] and xref:{refpages}VkInstance.html[VkInstance], and should create all captured descriptors before creating any others for use in the tool. ==== Samplers @@ -784,15 +788,15 @@ If the sampler is using custom border colors however, this means the index must ==== Device Addresses For descriptors requiring a device address, again an identical `VkDeviceAddressRangeEXT` or `VkTexelBufferDescriptorInfoEXT` is required to try to create the same descriptor. -To try to get the same device address range for a buffer allocation, tools can use the link:{docs}features.html#VkPhysicalDeviceBufferDeviceAddressFeatures[VkPhysicalDeviceBufferDeviceAddressFeatures::bufferDeviceAddressCaptureReplay] feature to recreate the buffer and any memory it is bound to with opaque capture data. -link:{docs}features.html#VkPhysicalDeviceBufferDeviceAddressFeatures[VkPhysicalDeviceBufferDeviceAddressFeatures::bufferDeviceAddressCaptureReplay] must be supported if `descriptorHeapCaptureReplay` is supported. +To try to get the same device address range for a buffer allocation, tools can use the xref:{refpages}VkPhysicalDeviceBufferDeviceAddressFeatures.html[VkPhysicalDeviceBufferDeviceAddressFeatures::bufferDeviceAddressCaptureReplay] feature to recreate the buffer and any memory it is bound to with opaque capture data. +xref:{refpages}VkPhysicalDeviceBufferDeviceAddressFeatures.html[VkPhysicalDeviceBufferDeviceAddressFeatures::bufferDeviceAddressCaptureReplay] must be supported if `descriptorHeapCaptureReplay` is supported. ==== Images For image descriptors created using a `VkImage` an identical `VkImageDescriptorInfoEXT`, other than the image itself, is required to try to create the same descriptor. For replay, the image must be recreated using the same creation parameters, but with additional opaque data captured in the first run, similar to how buffers must recreated with opaque data to try to obtain the same device address. -Memory bound to the image during replay must match the memory bound during capture, with memory objects recreated with identical parameters other than including the opaque capture data in link:{docs}memory.html#VkDeviceMemoryOpaqueCaptureAddressInfo[VkDeviceMemoryOpaqueCaptureAddressInfo] which was initially captured with link:{docs}memory.html#vkGetDeviceMemoryOpaqueCaptureAddress[vkGetDeviceMemoryOpaqueCaptureAddress]. +Memory bound to the image during replay must match the memory bound during capture, with memory objects recreated with identical parameters other than including the opaque capture data in xref:{refpages}VkDeviceMemoryOpaqueCaptureAddressInfo.html[VkDeviceMemoryOpaqueCaptureAddressInfo] which was initially captured with xref:{refpages}vkGetDeviceMemoryOpaqueCaptureAddress.html[vkGetDeviceMemoryOpaqueCaptureAddress]. This opaque data can be captured for multiple images with: [source,c] @@ -812,7 +816,7 @@ In order for this function to be valid, each image must be created with the foll VK_IMAGE_CREATE_DESCRIPTOR_HEAP_CAPTURE_REPLAY_BIT_EXT = 0x00010000 ---- -An image with this flag can be recreated from a previously captured image by passing `data` back into image creation by chaining the following structure to link:{docs}resources.html#VkImageCreateInfo[VkImageCreateInfo], with all other creation parameters matching: +An image with this flag can be recreated from a previously captured image by passing `data` back into image creation by chaining the following structure to xref:{refpages}VkImageCreateInfo.html[VkImageCreateInfo], with all other creation parameters matching: [source,c] ---- @@ -823,7 +827,7 @@ typedef struct VkOpaqueCaptureDataCreateInfoEXT { } VkOpaqueCaptureDataCreateInfoEXT; ---- -If the implementation is unable to recreate an identical image from this opaque data that would result in the same descriptors, link:{docs}resources.html#vkCreateImage[vkCreateImage] must return `VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS`. +If the implementation is unable to recreate an identical image from this opaque data that would result in the same descriptors, xref:{refpages}vkCreateImage.html[vkCreateImage] must return `VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS`. Implementations may return `VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS` when writing an image descriptor if the image was created with `VkOpaqueCaptureDataCreateInfoEXT` and the implementation cannot recreate the same descriptor. If `pData` is `NULL`, or if this structure is not present, image creation will proceed without matching previously captured data. @@ -837,7 +841,7 @@ Tensors can be captured and replayed similarly to images. For tensor descriptors created using a `VkTensorARM` an identical `VkTensorViewCreateInfoARM`, other than the tensor itself, is required to try to create the same descriptor. For replay, the tensor must be recreated using the same creation parameters, but with additional opaque data captured in the first run in the same way as for images. -Memory bound to the tensor during replay must match the memory bound during capture, with memory objects recreated with identical parameters other than including the opaque capture data in link:{docs}memory.html#VkDeviceMemoryOpaqueCaptureAddressInfo[VkDeviceMemoryOpaqueCaptureAddressInfo] which was initially captured with link:{docs}memory.html#vkGetDeviceMemoryOpaqueCaptureAddress[vkGetDeviceMemoryOpaqueCaptureAddress]. +Memory bound to the tensor during replay must match the memory bound during capture, with memory objects recreated with identical parameters other than including the opaque capture data in xref:{refpages}VkDeviceMemoryOpaqueCaptureAddressInfo.html[VkDeviceMemoryOpaqueCaptureAddressInfo] which was initially captured with xref:{refpages}vkGetDeviceMemoryOpaqueCaptureAddress.html[vkGetDeviceMemoryOpaqueCaptureAddress]. This opaque data can be captured for multiple tensors with: [source,c] @@ -857,9 +861,9 @@ In order for this function to be valid, each tensor must be created with the fol VK_TENSOR_CREATE_DESCRIPTOR_HEAP_CAPTURE_REPLAY_BIT_ARM = 0x00000004 ---- -A tensor with this flag can be recreated from a previously captured tensor by passing `data` back into tensor creation by chaining `VkOpaqueCaptureDataCreateInfoEXT` to link:{docs}resources.html#VkTensorCreateInfo[VkTensorCreateInfo], with all other creation parameters matching. +A tensor with this flag can be recreated from a previously captured tensor by passing `data` back into tensor creation by chaining `VkOpaqueCaptureDataCreateInfoEXT` to xref:{refpages}VkTensorCreateInfoARM.html[VkTensorCreateInfoARM], with all other creation parameters matching. -If the implementation is unable to recreate an identical tensor from this opaque data that would result in the same descriptors, link:{docs}resources.html#vkCreateTensorARM[vkCreateTensorARM] must return `VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS`. +If the implementation is unable to recreate an identical tensor from this opaque data that would result in the same descriptors, xref:{refpages}vkCreateTensorARM.html[vkCreateTensorARM] must return `VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS`. Implementations may return `VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS` when writing an tensor descriptor if the tensor was created with `VkOpaqueCaptureDataCreateInfoEXT` and the implementation cannot recreate the same descriptor. If `pData` is `NULL`, or if this structure is not present, tensor creation will proceed without matching previously captured data. @@ -903,7 +907,7 @@ typedef struct VkIndirectCommandsLayoutPushDataTokenNV { ---- This new token functions similarly to the push constant token, but does not require a pipeline layout or shader stage flags, both of which are similarly absent from `vkCmdPushDataEXT`. -`VkIndirectCommandsLayoutPushDataTokenNV` can be included in the `pNext` chain of link:{docs}device_generated_commands/generatedcommands.html#VkIndirectCommandsLayoutTokenNV[VkIndirectCommandsLayoutTokenNV] when the `VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_DATA_NV` token type is specified to enable the use of this token. +`VkIndirectCommandsLayoutPushDataTokenNV` can be included in the `pNext` chain of xref:{refpages}VkIndirectCommandsLayoutTokenNV.html[VkIndirectCommandsLayoutTokenNV] when the `VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_DATA_NV` token type is specified to enable the use of this token. === Interaction with VK_EXT_fragment_density_map @@ -919,7 +923,7 @@ typedef struct VkSubsampledImageFormatPropertiesEXT { } VkSubsampledImageFormatPropertiesEXT; ---- -This structure can be included in the `pNext` chain of link:{docs}capabilities.html#VkImageFormatProperties2[VkImageFormatProperties2] to query the number of image descriptors required for subsampled images. +This structure can be included in the `pNext` chain of xref:{refpages}VkImageFormatProperties2.html[VkImageFormatProperties2] to query the number of image descriptors required for subsampled images. === Device Features @@ -936,7 +940,7 @@ typedef struct VkPhysicalDeviceDescriptorHeapFeaturesEXT { } VkPhysicalDeviceDescriptorHeapFeaturesEXT; ---- -If the `descriptorHeap` feature is enabled, link:{extensions}VK_AMD_shader_fragment_mask[VK_AMD_shader_fragment_mask] must not be enabled. +If the `descriptorHeap` feature is enabled, xref:{refpages}VK_AMD_shader_fragment_mask.html[VK_AMD_shader_fragment_mask] must not be enabled. The `descriptorHeapCaptureReplay` feature is primarily for capture replay tools, and allows opaque image data to be captured and replayed, allowing the same descriptor handles to be used on replay. Supporting `descriptorHeapCaptureReplay` is _strongly_ recommended. @@ -1019,7 +1023,7 @@ These properties have the following required values: | bufferDescriptorAlignment | 128 | max | bufferDescriptorSize | maxPushDataSize | 256 | min | Matches DirectX 12 requirements for root parameters | maxDescriptorHeapEmbeddedSamplers | 2032 | min | DirectX 12 static sampler limit -| samplerYcbcrConversionCount | 3 | max | link:{docs}capabilities.html#VkSamplerYcbcrConversionImageFormatProperties[combinedImageSamplerDescriptorCount] +| samplerYcbcrConversionCount | 3 | max | xref:{refpages}VkSamplerYcbcrConversionImageFormatProperties.html[combinedImageSamplerDescriptorCount] |==== [[limit-tool-allowances]] @@ -1085,27 +1089,27 @@ In general, applications can ignore this function and just use the base sizes pr ==== -== Interaction with link:{extensions}VK_EXT_debug_utils[VK_EXT_debug_utils] +== Interaction with xref:{refpages}VK_EXT_debug_utils.html[VK_EXT_debug_utils] -As this extension allows the creation of descriptors without ever creating a sampler, image view, or buffer view object, in order to allow naming the resulting descriptors, link:{docs}debugging.html#VkDebugUtilsObjectNameInfoEXT[VkDebugUtilsObjectNameInfoEXT] can now be included in the `pNext` chain of `VkSamplerCreateInfo` and `VkResourceDescriptorInfoEXT` when either writing a descriptor or creating an embedded sampler, which associates a static name with the written descriptor. +As this extension allows the creation of descriptors without ever creating a sampler, image view, or buffer view object, in order to allow naming the resulting descriptors, xref:{refpages}VkDebugUtilsObjectNameInfoEXT.html[VkDebugUtilsObjectNameInfoEXT] can now be included in the `pNext` chain of `VkSamplerCreateInfo` and `VkResourceDescriptorInfoEXT` when either writing a descriptor or creating an embedded sampler, which associates a static name with the written descriptor. Note however that this is not necessarily a precise association - implementations may choose to simply associate the descriptor's bit patterns with the provided name, which can result in multiple descriptors taking the same name if those descriptors' bits match. For example, in some operations, whether an image uses an sRGB or linear encoding will not change the operation, so implementations may generate the same descriptor bits for image views with the format being the only difference. Tools may choose to free labels if the underlying data becomes invalid (e.g. the address range or image is freed). -== Interaction with link:{extensions}VK_KHR_pipeline_library[VK_KHR_pipeline_library] +== Interaction with xref:{refpages}VK_KHR_pipeline_library.html[VK_KHR_pipeline_library] When linking multiple pipelines, all pipelines must either have all been compiled with `VK_PIPELINE_CREATE_2_DESCRIPTOR_HEAP_BIT_EXT` specified, or all without it. Intermediate linked pipelines do not need to be additionally created with this flag if they are only linking other pipelines which have it. -== Interaction with link:{extensions}VK_EXT_graphics_pipeline_library[VK_EXT_graphics_pipeline_library] +== Interaction with xref:{refpages}VK_EXT_graphics_pipeline_library.html[VK_EXT_graphics_pipeline_library] When linking graphics pipeline libraries, if all pipelines were compiled with `VK_PIPELINE_CREATE_2_DESCRIPTOR_HEAP_BIT_EXT`, a pipeline layout must not be specified. There is also no need for matching of any of the descriptor mappings between different libraries; the application is responsible for packing data into push constants and heaps, so the implementation does not need to, and cannot, optimize that packing. -== link:{docs}resources.html#VkDescriptorSetLayout[VkDescriptorSetLayout] Mapping +== xref:{refpages}VkDescriptorSetLayout.html[VkDescriptorSetLayout] Mapping Specifying a descriptor set layout is how, prior to this extension, applications were able to specify how to bind resources between the API and shader code. Everything that was previously possible with descriptor set layouts is possible with the new `VkShaderDescriptorSetAndBindingMappingInfoEXT` structure, but it becomes the application's responsibility to layout descriptors in the heaps, rather than relying on the implementation to do it. @@ -1264,7 +1268,7 @@ VkShaderDescriptorSetAndBindingMappingInfoEXT nonVertexMappings = { === Example: Push Constants -With the existing descriptor set layout interface, applications need to specify the push constants they are using in each shader stage with link:{docs}descriptorsets.html#VkPipelineLayoutCreateInfo[VkPipelineLayoutCreateInfo]. +With the existing descriptor set layout interface, applications need to specify the push constants they are using in each shader stage with xref:{refpages}VkPipelineLayoutCreateInfo.html[VkPipelineLayoutCreateInfo]. However, there is no need for any specific matching here; the push data state in the command buffer is treated as an opaque blob of data, and the shader simply interprets that data as it describes. As such, this example is empty - applications can simply delete any code related to pipeline layouts and just use the data as-is. @@ -1747,7 +1751,7 @@ Work to <> is ongoing. === How does YC~B~C~R~ sampling work with the bindless interface? For now it still requires set and binding, mapping to shader combined image samplers. -A number of image descriptors will be consumed for each such resource, according to link:{docs}capabilities.html#VkSamplerYcbcrConversionImageFormatProperties[VkSamplerYcbcrConversionImageFormatProperties::combinedImageSamplerDescriptorCount]. +A number of image descriptors will be consumed for each such resource, according to xref:{refpages}VkSamplerYcbcrConversionImageFormatProperties.html[VkSamplerYcbcrConversionImageFormatProperties::combinedImageSamplerDescriptorCount]. === How does sampling of subsampled images for fragment density maps work with the bindless interface? @@ -1777,7 +1781,7 @@ It is also expected that a significant portion of existing content (particularly === What are the indexing rules when using descriptor heaps? -They are largely the same as link:{extensions}VK_EXT_descriptor_indexing[VK_EXT_descriptor_indexing] with all features enabled - indexing may be non-uniform, but does not need the expression to be tagged as non-uniform. +They are largely the same as xref:{refpages}VK_EXT_descriptor_indexing.html[VK_EXT_descriptor_indexing] with all features enabled - indexing may be non-uniform, but does not need the expression to be tagged as non-uniform. === How are embedded samplers handled on implementations that cannot embed them in shader constant data? @@ -1831,12 +1835,12 @@ So that each pointer can be set to `NULL` to define a "null descriptor" when int === How can I use debug labels with descriptor heaps? -Labels can be associated with patterns of descriptor bits when they are written, or with embedded samplers during pipeline creation, by chaining link:{docs}debugging.html#VkDebugUtilsObjectNameInfoEXT[VkDebugUtilsObjectNameInfoEXT] structures into `VkResourceDescriptorInfoEXT` or `VkSamplerCreateInfo`. +Labels can be associated with patterns of descriptor bits when they are written, or with embedded samplers during pipeline creation, by chaining xref:{refpages}VkDebugUtilsObjectNameInfoEXT.html[VkDebugUtilsObjectNameInfoEXT] structures into `VkResourceDescriptorInfoEXT` or `VkSamplerCreateInfo`. See <> for further information. -=== Why is link:{extensions}VK_KHR_shader_untyped_pointers[VK_KHR_shader_untyped_pointers] not a dependency, but still required by implementations? +=== Why is xref:{refpages}VK_KHR_shader_untyped_pointers.html[VK_KHR_shader_untyped_pointers] not a dependency, but still required by implementations? Untyped pointers are only necessary when accessing the heap directly from the shader; for applications using shader mappings, they are not needed, so the extension can be omitted in this case. diff --git a/proposals/VK_EXT_device_fault.adoc b/proposals/VK_EXT_device_fault.adoc index ffa40c102..6fc89e885 100644 --- a/proposals/VK_EXT_device_fault.adoc +++ b/proposals/VK_EXT_device_fault.adoc @@ -5,7 +5,7 @@ = VK_EXT_device_fault :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This document outlines functionality to allow applications to query for diff --git a/proposals/VK_EXT_device_generated_commands.adoc b/proposals/VK_EXT_device_generated_commands.adoc index bd752a553..bbf002652 100644 --- a/proposals/VK_EXT_device_generated_commands.adoc +++ b/proposals/VK_EXT_device_generated_commands.adoc @@ -5,7 +5,7 @@ = VK_EXT_device_generated_commands :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: // Required so images render in github ifndef::images[:images: ../images] @@ -457,7 +457,7 @@ typedef VkFlags VkIndirectCommandsLayoutUsageFlagsEXT; - `VK_INDIRECT_COMMANDS_LAYOUT_USAGE_EXPLICIT_PREPROCESS_BIT_EXT` specifies that the layout is always used with the manual preprocessing step through calling `vkCmdPreprocessGeneratedCommandsEXT` and executed by `vkCmdExecuteGeneratedCommandsEXT` when `isPreprocessed` set to `VK_TRUE`. -- `VK_INDIRECT_COMMANDS_LAYOUT_USAGE_UNORDERED_SEQUENCES_BIT_EXT` specifies that link:{docs}chapters/synchronization.html#synchronization-submission-order[submission order] is not affected by the ordering of sequences, and sequences may be processed in any order. +- `VK_INDIRECT_COMMANDS_LAYOUT_USAGE_UNORDERED_SEQUENCES_BIT_EXT` specifies that xref:{docs}chapters/synchronization.html#synchronization-submission-order[submission order] is not affected by the ordering of sequences, and sequences may be processed in any order. Indirect command layouts are destroyed by: diff --git a/proposals/VK_EXT_dynamic_rendering_unused_attachments.adoc b/proposals/VK_EXT_dynamic_rendering_unused_attachments.adoc index 98489a9a7..f0d00b3c8 100644 --- a/proposals/VK_EXT_dynamic_rendering_unused_attachments.adoc +++ b/proposals/VK_EXT_dynamic_rendering_unused_attachments.adoc @@ -5,16 +5,16 @@ = VK_EXT_dynamic_rendering_unused_attachments :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: -This document describes a limitation with link:{extensions}VK_KHR_dynamic_rendering[VK_KHR_dynamic_rendering] that limits what +This document describes a limitation with xref:{refpages}VK_KHR_dynamic_rendering.html[VK_KHR_dynamic_rendering] that limits what pipelines can be used with render pass instances, and may subsequently require many more pipeline objects to be created to work around the limitation. == Problem Statement -The link:{extensions}VK_KHR_dynamic_rendering[VK_KHR_dynamic_rendering] has several restrictions on what pipelines can be +The xref:{refpages}VK_KHR_dynamic_rendering.html[VK_KHR_dynamic_rendering] has several restrictions on what pipelines can be bound within a render pass instance which may cause the application to have to create multiple variants of the pipeline object in order to be compatible with the render pass instance. @@ -83,8 +83,8 @@ unused, and where it matches with unused the writes are discarded. == Proposal -Implementations may expose the link:{extensions}VK_EXT_dynamic_rendering_unused_attachments[VK_EXT_dynamic_rendering_unused_attachments] extension +Implementations may expose the xref:{refpages}VK_EXT_dynamic_rendering_unused_attachments.html[VK_EXT_dynamic_rendering_unused_attachments] extension and the -link:{docs}chapters/features.html#VkPhysicalDeviceDynamicRenderingUnusedAttachmentsFeaturesEXT[VkPhysicalDeviceDynamicRenderingUnusedAttachmentsFeaturesEXT]::`dynamicRenderingUnusedAttachments` +xref:{refpages}VkPhysicalDeviceDynamicRenderingUnusedAttachmentsFeaturesEXT.html[VkPhysicalDeviceDynamicRenderingUnusedAttachmentsFeaturesEXT]::`dynamicRenderingUnusedAttachments` feature which allows apps to bind pipelines to render pass instances where attachment formats can match with unused attachments. diff --git a/proposals/VK_EXT_extended_dynamic_state3.adoc b/proposals/VK_EXT_extended_dynamic_state3.adoc index fda0dc59c..dbefa2298 100644 --- a/proposals/VK_EXT_extended_dynamic_state3.adoc +++ b/proposals/VK_EXT_extended_dynamic_state3.adoc @@ -5,7 +5,7 @@ = VK_EXT_extended_dynamic_state3 :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This document details the motivation behind another extended dynamic state extension, which follows VK_EXT_extended_dynamic_state and VK_EXT_extended_dynamic_state2. diff --git a/proposals/VK_EXT_external_memory_acquire_unmodified.adoc b/proposals/VK_EXT_external_memory_acquire_unmodified.adoc index e425063ee..dc9227a89 100644 --- a/proposals/VK_EXT_external_memory_acquire_unmodified.adoc +++ b/proposals/VK_EXT_external_memory_acquire_unmodified.adoc @@ -5,13 +5,13 @@ = VK_EXT_external_memory_acquire_unmodified :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This document proposes adding a performance hint that may reduce the runtime cost of memory barriers that acquire ownership of a resource from an external queue family (such as -link:{docs}chapters/synchronization.html#VK_QUEUE_FAMILY_FOREIGN_EXT[VK_QUEUE_FAMILY_FOREIGN_EXT]). +xref:{refpages}VK_QUEUE_FAMILY_FOREIGN_EXT.html[VK_QUEUE_FAMILY_FOREIGN_EXT]). == Problem Statement @@ -22,24 +22,24 @@ noticeable latency. An external resource's data may be split between external memory and non-external memory. The resource's _external memory_ is the collection of ranges -of link:{docs}chapters/memory.html#VkDeviceMemory[VkDeviceMemory] bound to the resource, -where the link:{docs}chapters/memory.html#VkDeviceMemory[VkDeviceMemory] has been imported or +of xref:{refpages}VkDeviceMemory.html[VkDeviceMemory] bound to the resource, +where the xref:{refpages}VkDeviceMemory.html[VkDeviceMemory] has been imported or exported with an API related to -link:{extensions}VK_KHR_external_memory[VK_KHR_external_memory]. +xref:{refpages}VK_KHR_external_memory.html[VK_KHR_external_memory]. The external memory is shared among all external APIs and/or processes that access the resource. The resource's _non-external memory_, in this discussion, is any implementation-private memory that is associated with the resource -and does not reside in any range of link:{docs}chapters/memory.html#VkDeviceMemory[VkDeviceMemory] bound to the resource. -For example, if the external resource is a link:{docs}chapters/resources.html#VkImage[VkImage], +and does not reside in any range of xref:{refpages}VkDeviceMemory.html[VkDeviceMemory] bound to the resource. +For example, if the external resource is a xref:{refpages}VkImage.html[VkImage], then in some Vulkan implementations the external memory may contain the image's pixel data and externally shared metadata, and the non-external memory may contain implementation-private metadata. Note that, in some Vulkan implementations, the resource's non-external memory, unlike its external memory, is not shared globally among the APIs and/or processes that use the resource. -For example, each link:{docs}chapters/devsandqueues.html#VkDevice[VkDevice] +For example, each xref:{refpages}VkDevice.html[VkDevice] and `EGLContext` that accesses the resource may maintain its own private non-external memory for the resource. @@ -76,26 +76,26 @@ avoid the synchronization operation. For example, suppose the application renders to an image, then transfers ownership of the image to -link:{docs}chapters/synchronization.html#VK_QUEUE_FAMILY_FOREIGN_EXT[VK_QUEUE_FAMILY_FOREIGN_EXT], +xref:{refpages}VK_QUEUE_FAMILY_FOREIGN_EXT.html[VK_QUEUE_FAMILY_FOREIGN_EXT], then later re-acquires the image with -link:{docs}chapters/synchronization.html#VkImageMemoryBarrier[VkImageMemoryBarrier]. +xref:{refpages}VkImageMemoryBarrier.html[VkImageMemoryBarrier]. Suppose the application knows that the external queue family did not modify the image's external memory, but cannot inform the Vulkan implementation of its unmodified status due to lack of Vulkan API. The Vulkan implementation must perform the unnecessary data synchronization -during the execution of the link:{docs}chapters/synchronization.html#VkImageMemoryBarrier[VkImageMemoryBarrier]. +during the execution of the xref:{refpages}VkImageMemoryBarrier.html[VkImageMemoryBarrier]. The problem is especially relevant for systems that implement -link:{docs}chapters/VK_KHR_surface/wsi.html#VkSwapchainKHR[VkSwapchainKHR] +xref:{refpages}VkSwapchainKHR.html[VkSwapchainKHR] by layering it atop the external memory extensions such as -link:{extensions}VK_EXT_external_memory_dma_buf[VK_EXT_external_memory_dma_buf]. +xref:{refpages}VK_EXT_external_memory_dma_buf.html[VK_EXT_external_memory_dma_buf]. On such systems, the application may suffer the performance overhead each time it acquires an image from the swapchain, even though the window system did not modify the image's memory. Specifically, the overhead is likely to occur when the application transitions the image layout away from -link:{docs}chapters/resources.html#VkImageLayout[VK_IMAGE_LAYOUT_PRESENT_SRC_KHR] -after link:{docs}chapters/VK_KHR_surface/wsi.html#vkAcquireNextImageKHR[vkAcquireNextImageKHR]. +xref:{refpages}VkImageLayout.html[VK_IMAGE_LAYOUT_PRESENT_SRC_KHR] +after xref:{refpages}vkAcquireNextImageKHR.html[vkAcquireNextImageKHR]. == Solution Space @@ -106,16 +106,16 @@ after link:{docs}chapters/VK_KHR_surface/wsi.html#vkAcquireNextImageKHR[vkAcquir application's most recent release of ownership to the external queue family until the application's current ownership acquire operation. - The solution should not require the implementation to internally track the - link:{docs}chapters/resources.html#VkImageLayout[VkImageLayout] of external images. + xref:{refpages}VkImageLayout.html[VkImageLayout] of external images. Such tracking can be complex to implement and cause performance overhead. - The solution must work well for systems that implement - link:{docs}chapters/VK_KHR_surface/wsi.html#VkSwapchainKHR[VkSwapchainKHR] by layering it atop external + xref:{refpages}VkSwapchainKHR.html[VkSwapchainKHR] by layering it atop external memory extensions such as - link:{extensions}VK_EXT_external_memory_dma_buf[VK_EXT_external_memory_dma_buf]. + xref:{refpages}VK_EXT_external_memory_dma_buf.html[VK_EXT_external_memory_dma_buf]. - After acquiring a swapchain image but before using the image, applications must transition the image away from - link:{docs}chapters/resources.html#VkImageLayout[VK_IMAGE_LAYOUT_PRESENT_SRC_LAYOUT_KHR] - (which preserves the image's pixels) or link:{docs}chapters/resources.html#VkImageLayout[VK_IMAGE_LAYOUT_UNDEFINED] + xref:{refpages}VkImageLayout.html[VK_IMAGE_LAYOUT_PRESENT_SRC_LAYOUT_KHR] + (which preserves the image's pixels) or xref:{refpages}VkImageLayout.html[VK_IMAGE_LAYOUT_UNDEFINED] (which discards the image's pixels). The solution should work well and improve performance regardless of the source layout. @@ -125,16 +125,16 @@ after link:{docs}chapters/VK_KHR_surface/wsi.html#vkAcquireNextImageKHR[vkAcquir When the application transfers ownership of a resource to this queue family, it implicitly informs the implementation that the external queue will not modify the resource's external memory. -- **B**. Extend resource creation, such as link:{docs}chapters/resources.html#VkImageCreateInfo[VkImageCreateInfo], +- **B**. Extend resource creation, such as xref:{refpages}VkImageCreateInfo.html[VkImageCreateInfo], with a new parameter that informs the implementation that no external queue will modify the resource's external memory. - **C**. Extend the ownership-release memory barrier, such as - link:{docs}chapters/synchronization.html#VkImageMemoryBarrier[VkImageMemoryBarrier], with a new + xref:{refpages}VkImageMemoryBarrier.html[VkImageMemoryBarrier], with a new parameter that informs the implementation that the resource's external memory will remain unmodified for the duration of the external queue family's ownership. - **D**. Extend the ownership-acquire memory barrier, such as - link:{docs}chapters/synchronization.html#VkImageMemoryBarrier[VkImageMemoryBarrier], with a new + xref:{refpages}VkImageMemoryBarrier.html[VkImageMemoryBarrier], with a new parameter that informs the implementation that the resource's external memory has remained unmodified since the most recent ownership-release. @@ -154,13 +154,13 @@ an external image that involves the following producers/consumers. - A presentation engine (such as a window system) that only reads the image and never modifies it. The application does not use Vulkan WSI to interact with the presentation - engine, such as link:{docs}chapters/VK_KHR_surface/wsi.html#vkCreateWaylandSurfaceKHR[vkCreateWaylandSurfaceKHR], - link:{docs}chapters/VK_KHR_surface/wsi.html#VkSwapchainKHR[VkSwapchainKHR], and - link:{docs}chapters/VK_KHR_surface/wsi.html#vkQueuePresentKHR[vkQueuePresentKHR]. + engine, such as xref:{refpages}vkCreateWaylandSurfaceKHR.html[vkCreateWaylandSurfaceKHR], + xref:{refpages}VkSwapchainKHR.html[VkSwapchainKHR], and + xref:{refpages}vkQueuePresentKHR.html[vkQueuePresentKHR]. Instead, the application effectively implements these functions itself with a combination of - link:{extensions}VK_EXT_external_memory_dma_buf[VK_EXT_external_memory_dma_buf], - link:{extensions}VK_EXT_queue_family_foreign[VK_EXT_queue_family_foreign], + xref:{refpages}VK_EXT_external_memory_dma_buf.html[VK_EXT_external_memory_dma_buf], + xref:{refpages}VK_EXT_queue_family_foreign.html[VK_EXT_queue_family_foreign], and native Wayland API from `libwayland-client`. The image is used in the following loop: @@ -193,7 +193,7 @@ Solution (`C`) is equivalent to (A) in this example scenario. Solution (D) works well for all steps in the sequence. In particular, between (f) and (g), the application can query the post-processing library, asking whether (f.rw) or (f.ro) occurred. If (f.ro), the application can add the -performance hint to link:{docs}chapters/synchronization.html#VkImageMemoryBarrier[VkImageMemoryBarrier] in step (g). +performance hint to xref:{refpages}VkImageMemoryBarrier.html[VkImageMemoryBarrier] in step (g). == Proposal @@ -229,8 +229,8 @@ struct to be chained into any memory barrier for any resource. If the memory barrier's `srcQueueFamilyIndex` does not specify an external queue family, then the Vulkan implementation ignores the struct. This flexibility simplifies the implementation of layers that implement -link:{docs}chapters/VK_KHR_surface/wsi.html#VkSwapchainKHR[VkSwapchainKHR] atop -link:{extensions}VK_KHR_external_memory[VK_KHR_external_memory] and native +xref:{refpages}VkSwapchainKHR.html[VkSwapchainKHR] atop +xref:{refpages}VK_KHR_external_memory.html[VK_KHR_external_memory] and native window system APIs. === Caution @@ -253,7 +253,7 @@ In this method, examples of "read-only" access are SPIR-V instructions such as link:https://www.khronos.org/registry/SPIR-V/specs/unified1/SPIRV.html#OpImageRead[OpImageRead], link:https://www.khronos.org/registry/SPIR-V/specs/unified1/SPIRV.html#OpImageFetch[OpImageFetch], and link:https://www.khronos.org/registry/SPIR-V/specs/unified1/SPIRV.html#OpImageSampleImplicitLod[OpImageSampleImplicitLod], -and transfer commands such as link:{docs}chapters/copies.html#vkCmdCopyImage[vkCmdCopyImage]. +and transfer commands such as xref:{refpages}vkCmdCopyImage.html[vkCmdCopyImage]. Surprisingly, these operations may not be implemented as read-only. The Vulkan implementation, before dispatching the "read-only" shader or transfer command, may modify the image's external memory diff --git a/proposals/VK_EXT_external_memory_metal.adoc b/proposals/VK_EXT_external_memory_metal.adoc index a144c6ee8..10635e4ed 100644 --- a/proposals/VK_EXT_external_memory_metal.adoc +++ b/proposals/VK_EXT_external_memory_metal.adoc @@ -5,7 +5,7 @@ = VK_EXT_external_memory_metal :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This extension allows memory sharing through imports from or export to Metal resource handles. @@ -16,28 +16,28 @@ An application may wish to reference device memory in multiple Vulkan device ins This extension enables an application to export non-Vulkan handles from Vulkan memory objects such that the underlying resources can be referenced outside the scope of the Vulkan device instance that created them. -While link:{extensions}VK_EXT_metal_objects.html[VK_EXT_metal_objects] provides a way to expose underlying Metal resources, +While xref:{refpages}VK_EXT_metal_objects.html[VK_EXT_metal_objects] provides a way to expose underlying Metal resources, when importing an image from an `id` handle, said images and their backing memory will be imported at -link:{docs}chapters/resources.html#VkImage[VkImage] creation. -According to point link:https://registry.khronos.org/vulkan/specs/1.3-extensions/html/vkspec.html#resources-association[12.8 Memory Resource Association] +xref:{refpages}VkImage.html[VkImage] creation. +According to point xref:{docs}chapters/resources.html#resources-association[12.8 Memory Resource Association] resources are created as _virtual allocations_ with no backing memory. This leads to having to treat imported images through -link:{extensions}VK_EXT_metal_objects.html[VK_EXT_metal_objects] differently. +xref:{refpages}VK_EXT_metal_objects.html[VK_EXT_metal_objects] differently. -This extension aims to import both resources through link:{docs}chapters/memory.html#VkDeviceMemory[VkDeviceMemory] +This extension aims to import both resources through xref:{refpages}VkDeviceMemory.html[VkDeviceMemory] so that later can be bound to a existing -link:{docs}chapters/resources.html#VkImage[VkImage] or -link:{docs}chapters/resources.html#VkBuffer[VkBuffer] respectively. +xref:{refpages}VkImage.html[VkImage] or +xref:{refpages}VkBuffer.html[VkBuffer] respectively. == Proposal This extension aims to standardize memory imports and exports of Vulkan resources using -link:{extensions}VK_KHR_external_memory.html[VK_KHR_external_memory] as baseline to conform to what other platforms have done with -extensions like link:{extensions}VK_KHR_external_memory_win32.html[VK_KHR_external_memory_win32] and -link:{extensions}VK_ANDROID_external_memory_android_hardware_buffer.html[VK_ANDROID_external_memory_android_hardware_buffer] to name a few. +xref:{refpages}VK_KHR_external_memory.html[VK_KHR_external_memory] as baseline to conform to what other platforms have done with +extensions like xref:{refpages}VK_KHR_external_memory_win32.html[VK_KHR_external_memory_win32] and +xref:{refpages}VK_ANDROID_external_memory_android_hardware_buffer.html[VK_ANDROID_external_memory_android_hardware_buffer] to name a few. -This means that external Metal resources will be imported through link:{extensions}VkDeviceMemory.html[VkDeviceMemory] to later be bound. +This means that external Metal resources will be imported through xref:{refpages}VkDeviceMemory.html[VkDeviceMemory] to later be bound. -3 new bit values will be added to link:{docs}chapters/capabilities.html#VkExternalMemoryHandleTypeFlagBits[VkExternalMemoryHandleTypeFlagBits]: +3 new bit values will be added to xref:{refpages}VkExternalMemoryHandleTypeFlagBits.html[VkExternalMemoryHandleTypeFlagBits]: - `VK_EXTERNAL_MEMORY_HANDLE_TYPE_MTLBUFFER_BIT_EXT` to accommodate for Metal buffers (MTLBuffer) - `VK_EXTERNAL_MEMORY_HANDLE_TYPE_MTLTEXTURE_BIT_EXT` to accommodate for Metal textures (MTLTexture) @@ -46,9 +46,9 @@ This means that external Metal resources will be imported through link:{extensio Due to MTLTexture's semantics in Metal API roughly align with that of an image with a dedicated allocation in Vulkan, implementations will be required to report `VK_EXTERNAL_MEMORY_FEATURE_DEDICATED_ONLY_BIT` for `VK_EXTERNAL_MEMORY_HANDLE_TYPE_MTLTEXTURE_BIT_EXT`. When importing a MTLTexture through the creation of a -link:{docs}chapters/memory.html#VkDeviceMemory[VkDeviceMemory], the -link:{docs}chapters/resources.html#VkImage[VkImage] -link:{docs}chapters/resources.html#VkImage[VkImage] it will be bound to must have the same +xref:{refpages}VkDeviceMemory.html[VkDeviceMemory], the +xref:{refpages}VkImage.html[VkImage] +xref:{refpages}VkImage.html[VkImage] it will be bound to must have the same creation parameters as the MTLTexture used at import. == Examples diff --git a/proposals/VK_EXT_fragment_density_map_offset.adoc b/proposals/VK_EXT_fragment_density_map_offset.adoc index 484328481..0488975e3 100644 --- a/proposals/VK_EXT_fragment_density_map_offset.adoc +++ b/proposals/VK_EXT_fragment_density_map_offset.adoc @@ -5,25 +5,25 @@ = VK_EXT_fragment_density_map_offset :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This extension extends -link:{extensions}VK_EXT_fragment_density_map[VK_EXT_fragment_density_map] to +xref:{refpages}VK_EXT_fragment_density_map.html[VK_EXT_fragment_density_map] to allow for finer control over the location of the local framebuffer regions in a render pass with a fragment density map attachment. NOTE: This extension is a promotion of -link:{extensions}VK_QCOM_fragment_density_map_offset[VK_QCOM_fragment_density_map_offset], +xref:{refpages}VK_QCOM_fragment_density_map_offset.html[VK_QCOM_fragment_density_map_offset], with the addition of support for -link:{extensions}VK_KHR_dynamic_rendering[dynamic rendering]. As that extension +xref:{refpages}VK_KHR_dynamic_rendering.html[dynamic rendering]. As that extension already shipped before proposal documents existed, this document has been written retroactively during promotion to EXT. == Problem Statement Some use cases for -link:{extensions}VK_EXT_fragment_density_map[VK_EXT_fragment_density_map], such +xref:{refpages}VK_EXT_fragment_density_map.html[VK_EXT_fragment_density_map], such as eye-tracking foveation, require the fragment density map to be updated often. This can cause a distracting flickering effect for the user as local framebuffer regions pop in and out of high-density portion of the fragment @@ -44,8 +44,8 @@ whenever possible in order to smoothly scroll the local framebuffer regions. == Proposal A new structure is added that can be chained to -link:{docs}chapters/renderpass.html#VkSubpassEndInfo[VkSubpassEndInfo] or -link:{docs}chapters/renderpass.html#VkRenderingEndInfoEXT[VkRenderingEndInfoEXT] +xref:{refpages}VkSubpassEndInfo.html[VkSubpassEndInfo] or +xref:{refpages}VkRenderingEndInfoEXT.html[VkRenderingEndInfoEXT] which adds per-layer offsets to the fragment density map. === Features @@ -91,7 +91,7 @@ density map attachment, must be created with the new ==== Dynamic Rendering with fragment density map offsets Dynamic rendering support has been added since the original -link:{extensions}VK_QCOM_fragment_density_map_offset[VK_QCOM_fragment_density_map_offset] +xref:{refpages}VK_QCOM_fragment_density_map_offset.html[VK_QCOM_fragment_density_map_offset] extension was released. This requires the addition of a new command to terminate a dynamic rendering pass: diff --git a/proposals/VK_EXT_frame_boundary.adoc b/proposals/VK_EXT_frame_boundary.adoc index ccad355b4..8986b0e3e 100644 --- a/proposals/VK_EXT_frame_boundary.adoc +++ b/proposals/VK_EXT_frame_boundary.adoc @@ -4,7 +4,7 @@ = VK_EXT_frame_boundary :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: `VK_EXT_frame_boundary` is a device extension that helps *tools* (such as diff --git a/proposals/VK_EXT_graphics_pipeline_library.adoc b/proposals/VK_EXT_graphics_pipeline_library.adoc index 8e6dc26a9..b0e35a803 100644 --- a/proposals/VK_EXT_graphics_pipeline_library.adoc +++ b/proposals/VK_EXT_graphics_pipeline_library.adoc @@ -5,7 +5,7 @@ = VK_EXT_graphics_pipeline_library :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This document outlines a proposal to allow partial compilation of portions @@ -97,10 +97,10 @@ to separately compile state chunks and later link them together. === Prior Art: VK_EXT_pipeline_library -For link:{extensions}VK_KHR_ray_tracing_pipeline[VK_KHR_ray_tracing_pipeline], pipelines +For xref:{refpages}VK_KHR_ray_tracing_pipeline.html[VK_KHR_ray_tracing_pipeline], pipelines contain a significant number of shaders - making monolithic compilation very slow. -link:{extensions}VK_KHR_pipeline_library[VK_KHR_pipeline_library] allowed +xref:{refpages}VK_KHR_pipeline_library.html[VK_KHR_pipeline_library] allowed applications to create partial pipelines (pipeline libraries) containing only a subset of the final shaders. These pipeline libraries can be linked together to form a final executable. @@ -192,14 +192,14 @@ Pipeline libraries are created for the parts specified, and any parameters required to create a library with those parts must be provided. For all pipeline libraries -link:{docs}chapters/pipelines.html#VkPipelineCache[VkPipelineCache], `basePipelineHandle`, +xref:{refpages}VkPipelineCache.html[VkPipelineCache], `basePipelineHandle`, `basePipelineIndex`, -link:{docs}chapters/pipelines.html#VkPipelineCreationFeedbackCreateInfo[VkPipelineCreationFeedbackCreateInfo], +xref:{refpages}VkPipelineCreationFeedbackCreateInfo.html[VkPipelineCreationFeedbackCreateInfo], and -link:{docs}chapters/pipelines.html#VkPipelineCompilerControlCreateInfoAMD[VkPipelineCompilerControlCreateInfoAMD] +xref:{refpages}VkPipelineCompilerControlCreateInfoAMD.html[VkPipelineCompilerControlCreateInfoAMD] parameters are independently consumed and do not need to match between libraries or for any final pipeline. -link:{docs}chapters/pipelines.html#VkPipelineCreateFlags[VkPipelineCreateFlags] are also +xref:{refpages}VkPipelineCreateFlags.html[VkPipelineCreateFlags] are also independent, though `VK_PIPELINE_CREATE_LIBRARY_BIT_KHR` is required for all pipeline libraries. Only dynamic states that affect state consumed by a library are used, @@ -208,7 +208,7 @@ Where multiple pipeline libraries are built with the same required piece of state, those states must match exactly when linked together. The subset of -link:{docs}chapters/pipelines.html#VkGraphicsPipelineCreateInfo[VkGraphicsPipelineCreateInfo] +xref:{refpages}VkGraphicsPipelineCreateInfo.html[VkGraphicsPipelineCreateInfo] used to compile each kind of pipeline library is listed in the following sections, along with any pitfalls, quirks, or interactions that need calling out. @@ -232,53 +232,53 @@ specification for a more up-to-date list. A vertex input interface library is defined by the following state: - * link:{docs}chapters/fxvertex.html#VkPipelineVertexInputStateCreateInfo[VkPipelineVertexInputStateCreateInfo] - * link:{docs}chapters/drawing.html#VkPipelineInputAssemblyStateCreateInfo[VkPipelineInputAssemblyStateCreateInfo] + * xref:{refpages}VkPipelineVertexInputStateCreateInfo.html[VkPipelineVertexInputStateCreateInfo] + * xref:{refpages}VkPipelineInputAssemblyStateCreateInfo.html[VkPipelineInputAssemblyStateCreateInfo] ==== Pre-Rasterization Shaders A pre-rasterization shader library is defined by the following state: - * A valid link:{docs}chapters/pipelines.html#VkPipelineShaderStageCreateInfo[VkPipelineShaderStageCreateInfo] + * A valid xref:{refpages}VkPipelineShaderStageCreateInfo.html[VkPipelineShaderStageCreateInfo] for each pre-rasterization shader stage used - * Within the link:{docs}chapters/descriptorsets.html#VkPipelineLayout[VkPipelineLayout], all + * Within the xref:{refpages}VkPipelineLayout.html[VkPipelineLayout], all descriptor sets with pre-rasterization shader bindings if `VK_PIPELINE_LAYOUT_CREATE_INDEPENDENT_SETS_BIT_EXT` was specified. ** If `VK_PIPELINE_LAYOUT_CREATE_INDEPENDENT_SETS_BIT_EXT` was not specified, the full pipeline layout must be specified. - * link:{docs}chapters/vertexpostproc.html#VkPipelineViewportStateCreateInfo[VkPipelineViewportStateCreateInfo] + * xref:{refpages}VkPipelineViewportStateCreateInfo.html[VkPipelineViewportStateCreateInfo] ** However, all the functionality in that structure is dynamic other than the flags, and this extension allows the structure to be omitted such that it is as-if it was zero-initialized. - * link:{docs}chapters/primsrast.html#VkPipelineRasterizationStateCreateInfo[VkPipelineRasterizationStateCreateInfo] - * link:{docs}chapters/tessellation.html#VkPipelineTessellationStateCreateInfo[VkPipelineTessellationStateCreateInfo] + * xref:{refpages}VkPipelineRasterizationStateCreateInfo.html[VkPipelineRasterizationStateCreateInfo] + * xref:{refpages}VkPipelineTessellationStateCreateInfo.html[VkPipelineTessellationStateCreateInfo] is required if tessellation stages are included. - * link:{docs}chapters/renderpass.html#VkRenderPass[VkRenderPass] and `subpass` parameter - * link:{docs}chapters/pipelines.html#VkPipelineRenderingCreateInfo[VkPipelineRenderingCreateInfo] for the `viewMask` parameter - formats are ignored. - * link:{docs}chapters/fragops.html#VkPipelineDiscardRectangleStateCreateInfoEXT[VkPipelineDiscardRectangleStateCreateInfoEXT] - * link:{docs}chapters/primsrast.html#VkPipelineFragmentShadingRateStateCreateInfoKHR[VkPipelineFragmentShadingRateStateCreateInfoKHR] + * xref:{refpages}VkRenderPass.html[VkRenderPass] and `subpass` parameter + * xref:{refpages}VkPipelineRenderingCreateInfo.html[VkPipelineRenderingCreateInfo] for the `viewMask` parameter - formats are ignored. + * xref:{refpages}VkPipelineDiscardRectangleStateCreateInfoEXT.html[VkPipelineDiscardRectangleStateCreateInfoEXT] + * xref:{refpages}VkPipelineFragmentShadingRateStateCreateInfoKHR.html[VkPipelineFragmentShadingRateStateCreateInfoKHR] ==== Fragment Shader A fragment shader library is defined by the following state: - * A valid link:{docs}chapters/pipelines.html#VkPipelineShaderStageCreateInfo[VkPipelineShaderStageCreateInfo] + * A valid xref:{refpages}VkPipelineShaderStageCreateInfo.html[VkPipelineShaderStageCreateInfo] for the fragment shader stage. - * Within the link:{docs}chapters/descriptorsets.html#VkPipelineLayout[VkPipelineLayout], all + * Within the xref:{refpages}VkPipelineLayout.html[VkPipelineLayout], all descriptor sets with fragment shader bindings if `VK_PIPELINE_LAYOUT_CREATE_INDEPENDENT_SETS_BIT_EXT` was specified. ** If `VK_PIPELINE_LAYOUT_CREATE_INDEPENDENT_SETS_BIT_EXT` was not specified, the full pipeline layout must be specified. - * link:{docs}chapters/primsrast.html#VkPipelineMultisampleStateCreateInfo[VkPipelineMultisampleStateCreateInfo] + * xref:{refpages}VkPipelineMultisampleStateCreateInfo.html[VkPipelineMultisampleStateCreateInfo] if sample shading is enabled or `renderpass` is not `VK_NULL_HANDLE`. - * link:{docs}chapters/fragops.html#VkPipelineDepthStencilStateCreateInfo[VkPipelineDepthStencilStateCreateInfo] - * link:{docs}chapters/renderpass.html#VkRenderPass[VkRenderPass] and `subpass` parameter - * link:{docs}chapters/pipelines.html#VkPipelineRenderingCreateInfo[VkPipelineRenderingCreateInfo] for the `viewMask` parameter - formats are ignored. - * link:{docs}chapters/primsrast.html#VkPipelineFragmentShadingRateStateCreateInfoKHR[VkPipelineFragmentShadingRateStateCreateInfoKHR] - * link:{docs}chapters/primsrast.html#VkPipelineFragmentShadingRateEnumStateCreateInfoNV[VkPipelineFragmentShadingRateEnumStateCreateInfoNV] - * link:{docs}chapters/fragops.html#VkPipelineRepresentativeFragmentTestStateCreateInfoNV[VkPipelineRepresentativeFragmentTestStateCreateInfoNV] + * xref:{refpages}VkPipelineDepthStencilStateCreateInfo.html[VkPipelineDepthStencilStateCreateInfo] + * xref:{refpages}VkRenderPass.html[VkRenderPass] and `subpass` parameter + * xref:{refpages}VkPipelineRenderingCreateInfo.html[VkPipelineRenderingCreateInfo] for the `viewMask` parameter - formats are ignored. + * xref:{refpages}VkPipelineFragmentShadingRateStateCreateInfoKHR.html[VkPipelineFragmentShadingRateStateCreateInfoKHR] + * xref:{refpages}VkPipelineFragmentShadingRateEnumStateCreateInfoNV.html[VkPipelineFragmentShadingRateEnumStateCreateInfoNV] + * xref:{refpages}VkPipelineRepresentativeFragmentTestStateCreateInfoNV.html[VkPipelineRepresentativeFragmentTestStateCreateInfoNV] * Inclusion/omission of the `VK_PIPELINE_RASTERIZATION_STATE_CREATE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR` flag @@ -291,11 +291,11 @@ A fragment shader library is defined by the following state: A fragment output interface library is defined by the following state: - * link:{docs}chapters/framebuffer.html#VkPipelineColorBlendStateCreateInfo[VkPipelineColorBlendStateCreateInfo] - * link:{docs}chapters/primsrast.html#VkPipelineMultisampleStateCreateInfo[VkPipelineMultisampleStateCreateInfo] - * link:{docs}chapters/renderpass.html#VkRenderPass[VkRenderPass] and `subpass` parameter - * link:{docs}chapters/pipelines.html#VkPipelineRenderingCreateInfo[VkPipelineRenderingCreateInfo] - * link:{docs}chapters/cmdbuffers.html#VkAttachmentSampleCountInfoAMD[VkAttachmentSampleCountInfoAMD/NV] + * xref:{refpages}VkPipelineColorBlendStateCreateInfo.html[VkPipelineColorBlendStateCreateInfo] + * xref:{refpages}VkPipelineMultisampleStateCreateInfo.html[VkPipelineMultisampleStateCreateInfo] + * xref:{refpages}VkRenderPass.html[VkRenderPass] and `subpass` parameter + * xref:{refpages}VkPipelineRenderingCreateInfo.html[VkPipelineRenderingCreateInfo] + * xref:{refpages}VkAttachmentSampleCountInfoAMD.html[VkAttachmentSampleCountInfoAMD/NV] ==== Interactions with extensions @@ -306,11 +306,11 @@ implicitly accounted for unless otherwise stated. includes anything in the `pNext` chains of those structures, so any extensions that extend these structures will be automatically accounted for. If any extension allows parts of -link:{docs}chapters/pipelines.html#VkGraphicsPipelineCreateInfo[VkGraphicsPipelineCreateInfo] +xref:{refpages}VkGraphicsPipelineCreateInfo.html[VkGraphicsPipelineCreateInfo] to be ignored, by default that part of the state will also be ignored when using graphics pipeline libraries. Any extension that extends the base -link:{docs}chapters/pipelines.html#VkGraphicsPipelineCreateInfo[VkGraphicsPipelineCreateInfo] +xref:{refpages}VkGraphicsPipelineCreateInfo.html[VkGraphicsPipelineCreateInfo] directly, or otherwise differs from the above implicit interactions, will need an explicit interaction. @@ -332,8 +332,8 @@ Descriptor set layouts unused by a library may be set to `VK_NULL_HANDLE`. === Linking Linking is performed by including the existing -link:{docs}chapters/pipelines.html#VkPipelineLibraryCreateInfoKHR[VkPipelineLibraryCreateInfoKHR] structure in the pNext chain of -link:{docs}chapters/pipelines.html#VkGraphicsPipelineCreateInfo[VkGraphicsPipelineCreateInfo]. +xref:{refpages}VkPipelineLibraryCreateInfoKHR.html[VkPipelineLibraryCreateInfoKHR] structure in the pNext chain of +xref:{refpages}VkGraphicsPipelineCreateInfo.html[VkGraphicsPipelineCreateInfo]. [source,c] ---- @@ -353,7 +353,7 @@ library. A newly created graphics pipeline consists of the parts defined by linked libraries, plus those defined by -link:{docs}chapters/pipelines.html#VkGraphicsPipelineLibraryCreateInfoEXT[VkGraphicsPipelineLibraryCreateInfoEXT]. +xref:{refpages}VkGraphicsPipelineLibraryCreateInfoEXT.html[VkGraphicsPipelineLibraryCreateInfoEXT]. Parts specified in the pipeline must not overlap those defined by libraries, and similarly multiple libraries must not provide the same parts. @@ -402,9 +402,9 @@ more optimal pipeline layout to be used when generating the final pipeline. === Deprecating shader modules To make single-shader compilation consistent, shader modules will be -deprecated by allowing link:{docs}chapters/shaders.html#VkShaderModuleCreateInfo[VkShaderModuleCreateInfo] to be chained to -link:{docs}chapters/pipelines.html#VkPipelineShaderStageCreateInfo[VkPipelineShaderStageCreateInfo], and allowing the -link:{docs}chapters/shaders.html#VkShaderModule[VkShaderModule] to be link:{docs}appendices/boilerplate.html#VK_NULL_HANDLE[VK_NULL_HANDLE] in this case. +deprecated by allowing xref:{refpages}VkShaderModuleCreateInfo.html[VkShaderModuleCreateInfo] to be chained to +xref:{refpages}VkPipelineShaderStageCreateInfo.html[VkPipelineShaderStageCreateInfo], and allowing the +xref:{refpages}VkShaderModule.html[VkShaderModule] to be xref:{refpages}VK_NULL_HANDLE.html[VK_NULL_HANDLE] in this case. Applications can continue to use shader modules as they are not being removed; but it’s strongly recommended to not use them. The primary reason for this would be to allow bypassing what is in many @@ -482,7 +482,7 @@ VkPipeline createVertexShader( [NOTE] ==== This example makes use of -link:{extensions}VK_KHR_dynamic_rendering[VK_KHR_dynamic_rendering] to +xref:{refpages}VK_KHR_dynamic_rendering.html[VK_KHR_dynamic_rendering] to avoid render pass interactions. If that extension is not available, a render pass object and the corresponding subpass will also need to be provided. @@ -564,11 +564,11 @@ If an application has its own material cache, the library should be cached there. Applications should still use pipeline caches to amortize compilation across similar stage blobs but should avoid mixing different stage types in -the same link:{docs}chapters/pipelines.html#VkPipelineCache[VkPipelineCache], to avoid unnecessary lookup overhead. +the same xref:{refpages}VkPipelineCache.html[VkPipelineCache], to avoid unnecessary lookup overhead. Basic linking should then be done as early as the application is able. Applications should ideally store/cache this pipeline with relevant objects. -Using a link:{docs}chapters/pipelines.html#VkPipelineCache[VkPipelineCache] for this suboptimal pipeline is recommended; +Using a xref:{refpages}VkPipelineCache.html[VkPipelineCache] for this suboptimal pipeline is recommended; implementations where this would provide no benefit should ignore the cache lookup request for fast linking. diff --git a/proposals/VK_EXT_host_image_copy.adoc b/proposals/VK_EXT_host_image_copy.adoc index 6ba2c4beb..1d239d89a 100644 --- a/proposals/VK_EXT_host_image_copy.adoc +++ b/proposals/VK_EXT_host_image_copy.adoc @@ -5,7 +5,7 @@ = VK_EXT_host_image_copy :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This document identifies inefficiencies with image data initialization and proposes an extension to improve it. @@ -190,7 +190,7 @@ The allowed values for `newLayout` are: --- When `VK_HOST_IMAGE_COPY_MEMCPY_BIT_EXT` is used in copies to or from an image with `VK_IMAGE_TILING_OPTIMAL`, the application may need to query the memory size needed for copy. -The link:{docs}chapters/resources.html#vkGetImageSubresourceLayout2EXT[vkGetImageSubresourceLayout2EXT] function can be used for this purpose: +The xref:{refpages}vkGetImageSubresourceLayout2EXT.html[vkGetImageSubresourceLayout2EXT] function can be used for this purpose: [source,c] ---- diff --git a/proposals/VK_EXT_image_2d_view_of_3d.adoc b/proposals/VK_EXT_image_2d_view_of_3d.adoc index 4f8f17964..1321e8155 100644 --- a/proposals/VK_EXT_image_2d_view_of_3d.adoc +++ b/proposals/VK_EXT_image_2d_view_of_3d.adoc @@ -5,7 +5,7 @@ = VK_EXT_image_2d_view_of_3d :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This document proposes adding support for creating 2D views of 3D images. diff --git a/proposals/VK_EXT_image_compression_control.adoc b/proposals/VK_EXT_image_compression_control.adoc index 9ba453f4f..86a1cc40e 100644 --- a/proposals/VK_EXT_image_compression_control.adoc +++ b/proposals/VK_EXT_image_compression_control.adoc @@ -5,7 +5,7 @@ = VK_EXT_image_compression_control :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This document proposes adding support for fixed-rate, or 'lossy', image compression. diff --git a/proposals/VK_EXT_image_sliced_view_of_3d.adoc b/proposals/VK_EXT_image_sliced_view_of_3d.adoc index 49753ca92..019e8e93c 100644 --- a/proposals/VK_EXT_image_sliced_view_of_3d.adoc +++ b/proposals/VK_EXT_image_sliced_view_of_3d.adoc @@ -5,7 +5,7 @@ = VK_EXT_image_sliced_view_of_3d :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This document describes a proposal for adding support for taking a sliced view of a 3D image, diff --git a/proposals/VK_EXT_layer_settings.adoc b/proposals/VK_EXT_layer_settings.adoc index 87425fcaf..40a970eb6 100644 --- a/proposals/VK_EXT_layer_settings.adoc +++ b/proposals/VK_EXT_layer_settings.adoc @@ -6,7 +6,7 @@ :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: Adds an extension that allows applications to provide layer settings to any layers implementing the @@ -39,7 +39,7 @@ and the shader object layer. The intent of the extension is to be implemented in any layer that has settings to provide a consistent method across layers. -`VK_EXT_layer_settings` extends the `pNext` chain of link:{docs}chapters/initialization.html#VkInstanceCreateInfo[VkInstanceCreateInfo] to +`VK_EXT_layer_settings` extends the `pNext` chain of xref:{refpages}VkInstanceCreateInfo.html[VkInstanceCreateInfo] to provide a list of structures which contain the information needed by the layers to configure their settings. Each setting is built around a basic type (bool32, int32, int64, uint32, uint64, float32, float64 and strings) which diff --git a/proposals/VK_EXT_legacy_dithering.adoc b/proposals/VK_EXT_legacy_dithering.adoc index 579cd962d..92b1a8887 100644 --- a/proposals/VK_EXT_legacy_dithering.adoc +++ b/proposals/VK_EXT_legacy_dithering.adoc @@ -5,7 +5,7 @@ = VK_EXT_legacy_dithering :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This proposal regards layering OpenGL over Vulkan, and provides an efficient diff --git a/proposals/VK_EXT_legacy_vertex_attributes.adoc b/proposals/VK_EXT_legacy_vertex_attributes.adoc index 0064c05ff..bb7348d62 100644 --- a/proposals/VK_EXT_legacy_vertex_attributes.adoc +++ b/proposals/VK_EXT_legacy_vertex_attributes.adoc @@ -5,7 +5,7 @@ = VK_EXT_legacy_vertex_attributes :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This document proposes adding legacy features for vertex attributes as found in OpenGL. diff --git a/proposals/VK_EXT_map_memory_placed.adoc b/proposals/VK_EXT_map_memory_placed.adoc index 20c5a395b..cb4c3444b 100644 --- a/proposals/VK_EXT_map_memory_placed.adoc +++ b/proposals/VK_EXT_map_memory_placed.adoc @@ -4,7 +4,7 @@ = VK_EXT_map_memory_placed :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This document proposes adding support for application-controlled virtual address diff --git a/proposals/VK_EXT_memory_decompression.adoc b/proposals/VK_EXT_memory_decompression.adoc index c0fcbff53..5f27d5e3e 100644 --- a/proposals/VK_EXT_memory_decompression.adoc +++ b/proposals/VK_EXT_memory_decompression.adoc @@ -5,7 +5,7 @@ = VK_EXT_memory_decompression :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This document details the VK_EXT_memory_decompression extension which adds support diff --git a/proposals/VK_EXT_mesh_shader.adoc b/proposals/VK_EXT_mesh_shader.adoc index 9e663fa2e..bd48e4f3f 100644 --- a/proposals/VK_EXT_mesh_shader.adoc +++ b/proposals/VK_EXT_mesh_shader.adoc @@ -5,8 +5,7 @@ = VK_EXT_mesh_shader :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# -:spec: https://www.khronos.org/registry/vulkan/specs/latest/html/vkspec.html +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This extension provides a new mechanism allowing applications to generate collections of geometric primitives via programmable mesh shading. @@ -105,7 +104,7 @@ Mesh workgroups launched from a later task workgroup rasterize their output afte Graphics pipelines can now be created using mesh and task shaders in place of vertex, tessellation, and geometry shaders. This can be achieved by omitting existing pre-rasterization shaders and including a mesh shader stage, and optionally a task shader stage. -When present, a graphics pipeline is complete without the inclusion of the link:{spec}#pipeline-graphics-subsets-vertex-input[vertex input state subset], as this state does not participate in mesh pipelines. +When present, a graphics pipeline is complete without the inclusion of the xref:{docs}chapters/pipelines.html#pipelines-graphics-subsets-vertex-input[vertex input state subset], as this state does not participate in mesh pipelines. No other modifications to graphics pipelines are necessary. Two new shader stages are added to the API to describe the new shader stages: @@ -134,7 +133,7 @@ static const VkPipelineStageFlagBits2KHR VK_PIPELINE_STAGE_MESH_SHADER_BIT_2_EXT These new pipeline stages interact similarly to compute shaders, with all the same access types and operations. They are also logically ordered before fragment shading, but have no logical ordering compared to existing pre-rasterization shader stages. -The `VK_PIPELINE_STAGE_2_PRE_RASTERIZATION_SHADERS_BIT` stage added by link:{extensions}VK_KHR_synchronization2[VK_KHR_synchronization2] includes these new shader stages, and can be used identically. +The `VK_PIPELINE_STAGE_2_PRE_RASTERIZATION_SHADERS_BIT` stage added by xref:{refpages}VK_KHR_synchronization2.html[VK_KHR_synchronization2] includes these new shader stages, and can be used identically. ==== Queries @@ -192,9 +191,9 @@ typedef struct VkDrawMeshTasksIndirectCommandEXT { } VkDrawMeshTasksIndirectCommandEXT; ---- -`vkCmdDrawMeshTasksEXT` is the simplest as it functions the same as link:{docs}chapters/dispatch.html#vkCmdDispatch[vkCmdDispatch], but dispatches the mesh or task shader in a graphics pipeline with the specified workgroup counts, rather than a compute shader. +`vkCmdDrawMeshTasksEXT` is the simplest as it functions the same as xref:{refpages}vkCmdDispatch.html[vkCmdDispatch], but dispatches the mesh or task shader in a graphics pipeline with the specified workgroup counts, rather than a compute shader. -`vkCmdDrawMeshTasksIndirectEXT` functions similarly to link:{docs}chapters/dispatch.html#vkCmdDispatchIndirect[vkCmdDispatchIndirect], but with the draw count functionality from other draw commands. +`vkCmdDrawMeshTasksIndirectEXT` functions similarly to xref:{refpages}vkCmdDispatchIndirect.html[vkCmdDispatchIndirect], but with the draw count functionality from other draw commands. Multiple draws are dispatched according to the `drawCount` parameter, with data in buffer being consumed as a strided array of `VkDrawMeshTasksIndirectCommandEXT` structures, with stride equal to `stride`. Each element of this array defines a separate draw call's workgroup counts in each dimension, and dispatches mesh or task shaders for the current pipeline accordingly. @@ -540,7 +539,7 @@ The HLSL specification for mesh shaders is defined by Microsoft® here: https:// Everything in that specification should work directly as described, with the exception of linking per-primitive interface variables between pixel and mesh shaders. Microsoft defined the fragment/mesh interface to effectively be fixed up at link time - making no distinction between per-vertex and per-primitive variables in the pixel shader. -This works okay with monolithic pipeline construction, but with the addition of things like link:{extensions}VK_EXT_graphics_pipeline_library[VK_EXT_graphics_pipeline_library], modifying this at link time would cause undesirable slowdown. +This works okay with monolithic pipeline construction, but with the addition of things like xref:{refpages}VK_EXT_graphics_pipeline_library.html[VK_EXT_graphics_pipeline_library], modifying this at link time would cause undesirable slowdown. As a result, the Vulkan version of this feature requires the `\[[vk::perprimitive]]` attribute on pixel shader inputs in order to generate a match with mesh shader outputs denoted with the `primitives` qualifier. Mapping to SPIR-V is largely performed identically to any other shader for both mesh and task shaders, with most new functionality mapping 1:1. @@ -571,7 +570,7 @@ These changes aim to make the extension more portable across multiple vendors, a From the shader side, declaring mesh or amplification shaders in HLSL will have no meaningful differences - HLSL code written for DirectX should also work fine in Vulkan, with all the expected limits and features available. One difference is present in pixel shaders though - any user-declared attributes with the "primitive" keyword in the mesh shader will need to be declared in the fragment shader with the `\[[vk::perprimitive]]` attribute to facilitate linking. -This makes it so that the shader can be compiled without modifying the input interface, which is particularly important for interactions with extensions like link:{extensions}VK_EXT_graphics_pipeline_library[VK_EXT_graphics_pipeline_library]. +This makes it so that the shader can be compiled without modifying the input interface, which is particularly important for interactions with extensions like xref:{refpages}VK_EXT_graphics_pipeline_library.html[VK_EXT_graphics_pipeline_library]. Some amount of massaging by the HLSL compiler will be required to the shader interfaces as DirectX does linking by name rather than location between mesh and pixel shaders, but the requirement to use `\[[vk::perprimitive]]` allows the different attributes to continue using locations in Vulkan. diff --git a/proposals/VK_EXT_metal_objects.adoc b/proposals/VK_EXT_metal_objects.adoc index dca2ca694..aae37e3d8 100644 --- a/proposals/VK_EXT_metal_objects.adoc +++ b/proposals/VK_EXT_metal_objects.adoc @@ -5,7 +5,7 @@ = VK_EXT_metal_objects :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This document details API design ideas for the `VK_EXT_metal_objects` extension, diff --git a/proposals/VK_EXT_multisampled_render_to_single_sampled.adoc b/proposals/VK_EXT_multisampled_render_to_single_sampled.adoc index c5bc17870..e0032edc1 100644 --- a/proposals/VK_EXT_multisampled_render_to_single_sampled.adoc +++ b/proposals/VK_EXT_multisampled_render_to_single_sampled.adoc @@ -5,7 +5,7 @@ = VK_EXT_multisampled_render_to_single_sampled :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This document identifies difficulties with efficient multisampled rendering on @@ -23,7 +23,7 @@ on tiling GPUs in most cases. On some tiling GPUs, subpass resolve operations for some formats cannot be done on the tile, and so additional performance and memory cost is silently paid similarly to performing the resolve through -link:{docs}chapters/copies.html#vkCmdResolveImage[`vkCmdResolveImage`] after the subpass, +xref:{refpages}vkCmdResolveImage.html[`vkCmdResolveImage`] after the subpass, with no feedback to the application. Additionally, under certain circumstances, the application may not be able to @@ -129,7 +129,7 @@ In a multisampled-render-to-single-sampled pass with `N` samples, all rendering is done with `N` samples as if any single-sampled attachments truly had `N` samples. This means that -link:{docs}chapters/primsrast.html#VkPipelineMultisampleStateCreateInfo[`VkPipelineMultisampleStateCreateInfo::rasterizationSamples`] +xref:{refpages}VkPipelineMultisampleStateCreateInfo.html[`VkPipelineMultisampleStateCreateInfo::rasterizationSamples`] would have to be `N`, and rasterization is done identically to Vulkan's multisampling rules for passes not using this extension. As such, the functionality in this extension purely affects the load and store diff --git a/proposals/VK_EXT_mutable_descriptor_type.adoc b/proposals/VK_EXT_mutable_descriptor_type.adoc index 762eb1fa1..f1c5518a3 100644 --- a/proposals/VK_EXT_mutable_descriptor_type.adoc +++ b/proposals/VK_EXT_mutable_descriptor_type.adoc @@ -5,12 +5,12 @@ = VK_EXT_mutable_descriptor_type :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This extension enables applications to alias multiple descriptor types onto the same binding, reducing friction when porting between Vulkan and DirectX 12. -NOTE: This extension is a direct promotion of link:{extensions}VK_VALVE_mutable_descriptor_type[VK_VALVE_mutable_descriptor_type]. As that extension already shipped before proposal documents existed, this document has been written retroactively during promotion to EXT. +NOTE: This extension is a direct promotion of xref:{refpages}VK_VALVE_mutable_descriptor_type.html[VK_VALVE_mutable_descriptor_type]. As that extension already shipped before proposal documents existed, this document has been written retroactively during promotion to EXT. == Problem Statement @@ -62,7 +62,7 @@ This could be considered for future extensions, but for the problems identified === Mutable Descriptor Type -Typically when specifying a link:{docs}chapters/descriptorsets.html#VkDescriptorSetLayoutBinding[descriptor set layout binding], applications have to choose one of the available link:{docs}chapters/descriptorsets.html#VkDescriptorType[descriptor types] that will occupy that binding. +Typically when specifying a xref:{refpages}VkDescriptorSetLayoutBinding.html[descriptor set layout binding], applications have to choose one of the available xref:{refpages}VkDescriptorType.html[descriptor types] that will occupy that binding. This extension adds a new descriptor type: [source,c] @@ -87,7 +87,7 @@ typedef struct VkMutableDescriptorTypeListEXT { } VkMutableDescriptorTypeListEXT; ---- -`VkMutableDescriptorTypeCreateInfoEXT` can be added to the `pNext` chain of link:{docs}chapters/descriptorsets.html#VkDescriptorSetLayoutCreateInfo[VkDescriptorSetLayoutCreateInfo], where each entry in `pMutableDescriptorTypeLists` corresponds to a binding at the same index in `pBindings`. +`VkMutableDescriptorTypeCreateInfoEXT` can be added to the `pNext` chain of xref:{refpages}VkDescriptorSetLayoutCreateInfo.html[VkDescriptorSetLayoutCreateInfo], where each entry in `pMutableDescriptorTypeLists` corresponds to a binding at the same index in `pBindings`. The list of descriptor types in `VkMutableDescriptorTypeListEXT` then defines the set of types which can be used in that binding. When writing a descriptor to such a binding in a descriptor set, the actual type of the descriptor must be specified, and it must be one of the types specified in this list when the set layout was created. @@ -114,7 +114,7 @@ Support can be restricted if the descriptor type in question cannot be used with An example here would be `VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER` which may not be supported with update-after-bind on some implementations. In this situations, applications need to use `VK_DESCRIPTOR_TYPE_STORAGE_BUFFER` and modify the shaders accordingly, but ideally, plain uniform buffers should be used instead if possible. -It is possible to go beyond the minimum supported set. For this purpose, the desired descriptor set layout can be queried with link:{docs}chapters/descriptorsets.html#vkGetDescriptorSetLayoutSupport[vkGetDescriptorSetLayoutSupport]. +It is possible to go beyond the minimum supported set. For this purpose, the desired descriptor set layout can be queried with xref:{refpages}vkGetDescriptorSetLayoutSupport.html[vkGetDescriptorSetLayoutSupport]. The interactions between descriptor types and flags can be complicated enough that it is non-trivial to report a list of supported descriptor types at the physical device level. @@ -135,9 +135,9 @@ It might also disable certain fast-paths in implementations since the descriptor In order to enable better host write performance for descriptors, a new flag is added to descriptor pools and descriptor set layouts to specify that accesses to descriptor sets created with them will be done in host-local memory, and does not need to be directly visible to the device. Without these flags, implementations may favor device-local memory with better device access performance characteristics, at the expense of host access performance. These flags allow device access performance to be disregarded, enabling memory with better host access performance to be used. -Host-only descriptor sets cannot be bound to a command buffer, and their contents must be copied to a non-host-only set using link:{docs}chapters/descriptorsets.html#vkUpdateDescriptorSets[vkUpdateDescriptorSets] before those descriptors can be used. +Host-only descriptor sets cannot be bound to a command buffer, and their contents must be copied to a non-host-only set using xref:{refpages}vkUpdateDescriptorSets.html[vkUpdateDescriptorSets] before those descriptors can be used. -Descriptor pools are specified as host-only using a new link:{docs}chapters/descriptorsets.html#VkDescriptorSetLayoutCreateFlagBits[create flag]: +Descriptor pools are specified as host-only using a new xref:{refpages}VkDescriptorSetLayoutCreateFlagBits.html[create flag]: [source,c] ---- @@ -146,7 +146,7 @@ VK_DESCRIPTOR_POOL_CREATE_HOST_ONLY_BIT_EXT = 0x00000004 Any descriptor set created from a pool with this flag set is a host-only descriptor set. -The memory layout of a descriptor set may also be optimized for device access rather than host access, so a new link:{docs}chapters/descriptorsets.html#VkDescriptorSetLayoutCreateFlagBits[create flag] is provided to specify when a layout will be used with a host-only pool: +The memory layout of a descriptor set may also be optimized for device access rather than host access, so a new xref:{refpages}VkDescriptorSetLayoutCreateFlagBits.html[create flag] is provided to specify when a layout will be used with a host-only pool: [source,c] ---- @@ -154,7 +154,7 @@ VK_DESCRIPTOR_SET_LAYOUT_CREATE_HOST_ONLY_POOL_BIT_EXT = 0x00000004 ---- Descriptor set layouts created with this flag must only be used to create descriptor sets from host-only pools, and descriptor sets created from host-only pools must be created with layouts that specify this flag. -In addition, as such layouts are not valid for device access, link:{docs}chapters/descriptorsets.html#VkPipelineLayout[VkPipelineLayout] objects cannot be created with such descriptor set layouts. +In addition, as such layouts are not valid for device access, xref:{refpages}VkPipelineLayout.html[VkPipelineLayout] objects cannot be created with such descriptor set layouts. Host-only descriptor sets do not consume device-global descriptor resources (e.g. `maxUpdateAfterBindDescriptorsInAllPools`), and they support concurrent descriptor set updates similar to update-after-bind. diff --git a/proposals/VK_EXT_non_seamless_cube_map.adoc b/proposals/VK_EXT_non_seamless_cube_map.adoc index 8f6cebf6b..99c50e965 100644 --- a/proposals/VK_EXT_non_seamless_cube_map.adoc +++ b/proposals/VK_EXT_non_seamless_cube_map.adoc @@ -5,7 +5,7 @@ = VK_EXT_non_seamless_cube_map :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: == Problem Statement diff --git a/proposals/VK_EXT_opacity_micromap.adoc b/proposals/VK_EXT_opacity_micromap.adoc index c35206886..f2601b52f 100644 --- a/proposals/VK_EXT_opacity_micromap.adoc +++ b/proposals/VK_EXT_opacity_micromap.adoc @@ -5,7 +5,7 @@ = VK_EXT_opacity_micromap :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: VK_EXT_opacity_micromap adds a micromap object to associate micro-geometry information with geometry in an acceleration @@ -42,7 +42,7 @@ with a given subdivision level and format. For an opacity micromap, the micromap which controls how the traversal is performed when combined with a set of flags. Once the micromap is built an extension structure can attach it to -link:{docs}chapters/accelstructures.html#VkAccelerationStructureGeometryKHR[VkAccelerationStructureGeometryKHR] along with +xref:{refpages}VkAccelerationStructureGeometryKHR.html[VkAccelerationStructureGeometryKHR] along with mapping information from each triangle in the geometry to a specified triangle index in the micromap. == Examples diff --git a/proposals/VK_EXT_pipeline_library_group_handles.adoc b/proposals/VK_EXT_pipeline_library_group_handles.adoc index fd858f443..3d4c40085 100644 --- a/proposals/VK_EXT_pipeline_library_group_handles.adoc +++ b/proposals/VK_EXT_pipeline_library_group_handles.adoc @@ -5,7 +5,7 @@ = VK_EXT_pipeline_library_group_handles :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This extension adds support for querying ray tracing group handles on library creation time rather than waiting for pipeline linking. diff --git a/proposals/VK_EXT_pipeline_protected_access.adoc b/proposals/VK_EXT_pipeline_protected_access.adoc index fe392fe1e..d2e6c3f0b 100644 --- a/proposals/VK_EXT_pipeline_protected_access.adoc +++ b/proposals/VK_EXT_pipeline_protected_access.adoc @@ -5,7 +5,7 @@ = VK_EXT_pipeline_protected_access :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This proposal regards pipeline access to protected memory, and provides the diff --git a/proposals/VK_EXT_present_mode_fifo_latest_ready.adoc b/proposals/VK_EXT_present_mode_fifo_latest_ready.adoc index 527c4a2c3..85620fe6e 100644 --- a/proposals/VK_EXT_present_mode_fifo_latest_ready.adoc +++ b/proposals/VK_EXT_present_mode_fifo_latest_ready.adoc @@ -5,7 +5,7 @@ = VK_EXT_present_mode_fifo_latest_ready :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: == Problem Statement diff --git a/proposals/VK_EXT_present_timing.adoc b/proposals/VK_EXT_present_timing.adoc index aa4a2103c..feac0cd77 100644 --- a/proposals/VK_EXT_present_timing.adoc +++ b/proposals/VK_EXT_present_timing.adoc @@ -5,7 +5,7 @@ = VK_EXT_present_timing :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: ifndef::images[:images: ../images] diff --git a/proposals/VK_EXT_primitive_restart_index.adoc b/proposals/VK_EXT_primitive_restart_index.adoc index 4f6ffb55d..25cebd95c 100644 --- a/proposals/VK_EXT_primitive_restart_index.adoc +++ b/proposals/VK_EXT_primitive_restart_index.adoc @@ -5,7 +5,7 @@ = VK_EXT_primitive_restart_index :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This document proposes adding support for setting the index for primitive restart. diff --git a/proposals/VK_EXT_primitives_generated_query.adoc b/proposals/VK_EXT_primitives_generated_query.adoc index 1348ecabb..5c3a1cc65 100644 --- a/proposals/VK_EXT_primitives_generated_query.adoc +++ b/proposals/VK_EXT_primitives_generated_query.adoc @@ -5,7 +5,7 @@ = VK_EXT_primitives_generated_query :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This proposal regards layering OpenGL over Vulkan, and provides a convenience diff --git a/proposals/VK_EXT_rasterization_order_attachment_access.adoc b/proposals/VK_EXT_rasterization_order_attachment_access.adoc index b906414c5..ca29074c5 100644 --- a/proposals/VK_EXT_rasterization_order_attachment_access.adoc +++ b/proposals/VK_EXT_rasterization_order_attachment_access.adoc @@ -5,7 +5,7 @@ = VK_EXT_rasterization_order_attachment_access :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This proposal extends the mechanism of input attachments to allow access to framebuffer attachments that are used both as input and as @@ -21,7 +21,7 @@ For these use cases, a mechanisms that more closely matches framebuffer fetch is == Solution Space -For simplicity, this proposal extends the original render pass API and not the link:{extensions}VK_KHR_dynamic_rendering[VK_KHR_dynamic_rendering] API. +For simplicity, this proposal extends the original render pass API and not the xref:{refpages}VK_KHR_dynamic_rendering.html[VK_KHR_dynamic_rendering] API. Raster order attachment reads are done as input attachment reads (as before), but self-dependencies are no longer required when reading a value written by fragments earlier in rasterization order. @@ -78,7 +78,7 @@ typedef enum VkSubpassDescriptionFlagBits { == Issues -=== Is there any interaction with the link:{extensions}VK_KHR_dynamic_rendering[VK_KHR_dynamic_rendering] extension? +=== Is there any interaction with the xref:{refpages}VK_KHR_dynamic_rendering.html[VK_KHR_dynamic_rendering] extension? Render pass instances begun with `vkCmdBeginRenderingKHR` do not have input attachments and thus a different mechanism was needed to provide similar functionality in this case. This was provided by `VK_KHR_dynamic_rendering_local_read`, which enables reads from attachments and resources written by previous fragment shaders within a dynamic render pass. @@ -95,7 +95,7 @@ Instead, the behavior is controlled only by the corresponding pipeline flag bits * VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_DEPTH_ACCESS_BIT_EXT * VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_STENCIL_ACCESS_BIT_EXT -=== What are the differences to the link:{extensions}VK_ARM_rasterization_order_attachment_access[VK_ARM_rasterization_order_attachment_access] extension? +=== What are the differences to the xref:{refpages}VK_ARM_rasterization_order_attachment_access.html[VK_ARM_rasterization_order_attachment_access] extension? None. This extension is a multi-vendor version of that extension with no changes. The two extensions can be used interchangeably since the API structures and enumeration alias each other. diff --git a/proposals/VK_EXT_ray_tracing_invocation_reorder.adoc b/proposals/VK_EXT_ray_tracing_invocation_reorder.adoc index 624f6fbc4..cdb24fa45 100644 --- a/proposals/VK_EXT_ray_tracing_invocation_reorder.adoc +++ b/proposals/VK_EXT_ray_tracing_invocation_reorder.adoc @@ -4,7 +4,7 @@ = VK_EXT_ray_tracing_invocation_reorder :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :spirvextensions: https://github.khronos.org/SPIRV-Registry/extensions/ :sectnums: diff --git a/proposals/VK_EXT_shader_64bit_indexing.adoc b/proposals/VK_EXT_shader_64bit_indexing.adoc index ae9f793b9..31763a76e 100644 --- a/proposals/VK_EXT_shader_64bit_indexing.adoc +++ b/proposals/VK_EXT_shader_64bit_indexing.adoc @@ -5,7 +5,7 @@ = VK_EXT_shader_64bit_indexing :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: // Required so images render in github ifndef::images[:images: ../images] diff --git a/proposals/VK_EXT_shader_float8.adoc b/proposals/VK_EXT_shader_float8.adoc index c333b572a..e8a164d7b 100644 --- a/proposals/VK_EXT_shader_float8.adoc +++ b/proposals/VK_EXT_shader_float8.adoc @@ -5,7 +5,7 @@ = VK_EXT_shader_float8 :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This extension enables support for 8-bit floating point operations in shaders. @@ -83,9 +83,9 @@ typedef struct VkPhysicalDeviceShaderFloat8FeaturesEXT { `shaderFloat8` must be supported for this extension. -==== Interactions with link:{extensions}VK_KHR_cooperative_matrix[VK_KHR_cooperative_matrix] +==== Interactions with xref:{refpages}VK_KHR_cooperative_matrix.html[VK_KHR_cooperative_matrix] -Two new link:{docs}chapters/shaders.html#VkComponentTypeKHR[VkComponentTypeKHR] are added that can be reported as supported by link:{docs}chapters/shaders.html#vkGetPhysicalDeviceCooperativeMatrixPropertiesKHR[vkGetPhysicalDeviceCooperativeMatrixPropertiesKHR]: +Two new xref:{refpages}VkComponentTypeKHR.html[VkComponentTypeKHR] are added that can be reported as supported by xref:{refpages}vkGetPhysicalDeviceCooperativeMatrixPropertiesKHR.html[vkGetPhysicalDeviceCooperativeMatrixPropertiesKHR]: [source,c] ---- @@ -96,7 +96,7 @@ typedef enum VkComponentTypeKHR { } VkComponentTypeKHR; ---- -If `shaderFloat8CooperativeMatrix` is supported, at least one entry in link:{docs}chapters/shaders.html#vkGetPhysicalDeviceCooperativeMatrixPropertiesKHR[vkGetPhysicalDeviceCooperativeMatrixPropertiesKHR::pProperties] must include this type in all of its `AType`, `BType`, and `CType` members. +If `shaderFloat8CooperativeMatrix` is supported, at least one entry in xref:{refpages}vkGetPhysicalDeviceCooperativeMatrixPropertiesKHR.html[vkGetPhysicalDeviceCooperativeMatrixPropertiesKHR::pProperties] must include this type in all of its `AType`, `BType`, and `CType` members. == Issues diff --git a/proposals/VK_EXT_shader_long_vector.adoc b/proposals/VK_EXT_shader_long_vector.adoc index a1e5ecfc9..186fe9478 100644 --- a/proposals/VK_EXT_shader_long_vector.adoc +++ b/proposals/VK_EXT_shader_long_vector.adoc @@ -5,7 +5,7 @@ = VK_EXT_shader_long_vector :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: // Required so images render in github ifndef::images[:images: ../images] @@ -29,4 +29,4 @@ OpTypeCooperativeVectorNV are the same instruction (they are). == Examples -None. \ No newline at end of file +None. diff --git a/proposals/VK_EXT_shader_module_identifier.adoc b/proposals/VK_EXT_shader_module_identifier.adoc index 94c5d605e..1c146077e 100644 --- a/proposals/VK_EXT_shader_module_identifier.adoc +++ b/proposals/VK_EXT_shader_module_identifier.adoc @@ -4,7 +4,7 @@ = VK_EXT_shader_module_identifier :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This extension adds functionality to avoid having to pass down complete SPIR-V to shaders in situations diff --git a/proposals/VK_EXT_shader_object.adoc b/proposals/VK_EXT_shader_object.adoc index a8d9c5ea3..3107193dc 100644 --- a/proposals/VK_EXT_shader_object.adoc +++ b/proposals/VK_EXT_shader_object.adoc @@ -5,7 +5,7 @@ = VK_EXT_shader_object :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This document describes the proposed design for a new extension which aims to comprehensively address problems the pipeline abstraction has created for both applications and implementations. @@ -204,96 +204,96 @@ When drawing with shaders bound with `vkCmdBindShadersEXT()` most state must be * `vkCmdSetColorBlendEquationEXT()` * `vkCmdSetColorWriteMaskEXT()` -If link:{extensions}VK_KHR_fragment_shading_rate[VK_KHR_fragment_shading_rate] is supported and enabled: +If xref:{refpages}VK_KHR_fragment_shading_rate.html[VK_KHR_fragment_shading_rate] is supported and enabled: * `vkCmdSetFragmentShadingRateKHR()` -If link:{extensions}VK_EXT_transform_feedback[VK_EXT_transform_feedback] is supported and enabled: +If xref:{refpages}VK_EXT_transform_feedback.html[VK_EXT_transform_feedback] is supported and enabled: * `vkCmdSetRasterizationStreamEXT()` -If link:{extensions}VK_EXT_discard_rectangle[VK_EXT_discard_rectangle] is supported and enabled: +If xref:{refpages}VK_EXT_discard_rectangles.html[VK_EXT_discard_rectangles] is supported and enabled: * `vkCmdSetDiscardRectangleEnableEXT()` * `vkCmdSetDiscardRectangleModeEXT()` * `vkCmdSetDiscardRectangleEXT()` -If link:{extensions}VK_EXT_conservative_rasterization[VK_EXT_conservative_rasterization] is supported and enabled: +If xref:{refpages}VK_EXT_conservative_rasterization.html[VK_EXT_conservative_rasterization] is supported and enabled: * `vkCmdSetConservativeRasterizationModeEXT()` * `vkCmdSetExtraPrimitiveOverestimationSizeEXT()` -If link:{extensions}VK_EXT_depth_clip_enable[VK_EXT_depth_clip_enable] is supported and enabled: +If xref:{refpages}VK_EXT_depth_clip_enable.html[VK_EXT_depth_clip_enable] is supported and enabled: * `vkCmdSetDepthClipEnableEXT()` -If link:{extensions}VK_EXT_sample_locations[VK_EXT_sample_locations] is supported and enabled: +If xref:{refpages}VK_EXT_sample_locations.html[VK_EXT_sample_locations] is supported and enabled: * `vkCmdSetSampleLocationsEnableEXT()` * `vkCmdSetSampleLocationsEXT()` -If link:{extensions}VK_EXT_blend_operation_advanced[VK_EXT_blend_operation_advanced] is supported and enabled: +If xref:{refpages}VK_EXT_blend_operation_advanced.html[VK_EXT_blend_operation_advanced] is supported and enabled: * `vkCmdSetColorBlendAdvancedEXT()` -If link:{extensions}VK_EXT_provoking_vertex[VK_EXT_provoking_vertex] is supported and enabled: +If xref:{refpages}VK_EXT_provoking_vertex.html[VK_EXT_provoking_vertex] is supported and enabled: * `vkCmdSetProvokingVertexModeEXT()` -If link:{extensions}VK_EXT_line_rasterization[VK_EXT_line_rasterization] is supported and enabled: +If xref:{refpages}VK_EXT_line_rasterization.html[VK_EXT_line_rasterization] is supported and enabled: * `vkCmdSetLineRasterizationModeEXT()` * `vkCmdSetLineStippleEnableEXT()` * `vkCmdSetLineStippleEXT()` -If link:{extensions}VK_EXT_depth_clip_control[VK_EXT_depth_clip_control] is supported and enabled: +If xref:{refpages}VK_EXT_depth_clip_control.html[VK_EXT_depth_clip_control] is supported and enabled: * `vkCmdSetDepthClipNegativeOneToOneEXT()` -If link:{extensions}VK_EXT_color_write_enable[VK_EXT_color_write_enable] is supported and enabled: +If xref:{refpages}VK_EXT_color_write_enable.html[VK_EXT_color_write_enable] is supported and enabled: * `vkCmdSetColorWriteEnableEXT()` -If link:{extensions}VK_NV_clip_space_w_scaling[VK_NV_clip_space_w_scaling] is supported and enabled: +If xref:{refpages}VK_NV_clip_space_w_scaling.html[VK_NV_clip_space_w_scaling] is supported and enabled: * `vkCmdSetViewportWScalingEnableNV()` * `vkCmdSetViewportWScalingNV()` -If link:{extensions}VK_NV_viewport_swizzle[VK_NV_viewport_swizzle] is supported and enabled: +If xref:{refpages}VK_NV_viewport_swizzle.html[VK_NV_viewport_swizzle] is supported and enabled: * `vkCmdSetViewportSwizzleNV()` -If link:{extensions}VK_NV_fragment_coverage_to_color[VK_NV_fragment_coverage_to_color] is supported and enabled: +If xref:{refpages}VK_NV_fragment_coverage_to_color.html[VK_NV_fragment_coverage_to_color] is supported and enabled: * `vkCmdSetCoverageToColorEnableNV()` * `vkCmdSetCoverageToColorLocationNV()` -If link:{extensions}VK_NV_framebuffer_mixed_samples[VK_NV_framebuffer_mixed_samples] is supported and enabled: +If xref:{refpages}VK_NV_framebuffer_mixed_samples.html[VK_NV_framebuffer_mixed_samples] is supported and enabled: * `vkCmdSetCoverageModulationModeNV()` * `vkCmdSetCoverageModulationTableEnableNV()` * `vkCmdSetCoverageModulationTableNV()` -If link:{extensions}VK_NV_coverage_reduction_mode[VK_NV_coverage_reduction_mode] is supported and enabled: +If xref:{refpages}VK_NV_coverage_reduction_mode.html[VK_NV_coverage_reduction_mode] is supported and enabled: * `vkCmdSetCoverageReductionModeNV()` -If link:{extensions}VK_NV_representative_fragment_test[VK_NV_representative_fragment_test] is supported and enabled: +If xref:{refpages}VK_NV_representative_fragment_test.html[VK_NV_representative_fragment_test] is supported and enabled: * `vkCmdSetRepresentativeFragmentTestEnableNV()` -If link:{extensions}VK_NV_shading_rate_image[VK_NV_shading_rate_image] is supported and enabled: +If xref:{refpages}VK_NV_shading_rate_image.html[VK_NV_shading_rate_image] is supported and enabled: * `vkCmdSetCoarseSampleOrderNV()` * `vkCmdSetShadingRateImageEnableNV()` * `vkCmdSetViewportShadingRatePaletteNV()` -If link:{extensions}VK_NV_scissor_exclusive[VK_NV_scissor_exclusive] is supported and enabled: +If xref:{refpages}VK_NV_scissor_exclusive.html[VK_NV_scissor_exclusive] is supported and enabled: * `vkCmdSetExclusiveScissorEnableNV()` * `vkCmdSetExclusiveScissorNV()` -If link:{extensions}VK_NV_fragment_shading_rate_enums[VK_NV_fragment_shading_rate_enums] is supported and enabled: +If xref:{refpages}VK_NV_fragment_shading_rate_enums.html[VK_NV_fragment_shading_rate_enums] is supported and enabled: * `vkCmdSetFragmentShadingRateEnumNV()` diff --git a/proposals/VK_EXT_shader_replicated_composites.adoc b/proposals/VK_EXT_shader_replicated_composites.adoc index 863d1ac64..249f00195 100644 --- a/proposals/VK_EXT_shader_replicated_composites.adoc +++ b/proposals/VK_EXT_shader_replicated_composites.adoc @@ -5,7 +5,7 @@ = VK_EXT_shader_replicated_composites :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This document proposes adding support for new SPIR-V instructions to construct diff --git a/proposals/VK_EXT_shader_tile_image.adoc b/proposals/VK_EXT_shader_tile_image.adoc index 0f7e602e8..fad943830 100644 --- a/proposals/VK_EXT_shader_tile_image.adoc +++ b/proposals/VK_EXT_shader_tile_image.adoc @@ -5,7 +5,7 @@ = VK_EXT_shader_tile_image :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: // Required so images render in github ifndef::images[:images: ../images] @@ -139,19 +139,19 @@ When such memory dependencies are used the values at all sample locations inside the fragment area are made visible, regardless of coverage. To insert a memory dependency for explicit render pass tile image -synchronization, link:{docs}chapters/synchronization.html#vkCmdPipelineBarrier[vkCmdPipelineBarrier] -and link:{docs}chapters/synchronization.html#vkCmdPipelineBarrier2[vkCmdPipelineBarrier2] +synchronization, xref:{refpages}vkCmdPipelineBarrier.html[vkCmdPipelineBarrier] +and xref:{refpages}vkCmdPipelineBarrier2.html[vkCmdPipelineBarrier2] can now be called inside a render pass instance started with -link:{docs}chapters/renderpass.html#vkCmdBeginRendering[vkCmdBeginRendering]. +xref:{refpages}vkCmdBeginRendering.html[vkCmdBeginRendering]. The following restrictions apply for such pipeline barriers: * `dependencyFlags` must include `VK_DEPENDENCY_BY_REGION_BIT`. * The pipeline barriers can include only memory barriers. That is, buffer memory barriers and image memory barriers must not be used. - * The stages in the `srcStageMask` and `dstStageMask` members of link:{docs}chapters/synchronization.html#VkMemoryBarrier2[VkMemoryBarrier2] are restricted to framebuffer + * The stages in the `srcStageMask` and `dstStageMask` members of xref:{refpages}VkMemoryBarrier2.html[VkMemoryBarrier2] are restricted to framebuffer space stages. - * The access types in the `srcAccessMask` and `dstAccessMask` members of link:{docs}chapters/synchronization.html#VkMemoryBarrier2[VkMemoryBarrier2] are restricted to the + * The access types in the `srcAccessMask` and `dstAccessMask` members of xref:{refpages}VkMemoryBarrier2.html[VkMemoryBarrier2] are restricted to the following types: `VK_ACCESS_2_COLOR_ATTACHMENT_READ_BIT`, `VK_ACCESS_2_COLOR_ATTACHMENT_WRITE_BIT`, `VK_ACCESS_2_DEPTH_STENCIL_ATTACHMENT_READ_BIT`, and diff --git a/proposals/VK_EXT_shader_uniform_buffer_unsized_array.adoc b/proposals/VK_EXT_shader_uniform_buffer_unsized_array.adoc index 0ac58c0ae..2ba411930 100644 --- a/proposals/VK_EXT_shader_uniform_buffer_unsized_array.adoc +++ b/proposals/VK_EXT_shader_uniform_buffer_unsized_array.adoc @@ -5,7 +5,7 @@ = VK_EXT_shader_uniform_buffer_unsized_array :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: == Problem Statement diff --git a/proposals/VK_EXT_subpass_merge_feedback.adoc b/proposals/VK_EXT_subpass_merge_feedback.adoc index 9151aea95..d2576b480 100644 --- a/proposals/VK_EXT_subpass_merge_feedback.adoc +++ b/proposals/VK_EXT_subpass_merge_feedback.adoc @@ -5,7 +5,7 @@ = VK_EXT_subpass_merge_feedback :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: == Problem Statement diff --git a/proposals/VK_EXT_surface_maintenance1.adoc b/proposals/VK_EXT_surface_maintenance1.adoc index f5e24098c..21302039a 100644 --- a/proposals/VK_EXT_surface_maintenance1.adoc +++ b/proposals/VK_EXT_surface_maintenance1.adoc @@ -5,7 +5,7 @@ = VK_EXT_surface_maintenance1 :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This proposal investigates and addresses a number of practical issues with the diff --git a/proposals/VK_EXT_swapchain_maintenance1.adoc b/proposals/VK_EXT_swapchain_maintenance1.adoc index 091743bf7..4f73e9806 100644 --- a/proposals/VK_EXT_swapchain_maintenance1.adoc +++ b/proposals/VK_EXT_swapchain_maintenance1.adoc @@ -5,7 +5,7 @@ = VK_EXT_swapchain_maintenance1 :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This proposal investigates and addresses a number of practical issues with the diff --git a/proposals/VK_EXT_texture_compression_astc_3d.adoc b/proposals/VK_EXT_texture_compression_astc_3d.adoc index 0b89c02a2..3ff78dc5b 100644 --- a/proposals/VK_EXT_texture_compression_astc_3d.adoc +++ b/proposals/VK_EXT_texture_compression_astc_3d.adoc @@ -5,7 +5,7 @@ = VK_EXT_texture_compression_astc_3d :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This document proposes adding support for ASTC 3D formats. diff --git a/proposals/VK_EXT_zero_initialize_device_memory.adoc b/proposals/VK_EXT_zero_initialize_device_memory.adoc index 9780d5704..d4141e267 100644 --- a/proposals/VK_EXT_zero_initialize_device_memory.adoc +++ b/proposals/VK_EXT_zero_initialize_device_memory.adoc @@ -5,7 +5,7 @@ = VK_EXT_zero_initialize_device_memory :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: `VK_EXT_zero_initialize_device_memory` intends to add more control over how diff --git a/proposals/VK_GOOGLE_surfaceless_query.adoc b/proposals/VK_GOOGLE_surfaceless_query.adoc index b2bb256df..85dc5eea2 100644 --- a/proposals/VK_GOOGLE_surfaceless_query.adoc +++ b/proposals/VK_GOOGLE_surfaceless_query.adoc @@ -5,7 +5,7 @@ = VK_GOOGLE_surfaceless_query :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This proposal regards layering OpenGL over Vulkan, and addresses a discrepancy @@ -21,7 +21,7 @@ color space to `eglCreateWindowSurface` at the same time. In Vulkan, the format and color space information are retrievable from the `VkSurfaceKHR` through -link:{docs}chapters/VK_KHR_surface/wsi.html#vkGetPhysicalDeviceSurfaceFormatsKHR[`vkGetPhysicalDeviceSurfaceFormatsKHR`] +xref:{refpages}vkGetPhysicalDeviceSurfaceFormatsKHR.html[`vkGetPhysicalDeviceSurfaceFormatsKHR`] When layering OpenGL over Vulkan, there needs to be a way to query this information before the surface is created. @@ -45,7 +45,7 @@ OpenGL over Vulkan in this regard. === Surfaceless Queries One solution is to modify the existing relevant queries to allow querying -without a link:{docs}chapters/VK_KHR_surface/wsi.html#VkSurfaceKHR[`VkSurfaceKHR`]. +without a xref:{refpages}VkSurfaceKHR.html[`VkSurfaceKHR`]. This works on platforms where this information is truly global, which is currently the case with Google's Android and SwiftShader. @@ -65,15 +65,15 @@ accelerate producing working systems where OpenGL is layered on Vulkan. With this extension, the `surface` parameter can be `VK_NULL_HANDLE` in the following: -- link:{docs}chapters/VK_KHR_surface/wsi.html#vkGetPhysicalDeviceSurfaceFormatsKHR[`vkGetPhysicalDeviceSurfaceFormatsKHR`] -- link:{docs}chapters/VK_KHR_surface/wsi.html#vkGetPhysicalDeviceSurfacePresentModesKHR[`vkGetPhysicalDeviceSurfacePresentModesKHR`] +- xref:{refpages}vkGetPhysicalDeviceSurfaceFormatsKHR.html[`vkGetPhysicalDeviceSurfaceFormatsKHR`] +- xref:{refpages}vkGetPhysicalDeviceSurfacePresentModesKHR.html[`vkGetPhysicalDeviceSurfacePresentModesKHR`] - `pSurfaceInfo->surface` passed to - link:{docs}chapters/VK_KHR_surface/wsi.html#vkGetPhysicalDeviceSurfaceCapabilities2KHR[`vkGetPhysicalDeviceSurfaceCapabilities2KHR`] + xref:{refpages}vkGetPhysicalDeviceSurfaceCapabilities2KHR.html[`vkGetPhysicalDeviceSurfaceCapabilities2KHR`] if - link:{docs}chapters/VK_KHR_surface/wsi.html#VkSurfaceProtectedCapabilitiesKHR[`VkSurfaceProtectedCapabilitiesKHR`] + xref:{refpages}VkSurfaceProtectedCapabilitiesKHR.html[`VkSurfaceProtectedCapabilitiesKHR`] is chained to `pSurfaceCapabilities`. In this case, only the protected information is populated, while - link:{docs}chapters/VK_KHR_surface/wsi.html#VkSurfaceCapabilities2KHR[`VkSurfaceCapabilities2KHR`]`::surfaceCapabilities` + xref:{refpages}VkSurfaceCapabilities2KHR.html[`VkSurfaceCapabilities2KHR`]`::surfaceCapabilities` and any other chained structs will have undefined values. In all the above situations, calling the function with any valid `surface` diff --git a/proposals/VK_HUAWEI_cluster_culling_shader.adoc b/proposals/VK_HUAWEI_cluster_culling_shader.adoc index 459395431..d920f2244 100644 --- a/proposals/VK_HUAWEI_cluster_culling_shader.adoc +++ b/proposals/VK_HUAWEI_cluster_culling_shader.adoc @@ -5,7 +5,7 @@ = VK_HUAWEI_cluster_culling_shader :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: diff --git a/proposals/VK_HUAWEI_invocation_mask.adoc b/proposals/VK_HUAWEI_invocation_mask.adoc index 89292f6e2..c73f61859 100644 --- a/proposals/VK_HUAWEI_invocation_mask.adoc +++ b/proposals/VK_HUAWEI_invocation_mask.adoc @@ -6,7 +6,7 @@ = VK_HUAWEI_invocation_mask :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ diff --git a/proposals/VK_KHR_compute_shader_derivatives.adoc b/proposals/VK_KHR_compute_shader_derivatives.adoc index 103462e9f..789e00491 100644 --- a/proposals/VK_KHR_compute_shader_derivatives.adoc +++ b/proposals/VK_KHR_compute_shader_derivatives.adoc @@ -5,13 +5,13 @@ = VK_KHR_compute_shader_derivatives :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This extension enables applications to use derivative operations from execution models with defined workgroups. NOTE: This extension is a promotion (with additions) of -link:{extensions}VK_NV_compute_shader_derivatives[VK_NV_compute_shader_derivatives]. +xref:{refpages}VK_NV_compute_shader_derivatives.html[VK_NV_compute_shader_derivatives]. As that extension already shipped before proposal documents existed, this document has been written retroactively during promotion to KHR. diff --git a/proposals/VK_KHR_cooperative_matrix.adoc b/proposals/VK_KHR_cooperative_matrix.adoc index 3c324a982..133df0324 100644 --- a/proposals/VK_KHR_cooperative_matrix.adoc +++ b/proposals/VK_KHR_cooperative_matrix.adoc @@ -5,7 +5,7 @@ = VK_KHR_cooperative_matrix :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This document proposes adding support for so-called cooperative matrix diff --git a/proposals/VK_KHR_copy_memory_indirect.adoc b/proposals/VK_KHR_copy_memory_indirect.adoc index 158519acf..80ff01aa5 100644 --- a/proposals/VK_KHR_copy_memory_indirect.adoc +++ b/proposals/VK_KHR_copy_memory_indirect.adoc @@ -5,7 +5,7 @@ = VK_KHR_copy_memory_indirect :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This document details the VK_KHR_copy_memory_indirect extension which diff --git a/proposals/VK_KHR_device_address_commands.adoc b/proposals/VK_KHR_device_address_commands.adoc index 564ed8d4b..8aecb756c 100644 --- a/proposals/VK_KHR_device_address_commands.adoc +++ b/proposals/VK_KHR_device_address_commands.adoc @@ -5,10 +5,10 @@ = VK_KHR_device_address_commands :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: -This extension enables applications to use device addresses in place of buffer objects for core functionality. +This extension enables applications to use device addresses in place of buffer objects for core functionality. == Problem Statement @@ -197,13 +197,13 @@ void vkCmdDispatchIndirect2KHR( const VkDispatchIndirect2InfoKHR* pInfo); ---- -`vkCmdDrawMesh*` commands are added as an interaction with link:{extensions}VK_EXT_mesh_shader.html[VK_EXT_mesh_shader], and `vkCmdDraw*IndirectCount2KHR` commands are added as an interaction with link:{extensions}VK_KHR_draw_indirect_count.html[VK_KHR_draw_indirect_count] or Vulkan 1.2. +`vkCmdDrawMesh*` commands are added as an interaction with xref:{refpages}VK_EXT_mesh_shader.html[VK_EXT_mesh_shader], and `vkCmdDraw*IndirectCount2KHR` commands are added as an interaction with xref:{refpages}VK_KHR_draw_indirect_count.html[VK_KHR_draw_indirect_count] or Vulkan 1.2. === Transfer Commands Transfer commands involving buffer objects including copies, update, and fill, are modified to accept device addresses instead of buffer objects, and are renamed accordingly. -Copy commands are based on link:{extensions}VK_KHR_copy_commands2.html[VK_KHR_copy_commands2], which is required by this extension. +Copy commands are based on xref:{refpages}VK_KHR_copy_commands2.html[VK_KHR_copy_commands2], which is required by this extension. [source,c] ---- @@ -251,7 +251,7 @@ typedef struct VkCopyDeviceMemoryImageInfoKHR { void vkCmdCopyMemoryToImageKHR( VkCommandBuffer commandBuffer, const VkCopyDeviceMemoryImageInfoKHR* pCopyMemoryInfo); - + void vkCmdCopyImageToMemoryKHR( VkCommandBuffer commandBuffer, const VkCopyDeviceMemoryImageInfoKHR* pCopyMemoryInfo); @@ -307,12 +307,12 @@ typedef struct VkMemoryRangeBarrierKHR { } VkMemoryRangeBarrierKHR; ---- -`VkMemoryRangeBarriersInfoKHR` can be chained to link:{docs}/chapters/synchronization.html#VkDependencyInfo.html[VkDependencyInfo] structures to define memory dependencies on memory ranges directly, rather than buffer objects. +`VkMemoryRangeBarriersInfoKHR` can be chained to xref:{refpages}VkDependencyInfo.html[VkDependencyInfo] structures to define memory dependencies on memory ranges directly, rather than buffer objects. === Conditional Rendering -A revised version of link:{extensions}vkCmdBeginConditionalRenderingEXT.html[vkCmdBeginConditionalRenderingEXT] is added when link:{extensions}VK_EXT_conditional_rendering.html[VK_EXT_conditional_rendering] is supported, that functions identically but takes an address range instead of a buffer and offset: +A revised version of xref:{refpages}vkCmdBeginConditionalRenderingEXT.html[vkCmdBeginConditionalRenderingEXT] is added when xref:{refpages}VK_EXT_conditional_rendering.html[VK_EXT_conditional_rendering] is supported, that functions identically but takes an address range instead of a buffer and offset: [source,c] ---- @@ -332,7 +332,7 @@ void vkCmdBeginConditionalRendering2EXT( === Transform Feedback -Transform feedback commands added by link:{extensions}VK_EXT_transform_feedback.html[VK_EXT_transform_feedback] now accept address ranges rather than buffer objects, but are otherwise unmodified. +Transform feedback commands added by xref:{refpages}VK_EXT_transform_feedback.html[VK_EXT_transform_feedback] now accept address ranges rather than buffer objects, but are otherwise unmodified. [source,c] ---- @@ -360,7 +360,7 @@ void vkCmdEndTransformFeedback2EXT( uint32_t firstCounterRange, uint32_t counterRangeCount, const VkBindTransformFeedbackBuffer2InfoEXT* pCounterInfos); - + void vkCmdDrawIndirectByteCount2EXT( VkCommandBuffer commandBuffer, uint32_t instanceCount, @@ -373,7 +373,7 @@ void vkCmdDrawIndirectByteCount2EXT( === Buffer Markers -If link:{extensions}VK_AMD_buffer_marker.html[VK_AMD_buffer_marker] is supported, a new function is added that accepts an address rather than a buffer. +If xref:{refpages}VK_AMD_buffer_marker.html[VK_AMD_buffer_marker] is supported, a new function is added that accepts an address rather than a buffer. As precisely one `uint32_t` value is always written by this command, there is no associated size for the address. [source,c] @@ -395,7 +395,7 @@ void vkCmdWriteMarkerToMemoryAMD( === Acceleration Structures -If link:{extensions}VK_KHR_acceleration_structure.html[VK_KHR_acceleration_structure] is supported, a new function is added that accepts an address rather than a buffer. +If xref:{refpages}VK_KHR_acceleration_structure.html[VK_KHR_acceleration_structure] is supported, a new function is added that accepts an address rather than a buffer. [source,c] ---- diff --git a/proposals/VK_KHR_device_fault.adoc b/proposals/VK_KHR_device_fault.adoc index 4ac385c58..1f9366e4c 100644 --- a/proposals/VK_KHR_device_fault.adoc +++ b/proposals/VK_KHR_device_fault.adoc @@ -5,7 +5,7 @@ = VK_KHR_device_fault :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: // Required so images render in github ifndef::images[:images: ../images] diff --git a/proposals/VK_KHR_dynamic_rendering.adoc b/proposals/VK_KHR_dynamic_rendering.adoc index 2d4da7960..6fe2ab834 100644 --- a/proposals/VK_KHR_dynamic_rendering.adoc +++ b/proposals/VK_KHR_dynamic_rendering.adoc @@ -5,7 +5,7 @@ = VK_KHR_dynamic_rendering :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This document details API design ideas for the VK_KHR_dynamic_rendering extension, which adds a more dynamic and flexible way to use draw commands, as a straightforward replacement for single pass render passes. @@ -113,7 +113,7 @@ typedef struct VkRenderingAttachmentInfoKHR { There are no layout transitions or other synchronization info for images – synchronization is done exclusively by existing synchronization commands - the layouts provided are those that the image must already be in when rendering. -Image views for any attachment may be link:{docs}appendices/boilerplate.html#VK_NULL_HANDLE[VK_NULL_HANDLE], indicating that writes to the attachment are discarded, and reads return undefined values. +Image views for any attachment may be xref:{refpages}VK_NULL_HANDLE.html[VK_NULL_HANDLE], indicating that writes to the attachment are discarded, and reads return undefined values. Note that the resolve images do not have their own load/store operations; they are treated as if they are implicitly `VK_ATTACHMENT_LOAD_OP_DONT_CARE` and `VK_ATTACHMENT_STORE_OP_STORE` – other combinations in the existing API do not really carry any useful meaning. @@ -121,7 +121,7 @@ Note that the resolve images do not have their own load/store operations; they a ===== Store Op None -A new store operation is provided as originally described by link:{extensions}VK_QCOM_render_pass_store_ops[VK_QCOM_render_pass_store_ops]: +A new store operation is provided as originally described by xref:{refpages}VK_QCOM_render_pass_store_ops.html[VK_QCOM_render_pass_store_ops]: [source,c] ---- @@ -179,7 +179,7 @@ However, an alternative method of recording commands across multiple command buf [[command-buffer-inheritance-mixed-samples]] ====== Mixed Samples -If either of link:{extensions}VK_NV_framebuffer_mixed_samples[VK_NV_framebuffer_mixed_samples] or link:{extensions}VK_AMD_mixed_attachment_samples[VK_AMD_mixed_attachment_samples] are enabled, the sample counts of color and depth attachments may vary from the `rasterizationSamples`. +If either of xref:{refpages}VK_NV_framebuffer_mixed_samples.html[VK_NV_framebuffer_mixed_samples] or xref:{refpages}VK_AMD_mixed_attachment_samples.html[VK_AMD_mixed_attachment_samples] are enabled, the sample counts of color and depth attachments may vary from the `rasterizationSamples`. In this case, the sample count of each attachment can be specified by including the `VkAttachmentSampleInfoAMD`/`VkAttachmentSampleCountInfoNV` structure in the same `pNext` chain. [source,c] @@ -199,7 +199,7 @@ typedef VkAttachmentSampleCountInfoAMD VkAttachmentSampleCountInfoNV; [[command-buffer-inheritance-multiview-per-view-attributes]] ====== Multiview Per-View Attributes -If link:{extensions}VK_NVX_multiview_per_view_attributes[VK_NVX_multiview_per_view_attributes] is enabled, the multiview per-view attributes can be specified by including the `VkMultiviewPerViewAttributesInfoNVX` structure in the same `pNext` chain. +If xref:{refpages}VK_NVX_multiview_per_view_attributes.html[VK_NVX_multiview_per_view_attributes] is enabled, the multiview per-view attributes can be specified by including the `VkMultiviewPerViewAttributesInfoNVX` structure in the same `pNext` chain. [[suspending-and-resuming]] @@ -218,12 +218,12 @@ A dynamic render pass can be both suspending and resuming. ==== Device Groups -The link:{docs}chapters/renderpass.html#VkDeviceGroupRenderPassBeginInfo[VkDeviceGroupRenderPassBeginInfo] structure can be chained from `VkRenderingInfoKHR`, with the same effect as when chained to link:{docs}chapters/renderpass.html#VkRenderPassBeginInfo[VkRenderPassBeginInfo] - setting the device mask and setting independent render areas per device. +The xref:{refpages}VkDeviceGroupRenderPassBeginInfo.html[VkDeviceGroupRenderPassBeginInfo] structure can be chained from `VkRenderingInfoKHR`, with the same effect as when chained to xref:{refpages}VkRenderPassBeginInfo.html[VkRenderPassBeginInfo] - setting the device mask and setting independent render areas per device. ==== Fragment Shading Rate -If link:{extensions}VK_KHR_fragment_shading_rate[VK_KHR_fragment_shading_rate] is enabled, when calling `vkCmdBeginRenderingKHR`, the following structure should be chained to `VkRenderingInfoKHR` to include a fragment shading rate attachment: +If xref:{refpages}VK_KHR_fragment_shading_rate.html[VK_KHR_fragment_shading_rate] is enabled, when calling `vkCmdBeginRenderingKHR`, the following structure should be chained to `VkRenderingInfoKHR` to include a fragment shading rate attachment: [source,c] ---- @@ -238,7 +238,7 @@ typedef struct VkRenderingFragmentShadingRateAttachmentInfoKHR { ==== Fragment Density Map -If link:{extensions}VK_EXT_fragment_density_map[VK_EXT_fragment_density_map] is enabled, when calling `vkCmdBeginRenderingKHR`, the following structure should be chained to `VkRenderingInfoKHR` to include a fragment density map attachment: +If xref:{refpages}VK_EXT_fragment_density_map.html[VK_EXT_fragment_density_map] is enabled, when calling `vkCmdBeginRenderingKHR`, the following structure should be chained to `VkRenderingInfoKHR` to include a fragment density map attachment: [source,c] ---- @@ -254,7 +254,7 @@ typedef struct VkRenderingFragmentDensityMapAttachmentInfoEXT { === Pipeline Creation With the removal of render pass objects, it is now necessary to provide some of that same information to applications at pipeline creation. -This structure is chained from link:{docs}chapters/pipelines.html#VkGraphicsPipelineCreateInfo[VkGraphicsPipelineCreateInfo]: +This structure is chained from xref:{refpages}VkGraphicsPipelineCreateInfo.html[VkGraphicsPipelineCreateInfo]: [source,c] ---- @@ -277,18 +277,18 @@ The value of `viewMask` must match the value of the `viewMask` member of `VkRend ==== Multiview Per-View Attributes -If link:{extensions}VK_NVX_multiview_per_view_attributes[VK_NVX_multiview_per_view_attributes] is enabled, the multiview per-view attributes can be specified by including the `VkMultiviewPerViewAttributesInfoNVX` structure in the same `pNext` chain. +If xref:{refpages}VK_NVX_multiview_per_view_attributes.html[VK_NVX_multiview_per_view_attributes] is enabled, the multiview per-view attributes can be specified by including the `VkMultiviewPerViewAttributesInfoNVX` structure in the same `pNext` chain. ==== Mixed Sample Attachments -If either of link:{extensions}VK_NV_framebuffer_mixed_samples[VK_NV_framebuffer_mixed_samples] or link:{extensions}VK_AMD_mixed_attachment_samples[VK_AMD_mixed_attachment_samples] are enabled, the sample counts of color and depth attachments must be specified at pipeline creation as well. +If either of xref:{refpages}VK_NV_framebuffer_mixed_samples.html[VK_NV_framebuffer_mixed_samples] or xref:{refpages}VK_AMD_mixed_attachment_samples.html[VK_AMD_mixed_attachment_samples] are enabled, the sample counts of color and depth attachments must be specified at pipeline creation as well. As with <>, the sample count of each attachment can be specified by including the `VkAttachmentSampleInfoAMD`/`VkAttachmentSampleCountInfoNV` structure in the `pNext` chain. -If the structure is omitted, the sample count for each attachment is considered equal to link:{docs}chapters/primsrast.html#VkPipelineMultisampleStateCreateInfo[`VkPipelineMultisampleStateCreateInfo::rasterizationSamples`]. +If the structure is omitted, the sample count for each attachment is considered equal to xref:{refpages}VkPipelineMultisampleStateCreateInfo.html[`VkPipelineMultisampleStateCreateInfo::rasterizationSamples`]. ==== Fragment Shading Rate -If link:{extensions}VK_KHR_fragment_shading_rate[VK_KHR_fragment_shading_rate] is enabled, a new rasterization state pipeline creation flag must be provided if a shading rate attachment will be used: +If xref:{refpages}VK_KHR_fragment_shading_rate.html[VK_KHR_fragment_shading_rate] is enabled, a new rasterization state pipeline creation flag must be provided if a shading rate attachment will be used: [source,c] ---- @@ -298,7 +298,7 @@ VK_PIPELINE_CREATE_RENDERING_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR ==== Fragment Density Map -If link:{extensions}VK_EXT_fragment_density_map[VK_EXT_fragment_density_map] is enabled, a new rasterization state pipeline creation flag must be provided if a fragment density map will be used: +If xref:{refpages}VK_EXT_fragment_density_map.html[VK_EXT_fragment_density_map] is enabled, a new rasterization state pipeline creation flag must be provided if a fragment density map will be used: [source,c] ---- @@ -443,5 +443,5 @@ No - without input attachments or a solution for on-chip storage these are curre === Is there a preferred render area granularity for `VkRenderingInfo::renderArea` similar to `vkGetRenderAreaGranularity`? During design discussions for this extension, no hardware vendor felt that this functionality was important enough to bring over to dynamic rendering. -If vendors have performance concerns, extensions such as link:{extensions}VK_QCOM_tile_properties[VK_QCOM_tile_properties] can be exposed, and there may be scope for a future cross-vendor extension. +If vendors have performance concerns, extensions such as xref:{refpages}VK_QCOM_tile_properties.html[VK_QCOM_tile_properties] can be exposed, and there may be scope for a future cross-vendor extension. Applications can use values for the render area freely without alignment considerations. diff --git a/proposals/VK_KHR_dynamic_rendering_local_read.adoc b/proposals/VK_KHR_dynamic_rendering_local_read.adoc index 01333177e..e0925e851 100644 --- a/proposals/VK_KHR_dynamic_rendering_local_read.adoc +++ b/proposals/VK_KHR_dynamic_rendering_local_read.adoc @@ -5,7 +5,7 @@ = VK_KHR_dynamic_rendering_local_read :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This extension enables reads from attachments and resources written by previous fragment shaders within a dynamic render pass. @@ -13,10 +13,10 @@ This extension enables reads from attachments and resources written by previous == Problem Statement -link:{extensions}VK_KHR_dynamic_rendering.adoc[VK_KHR_dynamic_rendering] enabled a much more straightforward method for applications to setup rendering code without the need for a large dedicated object up front. +xref:{refpages}VK_KHR_dynamic_rendering.html[VK_KHR_dynamic_rendering] enabled a much more straightforward method for applications to setup rendering code without the need for a large dedicated object up front. That extension enabled a number of applications that do not use multiple subpasses to use a more streamlined method for getting rendering started. -However, applications using multiple subpasses or wanting to do things like order independent transparency or simple deferred rendering cannot make use of link:{extensions}VK_KHR_dynamic_rendering.adoc[VK_KHR_dynamic_rendering], as there is no path for subpass dependencies to be expressed without breaking rendering across multiple separate render passes. +However, applications using multiple subpasses or wanting to do things like order independent transparency or simple deferred rendering cannot make use of xref:{refpages}VK_KHR_dynamic_rendering.html[VK_KHR_dynamic_rendering], as there is no path for subpass dependencies to be expressed without breaking rendering across multiple separate render passes. Adding a method for applications using these techniques to express these in dynamic rendering would enable more developers to take advantage of this functionality without the complexity of setting up render pass objects. @@ -98,8 +98,8 @@ void vkCmdSetRenderingAttachmentLocationsKHR( As with render pass objects, this information must be provided both when creating a pipeline and during rendering, and must match between the two in order to be valid. -This information can be provided during pipeline creation by chaining `VkRenderingAttachmentLocationInfoKHR` to link:{docs}chapters/pipelines.html#VkGraphicsPipelineCreateInfo[VkGraphicsPipelineCreateInfo] when the fragment output state subset is required. -If this structure is not provided for pipeline creation, it is equivalent to setting the value of each element of `pColorAttachmentLocations` to the value of its index within the array, and `colorAttachmentCount` equal to the value of link:{docs}chapters/pipelines.html#VkPipelineRenderingCreateInfoKHR[VkPipelineRenderingCreateInfoKHR::colorAttachmentCount]. +This information can be provided during pipeline creation by chaining `VkRenderingAttachmentLocationInfoKHR` to xref:{refpages}VkGraphicsPipelineCreateInfo.html[VkGraphicsPipelineCreateInfo] when the fragment output state subset is required. +If this structure is not provided for pipeline creation, it is equivalent to setting the value of each element of `pColorAttachmentLocations` to the value of its index within the array, and `colorAttachmentCount` equal to the value of xref:{refpages}VkPipelineRenderingCreateInfoKHR.html[VkPipelineRenderingCreateInfoKHR::colorAttachmentCount]. `vkCmdSetRenderingAttachmentLocationsKHR` must only be called within a dynamic render pass instance. If this command is not called, the default state is that each element of `pColorAttachmentLocations` is equal to the value of its index within the array. @@ -116,14 +116,14 @@ This means when porting from render pass objects, care must be taken to ensure t When issuing a draw call, the location mapping must match between the bound graphics pipeline and the command buffer state set by `vkCmdSetRenderingAttachmentLocationsKHR`. -`VkRenderingAttachmentLocationInfoKHR` can also be chained to link:{docs}chapters/cmdbuffers.html#VkCommandBufferInheritanceInfo[VkCommandBufferInheritanceInfo] when using secondary command buffers, to specify the color attachment location mapping in the primary command buffer when link:{docs}chapters/cmdbuffers.html#vkCmdExecuteCommands[vkCmdExecuteCommands] is called. -If `VkRenderingAttachmentLocationInfoKHR` is not provided in the inheritance info, it is equivalent to providing it with the value of each element of `pColorAttachmentLocations` set to the value of its index within the array, with the color attachment count equal to that specified by link:{docs}chapters/cmdbuffers.html#VkCommandBufferInheritanceRenderingInfo[VkCommandBufferInheritanceRenderingInfo::colorAttachmentCount]. -This information must match between the inheritance info and the state when link:{docs}chapters/cmdbuffers.html#vkCmdExecuteCommands[vkCmdExecuteCommands] is called if there is a currently active render pass instance. +`VkRenderingAttachmentLocationInfoKHR` can also be chained to xref:{refpages}VkCommandBufferInheritanceInfo.html[VkCommandBufferInheritanceInfo] when using secondary command buffers, to specify the color attachment location mapping in the primary command buffer when xref:{refpages}vkCmdExecuteCommands.html[vkCmdExecuteCommands] is called. +If `VkRenderingAttachmentLocationInfoKHR` is not provided in the inheritance info, it is equivalent to providing it with the value of each element of `pColorAttachmentLocations` set to the value of its index within the array, with the color attachment count equal to that specified by xref:{refpages}VkCommandBufferInheritanceRenderingInfo.html[VkCommandBufferInheritanceRenderingInfo::colorAttachmentCount]. +This information must match between the inheritance info and the state when xref:{refpages}vkCmdExecuteCommands.html[vkCmdExecuteCommands] is called if there is a currently active render pass instance. NOTE: This functionality is provided primarily for porting existing content to the new API; new applications should maintain a consistent location for all attachments in their shaders during a render pass; this functionality can be considered immediately deprecated. -While an attachment is mapped to `VK_ATTACHMENT_UNUSED` in command buffer state (either via `vkCmdSetRenderingAttachmentLocationsKHR` or inheritance state), it must not be cleared by link:{docs}chapters/clears.html#vkCmdClearAttachments[vkCmdClearAttachments]. -Some implementations will update the render pass attachment bindings when remapping occurs, leaving unmapped attachments unavailable to be written to via the path that link:{docs}chapters/clears.html#vkCmdClearAttachments[vkCmdClearAttachments] would use. +While an attachment is mapped to `VK_ATTACHMENT_UNUSED` in command buffer state (either via `vkCmdSetRenderingAttachmentLocationsKHR` or inheritance state), it must not be cleared by xref:{refpages}vkCmdClearAttachments.html[vkCmdClearAttachments]. +Some implementations will update the render pass attachment bindings when remapping occurs, leaving unmapped attachments unavailable to be written to via the path that xref:{refpages}vkCmdClearAttachments.html[vkCmdClearAttachments] would use. This is in line with render pass objects, where applications would not be able to clear an attachment outside of the current subpass. @@ -153,8 +153,8 @@ void vkCmdSetRenderingInputAttachmentIndicesKHR( const VkRenderingInputAttachmentIndexInfoKHR* pInputAttachmentIndexInfo); ---- -This information can be provided during pipeline creation by chaining `VkRenderingInputAttachmentIndexInfoKHR` to link:{docs}chapters/pipelines.html#VkGraphicsPipelineCreateInfo[VkGraphicsPipelineCreateInfo] when the fragment shader state subset is required. -If this structure is not provided for pipeline creation, it is equivalent to setting the value of each element of `pColorAttachmentInputIndices` to the value of its index within the array, `colorAttachmentCount` to the value of link:{docs}chapters/pipelines.html#VkPipelineRenderingCreateInfoKHR[VkPipelineRenderingCreateInfoKHR::colorAttachmentCount], and `pDepthInputAttachmentIndex` and `pStencilInputAttachmentIndex` to `NULL`. +This information can be provided during pipeline creation by chaining `VkRenderingInputAttachmentIndexInfoKHR` to xref:{refpages}VkGraphicsPipelineCreateInfo.html[VkGraphicsPipelineCreateInfo] when the fragment shader state subset is required. +If this structure is not provided for pipeline creation, it is equivalent to setting the value of each element of `pColorAttachmentInputIndices` to the value of its index within the array, `colorAttachmentCount` to the value of xref:{refpages}VkPipelineRenderingCreateInfoKHR.html[VkPipelineRenderingCreateInfoKHR::colorAttachmentCount], and `pDepthInputAttachmentIndex` and `pStencilInputAttachmentIndex` to `NULL`. `vkCmdSetRenderingInputAttachmentIndicesKHR` must only be called within a dynamic render pass instance. If this command is not called, the default state is that each element of `pColorAttachmentInputIndices` to the value of its index within the array, and `pDepthInputAttachmentIndex` and `pStencilInputAttachmentIndex` are set to `NULL`. @@ -168,9 +168,9 @@ If `pDepthInputAttachmentIndex`, `pStencilInputAttachmentIndex`, or any element When issuing a draw call, the input attachment index mapping must match between the bound graphics pipeline and the command buffer state set by `vkCmdSetRenderingInputAttachmentIndicesKHR`. -`VkRenderingInputAttachmentIndexInfoKHR` can also be chained to link:{docs}chapters/cmdbuffers.html#VkCommandBufferInheritanceInfo[VkCommandBufferInheritanceInfo] when using secondary command buffers, to specify the input attachment index mapping in the primary command buffer when link:{docs}chapters/cmdbuffers.html#vkCmdExecuteCommands[vkCmdExecuteCommands] is called. -If `VkRenderingInputAttachmentIndexInfoKHR` is not provided in the inheritance info, it is equivalent to providing it with the value of each element of `pColorAttachmentInputIndices` set to the value of its index within the array, `colorAttachmentCount` set to the value of link:{docs}chapters/cmdbuffers.html#VkCommandBufferInheritanceRenderingInfo[VkCommandBufferInheritanceRenderingInfo::colorAttachmentCount], and `pDepthInputAttachmentIndex` and `pStencilInputAttachmentIndex` set to `NULL`. -This information must match between the inheritance info and the state when link:{docs}chapters/cmdbuffers.html#vkCmdExecuteCommands[vkCmdExecuteCommands] is called if there is a currently active render pass instance. +`VkRenderingInputAttachmentIndexInfoKHR` can also be chained to xref:{refpages}VkCommandBufferInheritanceInfo.html[VkCommandBufferInheritanceInfo] when using secondary command buffers, to specify the input attachment index mapping in the primary command buffer when xref:{refpages}vkCmdExecuteCommands.html[vkCmdExecuteCommands] is called. +If `VkRenderingInputAttachmentIndexInfoKHR` is not provided in the inheritance info, it is equivalent to providing it with the value of each element of `pColorAttachmentInputIndices` set to the value of its index within the array, `colorAttachmentCount` set to the value of xref:{refpages}VkCommandBufferInheritanceRenderingInfo.html[VkCommandBufferInheritanceRenderingInfo::colorAttachmentCount], and `pDepthInputAttachmentIndex` and `pStencilInputAttachmentIndex` set to `NULL`. +This information must match between the inheritance info and the state when xref:{refpages}vkCmdExecuteCommands.html[vkCmdExecuteCommands] is called if there is a currently active render pass instance. NOTE: The remapping functionality is provided primarily for porting existing content to the new API; new applications should set their index attachment indices consistently for all attachments in their shaders during a render pass; this functionality can be considered immediately deprecated. @@ -182,17 +182,17 @@ For dynamic rendering, these cannot be specified by tagging them as another atta Rather than specifying them in the render pass, as they must be associated with a descriptor, implementations will unconditionally fetch values from the input attachment descriptor if the `InputAttachmentIndex` is not mapped to another attachment. -NOTE: Some implementations may have to now provide a real descriptor when advertising this extension where they did not before - which may affect things like link:{extensions}VK_EXT_descriptor_buffer[VK_EXT_descriptor_buffer], where the size of the descriptor is advertised. +NOTE: Some implementations may have to now provide a real descriptor when advertising this extension where they did not before - which may affect things like xref:{refpages}VK_EXT_descriptor_buffer.html[VK_EXT_descriptor_buffer], where the size of the descriptor is advertised. -=== Interactions with link:{extensions}VK_EXT_shader_object[VK_EXT_shader_object] +=== Interactions with xref:{refpages}VK_EXT_shader_object.html[VK_EXT_shader_object] -If link:{extensions}VK_EXT_shader_object[VK_EXT_shader_object] is enabled, `vkCmdSetRenderingAttachmentLocationsKHR` and `vkCmdSetRenderingInputAttachmentIndicesKHR` are the only way to set the remapping state; the respective structures do not need to be chained to shader object creation or match any static state. +If xref:{refpages}VK_EXT_shader_object.html[VK_EXT_shader_object] is enabled, `vkCmdSetRenderingAttachmentLocationsKHR` and `vkCmdSetRenderingInputAttachmentIndicesKHR` are the only way to set the remapping state; the respective structures do not need to be chained to shader object creation or match any static state. -=== Interactions with link:{extensions}VK_EXT_rasterization_order_attachment_access[VK_EXT_rasterization_order_attachment_access] +=== Interactions with xref:{refpages}VK_EXT_rasterization_order_attachment_access.html[VK_EXT_rasterization_order_attachment_access] -If link:{extensions}VK_EXT_rasterization_order_attachment_access[VK_EXT_rasterization_order_attachment_access] is enabled, the pipeline depth/stencil state and color blend state bits can be used with dynamic rendering, with the same effect on input attachment reads as when used with render pass objects. +If xref:{refpages}VK_EXT_rasterization_order_attachment_access.html[VK_EXT_rasterization_order_attachment_access] is enabled, the pipeline depth/stencil state and color blend state bits can be used with dynamic rendering, with the same effect on input attachment reads as when used with render pass objects. Specifically, this allows local reads from input attachments to read values from previous fragments at overlapping locations within the same render pass (even the same draw), without a barrier. This interaction does not enable local reads between non-attachment resources without a barrier. @@ -281,7 +281,7 @@ To make this work, something as simple as a decoration on a color output or inpu === Should this extension advertise local reads between fragments in the same draw call? This is not efficient or easily implementable in all cases for many vendors. -For implementations that do support it, that feature is provided as an interaction with link:{extensions}VK_EXT_rasterization_order_attachment_access.adoc[VK_EXT_rasterization_order_attachment_access]. +For implementations that do support it, that feature is provided as an interaction with xref:{refpages}VK_EXT_rasterization_order_attachment_access.html[VK_EXT_rasterization_order_attachment_access]. === Should this extension allow applications to access local data from resources other than attachments? diff --git a/proposals/VK_KHR_fragment_shader_barycentric.adoc b/proposals/VK_KHR_fragment_shader_barycentric.adoc index 18bfc1b38..e87df20a4 100644 --- a/proposals/VK_KHR_fragment_shader_barycentric.adoc +++ b/proposals/VK_KHR_fragment_shader_barycentric.adoc @@ -5,7 +5,7 @@ = VK_KHR_fragment_shader_barycentric :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This document details the VK_KHR_fragment_shader_barcentric extension, which adds a cross-vendor way to access barycentric coordinates in a fragment shader. @@ -95,7 +95,7 @@ typedef struct VkPhysicalDeviceFragmentShaderBarycentricPropertiesKHR { ---- The `triStripVertexOrderIndependentOfProvokingVertex` property indicates that the implementation does not change its vertex numbering for triangle strip primitives -when the link:{docs}chapters/vertexpostproc.html#VkProvokingVertexModeEXT[provoking vertex mode] is `VK_PROVOKING_VERTEX_MODE_LAST_VERTEX_EXT`. +when the xref:{refpages}VkProvokingVertexModeEXT.html[provoking vertex mode] is `VK_PROVOKING_VERTEX_MODE_LAST_VERTEX_EXT`. === GLSL mapping diff --git a/proposals/VK_KHR_fragment_shading_rate.adoc b/proposals/VK_KHR_fragment_shading_rate.adoc index 950069878..bbc4b178a 100644 --- a/proposals/VK_KHR_fragment_shading_rate.adoc +++ b/proposals/VK_KHR_fragment_shading_rate.adoc @@ -5,7 +5,7 @@ = VK_KHR_fragment_shading_rate :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This extension adds the ability to change the rate at which fragments are shaded. Rather than the usual single fragment invocation for each pixel covered by a primitive, multiple pixels can be shaded by a single fragment shader invocation. @@ -42,7 +42,7 @@ Note though that enabling sample shading will effectively disable the fragment s === Per-Draw state -This state can be set per-draw as part of the pipeline by chaining the following structure to link:{docs}chapters/pipelines.html#VkGraphicsPipelineCreateInfo[VkGraphicsPipelineCreateInfo]: +This state can be set per-draw as part of the pipeline by chaining the following structure to xref:{refpages}VkGraphicsPipelineCreateInfo.html[VkGraphicsPipelineCreateInfo]: [source,c] ---- @@ -64,7 +64,7 @@ void vkCmdSetFragmentShadingRateKHR( const VkFragmentShadingRateCombinerOpKHR combinerOps[2]); ---- -In each case, the link:{docs}chapters/fundamentals.html#VkExtent2D[VkExtent2D] sets the base fragment size in the x and y dimensions for all fragments generated by draw calls using this state. +In each case, the xref:{refpages}VkExtent2D.html[VkExtent2D] sets the base fragment size in the x and y dimensions for all fragments generated by draw calls using this state. As there are three rates at which the state can be set, rather than having these only set one at a time, applications can have all three rates set and define combiner operations to dictate how the final result is calculated. This allows applications to e.g. have a per-screen-region rate while also marking some triangles or objects as lower detail than the base rate. @@ -151,7 +151,7 @@ Uses the *PrimitiveShadingRateKHR* or *ShadingRateKHR* Builtins. | *Shader* The per-region state can be set through an image where a pixel in that image corresponds to a given region in the render. Using the same flag values as the per-triangle rate, the value of that pixel determines the per-region rate for the corresponding region. -This image can be set per-subpass by chaining the following structure to link:{docs}chapters/renderpass.html#VkSubpassDescription2[VkSubpassDescription2]: +This image can be set per-subpass by chaining the following structure to xref:{refpages}VkSubpassDescription2.html[VkSubpassDescription2]: [source,c] ---- @@ -232,7 +232,7 @@ This allows applications to ship one algorithm while still ensuring valid behavi * `maxFragmentShadingRateCoverageSamples` determines the maximum total coverage samples for a fragment as a product of the fragment shading rate in each dimension and the multisample rate. * `maxFragmentShadingRateRasterizationSamples` determines the maximum multisample rate (`rasterizationSamples`) when using a fragment shading rate. * `fragmentShadingRateWithShaderDepthStencilWrites` determines if depth/stencil export from a shader can be used with fragment shading rate. -* `fragmentShadingRateWithSampleMask` determines if the `pSampleMask` member of link:{docs}chapters/primsrast.html#VkPipelineMultisampleStateCreateInfo[VkPipelineMultisampleStateCreateInfo] can have any valid bits equal to 0 when using with fragment shading rate. +* `fragmentShadingRateWithSampleMask` determines if the `pSampleMask` member of xref:{refpages}VkPipelineMultisampleStateCreateInfo.html[VkPipelineMultisampleStateCreateInfo] can have any valid bits equal to 0 when using with fragment shading rate. * `fragmentShadingRateWithShaderSampleMask` determines if the sample mask (input or output) can be used in a shader with fragment shading rate. * `fragmentShadingRateWithConservativeRasterization` determines if conservative rasterization can be used with fragment shading rate. * `fragmentShadingRateWithFragmentShaderInterlock` determines if fragment shader interlock can be used with fragment shading rate. diff --git a/proposals/VK_KHR_internally_synchronized_queues.adoc b/proposals/VK_KHR_internally_synchronized_queues.adoc index cf2baaa84..7021f7564 100644 --- a/proposals/VK_KHR_internally_synchronized_queues.adoc +++ b/proposals/VK_KHR_internally_synchronized_queues.adoc @@ -5,7 +5,7 @@ = VK_KHR_internally_synchronized_queues :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This extension allows the application to opt in for queues to be internally synchronized, eliminating the need to externally synchronize operations performed on the corresponding queues. diff --git a/proposals/VK_KHR_load_store_op_none.adoc b/proposals/VK_KHR_load_store_op_none.adoc index fa29c3316..0c33848ce 100644 --- a/proposals/VK_KHR_load_store_op_none.adoc +++ b/proposals/VK_KHR_load_store_op_none.adoc @@ -5,7 +5,7 @@ = VK_KHR_load_store_op_none :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This document describes useful load and store ops that did not exist in Vulkan 1.0. diff --git a/proposals/VK_KHR_maintenance10.adoc b/proposals/VK_KHR_maintenance10.adoc index f3598ea52..953c18944 100644 --- a/proposals/VK_KHR_maintenance10.adoc +++ b/proposals/VK_KHR_maintenance10.adoc @@ -4,7 +4,7 @@ = VK_KHR_maintenance10 :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This proposal details and addresses the issues solved by the diff --git a/proposals/VK_KHR_maintenance5.adoc b/proposals/VK_KHR_maintenance5.adoc index 6a93e7800..5786ceb76 100644 --- a/proposals/VK_KHR_maintenance5.adoc +++ b/proposals/VK_KHR_maintenance5.adoc @@ -5,7 +5,7 @@ = VK_KHR_maintenance5 :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This proposal details and addresses the issues solved by the `VK_KHR_maintenance5` extension. @@ -128,7 +128,7 @@ Solutions here should have the following properties: creation * Be as simple as possible -link:{extensions}VK_EXT_graphics_pipeline_library[VK_EXT_graphics_pipeline_library] +xref:{refpages}VK_EXT_graphics_pipeline_library.html[VK_EXT_graphics_pipeline_library] already introduced a simple way to do this, which is adopted by this extension. @@ -282,11 +282,11 @@ A new `earlyFragmentSampleMaskTestBeforeSampleCounting` property is added. === Deprecating Shader Modules Shader modules are deprecated by allowing -link:{docs}chapters/shaders.html#VkShaderModuleCreateInfo[VkShaderModuleCreateInfo] to be +xref:{refpages}VkShaderModuleCreateInfo.html[VkShaderModuleCreateInfo] to be chained to -link:{docs}chapters/pipelines.html#VkPipelineShaderStageCreateInfo[VkPipelineShaderStageCreateInfo], -and allowing the link:{docs}chapters/shaders.html#VkShaderModule[VkShaderModule] to be -link:{docs}appendices/boilerplate.html#VK_NULL_HANDLE[VK_NULL_HANDLE] in this case. +xref:{refpages}VkPipelineShaderStageCreateInfo.html[VkPipelineShaderStageCreateInfo], +and allowing the xref:{refpages}VkShaderModule.html[VkShaderModule] to be +xref:{refpages}VK_NULL_HANDLE.html[VK_NULL_HANDLE] in this case. Shader modules are not being removed, but it is recommended to not use them in order to save memory and avoid unnecessary copies. For example, where previously an application would have to create a shader diff --git a/proposals/VK_KHR_maintenance6.adoc b/proposals/VK_KHR_maintenance6.adoc index a77ccbd0e..6f6ed960d 100644 --- a/proposals/VK_KHR_maintenance6.adoc +++ b/proposals/VK_KHR_maintenance6.adoc @@ -4,7 +4,7 @@ = VK_KHR_maintenance6 :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This proposal details and addresses the issues solved by the `VK_KHR_maintenance6` extension. diff --git a/proposals/VK_KHR_maintenance7.adoc b/proposals/VK_KHR_maintenance7.adoc index 52eb55da2..a1181a086 100644 --- a/proposals/VK_KHR_maintenance7.adoc +++ b/proposals/VK_KHR_maintenance7.adoc @@ -4,7 +4,7 @@ = VK_KHR_maintenance7 :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This proposal details and addresses the issues solved by the `VK_KHR_maintenance7` extension. @@ -73,7 +73,7 @@ result in writes to both aspects. === Query Properties of Underlying Layered Implementations -A new set of structures are included, accessible through link:{docs}chapters/limits.html#VkPhysicalDeviceLayeredApiPropertiesListKHR[VkPhysicalDeviceLayeredApiPropertiesListKHR] when chained to link:{docs}chapters/devsandqueues.html#VkPhysicalDeviceProperties2[VkPhysicalDeviceProperties2]. +A new set of structures are included, accessible through xref:{refpages}VkPhysicalDeviceLayeredApiPropertiesListKHR.html[VkPhysicalDeviceLayeredApiPropertiesListKHR] when chained to xref:{refpages}VkPhysicalDeviceProperties2.html[VkPhysicalDeviceProperties2]. === Mixed Inline and Secondary Command Buffer Recording in Render Passes @@ -90,7 +90,7 @@ At the basic level, the first hurdle is allowing applications to specify fragmen The second challenge is ensuring that implementations all return the expected values. This could be achieved by using new language to describe the specifics of these lookups, but notably image reads with robust access already have the desired behavior. -As such, this proposal retools fragment shading rate attachment reads as general image reads, and guarantees the values match DirectX 12's guarantees when the link:{docs}chapters/features.html#VkPhysicalDeviceRobustness2FeaturesEXT[VkPhysicalDeviceRobustness2FeaturesEXT::robustImageAccess2] feature is enabled. +As such, this proposal retools fragment shading rate attachment reads as general image reads, and guarantees the values match DirectX 12's guarantees when the xref:{refpages}VkPhysicalDeviceRobustness2FeaturesEXT.html[VkPhysicalDeviceRobustness2FeaturesEXT::robustImageAccess2] feature is enabled. === Determine 32-Bit Query Overflow Behavior @@ -141,7 +141,7 @@ typedef struct VkPhysicalDeviceMaintenance7PropertiesKHR { * `robustFragmentShadingRateAttachmentAccess` indicates whether a fragment shading rate attachment created with - link:{docs}chapters/resources.html#VkImageSubresourceRange[VkImageSubresourceRange]::`baseMipLevel` + xref:{refpages}VkImageSubresourceRange.html[VkImageSubresourceRange]::`baseMipLevel` equal to 0 can have a size that is too small to cover a specified render area. * `separateDepthStencilAttachmentAccess` indicates whether diff --git a/proposals/VK_KHR_maintenance8.adoc b/proposals/VK_KHR_maintenance8.adoc index a06425718..74cfd9384 100644 --- a/proposals/VK_KHR_maintenance8.adoc +++ b/proposals/VK_KHR_maintenance8.adoc @@ -4,7 +4,7 @@ = VK_KHR_maintenance8 :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This proposal details and addresses the issues solved by the `VK_KHR_maintenance8` extension. @@ -63,7 +63,7 @@ are now meaningful when performing a queue family ownership transfer: VK_DEPENDENCY_QUEUE_FAMILY_OWNERSHIP_TRANSFER_USE_ALL_STAGES_BIT_KHR = 0xTBD, ---- -When `VK_DEPENDENCY_QUEUE_FAMILY_OWNERSHIP_TRANSFER_USE_ALL_STAGES_BIT_KHR` is included in link:{docs}chapters/synchronization.html#VkDependencyFlags[VkDependencyFlags], buffer and image memory barriers that specify queue family ownership transfers will make use of both synchronization scopes. +When `VK_DEPENDENCY_QUEUE_FAMILY_OWNERSHIP_TRANSFER_USE_ALL_STAGES_BIT_KHR` is included in xref:{refpages}VkDependencyFlags.html[VkDependencyFlags], buffer and image memory barriers that specify queue family ownership transfers will make use of both synchronization scopes. Without this new flag, the operations on each queue can only be synchronized by using `VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT`, which can cause a full stall of the device on many implementations. When this flag is specified, these operations can instead be synchronized using the stage flags just as any other synchronization operation would be. diff --git a/proposals/VK_KHR_maintenance9.adoc b/proposals/VK_KHR_maintenance9.adoc index b0f224869..46517f1cd 100644 --- a/proposals/VK_KHR_maintenance9.adoc +++ b/proposals/VK_KHR_maintenance9.adoc @@ -4,7 +4,7 @@ = VK_KHR_maintenance9 :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This proposal details and addresses the issues solved by the `VK_KHR_maintenance9` extension. diff --git a/proposals/VK_KHR_map_memory2.adoc b/proposals/VK_KHR_map_memory2.adoc index ec3bf3cdc..0b478699c 100644 --- a/proposals/VK_KHR_map_memory2.adoc +++ b/proposals/VK_KHR_map_memory2.adoc @@ -5,7 +5,7 @@ = VK_KHR_map_memory2 :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This document proposes adding extensible version of `vkMapMemory()` and diff --git a/proposals/VK_KHR_pipeline_binary.adoc b/proposals/VK_KHR_pipeline_binary.adoc index 53b0fb519..256038bc4 100644 --- a/proposals/VK_KHR_pipeline_binary.adoc +++ b/proposals/VK_KHR_pipeline_binary.adoc @@ -5,7 +5,7 @@ = VK_KHR_pipeline_binary :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This extension proposes a method to directly retrieve binary data associated with individual pipelines, bypassing the pipeline caching mechanism, and enabling applications to manage caching themselves. @@ -176,21 +176,21 @@ such as extensions and features being enabled, or even enabled layers in some ca Only one of `pipeline`, `pKeysAndDataInfo`, and `pPipelineCreateInfo` can be used at once. -A new link:{docs}chapters/fundamentals.html#VkResult[VkResult] value is added so that `vkCreatePipelineBinariesKHR` can indicate that an implementation supporting `pipelineBinaryInternalCache` <> does not have a binary in its internal cache: +A new xref:{refpages}VkResult.html[VkResult] value is added so that `vkCreatePipelineBinariesKHR` can indicate that an implementation supporting `pipelineBinaryInternalCache` <> does not have a binary in its internal cache: [source,c] ---- VK_PIPELINE_BINARY_MISSING_KHR = 1000483000 ---- -A new link:{docs}chapters/fundamentals.html#VkResult[VkResult] value is added so that `vkGetPipelineBinaryDataKHR` can indicate that the application has not provided enough storage to write pipeline binary data into: +A new xref:{refpages}VkResult.html[VkResult] value is added so that `vkGetPipelineBinaryDataKHR` can indicate that the application has not provided enough storage to write pipeline binary data into: [source,c] ---- VK_ERROR_NOT_ENOUGH_SPACE_KHR = -1000483000 ---- -A new link:{docs}chapters/pipelines.html#VkPipelineCreateFlagBits2KHR[VkPipelineCreateFlagBits2KHR] value is required to be able to obtain binary data from a pipeline object via this extension after creation: +A new xref:{refpages}VkPipelineCreateFlagBits2KHR.html[VkPipelineCreateFlagBits2KHR] value is required to be able to obtain binary data from a pipeline object via this extension after creation: [source,c] ---- diff --git a/proposals/VK_KHR_present_id2.adoc b/proposals/VK_KHR_present_id2.adoc index 78443ec6e..bd51c4a1e 100644 --- a/proposals/VK_KHR_present_id2.adoc +++ b/proposals/VK_KHR_present_id2.adoc @@ -5,7 +5,7 @@ = VK_KHR_present_id2 :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This document details the proposed design for a replacement for the diff --git a/proposals/VK_KHR_present_mode_fifo_latest_ready.adoc b/proposals/VK_KHR_present_mode_fifo_latest_ready.adoc index 46d04c748..9aa6fe83b 100644 --- a/proposals/VK_KHR_present_mode_fifo_latest_ready.adoc +++ b/proposals/VK_KHR_present_mode_fifo_latest_ready.adoc @@ -5,7 +5,7 @@ = VK_KHR_present_mode_fifo_latest_ready :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: // Required so images render in github ifndef::images[:images: ../images] @@ -15,7 +15,7 @@ which allows the presentation engine to dequeue multiple present requests during vblank, in FIFO order, until encountering a request that is not ready. This extension is a promotion of -link:VK_EXT_present_mode_fifo_latest_ready.adoc[`VK_EXT_present_mode_fifo_latest_ready`] to `KHR`. +xref:{refpages}VK_EXT_present_mode_fifo_latest_ready.html[`VK_EXT_present_mode_fifo_latest_ready`] to `KHR`. Its API and behavior is identical to the original `EXT` extension. For more details, please refer to the original extension's -link:VK_EXT_present_mode_fifo_latest_ready.adoc[proposal]. +xref:{refpages}VK_EXT_present_mode_fifo_latest_ready.html[proposal]. diff --git a/proposals/VK_KHR_present_wait2.adoc b/proposals/VK_KHR_present_wait2.adoc index d0ff2c509..c8f557fd0 100644 --- a/proposals/VK_KHR_present_wait2.adoc +++ b/proposals/VK_KHR_present_wait2.adoc @@ -5,7 +5,7 @@ = VK_KHR_present_wait2 :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This document details the proposed design for a replacement for the diff --git a/proposals/VK_KHR_ray_tracing_position_fetch.adoc b/proposals/VK_KHR_ray_tracing_position_fetch.adoc index b41653438..761e7332c 100644 --- a/proposals/VK_KHR_ray_tracing_position_fetch.adoc +++ b/proposals/VK_KHR_ray_tracing_position_fetch.adoc @@ -5,7 +5,7 @@ = VK_KHR_ray_tracing_position_fetch :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This document details the VK_KHR_ray_tracing_position_fetch extension which exposes the ability to fetch vertex positions from an acceleration structure hit when ray tracing. diff --git a/proposals/VK_KHR_shader_abort.adoc b/proposals/VK_KHR_shader_abort.adoc index 25e8e8cff..7ca08b7cf 100644 --- a/proposals/VK_KHR_shader_abort.adoc +++ b/proposals/VK_KHR_shader_abort.adoc @@ -5,9 +5,9 @@ = VK_KHR_shader_abort :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: -:VK_KHR_device_fault: link:{extensions}VK_KHR_device_fault[VK_KHR_device_fault] +:VK_KHR_device_fault: xref:{refpages}VK_KHR_device_fault.html[VK_KHR_device_fault] // Required so images render in github ifndef::images[:images: ../images] @@ -58,14 +58,14 @@ This instruction must be the last instruction in a block. | 3 | 5121 | Message Type | Message |===== -Execution of `OpAbortKHR` will trigger device loss in the API within finite time, making the data in _Message_ available via link:{docs}chapters/debugging.html#vkGetDeviceFaultDebugInfoKHR[vkGetDeviceFaultDebugInfoKHR] for further analysis. +Execution of `OpAbortKHR` will trigger device loss in the API within finite time, making the data in _Message_ available via xref:{refpages}vkGetDeviceFaultDebugInfoKHR.html[vkGetDeviceFaultDebugInfoKHR] for further analysis. This instruction is gated behind a new capability: [cols="1,8,8",width="100%"] |===== 2+|*Capability* | *Implicitly Declares* -| 5120 | *AbortKHR* | +| 5120 | *AbortKHR* | |===== @@ -105,7 +105,7 @@ typedef struct VkPhysicalDeviceShaderAbortPropertiesKHR { ==== Message Retrieval via {VK_KHR_device_fault} -If {VK_KHR_device_fault} is supported and enabled, new structures to retrieve shader abort messages can be chained into link:{docs}chapters/debugging.html#VkDeviceFaultDebugInfoKHR[VkDeviceFaultDebugInfoKHR] are added: +If {VK_KHR_device_fault} is supported and enabled, new structures to retrieve shader abort messages can be chained into xref:{refpages}VkDeviceFaultDebugInfoKHR.html[VkDeviceFaultDebugInfoKHR] are added: [source,c] ---- @@ -117,7 +117,7 @@ typedef struct VkDeviceFaultShaderAbortMessageInfoKHR { } VkDeviceFaultShaderAbortMessageInfoKHR; ---- -`VkDeviceFaultShaderAbortMessageInfoKHR` can be included in the `pNext` chain of link:{docs}chapters/debugging.html#VkDeviceFaultDebugInfoKHR[VkDeviceFaultDebugInfoKHR] to retrieve the total size of message data returned by the implementation and the actual the messages returned by `OpAbortKHR` instructions in shaders. +`VkDeviceFaultShaderAbortMessageInfoKHR` can be included in the `pNext` chain of xref:{refpages}VkDeviceFaultDebugInfoKHR.html[VkDeviceFaultDebugInfoKHR] to retrieve the total size of message data returned by the implementation and the actual the messages returned by `OpAbortKHR` instructions in shaders. As an implementation may not terminate all shader invocations immediately, it is possible for multiple invocations to call `OpAbortKHR` and return messages to the API. As such, `pMessageData` can contain multiple messages in a size / message pair. @@ -203,10 +203,10 @@ while ((((intptr_t)pMessageData + messageDataSize) - (intptr_t)pMessageDataCurre message.size = *(uint64_t*)pMessageDataCurrent; pMessageDataCurrent += 4; - + message.pData = pMessageDataCurrent; pMessageDataCurrent += message.size; - + myCustomPrintF(message); } ---- @@ -256,17 +256,17 @@ if ((vkGetDeviceFaultDebugInfoKHR(device, &debugInfo) == VK_SUCCESS) && (abortMe uint8* pMessageDataCurrent = (uint8_t*)(pMessageData); while ((((intptr_t)pMessageData + messageDataSize) - (intptr_t)pMessageDataCurrent) > 0) { Message message; - + // Get the size of the next message message.size = *(uint64_t*)pMessageDataCurrent; pMessageDataCurrent += 4; - + // Get a pointer to the message data message.pData = pMessageDataCurrent; pMessageDataCurrent += message.size; - + myCustomPrint(message); - + // Align the pointer to 8 bytes for the next message uintptr_t aligned = (uintptr_t)pMessageDataCurrent; if (aligned % 8 !=0) diff --git a/proposals/VK_KHR_shader_bfloat16.adoc b/proposals/VK_KHR_shader_bfloat16.adoc index 54d207ef9..45c54f44e 100644 --- a/proposals/VK_KHR_shader_bfloat16.adoc +++ b/proposals/VK_KHR_shader_bfloat16.adoc @@ -5,7 +5,7 @@ = VK_KHR_shader_bfloat16 :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :spirvspec: https://registry.khronos.org/SPIR-V/specs/unified1/SPIRV.html :sectnums: @@ -98,13 +98,13 @@ typedef struct VkPhysicalDeviceShaderBfloat16FeaturesKHR { * `shaderBFloat16CooperativeMatrix` indicates support for the `BFloat16CooperativeMatrixKHR` capability. `shaderBFloat16Type` must be supported for this extension. -`shaderBFloat16CooperativeMatrix` must be `VK_FALSE` if link:{extensions}VK_KHR_cooperative_matrix[VK_KHR_cooperative_matrix] is not supported. +`shaderBFloat16CooperativeMatrix` must be `VK_FALSE` if xref:{refpages}VK_KHR_cooperative_matrix.html[VK_KHR_cooperative_matrix] is not supported. At least one of `shaderBFloat16DotProduct` and `shaderBFloat16CooperativeMatrix` must be supported. -==== Interactions with link:{extensions}VK_KHR_cooperative_matrix[VK_KHR_cooperative_matrix] +==== Interactions with xref:{refpages}VK_KHR_cooperative_matrix.html[VK_KHR_cooperative_matrix] -A new link:{docs}chapters/shaders.html#VkComponentTypeKHR[VkComponentTypeKHR] is added that can be reported as supported by link:{docs}chapters/shaders.html#vkGetPhysicalDeviceCooperativeMatrixPropertiesKHR[vkGetPhysicalDeviceCooperativeMatrixPropertiesKHR]: +A new xref:{refpages}VkComponentTypeKHR.html[VkComponentTypeKHR] is added that can be reported as supported by xref:{refpages}vkGetPhysicalDeviceCooperativeMatrixPropertiesKHR.html[vkGetPhysicalDeviceCooperativeMatrixPropertiesKHR]: [source,c] ---- @@ -114,7 +114,7 @@ typedef enum VkComponentTypeKHR { } VkComponentTypeKHR; ---- -If `shaderBFloat16CooperativeMatrix` is supported, at least one entry in link:{docs}chapters/shaders.html#vkGetPhysicalDeviceCooperativeMatrixPropertiesKHR[vkGetPhysicalDeviceCooperativeMatrixPropertiesKHR::pProperties] must include this type in all of its `AType`, `BType`, and `CType` members. +If `shaderBFloat16CooperativeMatrix` is supported, at least one entry in xref:{refpages}vkGetPhysicalDeviceCooperativeMatrixPropertiesKHR.html[vkGetPhysicalDeviceCooperativeMatrixPropertiesKHR::pProperties] must include this type in all of its `AType`, `BType`, and `CType` members. == Issues diff --git a/proposals/VK_KHR_shader_constant_data.adoc b/proposals/VK_KHR_shader_constant_data.adoc index bef1961a7..cd220beb3 100644 --- a/proposals/VK_KHR_shader_constant_data.adoc +++ b/proposals/VK_KHR_shader_constant_data.adoc @@ -4,7 +4,7 @@ = VK_KHR_shader_constant_data :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :spirvextensions: https://github.khronos.org/SPIRV-Registry/extensions/ :sectnums: // Required so images render in github @@ -14,11 +14,11 @@ This extension allows applications to specify large constant data arrays in thei == Problem Statement -{spirvextensions}/KHR/SPV_KHR_constant_data.asciidoc[`SPV_KHR_constant_data`] added the capability to specify arrayed data as constants in SPIR-V, to enable the specification of strings as data, or other chunks of data, in a more compact manner than previously available. +{spirvextensions}/KHR/SPV_KHR_constant_data.html[`SPV_KHR_constant_data`] added the capability to specify arrayed data as constants in SPIR-V, to enable the specification of strings as data, or other chunks of data, in a more compact manner than previously available. A detailed problem statement on why this was added to SPIR-V is provided in the `SPV_KHR_constant_data` specification. -Support for this extension is required in Vulkan to add better string support to Vulkan, and particularly for link:{extensions}VK_KHR_shader_abort[VK_KHR_shader_abort]. +Support for this extension is required in Vulkan to add better string support to Vulkan, and particularly for xref:{refpages}VK_KHR_shader_abort.html[VK_KHR_shader_abort]. == Solution Space diff --git a/proposals/VK_KHR_shader_expect_assume.adoc b/proposals/VK_KHR_shader_expect_assume.adoc index cbcaacc3e..896891e35 100644 --- a/proposals/VK_KHR_shader_expect_assume.adoc +++ b/proposals/VK_KHR_shader_expect_assume.adoc @@ -5,7 +5,7 @@ = VK_KHR_shader_expect_assume :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This document proposes adding support for expect/assume SPIR-V instructions diff --git a/proposals/VK_KHR_shader_float_controls2.adoc b/proposals/VK_KHR_shader_float_controls2.adoc index 2035be3b2..98ad303e3 100644 --- a/proposals/VK_KHR_shader_float_controls2.adoc +++ b/proposals/VK_KHR_shader_float_controls2.adoc @@ -5,7 +5,7 @@ = VK_KHR_shader_float_controls2 :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: == Problem Statement diff --git a/proposals/VK_KHR_shader_fma.adoc b/proposals/VK_KHR_shader_fma.adoc index 355435a86..bb17f1a22 100644 --- a/proposals/VK_KHR_shader_fma.adoc +++ b/proposals/VK_KHR_shader_fma.adoc @@ -5,7 +5,7 @@ = VK_KHR_shader_fma :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: == Problem Statement diff --git a/proposals/VK_KHR_shader_integer_dot_product.adoc b/proposals/VK_KHR_shader_integer_dot_product.adoc index 8d6f0057b..2c5ecb144 100644 --- a/proposals/VK_KHR_shader_integer_dot_product.adoc +++ b/proposals/VK_KHR_shader_integer_dot_product.adoc @@ -5,7 +5,7 @@ = VK_KHR_shader_integer_dot_product :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This document proposes adding support for shader integer dot product instructions. diff --git a/proposals/VK_KHR_shader_maximal_reconvergence.adoc b/proposals/VK_KHR_shader_maximal_reconvergence.adoc index c61af8da5..21377583c 100644 --- a/proposals/VK_KHR_shader_maximal_reconvergence.adoc +++ b/proposals/VK_KHR_shader_maximal_reconvergence.adoc @@ -5,7 +5,7 @@ = VK_KHR_shader_maximal_reconvergence :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: == Problem Statement diff --git a/proposals/VK_KHR_shader_quad_control.adoc b/proposals/VK_KHR_shader_quad_control.adoc index 4be21e1f5..6a9b6eb0a 100644 --- a/proposals/VK_KHR_shader_quad_control.adoc +++ b/proposals/VK_KHR_shader_quad_control.adoc @@ -5,7 +5,7 @@ = VK_KHR_shader_quad_control :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This document proposes an extension giving applications better guarantees about the uniformity of sampling and derivative operations in fragment shaders, and provides features to manage these guarantees. @@ -30,7 +30,7 @@ This would need to be repeated for each conditional statement at every step of t If clustered operations are supported, an application could theoretically use link:https://registry.khronos.org/SPIR-V/specs/unified1/SPIRV.html#OpGroupNonUniformBitwiseOr[`OpGroupNonUniformBitwiseOr`] with a cluster size of 4 instead, but helper invocations are not guaranteed to participate in group operations that are not explicitly quad operations, so this would be unreliable. -Helper invocation participation in group operations has historically been ambiguous for the Vulkan spec, but this was fixed in link:{extensions}VK_KHR_shader_maximal_reconvergence[VK_KHR_shader_maximal_reconvergence]. +Helper invocation participation in group operations has historically been ambiguous for the Vulkan spec, but this was fixed in xref:{refpages}VK_KHR_shader_maximal_reconvergence.html[VK_KHR_shader_maximal_reconvergence]. == Solution Space @@ -54,7 +54,7 @@ Any/all operations are not clustered however, so for these, the simplest fix is === Requirements -This extension requires link:{docs}appendices/versions.html#versions-1.1[Vulkan Version 1.1], link:{extensions}VK_KHR_vulkan_memory_model[VK_KHR_vulkan_memory_model], link:{extensions}VK_KHR_shader_maximal_reconvergence[VK_KHR_shader_maximal_reconvergence]. +This extension requires xref:{docs}appendices/versions.html#versions-1.1[Vulkan Version 1.1], xref:{refpages}VK_KHR_vulkan_memory_model.html[VK_KHR_vulkan_memory_model], xref:{refpages}VK_KHR_shader_maximal_reconvergence.html[VK_KHR_shader_maximal_reconvergence]. === API diff --git a/proposals/VK_KHR_shader_relaxed_extended_instruction.adoc b/proposals/VK_KHR_shader_relaxed_extended_instruction.adoc index a3648c74e..5aa5d4408 100644 --- a/proposals/VK_KHR_shader_relaxed_extended_instruction.adoc +++ b/proposals/VK_KHR_shader_relaxed_extended_instruction.adoc @@ -5,7 +5,7 @@ = VK_KHR_shader_relaxed_extended_instruction :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: == Problem Statement diff --git a/proposals/VK_KHR_shader_subgroup_rotate.adoc b/proposals/VK_KHR_shader_subgroup_rotate.adoc index 70d4b38de..7fde69dcd 100644 --- a/proposals/VK_KHR_shader_subgroup_rotate.adoc +++ b/proposals/VK_KHR_shader_subgroup_rotate.adoc @@ -5,7 +5,7 @@ = Subgroup rotation instruction :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: == Problem Statement diff --git a/proposals/VK_KHR_shader_untyped_pointers.adoc b/proposals/VK_KHR_shader_untyped_pointers.adoc index f0dcdb8dc..65987c008 100644 --- a/proposals/VK_KHR_shader_untyped_pointers.adoc +++ b/proposals/VK_KHR_shader_untyped_pointers.adoc @@ -6,7 +6,7 @@ :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: == Problem Statement @@ -228,4 +228,4 @@ generated code is greatly simplified. === Which storage classes should allow untyped pointers? Because data needs a consistent layout among different interpretations, only -explicitly laid out storage classes are supported. \ No newline at end of file +explicitly laid out storage classes are supported. diff --git a/proposals/VK_KHR_surface_maintenance1.adoc b/proposals/VK_KHR_surface_maintenance1.adoc index 516bd0127..0f67736eb 100644 --- a/proposals/VK_KHR_surface_maintenance1.adoc +++ b/proposals/VK_KHR_surface_maintenance1.adoc @@ -5,7 +5,7 @@ = VK_KHR_surface_maintenance1 :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: -This extension is a promotion of link:{docs}/proposals/VK_EXT_surface_maintenance1.adoc[`VK_EXT_surface_maintenance1`] with no functional modifications. +This extension is a promotion of xref:{refpages}VK_EXT_surface_maintenance1.html[VK_EXT_surface_maintenance1] with no functional modifications. diff --git a/proposals/VK_KHR_swapchain_maintenance1.adoc b/proposals/VK_KHR_swapchain_maintenance1.adoc index 43ca358e4..5ed9b763f 100644 --- a/proposals/VK_KHR_swapchain_maintenance1.adoc +++ b/proposals/VK_KHR_swapchain_maintenance1.adoc @@ -5,7 +5,7 @@ = VK_KHR_swapchain_maintenance1 :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: -This extension is a promotion of link:{docs}/proposals/VK_EXT_swapchain_maintenance1.adoc[`VK_EXT_swapchain_maintenance1`] with no functional modifications. +This extension is a promotion of xref:{refpages}VK_EXT_swapchain_maintenance1.html[VK_EXT_swapchain_maintenance1] with no functional modifications. diff --git a/proposals/VK_KHR_unified_image_layouts.adoc b/proposals/VK_KHR_unified_image_layouts.adoc index c358ee1e5..6554a082b 100644 --- a/proposals/VK_KHR_unified_image_layouts.adoc +++ b/proposals/VK_KHR_unified_image_layouts.adoc @@ -5,7 +5,7 @@ = VK_KHR_unified_image_layouts :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This extension significantly simplifies synchronization in Vulkan by removing the need for image layout transitions. @@ -117,7 +117,7 @@ typedef struct VkAttachmentFeedbackLoopInfoEXT { The present engine is an entity external to Vulkan. These layouts were added in Vulkan 1.0 to make images compatible with this entity. -Since then however, `VK_QUEUE_FAMILY_EXTERNAL` and `VK_QUEUE_FAMILY_FOREIGN_EXT` in link:{docs}chapters/synchronization.html#synchronization-queue-transfers[queue family ownership transfers] provided a better mechanism to interact with such external entities. +Since then however, `VK_QUEUE_FAMILY_EXTERNAL` and `VK_QUEUE_FAMILY_FOREIGN_EXT` in xref:{docs}chapters/synchronization.html#synchronization-queue-transfers[queue family ownership transfers] provided a better mechanism to interact with such external entities. This extension does _not_ remove these layouts, and redesigning the API around the interaction with the present engine is deferred to a future extension. === Replacing Vulkan Video Layouts diff --git a/proposals/VK_KHR_vertex_attribute_divisor.adoc b/proposals/VK_KHR_vertex_attribute_divisor.adoc index 4a52eb625..9bea8ce96 100644 --- a/proposals/VK_KHR_vertex_attribute_divisor.adoc +++ b/proposals/VK_KHR_vertex_attribute_divisor.adoc @@ -5,7 +5,7 @@ = VK_KHR_vertex_attribute_divisor :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: Promoted from `VK_EXT_vertex_attribute_divisor`, this extension allows diff --git a/proposals/VK_KHR_video_decode_av1.adoc b/proposals/VK_KHR_video_decode_av1.adoc index b43a4bbd1..761aa7534 100644 --- a/proposals/VK_KHR_video_decode_av1.adoc +++ b/proposals/VK_KHR_video_decode_av1.adoc @@ -5,7 +5,7 @@ = VK_KHR_video_decode_av1 :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This document outlines a proposal to enable performing AV1 video decode operations in Vulkan. diff --git a/proposals/VK_KHR_video_decode_h264.adoc b/proposals/VK_KHR_video_decode_h264.adoc index e1cd30503..75a798ef1 100644 --- a/proposals/VK_KHR_video_decode_h264.adoc +++ b/proposals/VK_KHR_video_decode_h264.adoc @@ -5,7 +5,7 @@ = VK_KHR_video_decode_h264 :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This document outlines a proposal to enable performing H.264/AVC video decode operations in Vulkan. diff --git a/proposals/VK_KHR_video_decode_h265.adoc b/proposals/VK_KHR_video_decode_h265.adoc index 9e9d299c6..215413c82 100644 --- a/proposals/VK_KHR_video_decode_h265.adoc +++ b/proposals/VK_KHR_video_decode_h265.adoc @@ -5,7 +5,7 @@ = VK_KHR_video_decode_h265 :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This document outlines a proposal to enable performing H.265/HEVC video decode operations in Vulkan. diff --git a/proposals/VK_KHR_video_decode_queue.adoc b/proposals/VK_KHR_video_decode_queue.adoc index 057ca24fe..280fc40dc 100644 --- a/proposals/VK_KHR_video_decode_queue.adoc +++ b/proposals/VK_KHR_video_decode_queue.adoc @@ -5,7 +5,7 @@ = VK_KHR_video_decode_queue :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This document outlines a proposal to enable performing video decode operations in Vulkan. diff --git a/proposals/VK_KHR_video_decode_vp9.adoc b/proposals/VK_KHR_video_decode_vp9.adoc index 61cb676fa..38721861b 100644 --- a/proposals/VK_KHR_video_decode_vp9.adoc +++ b/proposals/VK_KHR_video_decode_vp9.adoc @@ -5,7 +5,7 @@ = VK_KHR_video_decode_vp9 :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This document outlines a proposal to enable performing VP9 video decode operations in Vulkan. diff --git a/proposals/VK_KHR_video_encode_av1.adoc b/proposals/VK_KHR_video_encode_av1.adoc index 4b413f6e3..c5cb6d7ae 100644 --- a/proposals/VK_KHR_video_encode_av1.adoc +++ b/proposals/VK_KHR_video_encode_av1.adoc @@ -5,7 +5,7 @@ = VK_KHR_video_encode_av1 :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This document outlines a proposal to enable performing AV1 video encode operations in Vulkan. diff --git a/proposals/VK_KHR_video_encode_h264.adoc b/proposals/VK_KHR_video_encode_h264.adoc index a02fe1f0e..425ae7d62 100644 --- a/proposals/VK_KHR_video_encode_h264.adoc +++ b/proposals/VK_KHR_video_encode_h264.adoc @@ -5,7 +5,7 @@ = VK_KHR_video_encode_h264 :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This document outlines a proposal to enable performing H.264/AVC video encode operations in Vulkan. diff --git a/proposals/VK_KHR_video_encode_h265.adoc b/proposals/VK_KHR_video_encode_h265.adoc index 8ec017f3b..c6afb0d05 100644 --- a/proposals/VK_KHR_video_encode_h265.adoc +++ b/proposals/VK_KHR_video_encode_h265.adoc @@ -5,7 +5,7 @@ = VK_KHR_video_encode_h265 :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This document outlines a proposal to enable performing H.265/HEVC video encode operations in Vulkan. diff --git a/proposals/VK_KHR_video_encode_intra_refresh.adoc b/proposals/VK_KHR_video_encode_intra_refresh.adoc index 82f86a591..c78a16ff6 100644 --- a/proposals/VK_KHR_video_encode_intra_refresh.adoc +++ b/proposals/VK_KHR_video_encode_intra_refresh.adoc @@ -5,7 +5,7 @@ = VK_KHR_video_encode_intra_refresh :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This document outlines a proposal that enables intra refresh in video encode operations. diff --git a/proposals/VK_KHR_video_encode_quantization_map.adoc b/proposals/VK_KHR_video_encode_quantization_map.adoc index d99ea206d..70249c92e 100644 --- a/proposals/VK_KHR_video_encode_quantization_map.adoc +++ b/proposals/VK_KHR_video_encode_quantization_map.adoc @@ -5,7 +5,7 @@ = VK_KHR_video_encode_quantization_map :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This document outlines a proposal that enables fine grained control of codec-specific quantization parameters in video encode operations. diff --git a/proposals/VK_KHR_video_encode_queue.adoc b/proposals/VK_KHR_video_encode_queue.adoc index 2feb9a4d4..f5ac20271 100644 --- a/proposals/VK_KHR_video_encode_queue.adoc +++ b/proposals/VK_KHR_video_encode_queue.adoc @@ -5,7 +5,7 @@ = VK_KHR_video_encode_queue :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This document outlines a proposal to enable performing video encode operations in Vulkan. diff --git a/proposals/VK_KHR_video_maintenance1.adoc b/proposals/VK_KHR_video_maintenance1.adoc index d47d13a7f..65f89f0a9 100644 --- a/proposals/VK_KHR_video_maintenance1.adoc +++ b/proposals/VK_KHR_video_maintenance1.adoc @@ -5,7 +5,7 @@ = VK_KHR_video_maintenance1 :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This proposal details and addresses the issues solved by the `VK_KHR_video_maintenance1` extension. diff --git a/proposals/VK_KHR_video_maintenance2.adoc b/proposals/VK_KHR_video_maintenance2.adoc index 436c8e97c..273cf9c13 100644 --- a/proposals/VK_KHR_video_maintenance2.adoc +++ b/proposals/VK_KHR_video_maintenance2.adoc @@ -5,7 +5,7 @@ = VK_KHR_video_maintenance2 :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This proposal details and addresses the issues solved by the `VK_KHR_video_maintenance2` extension. diff --git a/proposals/VK_KHR_video_queue.adoc b/proposals/VK_KHR_video_queue.adoc index 0e23655a2..83ee97a1e 100644 --- a/proposals/VK_KHR_video_queue.adoc +++ b/proposals/VK_KHR_video_queue.adoc @@ -5,7 +5,7 @@ = VK_KHR_video_queue :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This document outlines a proposal to enable performing video coding operations in Vulkan. diff --git a/proposals/VK_LUNARG_direct_driver_loading.adoc b/proposals/VK_LUNARG_direct_driver_loading.adoc index 121b442b0..2e4f53e86 100644 --- a/proposals/VK_LUNARG_direct_driver_loading.adoc +++ b/proposals/VK_LUNARG_direct_driver_loading.adoc @@ -6,7 +6,7 @@ :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: Adds an extension that allows applications to provide drivers to the loader during @@ -45,9 +45,9 @@ Environment Variables. == Proposal `VK_LUNARG_direct_driver_loading` extends the pNext chain of -link:{docs}chapters/initialization.html#VkInstanceCreateInfo[VkInstanceCreateInfo] to provide a list +xref:{refpages}VkInstanceCreateInfo.html[VkInstanceCreateInfo] to provide a list of structures which contain the information needed by the loader to load the drivers. -This is achieved by providing the driver's link:{docs}chapters/initialization.html#vkGetInstanceProcAddr[vkGetInstanceProcAddr], +This is achieved by providing the driver's xref:{refpages}vkGetInstanceProcAddr.html[vkGetInstanceProcAddr], bypassing the loaders need to use the systems dynamic linker to load the drivers functions. The extension also allows applications to use provided drivers exclusively, so that no diff --git a/proposals/VK_MSFT_layered_driver.adoc b/proposals/VK_MSFT_layered_driver.adoc index f02c20dc1..608be272b 100644 --- a/proposals/VK_MSFT_layered_driver.adoc +++ b/proposals/VK_MSFT_layered_driver.adoc @@ -5,7 +5,7 @@ = VK_MSFT_layered_driver :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This document proposes an extension to allow the loader to understand diff --git a/proposals/VK_NV_cluster_acceleration_structure.adoc b/proposals/VK_NV_cluster_acceleration_structure.adoc index 3435a486c..1cbec16ee 100644 --- a/proposals/VK_NV_cluster_acceleration_structure.adoc +++ b/proposals/VK_NV_cluster_acceleration_structure.adoc @@ -5,7 +5,7 @@ = VK_NV_cluster_acceleration_structure :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This document introduces a new type of bottom level acceleration structure diff --git a/proposals/VK_NV_compute_occupancy_priority.adoc b/proposals/VK_NV_compute_occupancy_priority.adoc index 3c1956354..a4fddefb9 100644 --- a/proposals/VK_NV_compute_occupancy_priority.adoc +++ b/proposals/VK_NV_compute_occupancy_priority.adoc @@ -5,7 +5,7 @@ = VK_NV_compute_occupancy_priority :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: == Problem Statement diff --git a/proposals/VK_NV_cooperative_matrix2.adoc b/proposals/VK_NV_cooperative_matrix2.adoc index 2cac3ce3a..c593f02ef 100644 --- a/proposals/VK_NV_cooperative_matrix2.adoc +++ b/proposals/VK_NV_cooperative_matrix2.adoc @@ -5,7 +5,7 @@ = VK_NV_cooperative_matrix2 :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This document proposes extending support for cooperative matrices to make them diff --git a/proposals/VK_NV_cooperative_vector.adoc b/proposals/VK_NV_cooperative_vector.adoc index bdf07e9b7..fcfb79550 100644 --- a/proposals/VK_NV_cooperative_vector.adoc +++ b/proposals/VK_NV_cooperative_vector.adoc @@ -5,7 +5,7 @@ = VK_NV_cooperative_vector :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: // Required so images render in github ifndef::images[:images: ../images] diff --git a/proposals/VK_NV_display_stereo.adoc b/proposals/VK_NV_display_stereo.adoc index 2efce8e40..0ed9ab293 100644 --- a/proposals/VK_NV_display_stereo.adoc +++ b/proposals/VK_NV_display_stereo.adoc @@ -5,7 +5,7 @@ = VK_NV_display_stereo :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This document proposes a new extension to configure stereo rendering on displays. diff --git a/proposals/VK_NV_external_compute_queue.adoc b/proposals/VK_NV_external_compute_queue.adoc index b1924b78f..42d030d43 100644 --- a/proposals/VK_NV_external_compute_queue.adoc +++ b/proposals/VK_NV_external_compute_queue.adoc @@ -5,7 +5,7 @@ = VK_NV_external_compute_queue :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: == Problem Statement diff --git a/proposals/VK_NV_partitioned_acceleration_structure.adoc b/proposals/VK_NV_partitioned_acceleration_structure.adoc index 9c9ae6460..ec74f4963 100644 --- a/proposals/VK_NV_partitioned_acceleration_structure.adoc +++ b/proposals/VK_NV_partitioned_acceleration_structure.adoc @@ -5,7 +5,7 @@ = VK_NV_partitioned_acceleration_structure :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This document proposes the addition of Partitioned Top Level Acceleration diff --git a/proposals/VK_NV_push_constant_bank.adoc b/proposals/VK_NV_push_constant_bank.adoc index 58c5fb095..617b14387 100644 --- a/proposals/VK_NV_push_constant_bank.adoc +++ b/proposals/VK_NV_push_constant_bank.adoc @@ -5,7 +5,7 @@ = VK_NV_push_constant_bank Extension Proposal :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: // Required so images render in github ifndef::images[:images: ../images] @@ -141,15 +141,15 @@ vkGetPhysicalDeviceProperties2(physicalDevice, &properties2); if (features.pushConstantBank) { // Ensure the requested bank is within the supported range for graphics assert(2 < properties.maxGraphicsPushConstantBanks); - + // For compute shaders, check compute bank limits assert(2 < properties.maxComputePushConstantBanks); - + // Configure push constant bank for descriptor set mapping VkPushConstantBankInfoNV bankInfo = {}; bankInfo.sType = VK_STRUCTURE_TYPE_PUSH_CONSTANT_BANK_INFO_NV; bankInfo.bank = 2; - + // Use in descriptor set mapping VkDescriptorSetAndBindingMappingEXT mapping = {}; mapping.sType = VK_STRUCTURE_TYPE_DESCRIPTOR_SET_AND_BINDING_MAPPING_EXT; diff --git a/proposals/VK_NV_ray_tracing_linear_swept_spheres.adoc b/proposals/VK_NV_ray_tracing_linear_swept_spheres.adoc index c29d8cd2a..8148aeebf 100644 --- a/proposals/VK_NV_ray_tracing_linear_swept_spheres.adoc +++ b/proposals/VK_NV_ray_tracing_linear_swept_spheres.adoc @@ -5,7 +5,7 @@ = VK_NV_ray_tracing_linear_swept_spheres :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This document outlines the addition of two primitives for ray tracing: a diff --git a/proposals/VK_NV_ray_tracing_validation.adoc b/proposals/VK_NV_ray_tracing_validation.adoc index 452f566ae..3bd2a0670 100644 --- a/proposals/VK_NV_ray_tracing_validation.adoc +++ b/proposals/VK_NV_ray_tracing_validation.adoc @@ -5,7 +5,7 @@ = VK_NV_ray_tracing_validation :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This document details the VK_NV_ray_tracing_validation extension which adds @@ -30,9 +30,9 @@ debugging or logging systems. == Proposal -Implementations may expose the link:{extensions}VK_NV_ray_tracing_validation[VK_NV_ray_tracing_validation] extension +Implementations may expose the xref:{refpages}VK_NV_ray_tracing_validation.html[VK_NV_ray_tracing_validation] extension and the -link:{docs}chapters/features.html#VkPhysicalDeviceRayTracingValidationFeaturesNV[VkPhysicalDeviceRayTracingValidationFeaturesNV]::`rayTracingValidation` +xref:{refpages}VkPhysicalDeviceRayTracingValidationFeaturesNV.html[VkPhysicalDeviceRayTracingValidationFeaturesNV]::`rayTracingValidation` feature which allows applications to enable ray tracing validation. == Issues diff --git a/proposals/VK_QCOM_cooperative_matrix_conversion.adoc b/proposals/VK_QCOM_cooperative_matrix_conversion.adoc index 92885374a..892077058 100644 --- a/proposals/VK_QCOM_cooperative_matrix_conversion.adoc +++ b/proposals/VK_QCOM_cooperative_matrix_conversion.adoc @@ -5,12 +5,12 @@ # VK_QCOM_cooperative_matrix_conversion :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: This document proposes a new extension that adds additional shader instructions for -link:{extensions}VK_KHR_cooperative_matrix.html[VK_KHR_cooperative_matrix]. +xref:{refpages}VK_KHR_cooperative_matrix.html[VK_KHR_cooperative_matrix]. ## Problem Statement @@ -347,7 +347,7 @@ for (uint stepN = 0; stepN < TOTAL_N; stepN += TILE_N64) coopmat matC; float16_t vecAh_block[32], vecAh[TILE_K16], vecBh[TILE_K16]; - for (uint step = 0; step < TOTAL_K; step += TILE_K16) + for (uint step = 0; step < TOTAL_K; step += TILE_K16) { for (int k=0; k> that describe the active tile's extent in framebuffer coordinates. - * link:{docs}chapters/renderpass.html#renderpass-tile-shading-aprons[Tile aprons] can be enabled and pixels in the apron + * xref:{docs}chapters/renderpass.html#renderpass-tile-shading-aprons[Tile aprons] can be enabled and pixels in the apron region can be accessed by the fragment shader. * A new state command is added that enables/disables - link:{docs}chapters/renderpass.html#renderpass-per-tile-execution-model[per-tile execution model]. + xref:{docs}chapters/renderpass.html#renderpass-per-tile-execution-model[per-tile execution model]. When this execution model is enabled: ** `VkCmdDispatch*` commands can be recorded in a render pass instance. ** Recorded draw and dispatch commands will be invoked multiple times; each recorded @@ -110,8 +110,8 @@ enabled for a render pass instance, these are the highlights of the new function extent is exposed in the shader via <> and in the API via `VK_QCOM_tile_properties`. ** Compute shaders have all the same functionality described above for fragment shaders. - This includes load/store/sample of link:{docs}chapters/renderpass.html#renderpass-tile-shading-attachment-access[tile image attachments], - <>, and link:{docs}chapters/renderpass.html#renderpass-tile-shading-aprons[tile aprons]. + This includes load/store/sample of xref:{docs}chapters/renderpass.html#renderpass-tile-shading-attachment-access[tile image attachments], + <>, and xref:{docs}chapters/renderpass.html#renderpass-tile-shading-aprons[tile aprons]. Vulkan tile shading will empower applications to leverage tile memory by injecting per-tile commands into the GPU's existing TBDR geometry pipeline, allowing compute to @@ -144,7 +144,7 @@ typedef struct VkRenderPassTileShadingCreateInfoQCOM { ---- `tileApronSize` specifies the width and height of the -link:{docs}chapters/renderpass.html#renderpass-tile-shading-aprons[tile apron]. +xref:{docs}chapters/renderpass.html#renderpass-tile-shading-aprons[tile apron]. If tile apron is not used, this should be set to 0. When tile shading is enabled for a render pass, the following @@ -155,8 +155,8 @@ features become available to shaders within that render pass: === Per-tile execution mode -Within a render pass that link:{docs}chapters/renderpass.html#renderpass-tile-shading[enables tile shading], -the link:{docs}chapters/renderpass.html#renderpass-per-tile-execution-model[per-tile execution mode] +Within a render pass that xref:{docs}chapters/renderpass.html#renderpass-tile-shading[enables tile shading], +the xref:{docs}chapters/renderpass.html#renderpass-per-tile-execution-model[per-tile execution mode] can be enabled or disabled: [source,c] @@ -195,7 +195,7 @@ These per-tile dispatches can use the functionality described in <>. When _per-tile execution mode_ is enabled, the -link:{docs}chapters/renderpass.html#renderpass-tile-shading-command-restrictions[Per-Tile Command Restrictions] apply. +xref:{docs}chapters/renderpass.html#renderpass-tile-shading-command-restrictions[Per-Tile Command Restrictions] apply. === Secondary Command Buffers @@ -247,7 +247,7 @@ operations are described in the <>. === Per-Tile Command Restrictions -When link:{docs}chapters/renderpass.html#renderpass-per-tile-execution-model[per-tile execution mode] +When xref:{docs}chapters/renderpass.html#renderpass-per-tile-execution-model[per-tile execution mode] is enabled within a render pass instance, the set of commands that can be recorded is largely unchanged. This section documents several exceptions. Due to the continuously evolving API, this may not be a complete list of exceptions. @@ -264,7 +264,7 @@ Where _per-tile execution model_ is enabled the following are disallowed: * Some synchronization commands are not allowed: `vkCmdWaitEvents2`, `vkCmdWaitEvents`. * The following action command is not allowed: `vkCmdClearAttachments` * Access of an attachment with layout `VK_IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL` - as provided by link:{extensions}VK_EXT_attachment_feedback_loop_layout[VK_EXT_attachment_feedback_loop_layout]. + as provided by xref:{refpages}VK_EXT_attachment_feedback_loop_layout.html[VK_EXT_attachment_feedback_loop_layout]. * Any commands that would cause an invocation of the tessellation, geometry, ray tracing, or mesh shading shader stages. @@ -277,7 +277,7 @@ Other tile shading restrictions: to a value other than `VK_NULL`. * A render pass that enables tile shading must not render to Android Hardware Buffers with external formats as provided by - link:{extensions}VK_ANDROID_external_format_resolve[VK_ANDROID_external_format_resolve]. + xref:{refpages}VK_ANDROID_external_format_resolve.html[VK_ANDROID_external_format_resolve]. === Tile Apron @@ -318,7 +318,7 @@ having greater impact. Aprons should be enabled judiciously. === Area-based dispatch The following command executes a tile-sized dispatch, where -link:{extensions}VK_QCOM_tile_properties[VK_QCOM_tile_properties] +xref:{refpages}VK_QCOM_tile_properties.html[VK_QCOM_tile_properties] `VkTilePropertiesQCOM::tileSize` or the associated shader built-ins provide the tile dimensions. @@ -335,7 +335,7 @@ void vkCmdDispatchTileQCOM( ---- This command operates in the -link:{docs}chapters/renderpass.html#renderpass-per-tile-execution-model[per-tile execution model], +xref:{docs}chapters/renderpass.html#renderpass-per-tile-execution-model[per-tile execution model], invoking a separate dispatch for each _covered tile_. The global workgroup count and local workgroup size of each dispatch are defined by the implementation to efficiently iterate over a uniform grid of pixel blocks within @@ -344,7 +344,7 @@ the area of its _active tile_. Each shader invocation operates on a single pixel block and its size is determined by the shader's tiling rate, which *must* be defined by shaders executed by this command. The TileShadingRateQCOM execution mode operand defines the shader's tiling rate. Its x and y *must* be a power -of two and less than or equal to the link:{docs}chapters/limits.html#limits-maxTileShadingRate[maxTileShadingRate] limit. +of two and less than or equal to the xref:{docs}chapters/limits.html#limits-maxTileShadingRate[maxTileShadingRate] limit. Its z *must* be less than or equal to the z value of the active tile size as returned by `VK_QCOM_tile_properties`, and `VkTilePropertiesQCOM::tileSize.z % TileShadingRateQCOM.z` *must* equal `0`. @@ -379,7 +379,7 @@ NonCoherentTileAttachmentReadQCOM Disables raster order guarantee. Fragment on ---- -link:{docs}chapters/renderpass.html#renderpass-tile-shading-attachment-access[Tile attachment] variables are declared +xref:{docs}chapters/renderpass.html#renderpass-tile-shading-attachment-access[Tile attachment] variables are declared as `OpTypeImage` variables with storage class `TileAttachmentQCOM`. Such variables can be used to perform tile read/write operations, tile sampling operations, or tile atomic operations. @@ -436,7 +436,7 @@ The Vulkan SPIR-V environment will specify that: * A fragment shader must not use stores for tile color, tile input, or tile depth/stencil attachments. * A fragment or compute shader can use loads (`OpImageRead`, `OpImageSparseRead`) for tile color, tile depth/stencil, or tile input attachments. - * If the link:{docs}chapters/renderpass.html#renderpass-tile-shading-aprons[tile apron] has width or height greater than zero, then loads + * If the xref:{docs}chapters/renderpass.html#renderpass-tile-shading-aprons[tile apron] has width or height greater than zero, then loads and sampling of apron pixels (outside the tile, but within the apron) are allowed. Stores to apron pixels are disallowed. If not executing in a dynamic render pass, the subpass flags must include `VK_SUBPASS_DESCRIPTION_TILE_SHADING_APRON_BIT_QCOM`. @@ -560,7 +560,7 @@ may be no larger than a single pixel or single sample. For a render pass that en the following changes are made: * The framebuffer regions defined by `VK_DEPENDENCY_BY_REGION_BIT` are enlarged to - be tile-sized regions, where link:{extensions}VK_QCOM_tile_properties[VK_QCOM_tile_properties] + be tile-sized regions, where xref:{refpages}VK_QCOM_tile_properties.html[VK_QCOM_tile_properties] exposes the tile regions. In other words, the framebuffer region is a tile region and framebuffer-local dependencies are tile granularity dependencies. * Both synchronization scopes of a framebuffer-local dependency include all the pixels @@ -656,7 +656,7 @@ A few notable features are documented below. * `tileShadingPerTileDispatch` indicates the implementation supports the recording of dispatch commands inside a render pass. Note that dispatches inside a render pass are allowed only where - link:{docs}chapters/renderpass.html#renderpass-per-tile-execution-model[per-tile execution] is enabled. + xref:{docs}chapters/renderpass.html#renderpass-per-tile-execution-model[per-tile execution] is enabled. * `tileShadingDispatchTile` indicates the implementation supports the `vkCmdDispatchTileQCOM` command. Note this feature requires `tileShadingPerTileDispatch`. @@ -763,7 +763,7 @@ reading locations outside the tile+apron boundary. Yes, the granularity is guaranteed. -link:{extensions}VK_QCOM_tile_properties[VK_QCOM_tile_properties] reports +xref:{refpages}VK_QCOM_tile_properties.html[VK_QCOM_tile_properties] reports tile dimensions but does not provide any guarantees on the granularity of the tile dimension, making it difficult to author compute shaders that operate on a workgroup size of known dimensions. @@ -804,7 +804,7 @@ TBDRs. === Is functionality and performance expected to be similar for both render pass objects and dynamic render passes? Yes, since this extension builds upon -link:{extensions}VK_KHR_dynamic_rendering_local_read[VK_KHR_dynamic_rendering_local_read], +xref:{refpages}VK_KHR_dynamic_rendering_local_read.html[VK_KHR_dynamic_rendering_local_read], the functionality and performance is expected to be equivalent. Earlier versions of this extension that were not based on @@ -818,7 +818,7 @@ No, there is no change to the behavior. === Can tile attachment load/store operations be used without enabling per-tile execution? Yes, if a render pass enables tile shading but not the -link:{docs}chapters/renderpass.html#renderpass-per-tile-execution-model[per-tile execution model], then +xref:{docs}chapters/renderpass.html#renderpass-per-tile-execution-model[per-tile execution model], then fragment shader invocations can load pixel values from tile attachment variables. @@ -855,7 +855,7 @@ most optimally perform load/store operations for the micro tile's pixels. No. In this proposal, a created graphics pipeline can be used in a render pass regardless whether the render pass enables tile shading, and regardless whether -link:{docs}chapters/renderpass.html#renderpass-per-tile-execution-model[per-tile execution mode] is enabled. Similarly, +xref:{docs}chapters/renderpass.html#renderpass-per-tile-execution-model[per-tile execution mode] is enabled. Similarly, a created compute pipelines can now be used inside or outside a render pass. We decided not to require these usage flags during pipeline creation because we think it would be a burden to developers and because we do not anticipate implementations will require this information. @@ -868,7 +868,7 @@ No. Similar to above, we believe that limiting compute pipelines to a single renderpass/subpass would be a burden to developers and we do not anticipate that implementations need this information. -=== How does this extension differ from link:{extensions}VK_EXT_shader_tile_image[VK_EXT_shader_tile_image]? +=== How does this extension differ from xref:{refpages}VK_EXT_shader_tile_image.html[VK_EXT_shader_tile_image]? The functionality of this extension is a superset of `VK_EXT_shader_tile_image`. @@ -899,7 +899,7 @@ For example, a robust out-of-bounds tile access might return 0, or the coordinat be clamped to the tile's boundaries. In this initial proposal, we have elected to simply ban out-of-bounds tile access. -=== How does this extension interact with link:{extensions}VK_QCOM_image_processing[VK_QCOM_image_processing]? +=== How does this extension interact with xref:{refpages}VK_QCOM_image_processing.html[VK_QCOM_image_processing]? The functionality VK_QCOM_image_processing and VK_QCOM_image_processing2 are available with tile shading with an optional feature bit `tileShadingImageProcessing`. diff --git a/proposals/VK_VERSION_1_4.adoc b/proposals/VK_VERSION_1_4.adoc index f9f9d6827..088e45371 100644 --- a/proposals/VK_VERSION_1_4.adoc +++ b/proposals/VK_VERSION_1_4.adoc @@ -5,7 +5,7 @@ = Vulkan 1.4 :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :features: https://docs.vulkan.org/spec/latest/chapters/features.html#features- :sectnums: :times: × @@ -136,7 +136,7 @@ NOTE: Vulkan 1.4 does not require a supported subgroup size of greater than 1, b pass:[*]`shaderSignedZeroInfNanPreserveFloat16` is only supported if the `shaderFloat16` feature is supported. -The {extensions}VK_KHR_global_priority[`VK_KHR_global_priority`] extension is promoted in its entirety to Vulkan 1.4. +The xref:{refpages}VK_KHR_global_priority.html[`VK_KHR_global_priority`] extension is promoted in its entirety to Vulkan 1.4. === Roadmap 2024 @@ -168,18 +168,18 @@ The following limits from Roadmap 2024 are now required in Vulkan 1.4: The following extensions are promoted in their entirety to Vulkan 1.4: - * {extensions}VK_KHR_load_store_op_none[`VK_KHR_load_store_op_none`] - * {extensions}VK_KHR_shader_subgroup_rotate[`VK_KHR_shader_subgroup_rotate`] - * {extensions}VK_KHR_shader_float_controls2[`VK_KHR_shader_float_controls2`] - * {extensions}VK_KHR_shader_expect_assume[`VK_KHR_shader_expect_assume`] - * {extensions}VK_KHR_line_rasterization[`VK_KHR_line_rasterization`] - * {extensions}VK_KHR_vertex_attribute_divisor[`VK_KHR_vertex_attribute_divisor`] - * {extensions}VK_KHR_index_type_uint8[`VK_KHR_index_type_uint8`] - * {extensions}VK_KHR_map_memory2[`VK_KHR_map_memory2`] - * {extensions}VK_KHR_maintenance5[`VK_KHR_maintenance5`] - * {extensions}VK_KHR_push_descriptor[`VK_KHR_push_descriptor`] - -Additionally, {extensions}VK_KHR_dynamic_rendering_local_read[`VK_KHR_dynamic_rendering_local_read`] is partially promoted; implementations must support local read for storage resources and single sampled color attachments. + * xref:{refpages}VK_KHR_load_store_op_none.html[`VK_KHR_load_store_op_none`] + * xref:{refpages}VK_KHR_shader_subgroup_rotate.html[`VK_KHR_shader_subgroup_rotate`] + * xref:{refpages}VK_KHR_shader_float_controls2.html[`VK_KHR_shader_float_controls2`] + * xref:{refpages}VK_KHR_shader_expect_assume.html[`VK_KHR_shader_expect_assume`] + * xref:{refpages}VK_KHR_line_rasterization.html[`VK_KHR_line_rasterization`] + * xref:{refpages}VK_KHR_vertex_attribute_divisor.html[`VK_KHR_vertex_attribute_divisor`] + * xref:{refpages}VK_KHR_index_type_uint8.html[`VK_KHR_index_type_uint8`] + * xref:{refpages}VK_KHR_map_memory2.html[`VK_KHR_map_memory2`] + * xref:{refpages}VK_KHR_maintenance5.html[`VK_KHR_maintenance5`] + * xref:{refpages}VK_KHR_push_descriptor.html[`VK_KHR_push_descriptor`] + +Additionally, xref:{refpages}VK_KHR_dynamic_rendering_local_read.html[`VK_KHR_dynamic_rendering_local_read`] is partially promoted; implementations must support local read for storage resources and single sampled color attachments. Support for reading depth/stencil attachments and multi-sampled attachments are gated behind the new Boolean `dynamicRenderingLocalReadDepthStencilAttachments` and `dynamicRenderingLocalReadMultisampledAttachments` properties. If `dynamicRenderingLocalReadDepthStencilAttachments` and `dynamicRenderingLocalReadMultisampledAttachments` are `VK_TRUE`, the full functionality of the extension is present. If `dynamicRenderingLocalReadDepthStencilAttachments` is `VK_FALSE`, implementations do not support depth/stencil attachment access within dynamic rendering. @@ -218,11 +218,11 @@ The following additional limits are required in Vulkan 1.4: The following additional extensions are promoted in their entirety to Vulkan 1.4: - * {extensions}VK_KHR_maintenance6[`VK_KHR_maintenance6`] - * {extensions}VK_EXT_pipeline_protected_access[`VK_EXT_pipeline_protected_access`] - * {extensions}VK_EXT_pipeline_robustness[`VK_EXT_pipeline_robustness`] + * xref:{refpages}VK_KHR_maintenance6.html[`VK_KHR_maintenance6`] + * xref:{refpages}VK_EXT_pipeline_protected_access.html[`VK_EXT_pipeline_protected_access`] + * xref:{refpages}VK_EXT_pipeline_robustness.html[`VK_EXT_pipeline_robustness`] -Clustered subgroup operations must also be advertised in Vulkan 1.4 via setting both `VK_SUBGROUP_FEATURE_CLUSTERED_BIT` and `VK_SUBGROUP_FEATURE_ROTATE_CLUSTERED_BIT` (as an interaction with the newly-promoted {extensions}VK_KHR_shader_subgroup_rotate[`VK_KHR_shader_subgroup_rotate`] extension) in `subgroupSupportedOperations`. +Clustered subgroup operations must also be advertised in Vulkan 1.4 via setting both `VK_SUBGROUP_FEATURE_CLUSTERED_BIT` and `VK_SUBGROUP_FEATURE_ROTATE_CLUSTERED_BIT` (as an interaction with the newly-promoted xref:{refpages}VK_KHR_shader_subgroup_rotate.html[`VK_KHR_shader_subgroup_rotate`] extension) in `subgroupSupportedOperations`. === Streaming Transfers @@ -230,12 +230,12 @@ Clustered subgroup operations must also be advertised in Vulkan 1.4 via setting One of the gnarlier problems without a clear solution in earlier versions of Vulkan has been streaming large quantities of data to the device while simultaneously rendering. In OpenGL and other APIs, copy functions taking in host pointers allowed implementations a lot of leeway on where and how the transfer was performed, allowing implementations to use host copies, a dedicated transfer queue, or other solutions as they saw fit to ensure rendering could keep going at full speed. -Vendors are free to expose a dedicated transfer queue if they have one, and more recently {extensions}VK_EXT_host_image_copy[`VK_EXT_host_image_copy`] has enabled drivers to advertise host copies as an option if they do not have a separate transfer queue. +Vendors are free to expose a dedicated transfer queue if they have one, and more recently xref:{refpages}VK_EXT_host_image_copy.html[`VK_EXT_host_image_copy`] has enabled drivers to advertise host copies as an option if they do not have a separate transfer queue. Either of these paths will result in a way to provide applications a method to stream data between host and device without interrupting rendering. Vulkan 1.4 imposes a few new requirements in order to ensure applications have a viable path for streaming on all Vulkan 1.4 implementations: - * {extensions}VK_EXT_host_image_copy[`VK_EXT_host_image_copy`] is promoted to core, but supporting its functionality is optional + * xref:{refpages}VK_EXT_host_image_copy.html[`VK_EXT_host_image_copy`] is promoted to core, but supporting its functionality is optional * An implementation must support either: ** the {features}hostImageCopy[`hostImageCopy`] feature; or ** an additional queue that supports `VK_QUEUE_TRANSFER_BIT`. @@ -281,7 +281,7 @@ typedef struct VkPhysicalDeviceVulkan14Features { All features have the same meaning and requirements as their counterparts in the extensions they were promoted from, with the following exceptions: * `bresenhamLines` and `shaderSubgroupRotateClustered` are additionally required - * `pushDescriptor`, which is added as an additional feature for the functionality of {extensions}VK_KHR_push_descriptor[`VK_KHR_push_descriptor`] and is required + * `pushDescriptor`, which is added as an additional feature for the functionality of xref:{refpages}VK_KHR_push_descriptor.html[`VK_KHR_push_descriptor`] and is required * `pipelineProtectedAccess`, which is required only when the `protectedMemory` feature is supported diff --git a/proposals/VulkanBase.adoc b/proposals/VulkanBase.adoc index fb6668643..59e5172fd 100644 --- a/proposals/VulkanBase.adoc +++ b/proposals/VulkanBase.adoc @@ -5,7 +5,7 @@ = Vulkan Base :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: // Required so images render in github ifndef::images[:images: ../images] diff --git a/proposals/template.adoc b/proposals/template.adoc index d5503583d..3c8018846 100644 --- a/proposals/template.adoc +++ b/proposals/template.adoc @@ -4,7 +4,7 @@ = Proposal Template :toc: left :docs: https://docs.vulkan.org/spec/latest/ -:extensions: {docs}appendices/extensions.html# +:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/ :sectnums: // Required so images render in github ifndef::images[:images: ../images] @@ -20,16 +20,43 @@ and custom macros available to specification markup. They should only use pure Asciidoctor markup, so they can be viewed in the GitHub and GitLab asciidoctor renderers. -When calling out existing API constructs or extensions, the `docs` attribute should be used to link to the relevant part of the Vulkan specification. -For example - "...used to extend link:{docs}chapters/pipelines.html#VkGraphicsPipelineCreateInfo[VkGraphicsPipelineCreateInfo]..." +To link to refpages for existing APIs or extensions, use the `xref:` macro +followed by the `refpages` attribute, the API name, and the `.html` suffix: + +Example: xref:{refpages}VkGraphicsPipelineCreateInfo.html[VkGraphicsPipelineCreateInfo] + +Example markup: + +[source,asciidoc] +---- +xref:{refpages}VkGraphicsPipelineCreateInfo.html[VkGraphicsPipelineCreateInfo] +---- + +To link to an anchor in the specification other than an API or extension +which has its own refpage, use the `xref:` macro followed by the `docs` +attribute, the relative path of the file containing that anchor within the +spec repository, the `.html` suffix, and the anchor: + +Example: xref:{docs}chapters/copies.html#copies[copies] + +Example markup: + +[source,asciidoc] +---- +xref:{docs}chapters/copies.html#copies[copies] +---- If adding an image to a proposal document, it must be located in -`../images/proposals/`, and referred to as +`../images/proposals/`, and referred to with the `image:` macro +followed by the `images` attribute: [source,asciidoc] ---- image::{images}/proposals/filename.svg[image options] ---- + +Only use the `link:` macro when linking to an external website (one not +found in the Vulkan Docs site). ==== A short summary of this proposal should be written here.