@plastic-software/three 0.174.0 → 0.175.0

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;
 
+		/**
+		 * TODO
+		 *
+		 * @type {number}
+		 * @default 0
+		 */
 		this.cumulativeWeight = 0;
+
+		/**
+		 * TODO
+		 *
+		 * @type {number}
+		 * @default 0
+		 */
 		this.cumulativeWeightAdditive = 0;
 
+		/**
+		 * TODO
+		 *
+		 * @type {number}
+		 * @default 0
+		 */
 		this.useCount = 0;
+
+		/**
+		 * TODO
+		 *
+		 * @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<number>} 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<number>} 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

package/src/audio/AudioAnalyser.js

@@ -31,7 +31,7 @@ class AudioAnalyser {
 	 * Constructs a new audio analyzer.
 	 *
 	 * @param {Audio} audio - The audio to analyze.
-	 * @param {Audio} [fftSize=2048] - The window size in samples that is used when performing a Fast Fourier Transform (FFT) to get frequency domain data.
+	 * @param {number} [fftSize=2048] - The window size in samples that is used when performing a Fast Fourier Transform (FFT) to get frequency domain data.
 	 */
 	constructor( audio, fftSize = 2048 ) {
 

package/src/audio/AudioListener.js

@@ -50,7 +50,7 @@ class AudioListener extends Object3D {
 		/**
 		 * An optional filter.
 		 *
-		 * Defined via {@AudioListener#setFilter}.
+		 * Defined via {@link AudioListener#setFilter}.
 		 *
 		 * @type {?AudioNode}
 		 * @default null
@@ -109,7 +109,7 @@ class AudioListener extends Object3D {
 	/**
 	 * Returns the current set filter.
 	 *
-	 * @return {AudioNode} The filter.
+	 * @return {?AudioNode} The filter.
 	 */
 	getFilter() {
 

package/src/audio/PositionalAudio.js

@@ -104,7 +104,7 @@ class PositionalAudio extends Audio {
 	 * starts taking effect.
 	 *
 	 * @param {number} value - The reference distance to set.
-	 * @return {Audio} A reference to this instance.
+	 * @return {PositionalAudio} A reference to this instance.
 	 */
 	setRefDistance( value ) {
 
@@ -129,7 +129,7 @@ class PositionalAudio extends Audio {
 	 * Defines how quickly the volume is reduced as the source moves away from the listener.
 	 *
 	 * @param {number} value - The rolloff factor.
-	 * @return {Audio} A reference to this instance.
+	 * @return {PositionalAudio} A reference to this instance.
 	 */
 	setRolloffFactor( value ) {
 
@@ -158,7 +158,7 @@ class PositionalAudio extends Audio {
 	 * for more details.
 	 *
 	 * @param {('linear'|'inverse'|'exponential')} value - The distance model to set.
-	 * @return {Audio} A reference to this instance.
+	 * @return {PositionalAudio} A reference to this instance.
 	 */
 	setDistanceModel( value ) {
 
@@ -186,7 +186,7 @@ class PositionalAudio extends Audio {
 	 * This value is used only by the `linear` distance model.
 	 *
 	 * @param {number} value - The max distance.
-	 * @return {Audio} A reference to this instance.
+	 * @return {PositionalAudio} A reference to this instance.
 	 */
 	setMaxDistance( value ) {
 
@@ -202,7 +202,7 @@ class PositionalAudio extends Audio {
 	 * @param {number} coneInnerAngle - An angle, in degrees, of a cone inside of which there will be no volume reduction.
 	 * @param {number} coneOuterAngle - An angle, in degrees, of a cone outside of which the volume will be reduced by a constant value, defined by the `coneOuterGain` parameter.
 	 * @param {number} coneOuterGain - The amount of volume reduction outside the cone defined by the `coneOuterAngle`. When set to `0`, no sound can be heard.
-	 * @return {Audio} A reference to this instance.
+	 * @return {PositionalAudio} A reference to this instance.
 	 */
 	setDirectionalCone( coneInnerAngle, coneOuterAngle, coneOuterGain ) {