super-three 0.171.0 → 0.173.0

package/src/nodes/core/LightingModel.js

@@ -1,15 +1,75 @@
+/**
+ * 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.
+	 *
+	 * @abstract
+	 * @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.
+	 *
+	 * @abstract
+	 * @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.
+	 *
+	 * @abstract
+	 * @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.
+	 *
+	 * @abstract
+	 * @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.
+	 *
+	 * @abstract
+	 * @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.
+	 *
+	 * @abstract
+	 * @param {ContextNode} input - The current node context.
+	 * @param {StackNode} stack - The current stack.
+	 * @param {NodeBuilder} builder - The current node builder.
+	 */
 	ambientOcclusion( /*input, stack, builder*/ ) { }
 
 }

package/src/nodes/core/MRTNode.js

@@ -1,6 +1,15 @@
 import OutputStructNode from './OutputStructNode.js';
 import { nodeProxy, vec4 } from '../tsl/TSLBase.js';
 
+/** @module MRTNode **/
+
+/**
+ * Returns the MRT texture index for the given name.
+ *
+ * @param {Array<Texture>} textures - The textures of a MRT-configured render target.
+ * @param {String} name - The name of the MRT texture which index is requested.
+ * @return {Number} The texture index.
+ */
 export function getTextureIndex( textures, name ) {
 
 	for ( let i = 0; i < textures.length; i ++ ) {
@@ -17,6 +26,19 @@ export function getTextureIndex( textures, name ) {
 
 }
 
+/**
+ * This node can be used setup a MRT context for rendering. A typical MRT setup for
+ * post-processing is shown below:
+ * ```js
+ * const mrtNode = mrt( {
+ *   output: output,
+ *   normal: normalView
+ * } ) );
+ * ```
+ * The MRT output is defined as a dictionary.
+ *
+ * @augments OutputStructNode
+ */
 class MRTNode extends OutputStructNode {
 
 	static get type() {
@@ -25,28 +47,65 @@ class MRTNode extends OutputStructNode {
 
 	}
 
+	/**
+	 * Constructs a new output struct node.
+	 *
+	 * @param {Object<String, Node>} outputNodes - The MRT outputs.
+	 */
 	constructor( outputNodes ) {
 
 		super();
 
+		/**
+		 * A dictionary representing the MRT outputs. The key
+		 * is the name of the output, the value the node which produces
+		 * the output result.
+		 *
+		 * @type {Object<String, Node>}
+		 */
 		this.outputNodes = outputNodes;
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {Boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isMRTNode = true;
 
 	}
 
+	/**
+	 * Returns `true` if the MRT node has an output with the given name.
+	 *
+	 * @param {String} name - The name of the output.
+	 * @return {NodeBuilder} Whether the MRT node has an output for the given name or not.
+	 */
 	has( name ) {
 
 		return this.outputNodes[ name ] !== undefined;
 
 	}
 
+	/**
+	 * Returns the output node for the given name.
+	 *
+	 * @param {String} name - The name of the output.
+	 * @return {Node} The output node.
+	 */
 	get( name ) {
 
 		return this.outputNodes[ name ];
 
 	}
 
+	/**
+	 * Merges the outputs of the given MRT node with the outputs of this node.
+	 *
+	 * @param {MRTNode} mrtNode - The MRT to merge.
+	 * @return {MRTNode} A new MRT node with merged outputs..
+	 */
 	merge( mrtNode ) {
 
 		const outputs = { ...this.outputNodes, ...mrtNode.outputNodes };
@@ -82,4 +141,11 @@ class MRTNode extends OutputStructNode {
 
 export default MRTNode;
 
+/**
+ * TSL function for creating a MRT node.
+ *
+ * @function
+ * @param {Object<String, Node>} outputNodes - The MRT outputs.
+ * @returns {MRTNode}
+ */
 export const mrt = /*@__PURE__*/ nodeProxy( MRTNode );