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

Built-ins and functions

This is everything Unipute provides. A kernel can also call functions you declare inside it, which Your own functions covers.

Knowing where you are

A kernel runs once per invocation. These tell an invocation which one it is.

CallTypeMeaning
global_id()Vec3<u32>position in the whole dispatch
local_id()Vec3<u32>position inside this workgroup
local_index()u32local_id flattened to one number
workgroup_id()Vec3<u32>which workgroup this is
num_workgroups()Vec3<u32>how many workgroups were dispatched

global_id() is the one you want most of the time. For one dimensional work it is the index into your buffer:

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

For two dimensional work, use two components and a width uniform to flatten them:

use unipute::kernel;
#[kernel(workgroup_size(8, 8))]
fn two_dimensional(output: &mut [f32], width: &u32, height: &u32) {
    let cell = global_id();
    if cell.x >= width {
        return;
    }
    if cell.y >= height {
        return;
    }
    output[cell.y * width + cell.x] = 1.0;
}

Notice the bounds check on both axes. A workgroup of 8 by 8 over an image that is not a multiple of 8 in each direction will run invocations past the edge.

The relationship between them is worth keeping in mind:

global_id = workgroup_id * workgroup_size + local_id

local_index() is what you use to index into workgroup memory, since it runs from zero to one less than the workgroup size, and workgroup_id() is where a result for the whole group goes. Everywhere else, global_id() covers almost everything.

Barriers

workgroup_barrier() and storage_barrier(), both taking no arguments. The first is what makes a write to workgroup memory visible to the rest of the group. See Control flow for when you need them and the rule about keeping them out of branches.

Buffer length

.len() on a slice parameter gives its length in elements, as a u32:

use unipute::kernel;
#[kernel(workgroup_size(64))]
fn lengths(input: &[f32], output: &mut [u32]) {
    output[0] = input.len();
}

It only works on a parameter, not on an arbitrary expression, and it is the only method a kernel can call.

Building vectors

vec2(x, y), vec3(x, y, z) and vec4(x, y, z, w). All the components have to agree on a type:

use unipute::kernel;
#[kernel(workgroup_size(64))]
fn make_vectors(output: &mut [f32]) {
    let a = vec3(1.0, 0.0, 0.0);
    let b = vec3(0.0, 1.0, 0.0);
    output[0] = dot(a, b);
}

Numeric functions

All of these are available. Most take and return whatever type you give them, so abs works on a scalar or a vector.

ArgumentsFunctions
oneabs, sign, sqrt, inverse_sqrt, exp, log, floor, ceil, round, sin, cos, tan, length, normalize
twomin, max, pow, step, dot, cross
threeclamp, mix, fma

The ones worth explaining

mix(a, b, t) blends between a and b. At t = 0 you get a and at t = 1 you get b.

step(edge, x) gives 0 when x < edge and 1 otherwise. Together with mix it replaces a lot of small branches:

use unipute::kernel;
#[kernel(workgroup_size(64))]
fn branchless(input: &[f32], output: &mut [f32]) {
    let index = global_id().x;
    if index >= input.len() {
        return;
    }
    let value = input[index];

    // The same as: if value < 0.5 { 0.0 } else { 1.0 }
    output[index] = step(0.5, value);
}

clamp(x, low, high) keeps x between the two bounds.

fma(a, b, c) is a * b + c done in one step, which is both faster and more accurate than writing it out.

dot and length collapse a vector down to a single number. cross takes two three component vectors and gives another one.

What you cannot call

A free function declared outside the kernel, including another #[kernel]. The macro only sees the function it is attached to, so a helper has to be declared inside the kernel body. See Your own functions.