@plastic-software/three 0.167.3 → 0.174.0

package/src/core/RenderTarget.js

@@ -54,6 +54,7 @@ class RenderTarget extends EventDispatcher {
 
 			this.textures[ i ] = texture.clone();
 			this.textures[ i ].isRenderTargetTexture = true;
+			this.textures[ i ].renderTarget = this;
 
 		}
 
@@ -63,6 +64,7 @@ class RenderTarget extends EventDispatcher {
 		this.resolveDepthBuffer = options.resolveDepthBuffer;
 		this.resolveStencilBuffer = options.resolveStencilBuffer;
 
+		this._depthTexture = null;
 		this.depthTexture = options.depthTexture;
 
 		this.samples = options.samples;
@@ -81,6 +83,21 @@ class RenderTarget extends EventDispatcher {
 
 	}
 
+	set depthTexture( current ) {
+
+		if ( this._depthTexture !== null ) this._depthTexture.renderTarget = null;
+		if ( current !== null ) current.renderTarget = this;
+
+		this._depthTexture = current;
+
+	}
+
+	get depthTexture() {
+
+		return this._depthTexture;
+
+	}
+
 	setSize( width, height, depth = 1 ) {
 
 		if ( this.width !== width || this.height !== height || this.depth !== depth ) {
@@ -129,13 +146,14 @@ class RenderTarget extends EventDispatcher {
 
 			this.textures[ i ] = source.textures[ i ].clone();
 			this.textures[ i ].isRenderTargetTexture = true;
+			this.textures[ i ].renderTarget = this;
 
-		}
+			// ensure image object is not shared, see #20328
 
-		// ensure image object is not shared, see #20328
+			const image = Object.assign( {}, source.textures[ i ].image );
+			this.textures[ i ].source = new Source( image );
 
-		const image = Object.assign( {}, source.texture.image );
-		this.texture.source = new Source( image );
+		}
 
 		this.depthBuffer = source.depthBuffer;
 		this.stencilBuffer = source.stencilBuffer;

package/src/core/RenderTarget3D.js

@@ -0,0 +1,22 @@
+import { RenderTarget } from './RenderTarget.js';
+import { Data3DTexture } from '../textures/Data3DTexture.js';
+
+class RenderTarget3D extends RenderTarget {
+
+	constructor( width = 1, height = 1, depth = 1, options = {} ) {
+
+		super( width, height, options );
+
+		this.isRenderTarget3D = true;
+
+		this.depth = depth;
+
+		this.texture = new Data3DTexture( null, width, height, depth );
+
+		this.texture.isRenderTargetTexture = true;
+
+	}
+
+}
+
+export { RenderTarget3D };

package/src/core/RenderTargetArray.js

@@ -0,0 +1,22 @@
+import { RenderTarget } from './RenderTarget.js';
+import { DataArrayTexture } from '../textures/DataArrayTexture.js';
+
+class RenderTargetArray extends RenderTarget {
+
+	constructor( width = 1, height = 1, depth = 1, options = {} ) {
+
+		super( width, height, options );
+
+		this.isRenderTargetArray = true;
+
+		this.depth = depth;
+
+		this.texture = new DataArrayTexture( null, width, height, depth );
+
+		this.texture.isRenderTargetTexture = true;
+
+	}
+
+}
+
+export { RenderTargetArray };

package/src/extras/Controls.js

@@ -0,0 +1,104 @@
+import { EventDispatcher } from '../core/EventDispatcher.js';
+
+/**
+ * Abstract base class for controls.
+ *
+ * @abstract
+ * @augments EventDispatcher
+ */
+class Controls extends EventDispatcher {
+
+	/**
+	 * Constructs a new controls instance.
+	 *
+	 * @param {Object3D} object - The object that is managed by the controls.
+	 * @param {?HTMLDOMElement} domElement - The HTML element used for event listeners.
+	 */
+	constructor( object, domElement = null ) {
+
+		super();
+
+		/**
+		 * The object that is managed by the controls.
+		 *
+		 * @type {Object3D}
+		 */
+		this.object = object;
+
+		/**
+		 * The HTML element used for event listeners.
+		 *
+		 * @type {?HTMLDOMElement}
+		 * @default null
+		 */
+		this.domElement = domElement;
+
+		/**
+		 * Whether the controls responds to user input or not.
+		 *
+		 * @type {boolean}
+		 * @default true
+		 */
+		this.enabled = true;
+
+		/**
+		 * The internal state of the controls.
+		 *
+		 * @type {number}
+		 * @default -1
+		 */
+		this.state = - 1;
+
+		/**
+		 * This object defines the keyboard input of the controls.
+		 *
+		 * @type {Object}
+		 */
+		this.keys = {};
+
+		/**
+		 * This object defines what type of actions are assigned to the available mouse buttons.
+		 * It depends on the control implementation what kind of mouse buttons and actions are supported.
+		 *
+		 * @type {{LEFT: ?number, MIDDLE: ?number, RIGHT: ?number}}
+		 */
+		this.mouseButtons = { LEFT: null, MIDDLE: null, RIGHT: null };
+
+		/**
+		 * This object defines what type of actions are assigned to what kind of touch interaction.
+		 * It depends on the control implementation what kind of touch interaction and actions are supported.
+		 *
+		 * @type {{ONE: ?number, TWO: ?number}}
+		 */
+		this.touches = { ONE: null, TWO: null };
+
+	}
+
+	/**
+	 * Connects the controls to the DOM. This method has so called "side effects" since
+	 * it adds the module's event listeners to the DOM.
+	 */
+	connect() {}
+
+	/**
+	 * Disconnects the controls from the DOM.
+	 */
+	disconnect() {}
+
+	/**
+	 * Call this method if you no longer want use to the controls. It frees all internal
+	 * resources and removes all event listeners.
+	 */
+	dispose() {}
+
+	/**
+	 * Controls should implement this method if they have to update their internal state
+	 * per simulation step.
+	 *
+	 * @param {number} [delta] - The time delta in seconds.
+	 */
+	update( /* delta */ ) {}
+
+}
+
+export { Controls };

package/src/extras/DataUtils.js

@@ -139,8 +139,13 @@ function _generateTables() {
 
 }
 
-// float32 to float16
-
+/**
+ * Returns a half precision floating point value (FP16) from the given single
+ * precision floating point value (FP32).
+ *
+ * @param {number} val - A single precision floating point value.
+ * @return {number} The FP16 value.
+ */
 function toHalfFloat( val ) {
 
 	if ( Math.abs( val ) > 65504 ) console.warn( 'THREE.DataUtils.toHalfFloat(): Value out of range.' );
@@ -154,8 +159,13 @@ function toHalfFloat( val ) {
 
 }
 
-// float16 to float32
-
+/**
+ * Returns a single precision floating point value (FP32) from the given half
+ * precision floating point value (FP16).
+ *
+ * @param {number} val - A half precision floating point value.
+ * @return {number} The FP32 value.
+ */
 function fromHalfFloat( val ) {
 
 	const m = val >> 10;
@@ -164,10 +174,40 @@ function fromHalfFloat( val ) {
 
 }
 
-const DataUtils = {
-	toHalfFloat: toHalfFloat,
-	fromHalfFloat: fromHalfFloat,
-};
+/**
+ * A class containing utility functions for data.
+ *
+ * @hideconstructor
+ */
+class DataUtils {
+
+	/**
+	 * Returns a half precision floating point value (FP16) from the given single
+	 * precision floating point value (FP32).
+	 *
+	 * @param {number} val - A single precision floating point value.
+	 * @return {number} The FP16 value.
+	 */
+	static toHalfFloat( val ) {
+
+		return toHalfFloat( val );
+
+	}
+
+	/**
+	 * Returns a single precision floating point value (FP32) from the given half
+	 * precision floating point value (FP16).
+	 *
+	 * @param {number} val - A half precision floating point value.
+	 * @return {number} The FP32 value.
+	 */
+	static fromHalfFloat( val ) {
+
+		return fromHalfFloat( val );
+
+	}
+
+}
 
 export {
 	toHalfFloat,

package/src/extras/Earcut.js

@@ -1,10 +1,21 @@
 /**
- * Port from https://github.com/mapbox/earcut (v2.2.4)
+ * An implementation of the earcut polygon triangulation algorithm. The code
+ * is a port of [mapbox/earcut]{@link https://github.com/mapbox/earcut mapbox/earcut} (v2.2.4).
+ *
+ * @hideconstructor
  */
-
-const Earcut = {
-
-	triangulate: function ( data, holeIndices, dim = 2 ) {
+class Earcut {
+
+	/**
+	 * Triangulates the given shape definition by returning an array of triangles.
+	 *
+	 * @param {Array<number>} data - An array with 2D points.
+	 * @param {Array<number>} holeIndices - An array with indices defining holes.
+	 * @param {number} [dim=2] - The number of coordinates per vertex in the input array.
+	 * @return {Array<number>} An array representing the triangulated faces. Each face is defined by three consecutive numbers
+	 * representing vertex indices.
+	 */
+	static triangulate( data, holeIndices, dim = 2 ) {
 
 		const hasHoles = holeIndices && holeIndices.length;
 		const outerLen = hasHoles ? holeIndices[ 0 ] * dim : data.length;
@@ -46,7 +57,7 @@ const Earcut = {
 
 	}
 
-};
+}
 
 // create a circular doubly linked list from polygon points in the specified winding order
 function linkedList( data, start, end, dim, clockwise ) {
@@ -591,7 +602,7 @@ function pointInTriangle( ax, ay, bx, by, cx, cy, px, py ) {
 // check if a diagonal between two polygon nodes is valid (lies in polygon interior)
 function isValidDiagonal( a, b ) {
 
-	return a.next.i !== b.i && a.prev.i !== b.i && ! intersectsPolygon( a, b ) && // dones't intersect other edges
+	return a.next.i !== b.i && a.prev.i !== b.i && ! intersectsPolygon( a, b ) && // doesn't intersect other edges
            ( locallyInside( a, b ) && locallyInside( b, a ) && middleInside( a, b ) && // locally visible
             ( area( a.prev, a, b.prev ) || area( a, b.prev, b ) ) || // does not create opposite-facing sectors
             equals( a, b ) && area( a.prev, a, a.next ) > 0 && area( b.prev, b, b.next ) > 0 ); // special zero-length case

package/src/extras/ImageUtils.js

@@ -3,8 +3,19 @@ import { SRGBToLinear } from '../math/ColorManagement.js';
 
 let _canvas;
 
+/**
+ * A class containing utility functions for images.
+ *
+ * @hideconstructor
+ */
 class ImageUtils {
 
+	/**
+	 * Returns a data URI containing a representation of the given image.
+	 *
+	 * @param {(HTMLImageElement|HTMLCanvasElement)} image - The image object.
+	 * @return {string} The data URI.
+	 */
 	static getDataURL( image ) {
 
 		if ( /^data:/i.test( image.src ) ) {
@@ -48,20 +59,16 @@ class ImageUtils {
 
 		}
 
-		if ( canvas.width > 2048 || canvas.height > 2048 ) {
-
-			console.warn( 'THREE.ImageUtils.getDataURL: Image converted to jpg for performance reasons', image );
-
-			return canvas.toDataURL( 'image/jpeg', 0.6 );
-
-		} else {
-
-			return canvas.toDataURL( 'image/png' );
-
-		}
+		return canvas.toDataURL( 'image/png' );
 
 	}
 
+	/**
+	 * Converts the given sRGB image data to linear color space.
+	 *
+	 * @param {(HTMLImageElement|HTMLCanvasElement|ImageBitmap|Object)} image - The image object.
+	 * @return {HTMLCanvasElement|Object} The converted image.
+	 */
 	static sRGBToLinear( image ) {
 
 		if ( ( typeof HTMLImageElement !== 'undefined' && image instanceof HTMLImageElement ) ||

package/src/extras/PMREMGenerator.js

@@ -60,6 +60,8 @@ const _axisDirections = [
 	/*@__PURE__*/ new Vector3( - 1, 1, 1 ),
 	/*@__PURE__*/ new Vector3( 1, 1, 1 ) ];
 
+const _origin = /*@__PURE__*/ new Vector3();
+
 /**
  * This class generates a Prefiltered, Mipmapped Radiance Environment Map
  * (PMREM) from a cubeMap environment texture. This allows different levels of
@@ -100,10 +102,21 @@ class PMREMGenerator {
 	 * Generates a PMREM from a supplied Scene, which can be faster than using an
 	 * image if networking bandwidth is low. Optional sigma specifies a blur radius
 	 * in radians to be applied to the scene before PMREM generation. Optional near
-	 * and far planes ensure the scene is rendered in its entirety (the cubeCamera
-	 * is placed at the origin).
+	 * and far planes ensure the scene is rendered in its entirety.
+	 *
+	 * @param {Scene} scene
+	 * @param {number} sigma
+	 * @param {number} near
+	 * @param {number} far
+	 * @param {Object} [options={}]
+	 * @return {WebGLRenderTarget}
 	 */
-	fromScene( scene, sigma = 0, near = 0.1, far = 100 ) {
+	fromScene( scene, sigma = 0, near = 0.1, far = 100, options = {} ) {
+
+		const {
+			size = 256,
+			position = _origin,
+		} = options;
 
 		_oldTarget = this._renderer.getRenderTarget();
 		_oldActiveCubeFace = this._renderer.getActiveCubeFace();
@@ -112,12 +125,12 @@ class PMREMGenerator {
 
 		this._renderer.xr.enabled = false;
 
-		this._setSize( 256 );
+		this._setSize( size );
 
 		const cubeUVRenderTarget = this._allocateTargets();
 		cubeUVRenderTarget.depthBuffer = true;
 
-		this._sceneToCubeUV( scene, near, far, cubeUVRenderTarget );
+		this._sceneToCubeUV( scene, near, far, cubeUVRenderTarget, position );
 
 		if ( sigma > 0 ) {
 
@@ -137,6 +150,10 @@ class PMREMGenerator {
 	 * or HDR. The ideal input image size is 1k (1024 x 512),
 	 * as this matches best with the 256 x 256 cubemap output.
 	 * The smallest supported equirectangular image size is 64 x 32.
+	 *
+	 * @param {Texture} equirectangular
+	 * @param {?WebGLRenderTarget} [renderTarget=null] - Optional render target.
+	 * @return {WebGLRenderTarget}
 	 */
 	fromEquirectangular( equirectangular, renderTarget = null ) {
 
@@ -149,6 +166,10 @@ class PMREMGenerator {
 	 * or HDR. The ideal input cube size is 256 x 256,
 	 * as this matches best with the 256 x 256 cubemap output.
 	 * The smallest supported cube size is 16 x 16.
+	 *
+	 * @param {Texture} cubemap
+	 * @param {null} [renderTarget=null] - Optional render target.
+	 * @return {WebGLRenderTarget}
 	 */
 	fromCubemap( cubemap, renderTarget = null ) {
 
@@ -306,7 +327,7 @@ class PMREMGenerator {
 
 	}
 
-	_sceneToCubeUV( scene, near, far, cubeUVRenderTarget ) {
+	_sceneToCubeUV( scene, near, far, cubeUVRenderTarget, position ) {
 
 		const fov = 90;
 		const aspect = 1;
@@ -358,17 +379,21 @@ class PMREMGenerator {
 			if ( col === 0 ) {
 
 				cubeCamera.up.set( 0, upSign[ i ], 0 );
-				cubeCamera.lookAt( forwardSign[ i ], 0, 0 );
+				cubeCamera.position.set( position.x, position.y, position.z );
+				cubeCamera.lookAt( position.x + forwardSign[ i ], position.y, position.z );
 
 			} else if ( col === 1 ) {
 
 				cubeCamera.up.set( 0, 0, upSign[ i ] );
-				cubeCamera.lookAt( 0, forwardSign[ i ], 0 );
+				cubeCamera.position.set( position.x, position.y, position.z );
+				cubeCamera.lookAt( position.x, position.y + forwardSign[ i ], position.z );
+
 
 			} else {
 
 				cubeCamera.up.set( 0, upSign[ i ], 0 );
-				cubeCamera.lookAt( 0, 0, forwardSign[ i ] );
+				cubeCamera.position.set( position.x, position.y, position.z );
+				cubeCamera.lookAt( position.x, position.y, position.z + forwardSign[ i ] );
 
 			}
 
@@ -466,6 +491,12 @@ class PMREMGenerator {
 	 * the blur latitudinally (around the poles), and then longitudinally (towards
 	 * the poles) to approximate the orthogonally-separable blur. It is least
 	 * accurate at the poles, but still does a decent job.
+	 *
+	 * @param {WebGLRenderTarget} cubeUVRenderTarget
+	 * @param {number} lodIn
+	 * @param {number} lodOut
+	 * @param {number} sigma
+	 * @param {Vector3} [poleAxis]
 	 */
 	_blur( cubeUVRenderTarget, lodIn, lodOut, sigma, poleAxis ) {
 

package/src/extras/ShapeUtils.js

@@ -1,9 +1,18 @@
 import { Earcut } from './Earcut.js';
 
+/**
+ * A class containing utility functions for shapes.
+ *
+ * @hideconstructor
+ */
 class ShapeUtils {
 
-	// calculate area of the contour polygon
-
+	/**
+	 * Calculate area of a ( 2D ) contour polygon.
+	 *
+	 * @param {Array<Vector2>} contour - An array of 2D points.
+	 * @return {number} The area.
+	 */
 	static area( contour ) {
 
 		const n = contour.length;
@@ -19,12 +28,25 @@ class ShapeUtils {
 
 	}
 
+	/**
+	 * Returns `true` if the given contour uses a clockwise winding order.
+	 *
+	 * @param {Array<Vector2>} pts - An array of 2D points defining a polygon.
+	 * @return {boolean} Whether the given contour uses a clockwise winding order or not.
+	 */
 	static isClockWise( pts ) {
 
 		return ShapeUtils.area( pts ) < 0;
 
 	}
 
+	/**
+	 * Triangulates the given shape definition.
+	 *
+	 * @param {Array<Vector2>} contour - An array of 2D points defining the contour.
+	 * @param {Array<Array<Vector2>>} holes - An array that holds arrays of 2D points defining the holes.
+	 * @return {Array<Array<number>>} An array that holds for each face definition an array with three indices.
+	 */
 	static triangulateShape( contour, holes ) {
 
 		const vertices = []; // flat array of vertices like [ x0,y0, x1,y1, x2,y2, ... ]

package/src/extras/TextureUtils.js

@@ -1,5 +1,14 @@
 import { AlphaFormat, LuminanceFormat, LuminanceAlphaFormat, RedFormat, RedIntegerFormat, RGFormat, RGIntegerFormat, RGBFormat, RGBAFormat, RGBAIntegerFormat, RGB_S3TC_DXT1_Format, RGBA_S3TC_DXT1_Format, RGBA_S3TC_DXT3_Format, RGBA_S3TC_DXT5_Format, RGB_PVRTC_2BPPV1_Format, RGBA_PVRTC_2BPPV1_Format, RGB_PVRTC_4BPPV1_Format, RGBA_PVRTC_4BPPV1_Format, RGB_ETC1_Format, RGB_ETC2_Format, RGBA_ETC2_EAC_Format, RGBA_ASTC_4x4_Format, RGBA_ASTC_5x4_Format, RGBA_ASTC_5x5_Format, RGBA_ASTC_6x5_Format, RGBA_ASTC_6x6_Format, RGBA_ASTC_8x5_Format, RGBA_ASTC_8x6_Format, RGBA_ASTC_8x8_Format, RGBA_ASTC_10x5_Format, RGBA_ASTC_10x6_Format, RGBA_ASTC_10x8_Format, RGBA_ASTC_10x10_Format, RGBA_ASTC_12x10_Format, RGBA_ASTC_12x12_Format, RGBA_BPTC_Format, RGB_BPTC_SIGNED_Format, RGB_BPTC_UNSIGNED_Format, RED_RGTC1_Format, SIGNED_RED_RGTC1_Format, RED_GREEN_RGTC2_Format, SIGNED_RED_GREEN_RGTC2_Format, UnsignedByteType, ByteType, UnsignedShortType, ShortType, HalfFloatType, UnsignedShort4444Type, UnsignedShort5551Type, UnsignedIntType, IntType, FloatType, UnsignedInt5999Type } from '../constants.js';
 
+/**
+ * Scales the texture as large as possible within its surface without cropping
+ * or stretching the texture. The method preserves the original aspect ratio of
+ * the texture. Akin to CSS `object-fit: contain`
+ *
+ * @param {Texture} texture - The texture.
+ * @param {number} aspect - The texture's aspect ratio.
+ * @return {Texture} The updated texture.
+ */
 function contain( texture, aspect ) {
 
 	const imageAspect = ( texture.image && texture.image.width ) ? texture.image.width / texture.image.height : 1;
@@ -26,6 +35,15 @@ function contain( texture, aspect ) {
 
 }
 
+/**
+ * Scales the texture to the smallest possible size to fill the surface, leaving
+ * no empty space. The method preserves the original aspect ratio of the texture.
+ * Akin to CSS `object-fit: cover`.
+ *
+ * @param {Texture} texture - The texture.
+ * @param {number} aspect - The texture's aspect ratio.
+ * @return {Texture} The updated texture.
+ */
 function cover( texture, aspect ) {
 
 	const imageAspect = ( texture.image && texture.image.width ) ? texture.image.width / texture.image.height : 1;
@@ -52,6 +70,12 @@ function cover( texture, aspect ) {
 
 }
 
+/**
+ * Configures the texture to the default transformation. Akin to CSS `object-fit: fill`.
+ *
+ * @param {Texture} texture - The texture.
+ * @return {Texture} The updated texture.
+ */
 function fill( texture ) {
 
 	texture.repeat.x = 1;
@@ -64,11 +88,14 @@ function fill( texture ) {
 
 }
 
-
-
 /**
- * Given the width, height, format, and type of a texture. Determines how many
- * bytes must be used to represent the texture.
+ * Determines how many bytes must be used to represent the texture.
+ *
+ * @param {number} width - The width of the texture.
+ * @param {number} height - The height of the texture.
+ * @param {number} format - The texture's format.
+ * @param {number} type - The texture's type.
+ * @return {number} The byte length.
  */
 function getByteLength( width, height, format, type ) {
 
@@ -200,11 +227,70 @@ function getTextureTypeByteLength( type ) {
 
 }
 
-const TextureUtils = {
-	contain,
-	cover,
-	fill,
-	getByteLength
-};
+/**
+ * A class containing utility functions for textures.
+ *
+ * @hideconstructor
+ */
+class TextureUtils {
+
+	/**
+	 * Scales the texture as large as possible within its surface without cropping
+	 * or stretching the texture. The method preserves the original aspect ratio of
+	 * the texture. Akin to CSS `object-fit: contain`
+	 *
+	 * @param {Texture} texture - The texture.
+	 * @param {number} aspect - The texture's aspect ratio.
+	 * @return {Texture} The updated texture.
+	 */
+	static contain( texture, aspect ) {
+
+		return contain( texture, aspect );
+
+	}
+
+	/**
+	 * Scales the texture to the smallest possible size to fill the surface, leaving
+	 * no empty space. The method preserves the original aspect ratio of the texture.
+	 * Akin to CSS `object-fit: cover`.
+	 *
+	 * @param {Texture} texture - The texture.
+	 * @param {number} aspect - The texture's aspect ratio.
+	 * @return {Texture} The updated texture.
+	 */
+	static cover( texture, aspect ) {
+
+		return cover( texture, aspect );
+
+	}
+
+	/**
+	 * Configures the texture to the default transformation. Akin to CSS `object-fit: fill`.
+	 *
+	 * @param {Texture} texture - The texture.
+	 * @return {Texture} The updated texture.
+	 */
+	static fill( texture ) {
+
+		return fill( texture );
+
+	}
+
+	/**
+	 * Determines how many bytes must be used to represent the texture.
+	 *
+	 * @param {number} width - The width of the texture.
+	 * @param {number} height - The height of the texture.
+	 * @param {number} format - The texture's format.
+	 * @param {number} type - The texture's type.
+	 * @return {number} The byte length.
+	 */
+	static getByteLength( width, height, format, type ) {
+
+		return getByteLength( width, height, format, type );
+
+	}
+
+}
 
 export { contain, cover, fill, getByteLength, TextureUtils };