fd83816945
Naga is now a workspace with `naga` and `cli` as its two members. The default package for cargo commands is `cli`, so that `cargo run` will just run the CLI. However, this has a few unexpected consequences: - Now `cargo test` will just try to run `cli`'s tests, of which there are none. Adding `"."` to the `default-members` list in the workspace's `Cargo.toml` seems to fix this, without breaking `cargo run`. - Even with `"."` added to `default-members`, `cargo test` will build `naga` by default with the features requested for it in `cli/Cargo.toml`: all the front and back ends, but no `serialize` or `deserialize`. This means that our CI job meant to verify no-feature builds isn't doing that job any more. We need to pass `--package naga` to `cargo test` to make it test naga directly.
Naga
The shader translation library for the needs of wgpu and gfx-rs projects.
Supported end-points
Everything is still work-in-progress, but some end-points are usable:
| Front-end | Status | Feature | Notes |
|---|---|---|---|
| SPIR-V (binary) | ✅ | spv-in | |
| WGSL | ✅ | wgsl-in | Fully validated |
| GLSL | 🚧 | glsl-in | Temporarily broken |
| Back-end | Status | Feature | Notes |
|---|---|---|---|
| SPIR-V | ✅ | spv-out | |
| WGSL | 🚧 | wgsl-out | |
| Metal | ✅ | msl-out | |
| HLSL | 🚧 | hlsl-out | Shader Model 5.0+ (DirectX 11+) |
| GLSL | 🆗 | glsl-out | |
| AIR | |||
| DXIL/DXIR | |||
| DXBC | |||
| DOT (GraphViz) | 🆗 | dot-out | Not a shading language |
✅ = Primary support — 🆗 = Secondary support — 🚧 = Unsupported, but support in progress
Conversion tool
Naga includes a default binary target, which allows to test the conversion of different code paths.
cargo run my_shader.wgsl # validate only
cargo run my_shader.spv my_shader.txt # dump the IR module into a file
cargo run 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 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 --workspace,
which will run the unit tests, and also update all the snapshots. You'll see these
changes in git before committing 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
make validate-dot # for dot files, requires GraphViz installed
make validate-wgsl # for WGSL shaders
make validate-hlsl # for HLSL shaders. Note: this Make target makes use of the "sh" shell. This is not the default shell in Windows.