Skip to content

Commit ebc8c5c

Browse files
authored
[NFC][Doc] Update HLSL to SPIR-V document (microsoft#7204)
This is all about updating urls and tables in docs/SPIR-V.rst. I'm currently working on a demo & tutorial about how to work with Vulkan+HLSL+dxc toolchain so I made this PR. Thanks a lot for your contribution to the ecosystem, and glad to see your feedback! Signed-off-by: lumina37 <starry.qvq@gmail.com>
1 parent 24dedfd commit ebc8c5c

File tree

1 file changed

+20
-20
lines changed

1 file changed

+20
-20
lines changed

docs/SPIR-V.rst

Lines changed: 20 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -282,7 +282,7 @@ Right now the following ``<builtin>`` are supported:
282282
Need ``SPV_KHR_device_group`` extension.
283283
* ``ViewportMaskNV``: The GLSL equivalent is ``gl_ViewportMask``.
284284

285-
Please see Vulkan spec. `14.6. Built-In Variables <https://www.khronos.org/registry/vulkan/specs/1.1-extensions/html/vkspec.html#interfaces-builtin-variables>`_
285+
Please see Vulkan spec. `15.9. Built-In Variables <https://registry.khronos.org/vulkan/specs/latest/html/vkspec.html#interfaces-builtin-variables>`_
286286
for detailed explanation of these builtins.
287287

288288
Supported extensions
@@ -446,7 +446,7 @@ environment (hence SPIR-V version) and SPIR-V extension control:
446446
``-fspv-target-env=`` accepts a Vulkan target environment (see ``-help`` for
447447
supported values). If such an option is not given, the CodeGen defaults to
448448
``vulkan1.0``. When targeting ``vulkan1.0``, trying to use features that are only
449-
available in Vulkan 1.1 (SPIR-V 1.3), like `Shader Model 6.0 wave intrinsics`_,
449+
available in Vulkan 1.1 (SPIR-V 1.3), like `Shader Model 6.0 wave intrinsic <https://github.com/microsoft/directxshadercompiler/wiki/wave-intrinsics>`_,
450450
will trigger a compiler error.
451451

452452
If ``-fspv-extension=`` is not specified, the CodeGen will select suitable
@@ -494,7 +494,7 @@ Specifically, we need to legalize the following HLSL source code patterns:
494494
Legalization transformations will not run unless the above patterns are
495495
encountered in the source code.
496496

497-
For more details, please see the `SPIR-V cookbook <https://github.com/Microsoft/DirectXShaderCompiler/tree/master/docs/SPIRV-Cookbook.rst>`_,
497+
For more details, please see the `SPIR-V cookbook <https://github.com/Microsoft/DirectXShaderCompiler/tree/main/docs/SPIRV-Cookbook.rst>`_,
498498
which contains examples of what HLSL code patterns will be accepted and
499499
generate valid SPIR-V for Vulkan.
500500

@@ -561,7 +561,7 @@ So if you want to run loop unrolling additionally after the default optimization
561561
recipe, you can specify ``-Oconfig=-O,--loop-unroll``.
562562

563563
For the whole list of accepted passes and details about each one, please see
564-
``spirv-opt``'s help manual (``spirv-opt --help``), or the SPIRV-Tools `optimizer header file <https://github.com/KhronosGroup/SPIRV-Tools/blob/master/include/spirv-tools/optimizer.hpp>`_.
564+
``spirv-opt``'s help manual (``spirv-opt --help``), or the SPIRV-Tools `optimizer header file <https://github.com/KhronosGroup/SPIRV-Tools/blob/main/include/spirv-tools/optimizer.hpp>`_.
565565

566566
Validation
567567
~~~~~~~~~~
@@ -640,7 +640,7 @@ HLSL Semantic
640640

641641
HLSL semantic strings are by default not emitted into the SPIR-V binary module.
642642
If you need them, by specifying ``-fspv-reflect``, the compiler will use
643-
the ``Op*DecorateStringGOOGLE`` instruction in `SPV_GOOGLE_hlsl_funtionality1 <https://github.com/KhronosGroup/SPIRV-Registry/blob/master/extensions/GOOGLE/SPV_GOOGLE_hlsl_functionality1.asciidoc>`_
643+
the ``Op*DecorateStringGOOGLE`` instruction in `SPV_GOOGLE_hlsl_funtionality1 <https://github.com/KhronosGroup/SPIRV-Registry/blob/main/extensions/GOOGLE/SPV_GOOGLE_hlsl_functionality1.asciidoc>`_
644644
extension to emit them.
645645

646646
HLSL User Types
@@ -661,7 +661,7 @@ Counter buffers for RW/Append/Consume StructuredBuffer
661661
The association between a counter buffer and its main RW/Append/Consume
662662
StructuredBuffer is conveyed by ``OpDecorateId <structured-buffer-id>
663663
HLSLCounterBufferGOOGLE <counter-buffer-id>`` instruction from the
664-
`SPV_GOOGLE_hlsl_funtionality1 <https://github.com/KhronosGroup/SPIRV-Registry/blob/master/extensions/GOOGLE/SPV_GOOGLE_hlsl_functionality1.asciidoc>`_
664+
`SPV_GOOGLE_hlsl_funtionality1 <https://github.com/KhronosGroup/SPIRV-Registry/blob/main/extensions/GOOGLE/SPV_GOOGLE_hlsl_functionality1.asciidoc>`_
665665
extension. This information is by default missing; you need to specify
666666
``-fspv-reflect`` to direct the compiler to emit them.
667667

@@ -911,7 +911,7 @@ For example,
911911
912912
RWTexture2D<float2> Tex2; // Works like before
913913
914-
``rgba8`` means ``Rgba8`` `SPIR-V Image Format <https://www.khronos.org/registry/spir-v/specs/unified1/SPIRV.html#_a_id_image_format_a_image_format>`_.
914+
``rgba8`` means ``Rgba8`` `SPIR-V Image Format <https://registry.khronos.org/SPIR-V/specs/unified1/SPIRV.html#Image_Format>`_.
915915
The following table lists the mapping between ``FORMAT`` of
916916
``[[vk::image_format("FORMAT")]]`` and its corresponding SPIR-V Image Format.
917917

@@ -994,7 +994,7 @@ Please see the following sections for the details of each type. As a summary:
994994
=========================== ================== ================================ ==================== =================
995995

996996
To know more about the Vulkan buffer types, please refer to the Vulkan spec
997-
`13.1 Descriptor Types <https://www.khronos.org/registry/vulkan/specs/1.1-extensions/html/vkspec.html#descriptorsets-types>`_.
997+
`14.1 Descriptor Types <https://registry.khronos.org/vulkan/specs/latest/html/vkspec.html#descriptorsets-types>`_.
998998

999999
Memory layout rules
10001000
~~~~~~~~~~~~~~~~~~~
@@ -1004,7 +1004,7 @@ right now:
10041004

10051005
1. Vector-relaxed OpenGL ``std140`` for uniform buffers and vector-relaxed
10061006
OpenGL ``std430`` for storage buffers: these rules satisfy Vulkan `"Standard
1007-
Uniform Buffer Layout" and "Standard Storage Buffer Layout" <https://www.khronos.org/registry/vulkan/specs/1.1-extensions/html/vkspec.html#interfaces-resources-layout>`_,
1007+
Uniform Buffer Layout" and "Standard Storage Buffer Layout" <https://registry.khronos.org/vulkan/specs/latest/html/vkspec.html#interfaces-resources-layout>`_,
10081008
respectively.
10091009
They are the default.
10101010
2. DirectX memory layout rules for uniform buffers and storage buffers:
@@ -1027,7 +1027,7 @@ In the above, "vector-relaxed OpenGL ``std140``/``std430``" rules mean OpenGL
10271027
alignment:
10281028

10291029
1. The alignment of a vector type is set to be the alignment of its element type
1030-
2. If the above causes an `improper straddle <https://www.khronos.org/registry/vulkan/specs/1.1-extensions/html/vkspec.html#interfaces-resources-layout>`_,
1030+
2. If the above causes an `improper straddle <https://registry.khronos.org/vulkan/specs/latest/html/vkspec.html#interfaces-resources-layout>`_,
10311031
the alignment will be set to 16 bytes.
10321032

10331033
As an exmaple, for the following HLSL definition:
@@ -1471,7 +1471,7 @@ Without hints from the developer, the compiler will try its best to map
14711471
semantics to ``Location`` numbers. However, there is no single rule for this
14721472
mapping; semantic strings should be handled case by case.
14731473

1474-
Firstly, under certain `SigPoints <https://github.com/Microsoft/DirectXShaderCompiler/blob/master/docs/DXIL.rst#hlsl-signatures-and-semantics>`_,
1474+
Firstly, under certain `SigPoints <https://github.com/Microsoft/DirectXShaderCompiler/blob/main/docs/DXIL.rst#hlsl-signatures-and-semantics>`_,
14751475
some system-value (SV) semantic strings will be translated into SPIR-V
14761476
``BuiltIn`` decorations:
14771477

@@ -1655,7 +1655,7 @@ some system-value (SV) semantic strings will be translated into SPIR-V
16551655
| +-------------+----------------------------------------+-----------------------+-----------------------------+
16561656
| | MSOut | ``PrimitiveShadingRateKHR`` | N/A | ``FragmentShadingRate`` |
16571657
+---------------------------+-------------+----------------------------------------+-----------------------+-----------------------------+
1658-
| SV_CullPrimitive | MSOut | ``CullPrimitiveEXT`` | N/A | ``MeshShadingEXT `` |
1658+
| SV_CullPrimitive | MSOut | ``CullPrimitiveEXT`` | N/A | ``MeshShadingEXT`` |
16591659
+---------------------------+-------------+----------------------------------------+-----------------------+-----------------------------+
16601660

16611661

@@ -3596,8 +3596,8 @@ Mesh and Amplification Shaders
35963596
| Amplification shaders corresponds to Task Shaders in Vulkan.
35973597
|
35983598
| Refer to following HLSL and SPIR-V specs for details:
3599-
| https://docs.microsoft.com/<TBD>
3600-
| https://github.com/KhronosGroup/SPIRV-Registry/blob/master/extensions/NV/SPV_NV_mesh_shader.asciidoc
3599+
| https://microsoft.github.io/DirectX-Specs/d3d/MeshShader.html
3600+
| https://github.com/KhronosGroup/SPIRV-Registry/blob/main/extensions/NV/SPV_NV_mesh_shader.asciidoc
36013601
|
36023602
| This section describes how Mesh and Amplification shaders are translated to SPIR-V for Vulkan.
36033603
@@ -3704,8 +3704,8 @@ Raytracing in Vulkan and SPIRV
37043704
| SPIR-V codegen is currently supported for NVIDIA platforms via SPV_NV_ray_tracing extension or
37053705
| on other platforms via provisional cross vendor SPV_KHR_ray_tracing extension.
37063706
| SPIR-V specification for reference:
3707-
| https://github.com/KhronosGroup/SPIRV-Registry/blob/master/extensions/NV/SPV_NV_ray_tracing.asciidoc
3708-
| https://github.com/KhronosGroup/SPIRV-Registry/blob/master/extensions/KHR/SPV_KHR_ray_tracing.asciidoc
3707+
| https://github.com/KhronosGroup/SPIRV-Registry/blob/main/extensions/NV/SPV_NV_ray_tracing.asciidoc
3708+
| https://github.com/KhronosGroup/SPIRV-Registry/blob/main/extensions/KHR/SPV_KHR_ray_tracing.asciidoc
37093709
37103710
| Vulkan ray tracing samples:
37113711
| https://developer.nvidia.com/rtx/raytracing/vkray
@@ -3868,7 +3868,7 @@ Ray Query in SPIRV
38683868
~~~~~~~~~~~~~~~~~~
38693869
RayQuery SPIR-V codegen is currently supported via SPV_KHR_ray_query extension
38703870
SPIR-V specification for reference:
3871-
https://github.com/KhronosGroup/SPIRV-Registry/blob/master/extensions/KHR/SPV_KHR_ray_query.asciidoc
3871+
https://github.com/KhronosGroup/SPIRV-Registry/blob/main/extensions/KHR/SPV_KHR_ray_query.asciidoc
38723872

38733873
Object Type
38743874
~~~~~~~~~~~
@@ -4081,7 +4081,7 @@ This intrinsic funcion has the following signature:
40814081
40824082
uint64_t ReadClock(in uint scope);
40834083
4084-
It translates to performing ``OpReadClockKHR`` defined in `VK_KHR_shader_clock <https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_KHR_shader_clock.html>`_.
4084+
It translates to performing ``OpReadClockKHR`` defined in `VK_KHR_shader_clock <https://registry.khronos.org/vulkan/specs/latest/man/html/VK_KHR_shader_clock.html>`_.
40854085
One can use the predefined scopes in the ``vk`` namepsace to specify the scope argument.
40864086
For example:
40874087

@@ -4091,11 +4091,11 @@ For example:
40914091
40924092
RawBufferLoad and RawBufferStore
40934093
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4094-
The Vulkan extension `VK_KHR_buffer_device_address <https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_KHR_buffer_device_address.html>`_
4094+
The Vulkan extension `VK_KHR_buffer_device_address <https://registry.khronos.org/vulkan/specs/latest/man/html/VK_KHR_buffer_device_address.html>`_
40954095
supports getting the 64-bit address of a buffer and passing it to SPIR-V as a
40964096
Uniform buffer. SPIR-V can use the address to load and store data without a descriptor.
40974097
We add the following intrinsic functions to expose a subset of the
4098-
`VK_KHR_buffer_device_address <https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_KHR_buffer_device_address.html>`_
4098+
`VK_KHR_buffer_device_address <https://registry.khronos.org/vulkan/specs/latest/man/html/VK_KHR_buffer_device_address.html>`_
40994099
and `SPV_KHR_physical_storage_buffer <https://github.com/KhronosGroup/SPIRV-Registry/blob/main/extensions/KHR/SPV_KHR_physical_storage_buffer.asciidoc>`_
41004100
functionality to HLSL:
41014101

0 commit comments

Comments
 (0)