super-three 0.170.1 → 0.172.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;

package/src/nodes/core/NodeUtils.js

@@ -5,6 +5,8 @@ import { Vector2 } from '../../math/Vector2.js';
 import { Vector3 } from '../../math/Vector3.js';
 import { Vector4 } from '../../math/Vector4.js';
 
+/** @module NodeUtils **/
+
 // cyrb53 (c) 2018 bryc (github.com/bryc). License: Public domain. Attribution appreciated.
 // A fast and simple 64-bit (or 53-bit) string hash function with decent collision resistance.
 // Largely inspired by MurmurHash2/3, but with a focus on speed/simplicity.
@@ -45,10 +47,41 @@ function cyrb53( value, seed = 0 ) {
 
 }
 
+/**
+ * Computes a hash for the given string.
+ *
+ * @method
+ * @param {String} str - The string to be hashed.
+ * @return {Number} The hash.
+ */
 export const hashString = ( str ) => cyrb53( str );
+
+/**
+ * Computes a hash for the given array.
+ *
+ * @method
+ * @param {Array<Number>} array - The array to be hashed.
+ * @return {Number} The hash.
+ */
 export const hashArray = ( array ) => cyrb53( array );
+
+/**
+ * Computes a hash for the given list of parameters.
+ *
+ * @method
+ * @param {...Number} params - A list of parameters.
+ * @return {Number} The hash.
+ */
 export const hash = ( ...params ) => cyrb53( params );
 
+/**
+ * Computes a cache key for the given node.
+ *
+ * @method
+ * @param {Object} object - The object to be hashed.
+ * @param {Boolean} [force=false] - Whether to force a cache key computation or not.
+ * @return {Number} The hash.
+ */
 export function getCacheKey( object, force = false ) {
 
 	const values = [];
@@ -70,6 +103,15 @@ export function getCacheKey( object, force = false ) {
 
 }
 
+/**
+ * This generator function can be used to iterate over the node children
+ * of the given object.
+ *
+ * @generator
+ * @param {Object} node - The object to be hashed.
+ * @param {Boolean} [toJSON=false] - Whether to return JSON or not.
+ * @yields {Object} A result node holding the property, index (if available) and the child node.
+ */
 export function* getNodeChildren( node, toJSON = false ) {
 
 	for ( const property in node ) {
@@ -126,12 +168,61 @@ const typeFromLength = /*@__PURE__*/ new Map( [
 	[ 16, 'mat4' ]
 ] );
 
+const dataFromObject = /*@__PURE__*/ new WeakMap();
+
+/**
+ * Returns the data type for the given the length.
+ *
+ * @method
+ * @param {Number} length - The length.
+ * @return {String} The data type.
+ */
 export function getTypeFromLength( length ) {
 
 	return typeFromLength.get( length );
 
 }
 
+/**
+ * Returns the typed array for the given data type.
+ *
+ * @method
+ * @param {String} type - The data type.
+ * @return {TypedArray} The typed array.
+ */
+export function getTypedArrayFromType( type ) {
+
+	// Handle component type for vectors and matrices
+	if ( /[iu]?vec\d/.test( type ) ) {
+
+		// Handle int vectors
+		if ( type.startsWith( 'ivec' ) ) return Int32Array;
+		// Handle uint vectors
+		if ( type.startsWith( 'uvec' ) ) return Uint32Array;
+		// Default to float vectors
+		return Float32Array;
+
+	}
+
+	// Handle matrices (always float)
+	if ( /mat\d/.test( type ) ) return Float32Array;
+
+	// Basic types
+	if ( /float/.test( type ) ) return Float32Array;
+	if ( /uint/.test( type ) ) return Uint32Array;
+	if ( /int/.test( type ) ) return Int32Array;
+
+	throw new Error( `THREE.NodeUtils: Unsupported type: ${type}` );
+
+}
+
+/**
+ * Returns the length for the given data type.
+ *
+ * @method
+ * @param {String} type - The data type.
+ * @return {Number} The length.
+ */
 export function getLengthFromType( type ) {
 
 	if ( /float|int|uint/.test( type ) ) return 1;
@@ -145,6 +236,13 @@ export function getLengthFromType( type ) {
 
 }
 
+/**
+ * Returns the data type for the given value.
+ *
+ * @method
+ * @param {Any} value - The value.
+ * @return {String?} The data type.
+ */
 export function getValueType( value ) {
 
 	if ( value === undefined || value === null ) return null;
@@ -205,6 +303,14 @@ export function getValueType( value ) {
 
 }
 
+/**
+ * Returns the value/object for the given data type and parameters.
+ *
+ * @method
+ * @param {String} type - The given type.
+ * @param {...Any} params - A parameter list.
+ * @return {Any} The value/object.
+ */
 export function getValueFromType( type, ...params ) {
 
 	const last4 = type ? type.slice( - 4 ) : undefined;
@@ -263,6 +369,34 @@ export function getValueFromType( type, ...params ) {
 
 }
 
+/**
+ * Gets the object data that can be shared between different rendering steps.
+ *
+ * @param {Object} object - The object to get the data for.
+ * @return {Object} The object data.
+ */
+export function getDataFromObject( object ) {
+
+	let data = dataFromObject.get( object );
+
+	if ( data === undefined ) {
+
+		data = {};
+		dataFromObject.set( object, data );
+
+	}
+
+	return data;
+
+}
+
+/**
+ * Converts the given array buffer to a Base64 string.
+ *
+ * @method
+ * @param {ArrayBuffer} arrayBuffer - The array buffer.
+ * @return {String} The Base64 string.
+ */
 export function arrayBufferToBase64( arrayBuffer ) {
 
 	let chars = '';
@@ -279,6 +413,13 @@ export function arrayBufferToBase64( arrayBuffer ) {
 
 }
 
+/**
+ * Converts the given Base64 string to an array buffer.
+ *
+ * @method
+ * @param {String} base64 - The Base64 string.
+ * @return {ArrayBuffer} The array buffer.
+ */
 export function base64ToArrayBuffer( base64 ) {
 
 	return Uint8Array.from( atob( base64 ), c => c.charCodeAt( 0 ) ).buffer;