@plastic-software/three 0.167.3 → 0.174.0

package/src/nodes/accessors/VertexColorNode.js

@@ -1,21 +1,54 @@
-import { addNodeClass } from '../core/Node.js';
 import AttributeNode from '../core/AttributeNode.js';
-import { nodeObject } from '../shadernode/ShaderNode.js';
-
+import { nodeObject } from '../tsl/TSLBase.js';
 import { Vector4 } from '../../math/Vector4.js';
 
+/**
+ * An attribute node for representing vertex colors.
+ *
+ * @augments AttributeNode
+ */
 class VertexColorNode extends AttributeNode {
 
+	static get type() {
+
+		return 'VertexColorNode';
+
+	}
+
+	/**
+	 * Constructs a new vertex color node.
+	 *
+	 * @param {number} [index=0] - The attribute index.
+	 */
 	constructor( index = 0 ) {
 
 		super( null, 'vec4' );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isVertexColorNode = true;
 
+		/**
+		 * The attribute index to enable more than one sets of vertex colors.
+		 *
+		 * @type {number}
+		 * @default 0
+		 */
 		this.index = index;
 
 	}
 
+	/**
+	 * Overwrites the default implementation by honoring the attribute index.
+	 *
+	 * @param {NodeBuilder} builder - The current node builder.
+	 * @return {string} The attribute name.
+	 */
 	getAttributeName( /*builder*/ ) {
 
 		const index = this.index;
@@ -66,6 +99,12 @@ class VertexColorNode extends AttributeNode {
 
 export default VertexColorNode;
 
-export const vertexColor = ( ...params ) => nodeObject( new VertexColorNode( ...params ) );
-
-addNodeClass( 'VertexColorNode', VertexColorNode );
+/**
+ * TSL function for creating a reference node.
+ *
+ * @tsl
+ * @function
+ * @param {number} index - The attribute index.
+ * @returns {VertexColorNode}
+ */
+export const vertexColor = ( index ) => nodeObject( new VertexColorNode( index ) );

package/src/nodes/code/CodeNode.js

@@ -1,27 +1,84 @@
-import Node, { addNodeClass } from '../core/Node.js';
-import { nodeProxy } from '../shadernode/ShaderNode.js';
-
+import Node from '../core/Node.js';
+import { nodeProxy } from '../tsl/TSLBase.js';
+
+/**
+ * This class represents native code sections. It is the base
+ * class for modules like {@link FunctionNode} which allows to implement
+ * functions with native shader languages.
+ *
+ * @augments Node
+ */
 class CodeNode extends Node {
 
+	static get type() {
+
+		return 'CodeNode';
+
+	}
+
+	/**
+	 * Constructs a new code node.
+	 *
+	 * @param {string} [code=''] - The native code.
+	 * @param {Array<Node>} [includes=[]] - An array of includes.
+	 * @param {('js'|'wgsl'|'glsl')} [language=''] - The used language.
+	 */
 	constructor( code = '', includes = [], language = '' ) {
 
 		super( 'code' );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isCodeNode = true;
 
+		/**
+		 * The native code.
+		 *
+		 * @type {string}
+		 * @default ''
+		 */
 		this.code = code;
-		this.language = language;
 
+		/**
+		 * An array of includes
+		 *
+		 * @type {Array<Node>}
+		 * @default []
+		 */
 		this.includes = includes;
 
+		/**
+		 * The used language.
+		 *
+		 * @type {('js'|'wgsl'|'glsl')}
+		 * @default ''
+		 */
+		this.language = language;
+
 	}
 
+	/**
+	 * The method is overwritten so it always returns `true`.
+	 *
+	 * @return {boolean} Whether this node is global or not.
+	 */
 	isGlobal() {
 
 		return true;
 
 	}
 
+	/**
+	 * Sets the includes of this code node.
+	 *
+	 * @param {Array<Node>} includes - The includes to set.
+	 * @return {CodeNode} A reference to this node.
+	 */
 	setIncludes( includes ) {
 
 		this.includes = includes;
@@ -30,6 +87,12 @@ class CodeNode extends Node {
 
 	}
 
+	/**
+	 * Returns the includes of this code node.
+	 *
+	 * @param {NodeBuilder} builder - The current node builder.
+	 * @return {Array<Node>} The includes.
+	 */
 	getIncludes( /*builder*/ ) {
 
 		return this.includes;
@@ -75,10 +138,47 @@ class CodeNode extends Node {
 
 export default CodeNode;
 
-export const code = nodeProxy( CodeNode );
-
+/**
+ * TSL function for creating a code node.
+ *
+ * @tsl
+ * @function
+ * @param {string} [code=''] - The native code.
+ * @param {Array<Node>} [includes=[]] - An array of includes.
+ * @param {('js'|'wgsl'|'glsl')} [language=''] - The used language.
+ * @returns {CodeNode}
+ */
+export const code = /*@__PURE__*/ nodeProxy( CodeNode );
+
+/**
+ * TSL function for creating a JS code node.
+ *
+ * @tsl
+ * @function
+ * @param {string} src - The native code.
+ * @param {Array<Node>} includes - An array of includes.
+ * @returns {CodeNode}
+ */
 export const js = ( src, includes ) => code( src, includes, 'js' );
+
+/**
+ * TSL function for creating a WGSL code node.
+ *
+ * @tsl
+ * @function
+ * @param {string} src - The native code.
+ * @param {Array<Node>} includes - An array of includes.
+ * @returns {CodeNode}
+ */
 export const wgsl = ( src, includes ) => code( src, includes, 'wgsl' );
-export const glsl = ( src, includes ) => code( src, includes, 'glsl' );
 
-addNodeClass( 'CodeNode', CodeNode );
+/**
+ * TSL function for creating a GLSL code node.
+ *
+ * @tsl
+ * @function
+ * @param {string} src - The native code.
+ * @param {Array<Node>} includes - An array of includes.
+ * @returns {CodeNode}
+ */
+export const glsl = ( src, includes ) => code( src, includes, 'glsl' );

package/src/nodes/code/ExpressionNode.js

@@ -1,12 +1,36 @@
-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 can be used to implement basic expressions in shader code.
+ * Basic examples for that are `return`, `continue` or `discard` statements.
+ *
+ * @augments Node
+ */
 class ExpressionNode extends Node {
 
+	static get type() {
+
+		return 'ExpressionNode';
+
+	}
+
+	/**
+	 * Constructs a new expression node.
+	 *
+	 * @param {string} [snippet=''] - The native code snippet.
+	 * @param {string} [nodeType='void'] - The node type.
+	 */
 	constructor( snippet = '', nodeType = 'void' ) {
 
 		super( nodeType );
 
+		/**
+		 * The native code snippet.
+		 *
+		 * @type {string}
+		 * @default ''
+		 */
 		this.snippet = snippet;
 
 	}
@@ -18,7 +42,7 @@ class ExpressionNode extends Node {
 
 		if ( type === 'void' ) {
 
-			builder.addLineFlowCode( snippet );
+			builder.addLineFlowCode( snippet, this );
 
 		} else {
 
@@ -32,6 +56,13 @@ class ExpressionNode extends Node {
 
 export default ExpressionNode;
 
-export const expression = nodeProxy( ExpressionNode );
-
-addNodeClass( 'ExpressionNode', ExpressionNode );
+/**
+ * TSL function for creating an expression node.
+ *
+ * @tsl
+ * @function
+ * @param {string} [snippet=''] - The native code snippet.
+ * @param {string} [nodeType='void'] - The node type.
+ * @returns {ExpressionNode}
+ */
+export const expression = /*@__PURE__*/ nodeProxy( ExpressionNode );

package/src/nodes/code/FunctionCallNode.js

@@ -1,18 +1,55 @@
 import TempNode from '../core/TempNode.js';
-import { addNodeClass } from '../core/Node.js';
-import { addNodeElement, nodeArray, nodeObject, nodeObjects } from '../shadernode/ShaderNode.js';
-
+import { addMethodChaining, nodeArray, nodeObject, nodeObjects } from '../tsl/TSLCore.js';
+
+/**
+ * This module represents the call of a {@link FunctionNode}. Developers are usually not confronted
+ * with this module since they use the predefined TSL syntax `wgslFn` and `glslFn` which encapsulate
+ * this logic.
+ *
+ * @augments TempNode
+ */
 class FunctionCallNode extends TempNode {
 
+	static get type() {
+
+		return 'FunctionCallNode';
+
+	}
+
+	/**
+	 * Constructs a new function call node.
+	 *
+	 * @param {?FunctionNode} functionNode - The function node.
+	 * @param {Object<string, Node>} [parameters={}] - The parameters for the function call.
+	 */
 	constructor( functionNode = null, parameters = {} ) {
 
 		super();
 
+		/**
+		 * The function node.
+		 *
+		 * @type {?FunctionNode}
+		 * @default null
+		 */
 		this.functionNode = functionNode;
+
+		/**
+		 * The parameters of the function call.
+		 *
+		 * @type {Object<string, Node>}
+		 * @default {}
+		 */
 		this.parameters = parameters;
 
 	}
 
+	/**
+	 * Sets the parameters of the function call node.
+	 *
+	 * @param {Object<string, Node>} parameters - The parameters to set.
+	 * @return {FunctionCallNode} A reference to this node.
+	 */
 	setParameters( parameters ) {
 
 		this.parameters = parameters;
@@ -21,6 +58,11 @@ class FunctionCallNode extends TempNode {
 
 	}
 
+	/**
+	 * Returns the parameters of the function call node.
+	 *
+	 * @return {Object<string, Node>} The parameters of this node.
+	 */
 	getParameters() {
 
 		return this.parameters;
@@ -42,14 +84,25 @@ class FunctionCallNode extends TempNode {
 		const inputs = functionNode.getInputs( builder );
 		const parameters = this.parameters;
 
+		const generateInput = ( node, inputNode ) => {
+
+			const type = inputNode.type;
+			const pointer = type === 'pointer';
+
+			let output;
+
+			if ( pointer ) output = '&' + node.build( builder );
+			else output = node.build( builder, type );
+
+			return output;
+
+		};
+
 		if ( Array.isArray( parameters ) ) {
 
 			for ( let i = 0; i < parameters.length; i ++ ) {
 
-				const inputNode = inputs[ i ];
-				const node = parameters[ i ];
-
-				params.push( node.build( builder, inputNode.type ) );
+				params.push( generateInput( parameters[ i ], inputs[ i ] ) );
 
 			}
 
@@ -61,7 +114,7 @@ class FunctionCallNode extends TempNode {
 
 				if ( node !== undefined ) {
 
-					params.push( node.build( builder, inputNode.type ) );
+					params.push( generateInput( node, inputNode ) );
 
 				} else {
 
@@ -91,6 +144,4 @@ export const call = ( func, ...params ) => {
 
 };
 
-addNodeElement( 'call', call );
-
-addNodeClass( 'FunctionCallNode', FunctionCallNode );
+addMethodChaining( 'call', call );

package/src/nodes/code/FunctionNode.js

@@ -1,15 +1,51 @@
 import CodeNode from './CodeNode.js';
-import { addNodeClass } from '../core/Node.js';
-import { nodeObject } from '../shadernode/ShaderNode.js';
-
+import { nodeObject } from '../tsl/TSLBase.js';
+
+/**
+ * This class represents a native shader function. It can be used to implement
+ * certain aspects of a node material with native shader code. There are two predefined
+ * TSL functions for easier usage.
+ *
+ * - `wgslFn`: Creates a WGSL function node.
+ * - `glslFn`: Creates a GLSL function node.
+ *
+ * A basic example with one include looks like so:
+ *
+ * ```js
+ * const desaturateWGSLFn = wgslFn( `
+ *	fn desaturate( color:vec3<f32> ) -> vec3<f32> {
+ *		let lum = vec3<f32>( 0.299, 0.587, 0.114 );
+ *		return vec3<f32>( dot( lum, color ) );
+ *	}`
+ *);
+ * const someWGSLFn = wgslFn( `
+ *	fn someFn( color:vec3<f32> ) -> vec3<f32> {
+ * 		return desaturate( color );
+ * 	}
+ * `, [ desaturateWGSLFn ] );
+ * material.colorNode = someWGSLFn( { color: texture( map ) } );
+ *```
+ * @augments CodeNode
+ */
 class FunctionNode extends CodeNode {
 
+	static get type() {
+
+		return 'FunctionNode';
+
+	}
+
+	/**
+	 * Constructs a new function node.
+	 *
+	 * @param {string} [code=''] - The native code.
+	 * @param {Array<Node>} [includes=[]] - An array of includes.
+	 * @param {('js'|'wgsl'|'glsl')} [language=''] - The used language.
+	 */
 	constructor( code = '', includes = [], language = '' ) {
 
 		super( code, includes, language );
 
-		this.keywords = {};
-
 	}
 
 	getNodeType( builder ) {
@@ -18,12 +54,24 @@ class FunctionNode extends CodeNode {
 
 	}
 
+	/**
+	 * Returns the inputs of this function node.
+	 *
+	 * @param {NodeBuilder} builder - The current node builder.
+	 * @return {Array<NodeFunctionInput>} The inputs.
+	 */
 	getInputs( builder ) {
 
 		return this.getNodeFunction( builder ).inputs;
 
 	}
 
+	/**
+	 * Returns the node function for this function node.
+	 *
+	 * @param {NodeBuilder} builder - The current node builder.
+	 * @return {NodeFunction} The node function.
+	 */
 	getNodeFunction( builder ) {
 
 		const nodeData = builder.getDataFromNode( this );
@@ -63,23 +111,7 @@ class FunctionNode extends CodeNode {
 
 		const propertyName = builder.getPropertyName( nodeCode );
 
-		let code = this.getNodeFunction( builder ).getCode( propertyName );
-
-		const keywords = this.keywords;
-		const keywordsProperties = Object.keys( keywords );
-
-		if ( keywordsProperties.length > 0 ) {
-
-			for ( const property of keywordsProperties ) {
-
-				const propertyRegExp = new RegExp( `\\b${property}\\b`, 'g' );
-				const nodeProperty = keywords[ property ].build( builder, 'property' );
-
-				code = code.replace( propertyRegExp, nodeProperty );
-
-			}
-
-		}
+		const code = this.getNodeFunction( builder ).getCode( propertyName );
 
 		nodeCode.code = code + '\n';
 
@@ -126,5 +158,3 @@ const nativeFn = ( code, includes = [], language = '' ) => {
 
 export const glslFn = ( code, includes ) => nativeFn( code, includes, 'glsl' );
 export const wgslFn = ( code, includes ) => nativeFn( code, includes, 'wgsl' );
-
-addNodeClass( 'FunctionNode', FunctionNode );