@needle-tools/three 0.169.20 → 0.183.2-canary.0

package/src/nodes/utils/FunctionOverloadingNode.js

@@ -1,6 +1,13 @@
 import Node from '../core/Node.js';
-import { nodeProxy } from '../tsl/TSLBase.js';
-
+import { nodeProxy } from '../tsl/TSLCore.js';
+
+/**
+ * This class allows to define multiple overloaded versions
+ * of the same function. Depending on the parameters of the function
+ * call, the node picks the best-fit overloaded version.
+ *
+ * @augments Node
+ */
 class FunctionOverloadingNode extends Node {
 
 	static get type() {
@@ -9,35 +16,79 @@ class FunctionOverloadingNode extends Node {
 
 	}
 
+	/**
+	 * Constructs a new function overloading node.
+	 *
+	 * @param {Array<Function>} functionNodes - Array of `Fn` function definitions.
+	 * @param {...Node} parametersNodes - A list of parameter nodes.
+	 */
 	constructor( functionNodes = [], ...parametersNodes ) {
 
 		super();
 
+		/**
+		 * Array of `Fn` function definitions.
+		 *
+		 * @type {Array<Function>}
+		 */
 		this.functionNodes = functionNodes;
-		this.parametersNodes = parametersNodes;
 
-		this._candidateFnCall = null;
+		/**
+		 * A list of parameter nodes.
+		 *
+		 * @type {Array<Node>}
+		 */
+		this.parametersNodes = parametersNodes;
 
+		/**
+		 * The selected overloaded function call.
+		 *
+		 * @private
+		 * @type {ShaderCallNodeInternal}
+		 */
+		this._candidateFn = null;
+
+		/**
+		 * This node is marked as global.
+		 *
+		 * @type {boolean}
+		 * @default true
+		 */
 		this.global = true;
 
 	}
 
-	getNodeType() {
+	/**
+	 * This method is overwritten since the node type is inferred from
+	 * the function's return type.
+	 *
+	 * @param {NodeBuilder} builder - The current node builder.
+	 * @return {string} The node type.
+	 */
+	getNodeType( builder ) {
+
+		const candidateFn = this.getCandidateFn( builder );
 
-		return this.functionNodes[ 0 ].shaderNode.layout.type;
+		return candidateFn.shaderNode.layout.type;
 
 	}
 
-	setup( builder ) {
+	/**
+	 * Returns the candidate function for the current parameters.
+	 *
+	 * @param {NodeBuilder} builder - The current node builder.
+	 * @return {FunctionNode} The candidate function.
+	 */
+	getCandidateFn( builder ) {
 
 		const params = this.parametersNodes;
 
-		let candidateFnCall = this._candidateFnCall;
+		let candidateFn = this._candidateFn;
 
-		if ( candidateFnCall === null ) {
+		if ( candidateFn === null ) {
 
-			let candidateFn = null;
-			let candidateScore = - 1;
+			let bestCandidateFn = null;
+			let bestScore = - 1;
 
 			for ( const functionNode of this.functionNodes ) {
 
@@ -54,7 +105,7 @@ class FunctionOverloadingNode extends Node {
 
 				if ( params.length === inputs.length ) {
 
-					let score = 0;
+					let currentScore = 0;
 
 					for ( let i = 0; i < params.length; i ++ ) {
 
@@ -63,20 +114,16 @@ class FunctionOverloadingNode extends Node {
 
 						if ( param.getNodeType( builder ) === input.type ) {
 
-							score ++;
-
-						} else {
-
-							score = 0;
+							currentScore ++;
 
 						}
 
 					}
 
-					if ( score > candidateScore ) {
+					if ( currentScore > bestScore ) {
 
-						candidateFn = functionNode;
-						candidateScore = score;
+						bestCandidateFn = functionNode;
+						bestScore = currentScore;
 
 					}
 
@@ -84,11 +131,25 @@ class FunctionOverloadingNode extends Node {
 
 			}
 
-			this._candidateFnCall = candidateFnCall = candidateFn( ...params );
+			this._candidateFn = candidateFn = bestCandidateFn;
 
 		}
 
-		return candidateFnCall;
+		return candidateFn;
+
+	}
+
+	/**
+	 * Sets up the node for the current parameters.
+	 *
+	 * @param {NodeBuilder} builder - The current node builder.
+	 * @return {Node} The setup node.
+	 */
+	setup( builder ) {
+
+		const candidateFn = this.getCandidateFn( builder );
+
+		return candidateFn( ...this.parametersNodes );
 
 	}
 
@@ -98,4 +159,12 @@ export default FunctionOverloadingNode;
 
 const overloadingBaseFn = /*@__PURE__*/ nodeProxy( FunctionOverloadingNode );
 
+/**
+ * TSL function for creating a function overloading node.
+ *
+ * @tsl
+ * @function
+ * @param {Array<Function>} functionNodes - Array of `Fn` function definitions.
+ * @returns {FunctionOverloadingNode}
+ */
 export const overloadingFn = ( functionNodes ) => ( ...params ) => overloadingBaseFn( functionNodes, ...params );

package/src/nodes/utils/JoinNode.js

@@ -1,5 +1,13 @@
 import TempNode from '../core/TempNode.js';
-
+import { error } from '../../utils.js';
+
+/**
+ * This module is part of the TSL core and usually not used in app level code.
+ * It represents a join operation during the shader generation process.
+ * For example in can compose/join two single floats into a `vec2` type.
+ *
+ * @augments TempNode
+ */
 class JoinNode extends TempNode {
 
 	static get type() {
@@ -8,14 +16,32 @@ class JoinNode extends TempNode {
 
 	}
 
+	/**
+	 * Constructs a new join node.
+	 *
+	 * @param {Array<Node>} nodes - An array of nodes that should be joined.
+	 * @param {?string} [nodeType=null] - The node type.
+	 */
 	constructor( nodes = [], nodeType = null ) {
 
 		super( nodeType );
 
+		/**
+		 * An array of nodes that should be joined.
+		 *
+		 * @type {Array<Node>}
+		 */
 		this.nodes = nodes;
 
 	}
 
+	/**
+	 * This method is overwritten since the node type must be inferred from the
+	 * joined data length if not explicitly defined.
+	 *
+	 * @param {NodeBuilder} builder - The current node builder.
+	 * @return {string} The node type.
+	 */
 	getNodeType( builder ) {
 
 		if ( this.nodeType !== null ) {
@@ -31,21 +57,48 @@ class JoinNode extends TempNode {
 	generate( builder, output ) {
 
 		const type = this.getNodeType( builder );
+		const maxLength = builder.getTypeLength( type );
+
 		const nodes = this.nodes;
 
 		const primitiveType = builder.getComponentType( type );
 
 		const snippetValues = [];
 
+		let length = 0;
+
 		for ( const input of nodes ) {
 
-			let inputSnippet = input.build( builder );
+			if ( length >= maxLength ) {
+
+				error( `TSL: Length of parameters exceeds maximum length of function '${ type }()' type.`, this.stackTrace );
+				break;
+
+			}
+
+			let inputType = input.getNodeType( builder );
+			let inputTypeLength = builder.getTypeLength( inputType );
+			let inputSnippet;
 
-			const inputPrimitiveType = builder.getComponentType( input.getNodeType( builder ) );
+			if ( length + inputTypeLength > maxLength ) {
+
+				error( `TSL: Length of '${ type }()' data exceeds maximum length of output type.`, this.stackTrace );
+
+				inputTypeLength = maxLength - length;
+				inputType = builder.getTypeFromLength( inputTypeLength );
+
+			}
+
+			length += inputTypeLength;
+			inputSnippet = input.build( builder, inputType );
+
+			const inputPrimitiveType = builder.getComponentType( inputType );
 
 			if ( inputPrimitiveType !== primitiveType ) {
 
-				inputSnippet = builder.format( inputSnippet, inputPrimitiveType, primitiveType );
+				const targetType = builder.getTypeFromLength( inputTypeLength, primitiveType );
+
+				inputSnippet = builder.format( inputSnippet, inputType, targetType );
 
 			}
 

package/src/nodes/utils/LoopNode.js

@@ -1,7 +1,44 @@
 import Node from '../core/Node.js';
 import { expression } from '../code/ExpressionNode.js';
-import { nodeObject, nodeArray } from '../tsl/TSLBase.js';
-
+import { nodeArray, Fn } from '../tsl/TSLBase.js';
+import { error } from '../../utils.js';
+
+/**
+ * This module offers a variety of ways to implement loops in TSL. In it's basic form it's:
+ * ```js
+ * Loop( count, ( { i } ) => {
+ *
+ * } );
+ * ```
+ * However, it is also possible to define a start and end ranges, data types and loop conditions:
+ * ```js
+ * Loop( { start: int( 0 ), end: int( 10 ), type: 'int', condition: '<' }, ( { i } ) => {
+ *
+ * } );
+ *```
+ * Nested loops can be defined in a compacted form:
+ * ```js
+ * Loop( 10, 5, ( { i, j } ) => {
+ *
+ * } );
+ * ```
+ * Loops that should run backwards can be defined like so:
+ * ```js
+ * Loop( { start: 10 }, () => {} );
+ * ```
+ * It is possible to execute with boolean values, similar to the `while` syntax.
+ * ```js
+ * const value = float( 0 ).toVar();
+ *
+ * Loop( value.lessThan( 10 ), () => {
+ *
+ * 	value.addAssign( 1 );
+ *
+ * } );
+ * ```
+ * The module also provides `Break()` and `Continue()` TSL expression for loop control.
+ * @augments Node
+ */
 class LoopNode extends Node {
 
 	static get type() {
@@ -10,20 +47,38 @@ class LoopNode extends Node {
 
 	}
 
+	/**
+	 * Constructs a new loop node.
+	 *
+	 * @param {Array<any>} params - Depending on the loop type, array holds different parameterization values for the loop.
+	 */
 	constructor( params = [] ) {
 
-		super();
+		super( 'void' );
 
 		this.params = params;
 
 	}
 
+	/**
+	 * Returns a loop variable name based on an index. The pattern is
+	 * `0` = `i`, `1`= `j`, `2`= `k` and so on.
+	 *
+	 * @param {number} index - The index.
+	 * @return {string} The loop variable name.
+	 */
 	getVarName( index ) {
 
-		return String.fromCharCode( 'i'.charCodeAt() + index );
+		return String.fromCharCode( 'i'.charCodeAt( 0 ) + index );
 
 	}
 
+	/**
+	 * Returns properties about this node.
+	 *
+	 * @param {NodeBuilder} builder - The current node builder.
+	 * @return {Object} The node properties.
+	 */
 	getProperties( builder ) {
 
 		const properties = builder.getNodeProperties( this );
@@ -45,22 +100,26 @@ class LoopNode extends Node {
 
 		}
 
-		const stack = builder.addStack(); // TODO: cache() it
+		const stack = builder.addStack();
+
+		const fnCall = this.params[ this.params.length - 1 ]( inputs );
 
-		properties.returnsNode = this.params[ this.params.length - 1 ]( inputs, stack, builder );
+		properties.returnsNode = fnCall.context( { nodeLoop: fnCall } );
 		properties.stackNode = stack;
 
-		builder.removeStack();
+		const baseParam = this.params[ 0 ];
 
-		return properties;
+		if ( baseParam.isNode !== true && typeof baseParam.update === 'function' ) {
 
-	}
+			const fnUpdateCall = Fn( this.params[ 0 ].update )( inputs );
 
-	getNodeType( builder ) {
+			properties.updateNode = fnUpdateCall.context( { nodeLoop: fnUpdateCall } );
 
-		const { returnsNode } = this.getProperties( builder );
+		}
 
-		return returnsNode ? returnsNode.getNodeType( builder ) : 'void';
+		builder.removeStack();
+
+		return properties;
 
 	}
 
@@ -70,6 +129,13 @@ class LoopNode extends Node {
 
 		this.getProperties( builder );
 
+		if ( builder.fnCall ) {
+
+			const shaderNodeData = builder.getDataFromNode( builder.fnCall.shaderNode );
+			shaderNodeData.hasLoop = true;
+
+		}
+
 	}
 
 	generate( builder ) {
@@ -83,15 +149,25 @@ class LoopNode extends Node {
 
 			const param = params[ i ];
 
-			let start = null, end = null, name = null, type = null, condition = null, update = null;
+			let isWhile = false, start = null, end = null, name = null, type = null, condition = null, update = null;
 
 			if ( param.isNode ) {
 
-				type = 'int';
-				name = this.getVarName( i );
-				start = '0';
-				end = param.build( builder, type );
-				condition = '<';
+				if ( param.getNodeType( builder ) === 'bool' ) {
+
+					isWhile = true;
+					type = 'bool';
+					end = param.build( builder, type );
+
+				} else {
+
+					type = 'int';
+					name = this.getVarName( i );
+					start = '0';
+					end = param.build( builder, type );
+					condition = '<';
+
+				}
 
 			} else {
 
@@ -102,10 +178,10 @@ class LoopNode extends Node {
 				condition = param.condition;
 				update = param.update;
 
-				if ( typeof start === 'number' ) start = start.toString();
+				if ( typeof start === 'number' ) start = builder.generateConst( type, start );
 				else if ( start && start.isNode ) start = start.build( builder, type );
 
-				if ( typeof end === 'number' ) end = end.toString();
+				if ( typeof end === 'number' ) end = builder.generateConst( type, end );
 				else if ( end && end.isNode ) end = end.build( builder, type );
 
 				if ( start !== undefined && end === undefined ) {
@@ -137,47 +213,96 @@ class LoopNode extends Node {
 
 			}
 
-			const internalParam = { start, end, condition };
+			let loopSnippet;
+
+			if ( isWhile ) {
+
+				loopSnippet = `while ( ${ end } )`;
+
+			} else {
+
+				const internalParam = { start, end, condition };
+
+				//
+
+				const startSnippet = internalParam.start;
+				const endSnippet = internalParam.end;
+
+				let updateSnippet;
+
+				const deltaOperator = () => condition.includes( '<' ) ? '+=' : '-=';
 
-			//
+				if ( update !== undefined && update !== null ) {
 
-			const startSnippet = internalParam.start;
-			const endSnippet = internalParam.end;
+					switch ( typeof update ) {
 
-			let declarationSnippet = '';
-			let conditionalSnippet = '';
-			let updateSnippet = '';
+						case 'function':
 
-			if ( ! update ) {
+							const flow = builder.flowStagesNode( properties.updateNode, 'void' );
+							const snippet = flow.code.replace( /\t|;/g, '' );
 
-				if ( type === 'int' || type === 'uint' ) {
+							updateSnippet = snippet;
 
-					if ( condition.includes( '<' ) ) update = '++';
-					else update = '--';
+							break;
+
+						case 'number':
+
+							updateSnippet = name + ' ' + deltaOperator() + ' ' + builder.generateConst( type, update );
+
+							break;
+
+						case 'string':
+
+							updateSnippet = name + ' ' + update;
+
+							break;
+
+						default:
+
+							if ( update.isNode ) {
+
+								updateSnippet = name + ' ' + deltaOperator() + ' ' + update.build( builder );
+
+							} else {
+
+								error( 'TSL: \'Loop( { update: ... } )\' is not a function, string or number.', this.stackTrace );
+
+								updateSnippet = 'break /* invalid update */';
+
+							}
+
+					}
 
 				} else {
 
-					if ( condition.includes( '<' ) ) update = '+= 1.';
-					else update = '-= 1.';
+					if ( type === 'int' || type === 'uint' ) {
 
-				}
+						update = condition.includes( '<' ) ? '++' : '--';
 
-			}
+					} else {
+
+						update = deltaOperator() + ' 1.';
 
-			declarationSnippet += builder.getVar( type, name ) + ' = ' + startSnippet;
+					}
+
+					updateSnippet = name + ' ' + update;
 
-			conditionalSnippet += name + ' ' + condition + ' ' + endSnippet;
-			updateSnippet += name + ' ' + update;
+				}
 
-			const forSnippet = `for ( ${ declarationSnippet }; ${ conditionalSnippet }; ${ updateSnippet } )`;
+				const declarationSnippet = builder.getVar( type, name ) + ' = ' + startSnippet;
+				const conditionalSnippet = name + ' ' + condition + ' ' + endSnippet;
 
-			builder.addFlowCode( ( i === 0 ? '\n' : '' ) + builder.tab + forSnippet + ' {\n\n' ).addFlowTab();
+				loopSnippet = `for ( ${ declarationSnippet }; ${ conditionalSnippet }; ${ updateSnippet } )`;
+
+			}
+
+			builder.addFlowCode( ( i === 0 ? '\n' : '' ) + builder.tab + loopSnippet + ' {\n\n' ).addFlowTab();
 
 		}
 
 		const stackSnippet = stackNode.build( builder, 'void' );
 
-		const returnsSnippet = properties.returnsNode ? properties.returnsNode.build( builder ) : '';
+		properties.returnsNode.build( builder, 'void' );
 
 		builder.removeFlowTab().addFlowCode( '\n' + builder.tab + stackSnippet );
 
@@ -189,23 +314,36 @@ class LoopNode extends Node {
 
 		builder.addFlowTab();
 
-		return returnsSnippet;
-
 	}
 
 }
 
 export default LoopNode;
 
-export const Loop = ( ...params ) => nodeObject( new LoopNode( nodeArray( params, 'int' ) ) ).append();
-export const Continue = () => expression( 'continue' ).append();
-export const Break = () => expression( 'break' ).append();
-
-//
-
-export const loop = ( ...params ) => { // @deprecated, r168
-
-	console.warn( 'TSL.LoopNode: loop() has been renamed to Loop().' );
-	return Loop( ...params );
-
-};
+/**
+ * TSL function for creating a loop node.
+ *
+ * @tsl
+ * @function
+ * @param {...any} params - A list of parameters.
+ * @returns {LoopNode}
+ */
+export const Loop = ( ...params ) => new LoopNode( nodeArray( params, 'int' ) ).toStack();
+
+/**
+ * TSL function for creating a `Continue()` expression.
+ *
+ * @tsl
+ * @function
+ * @returns {ExpressionNode}
+ */
+export const Continue = () => expression( 'continue' ).toStack();
+
+/**
+ * TSL function for creating a `Break()` expression.
+ *
+ * @tsl
+ * @function
+ * @returns {ExpressionNode}
+ */
+export const Break = () => expression( 'break' ).toStack();

package/src/nodes/utils/MatcapUV.js

@@ -0,0 +1,22 @@
+import { normalView } from '../accessors/Normal.js';
+import { positionViewDirection } from '../accessors/Position.js';
+import { Fn, vec2, vec3 } from '../tsl/TSLBase.js';
+
+/**
+ * TSL function for creating a matcap uv node.
+ *
+ * Can be used to compute texture coordinates for projecting a
+ * matcap onto a mesh. Used by {@link MeshMatcapNodeMaterial}.
+ *
+ * @tsl
+ * @function
+ * @returns {Node<vec2>} The matcap UV coordinates.
+ */
+export const matcapUV = /*@__PURE__*/ Fn( () => {
+
+	const x = vec3( positionViewDirection.z, 0, positionViewDirection.x.negate() ).normalize();
+	const y = positionViewDirection.cross( x );
+
+	return vec2( x.dot( normalView ), y.dot( normalView ) ).mul( 0.495 ).add( 0.5 ); // 0.495 to remove artifacts caused by undersized matcap disks
+
+} ).once( [ 'NORMAL', 'VERTEX' ] )().toVar( 'matcapUV' );