super-three 0.171.0 → 0.172.0

package/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,12 +96,18 @@ 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;
 		const uvNode = textureNode.uvNode || uv();
 
-		const sampleTexture = ( uv ) => textureNode.uv( uv );
+		const sampleTexture = ( uv ) => textureNode.sample( uv );
 
 		const dof = Fn( () => {
 
@@ -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 ) ) );

package/examples/jsm/tsl/display/DotScreenNode.js

@@ -1,6 +1,13 @@
-import { Vector2, TempNode } from 'three/webgpu';
+import { TempNode } from 'three/webgpu';
 import { nodeObject, Fn, uv, uniform, vec2, vec3, sin, cos, add, vec4, screenSize } from 'three/tsl';
 
+/** @module DotScreenNode **/
+
+/**
+ * Post processing node for creating dot-screen effect.
+ *
+ * @augments TempNode
+ */
 class DotScreenNode extends TempNode {
 
 	static get type() {
@@ -9,17 +16,46 @@ class DotScreenNode extends TempNode {
 
 	}
 
-	constructor( inputNode, center = new Vector2( 0.5, 0.5 ), angle = 1.57, scale = 1 ) {
+	/**
+	 * Constructs a new dot screen node.
+	 *
+	 * @param {Node} inputNode - The node that represents the input of the effect.
+	 * @param {Number} [angle=1.57] - The rotation of the effect in radians.
+	 * @param {Number} [scale=1] - The scale of the effect. A higher value means smaller dots.
+	 */
+	constructor( inputNode, angle = 1.57, scale = 1 ) {
 
 		super( 'vec4' );
 
+		/**
+		 * The node that represents the input of the effect.
+		 *
+		 * @type {Node}
+		 */
 		this.inputNode = inputNode;
-		this.center = uniform( center );
+
+		/**
+		 * A uniform node that represents the rotation of the effect in radians.
+		 *
+		 * @type {UniformNode<float>}
+		 */
 		this.angle = uniform( angle );
+
+		/**
+		 * A uniform node that represents the scale of the effect. A higher value means smaller dots.
+		 *
+		 * @type {UniformNode<float>}
+		 */
 		this.scale = uniform( scale );
 
 	}
 
+	/**
+	 * This method is used to setup the effect's TSL code.
+	 *
+	 * @param {NodeBuilder} builder - The current node builder.
+	 * @return {ShaderCallNodeInternal}
+	 */
 	setup() {
 
 		const inputNode = this.inputNode;
@@ -29,7 +65,7 @@ class DotScreenNode extends TempNode {
 			const s = sin( this.angle );
 			const c = cos( this.angle );
 
-			const tex = uv().mul( screenSize ).sub( this.center );
+			const tex = uv().mul( screenSize );
 			const point = vec2( c.mul( tex.x ).sub( s.mul( tex.y ) ), s.mul( tex.x ).add( c.mul( tex.y ) ) ).mul( this.scale );
 
 			return sin( point.x ).mul( sin( point.y ) ).mul( 4 );
@@ -56,4 +92,13 @@ class DotScreenNode extends TempNode {
 
 export default DotScreenNode;
 
-export const dotScreen = ( node, center, angle, scale ) => nodeObject( new DotScreenNode( nodeObject( node ), center, angle, scale ) );
+/**
+ * TSL function for creating a dot-screen node for post processing.
+ *
+ * @function
+ * @param {Node<vec4>} node - The node that represents the input of the effect.
+ * @param {Number} [angle=1.57] - The rotation of the effect in radians.
+ * @param {Number} [scale=1] - The scale of the effect. A higher value means smaller dots.
+ * @returns {DotScreenNode}
+ */
+export const dotScreen = ( node, angle, scale ) => nodeObject( new DotScreenNode( nodeObject( node ), angle, scale ) );

package/examples/jsm/tsl/display/FXAANode.js

@@ -1,6 +1,14 @@
 import { Vector2, TempNode } from 'three/webgpu';
 import { nodeObject, Fn, uniformArray, select, float, NodeUpdateType, uv, dot, clamp, uniform, convertToTexture, smoothstep, bool, vec2, vec3, If, Loop, max, min, Break, abs } from 'three/tsl';
 
+/** @module FXAANode **/
+
+/**
+ * Post processing node for applying FXAA. This node requires sRGB input
+ * so tone mapping and color space conversion must happen before the anti-aliasing.
+ *
+ * @augments TempNode
+ */
 class FXAANode extends TempNode {
 
 	static get type() {
@@ -9,19 +17,47 @@ class FXAANode extends TempNode {
 
 	}
 
+	/**
+	 * Constructs a new FXAA node.
+	 *
+	 * @param {TextureNode} textureNode - The texture node that represents the input of the effect.
+	 */
 	constructor( textureNode ) {
 
 		super( 'vec4' );
 
+		/**
+		 * The texture node that represents the input of the effect.
+		 *
+		 * @type {TextureNode}
+		 */
 		this.textureNode = textureNode;
 
+		/**
+		 * 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;
 
+		/**
+		 * A uniform node holding the inverse resolution value.
+		 *
+		 * @private
+		 * @type {UniformNode<vec2>}
+		 */
 		this._invSize = uniform( new Vector2() );
 
 	}
 
-	updateBefore() {
+	/**
+	 * This method is used to update the effect's uniforms once per frame.
+	 *
+	 * @param {NodeFrame} frame - The current node frame.
+	 */
+	updateBefore( /* frame */ ) {
 
 		const map = this.textureNode.value;
 
@@ -29,7 +65,13 @@ class FXAANode extends TempNode {
 
 	}
 
-	setup() {
+	/**
+	 * This method is used to setup the effect's TSL code.
+	 *
+	 * @param {NodeBuilder} builder - The current node builder.
+	 * @return {ShaderCallNodeInternal}
+	 */
+	setup( /* builder */ ) {
 
 		const textureNode = this.textureNode.bias( - 100 );
 		const uvNode = textureNode.uvNode || uv();
@@ -44,7 +86,7 @@ class FXAANode extends TempNode {
 
 		const Sample = Fn( ( [ uv ] ) => {
 
-			return textureNode.uv( uv );
+			return textureNode.sample( uv );
 
 		} );
 
@@ -313,4 +355,11 @@ class FXAANode extends TempNode {
 
 export default FXAANode;
 
+/**
+ * TSL function for creating a FXAA node for anti-aliasing via post processing.
+ *
+ * @function
+ * @param {Node<vec4>} node - The node that represents the input of the effect.
+ * @returns {FXAANode}
+ */
 export const fxaa = ( node ) => nodeObject( new FXAANode( convertToTexture( node ) ) );

package/examples/jsm/tsl/display/FilmNode.js

@@ -1,6 +1,13 @@
 import { TempNode } from 'three/webgpu';
 import { rand, Fn, fract, time, uv, clamp, mix, vec4, nodeProxy } from 'three/tsl';
 
+/** @module FilmNode **/
+
+/**
+ * Post processing node for creating a film grain effect.
+ *
+ * @augments TempNode
+ */
 class FilmNode extends TempNode {
 
 	static get type() {
@@ -9,17 +16,47 @@ class FilmNode extends TempNode {
 
 	}
 
+	/**
+	 * Constructs a new film node.
+	 *
+	 * @param {Node} inputNode - The node that represents the input of the effect.
+	 * @param {Node<float>?} [intensityNode=null] - A node that represents the effect's intensity.
+	 * @param {Node<vec2>?} [uvNode=null] - A node that allows to pass custom (e.g. animated) uv data.
+	 */
 	constructor( inputNode, intensityNode = null, uvNode = null ) {
 
 		super( 'vec4' );
 
+		/**
+		 * The node that represents the input of the effect.
+		 *
+		 * @type {Node}
+		 */
 		this.inputNode = inputNode;
+
+		/**
+		 * A node that represents the effect's intensity.
+		 *
+		 * @type {Node<float>}
+		 */
 		this.intensityNode = intensityNode;
+
+		/**
+		 * A node that allows to pass custom (e.g. animated) uv data.
+		 *
+		 * @type {Node<vec2>}
+		 */
 		this.uvNode = uvNode;
 
 	}
 
-	setup() {
+	/**
+	 * This method is used to setup the effect's TSL code.
+	 *
+	 * @param {NodeBuilder} builder - The current node builder.
+	 * @return {ShaderCallNodeInternal}
+	 */
+	setup( /* builder */ ) {
 
 		const uvNode = this.uvNode || uv();
 
@@ -50,4 +87,13 @@ class FilmNode extends TempNode {
 
 export default FilmNode;
 
+/**
+ * TSL function for creating a film node for post processing.
+ *
+ * @function
+ * @param {Node<vec4>} inputNode - The node that represents the input of the effect.
+ * @param {Node<float>?} [intensityNode=null] - A node that represents the effect's intensity.
+ * @param {Node<vec2>?} [uvNode=null] - A node that allows to pass custom (e.g. animated) uv data.
+ * @returns {FilmNode}
+ */
 export const film = /*@__PURE__*/ nodeProxy( FilmNode );