super-three 0.181.0 → 0.185.0

package/src/math/FrustumArray.js

@@ -3,7 +3,6 @@ import { Frustum } from './Frustum.js';
 import { Matrix4 } from './Matrix4.js';
 
 const _projScreenMatrix = /*@__PURE__*/ new Matrix4();
-const _frustum = /*@__PURE__*/ new Frustum();
 
 /**
  * FrustumArray is used to determine if an object is visible in at least one camera
@@ -25,220 +24,191 @@ class FrustumArray {
 		 */
 		this.coordinateSystem = WebGLCoordinateSystem;
 
+		/**
+		 * A pool of frustum instances. It may hold more entries than are
+		 * currently in use; surplus instances are kept for reuse to avoid
+		 * reallocating when array cameras of different lengths are rendered.
+		 *
+		 * @private
+		 * @type {Array<Frustum>}
+		 */
+		this._frustums = [];
+
+		/**
+		 * The number of frustums in {@link FrustumArray#_frustums} that are currently
+		 * in use.
+		 *
+		 * @private
+		 * @type {number}
+		 * @default 0
+		 */
+		this._count = 0;
+
 	}
 
 	/**
-	 * Returns `true` if the 3D object's bounding sphere is intersecting any frustum
-	 * from the camera array.
+	 * Computes and caches a frustum for each camera of the given array camera.
 	 *
-	 * @param {Object3D} object - The 3D object to test.
-	 * @param {Object} cameraArray - An object with a cameras property containing an array of cameras.
-	 * @return {boolean} Whether the 3D object is visible in any camera.
+	 * @param {ArrayCamera} cameraArray - The array camera whose sub-cameras define the frustums.
+	 * @return {FrustumArray} A reference to this frustum array.
 	 */
-	intersectsObject( object, cameraArray ) {
-
-		if ( ! cameraArray.isArrayCamera || cameraArray.cameras.length === 0 ) {
-
-			return false;
-
-		}
+	setFromArrayCamera( cameraArray ) {
 
-		for ( let i = 0; i < cameraArray.cameras.length; i ++ ) {
+		const cameras = cameraArray.cameras;
+		const frustums = this._frustums;
 
-			const camera = cameraArray.cameras[ i ];
+		for ( let i = 0; i < cameras.length; i ++ ) {
 
-			_projScreenMatrix.multiplyMatrices(
-				camera.projectionMatrix,
-				camera.matrixWorldInverse
-			);
+			const camera = cameras[ i ];
 
-			_frustum.setFromProjectionMatrix(
-				_projScreenMatrix,
-				camera.coordinateSystem,
-				camera.reversedDepth
-			);
+			_projScreenMatrix.multiplyMatrices( camera.projectionMatrix, camera.matrixWorldInverse );
 
-			if ( _frustum.intersectsObject( object ) ) {
+			if ( frustums[ i ] === undefined ) frustums[ i ] = new Frustum();
 
-				return true; // Object is visible in at least one camera
-
-			}
+			frustums[ i ].setFromProjectionMatrix( _projScreenMatrix, camera.coordinateSystem, camera.reversedDepth );
 
 		}
 
-		return false; // Not visible in any camera
+		this._count = cameras.length;
+
+		return this;
 
 	}
 
 	/**
-	 * Returns `true` if the given sprite is intersecting any frustum
-	 * from the camera array.
+	 * Returns `true` if the 3D object's bounding sphere is intersecting any cached frustum.
 	 *
-	 * @param {Sprite} sprite - The sprite to test.
-	 * @param {Object} cameraArray - An object with a cameras property containing an array of cameras.
-	 * @return {boolean} Whether the sprite is visible in any camera.
+	 * {@link FrustumArray#setFromArrayCamera} must be called once per render before this method.
+	 *
+	 * @param {Object3D} object - The 3D object to test.
+	 * @return {boolean} Whether the 3D object is visible in any camera.
 	 */
-	intersectsSprite( sprite, cameraArray ) {
+	intersectsObject( object ) {
 
-		if ( ! cameraArray || ! cameraArray.cameras || cameraArray.cameras.length === 0 ) {
+		const frustums = this._frustums;
 
-			return false;
+		for ( let i = 0; i < this._count; i ++ ) {
 
-		}
+			if ( frustums[ i ].intersectsObject( object ) ) return true;
 
-		for ( let i = 0; i < cameraArray.cameras.length; i ++ ) {
+		}
 
-			const camera = cameraArray.cameras[ i ];
+		return false;
 
-			_projScreenMatrix.multiplyMatrices(
-				camera.projectionMatrix,
-				camera.matrixWorldInverse
-			);
+	}
 
-			_frustum.setFromProjectionMatrix(
-				_projScreenMatrix,
-				camera.coordinateSystem,
-				camera.reversedDepth
-			);
+	/**
+	 * Returns `true` if the given sprite is intersecting any cached frustum.
+	 *
+	 * {@link FrustumArray#setFromArrayCamera} must be called once per render before this method.
+	 *
+	 * @param {Sprite} sprite - The sprite to test.
+	 * @return {boolean} Whether the sprite is visible in any camera.
+	 */
+	intersectsSprite( sprite ) {
 
-			if ( _frustum.intersectsSprite( sprite ) ) {
+		const frustums = this._frustums;
 
-				return true; // Sprite is visible in at least one camera
+		for ( let i = 0; i < this._count; i ++ ) {
 
-			}
+			if ( frustums[ i ].intersectsSprite( sprite ) ) return true;
 
 		}
 
-		return false; // Not visible in any camera
+		return false;
 
 	}
 
 	/**
-	 * Returns `true` if the given bounding sphere is intersecting any frustum
-	 * from the camera array.
+	 * Returns `true` if the given bounding sphere is intersecting any cached frustum.
+	 *
+	 * {@link FrustumArray#setFromArrayCamera} must be called once per render before this method.
 	 *
 	 * @param {Sphere} sphere - The bounding sphere to test.
-	 * @param {Object} cameraArray - An object with a cameras property containing an array of cameras.
 	 * @return {boolean} Whether the sphere is visible in any camera.
 	 */
-	intersectsSphere( sphere, cameraArray ) {
-
-		if ( ! cameraArray || ! cameraArray.cameras || cameraArray.cameras.length === 0 ) {
-
-			return false;
-
-		}
+	intersectsSphere( sphere ) {
 
-		for ( let i = 0; i < cameraArray.cameras.length; i ++ ) {
+		const frustums = this._frustums;
 
-			const camera = cameraArray.cameras[ i ];
+		for ( let i = 0; i < this._count; i ++ ) {
 
-			_projScreenMatrix.multiplyMatrices(
-				camera.projectionMatrix,
-				camera.matrixWorldInverse
-			);
-
-			_frustum.setFromProjectionMatrix(
-				_projScreenMatrix,
-				camera.coordinateSystem,
-				camera.reversedDepth
-			);
-
-			if ( _frustum.intersectsSphere( sphere ) ) {
-
-				return true; // Sphere is visible in at least one camera
-
-			}
+			if ( frustums[ i ].intersectsSphere( sphere ) ) return true;
 
 		}
 
-		return false; // Not visible in any camera
+		return false;
 
 	}
 
 	/**
-	 * Returns `true` if the given bounding box is intersecting any frustum
-	 * from the camera array.
+	 * Returns `true` if the given bounding box is intersecting any cached frustum.
+	 *
+	 * {@link FrustumArray#setFromArrayCamera} must be called once per render before this method.
 	 *
 	 * @param {Box3} box - The bounding box to test.
-	 * @param {Object} cameraArray - An object with a cameras property containing an array of cameras.
 	 * @return {boolean} Whether the box is visible in any camera.
 	 */
-	intersectsBox( box, cameraArray ) {
-
-		if ( ! cameraArray || ! cameraArray.cameras || cameraArray.cameras.length === 0 ) {
-
-			return false;
+	intersectsBox( box ) {
 
-		}
-
-		for ( let i = 0; i < cameraArray.cameras.length; i ++ ) {
-
-			const camera = cameraArray.cameras[ i ];
-
-			_projScreenMatrix.multiplyMatrices(
-				camera.projectionMatrix,
-				camera.matrixWorldInverse
-			);
+		const frustums = this._frustums;
 
-			_frustum.setFromProjectionMatrix(
-				_projScreenMatrix,
-				camera.coordinateSystem,
-				camera.reversedDepth
-			);
+		for ( let i = 0; i < this._count; i ++ ) {
 
-			if ( _frustum.intersectsBox( box ) ) {
-
-				return true; // Box is visible in at least one camera
-
-			}
+			if ( frustums[ i ].intersectsBox( box ) ) return true;
 
 		}
 
-		return false; // Not visible in any camera
+		return false;
 
 	}
 
 	/**
-	 * Returns `true` if the given point lies within any frustum
-	 * from the camera array.
+	 * Returns `true` if the given point lies within any cached frustum.
+	 *
+	 * {@link FrustumArray#setFromArrayCamera} must be called once per render before this method.
 	 *
 	 * @param {Vector3} point - The point to test.
-	 * @param {Object} cameraArray - An object with a cameras property containing an array of cameras.
 	 * @return {boolean} Whether the point is visible in any camera.
 	 */
-	containsPoint( point, cameraArray ) {
+	containsPoint( point ) {
 
-		if ( ! cameraArray || ! cameraArray.cameras || cameraArray.cameras.length === 0 ) {
+		const frustums = this._frustums;
 
-			return false;
+		for ( let i = 0; i < this._count; i ++ ) {
+
+			if ( frustums[ i ].containsPoint( point ) ) return true;
 
 		}
 
-		for ( let i = 0; i < cameraArray.cameras.length; i ++ ) {
+		return false;
 
-			const camera = cameraArray.cameras[ i ];
+	}
 
-			_projScreenMatrix.multiplyMatrices(
-				camera.projectionMatrix,
-				camera.matrixWorldInverse
-			);
+	/**
+	 * Copies the values of the given frustum array to this instance.
+	 *
+	 * @param {FrustumArray} frustumArray - The frustum array to copy.
+	 * @return {FrustumArray} A reference to this frustum array.
+	 */
+	copy( source ) {
+
+		this.coordinateSystem = source.coordinateSystem;
 
-			_frustum.setFromProjectionMatrix(
-				_projScreenMatrix,
-				camera.coordinateSystem,
-				camera.reversedDepth
-			);
+		const frustums = this._frustums;
+		const sourceFrustums = source._frustums;
 
-			if ( _frustum.containsPoint( point ) ) {
+		for ( let i = 0; i < source._count; i ++ ) {
 
-				return true; // Point is visible in at least one camera
+			if ( frustums[ i ] === undefined ) frustums[ i ] = new Frustum();
 
-			}
+			frustums[ i ].copy( sourceFrustums[ i ] );
 
 		}
 
-		return false; // Not visible in any camera
+		this._count = source._count;
+
+		return this;
 
 	}
 
@@ -249,7 +219,7 @@ class FrustumArray {
 	 */
 	clone() {
 
-		return new FrustumArray();
+		return new FrustumArray().copy( this );
 
 	}
 

package/src/math/Interpolant.js

@@ -297,7 +297,7 @@ class Interpolant {
 	 */
 	interpolate_( /* i1, t0, t, t1 */ ) {
 
-		throw new Error( 'call to abstract method' );
+		throw new Error( 'THREE.Interpolant: Call to abstract method.' );
 		// implementations shall return this.resultBuffer
 
 	}

package/src/math/Line3.js

@@ -142,6 +142,9 @@ class Line3 {
 		_startEnd.subVectors( this.end, this.start );
 
 		const startEnd2 = _startEnd.dot( _startEnd );
+
+		if ( startEnd2 === 0 ) return 0;
+
 		const startEnd_startP = _startEnd.dot( _startP );
 
 		let t = startEnd_startP / startEnd2;
@@ -284,12 +287,10 @@ class Line3 {
 
 		}
 
-		c1.copy( p1 ).add( _d1.multiplyScalar( s ) );
-		c2.copy( p2 ).add( _d2.multiplyScalar( t ) );
-
-		c1.sub( c2 );
+		c1.copy( p1 ).addScaledVector( _d1, s );
+		c2.copy( p2 ).addScaledVector( _d2, t );
 
-		return c1.dot( c1 );
+		return c1.distanceToSquared( c2 );
 
 	}
 

package/src/math/MathUtils.js

@@ -64,7 +64,7 @@ function euclideanModulo( n, m ) {
 
 /**
  * Performs a linear mapping from range `<a1, a2>` to range `<b1, b2>`
- * for the given value.
+ * for the given value. `a2` must be greater than `a1`.
  *
  * @param {number} x - The value to be mapped.
  * @param {number} a1 - Minimum value for range A.
@@ -159,9 +159,9 @@ function pingpong( x, length = 1 ) {
  *
  * See [Smoothstep](http://en.wikipedia.org/wiki/Smoothstep) for more details.
  *
- * @param {number} x - The value to evaluate based on its position between min and max.
- * @param {number} min - The min value. Any x value below min will be `0`.
- * @param {number} max - The max value. Any x value above max will be `1`.
+ * @param {number} x - The value to evaluate based on its position between `min` and `max`.
+ * @param {number} min - The min value. Any `x` value below `min` will be `0`. `min` must be lower than `max`.
+ * @param {number} max - The max value. Any `x` value above `max` will be `1`. `max` must be greater than `min`.
  * @return {number} The alternated value.
  */
 function smoothstep( x, min, max ) {
@@ -177,11 +177,11 @@ function smoothstep( x, min, max ) {
 
 /**
  * A [variation on smoothstep](https://en.wikipedia.org/wiki/Smoothstep#Variations)
- * that has zero 1st and 2nd order derivatives at x=0 and x=1.
+ * that has zero 1st and 2nd order derivatives at `x=0` and `x=1`.
  *
- * @param {number} x - The value to evaluate based on its position between min and max.
- * @param {number} min - The min value. Any x value below min will be `0`.
- * @param {number} max - The max value. Any x value above max will be `1`.
+ * @param {number} x - The value to evaluate based on its position between `min` and `max`.
+ * @param {number} min - The min value. Any `x` value below `min` will be `0`. `min` must be lower than `max`.
+ * @param {number} max - The max value. Any `x` value above `max` will be `1`. `max` must be greater than `min`.
  * @return {number} The alternated value.
  */
 function smootherstep( x, min, max ) {
@@ -294,7 +294,7 @@ function isPowerOfTwo( value ) {
 /**
  * Returns the smallest power of two that is greater than or equal to the given number.
  *
- * @param {number} value - The value to find a POT for.
+ * @param {number} value - The value to find a POT for. Must be greater than `0`.
  * @return {number} The smallest power of two that is greater than or equal to the given number.
  */
 function ceilPowerOfTwo( value ) {
@@ -306,7 +306,7 @@ function ceilPowerOfTwo( value ) {
 /**
  * Returns the largest power of two that is less than or equal to the given number.
  *
- * @param {number} value - The value to find a POT for.
+ * @param {number} value - The value to find a POT for. Must be greater than `0`.
  * @return {number} The largest power of two that is less than or equal to the given number.
  */
 function floorPowerOfTwo( value ) {
@@ -419,7 +419,7 @@ function denormalize( value, array ) {
 
 		default:
 
-			throw new Error( 'Invalid component type.' );
+			throw new Error( 'THREE.MathUtils: Invalid component type.' );
 
 	}
 
@@ -466,7 +466,7 @@ function normalize( value, array ) {
 
 		default:
 
-			throw new Error( 'Invalid component type.' );
+			throw new Error( 'THREE.MathUtils: Invalid component type.' );
 
 	}
 

package/src/math/Matrix2.js

@@ -26,6 +26,19 @@
  */
 export class Matrix2 {
 
+	static {
+
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
+		Matrix2.prototype.isMatrix2 = true;
+
+	}
+
 	/**
 	 * Constructs a new 2x2 matrix. The arguments are supposed to be
 	 * in row-major order. If no arguments are provided, the constructor
@@ -38,15 +51,6 @@ export class Matrix2 {
 	 */
 	constructor( n11, n12, n21, n22 ) {
 
-		/**
-		 * This flag can be used for type testing.
-		 *
-		 * @type {boolean}
-		 * @readonly
-		 * @default true
-		 */
-		Matrix2.prototype.isMatrix2 = true;
-
 		/**
 		 * A column-major list of matrix values.
 		 *

package/src/math/Matrix3.js

@@ -1,3 +1,5 @@
+import { warnOnce } from '../utils.js';
+
 /**
  * Represents a 3x3 matrix.
  *
@@ -28,6 +30,19 @@
  */
 class Matrix3 {
 
+	static {
+
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
+		Matrix3.prototype.isMatrix3 = true;
+
+	}
+
 	/**
 	 * Constructs a new 3x3 matrix. The arguments are supposed to be
 	 * in row-major order. If no arguments are provided, the constructor
@@ -45,15 +60,6 @@ class Matrix3 {
 	 */
 	constructor( n11, n12, n13, n21, n22, n23, n31, n32, n33 ) {
 
-		/**
-		 * This flag can be used for type testing.
-		 *
-		 * @type {boolean}
-		 * @readonly
-		 * @default true
-		 */
-		Matrix3.prototype.isMatrix3 = true;
-
 		/**
 		 * A column-major list of matrix values.
 		 *
@@ -403,12 +409,15 @@ class Matrix3 {
 	/**
 	 * Scales this matrix with the given scalar values.
 	 *
+	 * @deprecated
 	 * @param {number} sx - The amount to scale in the X axis.
 	 * @param {number} sy - The amount to scale in the Y axis.
 	 * @return {Matrix3} A reference to this matrix.
 	 */
 	scale( sx, sy ) {
 
+		warnOnce( 'Matrix3: .scale() is deprecated. Use .makeScale() instead.' ); // @deprecated r185
+
 		this.premultiply( _m3.makeScale( sx, sy ) );
 
 		return this;
@@ -418,11 +427,14 @@ class Matrix3 {
 	/**
 	 * Rotates this matrix by the given angle.
 	 *
+	 * @deprecated
 	 * @param {number} theta - The rotation in radians.
 	 * @return {Matrix3} A reference to this matrix.
 	 */
 	rotate( theta ) {
 
+		warnOnce( 'Matrix3: .rotate() is deprecated. Use .makeRotation() instead.' ); // @deprecated r185
+
 		this.premultiply( _m3.makeRotation( - theta ) );
 
 		return this;
@@ -432,12 +444,15 @@ class Matrix3 {
 	/**
 	 * Translates this matrix by the given scalar values.
 	 *
+	 * @deprecated
 	 * @param {number} tx - The amount to translate in the X axis.
 	 * @param {number} ty - The amount to translate in the Y axis.
 	 * @return {Matrix3} A reference to this matrix.
 	 */
 	translate( tx, ty ) {
 
+		warnOnce( 'Matrix3: .translate() is deprecated. Use .makeTranslation() instead.' ); // @deprecated r185
+
 		this.premultiply( _m3.makeTranslation( tx, ty ) );
 
 		return this;