Three.js Shading Language

With TSL the code would look like this:

import { texture, uv } from 'three/tsl'

const detail = texture( detailMap, uv().mul( 10 ) );

const material = new MeshStandardNodeMaterial();
material.colorNode = texture( colorMap ).mul( detail );

TSL is also capable of encoding code into different outputs such as WGSL/GLSL – WebGPU/WebGL, in addition to optimizing the shader graph automatically and through codes that can be inserted within each Node. This allows the developer to focus on productivity and leave the graphical management part to the Node System.

Another important feature of a graph shader is that we will no longer need to care about the sequence in which components are created, because the Node System will only declare and include it once.

Let’s say that you import positionWorld into your code, even if another component uses it, the calculations performed to obtain position world will only be performed once, as is the case with any other renderer component such as: normalWorld, modelPosition, etc.

Architeture

All TSL component is created from a Node. The Node allows it to communicate with any other, value conversions can be automatic or manual, a Node can receive the output value expected by the parent Node and modify its own output snippet.

Since they are all components are extended from the Node class, it is possible to modulate them using tree shaking. In the shader construction process, the Node will have important information such as geometry, material, renderer as well as the backend, which can influence the type and value of output.

The build process is based on three pillars: setup, analyze and generate.

Node also have a native update process invoked by the update() function, these events be called by frame, render call and object draw.

It is also possible to serialize or deserialize a Node using serialize() and deserialize() functions.

Constants and explicit conversions

Input functions can be used to create contants and do explicit conversions.

Conversions are also performed automatically if the output and input are of different types.

Example:

import { color, vec2, positionWorld } from 'three/tsl';

// constant
material.colorNode = color( 0x0066ff );

// conversion
material.colorNode = vec2( positionWorld ); // result positionWorld.xy

Conversions

It is also possible to perform conversions using the method chain:

Example:

import { positionWorld } from 'three/tsl';

// conversion
material.colorNode = positionWorld.toVec2(); // result positionWorld.xy

Method chaining

Method chaining will only be including operators, converters, math and some core functions. These functions, however, can be used on any node.

Example:

// it will invert the texture color
material.colorNode = texture( map ).rgb.oneMinus();

Swizzle

Swizzling is the technique that allows you to access, reorder, or duplicate the components of a vector using a specific notation within TSL. This is done by combining the identifiers:

const original = vec3( 1.0, 2.0, 3.0 ); // (x, y, z)
const swizzled = original.zyx; // swizzled = (3.0, 2.0, 1.0)

It’s possible use xyzw, rgba or stpq.

Operators

const a = float( 1 );
const b = float( 2 );

const result = a.add( b ); // output: 3

Functions

tslFn( function )

It is possible to use classic JS functions or a tslFn() interface. The main difference is that tslFn() creates a controllable environment, allowing the use of stack where you can use assign and conditional, while the classic function only allows inline approaches.

Example:

const oscSine = tslFn( ( { timer = timerGlobal } ) => {

	return timer.add( 0.75 ).mul( Math.PI * 2 ).sin().mul( 0.5 ).add( 0.5 );

} );

const value = oscSine( { timer: value } );

If you want to use an export function compatible with tree shaking, remember to use /*@__PURE__*/

const value = float( -1 );

// It's possible use `value.abs()` too.
const positiveValue = abs( value ); // output: 1

const uvScaled = uv().mul( 10 ).toVar();

material.colorNode = texture( map, uvScaled );

// multiplication will be executed in vertex stage
const normalView = varying( modelNormalMatrix.mul( normalLocal ) );

// normalize will be executed in fragment stage
// because .colorNode is fragment stage slot as default
material.colorNode = normalView.normalize();

Read More