Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Choosing targets

Each shader language is a cargo feature. Turning one on adds a constant to every kernel in your crate.

FeatureTraitConstantFor
wgslWgslKernelWGSL: &strwgpu, WebGPU, Dawn
spvSpirvKernelSPIRV: &[u32]Vulkan, OpenCL, and as an input to other tools
mslMslKernelMSL: &strMetal, so Apple platforms
hlslHlslKernelHLSL: &strDirect3D 12
glslGlslKernelGLSL: &strOpenGL and OpenGL ES

wgsl is on by default. Turn it off with default-features = false if you do not want it.

[dependencies]
unipute = { version = "0.2", features = ["spv", "msl"] }

Getting at the constant

Import the trait for the target you want, then read the constant off the kernel type:

use unipute::{WgslKernel, kernel};

#[kernel(workgroup_size(64))]
fn double(input: &[f32], output: &mut [f32]) {
    let index = global_id().x;
    if index < input.len() {
        output[index] = input[index] * 2.0;
    }
}

fn main() {
    let source: &str = double::WGSL;
    println!("{} bytes of WGSL", source.len());
}

Forgetting the import gives you a “cannot find” error, which is the usual Rust trait import problem rather than anything specific to Unipute.

Picking more than one

There is no cost to your program in enabling several. The strings all exist as constants and the ones you never read get dropped by the linker. What you pay is compile time, since each target runs its own writer over every kernel.

Supporting several backends usually looks like this:

#[cfg(target_vendor = "apple")]
fn shader() -> &'static str {
    use unipute::MslKernel;
    double::MSL
}

#[cfg(not(target_vendor = "apple"))]
fn shader() -> &'static str {
    use unipute::WgslKernel;
    double::WGSL
}

If you do not know the target until the program runs, see Generating at run time.

Notes per target

WGSL

The best supported path, and the one the tests exercise most. If you are using wgpu, this is what you want, and you can hand the string straight to create_shader_module.

SPIR-V

A &[u32], not bytes. Vulkan wants words, so this is the right shape already. If you need bytes, for writing to a file say, convert with to_le_bytes.

The first word is the SPIR-V magic number 0x07230203, which is a quick way to check you have a valid module.

MSL

Metal has no bind groups, so naga assigns buffer slots itself rather than using the group and binding numbers. Read the slots from Metal’s reflection rather than assuming they match BINDINGS. This is the one target where the layout information does not carry across directly.

HLSL

Targets Shader Model 6 by default. Groups and bindings become register assignments.

GLSL

Targets OpenGL ES 3.10, which is the first version with compute shaders, and which a desktop OpenGL 4.3 or later context also accepts when it has ARB_ES3_1_compatibility. For a particular desktop version, the runtime feature gives you naga_backend::write::glsl_with, which takes naga’s version type.

GLSL has no bind groups. Each resource is written with its binding number as its layout(binding = ...) and the group is dropped, so an OpenGL host binds a buffer at binding.binding and ignores binding.group. The cost is one namespace where the kernel had several: once glsl is on, two resources in different groups cannot share a binding number, and the macro reports the pair rather than writing a shader that binds them on top of each other. Give a second group’s parameters indices that carry on from the first, as in #[binding(group = 1, index = 2)].

One more thing if the output is going to wgpu rather than to OpenGL: wgpu reads GLSL through naga, and naga’s reader only takes desktop profiles 4.40 and up. Hand it glsl_with output for one of those rather than the GLSL constant. The GPU tests do exactly that.

Seeing all of them

The repository has an example that prints every enabled target for one kernel:

cargo run --example emit_shaders --features "spv,msl,hlsl,glsl"

That is the fastest way to see what a kernel actually becomes, and a good sanity check when something is not behaving. Examples lists the others that come with the repository.