@plastic-software/three 0.167.4 → 0.174.0

package/src/nodes/tsl/TSLBase.js

@@ -0,0 +1,31 @@
+// Non-PURE exports list, side-effects are required here.
+// TSL Base Syntax
+
+export * from './TSLCore.js'; // float(), vec2(), vec3(), vec4(), mat3(), mat4(), Fn(), If(), element(), nodeObject(), nodeProxy(), ...
+export * from '../core/ArrayNode.js'; // array(), .toArray()
+export * from '../core/UniformNode.js'; // uniform()
+export * from '../core/PropertyNode.js'; // property()  <-> TODO: Separate Material Properties in other file
+export * from '../core/AssignNode.js'; // .assign()
+export * from '../code/FunctionCallNode.js'; // .call()
+export * from '../math/OperatorNode.js'; // .add(), .sub(), ...
+export * from '../math/MathNode.js'; // abs(), floor(), ...
+export * from '../math/ConditionalNode.js'; // select(), ...
+export * from '../core/ContextNode.js'; // .context()
+export * from '../core/VarNode.js'; // .var() -> TODO: Maybe rename .toVar() -> .var()
+export * from '../core/VaryingNode.js'; // varying(), vertexStage()
+export * from '../display/ColorSpaceNode.js'; // .toColorSpace()
+export * from '../display/ToneMappingNode.js'; // .toToneMapping()
+export * from '../accessors/BufferAttributeNode.js'; // .toAttribute()
+export * from '../gpgpu/ComputeNode.js'; // .compute()
+export * from '../core/CacheNode.js'; // .cache()
+export * from '../core/BypassNode.js'; // .bypass()
+export * from '../utils/RemapNode.js'; // .remap(), .remapClamp()
+export * from '../code/ExpressionNode.js'; // expression()
+export * from '../utils/Discard.js'; // Discard(), Return()
+export * from '../display/RenderOutputNode.js'; // .renderOutput()
+
+export function addNodeElement( name/*, nodeElement*/ ) {
+
+	console.warn( 'THREE.TSLBase: AddNodeElement has been removed in favor of tree-shaking. Trying add', name );
+
+}

package/src/nodes/{shadernode/ShaderNode.js → tsl/TSLCore.js}

@@ -1,23 +1,23 @@
-import Node, { addNodeClass } from '../core/Node.js';
+import Node from '../core/Node.js';
 import ArrayElementNode from '../utils/ArrayElementNode.js';
 import ConvertNode from '../utils/ConvertNode.js';
 import JoinNode from '../utils/JoinNode.js';
 import SplitNode from '../utils/SplitNode.js';
 import SetNode from '../utils/SetNode.js';
+import FlipNode from '../utils/FlipNode.js';
 import ConstNode from '../core/ConstNode.js';
+import MemberNode from '../utils/MemberNode.js';
 import { getValueFromType, getValueType } from '../core/NodeUtils.js';
 
-//
-
 let currentStack = null;
 
-const NodeElements = new Map(); // @TODO: Currently only a few nodes are added, probably also add others
+const NodeElements = new Map();
 
-export function addNodeElement( name, nodeElement ) {
+export function addMethodChaining( name, nodeElement ) {
 
 	if ( NodeElements.has( name ) ) {
 
-		console.warn( `Redefinition of node element ${ name }` );
+		console.warn( `Redefinition of method chaining ${ name }` );
 		return;
 
 	}
@@ -29,6 +29,7 @@ export function addNodeElement( name, nodeElement ) {
 }
 
 const parseSwizzle = ( props ) => props.replace( /r|s/g, 'x' ).replace( /g|t/g, 'y' ).replace( /b|p/g, 'z' ).replace( /a|q/g, 'w' );
+const parseSwizzleAndSort = ( props ) => parseSwizzle( props ).split( '' ).sort().join( '' );
 
 const shaderNodeHandler = {
 
@@ -80,15 +81,19 @@ const shaderNodeHandler = {
 
 			} else if ( /^set[XYZWRGBASTPQ]{1,4}$/.test( prop ) === true ) {
 
-				// set properties ( swizzle )
+				// set properties ( swizzle ) and sort to xyzw sequence
 
-				prop = parseSwizzle( prop.slice( 3 ).toLowerCase() );
+				prop = parseSwizzleAndSort( prop.slice( 3 ).toLowerCase() );
 
-				// sort to xyzw sequence
+				return ( value ) => nodeObject( new SetNode( node, prop, value ) );
 
-				prop = prop.split( '' ).sort().join( '' );
+			} else if ( /^flip[XYZWRGBASTPQ]{1,4}$/.test( prop ) === true ) {
 
-				return ( value ) => nodeObject( new SetNode( node, prop, value ) );
+				// set properties ( swizzle ) and sort to xyzw sequence
+
+				prop = parseSwizzleAndSort( prop.slice( 4 ).toLowerCase() );
+
+				return () => nodeObject( new FlipNode( nodeObject( node ), prop ) );
 
 			} else if ( prop === 'width' || prop === 'height' || prop === 'depth' ) {
 
@@ -106,6 +111,12 @@ const shaderNodeHandler = {
 
 				return nodeObject( new ArrayElementNode( nodeObj, new ConstNode( Number( prop ), 'uint' ) ) );
 
+			} else if ( /^get$/.test( prop ) === true ) {
+
+				// accessing properties
+
+				return ( value ) => nodeObject( new MemberNode( nodeObj, value ) );
+
 			}
 
 		}
@@ -251,15 +262,13 @@ class ShaderCallNodeInternal extends Node {
 
 	getNodeType( builder ) {
 
-		const properties = builder.getNodeProperties( this );
-
-		if ( properties.outputNode === null ) {
+		return this.shaderNode.nodeType || this.getOutputNode( builder ).getNodeType( builder );
 
-			properties.outputNode = this.setupOutput( builder );
+	}
 
-		}
+	getMemberType( builder, name ) {
 
-		return properties.outputNode.getNodeType( builder );
+		return this.getOutputNode( builder ).getMemberType( builder, name );
 
 	}
 
@@ -267,6 +276,13 @@ class ShaderCallNodeInternal extends Node {
 
 		const { shaderNode, inputNodes } = this;
 
+		const properties = builder.getNodeProperties( shaderNode );
+		if ( properties.onceOutput ) return properties.onceOutput;
+
+		//
+
+		let result = null;
+
 		if ( shaderNode.layout ) {
 
 			let functionNodesCacheMap = nodeBuilderFunctionsCacheMap.get( builder.constructor );
@@ -289,28 +305,46 @@ class ShaderCallNodeInternal extends Node {
 
 			}
 
-			if ( builder.currentFunctionNode !== null ) {
+			builder.addInclude( functionNode );
 
-				builder.currentFunctionNode.includes.push( functionNode );
+			result = nodeObject( functionNode.call( inputNodes ) );
 
-			}
+		} else {
+
+			const jsFunc = shaderNode.jsFunc;
+			const outputNode = inputNodes !== null || jsFunc.length > 1 ? jsFunc( inputNodes || [], builder ) : jsFunc( builder );
 
-			return nodeObject( functionNode.call( inputNodes ) );
+			result = nodeObject( outputNode );
 
 		}
 
-		const jsFunc = shaderNode.jsFunc;
-		const outputNode = inputNodes !== null ? jsFunc( inputNodes, builder ) : jsFunc( builder );
+		if ( shaderNode.once ) {
+
+			properties.onceOutput = result;
 
-		return nodeObject( outputNode );
+		}
+
+		return result;
 
 	}
 
-	setup( builder ) {
+	getOutputNode( builder ) {
 
-		const { outputNode } = builder.getNodeProperties( this );
+		const properties = builder.getNodeProperties( this );
 
-		return outputNode || this.setupOutput( builder );
+		if ( properties.outputNode === null ) {
+
+			properties.outputNode = this.setupOutput( builder );
+
+		}
+
+		return properties.outputNode;
+
+	}
+
+	setup( builder ) {
+
+		return this.getOutputNode( builder );
 
 	}
 
@@ -326,17 +360,9 @@ class ShaderCallNodeInternal extends Node {
 
 	generate( builder, output ) {
 
-		const { outputNode } = builder.getNodeProperties( this );
-
-		if ( outputNode === null ) {
+		const outputNode = this.getOutputNode( builder );
 
-			// TSL: It's recommended to use `tslFn` in setup() pass.
-
-			return this.call( builder ).build( builder, output );
-
-		}
-
-		return super.generate( builder, output );
+		return outputNode.build( builder, output );
 
 	}
 
@@ -344,20 +370,16 @@ class ShaderCallNodeInternal extends Node {
 
 class ShaderNodeInternal extends Node {
 
-	constructor( jsFunc ) {
+	constructor( jsFunc, nodeType ) {
 
-		super();
+		super( nodeType );
 
 		this.jsFunc = jsFunc;
 		this.layout = null;
 
 		this.global = true;
 
-	}
-
-	get isArrayInput() {
-
-		return /^\((\s+)?\[/.test( this.jsFunc.toString() );
+		this.once = false;
 
 	}
 
@@ -480,9 +502,9 @@ export const getConstNodeType = ( value ) => ( value !== undefined && value !==
 
 // shader node base
 
-export function ShaderNode( jsFunc ) {
+export function ShaderNode( jsFunc, nodeType ) {
 
-	return new Proxy( new ShaderNodeInternal( jsFunc ), shaderNodeHandler );
+	return new Proxy( new ShaderNodeInternal( jsFunc, nodeType ), shaderNodeHandler );
 
 }
 
@@ -492,9 +514,9 @@ 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 ) => {
+export const Fn = ( jsFunc, nodeType ) => {
 
-	const shaderNode = new ShaderNode( jsFunc );
+	const shaderNode = new ShaderNode( jsFunc, nodeType );
 
 	const fn = ( ...params ) => {
 
@@ -517,6 +539,7 @@ export const Fn = ( jsFunc ) => {
 	};
 
 	fn.shaderNode = shaderNode;
+
 	fn.setLayout = ( layout ) => {
 
 		shaderNode.setLayout( layout );
@@ -525,22 +548,36 @@ export const Fn = ( jsFunc ) => {
 
 	};
 
+	fn.once = () => {
+
+		shaderNode.once = true;
+
+		return fn;
+
+	};
+
 	return fn;
 
 };
 
+/**
+ * @tsl
+ * @function
+ * @deprecated since r168. Use {@link Fn} instead.
+ *
+ * @param  {...any} params
+ * @returns {Function}
+ */
 export const tslFn = ( ...params ) => { // @deprecated, r168
 
-	console.warn( 'TSL.tslFn: tslFn() has been renamed to Fn().' );
+	console.warn( 'TSL.ShaderNode: tslFn() has been renamed to Fn().' );
 	return Fn( ...params );
 
 };
 
-addNodeClass( 'ShaderNode', ShaderNode );
-
 //
 
-addNodeElement( 'toGlobal', ( node ) => {
+addMethodChaining( 'toGlobal', ( node ) => {
 
 	node.global = true;
 
@@ -574,10 +611,9 @@ export function append( node ) {
 
 }
 
-addNodeElement( 'append', append );
+addMethodChaining( 'append', append );
 
 // types
-// @TODO: Maybe export from ConstNode.js?
 
 export const color = new ConvertType( 'color' );
 
@@ -602,58 +638,38 @@ export const uvec4 = new ConvertType( 'uvec4' );
 export const bvec4 = new ConvertType( 'bvec4' );
 
 export const mat2 = new ConvertType( 'mat2' );
-export const imat2 = new ConvertType( 'imat2' );
-export const umat2 = new ConvertType( 'umat2' );
-export const bmat2 = new ConvertType( 'bmat2' );
-
 export const mat3 = new ConvertType( 'mat3' );
-export const imat3 = new ConvertType( 'imat3' );
-export const umat3 = new ConvertType( 'umat3' );
-export const bmat3 = new ConvertType( 'bmat3' );
-
 export const mat4 = new ConvertType( 'mat4' );
-export const imat4 = new ConvertType( 'imat4' );
-export const umat4 = new ConvertType( 'umat4' );
-export const bmat4 = new ConvertType( 'bmat4' );
 
 export const string = ( value = '' ) => nodeObject( new ConstNode( value, 'string' ) );
 export const arrayBuffer = ( value ) => nodeObject( new ConstNode( value, 'ArrayBuffer' ) );
 
-addNodeElement( 'toColor', color );
-addNodeElement( 'toFloat', float );
-addNodeElement( 'toInt', int );
-addNodeElement( 'toUint', uint );
-addNodeElement( 'toBool', bool );
-addNodeElement( 'toVec2', vec2 );
-addNodeElement( 'toIvec2', ivec2 );
-addNodeElement( 'toUvec2', uvec2 );
-addNodeElement( 'toBvec2', bvec2 );
-addNodeElement( 'toVec3', vec3 );
-addNodeElement( 'toIvec3', ivec3 );
-addNodeElement( 'toUvec3', uvec3 );
-addNodeElement( 'toBvec3', bvec3 );
-addNodeElement( 'toVec4', vec4 );
-addNodeElement( 'toIvec4', ivec4 );
-addNodeElement( 'toUvec4', uvec4 );
-addNodeElement( 'toBvec4', bvec4 );
-addNodeElement( 'toMat2', mat2 );
-addNodeElement( 'toImat2', imat2 );
-addNodeElement( 'toUmat2', umat2 );
-addNodeElement( 'toBmat2', bmat2 );
-addNodeElement( 'toMat3', mat3 );
-addNodeElement( 'toImat3', imat3 );
-addNodeElement( 'toUmat3', umat3 );
-addNodeElement( 'toBmat3', bmat3 );
-addNodeElement( 'toMat4', mat4 );
-addNodeElement( 'toImat4', imat4 );
-addNodeElement( 'toUmat4', umat4 );
-addNodeElement( 'toBmat4', bmat4 );
+addMethodChaining( 'toColor', color );
+addMethodChaining( 'toFloat', float );
+addMethodChaining( 'toInt', int );
+addMethodChaining( 'toUint', uint );
+addMethodChaining( 'toBool', bool );
+addMethodChaining( 'toVec2', vec2 );
+addMethodChaining( 'toIVec2', ivec2 );
+addMethodChaining( 'toUVec2', uvec2 );
+addMethodChaining( 'toBVec2', bvec2 );
+addMethodChaining( 'toVec3', vec3 );
+addMethodChaining( 'toIVec3', ivec3 );
+addMethodChaining( 'toUVec3', uvec3 );
+addMethodChaining( 'toBVec3', bvec3 );
+addMethodChaining( 'toVec4', vec4 );
+addMethodChaining( 'toIVec4', ivec4 );
+addMethodChaining( 'toUVec4', uvec4 );
+addMethodChaining( 'toBVec4', bvec4 );
+addMethodChaining( 'toMat2', mat2 );
+addMethodChaining( 'toMat3', mat3 );
+addMethodChaining( 'toMat4', mat4 );
 
 // basic nodes
-// HACK - we cannot export them from the corresponding files because of the cyclic dependency
-export const element = nodeProxy( ArrayElementNode );
+
+export const element = /*@__PURE__*/ nodeProxy( ArrayElementNode );
 export const convert = ( node, types ) => nodeObject( new ConvertNode( nodeObject( node ), types ) );
 export const split = ( node, channels ) => nodeObject( new SplitNode( nodeObject( node ), channels ) );
 
-addNodeElement( 'element', element );
-addNodeElement( 'convert', convert );
+addMethodChaining( 'element', element );
+addMethodChaining( 'convert', convert );

package/src/nodes/utils/ArrayElementNode.js

@@ -1,18 +1,60 @@
-import Node, { addNodeClass } from '../core/Node.js';
-
+import Node from '../core/Node.js';
+
+/**
+ * Base class for representing element access on an array-like
+ * node data structures.
+ *
+ * @augments Node
+ */
 class ArrayElementNode extends Node { // @TODO: If extending from TempNode it breaks webgpu_compute
 
+	static get type() {
+
+		return 'ArrayElementNode';
+
+	}
+
+	/**
+	 * Constructs an array element node.
+	 *
+	 * @param {Node} node - The array-like node.
+	 * @param {Node} indexNode - The index node that defines the element access.
+	 */
 	constructor( node, indexNode ) {
 
 		super();
 
+		/**
+		 * The array-like node.
+		 *
+		 * @type {Node}
+		 */
 		this.node = node;
+
+		/**
+		 * The index node that defines the element access.
+		 *
+		 * @type {Node}
+		 */
 		this.indexNode = indexNode;
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isArrayElementNode = true;
 
 	}
 
+	/**
+	 * This method is overwritten since the node type is inferred from the array-like node.
+	 *
+	 * @param {NodeBuilder} builder - The current node builder.
+	 * @return {string} The node type.
+	 */
 	getNodeType( builder ) {
 
 		return this.node.getElementType( builder );
@@ -24,12 +66,10 @@ class ArrayElementNode extends Node { // @TODO: If extending from TempNode it br
 		const nodeSnippet = this.node.build( builder );
 		const indexSnippet = this.indexNode.build( builder, 'uint' );
 
-		return `${nodeSnippet}[ ${indexSnippet} ]`;
+		return `${ nodeSnippet }[ ${ indexSnippet } ]`;
 
 	}
 
 }
 
 export default ArrayElementNode;
-
-addNodeClass( 'ArrayElementNode', ArrayElementNode );

package/src/nodes/utils/ConvertNode.js

@@ -1,16 +1,53 @@
-import Node, { addNodeClass } from '../core/Node.js';
-
+import Node from '../core/Node.js';
+
+/**
+ * This module is part of the TSL core and usually not used in app level code.
+ * It represents a convert operation during the shader generation process
+ * meaning it converts the data type of a node to a target data type.
+ *
+ * @augments Node
+ */
 class ConvertNode extends Node {
 
+	static get type() {
+
+		return 'ConvertNode';
+
+	}
+
+	/**
+	 * Constructs a new convert node.
+	 *
+	 * @param {Node} node - The node which type should be converted.
+	 * @param {string} convertTo - The target node type. Multiple types can be defined by separating them with a `|` sign.
+	 */
 	constructor( node, convertTo ) {
 
 		super();
 
+		/**
+		 * The node which type should be converted.
+		 *
+		 * @type {Node}
+		 */
 		this.node = node;
+
+		/**
+		 * The target node type. Multiple types can be defined by separating them with a `|` sign.
+		 *
+		 * @type {string}
+		 */
 		this.convertTo = convertTo;
 
 	}
 
+	/**
+	 * This method is overwritten since the implementation tries to infer the best
+	 * matching type from the {@link ConvertNode#convertTo} property.
+	 *
+	 * @param {NodeBuilder} builder - The current node builder.
+	 * @return {string} The node type.
+	 */
 	getNodeType( builder ) {
 
 		const requestType = this.node.getNodeType( builder );
@@ -61,5 +98,3 @@ class ConvertNode extends Node {
 }
 
 export default ConvertNode;
-
-addNodeClass( 'ConvertNode', ConvertNode );

package/src/nodes/utils/CubeMapNode.js

@@ -1,30 +1,80 @@
 import TempNode from '../core/TempNode.js';
-import { addNodeClass } from '../core/Node.js';
 import { NodeUpdateType } from '../core/constants.js';
-import { nodeProxy } from '../shadernode/ShaderNode.js';
+import { nodeProxy } from '../tsl/TSLBase.js';
 import { CubeTexture } from '../../textures/CubeTexture.js';
 import { cubeTexture } from '../accessors/CubeTextureNode.js';
 import CubeRenderTarget from '../../renderers/common/CubeRenderTarget.js';
-import { CubeReflectionMapping, CubeRefractionMapping, EquirectangularReflectionMapping, EquirectangularRefractionMapping } from '../../constants';
+import { CubeReflectionMapping, CubeRefractionMapping, EquirectangularReflectionMapping, EquirectangularRefractionMapping } from '../../constants.js';
 
 const _cache = new WeakMap();
 
+/**
+ * This node can be used to automatically convert environment maps in the
+ * equirectangular format into the cube map format.
+ *
+ * @augments TempNode
+ */
 class CubeMapNode extends TempNode {
 
+	static get type() {
+
+		return 'CubeMapNode';
+
+	}
+
+	/**
+	 * Constructs a new cube map node.
+	 *
+	 * @param {Node} envNode - The node representing the environment map.
+	 */
 	constructor( envNode ) {
 
 		super( 'vec3' );
 
+		/**
+		 * The node representing the environment map.
+		 *
+		 * @type {Node}
+		 */
 		this.envNode = envNode;
 
+		/**
+		 * A reference to the internal cube texture.
+		 *
+		 * @private
+		 * @type {CubeTexture}
+		 * @default null
+		 */
 		this._cubeTexture = null;
+
+		/**
+		 * A reference to the internal cube texture node.
+		 *
+		 * @private
+		 * @type {CubeTextureNode}
+		 */
 		this._cubeTextureNode = cubeTexture();
 
 		const defaultTexture = new CubeTexture();
 		defaultTexture.isRenderTargetTexture = true;
 
+		/**
+		 * A default cube texture that acts as a placeholder.
+		 * It is used when the conversion from equirectangular to cube
+		 * map has not finished yet for a given texture.
+		 *
+		 * @private
+		 * @type {CubeTexture}
+		 */
 		this._defaultTexture = defaultTexture;
 
+		/**
+		 * The `updateBeforeType` is set to `NodeUpdateType.RENDER` since the node updates
+		 * the texture once per render in its {@link CubeMapNode#updateBefore} method.
+		 *
+		 * @type {string}
+		 * @default 'render'
+		 */
 		this.updateBeforeType = NodeUpdateType.RENDER;
 
 	}
@@ -110,6 +160,16 @@ class CubeMapNode extends TempNode {
 
 }
 
+export default CubeMapNode;
+
+/**
+ * Returns true if the given equirectangular image has been fully loaded
+ * and is ready for further processing.
+ *
+ * @private
+ * @param {Image} image - The equirectangular image to check.
+ * @return {boolean} Whether the image is ready or not.
+ */
 function isEquirectangularMapReady( image ) {
 
 	if ( image === null || image === undefined ) return false;
@@ -118,6 +178,14 @@ function isEquirectangularMapReady( image ) {
 
 }
 
+/**
+ * This function is executed when `dispose()` is called on the equirectangular
+ * texture. In this case, the generated cube map with its render target
+ * is deleted as well.
+ *
+ * @private
+ * @param {Object} event - The event object.
+ */
 function onTextureDispose( event ) {
 
 	const texture = event.target;
@@ -136,6 +204,14 @@ function onTextureDispose( event ) {
 
 }
 
+/**
+ * This function makes sure the generated cube map uses the correct
+ * texture mapping that corresponds to the equirectangular original.
+ *
+ * @private
+ * @param {Texture} texture - The cube texture.
+ * @param {number} mapping - The original texture mapping.
+ */
 function mapTextureMapping( texture, mapping ) {
 
 	if ( mapping === EquirectangularReflectionMapping ) {
@@ -150,8 +226,12 @@ function mapTextureMapping( texture, mapping ) {
 
 }
 
-export const cubeMapNode = nodeProxy( CubeMapNode );
-
-addNodeClass( 'CubeMapNode', CubeMapNode );
-
-export default CubeMapNode;
+/**
+ * TSL function for creating a cube map node.
+ *
+ * @tsl
+ * @function
+ * @param {Node} envNode - The node representing the environment map.
+ * @returns {CubeMapNode}
+ */
+export const cubeMapNode = /*@__PURE__*/ nodeProxy( CubeMapNode );