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.