super-three 0.171.0 → 0.172.0

package/src/nodes/tsl/TSLBase.js

@@ -3,7 +3,7 @@
 
 export * from './TSLCore.js'; // float(), vec2(), vec3(), vec4(), mat3(), mat4(), Fn(), If(), element(), nodeObject(), nodeProxy(), ...
 export * from '../core/UniformNode.js'; // uniform()
-export * from '../core/PropertyNode.js'; // property()  <-> TODO: Seperate Material Properties in other file
+export * from '../core/PropertyNode.js'; // property()  <-> TODO: Separate Material Properties in other file
 export * from '../core/AssignNode.js'; // .assign()
 export * from '../code/FunctionCallNode.js'; // .call()
 export * from '../math/OperatorNode.js'; // .add(), .sub(), ...
@@ -11,7 +11,7 @@ export * from '../math/MathNode.js'; // abs(), floor(), ...
 export * from '../math/ConditionalNode.js'; // select(), ...
 export * from '../core/ContextNode.js'; // .context()
 export * from '../core/VarNode.js'; // .var() -> TODO: Maybe rename .toVar() -> .var()
-export * from '../core/VaryingNode.js'; // varying() -> TODO: Add vertexStage()
+export * from '../core/VaryingNode.js'; // varying(), vertexStage()
 export * from '../display/ColorSpaceNode.js'; // .toColorSpace()
 export * from '../display/ToneMappingNode.js'; // .toToneMapping()
 export * from '../accessors/BufferAttributeNode.js'; // .toAttribute()

package/src/nodes/utils/ArrayElementNode.js

@@ -1,24 +1,60 @@
 import Node from '../core/Node.js';
 
-class ArrayElementNode extends Node {
+/**
+ * Base class for representing element access on an array-like
+ * node data structures.
+ *
+ * @augments Node
+ */
+class ArrayElementNode extends Node { // @TODO: If extending from TempNode it breaks webgpu_compute
 
 	static get type() {
 
 		return 'ArrayElementNode';
 
-	} // @TODO: If extending from TempNode it breaks webgpu_compute
+	}
 
+	/**
+	 * Constructs an array element node.
+	 *
+	 * @param {Node} node - The array-like node.
+	 * @param {Node} indexNode - The index node that defines the element access.
+	 */
 	constructor( node, indexNode ) {
 
 		super();
 
+		/**
+		 * The array-like node.
+		 *
+		 * @type {Node}
+		 */
 		this.node = node;
+
+		/**
+		 * The index node that defines the element access.
+		 *
+		 * @type {Node}
+		 */
 		this.indexNode = indexNode;
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {Boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isArrayElementNode = true;
 
 	}
 
+	/**
+	 * This method is overwritten since the node type is inferred from the array-like node.
+	 *
+	 * @param {NodeBuilder} builder - The current node builder.
+	 * @return {String} The node type.
+	 */
 	getNodeType( builder ) {
 
 		return this.node.getElementType( builder );

package/src/nodes/utils/ConvertNode.js

@@ -1,5 +1,12 @@
 import Node from '../core/Node.js';
 
+/**
+ * This module is part of the TSL core and usually not used in app level code.
+ * It represents a convert operation during the shader generation process
+ * meaning it converts the data type of a node to a target data type.
+ *
+ * @augments Node
+ */
 class ConvertNode extends Node {
 
 	static get type() {
@@ -8,15 +15,39 @@ class ConvertNode extends Node {
 
 	}
 
+	/**
+	 * Constructs a new convert node.
+	 *
+	 * @param {Node} node - The node which type should be converted.
+	 * @param {String} convertTo - The target node type. Multiple types can be defined by separating them with a `|` sign.
+	 */
 	constructor( node, convertTo ) {
 
 		super();
 
+		/**
+		 * The node which type should be converted.
+		 *
+		 * @type {Node}
+		 */
 		this.node = node;
+
+		/**
+		 * The target node type. Multiple types can be defined by separating them with a `|` sign.
+		 *
+		 * @type {String}
+		 */
 		this.convertTo = convertTo;
 
 	}
 
+	/**
+	 * This method is overwritten since the implementation tries to infer the best
+	 * matching type from the {@link ConvertNode#convertTo} property.
+	 *
+	 * @param {NodeBuilder} builder - The current node builder.
+	 * @return {String} The node type.
+	 */
 	getNodeType( builder ) {
 
 		const requestType = this.node.getNodeType( builder );

package/src/nodes/utils/CubeMapNode.js

@@ -6,8 +6,16 @@ import { cubeTexture } from '../accessors/CubeTextureNode.js';
 import CubeRenderTarget from '../../renderers/common/CubeRenderTarget.js';
 import { CubeReflectionMapping, CubeRefractionMapping, EquirectangularReflectionMapping, EquirectangularRefractionMapping } from '../../constants.js';
 
+/** @module CubeMapNode **/
+
 const _cache = new WeakMap();
 
+/**
+ * This node can be used to automatically convert environment maps in the
+ * equirectangular format into the cube map format.
+ *
+ * @augments TempNode
+ */
 class CubeMapNode extends TempNode {
 
 	static get type() {
@@ -16,20 +24,59 @@ class CubeMapNode extends TempNode {
 
 	}
 
+	/**
+	 * Constructs a new cube map node.
+	 *
+	 * @param {Node} envNode - The node representing the environment map.
+	 */
 	constructor( envNode ) {
 
 		super( 'vec3' );
 
+		/**
+		 * The node representing the environment map.
+		 *
+		 * @type {Node}
+		 */
 		this.envNode = envNode;
 
+		/**
+		 * A reference to the internal cube texture.
+		 *
+		 * @private
+		 * @type {CubeTexture}
+		 * @default null
+		 */
 		this._cubeTexture = null;
+
+		/**
+		 * A reference to the internal cube texture node.
+		 *
+		 * @private
+		 * @type {CubeTextureNode}
+		 */
 		this._cubeTextureNode = cubeTexture();
 
 		const defaultTexture = new CubeTexture();
 		defaultTexture.isRenderTargetTexture = true;
 
+		/**
+		 * A default cube texture that acts as a placeholder.
+		 * It is used when the conversion from equirectangular to cube
+		 * map has not finished yet for a given texture.
+		 *
+		 * @private
+		 * @type {CubeTexture}
+		 */
 		this._defaultTexture = defaultTexture;
 
+		/**
+		 * The `updateBeforeType` is set to `NodeUpdateType.RENDER` since the node updates
+		 * the texture once per render in its {@link CubeMapNode#updateBefore} method.
+		 *
+		 * @type {String}
+		 * @default 'render'
+		 */
 		this.updateBeforeType = NodeUpdateType.RENDER;
 
 	}
@@ -117,6 +164,14 @@ class CubeMapNode extends TempNode {
 
 export default CubeMapNode;
 
+/**
+ * Returns true if the given equirectangular image has been fully loaded
+ * and is ready for further processing.
+ *
+ * @private
+ * @param {Image} image - The equirectangular image to check.
+ * @return {Boolean} Whether the image is ready or not.
+ */
 function isEquirectangularMapReady( image ) {
 
 	if ( image === null || image === undefined ) return false;
@@ -125,6 +180,14 @@ function isEquirectangularMapReady( image ) {
 
 }
 
+/**
+ * This function is executed when `dispose()` is called on the equirectangular
+ * texture. In this case, the generated cube map with its render target
+ * is deleted as well.
+ *
+ * @private
+ * @param {Object} event - The event object.
+ */
 function onTextureDispose( event ) {
 
 	const texture = event.target;
@@ -143,6 +206,14 @@ function onTextureDispose( event ) {
 
 }
 
+/**
+ * This function makes sure the generated cube map uses the correct
+ * texture mapping that corresponds to the equirectangular original.
+ *
+ * @private
+ * @param {Texture} texture - The cube texture.
+ * @param {Number} mapping - The original texture mapping.
+ */
 function mapTextureMapping( texture, mapping ) {
 
 	if ( mapping === EquirectangularReflectionMapping ) {
@@ -157,4 +228,11 @@ function mapTextureMapping( texture, mapping ) {
 
 }
 
+/**
+ * TSL function for creating a cube map node.
+ *
+ * @function
+ * @param {Node} envNode - The node representing the environment map.
+ * @returns {CubeMapNode}
+ */
 export const cubeMapNode = /*@__PURE__*/ nodeProxy( CubeMapNode );

package/src/nodes/utils/Discard.js

@@ -2,7 +2,23 @@ import { select } from '../math/ConditionalNode.js';
 import { expression } from '../code/ExpressionNode.js';
 import { addMethodChaining } from '../tsl/TSLCore.js';
 
+/** @module Discard **/
+
+/**
+ * Represents a `discard` shader operation in TSL.
+ *
+ * @method
+ * @param {ConditionalNode?} conditional - An optional conditional node. It allows to decide whether the discard should be executed or not.
+ * @return {Node} The `discard` expression.
+ */
 export const Discard = ( conditional ) => ( conditional ? select( conditional, expression( 'discard' ) ) : expression( 'discard' ) ).append();
+
+/**
+ * Represents a `return` shader operation in TSL.
+ *
+ * @method
+ * @return {ExpressionNode} The `return` expression.
+ */
 export const Return = () => expression( 'return' ).append();
 
 addMethodChaining( 'discard', Discard );

package/src/nodes/utils/EquirectUVNode.js

@@ -2,6 +2,19 @@ import TempNode from '../core/TempNode.js';
 import { positionWorldDirection } from '../accessors/Position.js';
 import { nodeProxy, vec2 } from '../tsl/TSLBase.js';
 
+/** @module EquirectUVNode **/
+
+/**
+ * Can be used to compute texture coordinates for projecting an
+ * equirectangular texture onto a mesh for using it as the scene's
+ * background.
+ *
+ * ```js
+ * scene.backgroundNode = texture( equirectTexture, equirectUV() );
+ * ```
+ *
+ * @augments TempNode
+ */
 class EquirectUVNode extends TempNode {
 
 	static get type() {
@@ -10,10 +23,20 @@ class EquirectUVNode extends TempNode {
 
 	}
 
+	/**
+	 * Constructs a new equirect uv node.
+	 *
+	 * @param {Node<vec3>} [dirNode=positionWorldDirection] - A direction vector for sampling which is by default `positionWorldDirection`.
+	 */
 	constructor( dirNode = positionWorldDirection ) {
 
 		super( 'vec2' );
 
+		/**
+		 * A direction vector for sampling why is by default `positionWorldDirection`.
+		 *
+		 * @type {Node<vec3>}
+		 */
 		this.dirNode = dirNode;
 
 	}
@@ -22,7 +45,7 @@ class EquirectUVNode extends TempNode {
 
 		const dir = this.dirNode;
 
-		const u = dir.z.atan2( dir.x ).mul( 1 / ( Math.PI * 2 ) ).add( 0.5 );
+		const u = dir.z.atan( dir.x ).mul( 1 / ( Math.PI * 2 ) ).add( 0.5 );
 		const v = dir.y.clamp( - 1.0, 1.0 ).asin().mul( 1 / Math.PI ).add( 0.5 );
 
 		return vec2( u, v );
@@ -33,4 +56,11 @@ class EquirectUVNode extends TempNode {
 
 export default EquirectUVNode;
 
+/**
+ * TSL function for creating an equirect uv node.
+ *
+ * @function
+ * @param {Node<vec3>} [dirNode=positionWorldDirection] - A direction vector for sampling which is by default `positionWorldDirection`.
+ * @returns {EquirectUVNode}
+ */
 export const equirectUV = /*@__PURE__*/ nodeProxy( EquirectUVNode );

package/src/nodes/utils/FlipNode.js

@@ -1,6 +1,21 @@
 import TempNode from '../core/TempNode.js';
 import { vectorComponents } from '../core/constants.js';
 
+/**
+ * This module is part of the TSL core and usually not used in app level code.
+ * It represents a flip operation during the shader generation process
+ * meaning it flips normalized values with the following formula:
+ * ```
+ * x = 1 - x;
+ * ```
+ * `FlipNode` is internally used to implement any `flipXYZW()`, `flipRGBA()` and
+ * `flipSTPQ()` method invocations on node objects. For example:
+ * ```js
+ * uvNode = uvNode.flipY();
+ * ```
+ *
+ * @augments TempNode
+ */
 class FlipNode extends TempNode {
 
 	static get type() {
@@ -9,15 +24,38 @@ class FlipNode extends TempNode {
 
 	}
 
+	/**
+	 * Constructs a new flip node.
+	 *
+	 * @param {Node} sourceNode - The node which component(s) should be flipped.
+	 * @param {String} components - The components that should be flipped e.g. `'x'` or `'xy'`.
+	 */
 	constructor( sourceNode, components ) {
 
 		super();
 
+		/**
+		 * The node which component(s) should be flipped.
+		 *
+		 * @type {Node}
+		 */
 		this.sourceNode = sourceNode;
+
+		/**
+		 * The components that should be flipped e.g. `'x'` or `'xy'`.
+		 *
+		 * @type {String}
+		 */
 		this.components = components;
 
 	}
 
+	/**
+	 * This method is overwritten since the node type is inferred from the source node.
+	 *
+	 * @param {NodeBuilder} builder - The current node builder.
+	 * @return {String} The node type.
+	 */
 	getNodeType( builder ) {
 
 		return this.sourceNode.getNodeType( builder );

package/src/nodes/utils/FunctionOverloadingNode.js

@@ -1,6 +1,15 @@
 import Node from '../core/Node.js';
-import { nodeProxy } from '../tsl/TSLBase.js';
+import { nodeProxy } from '../tsl/TSLCore.js';
 
+/** @module FunctionOverloadingNode **/
+
+/**
+ * This class allows to define multiple overloaded versions
+ * of the same function. Depending on the parameters of the function
+ * call, the node picks the best-fit overloaded version.
+ *
+ * @augments Node
+ */
 class FunctionOverloadingNode extends Node {
 
 	static get type() {
@@ -9,19 +18,55 @@ class FunctionOverloadingNode extends Node {
 
 	}
 
+	/**
+	 * Constructs a new function overloading node.
+	 *
+	 * @param {Array<Function>} functionNodes - Array of `Fn` function definitions.
+	 * @param {...Node} parametersNodes - A list of parameter nodes.
+	 */
 	constructor( functionNodes = [], ...parametersNodes ) {
 
 		super();
 
+		/**
+		 * Array of `Fn` function definitions.
+		 *
+		 * @type {Array<Function>}
+		 */
 		this.functionNodes = functionNodes;
+
+		/**
+		 * A list of parameter nodes.
+		 *
+		 * @type {Array<Node>}
+		 */
 		this.parametersNodes = parametersNodes;
 
+		/**
+		 * The selected overloaded function call.
+		 *
+		 * @private
+		 * @type {ShaderCallNodeInternal}
+		 */
 		this._candidateFnCall = null;
 
+		/**
+		 * This node is marked as global.
+		 *
+		 * @type {Boolean}
+		 * @default true
+		 */
 		this.global = true;
 
 	}
 
+	/**
+	 * This method is overwritten since the node type is inferred from
+	 * the function's return type.
+	 *
+	 * @param {NodeBuilder} builder - The current node builder.
+	 * @return {String} The node type.
+	 */
 	getNodeType() {
 
 		return this.functionNodes[ 0 ].shaderNode.layout.type;
@@ -98,4 +143,11 @@ export default FunctionOverloadingNode;
 
 const overloadingBaseFn = /*@__PURE__*/ nodeProxy( FunctionOverloadingNode );
 
+/**
+ * TSL function for creating a function overloading node.
+ *
+ * @function
+ * @param {Array<Function>} functionNodes - Array of `Fn` function definitions.
+ * @returns {FunctionOverloadingNode}
+ */
 export const overloadingFn = ( functionNodes ) => ( ...params ) => overloadingBaseFn( functionNodes, ...params );

package/src/nodes/utils/JoinNode.js

@@ -1,5 +1,12 @@
 import TempNode from '../core/TempNode.js';
 
+/**
+ * This module is part of the TSL core and usually not used in app level code.
+ * It represents a join operation during the shader generation process.
+ * For example in can compose/join two single floats into a `vec2` type.
+ *
+ * @augments TempNode
+ */
 class JoinNode extends TempNode {
 
 	static get type() {
@@ -8,14 +15,32 @@ class JoinNode extends TempNode {
 
 	}
 
+	/**
+	 * Constructs a new join node.
+	 *
+	 * @param {Array<Node>} nodes - An array of nodes that should be joined.
+	 * @param {String?} [nodeType=null] - The node type.
+	 */
 	constructor( nodes = [], nodeType = null ) {
 
 		super( nodeType );
 
+		/**
+		 * An array of nodes that should be joined.
+		 *
+		 * @type {Array<Node>}
+		 */
 		this.nodes = nodes;
 
 	}
 
+	/**
+	 * This method is overwritten since the node type must be inferred from the
+	 * joined data length if not explicitly defined.
+	 *
+	 * @param {NodeBuilder} builder - The current node builder.
+	 * @return {String} The node type.
+	 */
 	getNodeType( builder ) {
 
 		if ( this.nodeType !== null ) {

package/src/nodes/utils/LoopNode.js

@@ -2,6 +2,34 @@ import Node from '../core/Node.js';
 import { expression } from '../code/ExpressionNode.js';
 import { nodeObject, nodeArray } from '../tsl/TSLBase.js';
 
+/** @module LoopNode **/
+
+/**
+ * This module offers a variety of ways to implement loops in TSL. In it's basic form it's:
+ * ```js
+ * Loop( count, ( { i } ) => {
+ *
+ * } );
+ * ```
+ * However, it is also possible to define a start and end ranges, data types and loop conditions:
+ * ```js
+ * Loop( { start: int( 0 ), end: int( 10 ), type: 'int', condition: '<' }, ( { i } ) => {
+ *
+ * } );
+ *```
+ * Nested loops can be defined in a compacted form:
+ * ```js
+ * Loop( 10, 5, ( { i, j } ) => {
+ *
+ * } );
+ * ```
+ * Loops that should run backwards can be defined like so:
+ * ```js
+ * Loop( { start: 10 }, () => {} );
+ * ```
+ * The module also provides `Break()` and `Continue()` TSL expression for loop control.
+ * @augments Node
+ */
 class LoopNode extends Node {
 
 	static get type() {
@@ -10,6 +38,11 @@ class LoopNode extends Node {
 
 	}
 
+	/**
+	 * Constructs a new loop node.
+	 *
+	 * @param {Array<Any>} params - Depending on the loop type, array holds different parameterization values for the loop.
+	 */
 	constructor( params = [] ) {
 
 		super();
@@ -18,12 +51,25 @@ class LoopNode extends Node {
 
 	}
 
+	/**
+	 * Returns a loop variable name based on an index. The pattern is
+	 * `0` = `i`, `1`= `j`, `2`= `k` and so on.
+	 *
+	 * @param {Number} index - The index.
+	 * @return {String} The loop variable name.
+	 */
 	getVarName( index ) {
 
-		return String.fromCharCode( 'i'.charCodeAt() + index );
+		return String.fromCharCode( 'i'.charCodeAt( 0 ) + index );
 
 	}
 
+	/**
+	 * Returns properties about this node.
+	 *
+	 * @param {NodeBuilder} builder - The current node builder.
+	 * @return {Object} The node properties.
+	 */
 	getProperties( builder ) {
 
 		const properties = builder.getNodeProperties( this );
@@ -56,6 +102,12 @@ class LoopNode extends Node {
 
 	}
 
+	/**
+	 * This method is overwritten since the node type is inferred based on the loop configuration.
+	 *
+	 * @param {NodeBuilder} builder - The current node builder.
+	 * @return {String} The node type.
+	 */
 	getNodeType( builder ) {
 
 		const { returnsNode } = this.getProperties( builder );
@@ -197,8 +249,29 @@ class LoopNode extends Node {
 
 export default LoopNode;
 
+/**
+ * TSL function for creating a loop node.
+ *
+ * @function
+ * @param {...Any} params - A list of parameters.
+ * @returns {LoopNode}
+ */
 export const Loop = ( ...params ) => nodeObject( new LoopNode( nodeArray( params, 'int' ) ) ).append();
+
+/**
+ * TSL function for creating a `Continue()` expression.
+ *
+ * @function
+ * @returns {ExpressionNode}
+ */
 export const Continue = () => expression( 'continue' ).append();
+
+/**
+ * TSL function for creating a `Break()` expression.
+ *
+ * @function
+ * @returns {ExpressionNode}
+ */
 export const Break = () => expression( 'break' ).append();
 
 //

package/src/nodes/utils/MatcapUVNode.js

@@ -3,6 +3,14 @@ import { transformedNormalView } from '../accessors/Normal.js';
 import { positionViewDirection } from '../accessors/Position.js';
 import { nodeImmutable, vec2, vec3 } from '../tsl/TSLBase.js';
 
+/** @module MatcapUVNode **/
+
+/**
+ * Can be used to compute texture coordinates for projecting a
+ * matcap onto a mesh. Used by {@link MeshMatcapNodeMaterial}.
+ *
+ * @augments TempNode
+ */
 class MatcapUVNode extends TempNode {
 
 	static get type() {
@@ -11,6 +19,9 @@ class MatcapUVNode extends TempNode {
 
 	}
 
+	/**
+	 * Constructs a new matcap uv node.
+	 */
 	constructor() {
 
 		super( 'vec2' );
@@ -30,4 +41,10 @@ class MatcapUVNode extends TempNode {
 
 export default MatcapUVNode;
 
+/**
+ * TSL function for creating a matcap uv node.
+ *
+ * @function
+ * @returns {MatcapUVNode}
+ */
 export const matcapUV = /*@__PURE__*/ nodeImmutable( MatcapUVNode );