super-three 0.171.0 → 0.172.0

package/src/nodes/utils/MaxMipLevelNode.js

@@ -2,6 +2,18 @@ import UniformNode from '../core/UniformNode.js';
 import { NodeUpdateType } from '../core/constants.js';
 import { nodeProxy } from '../tsl/TSLBase.js';
 
+/** @module MatcapUVNode **/
+
+/**
+ * A special type of uniform node that computes the
+ * maximum mipmap level for a given texture node.
+ *
+ * ```js
+ * const level = maxMipLevel( textureNode );
+ * ```
+ *
+ * @augments module:UniformNode~UniformNode
+ */
 class MaxMipLevelNode extends UniformNode {
 
 	static get type() {
@@ -10,22 +22,52 @@ class MaxMipLevelNode extends UniformNode {
 
 	}
 
+	/**
+	 * Constructs a new max mip level node.
+	 *
+	 * @param {TextureNode} textureNode - The texture node to compute the max mip level for.
+	 */
 	constructor( textureNode ) {
 
 		super( 0 );
 
+		/**
+		 * The texture node to compute the max mip level for.
+		 *
+		 * @private
+		 * @type {TextureNode}
+		 */
 		this._textureNode = textureNode;
 
+		/**
+		 * The `updateType` is set to `NodeUpdateType.FRAME` since the node updates
+		 * the texture once per frame in its {@link MaxMipLevelNode#update} method.
+		 *
+		 * @type {String}
+		 * @default 'frame'
+		 */
 		this.updateType = NodeUpdateType.FRAME;
 
 	}
 
+	/**
+	 * The texture node to compute the max mip level for.
+	 *
+	 * @readonly
+	 * @type {TextureNode}
+	 */
 	get textureNode() {
 
 		return this._textureNode;
 
 	}
 
+	/**
+	 * The texture.
+	 *
+	 * @readonly
+	 * @type {Texture}
+	 */
 	get texture() {
 
 		return this._textureNode.value;
@@ -52,4 +94,11 @@ class MaxMipLevelNode extends UniformNode {
 
 export default MaxMipLevelNode;
 
+/**
+ * TSL function for creating a max mip level node.
+ *
+ * @function
+ * @param {TextureNode} textureNode - The texture node to compute the max mip level for.
+ * @returns {MaxMipLevelNode}
+ */
 export const maxMipLevel = /*@__PURE__*/ nodeProxy( MaxMipLevelNode );

package/src/nodes/utils/Oscillators.js

@@ -1,6 +1,39 @@
 import { time } from './Timer.js';
 
+/** @module Oscillators **/
+
+/**
+ * Generates a sine wave oscillation based on a timer.
+ *
+ * @method
+ * @param {Node<float>} t - The timer to generate the oscillation with.
+ * @return {Node<float>} The oscillation node.
+ */
 export const oscSine = ( t = time ) => t.add( 0.75 ).mul( Math.PI * 2 ).sin().mul( 0.5 ).add( 0.5 );
+
+/**
+ * Generates a square wave oscillation based on a timer.
+ *
+ * @method
+ * @param {Node<float>} t - The timer to generate the oscillation with.
+ * @return {Node<float>} The oscillation node.
+ */
 export const oscSquare = ( t = time ) => t.fract().round();
+
+/**
+ * Generates a triangle wave oscillation based on a timer.
+ *
+ * @method
+ * @param {Node<float>} t - The timer to generate the oscillation with.
+ * @return {Node<float>} The oscillation node.
+ */
 export const oscTriangle = ( t = time ) => t.add( 0.5 ).fract().mul( 2 ).sub( 1 ).abs();
+
+/**
+ * Generates a sawtooth wave oscillation based on a timer.
+ *
+ * @method
+ * @param {Node<float>} t - The timer to generate the oscillation with.
+ * @return {Node<float>} The oscillation node.
+ */
 export const oscSawtooth = ( t = time ) => t.fract();

package/src/nodes/utils/Packing.js

@@ -1,4 +1,21 @@
 import { nodeObject } from '../tsl/TSLBase.js';
 
+/** @module Packing **/
+
+/**
+ * Packs a direction vector into a color value.
+ *
+ * @method
+ * @param {Node<vec3>} node - The direction to pack.
+ * @return {Node<vec3>} The color.
+ */
 export const directionToColor = ( node ) => nodeObject( node ).mul( 0.5 ).add( 0.5 );
+
+/**
+ * Unpacks a color value into a direction vector.
+ *
+ * @method
+ * @param {Node<vec3>} node - The color to unpack.
+ * @return {Node<vec3>} The direction.
+ */
 export const colorToDirection = ( node ) => nodeObject( node ).mul( 2.0 ).sub( 1 );

package/src/nodes/utils/PostProcessingUtils.js

@@ -3,15 +3,18 @@ import { textureSize } from '../accessors/TextureSizeNode.js';
 import { textureLoad } from '../accessors/TextureNode.js';
 import { WebGPUCoordinateSystem } from '../../constants.js';
 
+/** @module PostProcessingUtils **/
+
 /**
-* Computes a position in view space based on a fragment's screen position expressed as uv coordinates, the fragments
-* depth value and the camera's inverse projection matrix.
-*
-* @param {vec2} screenPosition - The fragment's screen position expressed as uv coordinates.
-* @param {float} depth - The fragment's depth value.
-* @param {mat4} projectionMatrixInverse - The camera's inverse projection matrix.
-* @return {vec3} The fragments position in view space.
-*/
+ * Computes a position in view space based on a fragment's screen position expressed as uv coordinates, the fragments
+ * depth value and the camera's inverse projection matrix.
+ *
+ * @method
+ * @param {Node<vec2>} screenPosition - The fragment's screen position expressed as uv coordinates.
+ * @param {Node<float>} depth - The fragment's depth value.
+ * @param {Node<mat4>} projectionMatrixInverse - The camera's inverse projection matrix.
+ * @return {Node<vec3>} The fragments position in view space.
+ */
 export const getViewPosition = /*@__PURE__*/ Fn( ( [ screenPosition, depth, projectionMatrixInverse ], builder ) => {
 
 	let clipSpacePosition;
@@ -34,13 +37,14 @@ export const getViewPosition = /*@__PURE__*/ Fn( ( [ screenPosition, depth, proj
 } );
 
 /**
-* Computes a screen position expressed as uv coordinates based on a fragment's position in view space
-* and the camera's projection matrix
-*
-* @param {vec3} viewPosition - The fragments position in view space.
-* @param {mat4} projectionMatrix - The camera's projection matrix.
-* @return {vec2} The fragment's screen position expressed as uv coordinates.
-*/
+ * Computes a screen position expressed as uv coordinates based on a fragment's position in view space
+ * and the camera's projection matrix
+ *
+ * @method
+ * @param {Node<vec3>} viewPosition - The fragments position in view space.
+ * @param {Node<mat4>} projectionMatrix - The camera's projection matrix.
+ * @return {Node<vec2>} The fragment's screen position expressed as uv coordinates.
+ */
 export const getScreenPosition = /*@__PURE__*/ Fn( ( [ viewPosition, projectionMatrix ] ) => {
 
 	const sampleClipPos = projectionMatrix.mul( vec4( viewPosition, 1.0 ) );
@@ -50,14 +54,15 @@ export const getScreenPosition = /*@__PURE__*/ Fn( ( [ viewPosition, projectionM
 } );
 
 /**
-* Computes a normal vector based on depth data. Can be used as a fallback when no normal render
-* target is available or if flat surface normals are required.
-*
-* @param {vec2} uv - The texture coordinate.
-* @param {DepthTexture} depthTexture - The depth texture.
-* @param {mat4} projectionMatrixInverse - The camera's inverse projection matrix.
-* @return {vec3} The computed normal vector.
-*/
+ * Computes a normal vector based on depth data. Can be used as a fallback when no normal render
+ * target is available or if flat surface normals are required.
+ *
+ * @method
+ * @param {Node<vec2>} uv - The texture coordinate.
+ * @param {DepthTexture} depthTexture - The depth texture.
+ * @param {Node<mat4>} projectionMatrixInverse - The camera's inverse projection matrix.
+ * @return {Node<vec3>} The computed normal vector.
+ */
 export const getNormalFromDepth = /*@__PURE__*/ Fn( ( [ uv, depthTexture, projectionMatrixInverse ] ) => {
 
 	const size = textureSize( textureLoad( depthTexture ) );

package/src/nodes/utils/RTTNode.js

@@ -9,8 +9,18 @@ import { RenderTarget } from '../../core/RenderTarget.js';
 import { Vector2 } from '../../math/Vector2.js';
 import { HalfFloatType } from '../../constants.js';
 
+/** @module RTTNode **/
+
 const _size = /*@__PURE__*/ new Vector2();
 
+/**
+ * `RTTNode` takes another node and uses it with a `QuadMesh` to render into a texture (RTT).
+ * This module is especially relevant in context of post processing where certain nodes require
+ * texture input for their effects. With the helper function `convertToTexture()` which is based
+ * on this module, the node system can automatically ensure texture input if required.
+ *
+ * @augments module:TextureNode~TextureNode
+ */
 class RTTNode extends TextureNode {
 
 	static get type() {
@@ -19,30 +29,110 @@ class RTTNode extends TextureNode {
 
 	}
 
+	/**
+	 * Constructs a new RTT node.
+	 *
+	 * @param {Node} node - The node to render a texture with.
+	 * @param {Number?} [width=null] - The width of the internal render target. If not width is applied, the render target is automatically resized.
+	 * @param {Number?} [height=null] - The height of the internal render target.
+	 * @param {Object} [options={type:HalfFloatType}] - The options for the internal render target.
+	 */
 	constructor( node, width = null, height = null, options = { type: HalfFloatType } ) {
 
 		const renderTarget = new RenderTarget( width, height, options );
 
 		super( renderTarget.texture, uv() );
 
+		/**
+		 * The node to render a texture with.
+		 *
+		 * @type {Node}
+		 */
 		this.node = node;
+
+		/**
+		 * The width of the internal render target.
+		 * If not width is applied, the render target is automatically resized.
+		 *
+		 * @type {Number?}
+		 * @default null
+		 */
 		this.width = width;
+
+		/**
+		 * The height of the internal render target.
+		 *
+		 * @type {Number?}
+		 * @default null
+		 */
 		this.height = height;
 
+		/**
+		 * The pixel ratio
+		 *
+		 * @type {Number}
+		 * @default 1
+		 */
+		this.pixelRatio = 1;
+
+		/**
+		 * The render target
+		 *
+		 * @type {RenderTarget}
+		 */
 		this.renderTarget = renderTarget;
 
+		/**
+		 * Whether the texture requires an update or not.
+		 *
+		 * @type {Boolean}
+		 * @default true
+		 */
 		this.textureNeedsUpdate = true;
-		this.autoUpdate = true;
 
-		this.updateMap = new WeakMap();
+		/**
+		 * Whether the texture should automatically be updated or not.
+		 *
+		 * @type {Boolean}
+		 * @default true
+		 */
+		this.autoUpdate = true;
 
+		/**
+		 * The node which is used with the quad mesh for RTT.
+		 *
+		 * @private
+		 * @type {Node}
+		 * @default null
+		 */
 		this._rttNode = null;
+
+		/**
+		 * The internal quad mesh for RTT.
+		 *
+		 * @private
+		 * @type {QuadMesh}
+		 */
 		this._quadMesh = new QuadMesh( new NodeMaterial() );
 
+		/**
+		 * The `updateBeforeType` is set to `NodeUpdateType.RENDER` since the node updates
+		 * the texture once per render in its {@link RTTNode#updateBefore} method.
+		 *
+		 * @type {String}
+		 * @default 'render'
+		 */
 		this.updateBeforeType = NodeUpdateType.RENDER;
 
 	}
 
+	/**
+	 * Whether the internal render target should automatically be resized or not.
+	 *
+	 * @type {Boolean}
+	 * @readonly
+	 * @default true
+	 */
 	get autoSize() {
 
 		return this.width === null;
@@ -59,6 +149,12 @@ class RTTNode extends TextureNode {
 
 	}
 
+	/**
+	 * Sets the size of the internal render target
+	 *
+	 * @param {Number} width - The width to set.
+	 * @param {Number} height - The width to set.
+	 */
 	setSize( width, height ) {
 
 		this.width = width;
@@ -73,6 +169,11 @@ class RTTNode extends TextureNode {
 
 	}
 
+	/**
+	 * Sets the pixel ratio. This will also resize the render target.
+	 *
+	 * @param {Number} pixelRatio - The pixel ratio to set.
+	 */
 	setPixelRatio( pixelRatio ) {
 
 		this.pixelRatio = pixelRatio;
@@ -129,8 +230,28 @@ class RTTNode extends TextureNode {
 
 export default RTTNode;
 
+/**
+ * TSL function for creating a RTT node.
+ *
+ * @function
+ * @param {Node} node - The node to render a texture with.
+ * @param {Number?} [width=null] - The width of the internal render target. If not width is applied, the render target is automatically resized.
+ * @param {Number?} [height=null] - The height of the internal render target.
+ * @param {Object} [options={type:HalfFloatType}] - The options for the internal render target.
+ * @returns {RTTNode}
+ */
 export const rtt = ( node, ...params ) => nodeObject( new RTTNode( nodeObject( node ), ...params ) );
 
+/**
+ * TSL function for converting nodes to textures nodes.
+ *
+ * @function
+ * @param {Node} node - The node to render a texture with.
+ * @param {Number?} [width=null] - The width of the internal render target. If not width is applied, the render target is automatically resized.
+ * @param {Number?} [height=null] - The height of the internal render target.
+ * @param {Object} [options={type:HalfFloatType}] - The options for the internal render target.
+ * @returns {RTTNode}
+ */
 export const convertToTexture = ( node, ...params ) => {
 
 	if ( node.isTextureNode ) return node;

package/src/nodes/utils/ReflectorNode.js

@@ -14,6 +14,8 @@ import { Matrix4 } from '../../math/Matrix4.js';
 import { RenderTarget } from '../../core/RenderTarget.js';
 import { DepthTexture } from '../../textures/DepthTexture.js';
 
+/** @module ReflectorNode **/
+
 const _reflectorPlane = new Plane();
 const _normal = new Vector3();
 const _reflectorWorldPosition = new Vector3();
@@ -35,6 +37,19 @@ _defaultRT.depthTexture = new DepthTexture( 1, 1 );
 
 let _inReflector = false;
 
+/**
+ * This node can be used to implement mirror-like flat reflective surfaces.
+ *
+ * ```js
+ * const groundReflector = reflector();
+ * material.colorNode = groundReflector;
+ *
+ * const plane = new Mesh( geometry, material );
+ * plane.add( groundReflector.target );
+ * ```
+ *
+ * @augments module:TextureNode~TextureNode
+ */
 class ReflectorNode extends TextureNode {
 
 	static get type() {
@@ -43,29 +58,72 @@ class ReflectorNode extends TextureNode {
 
 	}
 
+	/**
+	 * Constructs a new reflector node.
+	 *
+	 * @param {Object} [parameters={}] - An object holding configuration parameters.
+	 * @param {Object3D} [parameters.target=new Object3D()] - The 3D object the reflector is linked to.
+	 * @param {Number} [parameters.resolution=1] - The resolution scale.
+	 * @param {Boolean} [parameters.generateMipmaps=false] - Whether mipmaps should be generated or not.
+	 * @param {Boolean} [parameters.bounces=true] - Whether reflectors can render other reflector nodes or not.
+	 * @param {Boolean} [parameters.depth=false] - Whether depth data should be generated or not.
+	 * @param {TextureNode} [parameters.defaultTexture] - The default texture node.
+	 * @param {ReflectorBaseNode} [parameters.reflector] - The reflector base node.
+	 */
 	constructor( parameters = {} ) {
 
 		super( parameters.defaultTexture || _defaultRT.texture, _defaultUV );
 
+		/**
+		 * A reference to the internal reflector base node which holds the actual implementation.
+		 *
+		 * @private
+		 * @type {ReflectorBaseNode?}
+		 * @default null
+		 */
 		this._reflectorBaseNode = parameters.reflector || new ReflectorBaseNode( this, parameters );
+
+		/**
+		 * A reference to the internal depth node.
+		 *
+		 * @private
+		 * @type {Node?}
+		 * @default null
+		 */
 		this._depthNode = null;
 
 		this.setUpdateMatrix( false );
 
 	}
 
+	/**
+	 * A reference to the internal reflector node.
+	 *
+	 * @type {ReflectorBaseNode}
+	 */
 	get reflector() {
 
 		return this._reflectorBaseNode;
 
 	}
 
+	/**
+	 * A reference to 3D object the reflector is linked to.
+	 *
+	 * @type {Object3D}
+	 */
 	get target() {
 
 		return this._reflectorBaseNode.target;
 
 	}
 
+	/**
+	 * Returns a node representing the mirror's depth. That can be used
+	 * to implement more advanced reflection effects like distance attenuation.
+	 *
+	 * @return {Node} The depth node.
+	 */
 	getDepthNode() {
 
 		if ( this._depthNode === null ) {
@@ -107,7 +165,15 @@ class ReflectorNode extends TextureNode {
 
 }
 
-
+/**
+ * Holds the actual implementation of the reflector.
+ *
+ * TODO: Explain why `ReflectorBaseNode`. Originally the entire logic was implemented
+ * in `ReflectorNode`, see #29619.
+ *
+ * @private
+ * @augments Node
+ */
 class ReflectorBaseNode extends Node {
 
 	static get type() {
@@ -116,6 +182,17 @@ class ReflectorBaseNode extends Node {
 
 	}
 
+	/**
+	 * Constructs a new reflector base node.
+	 *
+	 * @param {TextureNode} textureNode - Represents the rendered reflections as a texture node.
+	 * @param {Object} [parameters={}] - An object holding configuration parameters.
+	 * @param {Object3D} [parameters.target=new Object3D()] - The 3D object the reflector is linked to.
+	 * @param {Number} [parameters.resolution=1] - The resolution scale.
+	 * @param {Boolean} [parameters.generateMipmaps=false] - Whether mipmaps should be generated or not.
+	 * @param {Boolean} [parameters.bounces=true] - Whether reflectors can render other reflector nodes or not.
+	 * @param {Boolean} [parameters.depth=false] - Whether depth data should be generated or not.
+	 */
 	constructor( textureNode, parameters = {} ) {
 
 		super();
@@ -128,23 +205,85 @@ class ReflectorBaseNode extends Node {
 			depth = false
 		} = parameters;
 
-		//
-
+		/**
+		 * Represents the rendered reflections as a texture node.
+		 *
+		 * @type {TextureNode}
+		 */
 		this.textureNode = textureNode;
 
+		/**
+		 * The 3D object the reflector is linked to.
+		 *
+		 * @type {Object3D}
+		 * @default {new Object3D()}
+		 */
 		this.target = target;
+
+		/**
+		 * The resolution scale.
+		 *
+		 * @type {Number}
+		 * @default {1}
+		 */
 		this.resolution = resolution;
+
+		/**
+		 * Whether mipmaps should be generated or not.
+		 *
+		 * @type {Boolean}
+		 * @default {false}
+		 */
 		this.generateMipmaps = generateMipmaps;
+
+		/**
+		 * Whether reflectors can render other reflector nodes or not.
+		 *
+		 * @type {Boolean}
+		 * @default {true}
+		 */
 		this.bounces = bounces;
+
+		/**
+		 * Whether depth data should be generated or not.
+		 *
+		 * @type {Boolean}
+		 * @default {false}
+		 */
 		this.depth = depth;
 
+		/**
+		 * The `updateBeforeType` is set to `NodeUpdateType.RENDER` when {@link ReflectorBaseNode#bounces}
+		 * is `true`. Otherwise it's `NodeUpdateType.FRAME`.
+		 *
+		 * @type {String}
+		 * @default 'render'
+		 */
 		this.updateBeforeType = bounces ? NodeUpdateType.RENDER : NodeUpdateType.FRAME;
 
+		/**
+		 * Weak map for managing virtual cameras.
+		 *
+		 * @type {WeakMap<Camera, Camera>}
+		 */
 		this.virtualCameras = new WeakMap();
+
+		/**
+		 * Weak map for managing render targets.
+		 *
+		 * @type {WeakMap<Camera, RenderTarget>}
+		 */
 		this.renderTargets = new WeakMap();
 
 	}
 
+	/**
+	 * Updates the resolution of the internal render target.
+	 *
+	 * @private
+	 * @param {RenderTarget} renderTarget - The render target to resize.
+	 * @param {Renderer} renderer - The renderer that is used to determine the new size.
+	 */
 	_updateResolution( renderTarget, renderer ) {
 
 		const resolution = this.resolution;
@@ -163,6 +302,13 @@ class ReflectorBaseNode extends Node {
 
 	}
 
+	/**
+	 * Returns a virtual camera for the given camera. The virtual camera is used to
+	 * render the scene from the reflector's view so correct reflections can be produced.
+	 *
+	 * @param {Camera} camera - The scene's camera.
+	 * @return {Camera} The corresponding virtual camera.
+	 */
 	getVirtualCamera( camera ) {
 
 		let virtualCamera = this.virtualCameras.get( camera );
@@ -179,6 +325,13 @@ class ReflectorBaseNode extends Node {
 
 	}
 
+	/**
+	 * Returns a render target for the given camera. The reflections are rendered
+	 * into this render target.
+	 *
+	 * @param {Camera} camera - The scene's camera.
+	 * @return {RenderTarget} The render target.
+	 */
 	getRenderTarget( camera ) {
 
 		let renderTarget = this.renderTargets.get( camera );
@@ -210,7 +363,7 @@ class ReflectorBaseNode extends Node {
 
 	updateBefore( frame ) {
 
-		if ( this.bounces === false && _inReflector ) return;
+		if ( this.bounces === false && _inReflector ) return false;
 
 		_inReflector = true;
 
@@ -307,14 +460,17 @@ class ReflectorBaseNode extends Node {
 
 		const currentRenderTarget = renderer.getRenderTarget();
 		const currentMRT = renderer.getMRT();
+		const currentAutoClear = renderer.autoClear;
 
 		renderer.setMRT( null );
 		renderer.setRenderTarget( renderTarget );
+		renderer.autoClear = true;
 
 		renderer.render( scene, virtualCamera );
 
 		renderer.setMRT( currentMRT );
 		renderer.setRenderTarget( currentRenderTarget );
+		renderer.autoClear = currentAutoClear;
 
 		material.visible = true;
 
@@ -324,6 +480,20 @@ class ReflectorBaseNode extends Node {
 
 }
 
+/**
+ * TSL function for creating a reflector node.
+ *
+ * @function
+ * @param {Object} [parameters={}] - An object holding configuration parameters.
+ * @param {Object3D} [parameters.target=new Object3D()] - The 3D object the reflector is linked to.
+ * @param {Number} [parameters.resolution=1] - The resolution scale.
+ * @param {Boolean} [parameters.generateMipmaps=false] - Whether mipmaps should be generated or not.
+ * @param {Boolean} [parameters.bounces=true] - Whether reflectors can render other reflector nodes or not.
+ * @param {Boolean} [parameters.depth=false] - Whether depth data should be generated or not.
+ * @param {TextureNode} [parameters.defaultTexture] - The default texture node.
+ * @param {ReflectorBaseNode} [parameters.reflector] - The reflector base node.
+ * @returns {ReflectorNode}
+ */
 export const reflector = ( parameters ) => nodeObject( new ReflectorNode( parameters ) );
 
 export default ReflectorNode;