regl: Fast Functional WebGL Framework

Common errors

• GLSL shader compilation failed: ERROR: 0:1: 'precision' : syntax error

  cause Invalid GLSL syntax or incompatible shader version for the WebGL context.
  fix Review the `frag` and `vert` shader strings for syntax errors, missing semicolons, incorrect variable declarations, or unsupported features. Check WebGL context version compatibility for specific GLSL features.

• WebGL context lost. Unable to recover from software mode. Please restart your browser and reload the Viewer.

  cause The browser's WebGL context has been lost, often due to system resource exhaustion, GPU driver issues, or the browser moving the tab to a different GPU process.
  fix Reload the browser tab or restart the browser. For programmatic handling, implement the context loss and restoration listeners described in the warnings.

• TypeError: regl is not a function

  cause The `regl` module's default export is a factory function that needs to be called to instantiate the `REGL` object. This error occurs if `require('regl')` or `import createREGL from 'regl'` is used without immediately invoking it.
  fix Ensure you call the imported `regl` factory function, typically as `const regl = require('regl')();` or `import createREGL from 'regl'; const regl = createREGL();`.

Warnings

• gotcha When developing with `regl`, especially when using tools like Browserify, runtime error messages and sanity checks are removed by default in production builds to reduce bundle size. This can make debugging difficult in deployed applications.
  Fix: During development, ensure you compile or bundle with a debug flag (e.g., `--debug` for Browserify) to keep error messages and enable source maps. This helps catch issues faster.
• gotcha WebGL contexts can be lost by the browser due to various reasons (e.g., system resource constraints, GPU driver updates, switching GPUs). While `regl` includes basic context loss handling since v1.0.0, applications must be prepared to re-initialize all GPU-resident resources (textures, buffers, shaders) on a `webglcontextrestored` event.
  Fix: Implement a `webglcontextlost` event listener to call `event.preventDefault()` and a `webglcontextrestored` listener to systematically recreate and re-upload all necessary `regl` resources and re-evaluate commands.
• gotcha WebGL resources (buffers, textures, framebuffers, etc.) consume GPU memory. Failing to explicitly `destroy()` these resources when they are no longer needed can lead to memory leaks, especially in applications that frequently create and destroy dynamic content.
  Fix: Call the `.destroy()` method on `regl` resources (e.g., `regl.buffer(...).destroy()`, `regl.texture(...).destroy()`) once they are out of scope or no longer actively used, to free up GPU memory. Manage the lifecycle of these objects carefully.
• breaking In `regl` versions prior to `0.6.0`, the order of arguments for dynamic functions was `(props, context)`. This was changed to `(context, props)` in `v0.6.0` to align with a more consistent pattern.
  Fix: If migrating from very old `regl` code or referencing outdated examples, be aware that dynamic functions now expect `(context, props)` as their argument signature. Adjust function definitions accordingly.

Install

• npm install regl npm
• yarn add regl yarn
• pnpm add regl pnpm

Imports

• regl
  wrong:

  import { regl } from 'regl'; // Incorrect named import, it's a default export (factory)
  const regl = require('regl'); // Missing function call to initialize

  correct:

  import createREGL from 'regl';
  const regl = createREGL();

  The default export is a factory function that creates the REGL instance. CommonJS examples often use `require('regl')()` directly.
• regl (CommonJS)

  const regl = require('regl')();

  This is the prevalent usage pattern in older Node.js environments and many `regl` examples.
• REGL (TypeScript Type)
  wrong:

  import { REGL } from 'regl'; // Imports the runtime value, not just the type

  correct:

  import type { REGL, Buffer, Texture } from 'regl';

  regl ships with TypeScript declarations. Use `import type` for type-only imports to avoid bundling issues and ensure correct type checking.

Quickstart

This example initializes a full-screen WebGL context with regl and draws a single animating triangle, demonstrating core concepts like defining commands with shaders, attributes, and uniforms.

const regl = require('regl')();

const drawTriangle = regl({
  frag: `
    precision mediump float;
    uniform vec4 color;
    void main() {
      gl_FragColor = color;
    }`,

  vert: `
    precision mediump float;
    attribute vec2 position;
    void main() {
      gl_Position = vec4(position, 0, 1);
    }`,

  attributes: {
    position: regl.buffer([
      [-2, -2],
      [4, -2],
      [4, 4]
    ])
  },

  uniforms: {
    color: regl.prop('color')
  },
  count: 3
});

regl.frame(({time}) => {
  regl.clear({
    color: [0, 0, 0, 0],
    depth: 1
  });

  drawTriangle({
    color: [
      Math.cos(time * 0.001),
      Math.sin(time * 0.0008),
      Math.cos(time * 0.003),
      1
    ]
  });
});