@plastic-software/three 0.174.0 → 0.175.1

package/src/nodes/tsl/TSLCore.js

@@ -17,12 +17,12 @@ export function addMethodChaining( name, nodeElement ) {
 
 	if ( NodeElements.has( name ) ) {
 
-		console.warn( `Redefinition of method chaining ${ name }` );
+		console.warn( `THREE.TSL: Redefinition of method chaining '${ name }'.` );
 		return;
 
 	}
 
-	if ( typeof nodeElement !== 'function' ) throw new Error( `Node element ${ name } is not a function` );
+	if ( typeof nodeElement !== 'function' ) throw new Error( `THREE.TSL: Node element ${ name } is not a function` );
 
 	NodeElements.set( name, nodeElement );
 
@@ -213,11 +213,38 @@ const ShaderNodeProxy = function ( NodeClass, scope = null, factor = null, setti
 
 	const assignNode = ( node ) => nodeObject( settings !== null ? Object.assign( node, settings ) : node );
 
+	let fn, name = scope, minParams, maxParams;
+
+	function verifyParamsLimit( params ) {
+
+		let tslName;
+
+		if ( name ) tslName = /[a-z]/i.test( name ) ? name + '()' : name;
+		else tslName = NodeClass.type;
+
+		if ( minParams !== undefined && params.length < minParams ) {
+
+			console.error( `THREE.TSL: "${ tslName }" parameter length is less than minimum required.` );
+
+			return params.concat( new Array( minParams - params.length ).fill( 0 ) );
+
+		} else if ( maxParams !== undefined && params.length > maxParams ) {
+
+			console.error( `THREE.TSL: "${ tslName }" parameter length exceeds limit.` );
+
+			return params.slice( 0, maxParams );
+
+		}
+
+		return params;
+
+	}
+
 	if ( scope === null ) {
 
-		return ( ...params ) => {
+		fn = ( ...params ) => {
 
-			return assignNode( new NodeClass( ...nodeArray( params ) ) );
+			return assignNode( new NodeClass( ...nodeArray( verifyParamsLimit( params ) ) ) );
 
 		};
 
@@ -225,22 +252,41 @@ const ShaderNodeProxy = function ( NodeClass, scope = null, factor = null, setti
 
 		factor = nodeObject( factor );
 
-		return ( ...params ) => {
+		fn = ( ...params ) => {
 
-			return assignNode( new NodeClass( scope, ...nodeArray( params ), factor ) );
+			return assignNode( new NodeClass( scope, ...nodeArray( verifyParamsLimit( params ) ), factor ) );
 
 		};
 
 	} else {
 
-		return ( ...params ) => {
+		fn = ( ...params ) => {
 
-			return assignNode( new NodeClass( scope, ...nodeArray( params ) ) );
+			return assignNode( new NodeClass( scope, ...nodeArray( verifyParamsLimit( params ) ) ) );
 
 		};
 
 	}
 
+	fn.setParameterLength = ( ...params ) => {
+
+		if ( params.length === 1 ) minParams = maxParams = params[ 0 ];
+		else if ( params.length === 2 ) [ minParams, maxParams ] = params;
+
+		return fn;
+
+	};
+
+	fn.setName = ( value ) => {
+
+		name = value;
+
+		return fn;
+
+	};
+
+	return fn;
+
 };
 
 const ShaderNodeImmutable = function ( NodeClass, ...params ) {
@@ -514,7 +560,35 @@ export const nodeArray = ( val, altType = null ) => new ShaderNodeArray( val, al
 export const nodeProxy = ( ...params ) => new ShaderNodeProxy( ...params );
 export const nodeImmutable = ( ...params ) => new ShaderNodeImmutable( ...params );
 
-export const Fn = ( jsFunc, nodeType ) => {
+let fnId = 0;
+
+export const Fn = ( jsFunc, layout = null ) => {
+
+	let nodeType = null;
+
+	if ( layout !== null ) {
+
+		if ( typeof layout === 'object' ) {
+
+			nodeType = layout.return;
+
+		} else {
+
+			if ( typeof layout === 'string' ) {
+
+				nodeType = layout;
+
+			} else {
+
+				console.error( 'THREE.TSL: Invalid layout type.' );
+
+			}
+
+			layout = null;
+
+		}
+
+	}
 
 	const shaderNode = new ShaderNode( jsFunc, nodeType );
 
@@ -556,6 +630,35 @@ export const Fn = ( jsFunc, nodeType ) => {
 
 	};
 
+	if ( layout !== null ) {
+
+		if ( typeof layout.inputs !== 'object' ) {
+
+			const fullLayout = {
+				name: 'fn' + fnId ++,
+				type: nodeType,
+				inputs: []
+			};
+
+			for ( const name in layout ) {
+
+				if ( name === 'return' ) continue;
+
+				fullLayout.inputs.push( {
+					name: name,
+					type: layout[ name ]
+				} );
+
+			}
+
+			layout = fullLayout;
+
+		}
+
+		fn.setLayout( layout );
+
+	}
+
 	return fn;
 
 };
@@ -565,12 +668,12 @@ export const Fn = ( jsFunc, nodeType ) => {
  * @function
  * @deprecated since r168. Use {@link Fn} instead.
  *
- * @param  {...any} params
+ * @param {...any} params
  * @returns {Function}
  */
 export const tslFn = ( ...params ) => { // @deprecated, r168
 
-	console.warn( 'TSL.ShaderNode: tslFn() has been renamed to Fn().' );
+	console.warn( 'THREE.TSL: tslFn() has been renamed to Fn().' );
 	return Fn( ...params );
 
 };
@@ -667,7 +770,7 @@ addMethodChaining( 'toMat4', mat4 );
 
 // basic nodes
 
-export const element = /*@__PURE__*/ nodeProxy( ArrayElementNode );
+export const element = /*@__PURE__*/ nodeProxy( ArrayElementNode ).setParameterLength( 2 );
 export const convert = ( node, types ) => nodeObject( new ConvertNode( nodeObject( node ), types ) );
 export const split = ( node, channels ) => nodeObject( new SplitNode( nodeObject( node ), channels ) );
 

package/src/nodes/utils/ArrayElementNode.js

@@ -63,8 +63,10 @@ class ArrayElementNode extends Node { // @TODO: If extending from TempNode it br
 
 	generate( builder ) {
 
+		const indexType = this.indexNode.getNodeType( builder );
+
 		const nodeSnippet = this.node.build( builder );
-		const indexSnippet = this.indexNode.build( builder, 'uint' );
+		const indexSnippet = this.indexNode.build( builder, ! builder.isVector( indexType ) && builder.isInteger( indexType ) ? indexType : 'uint' );
 
 		return `${ nodeSnippet }[ ${ indexSnippet } ]`;
 

package/src/nodes/utils/CubeMapNode.js

@@ -42,7 +42,7 @@ class CubeMapNode extends TempNode {
 		 * A reference to the internal cube texture.
 		 *
 		 * @private
-		 * @type {CubeTexture}
+		 * @type {?CubeTexture}
 		 * @default null
 		 */
 		this._cubeTexture = null;
@@ -53,7 +53,7 @@ class CubeMapNode extends TempNode {
 		 * @private
 		 * @type {CubeTextureNode}
 		 */
-		this._cubeTextureNode = cubeTexture();
+		this._cubeTextureNode = cubeTexture( null );
 
 		const defaultTexture = new CubeTexture();
 		defaultTexture.isRenderTargetTexture = true;
@@ -234,4 +234,4 @@ function mapTextureMapping( texture, mapping ) {
  * @param {Node} envNode - The node representing the environment map.
  * @returns {CubeMapNode}
  */
-export const cubeMapNode = /*@__PURE__*/ nodeProxy( CubeMapNode );
+export const cubeMapNode = /*@__PURE__*/ nodeProxy( CubeMapNode ).setParameterLength( 1 );

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/EquirectUVNode.js

@@ -59,7 +59,7 @@ export default EquirectUVNode;
  *
  * @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/JoinNode.js

@@ -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

@@ -25,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
  */
@@ -133,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 {
 
@@ -187,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 ( ! update ) {
+
+					if ( type === 'int' || type === 'uint' ) {
+
+						if ( condition.includes( '<' ) ) update = '++';
+						else update = '--';
 
-					if ( condition.includes( '<' ) ) update = '+= 1.';
-					else update = '-= 1.';
+					} 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();
 
 		}
 
@@ -282,12 +312,12 @@ export const Break = () => expression( 'break' ).append();
  * @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/MaxMipLevelNode.js

@@ -100,4 +100,4 @@ export default MaxMipLevelNode;
  * @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/ReflectorNode.js

@@ -76,8 +76,8 @@ class ReflectorNode extends TextureNode {
 		 * A reference to the internal reflector base node which holds the actual implementation.
 		 *
 		 * @private
-		 * @type {?ReflectorBaseNode}
-		 * @default null
+		 * @type {ReflectorBaseNode}
+		 * @default ReflectorBaseNode
 		 */
 		this._reflectorBaseNode = parameters.reflector || new ReflectorBaseNode( this, parameters );
 

package/src/nodes/utils/RemapNode.js

@@ -101,11 +101,11 @@ export default RemapNode;
  * @param {Node} node - The node that should be remapped.
  * @param {Node} inLowNode - The source or current lower bound of the range.
  * @param {Node} inHighNode - The source or current upper bound of the range.
- * @param {Node} [outLowNode=float(0)] - The target lower bound of the range.
- * @param {Node} [outHighNode=float(1)] - The target upper bound of the range.
+ * @param {?Node} [outLowNode=float(0)] - The target lower bound of the range.
+ * @param {?Node} [outHighNode=float(1)] - The target upper bound of the range.
  * @returns {RemapNode}
  */
-export const remap = /*@__PURE__*/ nodeProxy( RemapNode, null, null, { doClamp: false } );
+export const remap = /*@__PURE__*/ nodeProxy( RemapNode, null, null, { doClamp: false } ).setParameterLength( 3, 5 );
 
 /**
  * TSL function for creating a remap node, but with enabled clamping.
@@ -115,11 +115,11 @@ export const remap = /*@__PURE__*/ nodeProxy( RemapNode, null, null, { doClamp:
  * @param {Node} node - The node that should be remapped.
  * @param {Node} inLowNode - The source or current lower bound of the range.
  * @param {Node} inHighNode - The source or current upper bound of the range.
- * @param {Node} [outLowNode=float(0)] - The target lower bound of the range.
- * @param {Node} [outHighNode=float(1)] - The target upper bound of the range.
+ * @param {?Node} [outLowNode=float(0)] - The target lower bound of the range.
+ * @param {?Node} [outHighNode=float(1)] - The target upper bound of the range.
  * @returns {RemapNode}
  */
-export const remapClamp = /*@__PURE__*/ nodeProxy( RemapNode );
+export const remapClamp = /*@__PURE__*/ nodeProxy( RemapNode ).setParameterLength( 3, 5 );
 
 addMethodChaining( 'remap', remap );
 addMethodChaining( 'remapClamp', remapClamp );

package/src/nodes/utils/RotateNode.js

@@ -100,4 +100,4 @@ export default RotateNode;
  * on whether the position data are 2D or 3D, the rotation is expressed a single float value or an Euler value.
  * @returns {RotateNode}
  */
-export const rotate = /*@__PURE__*/ nodeProxy( RotateNode );
+export const rotate = /*@__PURE__*/ nodeProxy( RotateNode ).setParameterLength( 2 );

package/src/nodes/utils/SpriteSheetUVNode.js

@@ -83,8 +83,8 @@ export default SpriteSheetUVNode;
  * @tsl
  * @function
  * @param {Node<vec2>} countNode - The node that defines the number of sprites in the x and y direction (e.g 6x6).
- * @param {Node<vec2>} [uvNode=uv()] - The uv node.
- * @param {Node<float>} [frameNode=float()] - The node that defines the current frame/sprite.
+ * @param {?Node<vec2>} [uvNode=uv()] - The uv node.
+ * @param {?Node<float>} [frameNode=float()] - The node that defines the current frame/sprite.
  * @returns {SpriteSheetUVNode}
  */
-export const spritesheetUV = /*@__PURE__*/ nodeProxy( SpriteSheetUVNode );
+export const spritesheetUV = /*@__PURE__*/ nodeProxy( SpriteSheetUVNode ).setParameterLength( 3 );

package/src/nodes/utils/StorageArrayElementNode.js

@@ -140,4 +140,4 @@ export default StorageArrayElementNode;
  * @param {Node} indexNode - The index node that defines the element access.
  * @returns {StorageArrayElementNode}
  */
-export const storageElement = /*@__PURE__*/ nodeProxy( StorageArrayElementNode );
+export const storageElement = /*@__PURE__*/ nodeProxy( StorageArrayElementNode ).setParameterLength( 2 );

package/src/nodes/utils/TriplanarTexturesNode.js

@@ -46,7 +46,7 @@ class TriplanarTexturesNode extends Node {
 		/**
 		 * Second texture node. When not set, the shader will sample from `textureXNode` instead.
 		 *
-		 * @type {Node}
+		 * @type {?Node}
 		 * @default null
 		 */
 		this.textureYNode = textureYNode;
@@ -54,7 +54,7 @@ class TriplanarTexturesNode extends Node {
 		/**
 		 * Third texture node. When not set, the shader will sample from `textureXNode` instead.
 		 *
-		 * @type {Node}
+		 * @type {?Node}
 		 * @default null
 		 */
 		this.textureZNode = textureZNode;
@@ -130,7 +130,7 @@ export default TriplanarTexturesNode;
  * @param {?Node<vec3>} [normalNode=normalLocal] - Normals in local space.
  * @returns {TriplanarTexturesNode}
  */
-export const triplanarTextures = /*@__PURE__*/ nodeProxy( TriplanarTexturesNode );
+export const triplanarTextures = /*@__PURE__*/ nodeProxy( TriplanarTexturesNode ).setParameterLength( 1, 6 );
 
 /**
  * TSL function for creating a triplanar textures node.

package/src/objects/BatchedMesh.js

@@ -446,7 +446,7 @@ class BatchedMesh extends Mesh {
 	/**
 	 * Validates the instance defined by the given ID.
 	 *
-	 * @param {number} instanceId - The the instance to validate.
+	 * @param {number} instanceId - The instance to validate.
 	 */
 	validateInstanceId( instanceId ) {
 
@@ -462,7 +462,7 @@ class BatchedMesh extends Mesh {
 	/**
 	 * Validates the geometry defined by the given ID.
 	 *
-	 * @param {number} geometryId - The the geometry to validate.
+	 * @param {number} geometryId - The geometry to validate.
 	 */
 	validateGeometryId( geometryId ) {
 
@@ -705,7 +705,7 @@ class BatchedMesh extends Mesh {
 	 * is not enough space reserved for geometry. Calling this will change all instances that are
 	 * rendering that geometry.
 	 *
-	 * @param {number} geometryId - The ID of the geomtry that should be replaced with the given geometry.
+	 * @param {number} geometryId - The ID of the geometry that should be replaced with the given geometry.
 	 * @param {BufferGeometry} geometry - The new geometry.
 	 * @return {number} The geometry ID.
 	 */
@@ -818,7 +818,7 @@ class BatchedMesh extends Mesh {
 	 * Deletes the geometry defined by the given ID from this batch. Any instances referencing
 	 * this geometry will also be removed as a side effect.
 	 *
-	 * @param {number} geometryId - The ID of the geomtry to remove from the batch.
+	 * @param {number} geometryId - The ID of the geometry to remove from the batch.
 	 * @return {BatchedMesh} A reference to this batched mesh.
 	 */
 	deleteGeometry( geometryId ) {

package/src/objects/InstancedMesh.js

@@ -71,7 +71,7 @@ class InstancedMesh extends Mesh {
 		 * {@link Texture#needsUpdate} flag to true if you modify instanced data
 		 * via {@link InstancedMesh#setMorphAt}.
 		 *
-		 * @type {?InstancedBufferAttribute}
+		 * @type {?DataTexture}
 		 * @default null
 		 */
 		this.morphTexture = null;
@@ -321,7 +321,7 @@ class InstancedMesh extends Mesh {
 	 * {@link InstancedMesh#instanceMatrix} to `true` after updating all the colors.
 	 *
 	 * @param {number} index - The instance index.
-	 * @param {Matrix4} matrix - The the local transformation.
+	 * @param {Matrix4} matrix - The local transformation.
 	 */
 	setMatrixAt( index, matrix ) {
 

package/src/objects/LOD.js

@@ -245,7 +245,7 @@ class LOD extends Object3D {
 	 * Updates the LOD by computing which LOD level should be visible according
 	 * to the current distance of the given camera.
 	 *
-	 * @param {Camera} camera - The camera the scene is renderd with.
+	 * @param {Camera} camera - The camera the scene is rendered with.
 	 */
 	update( camera ) {
 

package/src/objects/Skeleton.js

@@ -310,7 +310,7 @@ class Skeleton {
 	 * Setups the skeleton by the given JSON and bones.
 	 *
 	 * @param {Object} json - The skeleton as serialized JSON.
-	 * @param {Array<Bone>} bones - An array of bones.
+	 * @param {Object<string, Bone>} bones - An array of bones.
 	 * @return {Skeleton} A reference of this instance.
 	 */
 	fromJSON( json, bones ) {