super-three 0.173.5 → 0.176.0

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

package/examples/jsm/webxr/OculusHandModel.js

@@ -4,18 +4,77 @@ import { XRHandMeshModel } from './XRHandMeshModel.js';
 const TOUCH_RADIUS = 0.01;
 const POINTING_JOINT = 'index-finger-tip';
 
+/**
+ * Represents an Oculus hand model.
+ *
+ * @augments Object3D
+ */
 class OculusHandModel extends Object3D {
 
+	/**
+	 * Constructs a new Oculus hand model.
+	 *
+	 * @param {Group} controller - The hand controller.
+	 * @param {?Loader} [loader=null] - A loader that is used to load hand models.
+	 * @param {?Function} [onLoad=null] - A callback that is executed when a hand model has been loaded.
+	 */
 	constructor( controller, loader = null, onLoad = null ) {
 
 		super();
 
+		/**
+		 * The hand controller.
+		 *
+		 * @type {Group}
+		 */
 		this.controller = controller;
+
+		/**
+		 * The motion controller.
+		 *
+		 * @type {?MotionController}
+		 * @default null
+		 */
 		this.motionController = null;
+
+		/**
+		 * The model's environment map.
+		 *
+		 * @type {?Texture}
+		 * @default null
+		 */
 		this.envMap = null;
+
+		/**
+		 * A loader that is used to load hand models.
+		 *
+		 * @type {?Loader}
+		 * @default null
+		 */
 		this.loader = loader;
+
+		/**
+		 * A callback that is executed when a hand model has been loaded.
+		 *
+		 * @type {?Function}
+		 * @default null
+		 */
 		this.onLoad = onLoad;
 
+		/**
+		 * The path to the model repository.
+		 *
+		 * @type {?string}
+		 * @default null
+		 */
+		this.path = null;
+
+		/**
+		 * The model mesh.
+		 *
+		 * @type {Mesh}
+		 * @default null
+		 */
 		this.mesh = null;
 
 		controller.addEventListener( 'connected', ( event ) => {
@@ -41,6 +100,12 @@ class OculusHandModel extends Object3D {
 
 	}
 
+	/**
+	 * Overwritten with a custom implementation. Makes sure the motion controller updates the mesh.
+	 *
+	 * @param {boolean} [force=false] - When set to `true`, a recomputation of world matrices is forced even
+	 * when {@link Object3D#matrixWorldAutoUpdate} is set to `false`.
+	 */
 	updateMatrixWorld( force ) {
 
 		super.updateMatrixWorld( force );
@@ -53,6 +118,11 @@ class OculusHandModel extends Object3D {
 
 	}
 
+	/**
+	 * Returns the pointer position which is the position of the index finger tip.
+	 *
+	 * @return {Vector3|null} The pointer position. Returns `null` if not index finger tip joint was found.
+	 */
 	getPointerPosition() {
 
 		const indexFingerTip = this.controller.joints[ POINTING_JOINT ];
@@ -68,6 +138,13 @@ class OculusHandModel extends Object3D {
 
 	}
 
+	/**
+	 * Returns `true` if the current pointer position (the index finger tip) intersections
+	 * with the given box object.
+	 *
+	 *  @param {Mesh} boxObject - The box object.
+	 * @return {boolean} Whether an intersection was found or not.
+	 */
 	intersectBoxObject( boxObject ) {
 
 		const pointerPosition = this.getPointerPosition();
@@ -85,6 +162,12 @@ class OculusHandModel extends Object3D {
 
 	}
 
+	/**
+	 * Executed actions depending on the interaction state with
+	 * the given button.
+	 *
+	 *  @param {Object} button - The button.
+	 */
 	checkButton( button ) {
 
 		if ( this.intersectBoxObject( button ) ) {