[Migrated] documentation and examples for porting WGSL/GLSL shaders

Issue automatically imported from old repo: https://github.com/EmbarkStudios/rust-gpu/issues/1096
Old labels: t: enhancement
Originally creatd by johnny-smitherson on 2023-11-07T18:49:37Z 👍: 3

I've been porting some WGSL code like like these into rust and the documentation for actually writing shaders is very sparse: https://embarkstudios.github.io/rust-gpu/book/writing-shader-crates.html

I only managed to get the above program working by reading through the spriv-std test code.

Here are some pain points I have:

• confusion about the various binding types and how WGSL declaration syntax converts to rust-spirv attribute equivalent for basic types
  • #[spirv(storage_buffer, ...)] vs. #[spirv(storage, ...)] vs. Image! - how do they translate from WGSL definitions?
  • https://github.com/EmbarkStudios/rust-gpu/issues/976
• confusion about various barrier types: which of these ones should i use for wgsl storageBarrier() ? what about atomic ops?
• basic operations, like reading and writing to image textures, image sampling, are not documented nor in examples
• what Rust types are allowed by default? I found out at runtime u8 are not a thing - not a problem, but should be outlined for the non-initiated
• is this assembly here the only way to do this thing? What is even this thing that's being done?
• what Rust language features are known not to work? I discovered the hard way while and loop and/or for don't work - I just can't remember which ones
• how do i configure capabilities?? - this should be a documentation page
• how do i debug? - this should be a documentation page

Having a small body of real-life examples, ported from the wgpu wgsl examples for instance, would greatly help outside people actually get into your ecosystem, without really going through the spirv specification and diffing it to the wgsl specification to display a couple of spinning triangles.

I get it that some concepts will not be translateable 1-to-1 but a few more starting examples showing off basic shader features (all shader types, most of binding types, various barrier types, various combinations of globals, uniforms -- these would all help porting WGSL and GLSL into rust

I propose a Before + After rust conversion from each example, so everyone can see how the porting gets done, what gets translated into what. And you can also do benchmarks and correctness testIng on the rust shader vs. the original shader.

Maybe the original WGPU example runner can be used with minimal modification to accept spirv-type shaders alongside the original wgsl, so you won't have to rebuild all the runner bind group code from scratch.

Otherwise, I feel like without being a GPU pipeline engineer, I can't be the target audience for this project, but I really want to be, WGSL is awful, Rust is great.

edit found

• https://dev.to/bardt/notes-on-migrating-from-wgsl-to-rust-gpu-shaders-56bg
• https://dev.to/bardt/sharing-types-between-wgpu-code-and-rust-gpu-shaders-17c4

Are there any other resources that exist for this?

Start with the writing-shader-crates.html documentation page and the spriv-std test code referenced in the issue. Review examples/shaders/reduce/src/lib.rs and the linked wgpu examples to identify missing guidance for bindings, barriers, image operations, supported Rust features, capabilities, and debugging. Done should include a coherent porting guide with before-and-after examples covering the requested shader concepts.