super-three 0.171.0 → 0.172.0

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

@@ -1,4 +1,4 @@
-import { RenderTarget, StereoCamera, HalfFloatType, LinearFilter, NearestFilter, Vector2, PassNode, QuadMesh, PostProcessingUtils } from 'three/webgpu';
+import { RenderTarget, StereoCamera, HalfFloatType, LinearFilter, NearestFilter, Vector2, PassNode, QuadMesh, RendererUtils } from 'three/webgpu';
 import { texture } from 'three/tsl';
 
 const _size = /*@__PURE__*/ new Vector2();
@@ -6,6 +6,16 @@ const _quadMesh = /*@__PURE__*/ new QuadMesh();
 
 let _rendererState;
 
+/**
+ * A special (abstract) render pass node that renders the scene
+ * as a stereoscopic image. Unlike {@link StereoPassNode}, this
+ * node merges the image for the left and right eye
+ * into a single one. That is required for effects like
+ * anaglyph or parallax barrier.
+ *
+ * @abstract
+ * @augments PassNode
+ */
 class StereoCompositePassNode extends PassNode {
 
 	static get type() {
@@ -14,25 +24,76 @@ class StereoCompositePassNode extends PassNode {
 
 	}
 
+	/**
+	 * Constructs a new stereo composite 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.isStereoCompositePassNode = true;
 
+		/**
+		 * The internal stereo camera that is used to render the scene.
+		 *
+		 * @type {StereoCamera}
+		 */
 		this.stereo = new StereoCamera();
 		const _params = { minFilter: LinearFilter, magFilter: NearestFilter, type: HalfFloatType };
 
+		/**
+		 * The render target for rendering the left eye's view.
+		 *
+		 * @type {RenderTarget}
+		 */
 		this._renderTargetL = new RenderTarget( 1, 1, _params );
+
+		/**
+		 * The render target for rendering the right eye's view.
+		 *
+		 * @type {RenderTarget}
+		 */
 		this._renderTargetR = new RenderTarget( 1, 1, _params );
 
+		/**
+		 * A texture node representing the left's eye view.
+		 *
+		 * @type {TextureNode}
+		 */
 		this._mapLeft = texture( this._renderTargetL.texture );
+
+		/**
+		 * A texture node representing the right's eye view.
+		 *
+		 * @type {TextureNode}
+		 */
 		this._mapRight = texture( this._renderTargetR.texture );
 
+		/**
+		 * The node material that implements the composite. All
+		 * derived effect passes must provide an instance for rendering.
+		 *
+		 * @type {NodeMaterial}
+		 */
 		this._material = null;
 
 	}
 
+	/**
+	 * Updates the internal stereo camera.
+	 *
+	 * @param {Number} coordinateSystem - The current coordinate system.
+	 */
 	updateStereoCamera( coordinateSystem ) {
 
 		this.stereo.cameraL.coordinateSystem = coordinateSystem;
@@ -41,6 +102,12 @@ class StereoCompositePassNode extends PassNode {
 
 	}
 
+	/**
+	 * Sets the size of the pass.
+	 *
+	 * @param {Number} width - The width of the pass.
+	 * @param {Number} height - The height of the pass.
+	 */
 	setSize( width, height ) {
 
 		super.setSize( width, height );
@@ -50,12 +117,17 @@ class StereoCompositePassNode extends PassNode {
 
 	}
 
+	/**
+	 * This method is used to render the effect once per frame.
+	 *
+	 * @param {NodeFrame} frame - The current node frame.
+	 */
 	updateBefore( frame ) {
 
 		const { renderer } = frame;
 		const { scene, stereo, renderTarget } = this;
 
-		_rendererState = PostProcessingUtils.resetRendererState( renderer, _rendererState );
+		_rendererState = RendererUtils.resetRendererState( renderer, _rendererState );
 
 		//
 
@@ -84,10 +156,14 @@ class StereoCompositePassNode extends PassNode {
 
 		// restore
 
-		PostProcessingUtils.restoreRendererState( renderer, _rendererState );
+		RendererUtils.restoreRendererState( renderer, _rendererState );
 
 	}
 
+	/**
+	 * Frees internal resources. This method should be called
+	 * when the pass is no longer required.
+	 */
 	dispose() {
 
 		super.dispose();

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

@@ -1,10 +1,17 @@
-import { StereoCamera, Vector2, PassNode, PostProcessingUtils } from 'three/webgpu';
+import { StereoCamera, Vector2, PassNode, RendererUtils } from 'three/webgpu';
 import { nodeObject } from 'three/tsl';
 
+/** @module StereoPassNode **/
+
 const _size = /*@__PURE__*/ new Vector2();
 
 let _rendererState;
 
+/**
+ * A special render pass node that renders the scene as a stereoscopic image.
+ *
+ * @augments PassNode
+ */
 class StereoPassNode extends PassNode {
 
 	static get type() {
@@ -13,23 +20,46 @@ class StereoPassNode extends PassNode {
 
 	}
 
+	/**
+	 * Constructs a new stereo 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.isStereoPassNode = true;
 
+		/**
+		 * The internal stereo camera that is used to render the scene.
+		 *
+		 * @type {StereoCamera}
+		 */
 		this.stereo = new StereoCamera();
 		this.stereo.aspect = 0.5;
 
 	}
 
+	/**
+	 * This method is used to render the stereo effect once per frame.
+	 *
+	 * @param {NodeFrame} frame - The current node frame.
+	 */
 	updateBefore( frame ) {
 
 		const { renderer } = frame;
 		const { scene, camera, stereo, renderTarget } = this;
 
-		_rendererState = PostProcessingUtils.resetRendererState( renderer, _rendererState );
+		_rendererState = RendererUtils.resetRendererState( renderer, _rendererState );
 
 		//
 
@@ -71,7 +101,7 @@ class StereoPassNode extends PassNode {
 
 		// restore
 
-		PostProcessingUtils.restoreRendererState( renderer, _rendererState );
+		RendererUtils.restoreRendererState( renderer, _rendererState );
 
 	}
 
@@ -79,4 +109,12 @@ class StereoPassNode extends PassNode {
 
 export default StereoPassNode;
 
+/**
+ * TSL function for creating a stereo pass node for stereoscopic rendering.
+ *
+ * @function
+ * @param {Scene} scene - The scene to render.
+ * @param {Camera} camera - The camera to render the scene with.
+ * @returns {StereoPassNode}
+ */
 export const stereoPass = ( scene, camera ) => nodeObject( new StereoPassNode( scene, camera ) );

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

@@ -1,19 +1,25 @@
-import { Color, Vector2, NearestFilter, Matrix4, PostProcessingUtils, PassNode, QuadMesh, NodeMaterial } from 'three/webgpu';
+import { Color, Vector2, NearestFilter, Matrix4, RendererUtils, PassNode, QuadMesh, NodeMaterial } from 'three/webgpu';
 import { add, float, If, Loop, int, Fn, min, max, clamp, nodeObject, texture, uniform, uv, vec2, vec4, luminance } from 'three/tsl';
 
+/** @module TRAAPassNode **/
+
 const _quadMesh = /*@__PURE__*/ new QuadMesh();
 const _size = /*@__PURE__*/ new Vector2();
 
 let _rendererState;
 
+
 /**
-* Temporal Reprojection Anti-Aliasing (TRAA).
-*
-* References:
-* https://alextardif.com/TAA.html
-* https://www.elopezr.com/temporal-aa-and-the-quest-for-the-holy-trail/
-*
-*/
+ * A special render pass node that renders the scene with TRAA (Temporal Reprojection Anti-Aliasing).
+ *
+ * Note: The current implementation does not yet support MRT setups.
+ *
+ * References:
+ * - {@link https://alextardif.com/TAA.html}
+ * - {@link https://www.elopezr.com/temporal-aa-and-the-quest-for-the-holy-trail/}
+ *
+ * @augments PassNode
+ */
 class TRAAPassNode extends PassNode {
 
 	static get type() {
@@ -22,34 +28,100 @@ class TRAAPassNode extends PassNode {
 
 	}
 
+	/**
+	 * Constructs a new TRAA 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.isTRAAPassNode = 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;
 
+		/**
+		 * The jitter index selects the current camera offset value.
+		 *
+		 * @private
+		 * @type {Number}
+		 * @default 0
+		 */
 		this._jitterIndex = 0;
-		this._originalProjectionMatrix = new Matrix4();
 
-		// uniforms
+		/**
+		 * Used to save the original/unjittered projection matrix.
+		 *
+		 * @private
+		 * @type {Matrix4}
+		 */
+		this._originalProjectionMatrix = new Matrix4();
 
+		/**
+		 * A uniform node holding the inverse resolution value.
+		 *
+		 * @private
+		 * @type {UniformNode<vec2>}
+		 */
 		this._invSize = uniform( new Vector2() );
 
-		// render targets
-
+		/**
+		 * The render target that holds the current sample.
+		 *
+		 * @private
+		 * @type {RenderTarget?}
+		 */
 		this._sampleRenderTarget = null;
-		this._historyRenderTarget = null;
 
-		// materials
+		/**
+		 * The render target that represents the history of frame data.
+		 *
+		 * @private
+		 * @type {RenderTarget?}
+		 */
+		this._historyRenderTarget = null;
 
+		/**
+		 * Material used for the resolve step.
+		 *
+		 * @private
+		 * @type {NodeMaterial}
+		 */
 		this._resolveMaterial = new NodeMaterial();
 		this._resolveMaterial.name = 'TRAA.Resolve';
 
 	}
 
+	/**
+	 * Sets the size of the effect.
+	 *
+	 * @param {Number} width - The width of the effect.
+	 * @param {Number} height - The height of the effect.
+	 * @return {Boolean} Whether the TRAA needs a restart or not. That is required after a resize since buffer data with different sizes can't be resolved.
+	 */
 	setSize( width, height ) {
 
 		super.setSize( width, height );
@@ -71,12 +143,17 @@ class TRAAPassNode extends PassNode {
 
 	}
 
+	/**
+	 * This method is used to render the 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 );
 
 		//
 
@@ -214,10 +291,16 @@ class TRAAPassNode extends PassNode {
 
 		velocityOutput.setProjectionMatrix( null );
 
-		PostProcessingUtils.restoreRendererAndSceneState( renderer, scene, _rendererState );
+		RendererUtils.restoreRendererAndSceneState( renderer, scene, _rendererState );
 
 	}
 
+	/**
+	 * This method is used to setup the effect's render targets and TSL code.
+	 *
+	 * @param {NodeBuilder} builder - The current node builder.
+	 * @return {PassTextureNode}
+	 */
 	setup( builder ) {
 
 		if ( this._sampleRenderTarget === null ) {
@@ -260,12 +343,12 @@ class TRAAPassNode extends PassNode {
 				Loop( { start: int( - 1 ), end: int( 1 ), type: 'int', condition: '<=', name: 'y' }, ( { y } ) => {
 
 					const uvNeighbor = uvNode.add( vec2( float( x ), float( y ) ).mul( this._invSize ) ).toVar();
-					const colorNeighbor = max( vec4( 0 ), sampleTexture.uv( uvNeighbor ) ).toVar(); // use max() to avoid propagate garbage values
+					const colorNeighbor = max( vec4( 0 ), sampleTexture.sample( uvNeighbor ) ).toVar(); // use max() to avoid propagate garbage values
 
 					minColor.assign( min( minColor, colorNeighbor ) );
 					maxColor.assign( max( maxColor, colorNeighbor ) );
 
-					const currentDepth = depthTexture.uv( uvNeighbor ).r.toVar();
+					const currentDepth = depthTexture.sample( uvNeighbor ).r.toVar();
 
 					// find the sample position of the closest depth in the neighborhood (used for velocity)
 
@@ -282,10 +365,10 @@ class TRAAPassNode extends PassNode {
 
 			// sampling/reprojection
 
-			const offset = velocityTexture.uv( closestDepthPixelPosition ).xy.mul( vec2( 0.5, - 0.5 ) ); // NDC to uv offset
+			const offset = velocityTexture.sample( closestDepthPixelPosition ).xy.mul( vec2( 0.5, - 0.5 ) ); // NDC to uv offset
 
-			const currentColor = sampleTexture.uv( uvNode );
-			const historyColor = historyTexture.uv( uvNode.sub( offset ) );
+			const currentColor = sampleTexture.sample( uvNode );
+			const historyColor = historyTexture.sample( uvNode.sub( offset ) );
 
 			// clamping
 
@@ -317,6 +400,10 @@ class TRAAPassNode extends PassNode {
 
 	}
 
+	/**
+	 * Frees internal resources. This method should be called
+	 * when the effect is no longer required.
+	 */
 	dispose() {
 
 		super.dispose();
@@ -352,4 +439,12 @@ const _JitterVectors = [
 	[ 2, 5 ], [ 7, 5 ], [ 5, 6 ], [ 3, 7 ]
 ];
 
+/**
+ * TSL function for creating a TRAA pass node for Temporal Reprojection Anti-Aliasing.
+ *
+ * @function
+ * @param {Scene} scene - The scene to render.
+ * @param {Camera} camera - The camera to render the scene with.
+ * @returns {TRAAPassNode}
+ */
 export const traaPass = ( scene, camera ) => nodeObject( new TRAAPassNode( scene, camera ) );

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

@@ -1,6 +1,13 @@
 import { TempNode } from 'three/webgpu';
 import { nodeObject, Fn, float, uv, convertToTexture, vec4, If, int, clamp, sub, mix } from 'three/tsl';
 
+/** @module TransitionNode **/
+
+/**
+ * Post processing node for creating a transition effect between scenes.
+ *
+ * @augments TempNode
+ */
 class TransitionNode extends TempNode {
 
 	static get type() {
@@ -9,24 +16,70 @@ class TransitionNode extends TempNode {
 
 	}
 
+	/**
+	 * Constructs a new transition node.
+	 *
+	 * @param {TextureNode} textureNodeA - A texture node that represents the beauty pass of the first scene.
+	 * @param {TextureNode} textureNodeB - A texture node that represents the beauty pass of the second scene.
+	 * @param {TextureNode} mixTextureNode - A texture node that defines how the transition effect should look like.
+	 * @param {Node<float>} mixRatioNode - The interpolation factor that controls the mix.
+	 * @param {Node<float>} thresholdNode - Can be used to tweak the linear interpolation.
+	 * @param {Node<float>} useTextureNode - Whether `mixTextureNode` should influence the transition or not.
+	 */
 	constructor( textureNodeA, textureNodeB, mixTextureNode, mixRatioNode, thresholdNode, useTextureNode ) {
 
 		super( 'vec4' );
 
-		// Input textures
-
+		/**
+		 * A texture node that represents the beauty pass of the first scene.
+		 *
+		 * @type {TextureNode}
+		 */
 		this.textureNodeA = textureNodeA;
+
+		/**
+		 * A texture node that represents the beauty pass of the second scene.
+		 *
+		 * @type {TextureNode}
+		 */
 		this.textureNodeB = textureNodeB;
-		this.mixTextureNode = mixTextureNode;
 
-		// Uniforms
+		/**
+		 * A texture that defines how the transition effect should look like.
+		 *
+		 * @type {TextureNode}
+		 */
+		this.mixTextureNode = mixTextureNode;
 
+		/**
+		 * The interpolation factor that controls the mix.
+		 *
+		 * @type {Node<float>}
+		 */
 		this.mixRatioNode = mixRatioNode;
+
+		/**
+		 * Can be used to tweak the linear interpolation.
+		 *
+		 * @type {Node<float>}
+		 */
 		this.thresholdNode = thresholdNode;
+
+		/**
+		 * Whether `mixTextureNode` should influence the transition or not.
+		 *
+		 * @type {Node<float>}
+		 */
 		this.useTextureNode = useTextureNode;
 
 	}
 
+	/**
+	 * This method is used to setup the effect's TSL code.
+	 *
+	 * @param {NodeBuilder} builder - The current node builder.
+	 * @return {ShaderCallNodeInternal}
+	 */
 	setup() {
 
 		const { textureNodeA, textureNodeB, mixTextureNode, mixRatioNode, thresholdNode, useTextureNode } = this;
@@ -34,7 +87,7 @@ class TransitionNode extends TempNode {
 		const sampleTexture = ( textureNode ) => {
 
 			const uvNodeTexture = textureNode.uvNode || uv();
-			return textureNode.uv( uvNodeTexture );
+			return textureNode.sample( uvNodeTexture );
 
 		};
 
@@ -73,4 +126,16 @@ class TransitionNode extends TempNode {
 
 export default TransitionNode;
 
-export const transition = ( nodeA, nodeB, mixTexture, mixRatio = 0.0, threshold = 0.1, useTexture = 0 ) => nodeObject( new TransitionNode( convertToTexture( nodeA ), convertToTexture( nodeB ), convertToTexture( mixTexture ), nodeObject( mixRatio ), nodeObject( threshold ), nodeObject( useTexture ) ) );
+/**
+ * TSL function for creating a transition node for post processing.
+ *
+ * @function
+ * @param {Node<vec4>} nodeA - A texture node that represents the beauty pass of the first scene.
+ * @param {Node<vec4>} nodeB - A texture node that represents the beauty pass of the second scene.
+ * @param {Node<vec4>} mixTextureNode - A texture that defines how the transition effect should look like.
+ * @param {Node<float> | Number} mixRatio - The interpolation factor that controls the mix.
+ * @param {Node<float> | Number} threshold - Can be used to tweak the linear interpolation.
+ * @param {Node<float> | Number} useTexture - Whether `mixTextureNode` should influence the transition or not.
+ * @returns {TransitionNode}
+ */
+export const transition = ( nodeA, nodeB, mixTextureNode, mixRatio, threshold, useTexture ) => nodeObject( new TransitionNode( convertToTexture( nodeA ), convertToTexture( nodeB ), convertToTexture( mixTextureNode ), nodeObject( mixRatio ), nodeObject( threshold ), nodeObject( useTexture ) ) );

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

@@ -1,10 +1,21 @@
 import { float, Fn, vec2, uv, sin, rand, degrees, cos, Loop, vec4 } from 'three/tsl';
 
-// https://www.shadertoy.com/view/4lXXWn
-
+/** @module HashBlur **/
+
+/**
+ * Applies a hash blur effect to the given texture node.
+ *
+ * Reference: {@link https://www.shadertoy.com/view/4lXXWn}.
+ *
+ * @function
+ * @param {Node<vec4>} textureNode - The texture node that should be blurred.
+ * @param {Node<float>} [bluramount=float(0.1)] - This node determines the amount of blur.
+ * @param {Node<float>} [repeats=float(45)] - This node determines the quality of the blur. A higher value produces a less grainy result but is also more expensive.
+ * @return {Node<vec4>} The blurred texture node.
+ */
 export const hashBlur = /*#__PURE__*/ Fn( ( [ textureNode, bluramount = float( 0.1 ), repeats = float( 45 ) ] ) => {
 
-	const draw = ( uv ) => textureNode.uv( uv );
+	const draw = ( uv ) => textureNode.sample( uv );
 
 	const targetUV = textureNode.uvNode || uv();
 	const blurred_image = vec4( 0. ).toVar();