@needle-tools/three 0.169.20 → 0.183.2-canary.0

package/src/animation/PropertyBinding.js

@@ -1,3 +1,4 @@
+import { warn, error } from '../utils.js';
 // Characters [].:/ are reserved for track binding syntax.
 const _RESERVED_CHARS_RE = '\\[\\]\\.:\\/';
 const _reservedRe = new RegExp( '[' + _RESERVED_CHARS_RE + ']', 'g' );
@@ -100,15 +101,48 @@ class Composite {
 // prototype version of these methods with one that represents
 // the bound state. When the property is not found, the methods
 // become no-ops.
+
+
+/**
+ * This holds a reference to a real property in the scene graph; used internally.
+ */
 class PropertyBinding {
 
+	/**
+	 * Constructs a new property binding.
+	 *
+	 * @param {Object} rootNode - The root node.
+	 * @param {string} path - The path.
+	 * @param {?Object} [parsedPath] - The parsed path.
+	 */
 	constructor( rootNode, path, parsedPath ) {
 
+		/**
+		 * The object path to the animated property.
+		 *
+		 * @type {string}
+		 */
 		this.path = path;
+
+		/**
+		 * An object holding information about the path.
+		 *
+		 * @type {Object}
+		 */
 		this.parsedPath = parsedPath || PropertyBinding.parseTrackName( path );
 
+		/**
+		 * The object owns the animated property.
+		 *
+		 * @type {?Object}
+		 */
 		this.node = PropertyBinding.findNode( rootNode, this.parsedPath.nodeName );
 
+		/**
+		 * The root node.
+		 *
+		 * @type {Object3D|Skeleton}
+		 */
 		this.rootNode = rootNode;
 
 		// initial state of these methods that calls 'bind'
@@ -118,6 +152,15 @@ class PropertyBinding {
 	}
 
 
+	/**
+	 * Factory method for creating a property binding from the given parameters.
+	 *
+	 * @static
+	 * @param {Object} root - The root node.
+	 * @param {string} path - The path.
+	 * @param {?Object} [parsedPath] - The parsed path.
+	 * @return {PropertyBinding|Composite} The created property binding or composite.
+	 */
 	static create( root, path, parsedPath ) {
 
 		if ( ! ( root && root.isAnimationObjectGroup ) ) {
@@ -136,8 +179,8 @@ class PropertyBinding {
 	 * Replaces spaces with underscores and removes unsupported characters from
 	 * node names, to ensure compatibility with parseTrackName().
 	 *
-	 * @param {string} name Node name to be sanitized.
-	 * @return {string}
+	 * @param {string} name - Node name to be sanitized.
+	 * @return {string} The sanitized node name.
 	 */
 	static sanitizeNodeName( name ) {
 
@@ -145,6 +188,24 @@ class PropertyBinding {
 
 	}
 
+	/**
+	 * Parses the given track name (an object path to an animated property) and
+	 * returns an object with information about the path. Matches strings in the following forms:
+	 *
+	 * - nodeName.property
+	 * - nodeName.property[accessor]
+	 * - nodeName.material.property[accessor]
+	 * - uuid.property[accessor]
+	 * - uuid.objectName[objectIndex].propertyName[propertyIndex]
+	 * - parentName/nodeName.property
+	 * - parentName/parentName/nodeName.property[index]
+	 * - .bone[Armature.DEF_cog].position
+	 * - scene:helium_balloon_model:helium_balloon_model.position
+	 *
+	 * @static
+	 * @param {string} trackName - The track name to parse.
+	 * @return {Object} The parsed track name as an object.
+	 */
 	static parseTrackName( trackName ) {
 
 		const matches = _trackRe.exec( trackName );
@@ -193,6 +254,15 @@ class PropertyBinding {
 
 	}
 
+	/**
+	 * Searches for a node in the hierarchy of the given root object by the given
+	 * node name.
+	 *
+	 * @static
+	 * @param {Object} root - The root object.
+	 * @param {string|number} nodeName - The name of the node.
+	 * @return {?Object} The found node. Returns `null` if no object was found.
+	 */
 	static findNode( root, nodeName ) {
 
 		if ( nodeName === undefined || nodeName === '' || nodeName === '.' || nodeName === - 1 || nodeName === root.name || nodeName === root.uuid ) {
@@ -427,7 +497,9 @@ class PropertyBinding {
 
 	}
 
-	// create getter / setter pair for a property in the scene graph
+	/**
+	 * Creates a getter / setter pair for the property tracked by this binding.
+	 */
 	bind() {
 
 		let targetObject = this.node;
@@ -452,7 +524,7 @@ class PropertyBinding {
 		// ensure there is a value node
 		if ( ! targetObject ) {
 
-			console.warn( 'THREE.PropertyBinding: No target node found for track: ' + this.path + '.' );
+			warn( 'PropertyBinding: No target node found for track: ' + this.path + '.' );
 			return;
 
 		}
@@ -468,14 +540,14 @@ class PropertyBinding {
 
 					if ( ! targetObject.material ) {
 
-						console.error( 'THREE.PropertyBinding: Can not bind to material as node does not have a material.', this );
+						error( 'PropertyBinding: Can not bind to material as node does not have a material.', this );
 						return;
 
 					}
 
 					if ( ! targetObject.material.materials ) {
 
-						console.error( 'THREE.PropertyBinding: Can not bind to material.materials as node.material does not have a materials array.', this );
+						error( 'PropertyBinding: Can not bind to material.materials as node.material does not have a materials array.', this );
 						return;
 
 					}
@@ -488,7 +560,7 @@ class PropertyBinding {
 
 					if ( ! targetObject.skeleton ) {
 
-						console.error( 'THREE.PropertyBinding: Can not bind to bones as node does not have a skeleton.', this );
+						error( 'PropertyBinding: Can not bind to bones as node does not have a skeleton.', this );
 						return;
 
 					}
@@ -523,14 +595,14 @@ class PropertyBinding {
 
 					if ( ! targetObject.material ) {
 
-						console.error( 'THREE.PropertyBinding: Can not bind to material as node does not have a material.', this );
+						error( 'PropertyBinding: Can not bind to material as node does not have a material.', this );
 						return;
 
 					}
 
 					if ( ! targetObject.material.map ) {
 
-						console.error( 'THREE.PropertyBinding: Can not bind to material.map as node.material does not have a map.', this );
+						error( 'PropertyBinding: Can not bind to material.map as node.material does not have a map.', this );
 						return;
 
 					}
@@ -542,7 +614,7 @@ class PropertyBinding {
 
 					if ( targetObject[ objectName ] === undefined ) {
 
-						console.error( 'THREE.PropertyBinding: Can not bind to objectName of node undefined.', this );
+						error( 'PropertyBinding: Can not bind to objectName of node undefined.', this );
 						return;
 
 					}
@@ -556,7 +628,7 @@ class PropertyBinding {
 
 				if ( targetObject[ objectIndex ] === undefined ) {
 
-					console.error( 'THREE.PropertyBinding: Trying to bind to objectIndex of objectName, but is undefined.', this, targetObject );
+					error( 'PropertyBinding: Trying to bind to objectIndex of objectName, but is undefined.', this, targetObject );
 					return;
 
 				}
@@ -574,7 +646,7 @@ class PropertyBinding {
 
 			const nodeName = parsedPath.nodeName;
 
-			console.error( 'THREE.PropertyBinding: Trying to update property for track: ' + nodeName +
+			error( 'PropertyBinding: Trying to update property for track: ' + nodeName +
 				'.' + propertyName + ' but it wasn\'t found.', targetObject );
 			return;
 
@@ -585,11 +657,11 @@ class PropertyBinding {
 
 		this.targetObject = targetObject;
 
-		if ( targetObject.needsUpdate !== undefined ) { // material
+		if ( targetObject.isMaterial === true ) {
 
 			versioning = this.Versioning.NeedsUpdate;
 
-		} else if ( targetObject.matrixWorldNeedsUpdate !== undefined ) { // node transform
+		} else if ( targetObject.isObject3D === true ) {
 
 			versioning = this.Versioning.MatrixWorldNeedsUpdate;
 
@@ -609,14 +681,14 @@ class PropertyBinding {
 				// support resolving morphTarget names into indices.
 				if ( ! targetObject.geometry ) {
 
-					console.error( 'THREE.PropertyBinding: Can not bind to morphTargetInfluences because node does not have a geometry.', this );
+					error( 'PropertyBinding: Can not bind to morphTargetInfluences because node does not have a geometry.', this );
 					return;
 
 				}
 
 				if ( ! targetObject.geometry.morphAttributes ) {
 
-					console.error( 'THREE.PropertyBinding: Can not bind to morphTargetInfluences because node does not have a geometry.morphAttributes.', this );
+					error( 'PropertyBinding: Can not bind to morphTargetInfluences because node does not have a geometry.morphAttributes.', this );
 					return;
 
 				}
@@ -660,6 +732,9 @@ class PropertyBinding {
 
 	}
 
+	/**
+	 * Unbinds the property.
+	 */
 	unbind() {
 
 		this.node = null;

package/src/animation/PropertyMixer.js

@@ -1,10 +1,31 @@
 import { Quaternion } from '../math/Quaternion.js';
 
+/**
+ * Buffered scene graph property that allows weighted accumulation; used internally.
+ */
 class PropertyMixer {
 
+	/**
+	 * Constructs a new property mixer.
+	 *
+	 * @param {PropertyBinding} binding - The property binding.
+	 * @param {string} typeName - The keyframe track type name.
+	 * @param {number} valueSize - The keyframe track value size.
+	 */
 	constructor( binding, typeName, valueSize ) {
 
+		/**
+		 * The property binding.
+		 *
+		 * @type {PropertyBinding}
+		 */
 		this.binding = binding;
+
+		/**
+		 * The keyframe track value size.
+		 *
+		 * @type {number}
+		 */
 		this.valueSize = valueSize;
 
 		let mixFunction,
@@ -66,15 +87,46 @@ class PropertyMixer {
 		this._origIndex = 3;
 		this._addIndex = 4;
 
+		/**
+		 * Accumulated weight of the property binding.
+		 *
+		 * @type {number}
+		 * @default 0
+		 */
 		this.cumulativeWeight = 0;
+
+		/**
+		 * Accumulated additive weight of the property binding.
+		 *
+		 * @type {number}
+		 * @default 0
+		 */
 		this.cumulativeWeightAdditive = 0;
 
+		/**
+		 * Number of active keyframe tracks currently using this property binding.
+		 *
+		 * @type {number}
+		 * @default 0
+		 */
 		this.useCount = 0;
+
+		/**
+		 * Number of keyframe tracks referencing this property binding.
+		 *
+		 * @type {number}
+		 * @default 0
+		 */
 		this.referenceCount = 0;
 
 	}
 
-	// accumulate data in the 'incoming' region into 'accu<i>'
+	/**
+	 * Accumulates data in the `incoming` region into `accu<i>`.
+	 *
+	 * @param {number} accuIndex - The accumulation index.
+	 * @param {number} weight - The weight.
+	 */
 	accumulate( accuIndex, weight ) {
 
 		// note: happily accumulating nothing when weight = 0, the caller knows
@@ -112,7 +164,11 @@ class PropertyMixer {
 
 	}
 
-	// accumulate data in the 'incoming' region into 'add'
+	/**
+	 * Accumulates data in the `incoming` region into `add`.
+	 *
+	 * @param {number} weight - The weight.
+	 */
 	accumulateAdditive( weight ) {
 
 		const buffer = this.buffer,
@@ -134,7 +190,11 @@ class PropertyMixer {
 
 	}
 
-	// apply the state of 'accu<i>' to the binding when accus differ
+	/**
+	 * Applies the state of `accu<i>` to the binding when accus differ.
+	 *
+	 * @param {number} accuIndex - The accumulation index.
+	 */
 	apply( accuIndex ) {
 
 		const stride = this.valueSize,
@@ -183,7 +243,10 @@ class PropertyMixer {
 
 	}
 
-	// remember the state of the bound property and copy it to both accus
+
+	/**
+	 * Remembers the state of the bound property and copy it to both accus.
+	 */
 	saveOriginalState() {
 
 		const binding = this.binding;
@@ -210,7 +273,9 @@ class PropertyMixer {
 
 	}
 
-	// apply the state previously taken via 'saveOriginalState' to the binding
+	/**
+	 * Applies the state previously taken via {@link PropertyMixer#saveOriginalState} to the binding.
+	 */
 	restoreOriginalState() {
 
 		const originalValueOffset = this.valueSize * 3;
@@ -218,6 +283,8 @@ class PropertyMixer {
 
 	}
 
+	// internals
+
 	_setAdditiveIdentityNumeric() {
 
 		const startIndex = this._addIndex * this.valueSize;

package/src/animation/tracks/BooleanKeyframeTrack.js

@@ -2,11 +2,22 @@ import { InterpolateDiscrete } from '../../constants.js';
 import { KeyframeTrack } from '../KeyframeTrack.js';
 
 /**
- * A Track of Boolean keyframe values.
+ * A track for boolean keyframe values.
+ *
+ * @augments KeyframeTrack
  */
 class BooleanKeyframeTrack extends KeyframeTrack {
 
-	// No interpolation parameter because only InterpolateDiscrete is valid.
+	/**
+	 * Constructs a new boolean keyframe track.
+	 *
+	 * This keyframe track type has no `interpolation` parameter because the
+	 * interpolation is always discrete.
+	 *
+	 * @param {string} name - The keyframe track's name.
+	 * @param {Array<number>} times - A list of keyframe times.
+	 * @param {Array<boolean>} values - A list of keyframe values.
+	 */
 	constructor( name, times, values ) {
 
 		super( name, times, values );
@@ -15,14 +26,30 @@ class BooleanKeyframeTrack extends KeyframeTrack {
 
 }
 
+/**
+ * The value type name.
+ *
+ * @type {string}
+ * @default 'bool'
+ */
 BooleanKeyframeTrack.prototype.ValueTypeName = 'bool';
+
+/**
+ * The value buffer type of this keyframe track.
+ *
+ * @type {TypedArray|Array}
+ * @default Array.constructor
+ */
 BooleanKeyframeTrack.prototype.ValueBufferType = Array;
+
+/**
+ * The default interpolation type of this keyframe track.
+ *
+ * @type {(InterpolateLinear|InterpolateDiscrete|InterpolateSmooth)}
+ * @default InterpolateDiscrete
+ */
 BooleanKeyframeTrack.prototype.DefaultInterpolation = InterpolateDiscrete;
 BooleanKeyframeTrack.prototype.InterpolantFactoryMethodLinear = undefined;
 BooleanKeyframeTrack.prototype.InterpolantFactoryMethodSmooth = undefined;
 
-// Note: Actually this track could have a optimized / compressed
-// representation of a single value and a custom interpolant that
-// computes "firstValue ^ isOdd( index )".
-
 export { BooleanKeyframeTrack };

package/src/animation/tracks/ColorKeyframeTrack.js

@@ -1,15 +1,36 @@
 import { KeyframeTrack } from '../KeyframeTrack.js';
 
 /**
- * A Track of keyframe values that represent color.
+ * A track for color keyframe values.
+ *
+ * @augments KeyframeTrack
  */
-class ColorKeyframeTrack extends KeyframeTrack {}
+class ColorKeyframeTrack extends KeyframeTrack {
 
+	/**
+	 * Constructs a new color keyframe track.
+	 *
+	 * @param {string} name - The keyframe track's name.
+	 * @param {Array<number>} times - A list of keyframe times.
+	 * @param {Array<number>} values - A list of keyframe values.
+	 * @param {(InterpolateLinear|InterpolateDiscrete|InterpolateSmooth)} [interpolation] - The interpolation type.
+	 */
+	constructor( name, times, values, interpolation ) {
+
+		super( name, times, values, interpolation );
+
+	}
+
+}
+
+/**
+ * The value type name.
+ *
+ * @type {string}
+ * @default 'color'
+ */
 ColorKeyframeTrack.prototype.ValueTypeName = 'color';
 // ValueBufferType is inherited
 // DefaultInterpolation is inherited
 
-// Note: Very basic implementation and nothing special yet.
-// However, this is the place for color space parameterization.
-
 export { ColorKeyframeTrack };

package/src/animation/tracks/NumberKeyframeTrack.js

@@ -1,10 +1,34 @@
 import { KeyframeTrack } from '../KeyframeTrack.js';
 
 /**
- * A Track of numeric keyframe values.
+ * A track for numeric keyframe values.
+ *
+ * @augments KeyframeTrack
  */
-class NumberKeyframeTrack extends KeyframeTrack {}
+class NumberKeyframeTrack extends KeyframeTrack {
 
+	/**
+	 * Constructs a new number keyframe track.
+	 *
+	 * @param {string} name - The keyframe track's name.
+	 * @param {Array<number>} times - A list of keyframe times.
+	 * @param {Array<number>} values - A list of keyframe values.
+	 * @param {(InterpolateLinear|InterpolateDiscrete|InterpolateSmooth)} [interpolation] - The interpolation type.
+	 */
+	constructor( name, times, values, interpolation ) {
+
+		super( name, times, values, interpolation );
+
+	}
+
+}
+
+/**
+ * The value type name.
+ *
+ * @type {string}
+ * @default 'number'
+ */
 NumberKeyframeTrack.prototype.ValueTypeName = 'number';
 // ValueBufferType is inherited
 // DefaultInterpolation is inherited

package/src/animation/tracks/QuaternionKeyframeTrack.js

@@ -2,10 +2,33 @@ import { KeyframeTrack } from '../KeyframeTrack.js';
 import { QuaternionLinearInterpolant } from '../../math/interpolants/QuaternionLinearInterpolant.js';
 
 /**
- * A Track of quaternion keyframe values.
+ * A track for Quaternion keyframe values.
+ *
+ * @augments KeyframeTrack
  */
 class QuaternionKeyframeTrack extends KeyframeTrack {
 
+	/**
+	 * Constructs a new Quaternion keyframe track.
+	 *
+	 * @param {string} name - The keyframe track's name.
+	 * @param {Array<number>} times - A list of keyframe times.
+	 * @param {Array<number>} values - A list of keyframe values.
+	 * @param {(InterpolateLinear|InterpolateDiscrete|InterpolateSmooth)} [interpolation] - The interpolation type.
+	 */
+	constructor( name, times, values, interpolation ) {
+
+		super( name, times, values, interpolation );
+
+	}
+
+	/**
+	 * Overwritten so the method returns Quaternion based interpolant.
+	 *
+	 * @static
+	 * @param {TypedArray} [result] - The result buffer.
+	 * @return {QuaternionLinearInterpolant} The new interpolant.
+	 */
 	InterpolantFactoryMethodLinear( result ) {
 
 		return new QuaternionLinearInterpolant( this.times, this.values, this.getValueSize(), result );
@@ -14,6 +37,12 @@ class QuaternionKeyframeTrack extends KeyframeTrack {
 
 }
 
+/**
+ * The value type name.
+ *
+ * @type {string}
+ * @default 'quaternion'
+ */
 QuaternionKeyframeTrack.prototype.ValueTypeName = 'quaternion';
 // ValueBufferType is inherited
 // DefaultInterpolation is inherited;

package/src/animation/tracks/StringKeyframeTrack.js

@@ -2,11 +2,22 @@ import { InterpolateDiscrete } from '../../constants.js';
 import { KeyframeTrack } from '../KeyframeTrack.js';
 
 /**
- * A Track that interpolates Strings
+ * A track for string keyframe values.
+ *
+ * @augments KeyframeTrack
  */
 class StringKeyframeTrack extends KeyframeTrack {
 
-	// No interpolation parameter because only InterpolateDiscrete is valid.
+	/**
+	 * Constructs a new string keyframe track.
+	 *
+	 * This keyframe track type has no `interpolation` parameter because the
+	 * interpolation is always discrete.
+	 *
+	 * @param {string} name - The keyframe track's name.
+	 * @param {Array<number>} times - A list of keyframe times.
+	 * @param {Array<string>} values - A list of keyframe values.
+	 */
 	constructor( name, times, values ) {
 
 		super( name, times, values );
@@ -15,8 +26,28 @@ class StringKeyframeTrack extends KeyframeTrack {
 
 }
 
+/**
+ * The value type name.
+ *
+ * @type {string}
+ * @default 'string'
+ */
 StringKeyframeTrack.prototype.ValueTypeName = 'string';
+
+/**
+ * The value buffer type of this keyframe track.
+ *
+ * @type {TypedArray|Array}
+ * @default Array.constructor
+ */
 StringKeyframeTrack.prototype.ValueBufferType = Array;
+
+/**
+ * The default interpolation type of this keyframe track.
+ *
+ * @type {(InterpolateLinear|InterpolateDiscrete|InterpolateSmooth)}
+ * @default InterpolateDiscrete
+ */
 StringKeyframeTrack.prototype.DefaultInterpolation = InterpolateDiscrete;
 StringKeyframeTrack.prototype.InterpolantFactoryMethodLinear = undefined;
 StringKeyframeTrack.prototype.InterpolantFactoryMethodSmooth = undefined;

package/src/animation/tracks/VectorKeyframeTrack.js

@@ -1,10 +1,34 @@
 import { KeyframeTrack } from '../KeyframeTrack.js';
 
 /**
- * A Track of vectored keyframe values.
+ * A track for vector keyframe values.
+ *
+ * @augments KeyframeTrack
  */
-class VectorKeyframeTrack extends KeyframeTrack {}
+class VectorKeyframeTrack extends KeyframeTrack {
 
+	/**
+	 * Constructs a new vector keyframe track.
+	 *
+	 * @param {string} name - The keyframe track's name.
+	 * @param {Array<number>} times - A list of keyframe times.
+	 * @param {Array<number>} values - A list of keyframe values.
+	 * @param {(InterpolateLinear|InterpolateDiscrete|InterpolateSmooth)} [interpolation] - The interpolation type.
+	 */
+	constructor( name, times, values, interpolation ) {
+
+		super( name, times, values, interpolation );
+
+	}
+
+}
+
+/**
+ * The value type name.
+ *
+ * @type {string}
+ * @default 'vector'
+ */
 VectorKeyframeTrack.prototype.ValueTypeName = 'vector';
 // ValueBufferType is inherited
 // DefaultInterpolation is inherited