Add documentation for expanded shader processing tools functionality.

docs/how/how_edit_shader.rst

@@ -20,30 +20,35 @@ How to edit a scene shader
 
 RenderDoc allows you to edit a shader used in the capture and make changes to it and see the effects in real-time.
 
-To launch the shader editor, go to the pipeline stage you wish to change in the :doc:`../window/pipeline_state` windows, and click on the edit button |page_white_edit| next to the shader.
+To launch the shader editor, go to the pipeline stage you wish to change in the :doc:`../window/pipeline_state` windows, and click on the edit button |page_white_edit| next to the shader. If there are multiple edit options, a drop-down menu will be available - see below for more information about shader processing tools.
 
 Any changes to the shader will affect any drawcall using this shader, not just the currently-selected drawcall. The changes will persist until the edit window is closed.
 
-.. warning::
+Shader processing tools
+-----------------------
 
-	One unfortunate artifact of how the shader debug info works, not all #included hlsl files will come along with the debug info, only those files that contain compiled code. RenderDoc automatically replaces any #includes to missing files with just an empty comment, but unfortunately this can lead to compile errors in unused code.
+.. _shader-processing-tools:
 
-For SPIR-V shaders in Vulkan, if there is embedded source info it will be used for compilation, however in many cases the source is not available.
+Each graphics API has a native shader format - for D3D11 and D3D12 this is DXBC bytecode, for Vulkan this is SPIR-V bytecode, and for OpenGL this is GLSL shader text. Additionally it's possible for the bytecode shaders to contain embedded debug information with the original source code and compilation settings.
 
-RenderDoc allows you to configure a SPIR-V disassembler in the :doc:`../window/settings_window`. By default if ``spirv-cross`` is available it will be pre-configured and invoked automatically to decompile the SPIR-V into compilable GLSL.
+When editing a shader RenderDoc will display the original source if available, but otherwise it will attempt to invoke a shader processing tool to decompile the bytecode into a usable form. Multiple tools can be configured :ref:`in the settings window <shader-processing-tools-config>` and several for SPIR-V processing come with RenderDoc by default. If no tool is available RenderDoc displays a generated stub or default disassembly as a starting point.
+
+Each shader tool is defined to translate from some input to some output, so for example a compiler might take HLSL and output DXBC, and a decompiler might take SPIR-V and output HLSL.
+
+Once the edit window for a shader tool is open, the most appropriate tool to compile from the source into the API's native format is selected, and the parameters used for compilation are populated from debug info if available. These can then be customised further.
 
 Using the built-in shader editor
 --------------------------------
 
 When you have launched the shader editor, the main window will be filled with the source of your shader. In here you can make edits and changes with the basic controls and syntax highlighting available with the Scintilla editor.
 
-To compile the shader and apply your changes, either click the refresh button in the toolbar or press :kbd:`F5`. This will compile the shader and apply it, any warnings and errors will be added to the box below the main source.
+To compile the shader and apply your changes, either click the refresh button in the toolbar or press :kbd:`F5`. This will compile the shader and apply it, any warnings and errors will be added to the errors panel below the main source.
 
-Custom shaders are built with a simple set of flags, any shaders from the scene will be compiled with the flags that were originally passed to the compiler.
+You can choose the tool used to compile in the lower section, as well as configure any parameters to it. See above for more information about shader processing tools.
 
 .. warning::
 
-	If there are errors compiling a visualisation shader, it will be removed from the texture viewer and normal RGB display will be used until you fix the error.
+  If there are errors compiling a visualisation shader, it will be removed from the texture viewer and normal RGB display will be used until you fix the error.
 
   If there are errors compiling a shader-replacement shader, it will revert back to the original shader from the capture until the error is fixed.
 

docs/window/settings_window.rst

@@ -191,15 +191,25 @@ This option tries to make the disassembly of shaders easier to read by substitut
 
 ---------------
 
-  | :guilabel:`Vulkan Disassemblers`
+  | :guilabel:`Shader Processing Tools`
 
-.. _vulkan-disassem:
+.. _shader-processing-tools-config:
 
-Here you can configure external tools that disassemble binary SPIR-V into a human-readable representation.
+Here you can configure external tools that convert between shader representations, including compilers from a high-level language like HLSL/GLSL to a bytecode, as well as disassemblers from bytecode back to high-level language.
 
-Some built-in tools are supported such as SPIRV-Cross and spirv-dis, for these tools if they can be auto-detected they will already be present, and they may be distributed with RenderDoc builds in case a version isn't installed on the system.
+Some built-in tools are supported such as SPIRV-Cross, glslang, spirv-dis and spirv-as. For these tools if they can be auto-detected they will already be present, and they may be distributed with RenderDoc builds in case a version isn't installed on the system.
 
-Other custom tools can be configured, but for those the command line arguments must be configured. The command line arguments will have ``{spv_bin}`` replaced with the full path to the binary SPIR-V file, and ``{spv_disasm}`` with the path of where the human-readable output must be written to.
+Other custom tools can be configured, but for those the command line arguments must be configured. The command line arguments will have certain substitutions made to customise to the needs of the compile:
+
+* ``{input_file}`` will be replaced by the input filename.
+* ``{output_file}`` will be replaced by the output filename.
+* ``{entry_point}`` will be replaced by the entry point name, only when compiling a shader.
+* ``{glsl_stage4}`` will be replaced by the glsl stage short-hand, one of: vert, tesc, tese, geom, frag, or comp.
+* ``{hlsl_stage2}`` will be replaced by the hlsl stage short-hand, one of: vs, hs, ds, gs, ps, or cs.
+
+You must also select the input and output format of the tool, such as HLSL input and SPIR-V output. This will be used to match the tool against a given need at runtime with different types of shaders.
+
+Custom parameters can also be added each time the tool is invoked on the shader editing panel. For full information about using shader processing tools to decompile or compile shaders, see :ref:`the section on editing shaders <shader-processing-tools>`.
 
 Event Browser options
 ---------------------

docs/window/shader_viewer.rst

@@ -20,7 +20,7 @@ The shader viewer displays the source code in the formats that are available. Wh
 
 Several different disassembly forms are possible, depending on the API and available plugins and hardware support. Above the disassembly tab will be a drop-down listing the possible representations including hardware specific ISA formats like AMD GCN.
 
-For Vulkan SPIR-V shaders, you can configure custom disassemblers :ref:`in the settings window <vulkan-disassem>` which allows for various customised disassemblers such as SPIRV-Cross and spirv-dis.
+You can configure shader processing tools :ref:`in the settings window <shader-processing-tools-config>` which allows for various customised disassemblers such as SPIRV-Cross and spirv-dis for SPIR-V.
 
 .. figure:: ../imgs/Screenshots/ShaderDisassembly.png