@plastic-software/three 0.174.0 → 0.175.0

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 );

package/examples/jsm/utils/ShadowMapViewerGPU.js

@@ -16,30 +16,25 @@ import { texture } from 'three/tsl';
  * 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 WebGPURenderer}. When using {@link WebGLRenderer},
+ * import the class from `ShadowMapViewer.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
@@ -106,11 +101,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,
@@ -127,7 +132,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 {{width:number,height:number}}
+		 * @default true
+		 */
 		this.position = {
 			x: frame.x,
 			y: frame.y,
@@ -146,6 +157,11 @@ class ShadowMapViewer {
 			}
 		};
 
+		/**
+		 * Renders the viewer. This method must be called in the app's animation loop.
+		 *
+		 * @param {WebGPURenderer} renderer - The renderer.
+		 */
 		this.render = function ( renderer ) {
 
 			if ( this.enabled ) {
@@ -167,6 +183,10 @@ class ShadowMapViewer {
 
 		};
 
+		/**
+		 * Resizes the viewer. This method should be called whenever the app's
+		 * window is resized.
+		 */
 		this.updateForWindowResize = function () {
 
 			if ( this.enabled ) {
@@ -183,6 +203,9 @@ class ShadowMapViewer {
 
 		};
 
+		/**
+		 * Updates the viewer.
+		 */
 		this.update = function () {
 
 			this.position.set( this.position.x, this.position.y );

package/examples/jsm/utils/SkeletonUtils.js

@@ -9,6 +9,8 @@ import {
 	VectorKeyframeTrack
 } from 'three';
 
+/** @module SkeletonUtils */
+
 function getBoneName( bone, options ) {
 
 	if ( options.getBoneName !== undefined ) {
@@ -21,6 +23,14 @@ function getBoneName( bone, options ) {
 
 }
 
+/**
+ * Retargets the skeleton from the given source 3D object to the
+ * target 3D object.
+ *
+ * @param {Object3D} target - The target 3D object.
+ * @param {Object3D} source - The source 3D object.
+ * @param {module:SkeletonUtils~RetargetOptions} options - The options.
+ */
 function retarget( target, source, options = {} ) {
 
 	const quat = new Quaternion(),
@@ -196,6 +206,16 @@ function retarget( target, source, options = {} ) {
 
 }
 
+/**
+ * Retargets the animation clip of the source object to the
+ * target 3D object.
+ *
+ * @param {Object3D} target - The target 3D object.
+ * @param {Object3D} source - The source 3D object.
+ * @param {AnimationClip} clip - The animation clip.
+ * @param {module:SkeletonUtils~RetargetOptions} options - The options.
+ * @return {AnimationClip} The retargeted animation clip.
+ */
 function retargetClip( target, source, clip, options = {} ) {
 
 	options.useFirstFramePosition = options.useFirstFramePosition !== undefined ? options.useFirstFramePosition : false;
@@ -354,6 +374,14 @@ function retargetClip( target, source, clip, options = {} ) {
 
 }
 
+/**
+ * Clones the given 3D object and its descendants, ensuring that any `SkinnedMesh` instances are
+ * correctly associated with their bones. Bones are also cloned, and must be descendants of the
+ * object passed to this method. Other data, like geometries and materials, are reused by reference.
+ *
+ * @param {Object3D} source - The 3D object to clone.
+ * @return {Object3D} The cloned 3D object.
+ */
 function clone( source ) {
 
 	const sourceLookup = new Map();
@@ -435,6 +463,23 @@ function parallelTraverse( a, b, callback ) {
 
 }
 
+/**
+ * Retarget options of `SkeletonUtils`.
+ *
+ * @typedef {Object} module:SkeletonUtils~RetargetOptions
+ * @property {boolean} [useFirstFramePosition=false] - Whether to use the position of the first frame or not.
+ * @property {number} [fps] - The FPS of the clip.
+ * @property {Object<string,string>} [names] - A dictionary for mapping target to source bone names.
+ * @property {function(string):string} [getBoneName] - A function for mapping bone names. Alternative to `names`.
+ * @property {Array<number>} [trim] - Whether to trim the clip or not. If set the array should hold two values for the start and end.
+ * @property {boolean} [preserveBoneMatrix=true] - Whether to preserve bone matrices or not.
+ * @property {boolean} [preserveBonePositions=true] - Whether to preserve bone positions or not.
+ * @property {boolean} [useTargetMatrix=false] - Whether to use the target matrix or not.
+ * @property {string} [hip='hip'] - The name of the source's hip bone.
+ * @property {Vector3} [hipInfluence=(1,1,1)] - The hip influence.
+ * @property {number} [scale=1] - The scale.
+ **/
+
 export {
 	retarget,
 	retargetClip,

package/examples/jsm/utils/SortUtils.js

@@ -1,8 +1,5 @@
-// Hybrid radix sort from
-// - https://gist.github.com/sciecode/93ed864dd77c5c8803c6a86698d68dab
-// - https://github.com/mrdoob/three.js/pull/27202#issuecomment-1817640271
-//
-// expects unsigned 32b integer values
+
+/** @module SortUtils */
 
 const POWER = 3;
 const BIT_MAX = 32;
@@ -24,6 +21,18 @@ for ( let i = 0; i < ( ITERATIONS + 1 ); i ++ ) {
 
 const defaultGet = ( el ) => el;
 
+/**
+ * Hybrid radix sort from.
+ *
+ * - {@link https://gist.github.com/sciecode/93ed864dd77c5c8803c6a86698d68dab}
+ * - {@link https://github.com/mrdoob/three.js/pull/27202#issuecomment-1817640271}
+ *
+ * Expects unsigned 32b integer values.
+ *
+ * @function
+ * @param {Array<Object>} arr - The array to sort.
+ * @param {Object} opt - The options
+ */
 export const radixSort = ( arr, opt ) => {
 
 	const len = arr.length;

package/examples/jsm/utils/UVsDebug.js

@@ -2,14 +2,19 @@ import {
 	Vector2
 } from 'three';
 
+/** @module UVsDebug */
+
 /**
- * tool for "unwrapping" and debugging three.js geometries UV mapping
+ * Function for "unwrapping" and debugging three.js geometries UV mapping.
  *
- * Sample usage:
- *	document.body.appendChild( UVsDebug( new THREE.SphereGeometry( 10, 10, 10, 10 ) ) );
+ * ```js
+ * document.body.appendChild( UVsDebug( new THREE.SphereGeometry() ) );
+ * ```
  *
+ * @param {BufferGeometry} geometry - The geometry whose uv coordinates should be inspected.
+ * @param {number} [size=1024] - The size of the debug canvas.
+ * @return {HTMLCanvasElement} A canvas element with visualized uv coordinates.
  */
-
 function UVsDebug( geometry, size = 1024 ) {
 
 	// handles wrapping of uv.x > 1 only

package/examples/jsm/utils/WebGLTextureUtils.js

@@ -10,11 +10,24 @@ import {
 	SRGBColorSpace
 } from 'three';
 
+/** @module WebGLTextureUtils */
+
 let _renderer;
 let fullscreenQuadGeometry;
 let fullscreenQuadMaterial;
 let fullscreenQuad;
 
+/**
+ * Returns an uncompressed version of the given compressed texture.
+ *
+ * This module can only be used with {@link WebGLRenderer}. When using {@link WebGPURenderer},
+ * import the function from {@link WebGPUTextureUtils}.
+ *
+ * @param {CompressedTexture} texture - The compressed texture.
+ * @param {number} [maxTextureSize=Infinity] - The maximum size of the uncompressed texture.
+ * @param {?WebGLRenderer} [renderer=null] - A reference to a renderer.
+ * @return {CanvasTexture} The uncompressed texture.
+ */
 export function decompress( texture, maxTextureSize = Infinity, renderer = null ) {
 
 	if ( ! fullscreenQuadGeometry ) fullscreenQuadGeometry = new PlaneGeometry( 2, 2, 1, 1 );

package/examples/jsm/utils/WebGPUTextureUtils.js

@@ -6,9 +6,23 @@ import {
 } from 'three';
 import { texture, uv } from 'three/tsl';
 
+/** @module WebGPUTextureUtils */
+
 let _renderer;
 const _quadMesh = /*@__PURE__*/ new QuadMesh();
 
+/**
+ * Returns an uncompressed version of the given compressed texture.
+ *
+ * This module can only be used with {@link WebGPURenderer}. When using {@link WebGLRenderer},
+ * import the function from {@link WebGLTextureUtils}.
+ *
+ * @async
+ * @param {CompressedTexture} blitTexture - The compressed texture.
+ * @param {number} [maxTextureSize=Infinity] - The maximum size of the uncompressed texture.
+ * @param {?WebGPURenderer} [renderer=null] - A reference to a renderer.
+ * @return {Promise<CanvasTexture>} A Promise that resolved with the uncompressed texture.
+ */
 export async function decompress( blitTexture, maxTextureSize = Infinity, renderer = null ) {
 
 	if ( renderer === null ) {

package/examples/jsm/utils/WorkerPool.js

@@ -1,17 +1,58 @@
 /**
- * @author Deepkolos / https://github.com/deepkolos
+ * A simple pool for managing Web Workers.
  */
-
 export class WorkerPool {
 
+	/**
+	 * Constructs a new Worker pool.
+	 *
+	 * @param {number} [pool=4] - The size of the pool.
+	 */
 	constructor( pool = 4 ) {
 
+		/**
+		 * The size of the pool.
+		 *
+		 * @type {number}
+		 * @default 4
+		 */
 		this.pool = pool;
+
+		/**
+		 * A message queue.
+		 *
+		 * @type {Array<Object>}
+		 */
 		this.queue = [];
+
+		/**
+		 * An array of Workers.
+		 *
+		 * @type {Array<Worker>}
+		 */
 		this.workers = [];
+
+		/**
+		 * An array with resolve functions for messages.
+		 *
+		 * @type {Array<Function>}
+		 */
 		this.workersResolve = [];
+
+		/**
+		 * The current worker status.
+		 *
+		 * @type {number}
+		 */
 		this.workerStatus = 0;
 
+		/**
+		 * A factory function for creating workers.
+		 *
+		 * @type {?Function}
+		 */
+		this.workerCreator = null;
+
 	}
 
 	_initWorker( workerId ) {
@@ -54,18 +95,36 @@ export class WorkerPool {
 
 	}
 
+	/**
+	 * Sets a function that is responsible for creating Workers.
+	 *
+	 * @param {Function} workerCreator - The worker creator function.
+	 */
 	setWorkerCreator( workerCreator ) {
 
 		this.workerCreator = workerCreator;
 
 	}
 
+	/**
+	 * Sets the Worker limit
+	 *
+	 * @param {number} pool - The size of the pool.
+	 */
 	setWorkerLimit( pool ) {
 
 		this.pool = pool;
 
 	}
 
+	/**
+	 * Post a message to an idle Worker. If no Worker is available,
+	 * the message is pushed into a message queue for later processing.
+	 *
+	 * @param {Object} msg - The message.
+	 * @param {Array<ArrayBuffer>} transfer - An array with array buffers for data transfer.
+	 * @return {Promise} A Promise that resolves when the message has been processed.
+	 */
 	postMessage( msg, transfer ) {
 
 		return new Promise( ( resolve ) => {
@@ -89,6 +148,10 @@ export class WorkerPool {
 
 	}
 
+	/**
+	 * Terminates all Workers of this pool. Call this  method whenever this
+	 * Worker pool is no longer used in your app.
+	 */
 	dispose() {
 
 		this.workers.forEach( ( worker ) => worker.terminate() );

package/examples/jsm/webxr/ARButton.js

@@ -1,5 +1,23 @@
+/**
+ * A utility class for creating a button that allows to initiate
+ * immersive AR sessions based on WebXR. The button can be created
+ * with a factory method and then appended ot the website's DOM.
+ *
+ * ```js
+ * document.body.appendChild( ARButton.createButton( renderer ) );
+ * ```
+ *
+ * @hideconstructor
+ */
 class ARButton {
 
+	/**
+	 * Constructs a new AR button.
+	 *
+	 * @param {WebGLRenderer|WebGPURenderer} renderer - The renderer.
+	 * @param {XRSessionInit} [sessionInit] - The a configuration object for the AR session.
+	 * @return {HTMLElement} The button or an error message if `immersive-ar` isn't supported.
+	 */
 	static createButton( renderer, sessionInit = {} ) {
 
 		const button = document.createElement( 'button' );