Add easy way to dump out final wgsl shader (#3947)

### What

.. and document how to inspect translated shaders in an easy way.

* Fixes #3944
   * not exactly what I had in mind but actually good enough! 

### Checklist
* [x] I have read and agree to [Contributor
Guide](https://github.com/rerun-io/rerun/blob/main/CONTRIBUTING.md) and
the [Code of
Conduct](https://github.com/rerun-io/rerun/blob/main/CODE_OF_CONDUCT.md)
* [x] I've included a screenshot or gif (if applicable)
* [x] I have tested [demo.rerun.io](https://demo.rerun.io/pr/3947) (if
applicable)
* [x] The PR title and labels are set such as to maximize their
usefulness for the next release's CHANGELOG

- [PR Build Summary](https://build.rerun.io/pr/3947)
- [Docs
preview](https://rerun.io/preview/9ae4da5c1069e952e391800cfce01e8da7dc88cd/docs)
<!--DOCS-PREVIEW-->
- [Examples
preview](https://rerun.io/preview/9ae4da5c1069e952e391800cfce01e8da7dc88cd/examples)
<!--EXAMPLES-PREVIEW-->
- [Recent benchmark results](https://ref.rerun.io/dev/bench/)
- [Wasm size tracking](https://ref.rerun.io/dev/sizes/)

crates/re_renderer/README.md

@@ -24,3 +24,40 @@ Goals & philosophy:
 * Lazy loading whenever possible for best startup performance
 * Run great both on the desktop and web
 * No dependencies on `re_viewer` or rerun data store libraries
+
+
+## Debugging
+
+### Shader
+
+#### Iterating
+
+In debug mode shaders are live-reloaded.
+If a failure occurs during live-reload, an error is logged and the previous shader is kept.
+
+#### Inspecting final source
+
+If `RERUN_WGSL_SHADER_DUMP_PATH` is set, all readily stitched (import resolve) and patched
+wgsl shaders will be written to the specified directory.
+
+Often you're also interested in the Naga translated shader. This can be done easily from command line using
+```sh
+cargo install naga-cli --all-features
+```
+
+Example for translating a wgsl fragment shader to GL as used on WebGL:
+```sh
+naga ./wgsl_dump/rectangle_fs.wgsl ./wgsl_dump/rectangle_fs.frag --entry-point fs_main --profile es300
+```
+Example for translating a wgsl vertex shader to GL as used on WebGL:
+```sh
+naga ./wgsl_dump/rectangle_vs.wgsl ./wgsl_dump/rectangle_vs.vert --entry-point vs_main --profile es300
+```
+Note that a single shader entry point from wgsl maps to a single frag/vert file!
+
+Example for translating a wgsl to MSL as used on MacOS.
+Note that a single metal file maps to a single wgsl file.
+```sh
+naga ./wgsl_dump/rectangle_fs.wgsl ./wgsl_dump/rectangle_fs.metal
+```
+

crates/re_renderer/src/wgpu_resources/shader_module_pool.rs

@@ -14,6 +14,10 @@ use super::{
 
 slotmap::new_key_type! { pub struct GpuShaderModuleHandle; }
 
+/// If set, all readily stitched (import resolve) and patched
+/// wgsl shaders will be written to the specified directory.
+const RERUN_WGSL_SHADER_DUMP_PATH: &str = "RERUN_WGSL_SHADER_DUMP_PATH";
+
 /// Create a shader module using the `include_file!` macro and set the path name as debug string.
 #[macro_export]
 macro_rules! include_shader_module {
@@ -74,6 +78,19 @@ impl ShaderModuleDesc {
             source_interpolated.contents = source_interpolated.contents.replace(from, to);
         }
 
+        if let Ok(wgsl_dump_dir) = std::env::var(RERUN_WGSL_SHADER_DUMP_PATH) {
+            let mut path = PathBuf::from(wgsl_dump_dir);
+            std::fs::create_dir_all(&path).unwrap();
+
+            let mut wgsl_filename = self.source.to_str().unwrap().replace(['/', '\\'], "_");
+            if let Some(position) = wgsl_filename.find("re_renderer_shader_") {
+                wgsl_filename = wgsl_filename[position + "re_renderer_shader_".len()..].to_owned();
+            }
+
+            path.push(&wgsl_filename);
+            std::fs::write(&path, &source_interpolated.contents).unwrap();
+        }
+
         // All wgpu errors come asynchronously: this call will succeed whether the given
         // source is valid or not.
         // Only when actually submitting passes that make use of this shader will we know if