GPU.js - GPU Accelerated JavaScript

Common errors

• TypeError: Cannot read properties of undefined (reading 'x')

  cause Attempting to access `this.thread.x` (or `y`/`z`) outside of a GPU.js kernel function, or when `this` context is incorrectly bound.
  fix Ensure `this.thread` is only accessed within the callback function passed to `gpu.createKernel()` or a function called by it that was added via `gpu.addFunction()`.

• WebGL: INVALID_VALUE: texImage2D: width or height is 0

  cause The output dimensions specified in `.setOutput()` resulted in a zero-dimension texture, or input arrays were empty/invalid.
  fix Verify that the arguments passed to `.setOutput([width, height, depth])` are positive integers reflecting the desired output size of the computation. Also, check input array dimensions.

• Error: Function 'someFunction' is not supported.

  cause A JavaScript function or method called inside the kernel could not be transpiled into an equivalent GLSL shader function by GPU.js.
  fix Review the list of supported Math methods and language features in the GPU.js documentation. For custom functions, use `gpu.addFunction()` to provide a transpilable implementation or refactor the logic to use supported operations.

• Error: GLSL failed to compile

  cause The transpiled GLSL code for the kernel contains syntax errors or uses unsupported features for the target WebGL environment, often due to complex JavaScript logic that can't be directly translated.
  fix Simplify the kernel logic. Avoid complex closures, object manipulations, or unsupported data structures within the kernel. Enable debugging (`gpu.setDebug(true)`) and check browser console logs for detailed GLSL compilation errors.

Warnings

• breaking GPU.js v2 introduced new concepts around 'pipelining' for chaining kernels efficiently and explicit texture cloning/cleanup. While these were performance features, they implied new memory management considerations for users chaining kernels, specifically regarding `cleanupPipelineTextureMemory()`.
  Fix: Review the 'Pipelining' and 'Cleanup pipeline texture memory' sections in the documentation for proper memory management when chaining kernels and using `pipeline: true`.
• gotcha External functions (functions not defined within the kernel's scope) cannot be directly called from within a `createKernel` function. The kernel's body is transpiled to GLSL, which does not have access to the surrounding JavaScript scope.
  Fix: Use `gpu.addFunction(yourFunction)` to make helper functions available inside kernels, or define helper functions directly inside the kernel if they are simple enough to be transpiled.
• gotcha The `this` context inside a GPU.js kernel function (`createKernel` callback) refers to the GPU thread's properties (`this.thread.x`, `this.thread.y`, `this.thread.z`) and not the surrounding JavaScript context. Accessing external variables directly from `this` will fail.
  Fix: Pass external variables as arguments to the `createKernel` function or use `constants` in the kernel configuration. Do not attempt to access `this.someVariable` if `someVariable` is not a kernel property.
• breaking Versions 2.8.4 and 2.8.5 addressed significant memory leaks related to texture deallocation. Earlier versions could consume excessive GPU memory, especially with frequent kernel runs or pipeline usage, potentially leading to performance degradation or crashes.
  Fix: Upgrade to GPU.js version 2.8.5 or newer to benefit from memory leak fixes. Ensure `kernel.destroy()` is called when a kernel is no longer needed to explicitly free resources.
• breaking Version 2.8.3 included a fix for a security issue. Details are not publicly disclosed beyond 'Fix Security Issue' in the release notes, but users on older versions are advised to upgrade for security patching.
  Fix: Upgrade to GPU.js version 2.8.3 or newer to mitigate potential security vulnerabilities.

Install

• npm install gpu.js npm
• yarn add gpu.js yarn
• pnpm add gpu.js pnpm

Imports

• GPU
  wrong:

  const GPU = require('gpu.js');

  correct:

  import { GPU } from 'gpu.js';

  For ESM environments (modern Node.js, bundlers), use named import. CommonJS `require` is also supported for Node.js.
• GPU (browser global)
  wrong:

  import { GPU } from 'gpu.js';

  correct:

  const gpu = new GPU();

  When `gpu-browser.min.js` is loaded via a `<script>` tag, `GPU` is available as a global variable. Do not use `import` in this context.
• IKernelFunction

  import { IKernelFunction } from 'gpu.js';

  Import `IKernelFunction` from 'gpu.js' for type-checking kernel functions when using TypeScript, as seen in advanced examples.

Quickstart

This quickstart demonstrates how to set up `gpu.js`, define a GPU kernel for 512x512 matrix multiplication, and execute it, showcasing the basic API for offloading computations.

import { GPU } from 'gpu.js';

// Initialize GPU.js
const gpu = new GPU();

// Define two 512x512 matrices for multiplication
const matrixA = Array(512).fill(0).map(() => Array(512).fill(Math.random()));
const matrixB = Array(512).fill(0).map(() => Array(512).fill(Math.random()));

// Create a GPU accelerated kernel function for matrix multiplication
const multiplyMatrix = gpu.createKernel(function(a: number[][], b: number[][]) {
  let sum = 0;
  for (let i = 0; i < 512; i++) {
    // this.thread.x and this.thread.y represent the current thread's coordinates
    sum += a[this.thread.y][i] * b[i][this.thread.x];
  }
  return sum;
}).setOutput([512, 512]); // Define the output dimensions of the kernel

// Run the kernel with the input matrices
const c = multiplyMatrix(matrixA, matrixB) as number[][];

console.log('Matrix multiplication completed on GPU (or CPU fallback).');
console.log('Resulting matrix dimensions:', c.length, 'x', c[0].length);
// For a real application, you'd inspect 'c' for results.