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

Your own functions

A kernel can declare fn items inside its body and call them, the same way a nested function works in ordinary Rust:

use unipute::kernel;
#[kernel(workgroup_size(64))]
fn tonemap(input: &[f32], output: &mut [f32]) {
    fn compress(value: f32) -> f32 {
        value / (value + 1.0)
    }

    let index = global_id().x;
    if index >= input.len() {
        return;
    }
    output[index] = compress(input[index]);
}

That comes out as two functions in the generated shader, with compress written above the entry point that calls it.

They capture nothing

This is the rule worth reading twice. A nested fn in Rust cannot see the variables around it, and the same is true here, only more so: a nested function cannot reach the kernel’s buffers, its workgroup memory or the hardware built-ins either.

#[kernel(workgroup_size(64))]
fn wrong(input: &[f32], output: &mut [f32]) {
    fn first() -> f32 {
        input[0] // error: `input` is not a parameter or a local variable
    }

    output[0] = first();
}

The reason is not a limitation of Unipute. Shader languages hand bindings and built-ins to the entry point, and a function called from it has no way to ask for them. So a nested function takes what it needs as a parameter:

use unipute::kernel;
#[kernel(workgroup_size(64))]
fn right(input: &[f32], output: &mut [f32]) {
    fn scale(value: f32, by: f32) -> f32 {
        value * by
    }

    let index = global_id().x;
    if index >= input.len() {
        return;
    }
    output[index] = scale(input[index], 2.0);
}

Calling global_id() inside a nested function is rejected for the same reason. Read it in the kernel body and pass it down.

Parameters and results

A parameter is a scalar or a vector, taken by value. Slices cannot be passed, which follows from the rule above: a buffer belongs to the entry point.

A result is a scalar or a vector too, or nothing at all. The body ends with a value or a return, as in Rust:

use unipute::kernel;
#[kernel(workgroup_size(64))]
fn shades(output: &mut [f32]) {
    fn luminance(color: Vec3<f32>) -> f32 {
        // A trailing expression is the return value.
        dot(color, vec3(0.2126, 0.7152, 0.0722))
    }

    fn clamp_up(value: f32) -> f32 {
        if value < 0.0 {
            return 0.0;
        }
        value
    }

    output[global_id().x] = clamp_up(luminance(vec3(0.5, 0.25, 0.75)));
}

One thing Rust allows that a kernel does not is a block used as a value, so if a { b } else { c } cannot be the result of a function. Write a return in each branch instead.

A function that returns nothing is called as a statement:

use unipute::kernel;
#[kernel(workgroup_size(64))]
fn with_a_void_helper(output: &mut [f32]) {
    fn fill(_value: f32) {
        // Nothing useful, but it shows the shape.
    }

    fill(1.0);
    output[0] = 1.0;
}

Order does not matter

Declare them in whichever order reads best. Unipute works out which function calls which and writes them out so that every callee comes before its callers, which is what a shader language needs since none of them have forward declarations.

The one thing that follows from this is that a function cannot call itself, directly or through another function. No shader language supports recursion, so a cycle is a compile error naming the function that closes it.

Where they go

At the top level of the kernel body. A fn inside an if or a loop is rejected, since it would be the only thing in a kernel whose meaning depended on where it appeared.

Two nested functions in the same kernel cannot share a name, and neither can take the name of a built-in such as abs or vec3.

Functions are not shared between kernels. Two kernels that want the same helper each declare it. Sharing one across kernels needs a different surface than #[kernel] offers, and is not built yet.