Crate wesl

Source
Expand description

§WESL: A Community Standard for Enhanced WGSL

This is the crate for all your WESL needs.

See also the standalone CLI.

§Basic Usage

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

let compiler = Wesl::new("src/shaders");

// compile a WESL file to a WGSL string
let wgsl_str = compiler
    .compile("main.wesl")
    .inspect_err(|e| eprintln!("WESL error: {e}")) // pretty errors with `display()`
    .unwrap()
    .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.1"

Create the build.rs file with the following content:

fn main() {
    Wesl::new("src/shaders")
        .build_artefact("main.wesl", "my_shader");
}

Include the compiled WGSL string in your code:

let module = device.create_shader_module(ShaderModuleDescriptor {
    label: Some("my_shader"),
    source: ShaderSource::Wgsl(include_wesl!("my_shader")),
});

§Advanced Examples

Evaluate const-expressions.

// ...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("source").unwrap()
    .eval("my_fn(my_const) + 2").unwrap()
    .to_string();
assert_eq!(wgsl_expr, "42u");

§Features

namedescriptionWESL Specification
importsimport statements and qualified identifiers with ::in progress
condcompconditional compilation with @if attributescomplete
genericsuser-defined type-generators and generic functionsexperimental
packagecreate shader libraries published to crates.ioexperimental
evalexecute shader code on the CPU and @const attributenot part of the spec

imports and condcomp are default features.

Modules§

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

Macros§

include_wesl
Include a WGSL file compiled with Wesl::build_artefact as a string.
wesl_pkg
Include a generated package.

Structs§

BasicSourceMap
Basic implementation of SourceMap.
CacheMangler
A mangler that remembers and can unmangle.
CompileOptions
Compilation options. Used in compile and Wesl::set_options.
CompileResult
The result of Wesl::compile.
Diagnostic
Error diagnostics. Display user-friendly error snippets with Display.
EscapeMangler
A mangler that replaces :: with _ and _ with __. e.g. foo::bar_baz item => foo_bar__baz_item
FileResolver
A resolver that looks for files in the filesystem.
HashMangler
A mangler that hashes the module path. e.g. foo::bar::baz item => item_32938483840293402930392
ModulePath
NoMangler
A mangler that just returns the identifer as-is (no mangling). e.g. foo::bar::baz item => item
NoResolver
A resolver that never resolves anything.
PkgResolver
A resolver that only resolves module paths that refer to modules in external packages.
Preprocessor
A WESL module preprocessor.
Router
A resolver that can dispatch imports to several sub-resolvers based on the import path prefix.
SourceMapper
Generate a SourceMap by keeping track of name mangling and file resolutions.
StandardResolver
The resolver that implements the WESL standard.
UnicodeMangler
A mangler that uses cryptic unicode symbols that look like :, < and > e.g. foo::bar::baz array<f32,2> => foo::bar::baz::arrayᐸf32ˏ2ᐳ
VirtualResolver
A resolver that resolves in-memory modules added with Self::add_module.
Wesl
The WESL compiler high-level API.

Enums§

CondCompError
Conditional translation error.
Error
Any WESL error.
ImportError
Error produced during import resolution.
ManglerKind
Mangling scheme. Used in Wesl::set_mangler.
ResolveError
Error produced by module resolution.
ValidateError
WESL or WGSL Validation error.

Traits§

Mangler
A name mangler is responsible for renaming import-qualified identifiers into valid WGSL identifiers.
PkgModule
The trait implemented by external packages.
Resolver
A Resolver implements the module resolution algorithm: it returns a module contents associated with a module path.
SourceMap
A SourceMap is a lookup from compiled WGSL to source WESL. It translates a mangled name into a module path and declaration name.
SyntaxUtil

Functions§

compile
Low-level version of Wesl::compile.
compile_sourcemap
Like compile, but provides better error diagnostics and returns the sourcemap.
lower
Performs conversions on the final syntax tree to make it more compatible with WGSL implementations like Naga, catch errors early and perform optimizations.
validate_wesl
Validate an intermediate WESL module.
validate_wgsl
Validate the final output (valid WGSL).