LYGIA Shader Library

WESL is a superset of WGSL designed to improve shader development. Key features include:

• import statements: Allows splitting shader code across files and loading libraries (npm or cargo).
• @if, @else, @elseif directives: Enables conditional compilation to assemble specialized shaders at build time or runtime.

Lygia provides its WebGPU-compatible shaders using the .wesl extension. While older .wgsl versions exist, the .wesl versions are more complete and recommended for new users.

To contribute a new shader to the Lygia WESL library, follow these steps:

1. Create a .wesl file: Place the file alongside existing shader files. Follow the Lygia convention of having one user-facing function per file to optimize application bundle sizes. You may include multiple type variants of the same function (e.g., one for f32 and one for vec3f) within a single file.
2. Add tests: Create corresponding tests in the test/wesl directory using the appropriate testing method:
   • Use testCompute() for pure math functions.
   • Use testFragment() for derivative functions (like fwidth, dpdx, dpdy) or texture sampling.
   • Use toMatchImage() for visual regression tests such as filters, generative patterns, or complex rendering.

If you are working with local .glsl files in a modern build pipeline, you can use existing plugins to handle #include directives automatically:

• Vite: Use vite-plugin-glsl to import local dependencies or load inline shaders.
• esbuild: Use esbuild-plugin-glsl-include to import local .glsl dependencies.
• Webpack: Use webpack-glsl-loader to import local dependencies.

To use Lygia in a Rust project, add the lygia crate. WESL tools are also available for Rust developers.

Installation

cargo add lygia

Linking at build time

Add wesl to your build dependencies and use a build.rs file to generate artifacts.

cargo add --build wesl

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

Linking at run-time

Add wesl to your dependencies to compile shaders during application execution.

cargo add wesl

let shader_string = Wesl::new("src/shaders")
    .compile("main.wesl")
    .inspect_err(|e| eprintln!("WESL error: {e}"))
    .unwrap()
    .to_string();

Using the Rust CLI tool

Install the CLI to compile shaders directly from the terminal.

cargo install wesl-cli
wesl compile <path/to/shader.wesl>

For applications using vite, webpack, or rollup, install wesl and wesl-plugin. You can choose between runtime or static linking:

Runtime Linking

Use the ?link suffix on your import. This allows you to use WESL's conditional compilation features (@if directives) to adapt shaders dynamically at runtime based on GPU capabilities or user settings. This requires the wesl linker in your runtime bundle.

Static Linking

Use the ?static suffix. This bundles shaders into a single transpiled WGSL string at build time. This is more efficient (~15KB smaller bundle) but prevents dynamic adaptation via @if directives.

// Runtime Linking
import appWesl from "../shaders/app.wesl?link";
import { link } from "wesl";

const linked = await link(appWesl);
linked.createShaderModule(gpuDevice);

// Static Linking
import appWgsl from "../shaders/app.wesl?static";

For cloud platforms (like CodePen or Observable) where you cannot host local files, use the LYGIA server to resolve #include dependencies online.

1. Include the resolver script in your HTML:

   • JavaScript: <script src="https://lygia.xyz/resolve.js"></script>
   • ES6 Module: <script type="module">import resolveLygia from "https://lygia.xyz/resolve.esm.js"</script>

2. Call the resolver in your JavaScript code to transform your shader source code strings.

You can install LYGIA locally to bundle it with your project. Choose one of the following methods:

• Git Clone: git clone https://github.com/patriciogonzalezvivo/lygia.git
• Git Submodule: git submodule add https://github.com/patriciogonzalezvivo/lygia.git
• Degit (No history): npx degit https://github.com/patriciogonzalezvivo/lygia.git lygia
• NPM: Use the @lygia/lygia package.

If you want to reduce the library size by only keeping the files for your specific language (e.g., GLSL), use the prune.py script.

To use LYGIA functions in a web environment, you must resolve the #include "path/to/file.glsl" dependencies into a single shader string. You can use the resolveLygia() or resolveLygiaAsync() functions provided by the resolve-lygia npm module or the vanilla JS resolver at lygia.xyz/resolve.js.

These functions take a string or string[] (representing your shader code or a list of shader files) and parse it, solving all #include dependencies. To support specific versions of LYGIA, use the path pattern lygia/vX.X.X/... within your dependency paths.

To use LYGIA in your shaders, use the #include directive to import specific functions. Ensure your environment is configured to resolve these include paths. Each function is typically contained in its own file.

#include "lygia/space/ratio.glsl"
#include "lygia/math/decimate.glsl"
#include "lygia/draw/circle.glsl"

void main(void) {
    // ... use functions like ratio(), decimate(), or circle()
}