TSL: Introduce events

[sunag]

Description

I am creating an event API for TSL functions; this way, it becomes easier to update their uniforms according to materials or objects. The events are indexed in the TSL functions Fn(), making it simple to share.

Introduce OnObjectUpdate() and OnMaterialUpdate() functions.

Usage

const myFn = Fn( () => {

	const color = uniform( new THREE.Color() );

	// call this function whenever
	// an object(mesh|sprite) is rendered with this Fn()

	OnObjectUpdate( ( { object } ) => {

		console.log( 'mesh:', object.name );

		// update object uniforms e.g:
		color.value = object.userData.customColor;

	} );

	// call this function whenever 
	// this material instance is rendered with this Fn()

	OnMaterialUpdate( ( { material } ) => {

		console.log( 'material:', material.name );

		// update material uniforms e.g:
		// color.value = material.userData.customColor;

	} );

	return color;

} )();

Setup for this example

material.colorNode = myFn;

material = new THREE.NodeMaterial();
material.name = 'myMaterial';
material.colorNode = myFn;

// assign same material

box.material = 
	sphere.material = 
	plane.material = material;

// creating object new properties

box.userData.customColor = new THREE.Color( 0xff0000 );
sphere.userData.customColor = new THREE.Color( 0x00ff00 );
plane.userData.customColor = new THREE.Color( 0x0000ff );

Result

console.log() - call sequence

--------- Begin render --------------
mesh: box
material: myMaterial
mesh: sphere
mesh: plane
--------- End render -----------------

Visual

[github-actions]

📦 Bundle size

Full ESM build, minified and gzipped.

	Before	After	Diff
WebGL	338.39 78.91	338.39 78.91	+0 B +0 B
WebGPU	561.91 155.44	562.31 155.58	+405 B +141 B
WebGPU Nodes	560.51 155.2	560.92 155.34	+405 B +143 B

🌳 Bundle size after tree-shaking

Minimal build including a renderer, camera, empty scene, and dependencies.

	Before	After	Diff
WebGL	469.77 113.61	469.77 113.61	+0 B +0 B
WebGPU	636.77 172.32	637.03 172.41	+261 B +89 B
WebGPU Nodes	591.42 161.55	591.68 161.64	+261 B +89 B

[mrdoob]

I think it's better to use userData for the examples?

color.value = object.userData.customColor;

[sunag]

I think it's better to use userData for the examples?

Good point, updated.