Document the new methods of generating SPIR-V shader debug information

docs/how/how_debug_shader.rst

@@ -10,11 +10,16 @@ This page goes into detail about how to set up your captures for debugging shade
 Including debug info in shaders
 -------------------------------
 
-For the most part at least some debug information is included with shaders unless it is being explicitly stripped out at some point. There is usually an option to also include additional debug information - such as original source code in a high-level language. The exact process varies by API, but for D3D11 the flag ``/Zi`` to fxc or the equivalent flag to ``D3DCompile()`` will include additional debugging information, and ``/Qstrip_debug`` and ``/Qstrip_reflection`` will remove reflection information that can be useful - such as the names of variables in constant buffers.
+For the most part at least some reflection information is included with shaders unless it is being explicitly stripped out at some point, but usually information for debugging shaders such as the original source code is not included by default.
 
-For shader debugging it's recommended that you build with ``/Od`` or ``D3DCOMPILE_SKIP_OPTIMIZATION``, as this will enable HLSL debugging by default.
+The option to include this additional debug information varies by API.
 
-For more information on how to get this unstripped debug information to renderdoc, see :doc:`how_shader_debug_info`.
+* For D3D11 and D3D12 the flag ``/Zi`` to fxc or the ``D3DCOMPILE_DEBUG`` flag to ``D3DCompile()`` will include additional debugging information. ``/Qstrip_debug`` and ``/Qstrip_reflection`` will remove reflection information that can be useful - such as the names of variables in constant buffers - so it's recommended against using these. RenderDoc does fully support the new split pdb information using ``/Fd``.
+
+  For shader debugging it's recommended that you build with ``/Od`` or ``D3DCOMPILE_SKIP_OPTIMIZATION`` for the best experience, as this will also enable HLSL debugging by default.
+* On Vulkan RenderDoc supports source-level debugging via the ``NonSemantic.Shader.DebugInfo.100`` extended instruction set. This information can be generated by glslang using ``-gVS`` to specify debug information, and by dxc using ``-fspv-debug=vulkan-with-source``. In both cases this will embed the necessary debug information in the SPIR-V blob to debug at source level.
+
+If you are manually splitting out debug information you can see more information on how to get this information to renderdoc, see :doc:`how_shader_debug_info`.
 
 Debugging a vertex
 ------------------

docs/how/how_shader_debug_info.rst

@@ -1,10 +1,12 @@
 How do I use shader debug information?
 ======================================
 
-RenderDoc makes extensive use of shader debug information to provide a smoother debugging experience. This kind of information gives names to anything in the shader interface such as constants, resource bindings, interpolated inputs and outputs. It includes better type information that in many cases is not available, and it can also even include embedded copies of the shader source which is used for source-level debugging.
+RenderDoc makes extensive use of shader reflection and debug information to provide a smoother debugging experience. This kind of information gives names to anything in the shader interface such as constants, resource bindings, interpolated inputs and outputs. It includes better type information that in many cases is not available, and it can also even include embedded copies of the shader source which is used for source-level debugging.
 
 On most APIs this debug information adds up to a large amount of information which is not necessary for functionality, and so it can be optionally stripped out. Many shader compilation pipelines will do this automatically, so the information is lost by the time RenderDoc can intercept it at the API level. For this reason there are several ways to save either the unstripped shader blob or just the debug information separately at compile time and provide ways for RenderDoc to correlate the stripped blob it sees passed to the API with the debug information on disk.
 
+If you did not deliberately strip out debug information and left it embedded in the blob, you do not need to do anything else and RenderDoc will find and use the information. If you used a compiler-based method of generating separate debug information you will at most need to specify search paths in the RenderDoc options but you do not need to follow any of these steps.
+
 .. note::
 
   OpenGL is effectively excluded from this consideration because it has no separate debug information, everything is generated from the source uploaded to the API. If the source has been stripped of information or obfuscated, this will have to be handled by your application.
@@ -16,7 +18,7 @@ On most APIs this debug information adds up to a large amount of information whi
 Specifying debug shader blobs
 -----------------------------
 
-Separated debug shader blobs can be specified using a path and an API-specific mechanism. The path itself can either be an absolute path, which will be used directly every time, or it can be a relative path which allows the blob identifier to be specified relative to customisable search folders. If using a relative path, it can be as simple as a filename.
+Separated debug shader blobs can be specified using a path and an API-specific mechanism, if the separation has been done manually. The path itself can either be an absolute path, which will be used directly every time, or it can be a relative path which allows the blob identifier to be specified relative to customisable search folders. If using a relative path, it can be as simple as a filename.
 
 The search folders for shader debug info are specified in the settings window, under the ``Core`` category. You can configure as many search directories as you wish, and they will be searched in the listed order.