super-three 0.171.0 → 0.173.0

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

@@ -2,6 +2,18 @@ import { DataTexture, RepeatWrapping, Vector2, Vector3, TempNode } from 'three/w
 import { texture, getNormalFromDepth, getViewPosition, convertToTexture, nodeObject, Fn, float, NodeUpdateType, uv, uniform, Loop, luminance, vec2, vec3, vec4, uniformArray, int, dot, max, pow, abs, If, textureSize, sin, cos, mat2, PI } from 'three/tsl';
 import { SimplexNoise } from '../../math/SimplexNoise.js';
 
+/** @module DenoiseNode **/
+
+/**
+ * Post processing node for denoising data like raw screen-space ambient occlusion output.
+ * Denoise can noticeably improve the quality of ambient occlusion but also add quite some
+ * overhead to the post processing setup. It's best to make its usage optional (e.g. via
+ * graphic settings).
+ *
+ * Reference: {@link https://openaccess.thecvf.com/content/WACV2021/papers/Khademi_Self-Supervised_Poisson-Gaussian_Denoising_WACV_2021_paper.pdf}.
+ *
+ * @augments TempNode
+ */
 class DenoiseNode extends TempNode {
 
 	static get type() {
@@ -10,32 +22,123 @@ class DenoiseNode extends TempNode {
 
 	}
 
+	/**
+	 * Constructs a new denoise node.
+	 *
+	 * @param {TextureNode} textureNode - The texture node that represents the input of the effect (e.g. AO).
+	 * @param {Node<float>} depthNode - A node that represents the scene's depth.
+	 * @param {Node<vec3>?} normalNode - A node that represents the scene's normals.
+	 * @param {Camera} camera - The camera the scene is rendered with.
+	 */
 	constructor( textureNode, depthNode, normalNode, camera ) {
 
 		super( 'vec4' );
 
+		/**
+		 * The texture node that represents the input of the effect (e.g. AO).
+		 *
+		 * @type {TextureNode}
+		 */
 		this.textureNode = textureNode;
+
+		/**
+		 * A node that represents the scene's depth.
+		 *
+		 * @type {Node<float>}
+		 */
 		this.depthNode = depthNode;
+
+		/**
+		 * A node that represents the scene's normals. If no normals are passed to the
+		 * constructor (because MRT is not available), normals can be automatically
+		 * reconstructed from depth values in the shader.
+		 *
+		 * @type {Node<vec3>?}
+		 */
 		this.normalNode = normalNode;
 
+		/**
+		 * The node represents the internal noise texture.
+		 *
+		 * @type {TextureNode}
+		 */
 		this.noiseNode = texture( generateDefaultNoise() );
 
+		/**
+		 * The luma Phi value.
+		 *
+		 * @type {UniformNode<float>}
+		 */
 		this.lumaPhi = uniform( 5 );
+
+		/**
+		 * The depth Phi value.
+		 *
+		 * @type {UniformNode<float>}
+		 */
 		this.depthPhi = uniform( 5 );
+
+		/**
+		 * The normal Phi value.
+		 *
+		 * @type {UniformNode<float>}
+		 */
 		this.normalPhi = uniform( 5 );
+
+		/**
+		 * The radius.
+		 *
+		 * @type {UniformNode<float>}
+		 */
 		this.radius = uniform( 5 );
+
+		/**
+		 * The index.
+		 *
+		 * @type {UniformNode<float>}
+		 */
 		this.index = 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;
 
-		// uniforms
-
+		/**
+		 * The resolution of the effect.
+		 *
+		 * @private
+		 * @type {UniformNode<vec2>}
+		 */
 		this._resolution = uniform( new Vector2() );
-		this._sampleVectors = uniformArray( generatePdSamplePointInitializer( 16, 2, 1 ) );
+
+		/**
+		 * An array of sample vectors.
+		 *
+		 * @private
+		 * @type {UniformArrayNode<vec3>}
+		 */
+		this._sampleVectors = uniformArray( generateDenoiseSamples( 16, 2, 1 ) );
+
+		/**
+		 * Represents the inverse projection matrix of the scene's camera.
+		 *
+		 * @private
+		 * @type {UniformNode<mat4>}
+		 */
 		this._cameraProjectionMatrixInverse = uniform( camera.projectionMatrixInverse );
 
 	}
 
+	/**
+	 * This method is used to update internal uniforms once per frame.
+	 *
+	 * @param {NodeFrame} frame - The current node frame.
+	 */
 	updateBefore() {
 
 		const map = this.textureNode.value;
@@ -44,14 +147,20 @@ class DenoiseNode 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 uvNode = uv();
 
-		const sampleTexture = ( uv ) => this.textureNode.uv( uv );
-		const sampleDepth = ( uv ) => this.depthNode.uv( uv ).x;
-		const sampleNormal = ( uv ) => ( this.normalNode !== null ) ? this.normalNode.uv( uv ).rgb.normalize() : getNormalFromDepth( uv, this.depthNode.value, this._cameraProjectionMatrixInverse );
-		const sampleNoise = ( uv ) => this.noiseNode.uv( uv );
+		const sampleTexture = ( uv ) => this.textureNode.sample( uv );
+		const sampleDepth = ( uv ) => this.depthNode.sample( uv ).x;
+		const sampleNormal = ( uv ) => ( this.normalNode !== null ) ? this.normalNode.sample( uv ).rgb.normalize() : getNormalFromDepth( uv, this.depthNode.value, this._cameraProjectionMatrixInverse );
+		const sampleNoise = ( uv ) => this.noiseNode.sample( uv );
 
 		const denoiseSample = Fn( ( [ center, viewNormal, viewPosition, sampleUv ] ) => {
 
@@ -149,23 +258,14 @@ class DenoiseNode extends TempNode {
 
 export default DenoiseNode;
 
-function generatePdSamplePointInitializer( samples, rings, radiusExponent ) {
-
-	const poissonDisk = generateDenoiseSamples( samples, rings, radiusExponent );
-
-	const array = [];
-
-	for ( let i = 0; i < samples; i ++ ) {
-
-		const sample = poissonDisk[ i ];
-		array.push( sample );
-
-	}
-
-	return array;
-
-}
-
+/**
+ * Generates denoise samples based on the given parameters.
+ *
+ * @param {Number} numSamples - The number of samples.
+ * @param {Number} numRings - The number of rings.
+ * @param {Number} radiusExponent - The radius exponent.
+ * @return {Array<Vector3>} The denoise samples.
+ */
 function generateDenoiseSamples( numSamples, numRings, radiusExponent ) {
 
 	const samples = [];
@@ -182,6 +282,12 @@ function generateDenoiseSamples( numSamples, numRings, radiusExponent ) {
 
 }
 
+/**
+ * Generates a default noise texture for the given size.
+ *
+ * @param {Number} [size=64] - The texture size.
+ * @return {DataTexture} The generated noise texture.
+ */
 function generateDefaultNoise( size = 64 ) {
 
 	const simplex = new SimplexNoise();
@@ -214,4 +320,14 @@ function generateDefaultNoise( size = 64 ) {
 
 }
 
+/**
+ * TSL function for creating a denoise effect.
+ *
+ * @function
+ * @param {Node} node - The node that represents the input of the effect (e.g. AO).
+ * @param {Node<float>} depthNode - A node that represents the scene's depth.
+ * @param {Node<vec3>?} normalNode - A node that represents the scene's normals.
+ * @param {Camera} camera - The camera the scene is rendered with.
+ * @returns {DenoiseNode}
+ */
 export const denoise = ( node, depthNode, normalNode, camera ) => nodeObject( new DenoiseNode( convertToTexture( node ), nodeObject( depthNode ), nodeObject( normalNode ), camera ) );

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 );