Node: Document more modules. (#30135)

* Node: Document more modules.

* Clean up.

* Node: Document more modules.

* Fix E2E.

examples/jsm/tsl/display/AfterImageNode.js

@@ -1,11 +1,18 @@
 import { RenderTarget, Vector2, QuadMesh, NodeMaterial, PostProcessingUtils, TempNode, NodeUpdateType } from 'three/webgpu';
 import { nodeObject, Fn, float, vec4, uv, texture, passTexture, uniform, sign, max, convertToTexture } from 'three/tsl';
 
+/** @module AfterImageNode **/
+
 const _size = /*@__PURE__*/ new Vector2();
 const _quadMeshComp = /*@__PURE__*/ new QuadMesh();
 
 let _rendererState;
 
+/**
+ * Post processing node for creating an after image effect.
+ *
+ * @augments TempNode
+ */
 class AfterImageNode extends TempNode {
 
 	static get type() {
@@ -14,39 +21,103 @@ class AfterImageNode extends TempNode {
 
 	}
 
+	/**
+	 * Constructs a new after image node.
+	 *
+	 * @param {TextureNode} textureNode - The texture node that represents the input of the effect.
+	 * @param {Number} [damp=0.96] - The damping intensity. A higher value means a stronger after image effect.
+	 */
 	constructor( textureNode, damp = 0.96 ) {
 
 		super( 'vec4' );
 
+		/**
+		 * The texture node that represents the input of the effect.
+		 *
+		 * @type {TextureNode}
+		 */
 		this.textureNode = textureNode;
+
+		/**
+		 * The texture represents the pervious frame.
+		 *
+		 * @type {TextureNode}
+		 */
 		this.textureNodeOld = texture();
+
+		/**
+		 * The damping intensity as a uniform node.
+		 *
+		 * @type {UniformNode<float>}
+		 */
 		this.damp = uniform( damp );
 
+		/**
+		 * The render target used for compositing the effect.
+		 *
+		 * @private
+		 * @type {RenderTarget}
+		 */
 		this._compRT = new RenderTarget( 1, 1, { depthBuffer: false } );
 		this._compRT.texture.name = 'AfterImageNode.comp';
 
+		/**
+		 * The render target that represents the previous frame.
+		 *
+		 * @private
+		 * @type {RenderTarget}
+		 */
 		this._oldRT = new RenderTarget( 1, 1, { depthBuffer: false } );
 		this._oldRT.texture.name = 'AfterImageNode.old';
 
+		/**
+		 * The result of the effect is represented as a separate texture node.
+		 *
+		 * @private
+		 * @type {PassTextureNode}
+		 */
 		this._textureNode = passTexture( this, this._compRT.texture );
 
+		/**
+		 * The `updateBeforeType` is set to `NodeUpdateType.FRAME` since the node renders
+		 * its effect once per frame in `updateBefore()`.
+		 *
+		 * @type {String}
+		 * @default 'frame'
+		 */
 		this.updateBeforeType = NodeUpdateType.FRAME;
 
 	}
 
+	/**
+	 * Returns the result of the effect as a texture node.
+	 *
+	 * @return {PassTextureNode} A texture node that represents the result of the effect.
+	 */
 	getTextureNode() {
 
 		return this._textureNode;
 
 	}
 
+	/**
+	 * Sets the size of the effect.
+	 *
+	 * @param {Number} width - The width of the effect.
+	 * @param {Number} height - The height of the effect.
+	 */
 	setSize( width, height ) {
 
 		this._compRT.setSize( width, height );
 		this._oldRT.setSize( width, height );
 
 	}
 
+	/**
+	 * This method is used to render the effect once per frame.
+	 *
+	 * @param {NodeFrame} frame - The current node frame.
+	 */
 	updateBefore( frame ) {
 
 		const { renderer } = frame;
@@ -90,6 +161,12 @@ class AfterImageNode extends TempNode {
 
 	}
 
+	/**
+	 * This method is used to setup the effect's TSL code.
+	 *
+	 * @param {NodeBuilder} builder - The current node builder.
+	 * @return {PassTextureNode}
+	 */
 	setup( builder ) {
 
 		const textureNode = this.textureNode;
@@ -141,6 +218,10 @@ class AfterImageNode extends TempNode {
 
 	}
 
+	/**
+	 * Frees internal resources. This method should be called
+	 * when the effect is no longer required.
+	 */
 	dispose() {
 
 		this._compRT.dispose();
@@ -150,6 +231,14 @@ class AfterImageNode extends TempNode {
 
 }
 
+/**
+ * TSL function for creating an after image node for post processing.
+ *
+ * @function
+ * @param {Node<vec4>} node - The node that represents the input of the effect.
+ * @param {Number} [damp=0.96] - The damping intensity. A higher value means a stronger after image effect.
+ * @returns {AfterImageNode}
+ */
 export const afterImage = ( node, damp ) => nodeObject( new AfterImageNode( convertToTexture( node ), damp ) );
 
 export default AfterImageNode;

examples/jsm/tsl/display/AnaglyphPassNode.js

@@ -2,6 +2,13 @@ import { Matrix3, NodeMaterial } from 'three/webgpu';
 import { clamp, nodeObject, Fn, vec4, uv, uniform, max } from 'three/tsl';
 import StereoCompositePassNode from './StereoCompositePassNode.js';
 
+/** @module AnaglyphPassNode **/
+
+/**
+ * A render pass node that creates an anaglyph effect.
+ *
+ * @augments StereoCompositePassNode
+ */
 class AnaglyphPassNode extends StereoCompositePassNode {
 
 	static get type() {
@@ -10,20 +17,43 @@ class AnaglyphPassNode extends StereoCompositePassNode {
 
 	}
 
+	/**
+	 * Constructs a new anaglyph pass node.
+	 *
+	 * @param {Scene} scene - The scene to render.
+	 * @param {Camera} camera - The camera to render the scene with.
+	 */
 	constructor( scene, camera ) {
 
 		super( scene, camera );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {Boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isAnaglyphPassNode = true;
 
 		// Dubois matrices from https://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.7.6968&rep=rep1&type=pdf#page=4
 
+		/**
+		 * Color matrix node for the left eye.
+		 *
+		 * @type {UniformNode<mat3>}
+		 */
 		this._colorMatrixLeft = uniform( new Matrix3().fromArray( [
 			0.456100, - 0.0400822, - 0.0152161,
 			0.500484, - 0.0378246, - 0.0205971,
 			0.176381, - 0.0157589, - 0.00546856
 		] ) );
 
+		/**
+		 * Color matrix node for the right eye.
+		 *
+		 * @type {UniformNode<mat3>}
+		 */
 		this._colorMatrixRight = uniform( new Matrix3().fromArray( [
 			- 0.0434706, 0.378476, - 0.0721527,
 			- 0.0879388, 0.73364, - 0.112961,
@@ -32,6 +62,12 @@ class AnaglyphPassNode extends StereoCompositePassNode {
 
 	}
 
+	/**
+	 * This method is used to setup the effect's TSL code.
+	 *
+	 * @param {NodeBuilder} builder - The current node builder.
+	 * @return {PassTextureNode}
+	 */
 	setup( builder ) {
 
 		const uvNode = uv();
@@ -60,4 +96,12 @@ class AnaglyphPassNode extends StereoCompositePassNode {
 
 export default AnaglyphPassNode;
 
+/**
+ * TSL function for creating an anaglyph pass node.
+ *
+ * @function
+ * @param {Scene} scene - The scene to render.
+ * @param {Camera} camera - The camera to render the scene with.
+ * @returns {AnaglyphPassNode}
+ */
 export const anaglyphPass = ( scene, camera ) => nodeObject( new AnaglyphPassNode( scene, camera ) );

examples/jsm/tsl/display/BleachBypass.js

@@ -1,5 +1,15 @@
 import { float, Fn, vec3, vec4, min, max, mix, luminance } from 'three/tsl';
 
+/** @module BleachBypass **/
+
+/**
+ * Applies a bleach bypass effect to the given color node.
+ *
+ * @function
+ * @param {Node<vec4>} color - The color node to apply the sepia for.
+ * @param {Node<float>} [opacity=1] - Influences how strong the effect is blended with the original color.
+ * @return {Node<vec4>} The updated color node.
+ */
 export const bleach = /*@__PURE__*/ Fn( ( [ color, opacity = 1 ] ) => {
 
 	const base = color;

examples/jsm/tsl/display/DepthOfFieldNode.js

@@ -1,6 +1,13 @@
 import { TempNode, NodeUpdateType } from 'three/webgpu';
 import { convertToTexture, nodeObject, Fn, uv, uniform, vec2, vec4, clamp } from 'three/tsl';
 
+/** @module DepthOfFieldNode **/
+
+/**
+ * Post processing node for creating depth of field (DOF) effect.
+ *
+ * @augments TempNode
+ */
 class DepthOfFieldNode extends TempNode {
 
 	static get type() {
@@ -9,23 +16,78 @@ class DepthOfFieldNode extends TempNode {
 
 	}
 
+	/**
+	 * Constructs a new DOF node.
+	 *
+	 * @param {TextureNode} textureNode - The texture node that represents the input of the effect.
+	 * @param {Node<float>} viewZNode - Represents the viewZ depth values of the scene.
+	 * @param {Node<float>} focusNode - Defines the effect's focus which is the distance along the camera's look direction in world units.
+	 * @param {Node<float>} apertureNode - Defines the effect's aperture.
+	 * @param {Node<float>} maxblurNode - Defines the effect's maximum blur.
+	 */
 	constructor( textureNode, viewZNode, focusNode, apertureNode, maxblurNode ) {
 
 		super( 'vec4' );
 
+		/**
+		 * The texture node that represents the input of the effect.
+		 *
+		 * @type {TextureNode}
+		 */
 		this.textureNode = textureNode;
+
+		/**
+		 * Represents the viewZ depth values of the scene.
+		 *
+		 * @type {Node<float>}
+		 */
 		this.viewZNode = viewZNode;
 
+		/**
+		 * Defines the effect's focus which is the distance along the camera's look direction in world units.
+		 *
+		 * @type {Node<float>}
+		 */
 		this.focusNode = focusNode;
+
+		/**
+		 * Defines the effect's aperture.
+		 *
+		 * @type {Node<float>}
+		 */
 		this.apertureNode = apertureNode;
+
+		/**
+		 * Defines the effect's maximum blur.
+		 *
+		 * @type {Node<float>}
+		 */
 		this.maxblurNode = maxblurNode;
 
+		/**
+		 * Represents the input's aspect ratio.
+		 *
+		 * @private
+		 * @type {UniformNode<float>}
+		 */
 		this._aspect = uniform( 0 );
 
+		/**
+		 * The `updateBeforeType` is set to `NodeUpdateType.FRAME` since the node updates
+		 * its internal uniforms once per frame in `updateBefore()`.
+		 *
+		 * @type {String}
+		 * @default 'frame'
+		 */
 		this.updateBeforeType = NodeUpdateType.FRAME;
 
 	}
 
+	/**
+	 * This method is used to update the effect's uniforms once per frame.
+	 *
+	 * @param {NodeFrame} frame - The current node frame.
+	 */
 	updateBefore() {
 
 		const map = this.textureNode.value;
@@ -34,6 +96,12 @@ class DepthOfFieldNode extends TempNode {
 
 	}
 
+	/**
+	 * This method is used to setup the effect's TSL code.
+	 *
+	 * @param {NodeBuilder} builder - The current node builder.
+	 * @return {ShaderCallNodeInternal}
+	 */
 	setup() {
 
 		const textureNode = this.textureNode;
@@ -116,4 +184,15 @@ class DepthOfFieldNode extends TempNode {
 
 export default DepthOfFieldNode;
 
+/**
+ * TSL function for creating a depth-of-field effect (DOF) for post processing.
+ *
+ * @function
+ * @param {Node<vec4>} node - The node that represents the input of the effect.
+ * @param {Node<float>} viewZNode - Represents the viewZ depth values of the scene.
+ * @param {Node<float> | Number} focus - Defines the effect's focus which is the distance along the camera's look direction in world units.
+ * @param {Node<float> | Number} aperture - Defines the effect's aperture.
+ * @param {Node<float> | Number} maxblur - Defines the effect's maximum blur.
+ * @returns {DepthOfFieldNode}
+ */
 export const dof = ( node, viewZNode, focus = 1, aperture = 0.025, maxblur = 1 ) => nodeObject( new DepthOfFieldNode( convertToTexture( node ), nodeObject( viewZNode ), nodeObject( focus ), nodeObject( aperture ), nodeObject( maxblur ) ) );