TSL: Introduce events (#31514)

* introduce events

* add js-docs

* Update EventNode.js

* Update EventNode.js

* Update EventNode.js

src/Three.TSL.js

@@ -391,6 +391,8 @@ export const objectRadius = TSL.objectRadius;
 export const objectScale = TSL.objectScale;
 export const objectViewPosition = TSL.objectViewPosition;
 export const objectWorldMatrix = TSL.objectWorldMatrix;
+export const OnObjectUpdate = TSL.OnObjectUpdate;
+export const OnMaterialUpdate = TSL.OnMaterialUpdate;
 export const oneMinus = TSL.oneMinus;
 export const or = TSL.or;
 export const orthographicDepthToViewZ = TSL.orthographicDepthToViewZ;

src/nodes/Nodes.js

@@ -55,6 +55,7 @@ export { default as ReflectorNode } from './utils/ReflectorNode.js';
 export { default as RTTNode } from './utils/RTTNode.js';
 export { default as MemberNode } from './utils/MemberNode.js';
 export { default as DebugNode } from './utils/DebugNode.js';
+export { default as EventNode } from './utils/EventNode.js';
 
 // accessors
 export { default as UniformArrayNode } from './accessors/UniformArrayNode.js';

src/nodes/TSL.js

@@ -43,6 +43,7 @@ export * from './utils/ReflectorNode.js';
 export * from './utils/RTTNode.js';
 export * from './utils/PostProcessingUtils.js';
 export * from './utils/SampleNode.js';
+export * from './utils/EventNode.js';
 
 // three.js shading language
 export * from './tsl/TSLBase.js';

src/nodes/utils/EventNode.js

@@ -0,0 +1,83 @@
+import Node from '../core/Node.js';
+import { NodeUpdateType } from '../core/constants.js';
+import { nodeObject } from '../tsl/TSLCore.js';
+
+/**
+ * EventNode is a node that executes a callback during specific update phases.
+ *
+ * @augments Node
+ */
+class EventNode extends Node {
+
+	static get type() {
+
+		return 'EventNode';
+
+	}
+
+	/**
+	 * Creates an EventNode.
+	 *
+	 * @param {string} eventType - The type of event
+	 * @param {Function} callback - The callback to execute on update.
+	 */
+	constructor( eventType, callback ) {
+
+		super( 'void' );
+
+		this.eventType = eventType;
+		this.callback = callback;
+
+		if ( eventType === EventNode.OBJECT ) {
+
+			this.updateType = NodeUpdateType.OBJECT;
+
+		} else if ( eventType === EventNode.MATERIAL ) {
+
+			this.updateType = NodeUpdateType.RENDER;
+
+		}
+
+	}
+
+	update( frame ) {
+
+		this.callback( frame );
+
+	}
+
+}
+
+EventNode.OBJECT = 'object';
+EventNode.MATERIAL = 'material';
+
+export default EventNode;
+
+/**
+ * Helper to create an EventNode and add it to the stack.
+ *
+ * @param {string} type - The event type.
+ * @param {Function} callback - The callback function.
+ * @returns {EventNode}
+ */
+const createEvent = ( type, callback ) => nodeObject( new EventNode( type, callback ) ).toStack();
+
+/**
+ * Creates an event that triggers a function every time an object (Mesh|Sprite) is rendered.
+ *
+ * The event will be bound to the declared TSL function `Fn()`; it must be declared within a `Fn()` or the JS function call must be inherited from one.
+ *
+ * @param {Function} callback - The callback function.
+ * @returns {EventNode}
+ */
+export const OnObjectUpdate = ( callback ) => createEvent( EventNode.OBJECT, callback );
+
+/**
+ * Creates an event that triggers a function when the first object that uses the material is rendered.
+ *
+ * The event will be bound to the declared TSL function `Fn()`; it must be declared within a `Fn()` or the JS function call must be inherited from one.
+ *
+ * @param {Function} callback - The callback function.
+ * @returns {EventNode}
+ */
+export const OnMaterialUpdate = ( callback ) => createEvent( EventNode.MATERIAL, callback );