Threads and Workgroups

threads describes how many logical invocations your kernel should run.

const processValues = kernel({
    shader: `...`,
    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 copyValues = kernel({
    shader: `...`,
    outputs: ['output']
});

const node = copyValues({ 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 updatePositions = kernel({
    shader: `...`,
    // the number of elements in positions will
    // determine the threads count
    threads: 'positions'
});

const node = updatePositions({
    positions,
    velocities,
    output
});

Kernel-Level Threads

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

const processValues = kernel({
    shader: `...`,
    threads: 'input'
});

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

const processHalf = kernel({
    shader: `...`,
    threads: ({ input }) => (input as Buffer).count / 2
});
const processCombined = kernel({
    shader: `...`,
    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.

Invocation-Time Threads

Invocation-time threads overrides the kernel definition.

const processImage = kernel({ shader: `...` });
const node = processImage(
    { image },
    {
        threads: [width, height]
    }
);

Use this when the same kernel runs over different shapes.

Workgroup Size

workgroupSize controls how invocations are grouped.

const processValues = kernel({
    shader: `...`,
    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 processRawData = kernel({
    shader: `...`,
    threads: 1024
});
// Alternatively:
const node = processRawData({ rawInputBuffer }, { threads: 1024 });