Crate wesl 

WESL: A Community Standard for Enhanced WGSL

This is the crate for all your WESL needs.

See also the standalone CLI.

Basic Usage

See Compiler for an overview of the high-level API.

let compiler = Compiler::default();
let compile_result = compiler
    .compile("path/to/shader.wesl")
    .inspect_err(|e| eprintln!("WESL error: {e}")) // pretty-print error diagnostics
    .expect("compilation error");
let wgsl_string = compile_result.syntax.to_string();

Usage in build.rs

In your Rust project you probably want to have your WESL code converted automatically to a WGSL string at build-time, unless your WGSL code must be assembled at runtime.

Add this crate to your build dependencies in Cargo.toml:

[build-dependencies]
wesl = "0.4"

Create the build.rs file with the following content:

fn main() {
    let compiler = Compiler::default();
    let compile_result = compiler
        .compile("src/shaders/main.wesl")
        .inspect_err(|e| eprintln!("{e}")) // pretty-print errors
        .expect("compilation error");

    compile_result.emit_rerun_if_changed(); // optional, it prevents re-running the script if the shader have not changed
    compile_result.write_artifact("my_main_shader"); // writes the compiled file to `$OUT_DIR/my_main_shader.wesl`.
}

Include the compiled WGSL string in your code:

let module = device.create_shader_module(ShaderModuleDescriptor {
    label: Some("my_main_shader"),
    source: ShaderSource::Wgsl(include_wesl!("my_main_shader")), // `include_wesl` is a tiny convenience macro to load `$OUT_DIR/my_main_shader.wesl`.
});

Write shaders inline with the quote_module macro

See the wesl-quote crate.

Evaluating const-expressions

This is an advanced and experimental feature. wesl-rs supports evaluation and execution of WESL code with the eval feature flag. Early evaluation (in particular of const-expressions) helps developers to catch bugs early by improving the validation and error reporting capabilities of WESL. Full evaluation of const-expressions can be enabled with the lower compiler option.

Additionally, the eval feature adds support for user-defined @const attributes on functions, which allows one to precompute data ahead of time, and ensure that code has no runtime dependencies.

The eval/exec implementation is tested with the WebGPU Conformance Test Suite.

// ...standalone expression
let wgsl_expr = eval_str("abs(3 - 5)").unwrap().to_string();
assert_eq!(wgsl_expr, "2");

// ...expression using declarations in a WESL file
let source = "const my_const = 4; @const fn my_fn(v: u32) -> u32 { return v * 10; }";
let wgsl_expr = compiler
    .compile("main.wgsl").unwrap()
    .eval("my_fn(my_const) + 2").unwrap()
    .to_string();
assert_eq!(wgsl_expr, "42u");

Features

name	description	Status/Specification
generics	user-defined type-generators and generic functions	experimental
package	create shader libraries published to crates.io	experimental
eval	execute shader code on the CPU and @const attribute	experimental
naga-ext	enable all Naga/WGPU extensions	experimental
serde	derive Serialize and Deserialize for syntax nodes

Re-exports

pub use crate::error::Error;

pub use crate::mangler::Mangler;

pub use crate::package::PackageBuilder;

pub use crate::pass::Feature;

pub use crate::pass::Features;

pub use crate::resolver::AsyncResolver;

pub use crate::resolver::Constants;

pub use crate::resolver::Resolver;

Modules

error

Error types.

mangler

Mangler trait and implementations.

package

Shader packaging.

pass

Low-level reusable compilation passes.

resolver

Resolver trait and implementations.

sourcemap

SourceMap trait and implementations.

syntax

A syntax tree for WGSL and WESL files. The root of the tree is TranslationUnit.

toml_cfg

wesl.toml configuration parsing and file scanning.

Structs

CompileOptions

Compilation options used by Compiler.

CompileResult

Result of Compiler::compile.

Compiler

The WESL compiler.

Enums

ManglerKind

Declaration name mangling scheme. Used in CompileOptions::mangler.

Functions

compile

Standalone version of Compiler::compile_module.

compile_async

Async version of compile.