@typegpu/three

TSL (Three.js Shading Language) is a node-based shader composition system for Three.js. Shader logic and control flow is built up by composing special functions, with a focus on composability, intuitive sharing of logic across modules and customizability. TypeGPU fits naturally into this system thanks to the @typegpu/three package. You can choose to write your TSL building blocks in TypeGPU, which has a few benefits:

• Control-flow like if statements and for loops makes use of familiar JavaScript syntax instead of special functions.
• The code you write is semantically valid JavaScript, with types flowing through each expression.
• Unit-testability, since you can call these functions on the CPU

You can see a direct comparison between TSL and TypeGPU here.

Caution

If your end user’s device doesn’t support WebGPU, Three.js enables a WebGL fallback. Currently, using @typegpu/three makes your app only work on WebGPU-enabled devices. If you need WebGL support, bombard this issue with reactions and state your use case in the comments.

Setup

Refer to TypeGPU’s installation guide for setting up TypeGPU if you haven’t already. After that, install Three.js and @typegpu/three using the package manager of your choice.

npm

npm install three @typegpu/three

pnpm

pnpm add three @typegpu/three

yarn

yarn add three @typegpu/three

Using TypeGPU with TSL

Calling t3.toTSL with a TypeGPU function will return a TSL node, which can then be plugged into material properties, or used by other nodes.

import * as THREE from 'three/webgpu';
import * as t3 from '@typegpu/three';

const material = new THREE.MeshBasicNodeMaterial();

material.colorNode = t3.toTSL(() => {
  'use gpu';
  return d.vec4f(1, 0, 0, 1); // just red
});

We can use other TSL nodes within TypeGPU functions with t3.fromTSL:

import * as THREE from 'three/webgpu';
import * as TSL from 'three/tsl';
import * as t3 from '@typegpu/three';

const material = new THREE.MeshBasicNodeMaterial();

const albedo = TSL.color('magenta').mul(0.5);
const albedoAccess = t3.fromTSL(albedo, d.vec3f);

material.colorNode = t3.toTSL(() => {
  'use gpu';
  return d.vec4f(albedoAccess.$, 1);
});

There are a handful of builtin TSL node accessors in the t3 namespace:

import * as THREE from 'three/webgpu';
import * as t3 from '@typegpu/three';

const material = new THREE.MeshBasicNodeMaterial();

material.colorNode = t3.toTSL(() => {
  'use gpu';
  const uv = t3.uv().$;
  return d.vec4f(uv, 0, 1);
});

Other TypeGPU functions (user-defined or from libraries) can be called to achieve more complex effects.

import { perlin3d } from '@typegpu/noise';
import * as THREE from 'three/webgpu';
import * as t3 from '@typegpu/three';

const material = new THREE.MeshBasicNodeMaterial();

material.colorNode = t3.toTSL(() => {
  'use gpu';
  const coords = t3.uv().$.mul(2);
  const pattern = perlin3d.sample(d.vec3f(coords, t3.time.$ * 0.2));
  return d.vec4f(std.tanh(pattern * 5), 0.2, 0.4, 1);
});

The code and interactive preview of this example can be found here.

Differences between TSL and TypeGPU

Below are a select few cases comparing TSL and TypeGPU:

Node definition

TSL:

const simulate = Fn(() => {
  //
  // ... TSL code ...
  //
});

TypeGPU:

const simulate = t3.toTSL(() => {
  'use gpu';
  //
  // ... TypeGPU code ...
  //
});

Function definition

TSL:

const oscSine = Fn(([t = time]) => {
  return t.add(0.75).mul(Math.PI * 2).sin().mul(0.5).add(0.5);
});

TypeGPU:

const oscSine = (t: number) => {
  'use gpu';
  return std.sin((t + 0.75) * Math.PI * 2) * 0.5 + 0.5;
};

If statements

TSL:

If(instanceIndex.greaterThanEqual(uint(vertexCount)), () => {
  Return();
});

TypeGPU:

if (t3.instanceIndex.$ >= vertexCount) {
  return;
}

For loops

TSL:

Loop({ start: ptrStart, end: ptrEnd, type: 'uint', condition: '<' }, ({ i }) => {
  const springId = springListBuffer.element( i ).toVar( 'springId' );
  const springForce = springForceBuffer.element( springId );
  const springVertexIds = springVertexIdBuffer.element( springId );
  const factor = select( springVertexIds.x.equal( instanceIndex ), 1.0, - 1.0 );
  force.addAssign( springForce.mul( factor ) );
});

TypeGPU:

for (let i = ptrStart; i < ptrEnd; i++) {
  const springId = springListBuffer.$[i];
  const springForce = springForceBuffer.$[springId];
  const springVertexIds = springVertexIdBuffer.$[springId];
  const factor = std.select(-1, 1, springVertexIds.x === idx);
  force = force.add(springForce.mul(d.f32(factor)));
}