super-three 0.171.0 → 0.172.0

package/src/nodes/gpgpu/ComputeNode.js

@@ -2,6 +2,13 @@ import Node from '../core/Node.js';
 import { NodeUpdateType } from '../core/constants.js';
 import { addMethodChaining, nodeObject } from '../tsl/TSLCore.js';
 
+/** @module ComputeNode **/
+
+/**
+ * TODO
+ *
+ * @augments Node
+ */
 class ComputeNode extends Node {
 
 	static get type() {
@@ -10,39 +17,116 @@ class ComputeNode extends Node {
 
 	}
 
+	/**
+	 * Constructs a new compute node.
+	 *
+	 * @param {Node} computeNode - TODO
+	 * @param {Number} count - TODO.
+	 * @param {Array<Number>} [workgroupSize=[64]] - TODO.
+	 */
 	constructor( computeNode, count, workgroupSize = [ 64 ] ) {
 
 		super( 'void' );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {Boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isComputeNode = true;
 
+		/**
+		 * TODO
+		 *
+		 * @type {Node}
+		 */
 		this.computeNode = computeNode;
 
+		/**
+		 * TODO
+		 *
+		 * @type {Number}
+		 */
 		this.count = count;
+
+		/**
+		 * TODO
+		 *
+		 * @type {Array<Number>}
+		 * @default [64]
+		 */
 		this.workgroupSize = workgroupSize;
+
+		/**
+		 * TODO
+		 *
+		 * @type {Number}
+		 */
 		this.dispatchCount = 0;
 
+		/**
+		 * TODO
+		 *
+		 * @type {Number}
+		 */
 		this.version = 1;
+
+		/**
+		 * The name or label of the uniform.
+		 *
+		 * @type {String}
+		 * @default ''
+		 */
+		this.name = '';
+
+		/**
+		 * The `updateBeforeType` is set to `NodeUpdateType.OBJECT` since {@link ComputeNode#updateBefore}
+		 * is executed once per object by default.
+		 *
+		 * @type {String}
+		 * @default 'object'
+		 */
 		this.updateBeforeType = NodeUpdateType.OBJECT;
 
+		/**
+		 * TODO
+		 *
+		 * @type {Function}
+		 */
 		this.onInitFunction = null;
 
 		this.updateDispatchCount();
 
 	}
 
+	/**
+	 * Executes the `dispose` event for this node.
+	 */
 	dispose() {
 
 		this.dispatchEvent( { type: 'dispose' } );
 
 	}
 
-	set needsUpdate( value ) {
+	/**
+	 * Sets the {@link ComputeNode#name} property.
+	 *
+	 * @param {String} name - The name of the uniform.
+	 * @return {ComputeNode} A reference to this node.
+	 */
+	label( name ) {
+
+		this.name = name;
 
-		if ( value === true ) this.version ++;
+		return this;
 
 	}
 
+	/**
+	 * TODO
+	 */
 	updateDispatchCount() {
 
 		const { count, workgroupSize } = this;
@@ -56,6 +140,12 @@ class ComputeNode extends Node {
 
 	}
 
+	/**
+	 * TODO
+	 *
+	 * @param {Function} callback - TODO.
+	 * @return {ComputeNode} A reference to this node.
+	 */
 	onInit( callback ) {
 
 		this.onInitFunction = callback;
@@ -64,6 +154,11 @@ class ComputeNode extends Node {
 
 	}
 
+	/**
+	 * The method execute the compute for this node.
+	 *
+	 * @param {NodeFrame} frame - A reference to the current node frame.
+	 */
 	updateBefore( { renderer } ) {
 
 		renderer.compute( this );
@@ -92,6 +187,15 @@ class ComputeNode extends Node {
 
 export default ComputeNode;
 
+/**
+ * TSL function for creating a compute node.
+ *
+ * @function
+ * @param {Node} node - TODO
+ * @param {Number} count - TODO.
+ * @param {Array<Number>} [workgroupSize=[64]] - TODO.
+ * @returns {AtomicFunctionNode}
+ */
 export const compute = ( node, count, workgroupSize ) => nodeObject( new ComputeNode( nodeObject( node ), count, workgroupSize ) );
 
 addMethodChaining( 'compute', compute );

package/src/nodes/gpgpu/WorkgroupInfoNode.js

@@ -2,12 +2,32 @@ import ArrayElementNode from '../utils/ArrayElementNode.js';
 import { nodeObject } from '../tsl/TSLCore.js';
 import Node from '../core/Node.js';
 
+/** @module WorkgroupInfoNode **/
+
+/**
+ * Represents an element of a 'workgroup' scoped buffer.
+ *
+ * @augments ArrayElementNode
+ */
 class WorkgroupInfoElementNode extends ArrayElementNode {
 
+	/**
+	 * Constructs a new workgroup info element node.
+	 *
+	 * @param {Node} workgroupInfoNode - The workgroup info node.
+	 * @param {Node} indexNode - The index node that defines the element access.
+	 */
 	constructor( workgroupInfoNode, indexNode ) {
 
 		super( workgroupInfoNode, indexNode );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {Boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isWorkgroupInfoElementNode = true;
 
 	}
@@ -35,22 +55,77 @@ class WorkgroupInfoElementNode extends ArrayElementNode {
 
 }
 
-
+/**
+ * A node allowing the user to create a 'workgroup' scoped buffer within the
+ * context of a compute shader. Typically, workgroup scoped buffers are
+ * created to hold data that is transfered from a global storage scope into
+ * a local workgroup scope. For invocations within a workgroup, data
+ * access speeds on 'workgroup' scoped buffers can be significantly faster
+ * than similar access operations on globally accessible storage buffers.
+ *
+ * This node can only be used with a WebGPU backend.
+ *
+ * @augments Node
+ */
 class WorkgroupInfoNode extends Node {
 
+	/**
+	 * Constructs a new buffer scoped to type scope.
+	 *
+	 * @param {String} scope - TODO.
+	 * @param {String} bufferType - The data type of a 'workgroup' scoped buffer element.
+	 * @param {Number} [bufferCount=0] - The number of elements in the buffer.
+	 */
 	constructor( scope, bufferType, bufferCount = 0 ) {
 
 		super( bufferType );
 
+		/**
+		 * The buffer type.
+		 *
+		 * @type {String}
+		 */
 		this.bufferType = bufferType;
+
+		/**
+		 * The buffer count.
+		 *
+		 * @type {Number}
+		 * @default 0
+		 */
 		this.bufferCount = bufferCount;
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {Boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isWorkgroupInfoNode = true;
 
+		/**
+		 * The data type of the array buffer.
+		 *
+		 * @type {String}
+		 */
+		this.elementType = bufferType;
+
+		/**
+		 * TODO.
+		 *
+		 * @type {String}
+		 */
 		this.scope = scope;
 
 	}
 
+	/**
+	 * Sets the name/label of this node.
+	 *
+	 * @param {String} name - The name to set.
+	 * @return {WorkgroupInfoNode} A reference to this node.
+	 */
 	label( name ) {
 
 		this.name = name;
@@ -59,26 +134,51 @@ class WorkgroupInfoNode extends Node {
 
 	}
 
-	getHash() {
+	/**
+	 * Sets the scope of this node.
+	 *
+	 * @param {String} scope - The scope to set.
+	 * @return {WorkgroupInfoNode} A reference to this node.
+	 */
+	setScope( scope ) {
+
+		this.scope = scope;
 
-		return this.uuid;
+		return this;
 
 	}
 
-	setScope( scope ) {
 
-		this.scope = scope;
+	/**
+	 * The data type of the array buffer.
+	 *
+	 * @return {String} The element type.
+	 */
+	getElementType() {
 
-		return this;
+		return this.elementType;
 
 	}
 
+	/**
+	 * Overwrites the default implementation since the input type
+	 * is inferred from the scope.
+	 *
+	 * @param {NodeBuilder} builder - The current node builder.
+	 * @return {String} The input type.
+	 */
 	getInputType( /*builder*/ ) {
 
 		return `${this.scope}Array`;
 
 	}
 
+	/**
+	 * This method can be used to access elements via an index node.
+	 *
+	 * @param {IndexNode} indexNode - indexNode.
+	 * @return {WorkgroupInfoElementNode} A reference to an element.
+	 */
 	element( indexNode ) {
 
 		return nodeObject( new WorkgroupInfoElementNode( this, indexNode ) );
@@ -95,6 +195,15 @@ class WorkgroupInfoNode extends Node {
 
 export default WorkgroupInfoNode;
 
+/**
+ * TSL function for creating a workgroup info node.
+ * Creates a new 'workgroup' scoped array buffer.
+ *
+ * @function
+ * @param {String} type - The data type of a 'workgroup' scoped buffer element.
+ * @param {Number} [count=0] - The number of elements in the buffer.
+ * @returns {WorkgroupInfoNode}
+ */
 export const workgroupArray = ( type, count ) => nodeObject( new WorkgroupInfoNode( 'Workgroup', type, count ) );
 
 

package/src/nodes/lighting/AONode.js

@@ -1,5 +1,12 @@
 import LightingNode from './LightingNode.js';
 
+/**
+ * A generic class that can be used by nodes which contribute
+ * ambient occlusion to the scene. E.g. an ambient occlusion map
+ * node can be used as input for this module. Used in {@link NodeMaterial}.
+ *
+ * @augments LightingNode
+ */
 class AONode extends LightingNode {
 
 	static get type() {
@@ -8,10 +15,21 @@ class AONode extends LightingNode {
 
 	}
 
+	/**
+	 * Constructs a new AO node.
+	 *
+	 * @param {Node<float>?} [aoNode=null] - The ambient occlusion node.
+	 */
 	constructor( aoNode = null ) {
 
 		super();
 
+		/**
+		 * The ambient occlusion node.
+		 *
+		 * @type {Node<float>?}
+		 * @default null
+		 */
 		this.aoNode = aoNode;
 
 	}

package/src/nodes/lighting/AmbientLightNode.js

@@ -1,5 +1,10 @@
 import AnalyticLightNode from './AnalyticLightNode.js';
 
+/**
+ * Module for representing ambient lights as nodes.
+ *
+ * @augments AnalyticLightNode
+ */
 class AmbientLightNode extends AnalyticLightNode {
 
 	static get type() {
@@ -8,6 +13,11 @@ class AmbientLightNode extends AnalyticLightNode {
 
 	}
 
+	/**
+	 * Constructs a new ambient light node.
+	 *
+	 * @param {AmbientLight?} [light=null] - The ambient light source.
+	 */
 	constructor( light = null ) {
 
 		super( light );

package/src/nodes/lighting/AnalyticLightNode.js

@@ -7,6 +7,11 @@ import { hash } from '../core/NodeUtils.js';
 import { shadow } from './ShadowNode.js';
 import { nodeObject } from '../tsl/TSLCore.js';
 
+/**
+ * Base class for analytic light nodes.
+ *
+ * @augments LightingNode
+ */
 class AnalyticLightNode extends LightingNode {
 
 	static get type() {
@@ -15,29 +20,92 @@ class AnalyticLightNode extends LightingNode {
 
 	}
 
+	/**
+	 * Constructs a new analytic light node.
+	 *
+	 * @param {Light?} [light=null] - The light source.
+	 */
 	constructor( light = null ) {
 
 		super();
 
+		/**
+		 * The light source.
+		 *
+		 * @type {Light?}
+		 * @default null
+		 */
 		this.light = light;
 
+		/**
+		 * The light's color value.
+		 *
+		 * @type {Color}
+		 */
 		this.color = new Color();
+
+		/**
+		 * The light's color node. Points to `colorNode` of the light source, if set. Otherwise
+		 * it creates a uniform node based on {@link AnalyticLightNode#color}.
+		 *
+		 * @type {Node}
+		 */
 		this.colorNode = ( light && light.colorNode ) || uniform( this.color ).setGroup( renderGroup );
 
+		/**
+		 * This property is used to retain a reference to the original value of {@link AnalyticLightNode#colorNode}.
+		 * The final color node is represented by a different node when using shadows.
+		 *
+		 * @type {Node?}
+		 * @default null
+		 */
 		this.baseColorNode = null;
 
+		/**
+		 * Represents the light's shadow.
+		 *
+		 * @type {ShadowNode?}
+   		 * @default null
+		 */
 		this.shadowNode = null;
+
+		/**
+		 * Represents the light's shadow color.
+		 *
+		 * @type {Node?}
+   		 * @default null
+		 */
 		this.shadowColorNode = null;
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {Boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isAnalyticLightNode = true;
 
+		/**
+		 * Overwritten since analytic light nodes are updated
+		 * once per frame.
+		 *
+		 * @type {String}
+		 * @default 'frame'
+		 */
 		this.updateType = NodeUpdateType.FRAME;
 
 	}
 
-	getCacheKey() {
+	/**
+	 * Overwrites the default {@link Node#customCacheKey} implementation by including the
+	 * `light.id` and `light.castShadow` into the cache key.
+	 *
+	 * @return {Number} The custom cache key.
+	 */
+	customCacheKey() {
 
-		return hash( super.getCacheKey(), this.light.id, this.light.castShadow ? 1 : 0 );
+		return hash( this.light.id, this.light.castShadow ? 1 : 0 );
 
 	}
 
@@ -47,12 +115,25 @@ class AnalyticLightNode extends LightingNode {
 
 	}
 
+	/**
+	 * Setups the shadow node for this light. The method exists so concrete light classes
+	 * can setup different types of shadow nodes.
+	 *
+	 * @return {ShadowNode} The created shadow node.
+	 */
 	setupShadowNode() {
 
 		return shadow( this.light );
 
 	}
 
+	/**
+	 * Setups the shadow for this light. This method is only executed if the light
+	 * cast shadows and the current build object receives shadows. It incorporates
+	 * shadows into the lighting computation.
+	 *
+	 * @param {NodeBuilder} builder - The current node builder.
+	 */
 	setupShadow( builder ) {
 
 		const { renderer } = builder;
@@ -91,6 +172,13 @@ class AnalyticLightNode extends LightingNode {
 
 	}
 
+	/**
+	 * Unlike most other nodes, lighting nodes do not return a output node in {@link Node#setup}.
+	 * The main purpose of lighting nodes is to configure the current {@link LightingModel} and/or
+	 * invocate the respective interface methods.
+	 *
+	 * @param {NodeBuilder} builder - The current node builder.
+	 */
 	setup( builder ) {
 
 		this.colorNode = this.baseColorNode || this.colorNode;
@@ -113,6 +201,13 @@ class AnalyticLightNode extends LightingNode {
 
 	}
 
+	/**
+	 * The update method is used to update light uniforms per frame.
+	 * Potentially overwritten in concrete light nodes to update light
+	 * specific uniforms.
+	 *
+	 * @param {NodeFrame} frame - A reference to the current node frame.
+	 */
 	update( /*frame*/ ) {
 
 		const { light } = this;

package/src/nodes/lighting/BasicEnvironmentNode.js

@@ -1,6 +1,14 @@
 import LightingNode from './LightingNode.js';
 import { cubeMapNode } from '../utils/CubeMapNode.js';
 
+/**
+ * Represents a basic model for Image-based lighting (IBL). The environment
+ * is defined via environment maps in the equirectangular or cube map format.
+ * `BasicEnvironmentNode` is intended for non-PBR materials like {@link MeshBasicNodeMaterial}
+ * or {@link MeshPhongNodeMaterial}.
+ *
+ * @augments LightingNode
+ */
 class BasicEnvironmentNode extends LightingNode {
 
 	static get type() {
@@ -9,10 +17,21 @@ class BasicEnvironmentNode extends LightingNode {
 
 	}
 
+	/**
+	 * Constructs a new basic environment node.
+	 *
+	 * @param {Node} [envNode=null] - A node representing the environment.
+	 */
 	constructor( envNode = null ) {
 
 		super();
 
+		/**
+		 * A node representing the environment.
+		 *
+		 * @type {Node}
+		 * @default null
+		 */
 		this.envNode = envNode;
 
 	}

package/src/nodes/lighting/BasicLightMapNode.js

@@ -1,6 +1,13 @@
 import LightingNode from './LightingNode.js';
 import { float } from '../tsl/TSLBase.js';
 
+/**
+ * A specific version of {@link IrradianceNode} that is only relevant
+ * for {@link MeshBasicNodeMaterial}. Since the material is unlit, it
+ * requires a special scaling factor for the light map.
+ *
+ * @augments LightingNode
+ */
 class BasicLightMapNode extends LightingNode {
 
 	static get type() {
@@ -9,10 +16,20 @@ class BasicLightMapNode extends LightingNode {
 
 	}
 
+	/**
+	 * Constructs a new basic light map node.
+	 *
+	 * @param {Node<vec3>?} [lightMapNode=null] - The light map node.
+	 */
 	constructor( lightMapNode = null ) {
 
 		super();
 
+		/**
+		 * The light map node.
+		 *
+		 * @type {Node<vec3>?}
+		 */
 		this.lightMapNode = lightMapNode;
 
 	}

package/src/nodes/lighting/DirectionalLightNode.js

@@ -1,6 +1,11 @@
 import AnalyticLightNode from './AnalyticLightNode.js';
 import { lightTargetDirection } from '../accessors/Lights.js';
 
+/**
+ * Module for representing directional lights as nodes.
+ *
+ * @augments AnalyticLightNode
+ */
 class DirectionalLightNode extends AnalyticLightNode {
 
 	static get type() {
@@ -9,6 +14,11 @@ class DirectionalLightNode extends AnalyticLightNode {
 
 	}
 
+	/**
+	 * Constructs a new directional light node.
+	 *
+	 * @param {DirectionalLight?} [light=null] - The directional light source.
+	 */
 	constructor( light = null ) {
 
 		super( light );

package/src/nodes/lighting/EnvironmentNode.js

@@ -11,6 +11,13 @@ import { pmremTexture } from '../pmrem/PMREMNode.js';
 
 const _envNodeCache = new WeakMap();
 
+/**
+ * Represents a physical model for Image-based lighting (IBL). The environment
+ * is defined via environment maps in the equirectangular, cube map or cubeUV (PMREM) format.
+ * `EnvironmentNode` is intended for PBR materials like {@link MeshStandardNodeMaterial}.
+ *
+ * @augments LightingNode
+ */
 class EnvironmentNode extends LightingNode {
 
 	static get type() {
@@ -19,10 +26,21 @@ class EnvironmentNode extends LightingNode {
 
 	}
 
+	/**
+	 * Constructs a new environment node.
+	 *
+	 * @param {Node} [envNode=null] - A node representing the environment.
+	 */
 	constructor( envNode = null ) {
 
 		super();
 
+		/**
+		 * A node representing the environment.
+		 *
+		 * @type {Node?}
+		 * @default null
+		 */
 		this.envNode = envNode;
 
 	}