WGSL Tools

A work in progress!

This project implements the necessary tools to build complex shaders, like what naga_oil does for bevy, but in a framework-agnostic way. At wgsl-tooling-wg, we aim at standardizing a few language extensions to facilitate the work of engine developers and shader wizards.

Current and planned extensions: imports, conditional compilation, generics, modules.

Usage

This project can be used as a rust library or as a standalone CLI.

Using the CLI

• Install cargo install --git https://github.com/k2d222/wgsl-tools
• Compile a WESL shader wgsl-tools compile <entrypoint.wgsl> (TODO: use the wesl extension)
• Run eval() wgsl-tools eval <entrypoint.wgsl> <expression to eval>

Using the Crate

documentation coming soon

Status

update: 2024-10

The crate wgsl-parse contains a WGSL-compliant syntax tree and parser, with optional syntax extensions from the WESL specification.

The crate wesl contains an implementation of the WESL specification, i.e. a compiler that takes WESL files and generates valid WGSL.

• "conditional translation"
• "imports" (WIP, the spec will evolve)
• "generics" (WIP, the spec will evolve)
• "modules" (WIP, the spec will evolve)
• eval/exec: 70%
• WESL validator: 0%
• WGSL optimization / compatibility: 10%

This crate contains a CLI to run the compiler and the parser.

See also:

• The online playground, wesl.thissma.fr / github.com/wesl-playground
• Nathalie Cuthbert's implementation, mew
• Lee Mighdoll's implementation, wgsl-linker

Goals

• Correct, mirror concepts present in the wgsl spec.
• Flexible, allow extending the wgsl syntax with well-defined extensions (see wgsl-tooling-wg).
• User-friendly, by sticking to the spec as much as possible, by providing clear and well-documented interfaces.

Non-goals

• Performant, we care about correctness, less so about time and memory constraints. The interface must be as user-friendly as possible. These tools target offline compilation first.