super-three 0.173.5 → 0.176.0

package/src/nodes/utils/DebugNode.js

@@ -0,0 +1,70 @@
+import TempNode from '../core/TempNode.js';
+import { addMethodChaining, nodeObject } from '../tsl/TSLCore.js';
+
+class DebugNode extends TempNode {
+
+	static get type() {
+
+		return 'DebugNode';
+
+	}
+
+	constructor( node, callback = null ) {
+
+		super();
+
+		this.node = node;
+		this.callback = callback;
+
+	}
+
+	getNodeType( builder ) {
+
+		return this.node.getNodeType( builder );
+
+	}
+
+	setup( builder ) {
+
+		return this.node.build( builder );
+
+	}
+
+	analyze( builder ) {
+
+		return this.node.build( builder );
+
+	}
+
+	generate( builder ) {
+
+		const callback = this.callback;
+		const snippet = this.node.build( builder );
+
+		let code = '';
+		code += '// #--- TSL Debug ---#\n';
+		code += builder.flow.code.replace( /^\t/mg, '' ) + '\n';
+		code += '/* ... */ ' + snippet + ' /* ... */\n';
+		code += '// #-----------------#\n';
+
+		if ( callback !== null ) {
+
+			callback( code );
+
+		} else {
+
+			console.log( code );
+
+		}
+
+		return snippet;
+
+	}
+
+}
+
+export default DebugNode;
+
+export const debug = ( node, callback = null ) => nodeObject( new DebugNode( nodeObject( node ), callback ) );
+
+addMethodChaining( 'debug', debug );

package/src/nodes/utils/Discard.js

@@ -2,13 +2,12 @@ import { select } from '../math/ConditionalNode.js';
 import { expression } from '../code/ExpressionNode.js';
 import { addMethodChaining } from '../tsl/TSLCore.js';
 
-/** @module Discard **/
-
 /**
  * Represents a `discard` shader operation in TSL.
  *
- * @method
- * @param {ConditionalNode?} conditional - An optional conditional node. It allows to decide whether the discard should be executed or not.
+ * @tsl
+ * @function
+ * @param {?ConditionalNode} conditional - An optional conditional node. It allows to decide whether the discard should be executed or not.
  * @return {Node} The `discard` expression.
  */
 export const Discard = ( conditional ) => ( conditional ? select( conditional, expression( 'discard' ) ) : expression( 'discard' ) ).append();
@@ -16,7 +15,8 @@ export const Discard = ( conditional ) => ( conditional ? select( conditional, e
 /**
  * Represents a `return` shader operation in TSL.
  *
- * @method
+ * @tsl
+ * @function
  * @return {ExpressionNode} The `return` expression.
  */
 export const Return = () => expression( 'return' ).append();

package/src/nodes/utils/EquirectUVNode.js

@@ -2,8 +2,6 @@ import TempNode from '../core/TempNode.js';
 import { positionWorldDirection } from '../accessors/Position.js';
 import { nodeProxy, vec2 } from '../tsl/TSLBase.js';
 
-/** @module EquirectUVNode **/
-
 /**
  * Can be used to compute texture coordinates for projecting an
  * equirectangular texture onto a mesh for using it as the scene's
@@ -59,8 +57,9 @@ export default EquirectUVNode;
 /**
  * TSL function for creating an equirect uv node.
  *
+ * @tsl
  * @function
- * @param {Node<vec3>} [dirNode=positionWorldDirection] - A direction vector for sampling which is by default `positionWorldDirection`.
+ * @param {?Node<vec3>} [dirNode=positionWorldDirection] - A direction vector for sampling which is by default `positionWorldDirection`.
  * @returns {EquirectUVNode}
  */
-export const equirectUV = /*@__PURE__*/ nodeProxy( EquirectUVNode );
+export const equirectUV = /*@__PURE__*/ nodeProxy( EquirectUVNode ).setParameterLength( 0, 1 );

package/src/nodes/utils/FlipNode.js

@@ -28,7 +28,7 @@ class FlipNode extends TempNode {
 	 * Constructs a new flip node.
 	 *
 	 * @param {Node} sourceNode - The node which component(s) should be flipped.
-	 * @param {String} components - The components that should be flipped e.g. `'x'` or `'xy'`.
+	 * @param {string} components - The components that should be flipped e.g. `'x'` or `'xy'`.
 	 */
 	constructor( sourceNode, components ) {
 
@@ -44,7 +44,7 @@ class FlipNode extends TempNode {
 		/**
 		 * The components that should be flipped e.g. `'x'` or `'xy'`.
 		 *
-		 * @type {String}
+		 * @type {string}
 		 */
 		this.components = components;
 
@@ -54,7 +54,7 @@ class FlipNode extends TempNode {
 	 * This method is overwritten since the node type is inferred from the source node.
 	 *
 	 * @param {NodeBuilder} builder - The current node builder.
-	 * @return {String} The node type.
+	 * @return {string} The node type.
 	 */
 	getNodeType( builder ) {
 

package/src/nodes/utils/FunctionOverloadingNode.js

@@ -1,8 +1,6 @@
 import Node from '../core/Node.js';
 import { nodeProxy } from '../tsl/TSLCore.js';
 
-/** @module FunctionOverloadingNode **/
-
 /**
  * This class allows to define multiple overloaded versions
  * of the same function. Depending on the parameters of the function
@@ -53,7 +51,7 @@ class FunctionOverloadingNode extends Node {
 		/**
 		 * This node is marked as global.
 		 *
-		 * @type {Boolean}
+		 * @type {boolean}
 		 * @default true
 		 */
 		this.global = true;
@@ -65,7 +63,7 @@ class FunctionOverloadingNode extends Node {
 	 * the function's return type.
 	 *
 	 * @param {NodeBuilder} builder - The current node builder.
-	 * @return {String} The node type.
+	 * @return {string} The node type.
 	 */
 	getNodeType() {
 
@@ -146,6 +144,7 @@ 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}

package/src/nodes/utils/JoinNode.js

@@ -19,7 +19,7 @@ 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.
+	 * @param {?string} [nodeType=null] - The node type.
 	 */
 	constructor( nodes = [], nodeType = null ) {
 
@@ -39,7 +39,7 @@ class JoinNode extends TempNode {
 	 * joined data length if not explicitly defined.
 	 *
 	 * @param {NodeBuilder} builder - The current node builder.
-	 * @return {String} The node type.
+	 * @return {string} The node type.
 	 */
 	getNodeType( builder ) {
 
@@ -56,17 +56,42 @@ 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 ) {
+
+				console.error( `THREE.TSL: Length of parameters exceeds maximum length of function '${ type }()' type.` );
+				break;
+
+			}
+
+			let inputType = input.getNodeType( builder );
+			let inputTypeLength = builder.getTypeLength( inputType );
+			let inputSnippet;
+
+			if ( length + inputTypeLength > maxLength ) {
+
+				console.error( `THREE.TSL: Length of '${ type }()' data exceeds maximum length of output type.` );
+
+				inputTypeLength = maxLength - length;
+				inputType = builder.getTypeFromLength( inputTypeLength );
+
+			}
+
+			length += inputTypeLength;
+			inputSnippet = input.build( builder, inputType );
 
-			const inputPrimitiveType = builder.getComponentType( input.getNodeType( builder ) );
+			const inputPrimitiveType = builder.getComponentType( inputType );
 
 			if ( inputPrimitiveType !== primitiveType ) {
 

package/src/nodes/utils/LoopNode.js

@@ -2,8 +2,6 @@ import Node from '../core/Node.js';
 import { expression } from '../code/ExpressionNode.js';
 import { nodeObject, nodeArray } from '../tsl/TSLBase.js';
 
-/** @module LoopNode **/
-
 /**
  * This module offers a variety of ways to implement loops in TSL. In it's basic form it's:
  * ```js
@@ -27,6 +25,16 @@ import { nodeObject, nodeArray } from '../tsl/TSLBase.js';
  * ```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
  */
@@ -41,7 +49,7 @@ 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.
+	 * @param {Array<any>} params - Depending on the loop type, array holds different parameterization values for the loop.
 	 */
 	constructor( params = [] ) {
 
@@ -55,8 +63,8 @@ class LoopNode extends Node {
 	 * 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.
+	 * @param {number} index - The index.
+	 * @return {string} The loop variable name.
 	 */
 	getVarName( index ) {
 
@@ -106,7 +114,7 @@ class LoopNode extends Node {
 	 * This method is overwritten since the node type is inferred based on the loop configuration.
 	 *
 	 * @param {NodeBuilder} builder - The current node builder.
-	 * @return {String} The node type.
+	 * @return {string} The node type.
 	 */
 	getNodeType( builder ) {
 
@@ -135,15 +143,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 {
 
@@ -189,41 +207,51 @@ class LoopNode extends Node {
 
 			}
 
-			const internalParam = { start, end, condition };
+			let loopSnippet;
 
-			//
+			if ( isWhile ) {
 
-			const startSnippet = internalParam.start;
-			const endSnippet = internalParam.end;
+				loopSnippet = `while ( ${ end } )`;
 
-			let declarationSnippet = '';
-			let conditionalSnippet = '';
-			let updateSnippet = '';
+			} else {
 
-			if ( ! update ) {
+				const internalParam = { start, end, condition };
 
-				if ( type === 'int' || type === 'uint' ) {
+				//
 
-					if ( condition.includes( '<' ) ) update = '++';
-					else update = '--';
+				const startSnippet = internalParam.start;
+				const endSnippet = internalParam.end;
 
-				} else {
+				let declarationSnippet = '';
+				let conditionalSnippet = '';
+				let updateSnippet = '';
 
-					if ( condition.includes( '<' ) ) update = '+= 1.';
-					else update = '-= 1.';
+				if ( ! update ) {
+
+					if ( type === 'int' || type === 'uint' ) {
+
+						if ( condition.includes( '<' ) ) update = '++';
+						else update = '--';
+
+					} else {
+
+						if ( condition.includes( '<' ) ) update = '+= 1.';
+						else update = '-= 1.';
+
+					}
 
 				}
 
-			}
+				declarationSnippet += builder.getVar( type, name ) + ' = ' + startSnippet;
 
-			declarationSnippet += builder.getVar( type, name ) + ' = ' + startSnippet;
+				conditionalSnippet += name + ' ' + condition + ' ' + endSnippet;
+				updateSnippet += name + ' ' + update;
 
-			conditionalSnippet += name + ' ' + condition + ' ' + endSnippet;
-			updateSnippet += name + ' ' + update;
+				loopSnippet = `for ( ${ declarationSnippet }; ${ conditionalSnippet }; ${ updateSnippet } )`;
 
-			const forSnippet = `for ( ${ declarationSnippet }; ${ conditionalSnippet }; ${ updateSnippet } )`;
+			}
 
-			builder.addFlowCode( ( i === 0 ? '\n' : '' ) + builder.tab + forSnippet + ' {\n\n' ).addFlowTab();
+			builder.addFlowCode( ( i === 0 ? '\n' : '' ) + builder.tab + loopSnippet + ' {\n\n' ).addFlowTab();
 
 		}
 
@@ -252,8 +280,9 @@ export default LoopNode;
 /**
  * TSL function for creating a loop node.
  *
+ * @tsl
  * @function
- * @param {...Any} params - A list of parameters.
+ * @param {...any} params - A list of parameters.
  * @returns {LoopNode}
  */
 export const Loop = ( ...params ) => nodeObject( new LoopNode( nodeArray( params, 'int' ) ) ).append();
@@ -261,6 +290,7 @@ export const Loop = ( ...params ) => nodeObject( new LoopNode( nodeArray( params
 /**
  * TSL function for creating a `Continue()` expression.
  *
+ * @tsl
  * @function
  * @returns {ExpressionNode}
  */
@@ -269,6 +299,7 @@ export const Continue = () => expression( 'continue' ).append();
 /**
  * TSL function for creating a `Break()` expression.
  *
+ * @tsl
  * @function
  * @returns {ExpressionNode}
  */
@@ -277,15 +308,16 @@ export const Break = () => expression( 'break' ).append();
 // Deprecated
 
 /**
+ * @tsl
  * @function
  * @deprecated since r168. Use {@link Loop} instead.
  *
- * @param  {...any} params
+ * @param {...any} params
  * @returns {LoopNode}
  */
 export const loop = ( ...params ) => { // @deprecated, r168
 
-	console.warn( 'TSL.LoopNode: loop() has been renamed to Loop().' );
+	console.warn( 'THREE.TSL: loop() has been renamed to Loop().' );
 	return Loop( ...params );
 
 };

package/src/nodes/utils/MatcapUVNode.js

@@ -3,8 +3,6 @@ import { transformedNormalView } from '../accessors/Normal.js';
 import { positionViewDirection } from '../accessors/Position.js';
 import { nodeImmutable, vec2, vec3 } from '../tsl/TSLBase.js';
 
-/** @module MatcapUVNode **/
-
 /**
  * Can be used to compute texture coordinates for projecting a
  * matcap onto a mesh. Used by {@link MeshMatcapNodeMaterial}.
@@ -44,6 +42,7 @@ export default MatcapUVNode;
 /**
  * TSL function for creating a matcap uv node.
  *
+ * @tsl
  * @function
  * @returns {MatcapUVNode}
  */

package/src/nodes/utils/MaxMipLevelNode.js

@@ -2,8 +2,6 @@ import UniformNode from '../core/UniformNode.js';
 import { NodeUpdateType } from '../core/constants.js';
 import { nodeProxy } from '../tsl/TSLBase.js';
 
-/** @module MatcapUVNode **/
-
 /**
  * A special type of uniform node that computes the
  * maximum mipmap level for a given texture node.
@@ -12,7 +10,7 @@ import { nodeProxy } from '../tsl/TSLBase.js';
  * const level = maxMipLevel( textureNode );
  * ```
  *
- * @augments module:UniformNode~UniformNode
+ * @augments UniformNode
  */
 class MaxMipLevelNode extends UniformNode {
 
@@ -43,7 +41,7 @@ class MaxMipLevelNode extends UniformNode {
 		 * The `updateType` is set to `NodeUpdateType.FRAME` since the node updates
 		 * the texture once per frame in its {@link MaxMipLevelNode#update} method.
 		 *
-		 * @type {String}
+		 * @type {string}
 		 * @default 'frame'
 		 */
 		this.updateType = NodeUpdateType.FRAME;
@@ -97,8 +95,9 @@ export default MaxMipLevelNode;
 /**
  * TSL function for creating a max mip level node.
  *
+ * @tsl
  * @function
  * @param {TextureNode} textureNode - The texture node to compute the max mip level for.
  * @returns {MaxMipLevelNode}
  */
-export const maxMipLevel = /*@__PURE__*/ nodeProxy( MaxMipLevelNode );
+export const maxMipLevel = /*@__PURE__*/ nodeProxy( MaxMipLevelNode ).setParameterLength( 1 );

package/src/nodes/utils/MemberNode.js

@@ -18,7 +18,7 @@ class MemberNode extends Node {
 	 * Constructs an array element node.
 	 *
 	 * @param {Node} node - The array-like node.
-	 * @param {String} property - The property name.
+	 * @param {string} property - The property name.
 	 */
 	constructor( node, property ) {
 
@@ -41,7 +41,7 @@ class MemberNode extends Node {
 		/**
 		 * This flag can be used for type testing.
 		 *
-		 * @type {Boolean}
+		 * @type {boolean}
 		 * @readonly
 		 * @default true
 		 */

package/src/nodes/utils/Oscillators.js

@@ -1,11 +1,10 @@
 import { time } from './Timer.js';
 
-/** @module Oscillators **/
-
 /**
  * Generates a sine wave oscillation based on a timer.
  *
- * @method
+ * @tsl
+ * @function
  * @param {Node<float>} t - The timer to generate the oscillation with.
  * @return {Node<float>} The oscillation node.
  */
@@ -14,7 +13,8 @@ export const oscSine = ( t = time ) => t.add( 0.75 ).mul( Math.PI * 2 ).sin().mu
 /**
  * Generates a square wave oscillation based on a timer.
  *
- * @method
+ * @tsl
+ * @function
  * @param {Node<float>} t - The timer to generate the oscillation with.
  * @return {Node<float>} The oscillation node.
  */
@@ -23,7 +23,8 @@ export const oscSquare = ( t = time ) => t.fract().round();
 /**
  * Generates a triangle wave oscillation based on a timer.
  *
- * @method
+ * @tsl
+ * @function
  * @param {Node<float>} t - The timer to generate the oscillation with.
  * @return {Node<float>} The oscillation node.
  */
@@ -32,7 +33,8 @@ export const oscTriangle = ( t = time ) => t.add( 0.5 ).fract().mul( 2 ).sub( 1
 /**
  * Generates a sawtooth wave oscillation based on a timer.
  *
- * @method
+ * @tsl
+ * @function
  * @param {Node<float>} t - The timer to generate the oscillation with.
  * @return {Node<float>} The oscillation node.
  */

package/src/nodes/utils/Packing.js

@@ -1,11 +1,10 @@
 import { nodeObject } from '../tsl/TSLBase.js';
 
-/** @module Packing **/
-
 /**
  * Packs a direction vector into a color value.
  *
- * @method
+ * @tsl
+ * @function
  * @param {Node<vec3>} node - The direction to pack.
  * @return {Node<vec3>} The color.
  */
@@ -14,7 +13,8 @@ export const directionToColor = ( node ) => nodeObject( node ).mul( 0.5 ).add( 0
 /**
  * Unpacks a color value into a direction vector.
  *
- * @method
+ * @tsl
+ * @function
  * @param {Node<vec3>} node - The color to unpack.
  * @return {Node<vec3>} The direction.
  */

package/src/nodes/utils/PostProcessingUtils.js

@@ -3,13 +3,12 @@ import { textureSize } from '../accessors/TextureSizeNode.js';
 import { textureLoad } from '../accessors/TextureNode.js';
 import { WebGPUCoordinateSystem } from '../../constants.js';
 
-/** @module PostProcessingUtils **/
-
 /**
  * Computes a position in view space based on a fragment's screen position expressed as uv coordinates, the fragments
  * depth value and the camera's inverse projection matrix.
  *
- * @method
+ * @tsl
+ * @function
  * @param {Node<vec2>} screenPosition - The fragment's screen position expressed as uv coordinates.
  * @param {Node<float>} depth - The fragment's depth value.
  * @param {Node<mat4>} projectionMatrixInverse - The camera's inverse projection matrix.
@@ -40,7 +39,8 @@ export const getViewPosition = /*@__PURE__*/ Fn( ( [ screenPosition, depth, proj
  * Computes a screen position expressed as uv coordinates based on a fragment's position in view space
  * and the camera's projection matrix
  *
- * @method
+ * @tsl
+ * @function
  * @param {Node<vec3>} viewPosition - The fragments position in view space.
  * @param {Node<mat4>} projectionMatrix - The camera's projection matrix.
  * @return {Node<vec2>} The fragment's screen position expressed as uv coordinates.
@@ -57,7 +57,8 @@ export const getScreenPosition = /*@__PURE__*/ Fn( ( [ viewPosition, projectionM
  * Computes a normal vector based on depth data. Can be used as a fallback when no normal render
  * target is available or if flat surface normals are required.
  *
- * @method
+ * @tsl
+ * @function
  * @param {Node<vec2>} uv - The texture coordinate.
  * @param {DepthTexture} depthTexture - The depth texture.
  * @param {Node<mat4>} projectionMatrixInverse - The camera's inverse projection matrix.