Threads and Workgroups

threads describes how many logical invocations your kernel should run.

const kernel = new Kernel(`...`, {
    threads: 1024
});

Volten divides that by the workgroup size to compute the actual dispatch.

Automatic Inference

If there is one clear input buffer, Volten can infer the thread count from its element count.

const input = new Buffer([1, 2, 3, 4], 'f32', 'r');
const output = new Buffer([0, 0, 0, 0], 'f32', 'rw');

const kernel = new Kernel(`...`, {
    outputs: ['output']
});

const node = v.pass(kernel, { input, output });

Here, output is declared as an output, so input.count is used as the logical thread count.

When there are multiple possible input buffers, Volten cannot guess which shape should drive the dispatch. Set threads explicitly.

const kernel = new Kernel(`...`, {
    threads: 'positions'
});

const node = v.pass(kernel, {
    positions,
    velocities,
    output
});

Kernel-Level Threads

Use the threads kernel property when the dispatch shape is part of the kernel’s normal behavior.

const kernel = new Kernel(`...`, {
    threads: 'input'
});

Use a function when the count depends on custom shapes or multiple bindings.

const kernel = new Kernel(`...`, {
    threads: ({ input }) => (input as Buffer).count / 2
});

const kernel = new Kernel(`...`, {
    threads: ({ input1, input2 }) =>
        (input1 as Buffer).count + (input2 as Buffer).count
});

Functions can return a number, [x, y], or [x, y, z]. For most 2D cases, prefer passing the explicit dimensions at pass time.

Pass-Time Threads

Pass-time threads overrides the kernel option.

const node = v.pass(
    kernel,
    { image },
    {
        threads: [width, height]
    }
);

Use this when the same kernel runs over different shapes.

Workgroup Size

workgroupSize controls how invocations are grouped.

const kernel = new Kernel(`...`, {
    threads: 'input',
    workgroupSize: [256]
});

The default is [64, 1, 1].

RawBuffer Cannot Infer Count

RawBuffer tracks bytes, not elements. Specify threads explicitly when a pass only has raw buffers.

const kernel = new Kernel(`...`, {
    threads: 1024
});

// Alternatively:
const node = v.pass(kernel, { rawInputBuffer }, { threads: 1024 });