Skip to content

Render in a worker with OffscreenCanvas ​

If drawing on the main thread competes with layout and input, move it to a worker. glCanvas and glContext accept an OffscreenCanvas wherever they accept an element or selector.

Transfer the canvas ​

ts
// main.ts
const canvas = document.querySelector("#glCanvas")!;
const offscreen = canvas.transferControlToOffscreen();

const worker = new Worker(new URL("./render.worker.ts", import.meta.url), { type: "module" });
worker.postMessage({ canvas: offscreen }, [offscreen]);
ts
// render.worker.ts
import { glCanvas } from "@radiancejs/gl";

self.onmessage = ({ data }) => {
  const { canvas } = data as { canvas: OffscreenCanvas };

  const { uniforms, render } = glCanvas({
    canvas, // an OffscreenCanvas — no DOM required
    fragment,
    uniforms: {
      uTime: ({ time }) => time / 1000,
      uPointer: [0, 0],
    },
    renderMode: "manual", // see "Sizing" below
  });

  self.onmessage = ({ data }) => {
    uniforms.uPointer = data.pointer;
    render();
  };
};

glContext throws Canvas element not found. when the selector matches nothing (or in a worker, where there is no document); a canvas that was already transferred makes the browser's getContext throw InvalidStateError.

Sizing ​

An OffscreenCanvas has no CSS layout box, so Radiance does not install a resize observer for it — same as a canvas that already has width/height attributes. Size it yourself and forward layout changes from the page:

ts
// main.ts — observe the visible canvas and forward its CSS size
const observer = new ResizeObserver(([entry]) => {
  const { width, height } = entry.contentRect;
  worker.postMessage({ size: { width, height } });
});
observer.observe(canvas);
ts
// render.worker.ts
const { setSize, render } = glCanvas({ canvas, fragment, renderMode: "manual" });

self.onmessage = ({ data }) => {
  if (data.size) {
    setSize({
      width: data.size.width * self.devicePixelRatio,
      height: data.size.height * self.devicePixelRatio,
    });
    render();
  }
};

setSize resizes the canvas and every managed render target in one call. See Handle resize and device pixel ratio for what the values mean.

Render mode in a worker ​

Reactive updates still work — uniforms is a proxy and auto schedules frames with requestAnimationFrame, which exists in workers. What you lose is easy access to DOM-driven input and visibility. Two workable setups:

SetupNotes
renderMode: "auto" + post every pointer/resize messagethe worker renders when messages change uniforms
renderMode: "manual" + render() after each messageexplicit; no hidden scheduling
renderMode: "continuous" for uTime-driven workthe worker owns its clock; play/pause via messages
ts
worker.postMessage({ type: "pause" }); // ← your message protocol
ts
// render.worker.ts
const { play, pause, render, uniforms } = glCanvas({ /* … */ });

self.onmessage = ({ data }) => {
  if (data.type === "pause") pause();
  if (data.type === "play") play();
};

What crosses the boundary ​

Everything you send is structured-cloned (or transferred). Keep the traffic dumb:

SendDo not send
plain numbers / arraysclass instances, DOM nodes (after transfer)
transferred ArrayBufferscopied large buffers on every frame
coarse state (pointer, time)per-frame uniform dumps

Uniform sources that fetch (like loadTexture) work in a worker — fetch and createImageBitmap are available there — as long as the URL is CORS-enabled. See Sample images, videos and data.

Feature detection

OffscreenCanvas + WebGL2 is widely available in current browsers, but not universal. Keep the main-thread path as a fallback when you need to support older ones:

ts
const target = canvas.transferControlToOffscreen
  ? canvas.transferControlToOffscreen()
  : canvas;

See also ​

Released under the MIT License.