@plastic-software/three 0.167.4 → 0.174.0

package/src/nodes/utils/Discard.js

@@ -0,0 +1,24 @@
+import { select } from '../math/ConditionalNode.js';
+import { expression } from '../code/ExpressionNode.js';
+import { addMethodChaining } from '../tsl/TSLCore.js';
+
+/**
+ * Represents a `discard` shader operation in TSL.
+ *
+ * @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();
+
+/**
+ * Represents a `return` shader operation in TSL.
+ *
+ * @tsl
+ * @function
+ * @return {ExpressionNode} The `return` expression.
+ */
+export const Return = () => expression( 'return' ).append();
+
+addMethodChaining( 'discard', Discard );

package/src/nodes/utils/EquirectUVNode.js

@@ -1,14 +1,40 @@
 import TempNode from '../core/TempNode.js';
-import { positionWorldDirection } from '../accessors/PositionNode.js';
-import { nodeProxy, vec2 } from '../shadernode/ShaderNode.js';
-import { addNodeClass } from '../core/Node.js';
+import { positionWorldDirection } from '../accessors/Position.js';
+import { nodeProxy, vec2 } from '../tsl/TSLBase.js';
 
+/**
+ * Can be used to compute texture coordinates for projecting an
+ * equirectangular texture onto a mesh for using it as the scene's
+ * background.
+ *
+ * ```js
+ * scene.backgroundNode = texture( equirectTexture, equirectUV() );
+ * ```
+ *
+ * @augments TempNode
+ */
 class EquirectUVNode extends TempNode {
 
+	static get type() {
+
+		return 'EquirectUVNode';
+
+	}
+
+	/**
+	 * Constructs a new equirect uv node.
+	 *
+	 * @param {Node<vec3>} [dirNode=positionWorldDirection] - A direction vector for sampling which is by default `positionWorldDirection`.
+	 */
 	constructor( dirNode = positionWorldDirection ) {
 
 		super( 'vec2' );
 
+		/**
+		 * A direction vector for sampling why is by default `positionWorldDirection`.
+		 *
+		 * @type {Node<vec3>}
+		 */
 		this.dirNode = dirNode;
 
 	}
@@ -17,7 +43,7 @@ class EquirectUVNode extends TempNode {
 
 		const dir = this.dirNode;
 
-		const u = dir.z.atan2( dir.x ).mul( 1 / ( Math.PI * 2 ) ).add( 0.5 );
+		const u = dir.z.atan( dir.x ).mul( 1 / ( Math.PI * 2 ) ).add( 0.5 );
 		const v = dir.y.clamp( - 1.0, 1.0 ).asin().mul( 1 / Math.PI ).add( 0.5 );
 
 		return vec2( u, v );
@@ -28,6 +54,12 @@ class EquirectUVNode extends TempNode {
 
 export default EquirectUVNode;
 
-export const equirectUV = nodeProxy( EquirectUVNode );
-
-addNodeClass( 'EquirectUVNode', 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`.
+ * @returns {EquirectUVNode}
+ */
+export const equirectUV = /*@__PURE__*/ nodeProxy( EquirectUVNode );

package/src/nodes/utils/FlipNode.js

@@ -0,0 +1,106 @@
+import TempNode from '../core/TempNode.js';
+import { vectorComponents } from '../core/constants.js';
+
+/**
+ * This module is part of the TSL core and usually not used in app level code.
+ * It represents a flip operation during the shader generation process
+ * meaning it flips normalized values with the following formula:
+ * ```
+ * x = 1 - x;
+ * ```
+ * `FlipNode` is internally used to implement any `flipXYZW()`, `flipRGBA()` and
+ * `flipSTPQ()` method invocations on node objects. For example:
+ * ```js
+ * uvNode = uvNode.flipY();
+ * ```
+ *
+ * @augments TempNode
+ */
+class FlipNode extends TempNode {
+
+	static get type() {
+
+		return 'FlipNode';
+
+	}
+
+	/**
+	 * 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'`.
+	 */
+	constructor( sourceNode, components ) {
+
+		super();
+
+		/**
+		 * The node which component(s) should be flipped.
+		 *
+		 * @type {Node}
+		 */
+		this.sourceNode = sourceNode;
+
+		/**
+		 * The components that should be flipped e.g. `'x'` or `'xy'`.
+		 *
+		 * @type {string}
+		 */
+		this.components = components;
+
+	}
+
+	/**
+	 * 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.
+	 */
+	getNodeType( builder ) {
+
+		return this.sourceNode.getNodeType( builder );
+
+	}
+
+	generate( builder ) {
+
+		const { components, sourceNode } = this;
+
+		const sourceType = this.getNodeType( builder );
+		const sourceSnippet = sourceNode.build( builder );
+
+		const sourceCache = builder.getVarFromNode( this );
+		const sourceProperty = builder.getPropertyName( sourceCache );
+
+		builder.addLineFlowCode( sourceProperty + ' = ' + sourceSnippet, this );
+
+		const length = builder.getTypeLength( sourceType );
+		const snippetValues = [];
+
+		let componentIndex = 0;
+
+		for ( let i = 0; i < length; i ++ ) {
+
+			const component = vectorComponents[ i ];
+
+			if ( component === components[ componentIndex ] ) {
+
+				snippetValues.push( '1.0 - ' + ( sourceProperty + '.' + component ) );
+
+				componentIndex ++;
+
+			} else {
+
+				snippetValues.push( sourceProperty + '.' + component );
+
+			}
+
+		}
+
+		return `${ builder.getType( sourceType ) }( ${ snippetValues.join( ', ' ) } )`;
+
+	}
+
+}
+
+export default FlipNode;

package/src/nodes/utils/FunctionOverloadingNode.js

@@ -1,21 +1,70 @@
-import Node, { addNodeClass } from '../core/Node.js';
-import { nodeProxy } from '../shadernode/ShaderNode.js';
-
+import Node from '../core/Node.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() {
+
+		return 'FunctionOverloadingNode';
+
+	}
+
+	/**
+	 * 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;
+
+		/**
+		 * A list of parameter nodes.
+		 *
+		 * @type {Array<Node>}
+		 */
 		this.parametersNodes = parametersNodes;
 
+		/**
+		 * The selected overloaded function call.
+		 *
+		 * @private
+		 * @type {ShaderCallNodeInternal}
+		 */
 		this._candidateFnCall = null;
 
+		/**
+		 * This node is marked as global.
+		 *
+		 * @type {boolean}
+		 * @default true
+		 */
 		this.global = true;
 
 	}
 
+	/**
+	 * 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() {
 
 		return this.functionNodes[ 0 ].shaderNode.layout.type;
@@ -90,8 +139,14 @@ class FunctionOverloadingNode extends Node {
 
 export default FunctionOverloadingNode;
 
-const overloadingBaseFn = nodeProxy( 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 );
-
-addNodeClass( 'FunctionOverloadingNode', FunctionOverloadingNode );

package/src/nodes/utils/JoinNode.js

@@ -1,16 +1,46 @@
-import { addNodeClass } from '../core/Node.js';
 import TempNode from '../core/TempNode.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() {
+
+		return 'JoinNode';
+
+	}
+
+	/**
+	 * 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 ) {
@@ -57,5 +87,3 @@ class JoinNode extends TempNode {
 }
 
 export default JoinNode;
-
-addNodeClass( 'JoinNode', JoinNode );

package/src/nodes/utils/LoopNode.js

@@ -1,9 +1,46 @@
-import Node, { addNodeClass } from '../core/Node.js';
+import Node from '../core/Node.js';
 import { expression } from '../code/ExpressionNode.js';
-import { nodeObject, nodeArray } from '../shadernode/ShaderNode.js';
-
+import { nodeObject, nodeArray } from '../tsl/TSLBase.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 }, () => {} );
+ * ```
+ * The module also provides `Break()` and `Continue()` TSL expression for loop control.
+ * @augments Node
+ */
 class LoopNode extends Node {
 
+	static get type() {
+
+		return 'LoopNode';
+
+	}
+
+	/**
+	 * 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();
@@ -12,12 +49,25 @@ 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.
+	 */
 	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 );
@@ -50,6 +100,12 @@ 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.
+	 */
 	getNodeType( builder ) {
 
 		const { returnsNode } = this.getProperties( builder );
@@ -96,10 +152,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 ) {
@@ -191,17 +247,47 @@ class LoopNode extends Node {
 
 export default LoopNode;
 
+/**
+ * TSL function for creating a loop node.
+ *
+ * @tsl
+ * @function
+ * @param {...any} params - A list of parameters.
+ * @returns {LoopNode}
+ */
 export const Loop = ( ...params ) => nodeObject( new LoopNode( nodeArray( params, 'int' ) ) ).append();
+
+/**
+ * TSL function for creating a `Continue()` expression.
+ *
+ * @tsl
+ * @function
+ * @returns {ExpressionNode}
+ */
 export const Continue = () => expression( 'continue' ).append();
+
+/**
+ * TSL function for creating a `Break()` expression.
+ *
+ * @tsl
+ * @function
+ * @returns {ExpressionNode}
+ */
 export const Break = () => expression( 'break' ).append();
 
-//
+// Deprecated
 
+/**
+ * @tsl
+ * @function
+ * @deprecated since r168. Use {@link Loop} instead.
+ *
+ * @param  {...any} params
+ * @returns {LoopNode}
+ */
 export const loop = ( ...params ) => { // @deprecated, r168
 
 	console.warn( 'TSL.LoopNode: loop() has been renamed to Loop().' );
 	return Loop( ...params );
 
 };
-
-addNodeClass( 'LoopNode', LoopNode );

package/src/nodes/utils/MatcapUVNode.js

@@ -1,11 +1,25 @@
 import TempNode from '../core/TempNode.js';
-import { transformedNormalView } from '../accessors/NormalNode.js';
-import { positionViewDirection } from '../accessors/PositionNode.js';
-import { nodeImmutable, vec2, vec3 } from '../shadernode/ShaderNode.js';
-import { addNodeClass } from '../core/Node.js';
-
+import { transformedNormalView } from '../accessors/Normal.js';
+import { positionViewDirection } from '../accessors/Position.js';
+import { nodeImmutable, vec2, vec3 } from '../tsl/TSLBase.js';
+
+/**
+ * Can be used to compute texture coordinates for projecting a
+ * matcap onto a mesh. Used by {@link MeshMatcapNodeMaterial}.
+ *
+ * @augments TempNode
+ */
 class MatcapUVNode extends TempNode {
 
+	static get type() {
+
+		return 'MatcapUVNode';
+
+	}
+
+	/**
+	 * Constructs a new matcap uv node.
+	 */
 	constructor() {
 
 		super( 'vec2' );
@@ -25,6 +39,11 @@ class MatcapUVNode extends TempNode {
 
 export default MatcapUVNode;
 
-export const matcapUV = nodeImmutable( MatcapUVNode );
-
-addNodeClass( 'MatcapUVNode', MatcapUVNode );
+/**
+ * TSL function for creating a matcap uv node.
+ *
+ * @tsl
+ * @function
+ * @returns {MatcapUVNode}
+ */
+export const matcapUV = /*@__PURE__*/ nodeImmutable( MatcapUVNode );

package/src/nodes/utils/MaxMipLevelNode.js

@@ -1,26 +1,71 @@
 import UniformNode from '../core/UniformNode.js';
 import { NodeUpdateType } from '../core/constants.js';
-import { nodeProxy } from '../shadernode/ShaderNode.js';
-import { addNodeClass } from '../core/Node.js';
-
+import { nodeProxy } from '../tsl/TSLBase.js';
+
+/**
+ * A special type of uniform node that computes the
+ * maximum mipmap level for a given texture node.
+ *
+ * ```js
+ * const level = maxMipLevel( textureNode );
+ * ```
+ *
+ * @augments UniformNode
+ */
 class MaxMipLevelNode extends UniformNode {
 
+	static get type() {
+
+		return 'MaxMipLevelNode';
+
+	}
+
+	/**
+	 * Constructs a new max mip level node.
+	 *
+	 * @param {TextureNode} textureNode - The texture node to compute the max mip level for.
+	 */
 	constructor( textureNode ) {
 
 		super( 0 );
 
+		/**
+		 * The texture node to compute the max mip level for.
+		 *
+		 * @private
+		 * @type {TextureNode}
+		 */
 		this._textureNode = textureNode;
 
+		/**
+		 * The `updateType` is set to `NodeUpdateType.FRAME` since the node updates
+		 * the texture once per frame in its {@link MaxMipLevelNode#update} method.
+		 *
+		 * @type {string}
+		 * @default 'frame'
+		 */
 		this.updateType = NodeUpdateType.FRAME;
 
 	}
 
+	/**
+	 * The texture node to compute the max mip level for.
+	 *
+	 * @readonly
+	 * @type {TextureNode}
+	 */
 	get textureNode() {
 
 		return this._textureNode;
 
 	}
 
+	/**
+	 * The texture.
+	 *
+	 * @readonly
+	 * @type {Texture}
+	 */
 	get texture() {
 
 		return this._textureNode.value;
@@ -47,6 +92,12 @@ class MaxMipLevelNode extends UniformNode {
 
 export default MaxMipLevelNode;
 
-export const maxMipLevel = nodeProxy( MaxMipLevelNode );
-
-addNodeClass( 'MaxMipLevelNode', 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 );

package/src/nodes/utils/MemberNode.js

@@ -0,0 +1,68 @@
+import Node from '../core/Node.js';
+
+/**
+ * Base class for representing member access on an object-like
+ * node data structures.
+ *
+ * @augments Node
+ */
+class MemberNode extends Node {
+
+	static get type() {
+
+		return 'MemberNode';
+
+	}
+
+	/**
+	 * Constructs an array element node.
+	 *
+	 * @param {Node} node - The array-like node.
+	 * @param {string} property - The property name.
+	 */
+	constructor( node, property ) {
+
+		super();
+
+		/**
+		 * The array-like node.
+		 *
+		 * @type {Node}
+		 */
+		this.node = node;
+
+		/**
+		 * The property name.
+		 *
+		 * @type {Node}
+		 */
+		this.property = property;
+
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
+		this.isMemberNode = true;
+
+	}
+
+	getNodeType( builder ) {
+
+		return this.node.getMemberType( builder, this.property );
+
+	}
+
+	generate( builder ) {
+
+		const propertyName = this.node.build( builder );
+
+		return propertyName + '.' + this.property;
+
+	}
+
+}
+
+export default MemberNode;