@plastic-software/three 0.167.4 → 0.174.0

package/src/nodes/core/NodeCache.js

@@ -1,16 +1,49 @@
-let id = 0;
+let _id = 0;
 
+/**
+ * This utility class is used in {@link NodeBuilder} as an internal
+ * cache data structure for node data.
+ */
 class NodeCache {
 
+	/**
+	 * Constructs a new node cache.
+	 *
+	 * @param {?NodeCache} parent - A reference to a parent cache.
+	 */
 	constructor( parent = null ) {
 
-		this.id = id ++;
+		/**
+		 * The id of the cache.
+		 *
+		 * @type {number}
+		 * @readonly
+		 */
+		this.id = _id ++;
+
+		/**
+		 * A weak map for managing node data.
+		 *
+		 * @type {WeakMap<Node, Object>}
+		 */
 		this.nodesData = new WeakMap();
 
+		/**
+		 * Reference to a parent node cache.
+		 *
+		 * @type {?NodeCache}
+		 * @default null
+		 */
 		this.parent = parent;
 
 	}
 
+	/**
+	 * Returns the data for the given node.
+	 *
+	 * @param {Node} node - The node.
+	 * @return {?Object} The data for the node.
+	 */
 	getData( node ) {
 
 		let data = this.nodesData.get( node );
@@ -25,6 +58,12 @@ class NodeCache {
 
 	}
 
+	/**
+	 * Sets the data for a given node.
+	 *
+	 * @param {Node} node - The node.
+	 * @param {Object} data - The data that should be cached.
+	 */
 	setData( node, data ) {
 
 		this.nodesData.set( node, data );

package/src/nodes/core/NodeCode.js

@@ -1,9 +1,40 @@
+/**
+ * {@link NodeBuilder} is going to create instances of this class during the build process
+ * of nodes. They represent user-defined, native shader code portions that are going to be
+ * injected by the builder. A dictionary of node codes is maintained in {@link NodeBuilder#codes}
+ * for this purpose.
+ */
 class NodeCode {
 
+	/**
+	 * Constructs a new code node.
+	 *
+	 * @param {string} name - The name of the code.
+	 * @param {string} type - The node type.
+	 * @param {string} [code=''] - The native shader code.
+	 */
 	constructor( name, type, code = '' ) {
 
+		/**
+		 * The name of the code.
+		 *
+		 * @type {string}
+		 */
 		this.name = name;
+
+		/**
+		 * The node type.
+		 *
+		 * @type {string}
+		 */
 		this.type = type;
+
+		/**
+		 * The native shader code.
+		 *
+		 * @type {string}
+		 * @default ''
+		 */
 		this.code = code;
 
 		Object.defineProperty( this, 'isNodeCode', { value: true } );

package/src/nodes/core/NodeFrame.js

@@ -1,29 +1,122 @@
 import { NodeUpdateType } from './constants.js';
 
+/**
+ * Management class for updating nodes. The module tracks metrics like
+ * the elapsed time, delta time, the render and frame ID to correctly
+ * call the node update methods {@link Node#updateBefore}, {@link Node#update}
+ * and {@link Node#updateAfter} depending on the node's configuration.
+ */
 class NodeFrame {
 
+	/**
+	 * Constructs a new node fame.
+	 */
 	constructor() {
 
+		/**
+		 * The elapsed time in seconds.
+		 *
+		 * @type {number}
+		 * @default 0
+		 */
 		this.time = 0;
+
+		/**
+		 * The delta time in seconds.
+		 *
+		 * @type {number}
+		 * @default 0
+		 */
 		this.deltaTime = 0;
 
+		/**
+		 * The frame ID.
+		 *
+		 * @type {number}
+		 * @default 0
+		 */
 		this.frameId = 0;
-		this.renderId = 0;
 
-		this.startTime = null;
+		/**
+		 * The render ID.
+		 *
+		 * @type {number}
+		 * @default 0
+		 */
+		this.renderId = 0;
 
+		/**
+		 * Used to control the {@link Node#update} call.
+		 *
+		 * @type {WeakMap<Node, Object>}
+		 */
 		this.updateMap = new WeakMap();
+
+		/**
+		 * Used to control the {@link Node#updateBefore} call.
+		 *
+		 * @type {WeakMap<Node, Object>}
+		 */
 		this.updateBeforeMap = new WeakMap();
+
+		/**
+		 * Used to control the {@link Node#updateAfter} call.
+		 *
+		 * @type {WeakMap<Node, Object>}
+		 */
 		this.updateAfterMap = new WeakMap();
 
+		/**
+		 * A reference to the current renderer.
+		 *
+		 * @type {?Renderer}
+		 * @default null
+		 */
 		this.renderer = null;
+
+		/**
+		 * A reference to the current material.
+		 *
+		 * @type {?Material}
+		 * @default null
+		 */
 		this.material = null;
+
+		/**
+		 * A reference to the current camera.
+		 *
+		 * @type {?Camera}
+		 * @default null
+		 */
 		this.camera = null;
+
+		/**
+		 * A reference to the current 3D object.
+		 *
+		 * @type {?Object3D}
+		 * @default null
+		 */
 		this.object = null;
+
+		/**
+		 * A reference to the current scene.
+		 *
+		 * @type {?Scene}
+		 * @default null
+		 */
 		this.scene = null;
 
 	}
 
+	/**
+	 * Returns a dictionary for a given node and update map which
+	 * is used to correctly call node update methods per frame or render.
+	 *
+	 * @private
+	 * @param {WeakMap<Node, Object>} referenceMap - The reference weak map.
+	 * @param {Node} nodeRef - The reference to the current node.
+	 * @return {Object<string,WeakMap>} The dictionary.
+	 */
 	_getMaps( referenceMap, nodeRef ) {
 
 		let maps = referenceMap.get( nodeRef );
@@ -43,6 +136,14 @@ class NodeFrame {
 
 	}
 
+	/**
+	 * This method executes the {@link Node#updateBefore} for the given node.
+	 * It makes sure {@link Node#updateBeforeType} is honored meaning the update
+	 * is only executed once per frame, render or object depending on the update
+	 * type.
+	 *
+	 * @param {Node} node - The node that should be updated.
+	 */
 	updateBeforeNode( node ) {
 
 		const updateType = node.getUpdateBeforeType();
@@ -84,6 +185,14 @@ class NodeFrame {
 
 	}
 
+	/**
+	 * This method executes the {@link Node#updateAfter} for the given node.
+	 * It makes sure {@link Node#updateAfterType} is honored meaning the update
+	 * is only executed once per frame, render or object depending on the update
+	 * type.
+	 *
+	 * @param {Node} node - The node that should be updated.
+	 */
 	updateAfterNode( node ) {
 
 		const updateType = node.getUpdateAfterType();
@@ -125,6 +234,14 @@ class NodeFrame {
 
 	}
 
+	/**
+	 * This method executes the {@link Node#update} for the given node.
+	 * It makes sure {@link Node#updateType} is honored meaning the update
+	 * is only executed once per frame, render or object depending on the update
+	 * type.
+	 *
+	 * @param {Node} node - The node that should be updated.
+	 */
 	updateNode( node ) {
 
 		const updateType = node.getUpdateType();
@@ -166,6 +283,10 @@ class NodeFrame {
 
 	}
 
+	/**
+	 * Updates the internal state of the node frame. This method is
+	 * called by the renderer in its internal animation loop.
+	 */
 	update() {
 
 		this.frameId ++;

package/src/nodes/core/NodeFunction.js

@@ -1,14 +1,60 @@
+/**
+ * Base class for node functions. A derived module must be implemented
+ * for each supported native shader language. Similar to other `Node*` modules,
+ * this class is only relevant during the building process and not used
+ * in user-level code.
+ */
 class NodeFunction {
 
+	/**
+	 * Constructs a new node function.
+	 *
+	 * @param {string} type - The node type. This type is the return type of the node function.
+	 * @param {Array<NodeFunctionInput>} inputs - The function's inputs.
+	 * @param {string} [name=''] - The function's name.
+	 * @param {string} [precision=''] - The precision qualifier.
+	 */
 	constructor( type, inputs, name = '', precision = '' ) {
 
+		/**
+		 * The node type. This type is the return type of the node function.
+		 *
+		 * @type {string}
+		 */
 		this.type = type;
+
+		/**
+		 * The function's inputs.
+		 *
+		 * @type {Array<NodeFunctionInput>}
+		 */
 		this.inputs = inputs;
+
+		/**
+		 * The name of the uniform.
+		 *
+		 * @type {string}
+		 * @default ''
+		 */
 		this.name = name;
+
+		/**
+		 * The precision qualifier.
+		 *
+		 * @type {string}
+		 * @default ''
+		 */
 		this.precision = precision;
 
 	}
 
+	/**
+	 * This method returns the native code of the node function.
+	 *
+	 * @abstract
+	 * @param {string} name - The function's name.
+	 * @return {string} A shader code.
+	 */
 	getCode( /*name = this.name*/ ) {
 
 		console.warn( 'Abstract function.' );

package/src/nodes/core/NodeFunctionInput.js

@@ -1,11 +1,55 @@
+/**
+ * Describes the input of a {@link NodeFunction}.
+ */
 class NodeFunctionInput {
 
+	/**
+	 * Constructs a new node function input.
+	 *
+	 * @param {string} type - The input type.
+	 * @param {string} name - The input name.
+	 * @param {?number} [count=null] - If the input is an Array, count will be the length.
+	 * @param {('in'|'out'|'inout')} [qualifier=''] - The parameter qualifier (only relevant for GLSL).
+	 * @param {boolean} [isConst=false] - Whether the input uses a const qualifier or not (only relevant for GLSL).
+	 */
 	constructor( type, name, count = null, qualifier = '', isConst = false ) {
 
+		/**
+		 *  The input type.
+		 *
+		 * @type {string}
+		 */
 		this.type = type;
+
+		/**
+		 * The input name.
+		 *
+		 * @type {string}
+		 */
 		this.name = name;
+
+		/**
+		 * If the input is an Array, count will be the length.
+		 *
+		 * @type {?number}
+		 * @default null
+		 */
 		this.count = count;
+
+		/**
+		 *The parameter qualifier (only relevant for GLSL).
+		 *
+		 * @type {('in'|'out'|'inout')}
+		 * @default ''
+		 */
 		this.qualifier = qualifier;
+
+		/**
+		 * Whether the input uses a const qualifier or not (only relevant for GLSL).
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.isConst = isConst;
 
 	}

package/src/nodes/core/NodeParser.js

@@ -1,5 +1,16 @@
+/**
+ * Base class for node parsers. A derived parser must be implemented
+ * for each supported native shader language.
+ */
 class NodeParser {
 
+	/**
+	 * The method parses the given native code an returns a node function.
+	 *
+	 * @abstract
+	 * @param {string} source - The native shader code.
+	 * @return {NodeFunction} A node function.
+	 */
 	parseFunction( /*source*/ ) {
 
 		console.warn( 'Abstract function.' );

package/src/nodes/core/NodeUniform.js

@@ -1,15 +1,57 @@
+/**
+ * {@link NodeBuilder} is going to create instances of this class during the build process
+ * of nodes. They represent the final shader uniforms that are going to be generated
+ * by the builder. A dictionary of node uniforms is maintained in {@link NodeBuilder#uniforms}
+ * for this purpose.
+ */
 class NodeUniform {
 
+	/**
+	 * Constructs a new node uniform.
+	 *
+	 * @param {string} name - The name of the uniform.
+	 * @param {string} type - The type of the uniform.
+	 * @param {UniformNode} node - An reference to the node.
+	 */
 	constructor( name, type, node ) {
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isNodeUniform = true;
 
+		/**
+		 * The name of the uniform.
+		 *
+		 * @type {string}
+		 */
 		this.name = name;
+
+		/**
+		 * The type of the uniform.
+		 *
+		 * @type {string}
+		 */
 		this.type = type;
+
+		/**
+		 * An reference to the node.
+		 *
+		 * @type {UniformNode}
+		 */
 		this.node = node.getSelf();
 
 	}
 
+	/**
+	 * The value of the uniform node.
+	 *
+	 * @type {any}
+	 */
 	get value() {
 
 		return this.node.value;
@@ -22,12 +64,22 @@ class NodeUniform {
 
 	}
 
+	/**
+	 * The id of the uniform node.
+	 *
+	 * @type {number}
+	 */
 	get id() {
 
 		return this.node.id;
 
 	}
 
+	/**
+	 * The uniform node's group.
+	 *
+	 * @type {UniformGroupNode}
+	 */
 	get groupNode() {
 
 		return this.node.groupNode;