Whether you’re a seasoned ThreeJS user or new to the library you need to know about TSL. Shoot over to the ThreeJS website. Select “Examples”, enter TSL and take a few minutes to admire the many examples.

Screenshot

The more observant of you will notice the “webgpu (wip) ” heading. At the moment WebGPU in the ThreeJS library is a work in progress and there is very little documentation available. In this article I hope to make a small contribution to the ThreeJS community to add a little guidance to developers starting out on the TSL Journey.

I know it doesn’t suit everyone but I’m going to use CodePen for the examples.

TSL – A first example

To use TSL you do not use three.module.js. Instead you use three.webgpu.js. The import map is

<script type="importmap">
  {
    "imports": {
      "three": "https://cdn.jsdelivr.net/npm/[email protected]/build/three.webgpu.js",
      "three/tsl": "https://cdn.jsdelivr.net/npm/[email protected]/build/three.webgpu.js",
      "three/addons/": "https://cdn.jsdelivr.net/npm/[email protected]/examples/jsm/"
    }
  }
</script>

In the CodePen examples I’m getting ThreeJS from CDN, if you use npm then just change the paths. Notice the three/tsl definition, all imports related to TSL use this path.

Before we review the code take a look at the CodePen example below. Nothing impressive just a really simple example of using tsl. Switch the mode between positionLocal and texture. The positionLocal sets the colour of a sphere pixel to the value of the local position. A sphere by default has radius 1, so local position values for each axis vary between -1 and 1. Notice that half the sphere is black because the value of each axis is zero or less.

I’ve placed all the TSL related code in the tsl function. This is simply to make it easier for you to focus on it. Click the JS button in the example above to see the JavaScript. First we create a SphereGeometry instance. Nothing new there. But then we create an instance of MeshStandardNodeMaterial. Notice the addition of the Node word. Here we enter TSL land. Then we set the colorNode of the material to positionLocal. Slide up to the start of the code and take a look at the import lines. Notice we import positionLocal and texture from the three/tsl import map definition. To use a TSL node we must import it. We create a Mesh in the usual way and add it to the scene. Then we load a texture.

Finally we create a GUI that allows the user to switch between using positionLocal for the colorNode and texture. Notice the texture function requires a texture passed to the method. When switching the colorNode make sure to set material.needsUpdate to true.

So what happens when you set colorNode equal to positionLocal. Here is a remix of the ThreeJS TSL Editor. When the ThreeJS library is initialising the shader it tries to uses WGSL, WebGPU Shading Language. If WebGPU is not supported it falls back to GLSL ES 3.0. Try commenting out line 5 and uncommenting lines 7 and 8 and see how this affects the WGSL and GLSL code. Notice the use of nodeUniform0 in the compiled shaders. Nodes are key to TSL, as you’ll see as you get deeper into the API.

That’s your opening lesson. In the next lesson we look at math operators.

Next