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

Running a kernel

Unipute stops at the shader. Getting it onto a GPU is your graphics API’s job. This chapter shows how the two meet.

The code here is sketched against wgpu to show the shape of it. The full version, which the examples and the GPU tests run through, is examples/host/mod.rs in the repository. Graphics APIs change their signatures often, so if the two ever disagree, the file is the one that compiles. The Unipute side, which is the part this book can promise, is the constants.

What a kernel gives the host

Three things:

use unipute::{Kernel, WgslKernel, kernel};
#[kernel(workgroup_size(64))]
fn scale(input: &[f32], output: &mut [f32], factor: &f32) {
    let index = global_id().x;
    if index >= input.len() { return; }
    output[index] = input[index] * factor;
}
fn main() {
scale::WGSL;            // the shader
scale::NAME;            // the entry point name inside it
scale::WORKGROUP_SIZE;  // how many invocations one group runs
scale::BINDINGS;        // where each buffer goes
}

Those four cover everything the host has to know.

Creating the pipeline

let module = device.create_shader_module(wgpu::ShaderModuleDescriptor {
    label: Some(scale::NAME),
    source: wgpu::ShaderSource::Wgsl(scale::WGSL.into()),
});

let pipeline = device.create_compute_pipeline(&wgpu::ComputePipelineDescriptor {
    label: Some(scale::NAME),
    layout: None,
    module: &module,
    entry_point: Some(scale::NAME),
    compilation_options: Default::default(),
    cache: None,
});

Using scale::NAME rather than the string "scale" means that renaming the kernel, or setting name = "..." on the attribute, does not leave the host side pointing at an entry point that no longer exists.

Building the bind group layout

This is where BINDINGS earns its place. Instead of writing the layout by hand and keeping it in step with the kernel, build it from the kernel:

use unipute::Access;

let entries: Vec<_> = scale::BINDINGS
    .iter()
    .map(|binding| wgpu::BindGroupLayoutEntry {
        binding: binding.binding,
        visibility: wgpu::ShaderStages::COMPUTE,
        ty: wgpu::BindingType::Buffer {
            ty: match binding.access {
                Access::Uniform => wgpu::BufferBindingType::Uniform,
                Access::Read => wgpu::BufferBindingType::Storage { read_only: true },
                Access::ReadWrite => wgpu::BufferBindingType::Storage { read_only: false },
            },
            has_dynamic_offset: false,
            min_binding_size: None,
        },
        count: None,
    })
    .collect();

Add a parameter to the kernel and this follows along. That is the difference between a layout that is derived and one that is duplicated.

binding.group matters once you use more than one group. Group the entries by it and create one layout per group.

Working out the dispatch size

WORKGROUP_SIZE tells you how many invocations one workgroup runs, so the number of workgroups is your element count divided by that, rounded up:

use unipute::{Kernel, kernel};
#[kernel(workgroup_size(64))]
fn scale(input: &[f32], output: &mut [f32], factor: &f32) {
    let index = global_id().x;
    if index >= input.len() { return; }
    output[index] = input[index] * factor;
}
/// Number of workgroups needed to cover `elements` items.
fn groups_for(elements: u32, workgroup: u32) -> u32 {
    elements.div_ceil(workgroup)
}

fn main() {
    let elements = 100u32;
    let groups = groups_for(elements, scale::WORKGROUP_SIZE[0]);
    assert_eq!(groups, 2); // 2 groups of 64 covers 100
}

Rounding up is why your kernel needs the bounds check. Two groups of 64 is 128 invocations for 100 elements, and the last 28 have to notice and stop. See Your first kernel if that check is not yet a reflex.

The image_blur example does this for two dimensions and prints the numbers, including how many invocations a 1920x1080 picture wastes. See Examples.

Then dispatch:

pass.set_pipeline(&pipeline);
pass.set_bind_group(0, &bind_group, &[]);
pass.dispatch_workgroups(groups, 1, 1);

For two dimensional work, use WORKGROUP_SIZE[1] for the second axis the same way.

Other APIs

The pieces are the same everywhere, only the spelling changes.

Vulkan. Enable spv and hand SPIRV to vkCreateShaderModule as words. BINDINGS maps onto descriptor set layout bindings, with group as the descriptor set number.

Metal. Enable msl and compile MSL with newLibraryWithSource. Metal assigns its own buffer slots rather than using group and binding numbers, so read them from Metal’s reflection instead of BINDINGS.

Direct3D 12. Enable hlsl and compile HLSL with DXC. Bindings appear as register assignments.

OpenGL. Enable glsl and compile GLSL as a compute shader. Bindings appear as layout(binding = ...), and since GLSL has no groups the binding number is the whole address. Choosing targets has the rule that follows from that.

Compiling shaders ahead of time

Nothing stops you writing the generated shaders out to files as part of a build step, since they are just constants:

std::fs::write("shaders/scale.wgsl", scale::WGSL)?;

This is useful for shipping precompiled pipelines, or for feeding SPIR-V through an optimiser before it reaches the driver.