super-three 0.173.5 → 0.175.0

package/examples/jsm/utils/GeometryCompressionUtils.js

@@ -1,10 +1,3 @@
-/**
- * Octahedron and Quantization encodings based on work by:
- *
- * @link https://github.com/tsherif/mesh-quantization-example
- *
- */
-
 import {
 	BufferAttribute,
 	Matrix3,
@@ -12,14 +5,15 @@ import {
 	Vector3
 } from 'three';
 
+/** @module GeometryCompressionUtils */
 
+// Octahedron and Quantization encodings based on work by: https://github.com/tsherif/mesh-quantization-example
 
 /**
- * Make the input geometry's normal attribute encoded and compressed by 3 different methods.
- *
- * @param {THREE.BufferGeometry} geometry
- * @param {String} encodeMethod		"DEFAULT" || "OCT1Byte" || "OCT2Byte" || "ANGLES"
+ * Compressed the given geometry's `normal` attribute by the selected encode method.
  *
+ * @param {BufferGeometry} geometry - The geometry whose normals should be compressed.
+ * @param {('DEFAULT'|'OCT1Byte'|'OCT2Byte'|'ANGLES')} encodeMethod - The compression method.
  */
 function compressNormals( geometry, encodeMethod ) {
 
@@ -27,7 +21,7 @@ function compressNormals( geometry, encodeMethod ) {
 
 	if ( ! normal ) {
 
-		console.error( 'Geometry must contain normal attribute. ' );
+		console.error( 'THREE.GeometryCompressionUtils.compressNormals(): Geometry must contain normal attribute.' );
 
 	}
 
@@ -35,7 +29,7 @@ function compressNormals( geometry, encodeMethod ) {
 
 	if ( normal.itemSize != 3 ) {
 
-		console.error( 'normal.itemSize is not 3, which cannot be encoded. ' );
+		console.error( 'THREE.GeometryCompressionUtils.compressNormals(): normal.itemSize is not 3, which cannot be encoded.' );
 
 	}
 
@@ -63,11 +57,10 @@ function compressNormals( geometry, encodeMethod ) {
 
 	} else if ( encodeMethod == 'OCT1Byte' ) {
 
-		/**
-		* It is not recommended to use 1-byte octahedron normals encoding unless you want to extremely reduce the memory usage
-		* As it makes vertex data not aligned to a 4 byte boundary which may harm some WebGL implementations and sometimes the normal distortion is visible
-		* Please refer to @zeux 's comments in https://github.com/mrdoob/three.js/pull/18208
-		*/
+
+		// It is not recommended to use 1-byte octahedron normals encoding unless you want to extremely reduce the memory usage
+		// As it makes vertex data not aligned to a 4 byte boundary which may harm some WebGL implementations and sometimes the normal distortion is visible
+		// Please refer to @zeux 's comments in https://github.com/mrdoob/three.js/pull/18208
 
 		result = new Int8Array( count * 2 );
 
@@ -127,20 +120,18 @@ function compressNormals( geometry, encodeMethod ) {
 
 }
 
-
 /**
-	 * Make the input geometry's position attribute encoded and compressed.
-	 *
-	 * @param {THREE.BufferGeometry} geometry
-	 *
-	 */
+ * Compressed the given geometry's `position` attribute.
+ *
+ * @param {BufferGeometry} geometry - The geometry whose position values should be compressed.
+ */
 function compressPositions( geometry ) {
 
 	const position = geometry.attributes.position;
 
 	if ( ! position ) {
 
-		console.error( 'Geometry must contain position attribute. ' );
+		console.error( 'THREE.GeometryCompressionUtils.compressPositions(): Geometry must contain position attribute.' );
 
 	}
 
@@ -148,7 +139,7 @@ function compressPositions( geometry ) {
 
 	if ( position.itemSize != 3 ) {
 
-		console.error( 'position.itemSize is not 3, which cannot be packed. ' );
+		console.error( 'THREE.GeometryCompressionUtils.compressPositions(): position.itemSize is not 3, which cannot be packed.' );
 
 	}
 
@@ -171,10 +162,9 @@ function compressPositions( geometry ) {
 }
 
 /**
- * Make the input geometry's uv attribute encoded and compressed.
- *
- * @param {THREE.BufferGeometry} geometry
+ * Compressed the given geometry's `uv` attribute.
  *
+ * @param {BufferGeometry} geometry - The geometry whose texture coordinates should be compressed.
  */
 function compressUvs( geometry ) {
 
@@ -182,7 +172,7 @@ function compressUvs( geometry ) {
 
 	if ( ! uvs ) {
 
-		console.error( 'Geometry must contain uv attribute. ' );
+		console.error( 'THREE.GeometryCompressionUtils.compressUvs(): Geometry must contain uv attribute.' );
 
 	}
 

package/examples/jsm/utils/GeometryUtils.js

@@ -1,20 +1,20 @@
 import { Vector3 } from 'three';
 
+/** @module GeometryUtils */
 
 /**
- * Generates 2D-Coordinates in a very fast way.
+ * Generates 2D-Coordinates along a Hilbert curve.
  *
- * Based on work by:
- * @link http://www.openprocessing.org/sketch/15493
+ * Based on work by: {@link http://www.openprocessing.org/sketch/15493}
  *
- * @param {Vector3} center - Center of Hilbert curve.
+ * @param {Vector3} [center] - Center of Hilbert curve.
  * @param {number} [size=10] - Total width of Hilbert curve.
  * @param {number} [iterations=10] - Number of subdivisions.
  * @param {number} [v0=0] - Corner index -X, -Z.
  * @param {number} [v1=1] - Corner index -X, +Z.
  * @param {number} [v2=2] - Corner index +X, +Z.
  * @param {number} [v3=3] - Corner index +X, -Z.
- * @returns {Array<Array<number>>} The Hilbert curve points.
+ * @returns {Array<Vector3>} The Hilbert curve points.
  */
 function hilbert2D( center = new Vector3( 0, 0, 0 ), size = 10, iterations = 1, v0 = 0, v1 = 1, v2 = 2, v3 = 3 ) {
 
@@ -52,12 +52,11 @@ function hilbert2D( center = new Vector3( 0, 0, 0 ), size = 10, iterations = 1,
 }
 
 /**
- * Generates 3D-Coordinates in a very fast way.
+ * Generates 3D-Coordinates along a Hilbert curve.
  *
- * Based on work by:
- * @link https://openprocessing.org/user/5654
+ * Based on work by: {@link https://openprocessing.org/user/5654}
  *
- * @param {Vector3} [center=new Vector3( 0, 0, 0 )] - Center of Hilbert curve.
+ * @param {Vector3} [center] - Center of Hilbert curve.
  * @param {number} [size=10] - Total width of Hilbert curve.
  * @param {number} [iterations=1] - Number of subdivisions.
  * @param {number} [v0=0] - Corner index -X, +Y, -Z.
@@ -68,7 +67,7 @@ function hilbert2D( center = new Vector3( 0, 0, 0 ), size = 10, iterations = 1,
  * @param {number} [v5=5] - Corner index +X, -Y, +Z.
  * @param {number} [v6=6] - Corner index +X, +Y, +Z.
  * @param {number} [v7=7] - Corner index +X, +Y, -Z.
- * @returns {Array<Array<number>>}  - The Hilbert curve points.
+ * @returns {Array<Vector3>}  - The Hilbert curve points.
  */
 function hilbert3D( center = new Vector3( 0, 0, 0 ), size = 10, iterations = 1, v0 = 0, v1 = 1, v2 = 2, v3 = 3, v4 = 4, v5 = 5, v6 = 6, v7 = 7 ) {
 
@@ -119,12 +118,12 @@ function hilbert3D( center = new Vector3( 0, 0, 0 ), size = 10, iterations = 1,
 }
 
 /**
- * Generates a Gosper curve (lying in the XY plane)
+ * Generates a Gosper curve (lying in the XY plane).
  *
- * https://gist.github.com/nitaku/6521802
+ * Reference: {@link https://gist.github.com/nitaku/6521802}
  *
  * @param {number} [size=1] - The size of a single gosper island.
- * @return {Array<[number, number, number]>} The gosper island points.
+ * @return {Array<number>} The gosper island points.
  */
 function gosper( size = 1 ) {
 

package/examples/jsm/utils/LDrawUtils.js

@@ -9,14 +9,21 @@ import {
 
 import { mergeGeometries } from './BufferGeometryUtils.js';
 
+/**
+ * Utility class for LDraw models.
+ */
 class LDrawUtils {
 
+	/**
+	 * Merges geometries in the given object by materials and returns a new group object.
+	 * Use on not indexed geometries. The object buffers reference the old object ones.
+	 * Special treatment is done to the conditional lines generated by LDrawLoader.
+	 *
+	 * @param {Object3D} object - The object to merge.
+	 * @returns {Group} The merged object.
+	 */
 	static mergeObject( object ) {
 
-		// Merges geometries in object by materials and returns new object. Use on not indexed geometries.
-		// The object buffers reference the old object ones.
-		// Special treatment is done to the conditional lines generated by LDrawLoader.
-
 		function extractGroup( geometry, group, elementSize, isConditionalLine ) {
 
 			// Extracts a group from a geometry as a new geometry (with attribute buffers referencing original buffers)

package/examples/jsm/utils/SceneOptimizer.js

@@ -1,7 +1,18 @@
 import * as THREE from 'three';
 
+/**
+ * This class can be used to optimized scenes by converting
+ * individual meshes into {@link BatchedMesh}. This component
+ * is an experimental attempt to implement auto-batching in three.js.
+ */
 class SceneOptimizer {
 
+	/**
+	 * Constructs a new scene optimizer.
+	 *
+	 * @param {Scene} scene - The scene to optimize.
+	 * @param {SceneOptimizer~Options} options - The configuration options.
+	 */
 	constructor( scene, options = {} ) {
 
 		this.scene = scene;
@@ -9,7 +20,7 @@ class SceneOptimizer {
 
 	}
 
-	bufferToHash( buffer ) {
+	_bufferToHash( buffer ) {
 
 		let hash = 0;
 		if ( buffer.byteLength !== 0 ) {
@@ -43,7 +54,7 @@ class SceneOptimizer {
 
 	}
 
-	getMaterialPropertiesHash( material ) {
+	_getMaterialPropertiesHash( material ) {
 
 		const mapProps = [
 			'map',
@@ -128,7 +139,7 @@ class SceneOptimizer {
 
 	}
 
-	getAttributesSignature( geometry ) {
+	_getAttributesSignature( geometry ) {
 
 		return Object.keys( geometry.attributes )
 			.sort()
@@ -142,24 +153,24 @@ class SceneOptimizer {
 
 	}
 
-	getGeometryHash( geometry ) {
+	_getGeometryHash( geometry ) {
 
 		const indexHash = geometry.index
-			? this.bufferToHash( geometry.index.array )
+			? this._bufferToHash( geometry.index.array )
 			: 'noIndex';
-		const positionHash = this.bufferToHash( geometry.attributes.position.array );
-		const attributesSignature = this.getAttributesSignature( geometry );
+		const positionHash = this._bufferToHash( geometry.attributes.position.array );
+		const attributesSignature = this._getAttributesSignature( geometry );
 		return `${indexHash}_${positionHash}_${attributesSignature}`;
 
 	}
 
-	getBatchKey( materialProps, attributesSignature ) {
+	_getBatchKey( materialProps, attributesSignature ) {
 
 		return `${materialProps}_${attributesSignature}`;
 
 	}
 
-	analyzeModel() {
+	_analyzeModel() {
 
 		const batchGroups = new Map();
 		const singleGroups = new Map();
@@ -170,10 +181,10 @@ class SceneOptimizer {
 
 			if ( ! node.isMesh ) return;
 
-			const materialProps = this.getMaterialPropertiesHash( node.material );
-			const attributesSignature = this.getAttributesSignature( node.geometry );
-			const batchKey = this.getBatchKey( materialProps, attributesSignature );
-			const geometryHash = this.getGeometryHash( node.geometry );
+			const materialProps = this._getMaterialPropertiesHash( node.material );
+			const attributesSignature = this._getAttributesSignature( node.geometry );
+			const batchKey = this._getBatchKey( materialProps, attributesSignature );
+			const geometryHash = this._getGeometryHash( node.geometry );
 			uniqueGeometries.add( geometryHash );
 
 			if ( ! batchGroups.has( batchKey ) ) {
@@ -222,7 +233,7 @@ class SceneOptimizer {
 
 	}
 
-	createBatchedMeshes( batchGroups ) {
+	_createBatchedMeshes( batchGroups ) {
 
 		const meshesToRemove = new Set();
 
@@ -269,7 +280,7 @@ class SceneOptimizer {
 
 			for ( const mesh of group.meshes ) {
 
-				const geometryHash = this.getGeometryHash( mesh.geometry );
+				const geometryHash = this._getGeometryHash( mesh.geometry );
 
 				if ( ! geometryIds.has( geometryHash ) ) {
 
@@ -308,6 +319,11 @@ class SceneOptimizer {
 
 	}
 
+	/**
+	 * Removes empty nodes from all descendants of the given 3D object.
+	 *
+	 * @param {Object3D} object - The 3D object to process.
+	 */
 	removeEmptyNodes( object ) {
 
 		const children = [ ...object.children ];
@@ -327,6 +343,11 @@ class SceneOptimizer {
 
 	}
 
+	/**
+	 * Removes the given array of meshes from the scene.
+	 *
+	 * @param {Set<Mesh>} meshesToRemove - The meshes to remove.
+	 */
 	disposeMeshes( meshesToRemove ) {
 
 		meshesToRemove.forEach( ( mesh ) => {
@@ -356,7 +377,7 @@ class SceneOptimizer {
 
 	}
 
-	logDebugInfo( stats ) {
+	_logDebugInfo( stats ) {
 
 		console.group( 'Scene Optimization Results' );
 		console.log( `Original meshes: ${stats.originalMeshes}` );
@@ -368,10 +389,18 @@ class SceneOptimizer {
 
 	}
 
+	/**
+	 * Performs the auto-baching by identifying groups of meshes in the scene
+	 * that can be represented as a single {@link BatchedMesh}. The method modifies
+	 * the scene by adding instances of `BatchedMesh` and removing the now redundant
+	 * individual meshes.
+	 *
+	 * @return {Scene} The optimized scene.
+	 */
 	toBatchedMesh() {
 
-		const { batchGroups, singleGroups, uniqueGeometries } = this.analyzeModel();
-		const meshesToRemove = this.createBatchedMeshes( batchGroups );
+		const { batchGroups, singleGroups, uniqueGeometries } = this._analyzeModel();
+		const meshesToRemove = this._createBatchedMeshes( batchGroups );
 
 		this.disposeMeshes( meshesToRemove );
 		this.removeEmptyNodes( this.scene );
@@ -390,7 +419,7 @@ class SceneOptimizer {
 				reductionRatio: ( ( 1 - totalFinalMeshes / totalOriginalMeshes ) * 100 ).toFixed( 1 ),
 			};
 
-			this.logDebugInfo( stats );
+			this._logDebugInfo( stats );
 
 		}
 
@@ -398,7 +427,17 @@ class SceneOptimizer {
 
 	}
 
-	// Placeholder for future implementation
+	/**
+	 * Performs the auto-instancing by identifying groups of meshes in the scene
+	 * that can be represented as a single {@link InstancedMesh}. The method modifies
+	 * the scene by adding instances of `InstancedMesh` and removing the now redundant
+	 * individual meshes.
+	 *
+	 * This method is not yet implemented.
+	 *
+	 * @abstract
+	 * @return {Scene} The optimized scene.
+	 */
 	toInstancingMesh() {
 
 		throw new Error( 'InstancedMesh optimization not implemented yet' );
@@ -407,4 +446,11 @@ class SceneOptimizer {
 
 }
 
+/**
+ * Constructor options of `SceneOptimizer`.
+ *
+ * @typedef {Object} SceneOptimizer~Options
+ * @property {boolean} [debug=false] - Whether to enable debug mode or not.
+ **/
+
 export { SceneOptimizer };

package/examples/jsm/utils/SceneUtils.js

@@ -10,9 +10,19 @@ import {
 
 import { mergeGroups, deepCloneAttribute } from './BufferGeometryUtils.js';
 
+/** @module SceneUtils */
+
 const _color = /*@__PURE__*/new Color();
 const _matrix = /*@__PURE__*/new Matrix4();
 
+/**
+ * This function creates a mesh for each instance of the given instanced mesh and
+ * adds it to a group. Each mesh will honor the current 3D transformation of its
+ * corresponding instance.
+ *
+ * @param {InstancedMesh} instancedMesh - The instanced mesh.
+ * @return {Group} A group of meshes.
+ */
 function createMeshesFromInstancedMesh( instancedMesh ) {
 
 	const group = new Group();
@@ -39,6 +49,13 @@ function createMeshesFromInstancedMesh( instancedMesh ) {
 
 }
 
+/**
+ * This function creates a mesh for each geometry-group of the given multi-material mesh and
+ * adds it to a group.
+ *
+ * @param {Mesh} mesh - The multi-material mesh.
+ * @return {Group} A group of meshes.
+ */
 function createMeshesFromMultiMaterialMesh( mesh ) {
 
 	if ( Array.isArray( mesh.material ) === false ) {
@@ -110,6 +127,16 @@ function createMeshesFromMultiMaterialMesh( mesh ) {
 
 }
 
+/**
+ * This function represents an alternative way to create 3D objects with multiple materials.
+ * Normally, {@link BufferGeometry#groups} are used which might introduce issues e.g. when
+ * exporting the object to a 3D format. This function accepts a geometry and an array of
+ * materials and creates for each material a mesh that is added to a group.
+ *
+ * @param {BufferGeometry} geometry - The geometry.
+ * @param {Array<Material>} materials - An array of materials.
+ * @return {Group} A group representing a multi-material object.
+ */
 function createMultiMaterialObject( geometry, materials ) {
 
 	const group = new Group();
@@ -124,6 +151,18 @@ function createMultiMaterialObject( geometry, materials ) {
 
 }
 
+
+/**
+ * Executes a reducer function for each vertex of the given 3D object.
+ * `reduceVertices()` returns a single value: the function's accumulated result.
+ *
+ * @param {Object3D} object - The 3D object that should be processed. It must have a
+ * geometry with a `position` attribute.
+ * @param {function(number,Vector3):number} func - The reducer function. First argument
+ * is the current value, second argument the current vertex.
+ * @param {any} initialValue - The initial value.
+ * @return {any} The result.
+ */
 function reduceVertices( object, func, initialValue ) {
 
 	let value = initialValue;
@@ -174,8 +213,10 @@ function reduceVertices( object, func, initialValue ) {
 }
 
 /**
- * @param {InstancedMesh} mesh
- * @param {function(int, int):int} compareFn
+ * Sorts the instances of the given instanced mesh.
+ *
+ * @param {InstancedMesh} mesh - The instanced mesh to sort.
+ * @param {function(number, number):number} compareFn - A custom compare function for the sort.
  */
 function sortInstancedMesh( mesh, compareFn ) {
 
@@ -246,7 +287,9 @@ function sortInstancedMesh( mesh, compareFn ) {
 }
 
 /**
- * @param {Object3D} object Object to traverse.
+ * Generator based alternative to {@link Object3D#traverse}.
+ *
+ * @param {Object3D} object - Object to traverse.
  * @yields {Object3D} Objects that passed the filter condition.
  */
 function* traverseGenerator( object ) {
@@ -264,6 +307,8 @@ function* traverseGenerator( object ) {
 }
 
 /**
+ * Generator based alternative to {@link Object3D#traverseVisible}.
+ *
  * @param {Object3D} object Object to traverse.
  * @yields {Object3D} Objects that passed the filter condition.
  */
@@ -284,6 +329,8 @@ function* traverseVisibleGenerator( object ) {
 }
 
 /**
+ * Generator based alternative to {@link Object3D#traverseAncestors}.
+ *
  * @param {Object3D} object Object to traverse.
  * @yields {Object3D} Objects that passed the filter condition.
  */

package/examples/jsm/utils/ShadowMapViewer.js

@@ -16,30 +16,25 @@ import { UnpackDepthRGBAShader } from '../shaders/UnpackDepthRGBAShader.js';
  * It works for shadow casting lights: DirectionalLight and SpotLight.
  * It renders out the shadow map and displays it on a HUD.
  *
- * Example usage:
- *	1) Import ShadowMapViewer into your app.
+ * This module can only be used with {@link WebGLRenderer}. When using {@link WebGPURenderer},
+ * import the class from `ShadowMapViewerGPU.js`.
  *
- *	2) Create a shadow casting light and name it optionally:
- *		let light = new DirectionalLight( 0xffffff, 1 );
- *		light.castShadow = true;
- *		light.name = 'Sun';
- *
- *	3) Create a shadow map viewer for that light and set its size and position optionally:
- *		let shadowMapViewer = new ShadowMapViewer( light );
- *		shadowMapViewer.size.set( 128, 128 );	//width, height  default: 256, 256
- *		shadowMapViewer.position.set( 10, 10 );	//x, y in pixel	 default: 0, 0 (top left corner)
- *
- *	4) Render the shadow map viewer in your render loop:
- *		shadowMapViewer.render( renderer );
- *
- *	5) Optionally: Update the shadow map viewer on window resize:
- *		shadowMapViewer.updateForWindowResize();
- *
- *	6) If you set the position or size members directly, you need to call shadowMapViewer.update();
+ * ```js
+ * const lightShadowMapViewer = new ShadowMapViewer( light );
+ * lightShadowMapViewer.position.x = 10;
+ * lightShadowMapViewer.position.y = SCREEN_HEIGHT - ( SHADOW_MAP_HEIGHT / 4 ) - 10;
+ * lightShadowMapViewer.size.width = SHADOW_MAP_WIDTH / 4;
+ * lightShadowMapViewer.size.height = SHADOW_MAP_HEIGHT / 4;
+ * lightShadowMapViewer.update();
+ * ```
  */
-
 class ShadowMapViewer {
 
+	/**
+	 * Constructs a new shadow map viewer.
+	 *
+	 * @param {Light} light - The shadow casting light.
+	 */
 	constructor( light ) {
 
 		//- Internals
@@ -110,11 +105,21 @@ class ShadowMapViewer {
 
 		}
 
-		//- API
-		// Set to false to disable displaying this shadow map
+		/**
+		 * Whether to display the shadow map viewer or not.
+		 *
+		 * @type {boolean}
+		 * @default true
+		 */
 		this.enabled = true;
 
-		// Set the size of the displayed shadow map on the HUD
+		/**
+		 * The size of the viewer. When changing this property, make sure
+		 * to call {@link ShadowMapViewer#update}.
+		 *
+		 * @type {{width:number,height:number}}
+		 * @default true
+		 */
 		this.size = {
 			width: frame.width,
 			height: frame.height,
@@ -131,7 +136,13 @@ class ShadowMapViewer {
 			}
 		};
 
-		// Set the position of the displayed shadow map on the HUD
+		/**
+		 * The position of the viewer. When changing this property, make sure
+		 * to call {@link ShadowMapViewer#update}.
+		 *
+		 * @type {{x:number,y:number, set:function(number,number)}}
+		 * @default true
+		 */
 		this.position = {
 			x: frame.x,
 			y: frame.y,
@@ -150,6 +161,11 @@ class ShadowMapViewer {
 			}
 		};
 
+		/**
+		 * Renders the viewer. This method must be called in the app's animation loop.
+		 *
+		 * @param {WebGLRenderer} renderer - The renderer.
+		 */
 		this.render = function ( renderer ) {
 
 			if ( this.enabled ) {
@@ -171,6 +187,10 @@ class ShadowMapViewer {
 
 		};
 
+		/**
+		 * Resizes the viewer. This method should be called whenever the app's
+		 * window is resized.
+		 */
 		this.updateForWindowResize = function () {
 
 			if ( this.enabled ) {
@@ -187,6 +207,9 @@ class ShadowMapViewer {
 
 		};
 
+		/**
+		 * Updates the viewer.
+		 */
 		this.update = function () {
 
 			this.position.set( this.position.x, this.position.y );