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
name | description | WESL Specification |
---|---|---|
imports | import statements and qualified identifiers with :: | in progress |
condcomp | conditional compilation with @if attributes | complete |
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 | not 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§
- Basic
Source Map - Basic implementation of
SourceMap
. - Cache
Mangler - A mangler that remembers and can unmangle.
- Compile
Options - Compilation options. Used in
compile
andWesl::set_options
. - Compile
Result - The result of
Wesl::compile
. - Diagnostic
- Error diagnostics. Display user-friendly error snippets with
Display
. - Escape
Mangler - A mangler that replaces
::
with_
and_
with__
. e.g.foo::bar_baz item => foo_bar__baz_item
- File
Resolver - A resolver that looks for files in the filesystem.
- Hash
Mangler - A mangler that hashes the module path.
e.g.
foo::bar::baz item => item_32938483840293402930392
- Module
Path - 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.
- Source
Mapper - Generate a SourceMap by keeping track of name mangling and file resolutions.
- Standard
Resolver - The resolver that implements the WESL standard.
- Unicode
Mangler - 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ᐳ
- Virtual
Resolver - A resolver that resolves in-memory modules added with
Self::add_module
. - Wesl
- The WESL compiler high-level API.
Enums§
- Cond
Comp Error - Conditional translation error.
- Error
- Any WESL error.
- Import
Error - Error produced during import resolution.
- Mangler
Kind - Mangling scheme. Used in
Wesl::set_mangler
. - Resolve
Error - Error produced by module resolution.
- Validate
Error - 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.
- Source
Map - A SourceMap is a lookup from compiled WGSL to source WESL. It translates a mangled name into a module path and declaration name.
- Syntax
Util
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).