• Introduction
  • Why TSL?
  • Example
  • Architecture
• Constants and explicit conversions
• Conversions
• Uniform
  • onUpdate
• Swizzle
• Operators
• Function
• Conditional
  • If-else
  • Ternary
• Math
• Method chaining
• Texture
• Attributes
• Position
• Normal
• Tangent
• Bitangent
• Camera
• Model
• Screen
• Viewport
• Blend Modes
• Reflect
• UV Utils
• Interpolation
• Random
• Oscillator
• Packing
• Functions
• NodeMaterial
  • MeshPhongNodeMaterial
  • MeshStandardNodeMaterial
    • MeshPhysicalNodeMaterial
• Transitioning common GLSL properties to TSL

Creating shaders has always been an advanced step for most developers, many game developers have never created GLSL code from scratch. The shader graph solution adopted today by the industry has allowed developers more focused on dynamics to create the necessary graphic effects to meet the demands of their projects.

The aim of the project is to create an easy-to-use, environment for shader creation. Even if for this we need to create complexity behind, this happened initially with Renderer and now with the TSL.

Other benefits that TSL brings besides simplifying shading creation is keeping the renderer agnostic, while all the complexity of a material can be imported into different modules and use tree shaking without breaking during the process.

A detail map makes things look more real in games. It adds tiny details like cracks or bumps to surfaces. In this example we will scale uv to improve details when seen up close and multiply with a base texture.

This is how we would achieve that using .onBeforeCompile():

const material = new THREE.MeshStandardMaterial();
material.map = colorMap;
material.onBeforeCompile = ( shader ) => {

	shader.uniforms.detailMap = { value: detailMap };

	let token = '#define STANDARD';

	let insert = /* glsl */`
		uniform sampler2D detailMap;
	`;

	shader.fragmentShader = shader.fragmentShader.replace( token, token + insert );

	token = '#include <map_fragment>';

	insert = /* glsl */`
		diffuseColor *= texture2D( detailMap, vMapUv * 10.0 );
	`;

	shader.fragmentShader = shader.fragmentShader.replace( token, token + insert );

};

Any simple change from this makes the code increasingly complicated using .onBeforeCompile, the result we have today in the community are countless types of parametric materials that do not communicate with each other, and that need to be updated periodically to be operating, limiting the creativity to create unique materials reusing modules in a simple way.

With TSL the code would look like this:

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

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

const material = new THREE.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.

All TSL components are extended from Node class. 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. It's 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 main class responsible for creating the code is NodeBuilder. This class can be extended to any output programming language, so you can use TSL for a third language if you wish. Currently NodeBuilder has two extended classes, the WGSLNodeBuilder aimed at WebGPU and GLSLNodeBuilder aimed at WebGL2.

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.

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

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

Example:

import { positionWorld } from 'three/tsl';

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

Uniforms are useful to update values of variables like colors, lighting, or transformations without having to recreate the shader program. They are the true variables from a CPU's point of view.

Example:

const posY = uniform( mesh.position.y );

// it's possible use posY.value to update manualy the value
posY.value = mesh.position.y;

material.colorNode = posY;

It is also possible to create update events on uniforms, which can be defined by the user:

Example:

const posY = uniform( 0 ); // it's possible use uniform( 'number' )

// or using event to be done automatically
// { object } will be the current rendering object
posY.onObjectUpdate( ( { object } ) => object.position.y );

material.colorNode = posY;

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.

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

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

It is possible to use classic JS functions or a Fn() interface. The main difference is that Fn() 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:

// tsl function
const oscSine = Fn( ( [ t = timer ] ) => {

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

} );

// inline function
export const oscSine = ( t = timer ) => t.add( 0.75 ).mul( Math.PI * 2 ).sin().mul( 0.5 ).add( 0.5 );

Both above can be called with oscSin( value ).

TSL allows the entry of parameters as objects, this is useful in functions that have many optional arguments.

Example:

const oscSine = Fn( ( { 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__*/

export const oscSawtooth = /*@__PURE__*/ Fn( ( [ timer = timerGlobal ] ) => timer.fract() );

If-else conditionals can be used within tsnFn(). Conditionals in TSL are built using the If function:

If( conditional, function )
.ElseIf( conditional, function )
.Else( function )

Notice here the i in If is capitalized.

Example:

In this example below, we will limit the y position of the geometry to 10.

const limitPosition = Fn( ( { position } ) => {

	const limit = 10;

	// Convert to variable using `.toVar()` to be able to use assignments.
	const result = position.toVec3().toVar();

	If( result.y.greaterThan( limit ), () => {

		result.y = limit;

	} );

	return result;

} );

material.positionNode = limitPosition( { position: positionLocal } );

Example using elseif:

const limitPosition = Fn( ( { position } ) => {

	const limit = 10;

	// Convert to variable using `.toVar()` to be able to use assignments.
	const result = position.toVec3().toVar();

	If( result.y.greaterThan( limit ), () => {

		result.y = limit;

	} ).ElseIf( result.y.lessThan( limit ), () => {

		result.y = limit;

	} );

	return result;

} );

material.positionNode = limitPosition( { position: positionLocal } );

Different from if-else, a ternary conditional will return a value and can be used outside of Fn().

const result = select( value.greaterThan( 1 ), 1.0, value );

Equivalent in JavaScript should be: value > 1 ? 1.0 : value

const value = float( -1 );

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

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

Example:

oneMinus() is a mathematical function like abs(), sin(). This example uses .oneMinus() as a built-in function in the class that returns a new class component and not as a classic C function like oneMinus( texture( map ).rgb ), it is called method chaining.

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

positionLocal represents the position after modifications made by skinning, morpher, etc.

transformed* represents the normal after modifications made by skinning, morpher, etc.

Screen nodes will return the values related to the current frame buffer, either normalized or in physical pixel units considering the current Pixel Ratio.

viewport is influenced by the area defined in renderer.setViewport(), different of the values ​​defined in the renderer that are logical pixel units, it use physical pixel units considering the current Pixel Ratio.

import { texture, matcapUV } from 'three/tsl';

const matcap = texture( matcapMap, matcapUV );

To create a variable from a node use .toVar().

The first parameter is used to add a name to it, otherwise the node system will name it automatically, it can be useful in debugging or access using wgslFn.

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

material.colorNode = texture( map, uvScaled );

Let's suppose you want to optimize some calculation in the vertex stage but are using it in a slot like material.colorNode.

For example:

// 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();

The first parameter of varying modelNormalMatrix.mul( normalLocal ) will be executed in vertex stage, and the return from varying() will be a varying as we are used in WGSL/GLSL, this can optimize extra calculations in the fragment stage. The second parameter allows you to add a custom name to varying.

If varying() is added only to .positionNode, it will only return a simple variable and varying will not be created.

Check below for more details about NodeMaterial inputs.