@plastic-software/three 0.167.4 → 0.174.0

package/src/nodes/core/PropertyNode.js

@@ -1,15 +1,61 @@
-import Node, { addNodeClass } from './Node.js';
-import { nodeImmutable, nodeObject } from '../shadernode/ShaderNode.js';
+import Node from './Node.js';
+import { nodeImmutable, nodeObject } from '../tsl/TSLCore.js';
 
+/**
+ * This class represents a shader property. It can be used
+ * to explicitly define a property and assign a value to it.
+ *
+ * ```js
+ * const threshold = property( 'float', 'threshold' ).assign( THRESHOLD );
+ *```
+ * `PropertyNode` is used by the engine to predefined common material properties
+ * for TSL code.
+ *
+ * @augments Node
+ */
 class PropertyNode extends Node {
 
+	static get type() {
+
+		return 'PropertyNode';
+
+	}
+
+	/**
+	 * Constructs a new property node.
+	 *
+	 * @param {string} nodeType - The type of the node.
+	 * @param {?string} [name=null] - The name of the property in the shader.
+	 * @param {boolean} [varying=false] - Whether this property is a varying or not.
+	 */
 	constructor( nodeType, name = null, varying = false ) {
 
 		super( nodeType );
 
+		/**
+		 * The name of the property in the shader. If no name is defined,
+		 * the node system auto-generates one.
+		 *
+		 * @type {?string}
+		 * @default null
+		 */
 		this.name = name;
+
+		/**
+		 * Whether this property is a varying or not.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.varying = varying;
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isPropertyNode = true;
 
 	}
@@ -20,6 +66,12 @@ class PropertyNode extends Node {
 
 	}
 
+	/**
+	 * The method is overwritten so it always returns `true`.
+	 *
+	 * @param {NodeBuilder} builder - The current node builder.
+	 * @return {boolean} Whether this node is global or not.
+	 */
 	isGlobal( /*builder*/ ) {
 
 		return true;
@@ -49,36 +101,248 @@ class PropertyNode extends Node {
 
 export default PropertyNode;
 
+/**
+ * TSL function for creating a property node.
+ *
+ * @tsl
+ * @function
+ * @param {string} type - The type of the node.
+ * @param {?string} [name=null] - The name of the property in the shader.
+ * @returns {PropertyNode}
+ */
 export const property = ( type, name ) => nodeObject( new PropertyNode( type, name ) );
+
+/**
+ * TSL function for creating a varying property node.
+ *
+ * @tsl
+ * @function
+ * @param {string} type - The type of the node.
+ * @param {?string} [name=null] - The name of the varying in the shader.
+ * @returns {PropertyNode}
+ */
 export const varyingProperty = ( type, name ) => nodeObject( new PropertyNode( type, name, true ) );
 
-export const diffuseColor = nodeImmutable( PropertyNode, 'vec4', 'DiffuseColor' );
-export const emissive = nodeImmutable( PropertyNode, 'vec3', 'EmissiveColor' );
-export const roughness = nodeImmutable( PropertyNode, 'float', 'Roughness' );
-export const metalness = nodeImmutable( PropertyNode, 'float', 'Metalness' );
-export const clearcoat = nodeImmutable( PropertyNode, 'float', 'Clearcoat' );
-export const clearcoatRoughness = nodeImmutable( PropertyNode, 'float', 'ClearcoatRoughness' );
-export const sheen = nodeImmutable( PropertyNode, 'vec3', 'Sheen' );
-export const sheenRoughness = nodeImmutable( PropertyNode, 'float', 'SheenRoughness' );
-export const iridescence = nodeImmutable( PropertyNode, 'float', 'Iridescence' );
-export const iridescenceIOR = nodeImmutable( PropertyNode, 'float', 'IridescenceIOR' );
-export const iridescenceThickness = nodeImmutable( PropertyNode, 'float', 'IridescenceThickness' );
-export const alphaT = nodeImmutable( PropertyNode, 'float', 'AlphaT' );
-export const anisotropy = nodeImmutable( PropertyNode, 'float', 'Anisotropy' );
-export const anisotropyT = nodeImmutable( PropertyNode, 'vec3', 'AnisotropyT' );
-export const anisotropyB = nodeImmutable( PropertyNode, 'vec3', 'AnisotropyB' );
-export const specularColor = nodeImmutable( PropertyNode, 'color', 'SpecularColor' );
-export const specularF90 = nodeImmutable( PropertyNode, 'float', 'SpecularF90' );
-export const shininess = nodeImmutable( PropertyNode, 'float', 'Shininess' );
-export const output = nodeImmutable( PropertyNode, 'vec4', 'Output' );
-export const dashSize = nodeImmutable( PropertyNode, 'float', 'dashSize' );
-export const gapSize = nodeImmutable( PropertyNode, 'float', 'gapSize' );
-export const pointWidth = nodeImmutable( PropertyNode, 'float', 'pointWidth' );
-export const ior = nodeImmutable( PropertyNode, 'float', 'IOR' );
-export const transmission = nodeImmutable( PropertyNode, 'float', 'Transmission' );
-export const thickness = nodeImmutable( PropertyNode, 'float', 'Thickness' );
-export const attenuationDistance = nodeImmutable( PropertyNode, 'float', 'AttenuationDistance' );
-export const attenuationColor = nodeImmutable( PropertyNode, 'color', 'AttenuationColor' );
-export const dispersion = nodeImmutable( PropertyNode, 'float', 'Dispersion' );
-
-addNodeClass( 'PropertyNode', PropertyNode );
+/**
+ * TSL object that represents the shader variable `DiffuseColor`.
+ *
+ * @tsl
+ * @type {PropertyNode<vec4>}
+ */
+export const diffuseColor = /*@__PURE__*/ nodeImmutable( PropertyNode, 'vec4', 'DiffuseColor' );
+
+/**
+ * TSL object that represents the shader variable `EmissiveColor`.
+ *
+ * @tsl
+ * @type {PropertyNode<vec3>}
+ */
+export const emissive = /*@__PURE__*/ nodeImmutable( PropertyNode, 'vec3', 'EmissiveColor' );
+
+/**
+ * TSL object that represents the shader variable `Roughness`.
+ *
+ * @tsl
+ * @type {PropertyNode<float>}
+ */
+export const roughness = /*@__PURE__*/ nodeImmutable( PropertyNode, 'float', 'Roughness' );
+
+/**
+ * TSL object that represents the shader variable `Metalness`.
+ *
+ * @tsl
+ * @type {PropertyNode<float>}
+ */
+export const metalness = /*@__PURE__*/ nodeImmutable( PropertyNode, 'float', 'Metalness' );
+
+/**
+ * TSL object that represents the shader variable `Clearcoat`.
+ *
+ * @tsl
+ * @type {PropertyNode<float>}
+ */
+export const clearcoat = /*@__PURE__*/ nodeImmutable( PropertyNode, 'float', 'Clearcoat' );
+
+/**
+ * TSL object that represents the shader variable `ClearcoatRoughness`.
+ *
+ * @tsl
+ * @type {PropertyNode<float>}
+ */
+export const clearcoatRoughness = /*@__PURE__*/ nodeImmutable( PropertyNode, 'float', 'ClearcoatRoughness' );
+
+/**
+ * TSL object that represents the shader variable `Sheen`.
+ *
+ * @tsl
+ * @type {PropertyNode<vec3>}
+ */
+export const sheen = /*@__PURE__*/ nodeImmutable( PropertyNode, 'vec3', 'Sheen' );
+
+/**
+ * TSL object that represents the shader variable `SheenRoughness`.
+ *
+ * @tsl
+ * @type {PropertyNode<float>}
+ */
+export const sheenRoughness = /*@__PURE__*/ nodeImmutable( PropertyNode, 'float', 'SheenRoughness' );
+
+/**
+ * TSL object that represents the shader variable `Iridescence`.
+ *
+ * @tsl
+ * @type {PropertyNode<float>}
+ */
+export const iridescence = /*@__PURE__*/ nodeImmutable( PropertyNode, 'float', 'Iridescence' );
+
+/**
+ * TSL object that represents the shader variable `IridescenceIOR`.
+ *
+ * @tsl
+ * @type {PropertyNode<float>}
+ */
+export const iridescenceIOR = /*@__PURE__*/ nodeImmutable( PropertyNode, 'float', 'IridescenceIOR' );
+
+/**
+ * TSL object that represents the shader variable `IridescenceThickness`.
+ *
+ * @tsl
+ * @type {PropertyNode<float>}
+ */
+export const iridescenceThickness = /*@__PURE__*/ nodeImmutable( PropertyNode, 'float', 'IridescenceThickness' );
+
+/**
+ * TSL object that represents the shader variable `AlphaT`.
+ *
+ * @tsl
+ * @type {PropertyNode<float>}
+ */
+export const alphaT = /*@__PURE__*/ nodeImmutable( PropertyNode, 'float', 'AlphaT' );
+
+/**
+ * TSL object that represents the shader variable `Anisotropy`.
+ *
+ * @tsl
+ * @type {PropertyNode<float>}
+ */
+export const anisotropy = /*@__PURE__*/ nodeImmutable( PropertyNode, 'float', 'Anisotropy' );
+
+/**
+ * TSL object that represents the shader variable `AnisotropyT`.
+ *
+ * @tsl
+ * @type {PropertyNode<vec3>}
+ */
+export const anisotropyT = /*@__PURE__*/ nodeImmutable( PropertyNode, 'vec3', 'AnisotropyT' );
+
+/**
+ * TSL object that represents the shader variable `AnisotropyB`.
+ *
+ * @tsl
+ * @type {PropertyNode<vec3>}
+ */
+export const anisotropyB = /*@__PURE__*/ nodeImmutable( PropertyNode, 'vec3', 'AnisotropyB' );
+
+/**
+ * TSL object that represents the shader variable `SpecularColor`.
+ *
+ * @tsl
+ * @type {PropertyNode<color>}
+ */
+export const specularColor = /*@__PURE__*/ nodeImmutable( PropertyNode, 'color', 'SpecularColor' );
+
+/**
+ * TSL object that represents the shader variable `SpecularF90`.
+ *
+ * @tsl
+ * @type {PropertyNode<float>}
+ */
+export const specularF90 = /*@__PURE__*/ nodeImmutable( PropertyNode, 'float', 'SpecularF90' );
+
+/**
+ * TSL object that represents the shader variable `Shininess`.
+ *
+ * @tsl
+ * @type {PropertyNode<float>}
+ */
+export const shininess = /*@__PURE__*/ nodeImmutable( PropertyNode, 'float', 'Shininess' );
+
+/**
+ * TSL object that represents the shader variable `Output`.
+ *
+ * @tsl
+ * @type {PropertyNode<vec4>}
+ */
+export const output = /*@__PURE__*/ nodeImmutable( PropertyNode, 'vec4', 'Output' );
+
+/**
+ * TSL object that represents the shader variable `dashSize`.
+ *
+ * @tsl
+ * @type {PropertyNode<float>}
+ */
+export const dashSize = /*@__PURE__*/ nodeImmutable( PropertyNode, 'float', 'dashSize' );
+
+/**
+ * TSL object that represents the shader variable `gapSize`.
+ *
+ * @tsl
+ * @type {PropertyNode<float>}
+ */
+export const gapSize = /*@__PURE__*/ nodeImmutable( PropertyNode, 'float', 'gapSize' );
+
+/**
+ * TSL object that represents the shader variable `pointWidth`.
+ *
+ * @tsl
+ * @type {PropertyNode<float>}
+ */
+export const pointWidth = /*@__PURE__*/ nodeImmutable( PropertyNode, 'float', 'pointWidth' );
+
+/**
+ * TSL object that represents the shader variable `IOR`.
+ *
+ * @tsl
+ * @type {PropertyNode<float>}
+ */
+export const ior = /*@__PURE__*/ nodeImmutable( PropertyNode, 'float', 'IOR' );
+
+/**
+ * TSL object that represents the shader variable `Transmission`.
+ *
+ * @tsl
+ * @type {PropertyNode<float>}
+ */
+export const transmission = /*@__PURE__*/ nodeImmutable( PropertyNode, 'float', 'Transmission' );
+
+/**
+ * TSL object that represents the shader variable `Thickness`.
+ *
+ * @tsl
+ * @type {PropertyNode<float>}
+ */
+export const thickness = /*@__PURE__*/ nodeImmutable( PropertyNode, 'float', 'Thickness' );
+
+/**
+ * TSL object that represents the shader variable `AttenuationDistance`.
+ *
+ * @tsl
+ * @type {PropertyNode<float>}
+ */
+export const attenuationDistance = /*@__PURE__*/ nodeImmutable( PropertyNode, 'float', 'AttenuationDistance' );
+
+/**
+ * TSL object that represents the shader variable `AttenuationColor`.
+ *
+ * @tsl
+ * @type {PropertyNode<color>}
+ */
+export const attenuationColor = /*@__PURE__*/ nodeImmutable( PropertyNode, 'color', 'AttenuationColor' );
+
+/**
+ * TSL object that represents the shader variable `Dispersion`.
+ *
+ * @tsl
+ * @type {PropertyNode<float>}
+ */
+export const dispersion = /*@__PURE__*/ nodeImmutable( PropertyNode, 'float', 'Dispersion' );

package/src/nodes/core/StackNode.js

@@ -1,20 +1,69 @@
-import Node, { addNodeClass } from './Node.js';
-import { select } from '../math/CondNode.js';
-import { ShaderNode, nodeProxy, getCurrentStack, setCurrentStack } from '../shadernode/ShaderNode.js';
-
+import Node from './Node.js';
+import { select } from '../math/ConditionalNode.js';
+import { ShaderNode, nodeProxy, getCurrentStack, setCurrentStack } from '../tsl/TSLBase.js';
+
+/**
+ * Stack is a helper for Nodes that need to produce stack-based code instead of continuous flow.
+ * They are usually needed in cases like `If`, `Else`.
+ *
+ * @augments Node
+ */
 class StackNode extends Node {
 
+	static get type() {
+
+		return 'StackNode';
+
+	}
+
+	/**
+	 * Constructs a new stack node.
+	 *
+	 * @param {?StackNode} [parent=null] - The parent stack node.
+	 */
 	constructor( parent = null ) {
 
 		super();
 
+		/**
+		 * List of nodes.
+		 *
+		 * @type {Array<Node>}
+		 */
 		this.nodes = [];
+
+		/**
+		 * The output node.
+		 *
+		 * @type {?Node}
+		 * @default null
+		 */
 		this.outputNode = null;
 
+		/**
+		 * The parent stack node.
+		 *
+		 * @type {?StackNode}
+		 * @default null
+		 */
 		this.parent = parent;
 
+		/**
+		 * The current conditional node.
+		 *
+		 * @private
+		 * @type {ConditionalNode}
+		 * @default null
+		 */
 		this._currentCond = null;
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isStackNode = true;
 
 	}
@@ -25,6 +74,18 @@ class StackNode extends Node {
 
 	}
 
+	getMemberType( builder, name ) {
+
+		return this.outputNode ? this.outputNode.getMemberType( builder, name ) : 'void';
+
+	}
+
+	/**
+	 * Adds a node to this stack.
+	 *
+	 * @param {Node} node - The node to add.
+	 * @return {StackNode} A reference to this stack node.
+	 */
 	add( node ) {
 
 		this.nodes.push( node );
@@ -33,6 +94,13 @@ class StackNode extends Node {
 
 	}
 
+	/**
+	 * Represent an `if` statement in TSL.
+	 *
+	 * @param {Node} boolNode - Represents the condition.
+	 * @param {Function} method - TSL code which is executed if the condition evaluates to `true`.
+	 * @return {StackNode} A reference to this stack node.
+	 */
 	If( boolNode, method ) {
 
 		const methodNode = new ShaderNode( method );
@@ -42,6 +110,13 @@ class StackNode extends Node {
 
 	}
 
+	/**
+	 * Represent an `elseif` statement in TSL.
+	 *
+	 * @param {Node} boolNode - Represents the condition.
+	 * @param {Function} method - TSL code which is executed if the condition evaluates to `true`.
+	 * @return {StackNode} A reference to this stack node.
+	 */
 	ElseIf( boolNode, method ) {
 
 		const methodNode = new ShaderNode( method );
@@ -54,6 +129,12 @@ class StackNode extends Node {
 
 	}
 
+	/**
+	 * Represent an `else` statement in TSL.
+	 *
+	 * @param {Function} method - TSL code which is executed in the `else` case.
+	 * @return {StackNode} A reference to this stack node.
+	 */
 	Else( method ) {
 
 		this._currentCond.elseNode = new ShaderNode( method );
@@ -80,8 +161,15 @@ class StackNode extends Node {
 
 	}
 
-	//
+	// Deprecated
 
+	/**
+	 * @function
+	 * @deprecated since r168. Use {@link StackNode#Else} instead.
+	 *
+	 * @param  {...any} params
+	 * @returns {StackNode}
+	 */
 	else( ...params ) { // @deprecated, r168
 
 		console.warn( 'TSL.StackNode: .else() has been renamed to .Else().' );
@@ -89,6 +177,12 @@ class StackNode extends Node {
 
 	}
 
+	/**
+	 * @deprecated since r168. Use {@link StackNode#ElseIf} instead.
+	 *
+	 * @param  {...any} params
+	 * @returns {StackNode}
+	 */
 	elseif( ...params ) { // @deprecated, r168
 
 		console.warn( 'TSL.StackNode: .elseif() has been renamed to .ElseIf().' );
@@ -100,6 +194,12 @@ class StackNode extends Node {
 
 export default StackNode;
 
-export const stack = nodeProxy( StackNode );
-
-addNodeClass( 'StackNode', StackNode );
+/**
+ * TSL function for creating a stack node.
+ *
+ * @tsl
+ * @function
+ * @param {?StackNode} [parent=null] - The parent stack node.
+ * @returns {StackNode}
+ */
+export const stack = /*@__PURE__*/ nodeProxy( StackNode );

package/src/nodes/core/StructNode.js

@@ -0,0 +1,120 @@
+import Node from './Node.js';
+import StructTypeNode from './StructTypeNode.js';
+import { nodeObject } from '../tsl/TSLCore.js';
+
+/**
+ * StructNode allows to create custom structures with multiple members.
+ * This can also be used to define structures in attribute and uniform data.
+ *
+ * ```js
+ * // Define a custom struct
+ * const BoundingBox = struct( { min: 'vec3', max: 'vec3' } );
+ *
+ * // Create a new instance of the struct
+ * const bb = BoundingBox( vec3( 0 ), vec3( 1 ) ); // style 1
+ * const bb = BoundingBox( { min: vec3( 0 ), max: vec3( 1 ) } ); // style 2
+ *
+ * // Access the struct members
+ * const min = bb.get( 'min' );
+ *
+ * // Assign a new value to a member
+ * min.assign( vec3() );
+ * ```
+ * @augments Node
+ */
+class StructNode extends Node {
+
+	static get type() {
+
+		return 'StructNode';
+
+	}
+
+	constructor( structLayoutNode, values ) {
+
+		super( 'vec3' );
+
+		this.structLayoutNode = structLayoutNode;
+		this.values = values;
+
+		this.isStructNode = true;
+
+	}
+
+	getNodeType( builder ) {
+
+		return this.structLayoutNode.getNodeType( builder );
+
+	}
+
+	getMemberType( builder, name ) {
+
+		return this.structLayoutNode.getMemberType( builder, name );
+
+	}
+
+	generate( builder ) {
+
+		const nodeVar = builder.getVarFromNode( this );
+		const structType = nodeVar.type;
+		const propertyName = builder.getPropertyName( nodeVar );
+
+		builder.addLineFlowCode( `${ propertyName } = ${ builder.generateStruct( structType, this.structLayoutNode.membersLayout, this.values ) }`, this );
+
+		return nodeVar.name;
+
+	}
+
+}
+
+export default StructNode;
+
+/**
+ * TSL function for creating a struct node.
+ *
+ * @tsl
+ * @function
+ * @param {Object} membersLayout - The layout of the struct members.
+ * @param {string} [name=null] - The name of the struct.
+ * @returns {Function} The struct function.
+ */
+export const struct = ( membersLayout, name = null ) => {
+
+	const structLayout = new StructTypeNode( membersLayout, name );
+
+	const struct = ( ...params ) => {
+
+		let values = null;
+
+		if ( params.length > 0 ) {
+
+			if ( params[ 0 ].isNode ) {
+
+				values = {};
+
+				const names = Object.keys( membersLayout );
+
+				for ( let i = 0; i < params.length; i ++ ) {
+
+					values[ names[ i ] ] = params[ i ];
+
+				}
+
+			} else {
+
+				values = params[ 0 ];
+
+			}
+
+		}
+
+		return nodeObject( new StructNode( structLayout, values ) );
+
+	};
+
+	struct.layout = structLayout;
+	struct.isStruct = true;
+
+	return struct;
+
+};

package/src/nodes/core/StructType.js

@@ -0,0 +1,13 @@
+class StructType {
+
+	constructor( name, members ) {
+
+		this.name = name;
+		this.members = members;
+		this.output = false;
+
+	}
+
+}
+
+export default StructType;