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!;
let downlevel_flags = adapter.get_downlevel_capabilities.flags;
assert!;
let required_features =
BASELINE_FEATURES | ;
let = adapter
.request_device
.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 = new?;
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 = update_particles;
let nested_pipeline = update;
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:
[]
= [
"SHADER_F16",
"TEXTURE_COMPRESSION_BC",
]
[]
= "downlevel_defaults"
= 4096
= 8192
= 8
= 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:
Entry points that require features beyond the baseline can be gated by those features:
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:
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:
defaultsdownlevel_defaultsdownlevel_webgl2_defaults
If no limits are configured, defaults is used. A preset without overrides
can be written directly:
[]
= "downlevel_webgl2_defaults"
Individual limits can be overridden in the limits table:
[]
= "downlevel_defaults"
= 8
Limit names use camelCase. The preset entry is optional and defaults to
defaults. Unknown limit names produce warnings and are ignored.