cargo-wgpu-shaderc 0.2.2

Compile rust-gpu compute shaders into WGSL and wgpu pipeline constructors
cargo-wgpu-shaderc-0.2.2 is not a library.

cargo-wgpu-shaderc

Not affiliated with or endorsed by the wgpu project. Any resemblance to something the wgpu maintainers would approve of is purely coincidental.

cargo-wgpu-shaderc is a Cargo subcommand for compiling a rust-gpu shader crate for use with wgpu.

The project reads the shader crate's wgpu requirements and compiles each rust-gpu compute entry point to validated WGSL and a pipeline constructor.

Only compute shaders are supported. Vertex, fragment, mesh, task, and every other shader stage are rejected.

Installation

Install Rust through rustup, then clone or download this repository and run the following from its root:

cargo install --path . --locked

The repository's rust-toolchain.toml selects the required compiler and Rust components. The installed executable contains its rust-gpu backend and is available as cargo wgpu-shaderc.

Usage

cargo wgpu-shaderc <SHADER_CRATE_ROOT>

For example:

cargo wgpu-shaderc ./crates/shaders

The shader crate root must contain the package's Cargo.toml. Generated files are written to its output directory. That directory contains generated.rs and the generated WGSL files. Baseline variants use <entry-point>.wgsl and extended variants use <entry-point>_extended.wgsl. The generated module exposes BASELINE_FEATURES, BASELINE_LIMITS, and BASELINE_DOWNLEVEL_FLAGS for device creation. ALL_FEATURES contains the baseline and every optional feature that an extended shader can use.

The output directory is managed by the compiler and replaced whenever the shaders are regenerated.

Device creation

The device must support the baseline features, limits, and downlevel flags. Request every feature from ALL_FEATURES that the selected adapter supports so extended shader variants can be used whenever possible:

let adapter_features = adapter.features();
assert!(adapter_features.contains(BASELINE_FEATURES));

let downlevel_flags = adapter.get_downlevel_capabilities().flags;
assert!(downlevel_flags.contains(BASELINE_DOWNLEVEL_FLAGS));

let required_features =
    BASELINE_FEATURES | (adapter_features & ALL_FEATURES);
let (device, queue) = adapter
    .request_device(&wgpu::DeviceDescriptor {
        label: None,
        required_features,
        required_limits: BASELINE_LIMITS.clone(),
        ..Default::default()
    })
    .await?;

wgpu does not request downlevel flags through DeviceDescriptor, so they must be checked on the adapter before requesting the device. Applications can union their own required features into required_features and raise individual limits beyond BASELINE_LIMITS when needed.

The module also provides a BindGroupLayoutPool. Its constructor checks the device features and limits:

let mut layouts = BindGroupLayoutPool::new(&device)?;

Layouts are requested using a dense slice of BindingShape values. Bindings are compute-only, cannot be binding arrays, and buffer sizes are specified with BindingSize::of::<T>(). Repeated shapes return the same cached layout.

Pipeline constructors are exposed beneath the generated shaders module. A constructor follows the entry point's module path and takes a mutable reference to the pool:

let pipeline = shaders::update_particles(&mut layouts);
let nested_pipeline = shaders::particles::update(&mut layouts);

Constructors prefer an extended shader when its features are available and otherwise use the baseline shader. An entry point that only has an extended shader returns Option<wgpu::ComputePipeline>.

Shader requirements

rust-gpu 0.10.0-alpha.1 currently requires #[unsafe(no_mangle)] on every entry point. Without it, rustc may remove the function before rust-gpu discovers it.

Requirements are declared in the shader crate's Cargo.toml:

[package.metadata.wgpu]
features = [
    "SHADER_F16",
    "TEXTURE_COMPRESSION_BC",
]

[package.metadata.wgpu.limits]
preset = "downlevel_defaults"
maxTextureDimension1D = 4096
maxTextureDimension2D = 8192
maxBindGroups = 8
maxBufferSize = 536870912

Features

Features use wgpu_types::Features constant names and are combined into the required feature baseline. If no features are listed, the baseline is empty. Unknown feature names are errors.

Shader code can select feature-dependent implementations through the wgpu_feature cfg without declaring Cargo features:

#[cfg(wgpu_feature = "SUBGROUP")]
fn subgroup_implementation() {}

Entry points that require features beyond the baseline can be gated by those features:

#[cfg(wgpu_feature = "SUBGROUP")]
#[unsafe(no_mangle)]
#[spirv(compute(threads(1)))]
pub fn subgroup_shader() {}

Their constructors return Option<wgpu::ComputePipeline> and return None when the device does not provide the required features.

An entry point can also be available in both passes while conditionally using features above the baseline:

#[unsafe(no_mangle)]
#[spirv(compute(threads(1)))]
pub fn adaptive_shader() {
    #[cfg(wgpu_feature = "SUBGROUP")]
    use_subgroups();

    #[cfg(not(wgpu_feature = "SUBGROUP"))]
    use_baseline_path();
}

The constructor uses the extended version when the device supports it and falls back to the baseline version otherwise. Every shader must stay within the configured baseline limits. Override constants and non-compute entry points are not supported.

Limits

Limits start from one of three presets:

  • defaults
  • downlevel_defaults
  • downlevel_webgl2_defaults

If no limits are configured, defaults is used. A preset without overrides can be written directly:

[package.metadata.wgpu]
limits = "downlevel_webgl2_defaults"

Individual limits can be overridden in the limits table:

[package.metadata.wgpu.limits]
preset = "downlevel_defaults"
maxBindGroups = 8

Limit names use camelCase. The preset entry is optional and defaults to defaults. Unknown limit names produce warnings and are ignored.