Node: Document more modules. (#30001)

* Node: Document more modules.

* Docs: Fix typo.

* Docs: More clean up.

Author: Mugen87

src/nodes/code/CodeNode.js

@@ -1,6 +1,13 @@
 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() {
@@ -9,25 +16,69 @@ class CodeNode extends Node {
 
 	}
 
+	/**
+	 * 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;
@@ -36,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;

src/nodes/code/ExpressionNode.js

@@ -1,6 +1,12 @@
 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() {
@@ -9,10 +15,22 @@ class ExpressionNode extends Node {
 
 	}
 
+	/**
+	 * Constructs a new expression node.
+	 *
+	 * @param {String} [snippet=''] - The native code snippet.
+	 * @param {String} [includes='void'] - The node type.
+	 */
 	constructor( snippet = '', nodeType = 'void' ) {
 
 		super( nodeType );
 
+		/**
+		 * The native code snippet.
+		 *
+		 * @type {String}
+		 * @default ''
+		 */
 		this.snippet = snippet;
 
 	}

src/nodes/core/ContextNode.js

@@ -1,6 +1,16 @@
 import Node from './Node.js';
 import { addMethodChaining, nodeProxy } from '../tsl/TSLCore.js';
 
+/**
+ * This node can be used as a context management component for another node.
+ * {@link NodeBuilder} performs its node building process in a specific context and
+ * this node allows the modify the context. A typical use case is to overwrite `getUV()` e.g.:
+ *
+ * ```js
+ *node.context( { getUV: () => customCoord } );
+ *```
+ * @augments Node
+ */
 class ContextNode extends Node {
 
 	static get type() {
@@ -9,23 +19,59 @@ class ContextNode extends Node {
 
 	}
 
+	/**
+	 * Constructs a new context node.
+	 *
+	 * @param {Node} node - The node whose context should be modified.
+	 * @param {Object} [value={}] - The modified context data.
+	 */
 	constructor( node, value = {} ) {
 
 		super();
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {Boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isContextNode = true;
 
+		/**
+		 * The node whose context should be modified.
+		 *
+		 * @type {Node}
+		 */
 		this.node = node;
+
+		/**
+		 * The modified context data.
+		 *
+		 * @type {Object}
+		 * @default {}
+		 */
 		this.value = value;
 
 	}
 
+	/**
+	 * This method is overwritten to ensure it returns the reference to {@link ContextNode#node}.
+	 *
+	 * @return {Node} A reference to {@link ContextNode#node}.
+	 */
 	getScope() {
 
 		return this.node.getScope();
 
 	}
 
+	/**
+	 * This method is overwritten to ensure it returns the type to {@link ContextNode#node}.
+	 *
+	 * @param {NodeBuilder} builder - The current node builder.
+	 * @return {String} The type of {@link ContextNode#node}.
+	 */
 	getNodeType( builder ) {
 
 		return this.node.getNodeType( builder );

src/nodes/core/IndexNode.js

@@ -1,6 +1,19 @@
 import Node from './Node.js';
 import { nodeImmutable, varying } from '../tsl/TSLBase.js';
 
+/**
+ * This class represents shader indices of different types. The following predefined node
+ * objects cover frequent use cases:
+ *
+ * - `vertexIndex`: The index of a vertex within a mesh.
+ * - `instanceIndex`: The index of either a mesh instance or an invocation of a compute shader.
+ * - `drawIndex`: The index of a draw call.
+ * - `invocationLocalIndex`: The index of a compute invocation within the scope of a workgroup load.
+ * - `invocationSubgroupIndex`: The index of a compute invocation within the scope of a subgroup.
+ * - `subgroupIndex`: The index of the subgroup the current compute invocation belongs to.
+ *
+ * @augments Node
+ */
 class IndexNode extends Node {
 
 	static get type() {
@@ -9,13 +22,30 @@ class IndexNode extends Node {
 
 	}
 
+	/**
+	 * Constructs a new index node.
+	 *
+	 * @param {('vertex'|'instance'|'subgroup'|'invocationLocal'|'invocationSubgroup'|'draw')} value - The scope of the index node.
+	 */
 	constructor( scope ) {
 
 		super( 'uint' );
 
+		/**
+		 * The scope of the index node.
+		 *
+		 * @type {String}
+		 */
 		this.scope = scope;
 
-		this.isInstanceIndexNode = true;
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {Boolean}
+		 * @readonly
+		 * @default true
+		 */
+		this.isIndexNode = true;
 
 	}
 
@@ -28,32 +58,26 @@ class IndexNode extends Node {
 
 		if ( scope === IndexNode.VERTEX ) {
 
-			// The index of a vertex within a mesh.
 			propertyName = builder.getVertexIndex();
 
 		} else if ( scope === IndexNode.INSTANCE ) {
 
-			// The index of either a mesh instance or an invocation of a compute shader.
 			propertyName = builder.getInstanceIndex();
 
 		} else if ( scope === IndexNode.DRAW ) {
 
-			// The index of a draw call.
 			propertyName = builder.getDrawIndex();
 
 		} else if ( scope === IndexNode.INVOCATION_LOCAL ) {
 
-			// The index of a compute invocation within the scope of a workgroup load.
 			propertyName = builder.getInvocationLocalIndex();
 
 		} else if ( scope === IndexNode.INVOCATION_SUBGROUP ) {
 
-			// The index of a compute invocation within the scope of a subgroup.
 			propertyName = builder.getInvocationSubgroupIndex();
 
 		} else if ( scope === IndexNode.SUBGROUP ) {
 
-			// The index of the subgroup the current compute invocation belongs to.
 			propertyName = builder.getSubgroupIndex();
 
 		} else {

src/nodes/core/LightingModel.js

@@ -1,15 +1,69 @@
+/**
+ * Abstract class for implementing lighting models. The module defines
+ * multiple methods that concrete lighting models can implement. These
+ * methods are executed at different points during the light evaluation
+ * process.
+ */
 class LightingModel {
 
+	/**
+	 * This method is intended for setting up lighting model and context data
+	 * which are later used in the evaluation process.
+	 *
+	 * @param {ContextNode} input - The current node context.
+	 * @param {StackNode} stack - The current stack.
+	 * @param {NodeBuilder} builder - The current node builder.
+	 */
 	start( /*input, stack, builder*/ ) { }
 
+	/**
+	 * This method is intended for executing final tasks like final updates
+	 * to the outgoing light.
+	 *
+	 * @param {ContextNode} input - The current node context.
+	 * @param {StackNode} stack - The current stack.
+	 * @param {NodeBuilder} builder - The current node builder.
+	 */
 	finish( /*input, stack, builder*/ ) { }
 
+	/**
+	 * This method is intended for implementing the direct light term and
+	 * executed during the build process of directional, point and spot light nodes.
+	 *
+	 * @param {Object} input - The input data.
+	 * @param {StackNode} stack - The current stack.
+	 * @param {NodeBuilder} builder - The current node builder.
+	 */
 	direct( /*input, stack, builder*/ ) { }
 
+	/**
+	 * This method is intended for implementing the direct light term for
+	 * rect area light nodes.
+	 *
+	 * @param {Object} input - The input data.
+	 * @param {StackNode} stack - The current stack.
+	 * @param {NodeBuilder} builder - The current node builder.
+	 */
 	directRectArea( /*input, stack, builder*/ ) {}
 
+	/**
+	 * This method is intended for implementing the indirect light term.
+	 *
+	 * @param {ContextNode} input - The current node context.
+	 * @param {StackNode} stack - The current stack.
+	 * @param {NodeBuilder} builder - The current node builder.
+	 */
 	indirect( /*input, stack, builder*/ ) { }
 
+	/**
+	 * This method is intended for implementing the ambient occlusion term.
+	 * Unlike other methods, this method must be called manually by the lighting
+	 * model in its indirect term.
+	 *
+	 * @param {ContextNode} input - The current node context.
+	 * @param {StackNode} stack - The current stack.
+	 * @param {NodeBuilder} builder - The current node builder.
+	 */
 	ambientOcclusion( /*input, stack, builder*/ ) { }
 
 }