Crate wgcore 

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 for shader composition. Though we are keeping an eye on the ongoing WESL 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:

#[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:

#[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:

#[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.

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

Re-exports

pub use shader::Shader;

pub use shader::ShaderRegistry;

Modules

composer

Extensions over naga-oil’s Composer.

gpu

Utilities struct to initialize a gpu device.

hot_reloading

Utility to detect changed files for shader hot-reloading.

kernel

Utilities for queueing and dispatching kernels.

re_exports

Third-party modules re-exports.

shader

Trait for reusable gpu shaders.

shapes

Tensor shape definition.

tensor

Utilities for initializing and slicing tensors, matrices, vectors, and scalars gpu storage buffers.

timestamps

A convenient wrapper for handling gpu timestamps.

utils

Utilities for creating a ComputePipeline from source or from a naga module.

Macros

test_shader_compilation

A macro that declares a test that will check compilation of the shader identified by the given struct implementing Shader.

Traits

Pod

Marker trait for “plain old data”.

Derive Macros

Pod

Derive the Pod trait for a struct