GPU.js Kernel Without Output Dimensions

Invoking a GPU.js kernel without specifying an output dimension causes the library to fail immediately, throwing a runtime error before any computation occurs. Because GPU computing relies on parallel hardware threads mapped directly to memory buffers, GPU.js cannot compile or dispatch the WebGL or WebGPU shader without a predefined output size. This article explains the exact behavior, the mechanism behind the failure, and how to define output dimensions correctly.

The Immediate Error

When you create and invoke a kernel without setting its dimensions, GPU.js throws an error during the validation and compilation phase:

Error: output dimensions are required

The function fails synchronously. It does not fall back to a default size (such as [1]), nor does it infer the size from the input arguments.

Why GPU.js Requires Output Dimensions

CPUs iterate through loops sequentially, but GPUs execute code massively in parallel. GPU.js translates your JavaScript function into a fragment shader and renders the result onto a texture:

  1. Thread Allocation: The output dimensions define the exact grid size of GPU threads. Without a specified grid, the graphics driver does not know how many parallel instances of the kernel to dispatch.
  2. Memory Allocation: In WebGL and WebGPU, the output must be written to an allocated memory buffer or texture of a fixed width and height. Without dimensions, GPU.js cannot allocate the destination buffer to store the results.
  3. Thread Indexing (this.thread): Inside the kernel, properties like this.thread.x, this.thread.y, and this.thread.z rely on the grid bounds to compute each thread's unique coordinate.

Example of the Problem

The following code omits the dimensions and causes a crash:

const { GPU } = require('gpu.js');
const gpu = new GPU();

// Creating a kernel without setting output
const multiplyMatrix = gpu.createKernel(function(a, b) {
    return a[this.thread.x] * b[this.thread.x];
});

// Invoking the kernel throws an Error: output dimensions are required
multiplyMatrix([1, 2, 3], [4, 5, 6]);

How to Correctly Set Output Dimensions

You must define the output dimensions before invoking the kernel. This can be done in two ways:

Method 1: Chaining .setOutput()

Chain the .setOutput() method directly to the kernel declaration:

const multiplyMatrix = gpu.createKernel(function(a, b) {
    return a[this.thread.x] * b[this.thread.x];
}).setOutput([3]); // 1D array of length 3

const result = multiplyMatrix([1, 2, 3], [4, 5, 6]);

Method 2: Defining Output in Options

Pass the dimensions within the kernel's configuration object:

const multiplyMatrix = gpu.createKernel(function(a, b) {
    return a[this.thread.x] * b[this.thread.x];
}, {
    output: [3]
});

const result = multiplyMatrix([1, 2, 3], [4, 5, 6]);

GPU.js accepts 1D arrays ([width]), 2D arrays ([width, height]), and 3D arrays ([width, height, depth]). Providing these dimensions ensures the runtime accurately allocates hardware resources and returns the computed data structure.