super-three 0.171.0 → 0.172.0

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

@@ -1,20 +1,23 @@
-import { AdditiveBlending, Color, Vector2, PostProcessingUtils, PassNode, QuadMesh, NodeMaterial } from 'three/webgpu';
+import { AdditiveBlending, Color, Vector2, RendererUtils, PassNode, QuadMesh, NodeMaterial } from 'three/webgpu';
 import { nodeObject, uniform, mrt, texture, getTextureIndex } from 'three/tsl';
 
+/** @module SSAAPassNode **/
+
 const _size = /*@__PURE__*/ new Vector2();
 
 let _rendererState;
 
 /**
-*
-* Supersample Anti-Aliasing Render Pass
-*
-* This manual approach to SSAA re-renders the scene ones for each sample with camera jitter and accumulates the results.
-*
-* References: https://en.wikipedia.org/wiki/Supersampling
-*
-*/
-
+ * A special render pass node that renders the scene with SSAA (Supersampling Anti-Aliasing).
+ * This manual SSAA approach re-renders the scene ones for each sample with camera jitter and accumulates the results.
+ *
+ * This node produces a high-quality anti-aliased output but is also extremely expensive because of
+ * its brute-force approach of re-rendering the entire scene multiple times.
+ *
+ * Reference: {@link https://en.wikipedia.org/wiki/Supersampling}
+ *
+ * @augments PassNode
+ */
 class SSAAPassNode extends PassNode {
 
 	static get type() {
@@ -23,31 +26,95 @@ class SSAAPassNode extends PassNode {
 
 	}
 
+	/**
+	 * Constructs a new SSAA pass node.
+	 *
+	 * @param {Scene} scene - The scene to render.
+	 * @param {Camera} camera - The camera to render the scene with.
+	 */
 	constructor( scene, camera ) {
 
 		super( PassNode.COLOR, scene, camera );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {Boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isSSAAPassNode = true;
 
-		this.sampleLevel = 4; // specified as n, where the number of samples is 2^n, so sampleLevel = 4, is 2^4 samples, 16.
+		/**
+		 * The sample level specified  as n, where the number of samples is 2^n,
+		 * so sampleLevel = 4, is 2^4 samples, 16.
+		 *
+		 * @type {Number}
+		 * @default 4
+		 */
+		this.sampleLevel = 4;
+
+		/**
+		 * Whether rounding errors should be mitigated or not.
+		 *
+		 * @type {Boolean}
+		 * @default true
+		 */
 		this.unbiased = true;
+
+		/**
+		 * The clear color of the pass.
+		 *
+		 * @type {Color}
+		 * @default 0x000000
+		 */
 		this.clearColor = new Color( 0x000000 );
+
+		/**
+		 * The clear alpha of the pass.
+		 *
+		 * @type {Number}
+		 * @default 0
+		 */
 		this.clearAlpha = 0;
 
+		/**
+		 * A uniform node representing the sample weight.
+		 *
+		 * @type {UniformNode<float>}
+		 * @default 1
+		 */
 		this.sampleWeight = uniform( 1 );
 
-		this.sampleRenderTarget = null;
-
+		/**
+		 * Reference to the internal render target that holds the current sample.
+		 *
+		 * @private
+		 * @type {RenderTarget?}
+		 */
+		this._sampleRenderTarget = null;
+
+		/**
+		 * Reference to the internal quad mesh.
+		 *
+		 * @private
+		 * @type {QuadMesh}
+		 */
 		this._quadMesh = new QuadMesh();
 
 	}
 
+	/**
+	 * This method is used to render the SSAA effect once per frame.
+	 *
+	 * @param {NodeFrame} frame - The current node frame.
+	 */
 	updateBefore( frame ) {
 
 		const { renderer } = frame;
 		const { scene, camera } = this;
 
-		_rendererState = PostProcessingUtils.resetRendererAndSceneState( renderer, scene, _rendererState );
+		_rendererState = RendererUtils.resetRendererAndSceneState( renderer, scene, _rendererState );
 
 		//
 
@@ -56,7 +123,7 @@ class SSAAPassNode extends PassNode {
 		const size = renderer.getSize( _size );
 
 		this.setSize( size.width, size.height );
-		this.sampleRenderTarget.setSize( this.renderTarget.width, this.renderTarget.height );
+		this._sampleRenderTarget.setSize( this.renderTarget.width, this.renderTarget.height );
 
 		//
 
@@ -120,7 +187,7 @@ class SSAAPassNode extends PassNode {
 			}
 
 			renderer.setClearColor( this.clearColor, this.clearAlpha );
-			renderer.setRenderTarget( this.sampleRenderTarget );
+			renderer.setRenderTarget( this._sampleRenderTarget );
 			renderer.clear();
 			renderer.render( scene, camera );
 
@@ -139,7 +206,7 @@ class SSAAPassNode extends PassNode {
 
 		}
 
-		renderer.copyTextureToTexture( this.sampleRenderTarget.depthTexture, this.renderTarget.depthTexture );
+		renderer.copyTextureToTexture( this._sampleRenderTarget.depthTexture, this.renderTarget.depthTexture );
 
 		// restore
 
@@ -163,15 +230,21 @@ class SSAAPassNode extends PassNode {
 
 		//
 
-		PostProcessingUtils.restoreRendererAndSceneState( renderer, scene, _rendererState );
+		RendererUtils.restoreRendererAndSceneState( renderer, scene, _rendererState );
 
 	}
 
+	/**
+	 * This method is used to setup the effect's MRT configuration and quad mesh.
+	 *
+	 * @param {NodeBuilder} builder - The current node builder.
+	 * @return {PassTextureNode}
+	 */
 	setup( builder ) {
 
-		if ( this.sampleRenderTarget === null ) {
+		if ( this._sampleRenderTarget === null ) {
 
-			this.sampleRenderTarget = this.renderTarget.clone();
+			this._sampleRenderTarget = this.renderTarget.clone();
 
 		}
 
@@ -185,11 +258,11 @@ class SSAAPassNode extends PassNode {
 
 			for ( const name in passMRT.outputNodes ) {
 
-				const index = getTextureIndex( this.sampleRenderTarget.textures, name );
+				const index = getTextureIndex( this._sampleRenderTarget.textures, name );
 
 				if ( index >= 0 ) {
 
-					outputs[ name ] = texture( this.sampleRenderTarget.textures[ index ] ).mul( this.sampleWeight );
+					outputs[ name ] = texture( this._sampleRenderTarget.textures[ index ] ).mul( this.sampleWeight );
 
 				}
 
@@ -199,7 +272,7 @@ class SSAAPassNode extends PassNode {
 
 		} else {
 
-			sampleTexture = texture( this.sampleRenderTarget.texture ).mul( this.sampleWeight );
+			sampleTexture = texture( this._sampleRenderTarget.texture ).mul( this.sampleWeight );
 
 		}
 
@@ -216,13 +289,17 @@ class SSAAPassNode extends PassNode {
 
 	}
 
+	/**
+	 * Frees internal resources. This method should be called
+	 * when the pass is no longer required.
+	 */
 	dispose() {
 
 		super.dispose();
 
-		if ( this.sampleRenderTarget !== null ) {
+		if ( this._sampleRenderTarget !== null ) {
 
-			this.sampleRenderTarget.dispose();
+			this._sampleRenderTarget.dispose();
 
 		}
 
@@ -269,4 +346,12 @@ const _JitterVectors = [
 	]
 ];
 
+/**
+ * TSL function for creating a SSAA pass node for Supersampling Anti-Aliasing.
+ *
+ * @function
+ * @param {Scene} scene - The scene to render.
+ * @param {Camera} camera - The camera to render the scene with.
+ * @returns {SSAAPassNode}
+ */
 export const ssaaPass = ( scene, camera ) => nodeObject( new SSAAPassNode( scene, camera ) );

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

@@ -1,13 +1,18 @@
-import { NearestFilter, RenderTarget, Vector2, PostProcessingUtils, QuadMesh, TempNode, NodeMaterial, NodeUpdateType } from 'three/webgpu';
+import { NearestFilter, RenderTarget, Vector2, RendererUtils, QuadMesh, TempNode, NodeMaterial, NodeUpdateType } from 'three/webgpu';
 import { reference, viewZToPerspectiveDepth, logarithmicDepthToViewZ, getScreenPosition, getViewPosition, sqrt, mul, div, cross, float, Continue, Break, Loop, int, max, abs, sub, If, dot, reflect, normalize, screenCoordinate, nodeObject, Fn, passTexture, uv, uniform, perspectiveDepthToViewZ, orthographicDepthToViewZ, vec2, vec3, vec4 } from 'three/tsl';
 
+/** @module SSRNode **/
+
 const _quadMesh = /*@__PURE__*/ new QuadMesh();
 const _size = /*@__PURE__*/ new Vector2();
 let _rendererState;
 
 /**
- * References:
- * https://lettier.github.io/3d-game-shaders-for-beginners/screen-space-reflection.html
+ * Post processing node for computing screen space reflections (SSR).
+ *
+ * Reference: {@link https://lettier.github.io/3d-game-shaders-for-beginners/screen-space-reflection.html}
+ *
+ * @augments TempNode
  */
 class SSRNode extends TempNode {
 
@@ -17,56 +22,198 @@ class SSRNode extends TempNode {
 
 	}
 
+	/**
+	 * Constructs a new SSR node.
+	 *
+	 * @param {Node<vec4>} colorNode - The node that represents the beauty pass.
+	 * @param {Node<float>} depthNode - A node that represents the beauty pass's depth.
+	 * @param {Node<vec3>} normalNode - A node that represents the beauty pass's normals.
+	 * @param {Node<float>} metalnessNode - A node that represents the beauty pass's metalness.
+	 * @param {Camera} camera - The camera the scene is rendered with.
+	 */
 	constructor( colorNode, depthNode, normalNode, metalnessNode, camera ) {
 
 		super( 'vec4' );
 
+		/**
+		 * The node that represents the beauty pass.
+		 *
+		 * @type {Node<vec4>}
+		 */
 		this.colorNode = colorNode;
+
+		/**
+		 * A node that represents the beauty pass's depth.
+		 *
+		 * @type {Node<float>}
+		 */
 		this.depthNode = depthNode;
+
+		/**
+		 * A node that represents the beauty pass's normals.
+		 *
+		 * @type {Node<vec3>}
+		 */
 		this.normalNode = normalNode;
+
+		/**
+		 * A node that represents the beauty pass's metalness.
+		 *
+		 * @type {Node<float>}
+		 */
 		this.metalnessNode = metalnessNode;
+
+		/**
+		 * The camera the scene is rendered with.
+		 *
+		 * @type {Camera}
+		 */
 		this.camera = camera;
 
+		/**
+		 * The resolution scale. By default SSR reflections
+		 * are computed in half resolutions. Setting the value
+		 * to `1` improves quality but also results in more
+		 * computational overhead.
+		 *
+		 * @type {Number}
+		 * @default 0.5
+		 */
 		this.resolutionScale = 0.5;
 
+		/**
+		 * 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;
 
-		// render targets
-
+		/**
+		 * The render target the SSR is rendered into.
+		 *
+		 * @private
+		 * @type {RenderTarget}
+		 */
 		this._ssrRenderTarget = new RenderTarget( 1, 1, { depthBuffer: false, minFilter: NearestFilter, magFilter: NearestFilter } );
 		this._ssrRenderTarget.texture.name = 'SSRNode.SSR';
 
-		// uniforms
-
-		this.maxDistance = uniform( 1 ); // controls how far a fragment can reflect
-		this.thickness = uniform( 0.1 ); // controls the cutoff between what counts as a possible reflection hit and what does not
-		this.opacity = uniform( 1 ); // controls the transparency of the reflected colors
-
+		/**
+		 * Controls how far a fragment can reflect
+		 *
+		 *
+		 * @type {UniformNode<float>}
+		 */
+		this.maxDistance = uniform( 1 );
+
+		/**
+		 * Controls the cutoff between what counts as a possible reflection hit and what does not.
+		 *
+		 * @type {UniformNode<float>}
+		 */
+		this.thickness = uniform( 0.1 );
+
+		/**
+		 * Controls the transparency of the reflected colors.
+		 *
+		 * @type {UniformNode<float>}
+		 */
+		this.opacity = uniform( 1 );
+
+		/**
+		 * Represents the projection matrix of the scene's camera.
+		 *
+		 * @private
+		 * @type {UniformNode<mat4>}
+		 */
 		this._cameraProjectionMatrix = uniform( camera.projectionMatrix );
+
+		/**
+		 * Represents the inverse projection matrix of the scene's camera.
+		 *
+		 * @private
+		 * @type {UniformNode<mat4>}
+		 */
 		this._cameraProjectionMatrixInverse = uniform( camera.projectionMatrixInverse );
+
+		/**
+		 * Represents the near value of the scene's camera.
+		 *
+		 * @private
+		 * @type {ReferenceNode<float>}
+		 */
 		this._cameraNear = reference( 'near', 'float', camera );
+
+		/**
+		 * Represents the far value of the scene's camera.
+		 *
+		 * @private
+		 * @type {ReferenceNode<float>}
+		 */
 		this._cameraFar = reference( 'far', 'float', camera );
+
+		/**
+		 * Whether the scene's camera is perspective or orthographic.
+		 *
+		 * @private
+		 * @type {UniformNode<bool>}
+		 */
 		this._isPerspectiveCamera = uniform( camera.isPerspectiveCamera ? 1 : 0 );
+
+		/**
+		 * The resolution of the pass.
+		 *
+		 * @private
+		 * @type {UniformNode<vec2>}
+		 */
 		this._resolution = uniform( new Vector2() );
-		this._maxStep = uniform( 0 );
 
-		// materials
+		/**
+		 * This value is derived from the resolution and restricts
+		 * the maximum raymarching steps in the fragment shader.
+		 *
+		 * @private
+		 * @type {UniformNode<float>}
+		 */
+		this._maxStep = uniform( 0 );
 
+		/**
+		 * The material that is used to render the effect.
+		 *
+		 * @private
+		 * @type {NodeMaterial}
+		 */
 		this._material = new NodeMaterial();
 		this._material.name = 'SSRNode.SSR';
 
-		//
-
+		/**
+		 * The result of the effect is represented as a separate texture node.
+		 *
+		 * @private
+		 * @type {PassTextureNode}
+		 */
 		this._textureNode = passTexture( this, this._ssrRenderTarget.texture );
 
 	}
 
+	/**
+	 * 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 ) {
 
 		width = Math.round( this.resolutionScale * width );
@@ -79,11 +226,16 @@ class SSRNode extends TempNode {
 
 	}
 
+	/**
+	 * This method is used to render the effect once per frame.
+	 *
+	 * @param {NodeFrame} frame - The current node frame.
+	 */
 	updateBefore( frame ) {
 
 		const { renderer } = frame;
 
-		_rendererState = PostProcessingUtils.resetRendererState( renderer, _rendererState );
+		_rendererState = RendererUtils.resetRendererState( renderer, _rendererState );
 
 		const size = renderer.getDrawingBufferSize( _size );
 
@@ -103,10 +255,16 @@ class SSRNode extends TempNode {
 
 		// restore
 
-		PostProcessingUtils.restoreRendererState( renderer, _rendererState );
+		RendererUtils.restoreRendererState( renderer, _rendererState );
 
 	}
 
+	/**
+	 * 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();
@@ -153,7 +311,7 @@ class SSRNode extends TempNode {
 
 		const sampleDepth = ( uv ) => {
 
-			const depth = this.depthNode.uv( uv ).r;
+			const depth = this.depthNode.sample( uv ).r;
 
 			if ( builder.renderer.logarithmicDepthBuffer === true ) {
 
@@ -169,7 +327,7 @@ class SSRNode extends TempNode {
 
 		const ssr = Fn( () => {
 
-			const metalness = this.metalnessNode.uv( uvNode ).r;
+			const metalness = this.metalnessNode.sample( uvNode ).r;
 
 			// fragments with no metalness do not reflect their environment
 			metalness.equal( 0.0 ).discard();
@@ -295,7 +453,7 @@ class SSRNode extends TempNode {
 
 					If( away.lessThanEqual( tk ), () => { // hit
 
-						const vN = this.normalNode.uv( uvNode ).rgb.normalize().toVar();
+						const vN = this.normalNode.sample( uvNode ).rgb.normalize().toVar();
 
 						If( dot( viewReflectDir, vN ).greaterThanEqual( 0 ), () => {
 
@@ -328,7 +486,7 @@ class SSRNode extends TempNode {
 						op.mulAssign( fresnelCoe );
 
 						// output
-						const reflectColor = this.colorNode.uv( uvNode );
+						const reflectColor = this.colorNode.sample( uvNode );
 						output.assign( vec4( reflectColor.rgb, op ) );
 						Break();
 
@@ -351,6 +509,10 @@ class SSRNode extends TempNode {
 
 	}
 
+	/**
+	 * Frees internal resources. This method should be called
+	 * when the effect is no longer required.
+	 */
 	dispose() {
 
 		this._ssrRenderTarget.dispose();
@@ -363,4 +525,15 @@ class SSRNode extends TempNode {
 
 export default SSRNode;
 
+/**
+ * TSL function for creating screen space reflections (SSR).
+ *
+ * @function
+ * @param {Node<vec4>} colorNode - The node that represents the beauty pass.
+ * @param {Node<float>} depthNode - A node that represents the beauty pass's depth.
+ * @param {Node<vec3>} normalNode - A node that represents the beauty pass's normals.
+ * @param {Node<float>} metalnessNode - A node that represents the beauty pass's metalness.
+ * @param {Camera} camera - The camera the scene is rendered with.
+ * @returns {SSRNode}
+ */
 export const ssr = ( colorNode, depthNode, normalNode, metalnessNode, camera ) => nodeObject( new SSRNode( nodeObject( colorNode ), nodeObject( depthNode ), nodeObject( normalNode ), nodeObject( metalnessNode ), camera ) );

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

@@ -1,5 +1,14 @@
 import { dot, Fn, vec3, vec4 } from 'three/tsl';
 
+/** @module Sepia **/
+
+/**
+ * Applies a sepia effect to the given color node.
+ *
+ * @function
+ * @param {Node<vec4>} color - The color node to apply the sepia for.
+ * @return {Node<vec4>} The updated color node.
+ */
 export const sepia = /*@__PURE__*/ Fn( ( [ color ] ) => {
 
 	const c = vec3( color );

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

@@ -1,6 +1,15 @@
 import { Vector2, TempNode, NodeUpdateType } from 'three/webgpu';
 import { nodeObject, Fn, uv, uniform, convertToTexture, vec2, vec3, vec4, mat3, luminance, add } from 'three/tsl';
 
+/** @module SobelOperatorNode **/
+
+/**
+ * Post processing node for detecting edges with a sobel filter.
+ * A sobel filter should be applied after tone mapping and output color
+ * space conversion.
+ *
+ * @augments TempNode
+ */
 class SobelOperatorNode extends TempNode {
 
 	static get type() {
@@ -9,19 +18,47 @@ class SobelOperatorNode extends TempNode {
 
 	}
 
+	/**
+	 * Constructs a new sobel operator 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,13 +66,19 @@ class SobelOperatorNode 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;
 
 		const uvNode = textureNode.uvNode || uv();
 
-		const sampleTexture = ( uv ) => textureNode.uv( uv );
+		const sampleTexture = ( uv ) => textureNode.sample( uv );
 
 		const sobel = Fn( () => {
 
@@ -97,7 +140,7 @@ class SobelOperatorNode extends TempNode {
 				Gy[ 2 ][ 2 ].mul( tx2y2 )
 			);
 
-			// magnitute of the total gradient
+			// magnitude of the total gradient
 
 			const G = valueGx.mul( valueGx ).add( valueGy.mul( valueGy ) ).sqrt();
 
@@ -115,4 +158,11 @@ class SobelOperatorNode extends TempNode {
 
 export default SobelOperatorNode;
 
+/**
+ * TSL function for creating a sobel operator node which performs edge detection with a sobel filter.
+ *
+ * @function
+ * @param {Node<vec4>} node - The node that represents the input of the effect.
+ * @returns {SobelOperatorNode}
+ */
 export const sobel = ( node ) => nodeObject( new SobelOperatorNode( convertToTexture( node ) ) );