# wgcore − utilities and abstractions for composable WGSL shaders

**wgcore** provides simple abstractions over shaders and gpu resources based on `wgpu`. It aims to:

- Expose thin wrappers that are as unsurprising as possible. We do not rely on complex compiler
  magic like bitcode generation in frameworks like `cust` and `rust-gpu`.
- Provide a proc-macro (through the `wgcore-derive` crate) to simplifies shader reuse across
  crates with very low boilerplate.
- No ownership of the gpu device and queue. While `wgcore` does expose a utility struct
  [`gpu::GpuInstance`] to initialize the compute unit, it is completely optional. All the features
  of `wgcore` remain usable if the gpu device and queue are already own by, e.g., a game engine.

## Shader composition

#### Basic usage

Currently, **wgcore** relies on [naga-oil](https://github.com/bevyengine/naga_oil) for shader
composition. Though we are keeping an eye on the ongoing [WESL](https://github.com/wgsl-tooling-wg)
effort for an alternative to `naga-oil`.

The main value added over `naga-oil` is the `wgcore::Shader` trait and proc-macro. This lets you
declare composable shaders very concisely. For example, if the WGSL sources are at the path
`./shader_sources.wgsl` relative to the `.rs` source file, all that’s needed for it to be composable
is to `derive` she `Shader` trait:

```rust .ignore
#[derive(Shader)]
#[shader(src = "shader_source.wgsl")]
struct MyShader1;
```

Then it becomes immediately importable (assuming the `.wgsl` source itself contains a
`#define_import_path` statement) from another shader with the `shader(derive)` attribute:

```rust .ignore
#[derive(Shader)]
#[shader(
    derive(MyShader1), // This shader depends on the `MyShader1` shader.
    src = "kernel.wgsl",  // Shader source code, will be embedded in the exe with `include_str!`.
)]
struct MyShader2;
```

Finally, if we want to use these shaders from another one which contains a kernel entry-point,
it is possible to declare `ComputePipeline` fields on the struct deriving `Shader`:

```rust .ignore
#[derive(Shader)]
#[shader(
    derive(MyShader1, MyShader2),
    src = "kernel.wgsl",
)]
struct MyKernel {
    // Note that the field name has to match the kernel entry-point’s name.
    main: ComputePipeline,
}
```

This will automatically generate the necessary boiler-place for creating the compute pipeline
from a device: `MyKernel::from_device(device)`.

#### Some customization

The `Shader` proc-macro allows some customizations of the imported shaders:

- `src_fn = "function_name"`: allows the input sources to be modified by an arbitrary string
  transformation function before being compiled as a naga module. This enables any custom
  preprocessor to run before naga-oil.
- `shader_defs = "function_name"`: allows the declaration of shader definitions that can then be
  used in the shader in, e.g., `#ifdef MY_SHADER_DEF` statements (as well as `#if` statements and
  anything supported by the `naga-oil`’s shader definitions feature).
- `composable = false`: specifies that the shader does not exports any reusable symbols to other
  shaders. in particular, this **must** be specified if the shader sources doesn’t contain any
  `#define_import_path` statement.

```rust .ignore
#[derive(Shader)]
#[shader(
    derive(MyShader1, MyShader2),
    src = "kernel.wgsl",
    src_fn = "substitute_aliases",
    shader_defs = "dim_shader_defs"
    composable = false
)]
struct MyKernel {
    main: ComputePipeline,
}