super-three 0.171.0 → 0.173.0

package/src/nodes/display/FrontFacingNode.js

@@ -3,6 +3,13 @@ import { nodeImmutable, float } from '../tsl/TSLBase.js';
 
 import { BackSide, WebGLCoordinateSystem } from '../../constants.js';
 
+/** @module FrontFacingNode **/
+
+/**
+ * This node can be used to evaluate whether a primitive is front or back facing.
+ *
+ * @augments Node
+ */
 class FrontFacingNode extends Node {
 
 	static get type() {
@@ -11,10 +18,20 @@ class FrontFacingNode extends Node {
 
 	}
 
+	/**
+	 * Constructs a new front facing node.
+	 */
 	constructor() {
 
 		super( 'bool' );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {Boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isFrontFacingNode = true;
 
 	}
@@ -41,5 +58,17 @@ class FrontFacingNode extends Node {
 
 export default FrontFacingNode;
 
+/**
+ * TSL object that represents whether a primitive is front or back facing
+ *
+ * @type {FrontFacingNode<bool>}
+ */
 export const frontFacing = /*@__PURE__*/ nodeImmutable( FrontFacingNode );
+
+/**
+ * TSL object that represents the front facing status as a number instead of a bool.
+ * `1` means front facing, `-1` means back facing.
+ *
+ * @type {Node<float>}
+ */
 export const faceDirection = /*@__PURE__*/ float( frontFacing ).mul( 2.0 ).sub( 1.0 );

package/src/nodes/display/NormalMapNode.js

@@ -10,6 +10,8 @@ import { Fn, nodeProxy, vec3 } from '../tsl/TSLBase.js';
 
 import { TangentSpaceNormalMap, ObjectSpaceNormalMap } from '../../constants.js';
 
+/** @module NormalMapNode **/
+
 // Normal Mapping Without Precomputed Tangents
 // http://www.thetenthplanet.de/archives/1180
 
@@ -37,6 +39,15 @@ const perturbNormal2Arb = /*@__PURE__*/ Fn( ( inputs ) => {
 
 } );
 
+/**
+ * This class can be used for applying normals maps to materials.
+ *
+ * ```js
+ * material.normalNode = normalMap( texture( normalTex ) );
+ * ```
+ *
+ * @augments TempNode
+ */
 class NormalMapNode extends TempNode {
 
 	static get type() {
@@ -45,13 +56,37 @@ class NormalMapNode extends TempNode {
 
 	}
 
+	/**
+	 * Constructs a new normal map node.
+	 *
+	 * @param {Node<vec3>} node - Represents the normal map data.
+	 * @param {Node<vec2>?} [scaleNode=null] - Controls the intensity of the effect.
+	 */
 	constructor( node, scaleNode = null ) {
 
 		super( 'vec3' );
 
+		/**
+		 * Represents the normal map data.
+		 *
+		 * @type {Node<vec3>}
+		 */
 		this.node = node;
+
+		/**
+		 * Controls the intensity of the effect.
+		 *
+		 * @type {Node<vec2>?}
+		 * @default null
+		 */
 		this.scaleNode = scaleNode;
 
+		/**
+		 * The normal map type.
+		 *
+		 * @type {(TangentSpaceNormalMap|ObjectSpaceNormalMap)}
+		 * @default TangentSpaceNormalMap
+		 */
 		this.normalMapType = TangentSpaceNormalMap;
 
 	}
@@ -103,4 +138,12 @@ class NormalMapNode extends TempNode {
 
 export default NormalMapNode;
 
+/**
+ * TSL function for creating a normal map node.
+ *
+ * @function
+ * @param {Node<vec3>} node - Represents the normal map data.
+ * @param {Node<vec2>?} [scaleNode=null] - Controls the intensity of the effect.
+ * @returns {NormalMapNode}
+ */
 export const normalMap = /*@__PURE__*/ nodeProxy( NormalMapNode );

package/src/nodes/display/PassNode.js

@@ -10,8 +10,15 @@ import { Vector2 } from '../../math/Vector2.js';
 import { DepthTexture } from '../../textures/DepthTexture.js';
 import { RenderTarget } from '../../core/RenderTarget.js';
 
+/** @module PassNode **/
+
 const _size = /*@__PURE__*/ new Vector2();
 
+/**
+ * Represents the texture of a pass node.
+ *
+ * @augments module:TextureNode~TextureNode
+ */
 class PassTextureNode extends TextureNode {
 
 	static get type() {
@@ -20,10 +27,21 @@ class PassTextureNode extends TextureNode {
 
 	}
 
+	/**
+	 * Constructs a new pass texture node.
+	 *
+	 * @param {PassNode} passNode - The pass node.
+	 * @param {Texture} texture - The output texture.
+	 */
 	constructor( passNode, texture ) {
 
 		super( texture );
 
+		/**
+		 * A reference to the pass node.
+		 *
+		 * @type {PassNode}
+		 */
 		this.passNode = passNode;
 
 		this.setUpdateMatrix( false );
@@ -46,6 +64,12 @@ class PassTextureNode extends TextureNode {
 
 }
 
+/**
+ * An extension of `PassTextureNode` which allows to manage more than one
+ * internal texture. Relevant for the `getPreviousTexture()` related API.
+ *
+ * @augments module:PassTextureNode~PassTextureNode
+ */
 class PassMultipleTextureNode extends PassTextureNode {
 
 	static get type() {
@@ -54,15 +78,40 @@ class PassMultipleTextureNode extends PassTextureNode {
 
 	}
 
+	/**
+	 * Constructs a new pass texture node.
+	 *
+	 * @param {PassNode} passNode - The pass node.
+	 * @param {String} textureName - The output texture name.
+	 * @param {Boolean} [previousTexture=false] - Whether previous frame data should be used or not.
+	 */
 	constructor( passNode, textureName, previousTexture = false ) {
 
+		// null is passed to the super call since this class does not
+		// use an external texture for rendering pass data into. Instead
+		// the texture is managed by the pass node itself
+
 		super( passNode, null );
 
+		/**
+		 * The output texture name.
+		 *
+		 * @type {String}
+		 */
 		this.textureName = textureName;
+
+		/**
+		 * Whether previous frame data should be used or not.
+		 *
+		 * @type {Boolean}
+		 */
 		this.previousTexture = previousTexture;
 
 	}
 
+	/**
+	 * Updates the texture reference of this node.
+	 */
 	updateTexture() {
 
 		this.value = this.previousTexture ? this.passNode.getPreviousTexture( this.textureName ) : this.passNode.getTexture( this.textureName );
@@ -85,6 +134,21 @@ class PassMultipleTextureNode extends PassTextureNode {
 
 }
 
+/**
+ * Represents a render pass (sometimes called beauty pass) in context of post processing.
+ * This pass produces a render for the given scene and camera and can provide multiple outputs
+ * via MRT for further processing.
+ *
+ * ```js
+ * const postProcessing = new PostProcessing( renderer );
+ *
+ * const scenePass = pass( scene, camera );
+ *
+ * postProcessing.outputNode = scenePass;
+ * ```
+ *
+ * @augments TempNode
+ */
 class PassNode extends TempNode {
 
 	static get type() {
@@ -93,17 +157,69 @@ class PassNode extends TempNode {
 
 	}
 
+	/**
+	 * Constructs a new pass node.
+	 *
+	 * @param {('color'|'depth')} scope - The scope of the pass. The scope determines whether the node outputs color or depth.
+	 * @param {Scene} scene - A reference to the scene.
+	 * @param {Camera} camera - A reference to the camera.
+	 * @param {Object} options - Options for the internal render target.
+	 */
 	constructor( scope, scene, camera, options = {} ) {
 
 		super( 'vec4' );
 
+		/**
+		 * The scope of the pass. The scope determines whether the node outputs color or depth.
+		 *
+		 * @type {('color'|'depth')}
+		 */
 		this.scope = scope;
+
+		/**
+		 * A reference to the scene.
+		 *
+		 * @type {Scene}
+		 */
 		this.scene = scene;
+
+		/**
+		 * A reference to the camera.
+		 *
+		 * @type {Camera}
+		 */
 		this.camera = camera;
+
+		/**
+		 * Options for the internal render target.
+		 *
+		 * @type {Object}
+		 */
 		this.options = options;
 
+		/**
+		 * The pass's pixel ratio. Will be kept automatically kept in sync with the renderer's pixel ratio.
+		 *
+		 * @private
+		 * @type {Number}
+		 * @default 1
+		 */
 		this._pixelRatio = 1;
+
+		/**
+		 * The pass's pixel width. Will be kept automatically kept in sync with the renderer's width.
+		 * @private
+		 * @type {Number}
+		 * @default 1
+		 */
 		this._width = 1;
+
+		/**
+		 * The pass's pixel height. Will be kept automatically kept in sync with the renderer's height.
+		 * @private
+		 * @type {Number}
+		 * @default 1
+		 */
 		this._height = 1;
 
 		const depthTexture = new DepthTexture();
@@ -115,31 +231,117 @@ class PassNode extends TempNode {
 		renderTarget.texture.name = 'output';
 		renderTarget.depthTexture = depthTexture;
 
+		/**
+		 * The pass's render target.
+		 *
+		 * @type {RenderTarget}
+		 */
 		this.renderTarget = renderTarget;
 
-		this.updateBeforeType = NodeUpdateType.FRAME;
-
+		/**
+		 * A dictionary holding the internal result textures.
+		 *
+		 * @private
+		 * @type {Object<String, Texture>}
+		 */
 		this._textures = {
 			output: renderTarget.texture,
 			depth: depthTexture
 		};
 
+		/**
+		 * A dictionary holding the internal texture nodes.
+		 *
+		 * @private
+		 * @type {Object<String, TextureNode>}
+		 */
 		this._textureNodes = {};
+
+		/**
+		 * A dictionary holding the internal depth nodes.
+		 *
+		 * @private
+		 * @type {Object}
+		 */
 		this._linearDepthNodes = {};
+
+		/**
+		 * A dictionary holding the internal viewZ nodes.
+		 *
+		 * @private
+		 * @type {Object}
+		 */
 		this._viewZNodes = {};
 
+		/**
+		 * A dictionary holding the texture data of the previous frame.
+		 * Used for computing velocity/motion vectors.
+		 *
+		 * @private
+		 * @type {Object<String, Texture>}
+		 */
 		this._previousTextures = {};
+
+		/**
+		 * A dictionary holding the texture nodes of the previous frame.
+		 * Used for computing velocity/motion vectors.
+		 *
+		 * @private
+		 * @type {Object<String, TextureNode>}
+		 */
 		this._previousTextureNodes = {};
 
+		/**
+		 * The `near` property of the camera as a uniform.
+		 *
+		 * @private
+		 * @type {UniformNode}
+		 */
 		this._cameraNear = uniform( 0 );
+
+		/**
+		 * The `far` property of the camera as a uniform.
+		 *
+		 * @private
+		 * @type {UniformNode}
+		 */
 		this._cameraFar = uniform( 0 );
 
+		/**
+		 * A MRT node configuring the MRT settings.
+		 *
+		 * @private
+		 * @type {MRTNode?}
+		 * @default null
+		 */
 		this._mrt = null;
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {Boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isPassNode = true;
 
+		/**
+		 * The `updateBeforeType` is set to `NodeUpdateType.FRAME` since the node renders the
+		 * scene once per frame in its {@link PassNode#updateBefore} method.
+		 *
+		 * @type {String}
+		 * @default 'frame'
+		 */
+		this.updateBeforeType = NodeUpdateType.FRAME;
+
 	}
 
+	/**
+	 * Sets the given MRT node to setup MRT for this pass.
+	 *
+	 * @param {MRTNode} mrt - The MRT object.
+	 * @return {PassNode} A reference to this pass.
+	 */
 	setMRT( mrt ) {
 
 		this._mrt = mrt;
@@ -148,18 +350,34 @@ class PassNode extends TempNode {
 
 	}
 
+	/**
+	 * Returns the current MRT node.
+	 *
+	 * @return {MRTNode} The current MRT node.
+	 */
 	getMRT() {
 
 		return this._mrt;
 
 	}
 
+	/**
+	 * The method is overwritten so it always returns `true`.
+	 *
+	 * @return {Boolean} Whether this node is global or not.
+	 */
 	isGlobal() {
 
 		return true;
 
 	}
 
+	/**
+	 * Returns the texture for the given output name.
+	 *
+	 * @param {String} name - The output name to get the texture for.
+	 * @return {Texture} The texture.
+	 */
 	getTexture( name ) {
 
 		let texture = this._textures[ name ];
@@ -169,7 +387,6 @@ class PassNode extends TempNode {
 			const refTexture = this.renderTarget.texture;
 
 			texture = refTexture.clone();
-			texture.isRenderTargetTexture = true;
 			texture.name = name;
 
 			this._textures[ name ] = texture;
@@ -182,6 +399,12 @@ class PassNode extends TempNode {
 
 	}
 
+	/**
+	 * Returns the texture holding the data of the previous frame for the given output name.
+	 *
+	 * @param {String} name - The output name to get the texture for.
+	 * @return {Texture} The texture holding the data of the previous frame.
+	 */
 	getPreviousTexture( name ) {
 
 		let texture = this._previousTextures[ name ];
@@ -189,7 +412,6 @@ class PassNode extends TempNode {
 		if ( texture === undefined ) {
 
 			texture = this.getTexture( name ).clone();
-			texture.isRenderTargetTexture = true;
 
 			this._previousTextures[ name ] = texture;
 
@@ -199,6 +421,11 @@ class PassNode extends TempNode {
 
 	}
 
+	/**
+	 * Switches current and previous textures for the given output name.
+	 *
+	 * @param {String} name - The output name.
+	 */
 	toggleTexture( name ) {
 
 		const prevTexture = this._previousTextures[ name ];
@@ -220,6 +447,12 @@ class PassNode extends TempNode {
 
 	}
 
+	/**
+	 * Returns the texture node for the given output name.
+	 *
+	 * @param {String} [name='output'] - The output name to get the texture node for.
+	 * @return {TextureNode} The texture node.
+	 */
 	getTextureNode( name = 'output' ) {
 
 		let textureNode = this._textureNodes[ name ];
@@ -236,6 +469,12 @@ class PassNode extends TempNode {
 
 	}
 
+	/**
+	 * Returns the previous texture node for the given output name.
+	 *
+	 * @param {String} [name='output'] - The output name to get the previous texture node for.
+	 * @return {TextureNode} The previous texture node.
+	 */
 	getPreviousTextureNode( name = 'output' ) {
 
 		let textureNode = this._previousTextureNodes[ name ];
@@ -254,6 +493,12 @@ class PassNode extends TempNode {
 
 	}
 
+	/**
+	 * Returns a viewZ node of this pass.
+	 *
+	 * @param {String} [name='depth'] - The output name to get the viewZ node for. In most cases the default `'depth'` can be used however the parameter exists for custom depth outputs.
+	 * @return {Node} The viewZ node.
+	 */
 	getViewZNode( name = 'depth' ) {
 
 		let viewZNode = this._viewZNodes[ name ];
@@ -271,6 +516,12 @@ class PassNode extends TempNode {
 
 	}
 
+	/**
+	 * Returns a linear depth node of this pass.
+	 *
+	 * @param {String} [name='depth'] - The output name to get the linear depth node for. In most cases the default `'depth'` can be used however the parameter exists for custom depth outputs.
+	 * @return {Node} The linear depth node.
+	 */
 	getLinearDepthNode( name = 'depth' ) {
 
 		let linearDepthNode = this._linearDepthNodes[ name ];
@@ -295,14 +546,14 @@ class PassNode extends TempNode {
 
 		this.renderTarget.samples = this.options.samples === undefined ? renderer.samples : this.options.samples;
 
-		// Disable MSAA for WebGL backend for now
+		// TODO: Disable MSAA for WebGL backend for now
 		if ( renderer.backend.isWebGLBackend === true ) {
 
 			this.renderTarget.samples = 0;
 
 		}
 
-		this.renderTarget.depthTexture.isMultisampleRenderTargetTexture = this.renderTarget.samples > 1;
+		this.renderTarget.texture.type = renderer.getColorBufferType();
 
 		return this.scope === PassNode.COLOR ? this.getTextureNode() : this.getLinearDepthNode();
 
@@ -341,6 +592,12 @@ class PassNode extends TempNode {
 
 	}
 
+	/**
+	 * Sets the size of the pass's render target. Honors the pixel ratio.
+	 *
+	 * @param {Number} width - The width to set.
+	 * @param {Number} height - The height to set.
+	 */
 	setSize( width, height ) {
 
 		this._width = width;
@@ -353,6 +610,11 @@ class PassNode extends TempNode {
 
 	}
 
+	/**
+	 * Sets the pixel ratio the pass's render target and updates the size.
+	 *
+	 * @param {Number} pixelRatio - The pixel ratio to set.
+	 */
 	setPixelRatio( pixelRatio ) {
 
 		this._pixelRatio = pixelRatio;
@@ -361,6 +623,9 @@ class PassNode extends TempNode {
 
 	}
 
+	/**
+	 * Frees internal resources. Should be called when the node is no longer in use.
+	 */
 	dispose() {
 
 		this.renderTarget.dispose();
@@ -375,6 +640,34 @@ PassNode.DEPTH = 'depth';
 
 export default PassNode;
 
+/**
+ * TSL function for creating a pass node.
+ *
+ * @function
+ * @param {Scene} scene - A reference to the scene.
+ * @param {Camera} camera - A reference to the camera.
+ * @param {Object} options - Options for the internal render target.
+ * @returns {PassNode}
+ */
 export const pass = ( scene, camera, options ) => nodeObject( new PassNode( PassNode.COLOR, scene, camera, options ) );
+
+/**
+ * TSL function for creating a pass texture node.
+ *
+ * @function
+ * @param {PassNode} pass - The pass node.
+ * @param {Texture} texture - The output texture.
+ * @returns {PassTextureNode}
+ */
 export const passTexture = ( pass, texture ) => nodeObject( new PassTextureNode( pass, texture ) );
-export const depthPass = ( scene, camera ) => nodeObject( new PassNode( PassNode.DEPTH, scene, camera ) );
+
+/**
+ * TSL function for creating a depth pass node.
+ *
+ * @function
+ * @param {Scene} scene - A reference to the scene.
+ * @param {Camera} camera - A reference to the camera.
+ * @param {Object} options - Options for the internal render target.
+ * @returns {PassNode}
+ */
+export const depthPass = ( scene, camera, options ) => nodeObject( new PassNode( PassNode.DEPTH, scene, camera, options ) );

package/src/nodes/display/PosterizeNode.js

@@ -1,6 +1,14 @@
 import TempNode from '../core/TempNode.js';
 import { nodeProxy } from '../tsl/TSLBase.js';
 
+/** @module PosterizeNode **/
+
+/**
+ * Represents a posterize effect which reduces the number of colors
+ * in an image, resulting in a more blocky and stylized appearance.
+ *
+ * @augments TempNode
+ */
 class PosterizeNode extends TempNode {
 
 	static get type() {
@@ -9,11 +17,28 @@ class PosterizeNode extends TempNode {
 
 	}
 
+	/**
+	 * Constructs a new posterize node.
+	 *
+	 * @param {Node} sourceNode - The input color.
+	 * @param {Node} stepsNode - Controls the intensity of the posterization effect. A lower number results in a more blocky appearance.
+	 */
 	constructor( sourceNode, stepsNode ) {
 
 		super();
 
+		/**
+		 * The input color.
+		 *
+		 * @type {Node}
+		 */
 		this.sourceNode = sourceNode;
+
+		/**
+		 * Controls the intensity of the posterization effect. A lower number results in a more blocky appearance.
+		 *
+		 * @type {Node}
+		 */
 		this.stepsNode = stepsNode;
 
 	}
@@ -30,4 +55,12 @@ class PosterizeNode extends TempNode {
 
 export default PosterizeNode;
 
+/**
+ * TSL function for creating a posterize node.
+ *
+ * @function
+ * @param {Node} sourceNode - The input color.
+ * @param {Node} stepsNode - Controls the intensity of the posterization effect. A lower number results in a more blocky appearance.
+ * @returns {PosterizeNode}
+ */
 export const posterize = /*@__PURE__*/ nodeProxy( PosterizeNode );