super-three 0.170.1 → 0.172.0

package/src/nodes/core/NodeVar.js

@@ -1,10 +1,40 @@
+/**
+ * {@link NodeBuilder} is going to create instances of this class during the build process
+ * of nodes. They represent the final shader variables that are going to be generated
+ * by the builder. A dictionary of node variables is maintained in {@link NodeBuilder#vars} for
+ * this purpose.
+ */
 class NodeVar {
 
+	/**
+	 * Constructs a new node variable.
+	 *
+	 * @param {String} name - The name of the variable.
+	 * @param {String} type - The type of the variable.
+	 */
 	constructor( name, type ) {
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {Boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isNodeVar = true;
 
+		/**
+		 * The name of the variable.
+		 *
+		 * @type {String}
+		 */
 		this.name = name;
+
+		/**
+		 * The type of the variable.
+		 *
+		 * @type {String}
+		 */
 		this.type = type;
 
 	}

package/src/nodes/core/NodeVarying.js

@@ -1,13 +1,41 @@
 import NodeVar from './NodeVar.js';
 
+/**
+ * {@link NodeBuilder} is going to create instances of this class during the build process
+ * of nodes. They represent the final shader varyings that are going to be generated
+ * by the builder. An array of node varyings is maintained in {@link NodeBuilder#varyings} for
+ * this purpose.
+ *
+ * @augments NodeVar
+ */
 class NodeVarying extends NodeVar {
 
+	/**
+	 * Constructs a new node varying.
+	 *
+	 * @param {String} name - The name of the varying.
+	 * @param {String} type - The type of the varying.
+	 */
 	constructor( name, type ) {
 
 		super( name, type );
 
+		/**
+		 * Whether this varying requires interpolation or not. This property can be used
+		 * to check if the varying can be optimized for a variable.
+		 *
+		 * @type {Boolean}
+		 * @default false
+		 */
 		this.needsInterpolation = false;
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {Boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isNodeVarying = true;
 
 	}

package/src/nodes/core/OutputStructNode.js

@@ -1,7 +1,13 @@
 import Node from './Node.js';
-import StructTypeNode from './StructTypeNode.js';
 import { nodeProxy } from '../tsl/TSLBase.js';
 
+/** @module OutputStructNode **/
+
+/**
+ * This node can be used to define multiple outputs in a shader programs.
+ *
+ * @augments Node
+ */
 class OutputStructNode extends Node {
 
 	static get type() {
@@ -10,12 +16,30 @@ class OutputStructNode extends Node {
 
 	}
 
+	/**
+	 * Constructs a new output struct node. The constructor can be invoked with an
+	 * arbitrary number of nodes representing the members.
+	 *
+	 * @param {...Node} members - A parameter list of nodes.
+	 */
 	constructor( ...members ) {
 
 		super();
 
+		/**
+		 * An array of nodes which defines the output.
+		 *
+		 * @type {Array<Node>}
+		 */
 		this.members = members;
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {Boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isOutputStructNode = true;
 
 	}
@@ -33,7 +57,7 @@ class OutputStructNode extends Node {
 
 		}
 
-		this.nodeType = builder.getStructTypeFromNode( new StructTypeNode( types ) ).name;
+		this.nodeType = builder.getStructTypeFromNode( this, types ).name;
 
 	}
 
@@ -60,4 +84,11 @@ class OutputStructNode extends Node {
 
 export default OutputStructNode;
 
+/**
+ * TSL function for creating an output struct node.
+ *
+ * @function
+ * @param {...Node} members - A parameter list of nodes.
+ * @returns {OutputStructNode}
+ */
 export const outputStruct = /*@__PURE__*/ nodeProxy( OutputStructNode );

package/src/nodes/core/ParameterNode.js

@@ -1,6 +1,13 @@
 import { nodeObject } from '../tsl/TSLBase.js';
 import PropertyNode from './PropertyNode.js';
 
+/** @module ParameterNode **/
+
+/**
+ * Special version of {@link PropertyNode} which is used for parameters.
+ *
+ * @augments PropertyNode
+ */
 class ParameterNode extends PropertyNode {
 
 	static get type() {
@@ -9,10 +16,23 @@ class ParameterNode extends PropertyNode {
 
 	}
 
+	/**
+	 * Constructs a new parameter node.
+	 *
+	 * @param {String} nodeType - The type of the node.
+	 * @param {String?} [name=null] - The name of the parameter in the shader.
+	 */
 	constructor( nodeType, name = null ) {
 
 		super( nodeType, name );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {Boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isParameterNode = true;
 
 	}
@@ -33,4 +53,12 @@ class ParameterNode extends PropertyNode {
 
 export default ParameterNode;
 
+/**
+ * TSL function for creating a parameter node.
+ *
+ * @function
+ * @param {String} type - The type of the node.
+ * @param {String?} name - The name of the parameter in the shader.
+ * @returns {ParameterNode}
+ */
 export const parameter = ( type, name ) => nodeObject( new ParameterNode( type, name ) );

package/src/nodes/core/PropertyNode.js

@@ -1,6 +1,20 @@
 import Node from './Node.js';
 import { nodeImmutable, nodeObject } from '../tsl/TSLCore.js';
 
+/** @module PropertyNode **/
+
+/**
+ * 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() {
@@ -9,13 +23,41 @@ class PropertyNode extends Node {
 
 	}
 
+	/**
+	 * 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;
 
 	}
@@ -26,6 +68,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;
@@ -55,34 +103,218 @@ class PropertyNode extends Node {
 
 export default PropertyNode;
 
+/**
+ * TSL function for creating a property node.
+ *
+ * @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.
+ *
+ * @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 ) );
 
+/**
+ * TSL object that represents the shader variable `DiffuseColor`.
+ *
+ * @type {PropertyNode<vec4>}
+ */
 export const diffuseColor = /*@__PURE__*/ nodeImmutable( PropertyNode, 'vec4', 'DiffuseColor' );
+
+/**
+ * TSL object that represents the shader variable `EmissiveColor`.
+ *
+ * @type {PropertyNode<vec3>}
+ */
 export const emissive = /*@__PURE__*/ nodeImmutable( PropertyNode, 'vec3', 'EmissiveColor' );
+
+/**
+ * TSL object that represents the shader variable `Roughness`.
+ *
+ * @type {PropertyNode<float>}
+ */
 export const roughness = /*@__PURE__*/ nodeImmutable( PropertyNode, 'float', 'Roughness' );
+
+/**
+ * TSL object that represents the shader variable `Metalness`.
+ *
+ * @type {PropertyNode<float>}
+ */
 export const metalness = /*@__PURE__*/ nodeImmutable( PropertyNode, 'float', 'Metalness' );
+
+/**
+ * TSL object that represents the shader variable `Clearcoat`.
+ *
+ * @type {PropertyNode<float>}
+ */
 export const clearcoat = /*@__PURE__*/ nodeImmutable( PropertyNode, 'float', 'Clearcoat' );
+
+/**
+ * TSL object that represents the shader variable `ClearcoatRoughness`.
+ *
+ * @type {PropertyNode<float>}
+ */
 export const clearcoatRoughness = /*@__PURE__*/ nodeImmutable( PropertyNode, 'float', 'ClearcoatRoughness' );
+
+/**
+ * TSL object that represents the shader variable `Sheen`.
+ *
+ * @type {PropertyNode<vec3>}
+ */
 export const sheen = /*@__PURE__*/ nodeImmutable( PropertyNode, 'vec3', 'Sheen' );
+
+/**
+ * TSL object that represents the shader variable `SheenRoughness`.
+ *
+ * @type {PropertyNode<float>}
+ */
 export const sheenRoughness = /*@__PURE__*/ nodeImmutable( PropertyNode, 'float', 'SheenRoughness' );
+
+/**
+ * TSL object that represents the shader variable `Iridescence`.
+ *
+ * @type {PropertyNode<float>}
+ */
 export const iridescence = /*@__PURE__*/ nodeImmutable( PropertyNode, 'float', 'Iridescence' );
+
+/**
+ * TSL object that represents the shader variable `IridescenceIOR`.
+ *
+ * @type {PropertyNode<float>}
+ */
 export const iridescenceIOR = /*@__PURE__*/ nodeImmutable( PropertyNode, 'float', 'IridescenceIOR' );
+
+/**
+ * TSL object that represents the shader variable `IridescenceThickness`.
+ *
+ * @type {PropertyNode<float>}
+ */
 export const iridescenceThickness = /*@__PURE__*/ nodeImmutable( PropertyNode, 'float', 'IridescenceThickness' );
+
+/**
+ * TSL object that represents the shader variable `AlphaT`.
+ *
+ * @type {PropertyNode<float>}
+ */
 export const alphaT = /*@__PURE__*/ nodeImmutable( PropertyNode, 'float', 'AlphaT' );
+
+/**
+ * TSL object that represents the shader variable `Anisotropy`.
+ *
+ * @type {PropertyNode<float>}
+ */
 export const anisotropy = /*@__PURE__*/ nodeImmutable( PropertyNode, 'float', 'Anisotropy' );
+
+/**
+ * TSL object that represents the shader variable `AnisotropyT`.
+ *
+ * @type {PropertyNode<vec3>}
+ */
 export const anisotropyT = /*@__PURE__*/ nodeImmutable( PropertyNode, 'vec3', 'AnisotropyT' );
+
+/**
+ * TSL object that represents the shader variable `AnisotropyB`.
+ *
+ * @type {PropertyNode<vec3>}
+ */
 export const anisotropyB = /*@__PURE__*/ nodeImmutable( PropertyNode, 'vec3', 'AnisotropyB' );
+
+/**
+ * TSL object that represents the shader variable `SpecularColor`.
+ *
+ * @type {PropertyNode<color>}
+ */
 export const specularColor = /*@__PURE__*/ nodeImmutable( PropertyNode, 'color', 'SpecularColor' );
+
+/**
+ * TSL object that represents the shader variable `SpecularF90`.
+ *
+ * @type {PropertyNode<float>}
+ */
 export const specularF90 = /*@__PURE__*/ nodeImmutable( PropertyNode, 'float', 'SpecularF90' );
+
+/**
+ * TSL object that represents the shader variable `Shininess`.
+ *
+ * @type {PropertyNode<float>}
+ */
 export const shininess = /*@__PURE__*/ nodeImmutable( PropertyNode, 'float', 'Shininess' );
+
+/**
+ * TSL object that represents the shader variable `Output`.
+ *
+ * @type {PropertyNode<vec4>}
+ */
 export const output = /*@__PURE__*/ nodeImmutable( PropertyNode, 'vec4', 'Output' );
+
+/**
+ * TSL object that represents the shader variable `dashSize`.
+ *
+ * @type {PropertyNode<float>}
+ */
 export const dashSize = /*@__PURE__*/ nodeImmutable( PropertyNode, 'float', 'dashSize' );
+
+/**
+ * TSL object that represents the shader variable `gapSize`.
+ *
+ * @type {PropertyNode<float>}
+ */
 export const gapSize = /*@__PURE__*/ nodeImmutable( PropertyNode, 'float', 'gapSize' );
+
+/**
+ * TSL object that represents the shader variable `pointWidth`.
+ *
+ * @type {PropertyNode<float>}
+ */
 export const pointWidth = /*@__PURE__*/ nodeImmutable( PropertyNode, 'float', 'pointWidth' );
+
+/**
+ * TSL object that represents the shader variable `IOR`.
+ *
+ * @type {PropertyNode<float>}
+ */
 export const ior = /*@__PURE__*/ nodeImmutable( PropertyNode, 'float', 'IOR' );
+
+/**
+ * TSL object that represents the shader variable `Transmission`.
+ *
+ * @type {PropertyNode<float>}
+ */
 export const transmission = /*@__PURE__*/ nodeImmutable( PropertyNode, 'float', 'Transmission' );
+
+/**
+ * TSL object that represents the shader variable `Thickness`.
+ *
+ * @type {PropertyNode<float>}
+ */
 export const thickness = /*@__PURE__*/ nodeImmutable( PropertyNode, 'float', 'Thickness' );
+
+/**
+ * TSL object that represents the shader variable `AttenuationDistance`.
+ *
+ * @type {PropertyNode<float>}
+ */
 export const attenuationDistance = /*@__PURE__*/ nodeImmutable( PropertyNode, 'float', 'AttenuationDistance' );
+
+/**
+ * TSL object that represents the shader variable `AttenuationColor`.
+ *
+ * @type {PropertyNode<color>}
+ */
 export const attenuationColor = /*@__PURE__*/ nodeImmutable( PropertyNode, 'color', 'AttenuationColor' );
+
+/**
+ * TSL object that represents the shader variable `Dispersion`.
+ *
+ * @type {PropertyNode<float>}
+ */
 export const dispersion = /*@__PURE__*/ nodeImmutable( PropertyNode, 'float', 'Dispersion' );

package/src/nodes/core/StackNode.js

@@ -2,6 +2,14 @@ import Node from './Node.js';
 import { select } from '../math/ConditionalNode.js';
 import { ShaderNode, nodeProxy, getCurrentStack, setCurrentStack } from '../tsl/TSLBase.js';
 
+/** @module StackNode **/
+
+/**
+ * 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() {
@@ -10,17 +18,54 @@ class StackNode extends Node {
 
 	}
 
+	/**
+	 * 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;
 
 	}
@@ -31,6 +76,12 @@ class StackNode extends Node {
 
 	}
 
+	/**
+	 * 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 );
@@ -39,6 +90,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 );
@@ -48,6 +106,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 );
@@ -60,6 +125,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 );
@@ -106,4 +177,11 @@ class StackNode extends Node {
 
 export default StackNode;
 
+/**
+ * TSL function for creating a stack node.
+ *
+ * @function
+ * @param {StackNode?} [parent=null] - The parent stack node.
+ * @returns {StackNode}
+ */
 export const stack = /*@__PURE__*/ nodeProxy( StackNode );

package/src/nodes/core/StructTypeNode.js

@@ -1,5 +1,11 @@
 import Node from './Node.js';
 
+/**
+ * {@link NodeBuilder} is going to create instances of this class during the build process
+ * of nodes. They represent the final shader struct data that are going to be generated
+ * by the builder. A dictionary of struct types is maintained in {@link NodeBuilder#structs}
+ * for this purpose.
+ */
 class StructTypeNode extends Node {
 
 	static get type() {
@@ -8,15 +14,47 @@ class StructTypeNode extends Node {
 
 	}
 
-	constructor( types ) {
+	/**
+	 * Constructs a new struct type node.
+	 *
+	 * @param {String} name - The name of the struct.
+	 * @param {Array<String>} types - An array of types.
+	 */
+	constructor( name, types ) {
 
 		super();
 
+		/**
+		 * The name of the struct.
+		 *
+		 * @type {String}
+		 */
+		this.name = name;
+
+
+		/**
+		 * An array of types.
+		 *
+		 * @type {Array<String>}
+		 */
 		this.types = types;
+
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {Boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isStructTypeNode = true;
 
 	}
 
+	/**
+	 * Returns the member types.
+	 *
+	 * @return {Array<String>} The types.
+	 */
 	getMemberTypes() {
 
 		return this.types;