super-three 0.170.1 → 0.172.0

package/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,14 +62,20 @@ 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();
 
 		const anaglyph = Fn( () => {
 
-			const colorL = this._mapLeft.uv( uvNode );
-			const colorR = this._mapRight.uv( uvNode );
+			const colorL = this._mapLeft.sample( uvNode );
+			const colorR = this._mapRight.sample( uvNode );
 
 			const color = clamp( this._colorMatrixLeft.mul( colorL.rgb ).add( this._colorMatrixRight.mul( colorR.rgb ) ) );
 
@@ -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 ) );

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

@@ -1,10 +1,17 @@
-import { RenderTarget, Vector2, TempNode, QuadMesh, NodeMaterial, PostProcessingUtils } from 'three/webgpu';
-import { nodeObject, Fn, float, NodeUpdateType, uv, passTexture, uniform, convertToTexture, vec2, vec3, Loop, threshold } from 'three/tsl';
+import { RenderTarget, Vector2, TempNode, QuadMesh, NodeMaterial, RendererUtils } from 'three/webgpu';
+import { nodeObject, Fn, float, NodeUpdateType, uv, passTexture, uniform, convertToTexture, vec2, vec3, Loop, mix, luminance } from 'three/tsl';
+
+/** @module AnamorphicNode **/
 
 const _quadMesh = /*@__PURE__*/ new QuadMesh();
 
 let _rendererState;
 
+/**
+ * Post processing node for adding an anamorphic flare effect.
+ *
+ * @augments TempNode
+ */
 class AnamorphicNode extends TempNode {
 
 	static get type() {
@@ -13,34 +20,113 @@ class AnamorphicNode extends TempNode {
 
 	}
 
+	/**
+	 * Constructs a new anamorphic node.
+	 *
+	 * @param {TextureNode} textureNode - The texture node that represents the input of the effect.
+	 * @param {Node<float>} tresholdNode - The threshold is one option to control the intensity and size of the effect.
+	 * @param {Node<float>} scaleNode - Defines the vertical scale of the flares.
+	 * @param {Number} samples - More samples result in larger flares and a more expensive runtime behavior.
+	 */
 	constructor( textureNode, tresholdNode, scaleNode, samples ) {
 
 		super( 'vec4' );
 
+		/**
+		 * The texture node that represents the input of the effect.
+		 *
+		 * @type {TextureNode}
+		 */
 		this.textureNode = textureNode;
+
+		/**
+		 * The threshold is one option to control the intensity and size of the effect.
+		 *
+		 * @type {Node<float>}
+		 */
 		this.tresholdNode = tresholdNode;
+
+		/**
+		 * Defines the vertical scale of the flares.
+		 *
+		 * @type {Node<float>}
+		 */
 		this.scaleNode = scaleNode;
+
+		/**
+		 * The color of the flares.
+		 *
+		 * @type {Node<vec3>}
+		 */
 		this.colorNode = vec3( 0.1, 0.0, 1.0 );
+
+		/**
+		 * More samples result in larger flares and a more expensive runtime behavior.
+		 *
+		 * @type {Node<float>}
+		 */
 		this.samples = samples;
+
+		/**
+		 * The resolution scale.
+		 *
+		 * @type {Vector2}
+		 */
 		this.resolution = new Vector2( 1, 1 );
 
+		/**
+		 * The internal render target of the effect.
+		 *
+		 * @private
+		 * @type {RenderTarget}
+		 */
 		this._renderTarget = new RenderTarget( 1, 1, { depthBuffer: false } );
 		this._renderTarget.texture.name = 'anamorphic';
 
+		/**
+		 * A uniform node holding the inverse resolution value.
+		 *
+		 * @private
+		 * @type {UniformNode<vec2>}
+		 */
 		this._invSize = uniform( new Vector2() );
 
+		/**
+		 * The result of the effect is represented as a separate texture node.
+		 *
+		 * @private
+		 * @type {PassTextureNode}
+		 */
 		this._textureNode = passTexture( this, this._renderTarget.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._invSize.value.set( 1 / width, 1 / height );
@@ -52,11 +138,16 @@ class AnamorphicNode 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 );
 
 		//
 
@@ -81,16 +172,24 @@ class AnamorphicNode extends TempNode {
 
 		textureNode.value = currentTexture;
 
-		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 textureNode = this.textureNode;
 		const uvNode = textureNode.uvNode || uv();
 
-		const sampleTexture = ( uv ) => textureNode.uv( uv );
+		const sampleTexture = ( uv ) => textureNode.sample( uv );
+
+		const threshold = ( color, threshold ) => mix( vec3( 0.0 ), color, luminance( color ).sub( threshold ).max( 0 ) );
 
 		const anamorph = Fn( () => {
 
@@ -132,6 +231,10 @@ class AnamorphicNode extends TempNode {
 
 	}
 
+	/**
+	 * Frees internal resources. This method should be called
+	 * when the effect is no longer required.
+	 */
 	dispose() {
 
 		this._renderTarget.dispose();
@@ -140,6 +243,16 @@ class AnamorphicNode extends TempNode {
 
 }
 
+/**
+ * TSL function for creating an anamorphic flare effect.
+ *
+ * @function
+ * @param {TextureNode} node - The node that represents the input of the effect.
+ * @param {Node<float> | Number} [threshold=0.9] - The threshold is one option to control the intensity and size of the effect.
+ * @param {Node<float> | Number} [scale=3] - Defines the vertical scale of the flares.
+ * @param {Number} [samples=32] - More samples result in larger flares and a more expensive runtime behavior.
+ * @returns {AnamorphicNode}
+ */
 export const anamorphic = ( node, threshold = .9, scale = 3, samples = 32 ) => nodeObject( new AnamorphicNode( convertToTexture( node ), nodeObject( threshold ), nodeObject( scale ), samples ) );
 
 export default AnamorphicNode;

package/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;