Threejs Impl Webgpu

threejs-impl-webgpu

EXPERIMENTAL — The WebGPU renderer and TSL are under active development. API surfaces may change between Three.js releases. Pin your Three.js version.

Quick Reference

WebGPURenderer Setup

import * as THREE from 'three/webgpu';

const renderer = new THREE.WebGPURenderer({ antialias: true });
await renderer.init(); // MUST await before first render
renderer.setSize(window.innerWidth, window.innerHeight);
renderer.setAnimationLoop(animate);
document.body.appendChild(renderer.domElement);

ALWAYS call await renderer.init() before the first renderer.render() call. ALWAYS use renderer.setAnimationLoop(callback) instead of requestAnimationFrame. NEVER call renderer.render() before init() resolves — this throws a runtime error.

Browser Support

Feature Detection and Fallback

import { WebGPU } from 'three/webgpu';

if (WebGPU.isAvailable()) {
  const renderer = new THREE.WebGPURenderer({ antialias: true });
  await renderer.init();
} else {
  const renderer = new THREE.WebGLRenderer({ antialias: true });
}

ALWAYS check WebGPU.isAvailable() before creating a WebGPURenderer. ALWAYS provide a WebGLRenderer fallback for unsupported browsers.

Critical Warnings

NEVER write raw GLSL or WGSL strings — ALWAYS use TSL functions. WebGPU compiles TSL to WGSL automatically. GLSL is NOT supported by the WebGPU backend.

NEVER use ShaderMaterial with WebGPURenderer — use NodeMaterial with TSL instead.

NEVER use requestAnimationFrame with WebGPURenderer — ALWAYS use renderer.setAnimationLoop().

NEVER use EffectComposer (three/examples) with WebGPURenderer — use the PostProcessing class with TSL nodes instead.

Node Materials

Every classic Three.js material has a node-based equivalent. Classic materials auto-convert when used with WebGPURenderer, but node materials provide full TSL customization.

Material Mapping

ALWAYS import node materials from 'three/webgpu', not from 'three'.

NodeMaterial Input Properties

All properties accept TSL node values. All are optional and override defaults.

Common inputs (all node materials):

Standard/Physical inputs:

Physical-only inputs: .clearcoatNode, .clearcoatRoughnessNode, .clearcoatNormalNode, .sheenNode, .iridescenceNode, .iridescenceIORNode, .iridescenceThicknessNode, .specularIntensityNode, .specularColorNode, .iorNode, .transmissionNode, .thicknessNode, .attenuationDistanceNode, .attenuationColorNode, .dispersionNode, .anisotropyNode.

TSL (Three Shading Language)

TSL is a JavaScript-based node graph system that compiles to GLSL (WebGL2) and WGSL (WebGPU). It replaces raw shader strings entirely.

Type System

Variables and Uniforms

Uniforms support callbacks: .onRenderUpdate(fn), .onFrameUpdate(fn), .onObjectUpdate(fn).

Operators

All operators are chainable on TSL nodes:

• Arithmetic: .add(), .sub(), .mul(), .div(), .mod()
• Comparison: .equal(), .notEqual(), .lessThan(), .greaterThan(), .lessThanEqual(), .greaterThanEqual()
• Logical: .and(), .or(), .not(), .xor()
• Assignment: .assign(), .addAssign(), .subAssign(), .mulAssign(), .divAssign()
• Bitwise: .bitAnd(), .bitOr(), .bitXor(), .shiftLeft(), .shiftRight()

Geometry Nodes

Camera and Model Nodes

• Camera: cameraNear, cameraFar, cameraPosition, cameraProjectionMatrix, cameraViewMatrix, cameraWorldMatrix, cameraNormalMatrix
• Model: modelViewMatrix, modelNormalMatrix, modelWorldMatrix, modelPosition, modelScale, modelDirection

Animation Nodes

Texture Operations

Control Flow

ALWAYS use capital If — lowercase if is JavaScript, not TSL.

If(condition, () => {
  // true branch
}).ElseIf(otherCondition, () => {
  // else-if branch
}).Else(() => {
  // false branch
});

• select(condition, trueVal, falseVal) — ternary operator
• Loop(count, ({ i }) => { }) — GPU loop, supports Break(), Continue()
• Switch(value).Case(val, fn).Default(fn) — no fallthrough
• Discard() — discard fragment
• Return() — early return

Function Definition

const myFn = Fn(([param1, param2]) => {
  return param1.add(param2);
});
// Call: myFn(nodeA, nodeB)

Compute Shaders

WebGPU enables general-purpose GPU compute via TSL. Compute shaders are NOT available in WebGL fallback mode.

Setup

import { compute, storage } from 'three/webgpu';

const computeNode = compute(shaderFn, count, workgroupSize);
await renderer.computeAsync(computeNode);

ALWAYS use await renderer.computeAsync() — compute dispatch is asynchronous.

Storage and Atomics

• Storage: storage(attribute, type, count), storageTexture(texture)
• Atomics: atomicAdd(), atomicSub(), atomicMax(), atomicMin(), atomicAnd(), atomicOr(), atomicXor(), atomicStore(), atomicLoad()
• Barriers: workgroupBarrier(), storageBarrier(), textureBarrier()
• Built-in IDs: workgroupId, localId, globalId, numWorkgroups, subgroupSize

WebGPU Post-Processing

NEVER use the WebGL EffectComposer with WebGPURenderer. Use the PostProcessing class instead.

import { PostProcessing } from 'three/webgpu';
import { bloom, renderOutput } from 'three/tsl';

const postProcessing = new PostProcessing(renderer);
const scenePass = renderOutput(scene, camera);
postProcessing.outputNode = bloom(scenePass);

Available Post-Processing Nodes

bloom(), dof(), fxaa(), smaa(), gaussianBlur(), ssr(), ssgi(), ao(), chromaticAberration(), film(), dotScreen(), sobel(), afterImage(), anamorphic(), denoise(), lut3D(), motionBlur(), outline(), rgbShift(), transition(), traa(), renderOutput()

Color Operations

luminance(), saturation(), vibrance(), hue(), posterize(), grayscale(), sepia()

Blend Modes

blendBurn(), blendDodge(), blendOverlay(), blendScreen(), blendColor()

WebGL to WebGPU Migration

ALWAYS make the entry point async when using WebGPURenderer — renderer.init() returns a Promise.

Reference Links

• references/methods.md — API signatures for WebGPURenderer, NodeMaterial, TSL, compute
• references/examples.md — Working code examples for WebGPU scenes
• references/anti-patterns.md — Common mistakes and how to avoid them

Official Sources

• https://threejs.org/docs/
• https://github.com/mrdoob/three.js/wiki/Three.js-Shading-Language
• https://threejs.org/examples/?q=webgpu