@needle-tools/three 0.169.20-experimental.0 → 0.183.2-canary.0

package/examples/jsm/utils/ShadowMapViewer.js

@@ -6,40 +6,35 @@ import {
 	OrthographicCamera,
 	PlaneGeometry,
 	Scene,
-	ShaderMaterial,
-	UniformsUtils
+	ShaderMaterial
 } from 'three';
-import { UnpackDepthRGBAShader } from '../shaders/UnpackDepthRGBAShader.js';
 
 /**
  * This is a helper for visualising a given light's shadow map.
  * 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';
+ * ```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();
+ * ```
  *
- *	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();
+ * @three_import import { ShadowMapViewer } from 'three/addons/utils/ShadowMapViewer.js';
  */
-
 class ShadowMapViewer {
 
+	/**
+	 * Constructs a new shadow map viewer.
+	 *
+	 * @param {Light} light - The shadow casting light.
+	 */
 	constructor( light ) {
 
 		//- Internals
@@ -60,13 +55,29 @@ class ShadowMapViewer {
 		const scene = new Scene();
 
 		//HUD for shadow map
-		const shader = UnpackDepthRGBAShader;
-
-		const uniforms = UniformsUtils.clone( shader.uniforms );
 		const material = new ShaderMaterial( {
-			uniforms: uniforms,
-			vertexShader: shader.vertexShader,
-			fragmentShader: shader.fragmentShader
+			uniforms: {
+				tDiffuse: { value: null },
+				opacity: { value: 1.0 }
+			},
+			vertexShader: /* glsl */`
+				varying vec2 vUv;
+				void main() {
+					vUv = uv;
+					gl_Position = projectionMatrix * modelViewMatrix * vec4( position, 1.0 );
+				}`,
+			fragmentShader: /* glsl */`
+				uniform float opacity;
+				uniform sampler2D tDiffuse;
+				varying vec2 vUv;
+				void main() {
+					float depth = texture2D( tDiffuse, vUv ).r;
+					#ifdef USE_REVERSED_DEPTH_BUFFER
+						gl_FragColor = vec4( vec3( depth ), opacity );
+					#else
+						gl_FragColor = vec4( vec3( 1.0 - depth ), opacity );
+					#endif
+				}`
 		} );
 		const plane = new PlaneGeometry( frame.width, frame.height );
 		const mesh = new Mesh( plane, material );
@@ -110,11 +121,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 +152,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 +177,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 ) {
@@ -159,7 +191,7 @@ class ShadowMapViewer {
 				//always end up with the scene's first added shadow casting light's shadowMap
 				//in the shader
 				//See: https://github.com/mrdoob/three.js/issues/5932
-				uniforms.tDiffuse.value = light.shadow.map.texture;
+				material.uniforms.tDiffuse.value = light.shadow.map.texture;
 
 				userAutoClearSetting = renderer.autoClear;
 				renderer.autoClear = false; // To allow render overlay
@@ -171,6 +203,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 +223,9 @@ class ShadowMapViewer {
 
 		};
 
+		/**
+		 * Updates the viewer.
+		 */
 		this.update = function () {
 
 			this.position.set( this.position.x, this.position.y );

package/examples/jsm/utils/ShadowMapViewerGPU.js

@@ -7,39 +7,37 @@ import {
 	OrthographicCamera,
 	PlaneGeometry,
 	Scene,
-	Texture
-} from 'three';
-import { texture } from 'three/tsl';
+	DepthTexture,
+	Vector2
+} from 'three/webgpu';
+import { uv, uniform, textureLoad } from 'three/tsl';
 
 /**
  * This is a helper for visualising a given light's shadow map.
  * 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';
+ * ```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();
+ * ```
  *
- *	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();
+ * @three_import import { ShadowMapViewer } from 'three/addons/utils/ShadowMapViewerGPU.js';
  */
-
 class ShadowMapViewer {
 
+	/**
+	 * Constructs a new shadow map viewer.
+	 *
+	 * @param {Light} light - The shadow casting light.
+	 */
 	constructor( light ) {
 
 		//- Internals
@@ -63,8 +61,10 @@ class ShadowMapViewer {
 
 		const material = new NodeMaterial();
 
-		const shadowMapUniform = texture( new Texture() );
-		material.fragmentNode = shadowMapUniform;
+		const textureDimension = uniform( new Vector2() );
+
+		const shadowMapUniform = textureLoad( new DepthTexture(), uv().flipY().mul( textureDimension ) );
+		material.fragmentNode = shadowMapUniform.x.oneMinus();
 
 		const plane = new PlaneGeometry( frame.width, frame.height );
 		const mesh = new Mesh( plane, material );
@@ -106,11 +106,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 +137,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 +162,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 ) {
@@ -155,7 +176,11 @@ class ShadowMapViewer {
 				//always end up with the scene's first added shadow casting light's shadowMap
 				//in the shader
 				//See: https://github.com/mrdoob/three.js/issues/5932
-				shadowMapUniform.value = light.shadow.map.texture;
+
+				const depthTexture = light.shadow.map.depthTexture;
+
+				shadowMapUniform.value = depthTexture;
+				textureDimension.value.set( depthTexture.width, depthTexture.height );
 
 				currentAutoClear = renderer.autoClear;
 				renderer.autoClear = false; // To allow render overlay
@@ -167,6 +192,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 +212,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,11 @@ import {
 	VectorKeyframeTrack
 } from 'three';
 
+/**
+ * @module SkeletonUtils
+ * @three_import import * as SkeletonUtils from 'three/addons/utils/SkeletonUtils.js';
+ */
+
 function getBoneName( bone, options ) {
 
 	if ( options.getBoneName !== undefined ) {
@@ -21,6 +26,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 +209,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 +377,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 +466,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,8 @@
-// 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
+ * @three_import import * as SortUtils from 'three/addons/utils/SortUtils.js';
+ */
 
 const POWER = 3;
 const BIT_MAX = 32;
@@ -24,6 +24,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

@@ -3,13 +3,21 @@ import {
 } from 'three';
 
 /**
- * tool for "unwrapping" and debugging three.js geometries UV mapping
+ * @module UVsDebug
+ * @three_import import { UVsDebug } from 'three/addons/utils/UVsDebug.js';
+ */
+
+/**
+ * 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/{TextureUtils.js → WebGLTextureUtils.js}

@@ -10,11 +10,27 @@ import {
 	SRGBColorSpace
 } from 'three';
 
+/**
+ * @module WebGLTextureUtils
+ * @three_import import * as WebGLTextureUtils from 'three/addons/utils/WebGLTextureUtils.js';
+ */
+
 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/{TextureUtilsGPU.js → WebGPUTextureUtils.js}

@@ -3,12 +3,29 @@ import {
 	NodeMaterial,
 	WebGPURenderer,
 	CanvasTexture
-} from 'three';
+} from 'three/webgpu';
 import { texture, uv } from 'three/tsl';
 
+/**
+ * @module WebGPUTextureUtils
+ * @three_import import * as WebGPUTextureUtils from 'three/addons/utils/WebGPUTextureUtils.js';
+ */
+
 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 ) {
@@ -19,7 +36,8 @@ export async function decompress( blitTexture, maxTextureSize = Infinity, render
 	}
 
 	const material = new NodeMaterial();
-	material.fragmentNode = texture( blitTexture ).uv( uv().flipY() );
+
+	material.fragmentNode = texture( blitTexture, uv().flipY() );
 
 	const width = Math.min( blitTexture.image.width, maxTextureSize );
 	const height = Math.min( blitTexture.image.height, maxTextureSize );

package/examples/jsm/utils/WorkerPool.js

@@ -1,17 +1,60 @@
 /**
- * @author Deepkolos / https://github.com/deepkolos
+ * A simple pool for managing Web Workers.
+ *
+ * @three_import import { WorkerPool } from 'three/addons/utils/WorkerPool.js';
  */
-
 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 +97,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 +150,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,24 @@
+/**
+ * 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
+ * @three_import import { ARButton } from 'three/addons/webxr/ARButton.js';
+ */
 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' );