Radiance

Lightweight, reactive WebGL2 library for building shader-driven experiences.

Radiance removes repetitive WebGL setup while keeping the shader and rendering pipeline close to the native API. Use the high-level canvas API for a quick start, or compose render passes, render targets, textures, and GPU simulations directly.

Documentation · Examples · API reference · Changelog

Features

• Reactive, fully typed uniforms and automatic rendering
• WebGL2 canvas setup with resize and device-pixel-ratio handling
• Full-screen shader rendering with a minimal API
• Composable render, effect, composite-effect, and post-processing passes
• Built-in bloom, trails, and tone-mapping effects
• Image, video, data, and floating-point textures
• Ping-pong framebuffers and transform feedback for GPGPU workflows
• Pointer events, animation loops, and OffscreenCanvas support
• ESM distribution with generated TypeScript declarations

Installation

npm install @radiancejs/gl

pnpm add @radiancejs/gl

yarn add @radiancejs/gl

bun add @radiancejs/gl

Radiance uses WebGL2. Make sure the browser or runtime where it runs provides a WebGL2-capable canvas.

Quick Start

Add a canvas to your page:

<canvas id="glCanvas"></canvas>

Then render a full-screen shader:

import { glCanvas } from "@radiancejs/gl";

glCanvas({
  canvas: "#glCanvas",
  fragment: /* glsl */ `
    varying vec2 vUv; // provided by the default vertex shader
    uniform float uTime;
    uniform vec2 uResolution;

    void main() {
      vec2 uv = (gl_FragCoord.xy * 2.0 - uResolution) / uResolution.y;
      vec3 color = 0.5 + 0.5 * cos(uTime + uv.xyx + vec3(0.0, 2.0, 4.0));
      gl_FragColor = vec4(color, 1.0);
    }
  `,
  uniforms: {
    uTime: ({ time }) => time / 500,
    uResolution: ({ canvasResolution }) => canvasResolution,
  },
});

An animation loop is started if a time uniform is detected. Uniforms are reactive, so changing a value schedules a render:

const canvas = glCanvas({
  canvas: "#glCanvas",
  fragment,
  uniforms: {
    uColor: [1, 0.2, 0.1],
  },
});

canvas.uniforms.uColor = [0.2, 0.8, 1];

Post-processing

Pass built-in effects to postEffects, or create your own effect passes with effectPass and compositor:

import { bloom, glCanvas, hableToneMapping, trails } from "@radiancejs/gl";

glCanvas({
  canvas: "#glCanvas",
  fragment,
  postEffects: [
    bloom({ radius: 0.5, mix: 0.8 }),
    trails({ fadeout: 0.25 }),
    hableToneMapping({ exposure: 1.2 }),
  ],
});

GPU Computation

Radiance includes building blocks for GPU simulations such as particles, boids, fluid-like effects, and cellular automata. pingPongFBO swaps textures between frames, while transformFeedback captures vertex shader outputs in buffers.

import { glContext, pingPongFBO } from "@radiancejs/gl";

const { gl } = glContext({ canvas: "#glCanvas" });

const simulation = pingPongFBO({
  gl,
  fragment: simulationFragment,
  dataTexture: {
    name: "tState",
    initialData: new Float32Array(initialState),
  },
  uniforms: {
    uDeltaTime: 0,
  },
});

simulation.uniforms.uDeltaTime = 1 / 60;
simulation.render();

See the GPGPU examples for complete simulations.

API Overview

The package exports low-level and high-level primitives from one entry point:

• Canvas and context: glCanvas, glContext
• Rendering: renderPass, quadRenderPass, compositor
• Effects: effectPass, compositeEffectPass, bloom, trails, tone mapping
• GPU computation: pingPongFBO, transformFeedback
• Resources: createProgram, createShader, render targets, attributes, textures
• Helpers: loop, onResize, onPointerEvents

Browse the API reference or start with the quick-start guide.

Browser Support

Radiance targets environments with WebGL2 support. Features that use browser APIs such as HTMLVideoElement, ImageBitmap, pointer events, or OffscreenCanvas depend on the runtime providing those APIs.

Contributing

Issues and pull requests are welcome on GitHub. Please include a focused description of the change and, where relevant, an example or regression test.

License

MIT © Julien SULPIS.