Integration

BWSL can be integrated in two common ways:

• run bwslc in your asset pipeline and ship generated shader output
• embed the compiler service or WASM build in editor tooling

CLI-Driven Integration

The CLI is the simplest integration path for builds and asset baking.

./build/bwslc shader.bwsl -modules ./modules -all

Typical inputs:

• a .bwsl source file
• zero or more module search paths

Typical outputs:

• SPIR-V for each compiled stage
• optional Metal, HLSL, GLSL, or GLSL ES output
• optional IR and SPIR-V disassembly via -internals

Use this path when your engine already has an asset build step and you want shader compilation to behave like any other imported asset.

Engine Runtime Integration

The repository also contains compiler-service code intended for host-engine integration:

• bwsl_compiler_service_core.h for platform-agnostic compilation and variant caching
• bwsl_compiler_service.h for Metal-focused runtime integration
• middleware/ for backend-specific glue

This path is useful when the engine needs to compile or specialize shaders on demand.

Recommended Project Layout

shaders/
  pipelines/
    MaterialPreview.bwsl
  modules/
    Lighting.bwsl
    Noise.bwsl
preview/
  MaterialPreview.preview.json

Then compile with explicit module roots:

./build/bwslc shaders/pipelines/MaterialPreview.bwsl \
  -modules shaders/modules \
  -variant lighting=Forward \
  -all

Resources and Validation

Shader-visible resources are declared directly in the BWSL pipeline with a resources {} block, selected per pass with use resources { ... }, and accessed through resources.*.

• the compiler assigns bindings automatically
• the reflection output describes resolved bindings and stage metadata
• invalid stage/resource access is rejected during compilation

Host-only metadata such as preview targets, pass wiring, or app-specific binding data should live outside the language surface. In this docs app that metadata lives in preview JSON.

That means mismatches are usually found during compilation instead of surfacing later as backend-specific shader errors.

Modules

Imports are resolved from:

• module search paths passed with -modules
• the input shader's directory

Example:

pipeline Demo {
    import Lighting, Noise
}

Tooling and Playground

For browser tools or editors, the repo also ships a WASM build. That is the right fit for autocomplete, preview compilation, and playground-style workflows where calling the native CLI is inconvenient.

The native and WASM compiler frontends both understand shader variants:

• use -variant name=value to specialize a concrete build
• use -dump-variant-space to inspect the legal variant space for tooling
• use compiler-service attribute masks when specializing optional vertex attributes at runtime

Next

• Installation
• CLI Reference
• Shader Variants
• Resources