Naga

This is an experimental shader translation library for the needs of gfx-rs project and WebGPU.

Supported end-points

Everything is still a work-in-progress, but some end-points are usable:

Front-end	Status	Notes
SPIR-V (binary)	✅
WGSL	✅
GLSL (Vulkan)	🆗
Rust

Back-end	Status	Notes
SPIR-V (binary)	✅
WGSL
Metal	✅
HLSL
GLSL	🆗
AIR
DXIL/DXIR
DXBC

✅ = Primary support — 🆗 = Secondary support — 🚧 = Unsupported, but support in progress

Conversion tool

Naga includes a default binary target "convert", which allows to test the conversion of different code paths.

cargo run --features spv-in -- my_shader.spv # dump the IR module to debug output
cargo run --features spv-in,msl-out -- my_shader.spv my_shader.metal --flow-dir flow-dir # convert the SPV to Metal, also dump the SPIR-V flow graph to `flow-dir`
cargo run --features wgsl-in,glsl-out -- my_shader.wgsl my_shader.vert --profile es310 # convert the WGSL to GLSL vertex stage under ES 3.20 profile

Development workflow

The main instrument aiding the development is the good old cargo test --all-features, which will run the snapshot tests as well as the unit tests. Any changes in the snapshots would then have to be reviewed with cargo insta review before being accepted into the code.

If working on a particular front-end or back-end, it may be convenient to enable the relevant features in Cargo.toml, e.g.

default = ["spv-out"] #TEMP!

This allows IDE basic checks to report errors there, unless your IDE is sufficiently configurable already.

Finally, when changes to the snapshots are made, we should verify that the produced shaders are indeed valid for the target platforms they are compiled for. We automate this with Makefile:

make validate-spv # for Vulkan shaders, requires SPIRV-Tools installed
make validate-msl # for Metal shaders, requires XCode command-line tools installed
make validate-glsl # for OpenGL shaders, requires GLSLang installed