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

package/examples/jsm/math/SimplexNoise.js

@@ -1,17 +1,19 @@
-// Ported from Stefan Gustavson's java implementation
-// http://staffwww.itn.liu.se/~stegu/simplexnoise/simplexnoise.pdf
-// Read Stefan's excellent paper for details on how this code works.
-//
-// Sean McCullough banksean@gmail.com
-//
-// Added 4D noise
-
 /**
- * You can pass in a random number generator object if you like.
- * It is assumed to have a random() method.
+ * A utility class providing noise functions.
+ *
+ * The code is based on [Simplex noise demystified](https://web.archive.org/web/20210210162332/http://staffwww.itn.liu.se/~stegu/simplexnoise/simplexnoise.pdf)
+ * by Stefan Gustavson, 2005.
+ *
+ * @three_import import { SimplexNoise } from 'three/addons/math/SimplexNoise.js';
  */
 class SimplexNoise {
 
+	/**
+	 * Constructs a new simplex noise object.
+	 *
+	 * @param {Object} [r=Math] - A math utility class that holds a `random()` method. This makes it
+	 * possible to pass in custom random number generator.
+	 */
 	constructor( r = Math ) {
 
 		this.grad3 = [[ 1, 1, 0 ], [ - 1, 1, 0 ], [ 1, - 1, 0 ], [ - 1, - 1, 0 ],
@@ -58,24 +60,13 @@ class SimplexNoise {
 
 	}
 
-	dot( g, x, y ) {
-
-		return g[ 0 ] * x + g[ 1 ] * y;
-
-	}
-
-	dot3( g, x, y, z ) {
-
-		return g[ 0 ] * x + g[ 1 ] * y + g[ 2 ] * z;
-
-	}
-
-	dot4( g, x, y, z, w ) {
-
-		return g[ 0 ] * x + g[ 1 ] * y + g[ 2 ] * z + g[ 3 ] * w;
-
-	}
-
+	/**
+	 * A 2D simplex noise method.
+	 *
+	 * @param {number} xin - The x coordinate.
+	 * @param {number} yin - The y coordinate.
+	 * @return {number} The noise value.
+	 */
 	noise( xin, yin ) {
 
 		let n0; // Noise contributions from the three corners
@@ -129,7 +120,7 @@ class SimplexNoise {
 		else {
 
 			t0 *= t0;
-			n0 = t0 * t0 * this.dot( this.grad3[ gi0 ], x0, y0 ); // (x,y) of grad3 used for 2D gradient
+			n0 = t0 * t0 * this._dot( this.grad3[ gi0 ], x0, y0 ); // (x,y) of grad3 used for 2D gradient
 
 		}
 
@@ -138,7 +129,7 @@ class SimplexNoise {
 		else {
 
 			t1 *= t1;
-			n1 = t1 * t1 * this.dot( this.grad3[ gi1 ], x1, y1 );
+			n1 = t1 * t1 * this._dot( this.grad3[ gi1 ], x1, y1 );
 
 		}
 
@@ -147,7 +138,7 @@ class SimplexNoise {
 		else {
 
 			t2 *= t2;
-			n2 = t2 * t2 * this.dot( this.grad3[ gi2 ], x2, y2 );
+			n2 = t2 * t2 * this._dot( this.grad3[ gi2 ], x2, y2 );
 
 		}
 
@@ -157,7 +148,14 @@ class SimplexNoise {
 
 	}
 
-	// 3D simplex noise
+	/**
+	 * A 3D simplex noise method.
+	 *
+	 * @param {number} xin - The x coordinate.
+	 * @param {number} yin - The y coordinate.
+	 * @param {number} zin - The z coordinate.
+	 * @return {number} The noise value.
+	 */
 	noise3d( xin, yin, zin ) {
 
 		let n0; // Noise contributions from the four corners
@@ -257,7 +255,7 @@ class SimplexNoise {
 		else {
 
 			t0 *= t0;
-			n0 = t0 * t0 * this.dot3( this.grad3[ gi0 ], x0, y0, z0 );
+			n0 = t0 * t0 * this._dot3( this.grad3[ gi0 ], x0, y0, z0 );
 
 		}
 
@@ -266,7 +264,7 @@ class SimplexNoise {
 		else {
 
 			t1 *= t1;
-			n1 = t1 * t1 * this.dot3( this.grad3[ gi1 ], x1, y1, z1 );
+			n1 = t1 * t1 * this._dot3( this.grad3[ gi1 ], x1, y1, z1 );
 
 		}
 
@@ -275,7 +273,7 @@ class SimplexNoise {
 		else {
 
 			t2 *= t2;
-			n2 = t2 * t2 * this.dot3( this.grad3[ gi2 ], x2, y2, z2 );
+			n2 = t2 * t2 * this._dot3( this.grad3[ gi2 ], x2, y2, z2 );
 
 		}
 
@@ -284,7 +282,7 @@ class SimplexNoise {
 		else {
 
 			t3 *= t3;
-			n3 = t3 * t3 * this.dot3( this.grad3[ gi3 ], x3, y3, z3 );
+			n3 = t3 * t3 * this._dot3( this.grad3[ gi3 ], x3, y3, z3 );
 
 		}
 
@@ -294,7 +292,15 @@ class SimplexNoise {
 
 	}
 
-	// 4D simplex noise
+	/**
+	 * A 4D simplex noise method.
+	 *
+	 * @param {number} x - The x coordinate.
+	 * @param {number} y - The y coordinate.
+	 * @param {number} z - The z coordinate.
+	 * @param {number} w - The w coordinate.
+	 * @return {number} The noise value.
+	 */
 	noise4d( x, y, z, w ) {
 
 		// For faster and easier lookups
@@ -394,7 +400,7 @@ class SimplexNoise {
 		else {
 
 			t0 *= t0;
-			n0 = t0 * t0 * this.dot4( grad4[ gi0 ], x0, y0, z0, w0 );
+			n0 = t0 * t0 * this._dot4( grad4[ gi0 ], x0, y0, z0, w0 );
 
 		}
 
@@ -403,7 +409,7 @@ class SimplexNoise {
 		else {
 
 			t1 *= t1;
-			n1 = t1 * t1 * this.dot4( grad4[ gi1 ], x1, y1, z1, w1 );
+			n1 = t1 * t1 * this._dot4( grad4[ gi1 ], x1, y1, z1, w1 );
 
 		}
 
@@ -412,7 +418,7 @@ class SimplexNoise {
 		else {
 
 			t2 *= t2;
-			n2 = t2 * t2 * this.dot4( grad4[ gi2 ], x2, y2, z2, w2 );
+			n2 = t2 * t2 * this._dot4( grad4[ gi2 ], x2, y2, z2, w2 );
 
 		}
 
@@ -421,7 +427,7 @@ class SimplexNoise {
 		else {
 
 			t3 *= t3;
-			n3 = t3 * t3 * this.dot4( grad4[ gi3 ], x3, y3, z3, w3 );
+			n3 = t3 * t3 * this._dot4( grad4[ gi3 ], x3, y3, z3, w3 );
 
 		}
 
@@ -430,7 +436,7 @@ class SimplexNoise {
 		else {
 
 			t4 *= t4;
-			n4 = t4 * t4 * this.dot4( grad4[ gi4 ], x4, y4, z4, w4 );
+			n4 = t4 * t4 * this._dot4( grad4[ gi4 ], x4, y4, z4, w4 );
 
 		}
 
@@ -439,6 +445,26 @@ class SimplexNoise {
 
 	}
 
+	// private
+
+	_dot( g, x, y ) {
+
+		return g[ 0 ] * x + g[ 1 ] * y;
+
+	}
+
+	_dot3( g, x, y, z ) {
+
+		return g[ 0 ] * x + g[ 1 ] * y + g[ 2 ] * z;
+
+	}
+
+	_dot4( g, x, y, z, w ) {
+
+		return g[ 0 ] * x + g[ 1 ] * y + g[ 2 ] * z + g[ 3 ] * w;
+
+	}
+
 }
 
 export { SimplexNoise };

package/examples/jsm/misc/ConvexObjectBreaker.js

@@ -6,39 +6,35 @@ import {
 } from 'three';
 import { ConvexGeometry } from '../geometries/ConvexGeometry.js';
 
+const _v1 = new Vector3();
+
 /**
- * @fileoverview This class can be used to subdivide a convex Geometry object into pieces.
- *
- * Usage:
+ * This class can be used to subdivide a convex Geometry object into pieces.
  *
  * Use the function prepareBreakableObject to prepare a Mesh object to be broken.
- *
- * Then, call the various functions to subdivide the object (subdivideByImpact, cutByPlane)
- *
+ * Then, call the various functions to subdivide the object (subdivideByImpact, cutByPlane).
  * Sub-objects that are product of subdivision don't need prepareBreakableObject to be called on them.
  *
  * Requisites for the object:
- *
- *  - Mesh object must have a buffer geometry and a material
- *
- *  - Vertex normals must be planar (not smoothed)
- *
- *  - The geometry must be convex (this is not checked in the library). You can create convex
- *  geometries with ConvexGeometry. The BoxGeometry, SphereGeometry and other convex primitives
- *  can also be used.
+ * - Mesh object must have a buffer geometry and a material.
+ * - Vertex normals must be planar (not smoothed).
+ * - The geometry must be convex (this is not checked in the library). You can create convex
+ * geometries with {@link ConvexGeometry}. The {@link BoxGeometry}, {@link SphereGeometry} and other
+ * convex primitives can also be used.
  *
  * Note: This lib adds member variables to object's userData member (see prepareBreakableObject function)
  * Use with caution and read the code when using with other libs.
  *
- * @param {double} minSizeForBreak Min size a debris can have to break.
- * @param {double} smallDelta Max distance to consider that a point belongs to a plane.
- *
-*/
-
-const _v1 = new Vector3();
-
+ * @three_import import { ConvexObjectBreaker } from 'three/addons/misc/ConvexObjectBreaker.js';
+ */
 class ConvexObjectBreaker {
 
+	/**
+	 * Constructs a new convex object breaker.
+	 *
+	 * @param {number} [minSizeForBreak=1.4] - Min size a debris can have to break.
+ 	 * @param {number} [smallDelta=0.0001] - Max distance to consider that a point belongs to a plane.
+	 */
 	constructor( minSizeForBreak = 1.4, smallDelta = 0.0001 ) {
 
 		this.minSizeForBreak = minSizeForBreak;
@@ -68,6 +64,15 @@ class ConvexObjectBreaker {
 
 	}
 
+	/**
+	 * Must be called for all 3D objects that should be breakable.
+	 *
+	 * @param {Object3D} object - The 3D object. It must have a convex geometry.
+	 * @param {number} mass - The 3D object's mass in kg. Must be greater than `0`.
+	 * @param {Vector3} velocity - The 3D object's velocity.
+	 * @param {Vector3} angularVelocity - The 3D object's angular velocity.
+	 * @param {boolean} breakable - Whether the 3D object is breakable or not.
+	 */
 	prepareBreakableObject( object, mass, velocity, angularVelocity, breakable ) {
 
 		// object is a Object3d (normally a Mesh), must have a buffer geometry, and it must be convex.
@@ -82,11 +87,16 @@ class ConvexObjectBreaker {
 
 	}
 
-	/*
-	 * @param {int} maxRadialIterations Iterations for radial cuts.
-	 * @param {int} maxRandomIterations Max random iterations for not-radial cuts
+	/**
+	 * Subdivides the given 3D object into pieces by an impact (meaning another object hits
+	 * the given 3D object at a certain surface point).
 	 *
-	 * Returns the array of pieces
+	 * @param {Object3D} object - The 3D object to subdivide.
+	 * @param {Vector3} pointOfImpact - The point of impact.
+	 * @param {Vector3} normal - The impact normal.
+	 * @param {number} maxRadialIterations - Iterations for radial cuts.
+	 * @param {number} maxRandomIterations - Max random iterations for not-radial cuts.
+	 * @return {Array<Object3D>} The array of pieces.
 	 */
 	subdivideByImpact( object, pointOfImpact, normal, maxRadialIterations, maxRandomIterations ) {
 
@@ -168,6 +178,14 @@ class ConvexObjectBreaker {
 
 	}
 
+	/**
+	 * Subdivides the given 3D object into pieces by a plane.
+	 *
+	 * @param {Object3D} object - The 3D object to subdivide.
+	 * @param {Plane} plane - The plane to cut the 3D object.
+	 * @param {{object1:?Mesh,object2:?Mesh}} output - An object that stores the pieces.
+	 * @return {number} The number of pieces.
+	 */
 	cutByPlane( object, plane, output ) {
 
 		// Returns breakable objects in output.object1 and output.object2 members, the resulting 2 pieces of the cut.
@@ -449,6 +467,8 @@ class ConvexObjectBreaker {
 
 	}
 
+	// internal helpers
+
 	static transformFreeVector( v, m ) {
 
 		// input:

package/examples/jsm/misc/GPUComputationRenderer.js

@@ -11,10 +11,10 @@ import {
 import { FullScreenQuad } from '../postprocessing/Pass.js';
 
 /**
- * GPUComputationRenderer, based on SimulationRenderer by zz85
+ * GPUComputationRenderer, based on SimulationRenderer by @zz85.
  *
  * The GPUComputationRenderer uses the concept of variables. These variables are RGBA float textures that hold 4 floats
- * for each compute element (texel)
+ * for each compute element (texel).
  *
  * Each variable has a fragment shader that defines the computation made to obtain the variable in question.
  * You can use as many variables you need, and make dependencies so you can use textures of other variables in the shader
@@ -29,12 +29,11 @@ import { FullScreenQuad } from '../postprocessing/Pass.js';
  * a common approach could be to use 'texture' prefixing the variable name; i.e texturePosition, textureVelocity...
  *
  * The size of the computation (sizeX * sizeY) is defined as 'resolution' automatically in the shader. For example:
+ * ```
  * #DEFINE resolution vec2( 1024.0, 1024.0 )
- *
- * -------------
- *
+ * ```
  * Basic use:
- *
+ * ```js
  * // Initialization...
  *
  * // Create computation renderer
@@ -62,7 +61,6 @@ import { FullScreenQuad } from '../postprocessing/Pass.js';
  *		console.error( error );
   * }
  *
- *
  * // In each frame...
  *
  * // Compute!
@@ -73,12 +71,12 @@ import { FullScreenQuad } from '../postprocessing/Pass.js';
  *
  * // Do your rendering
  * renderer.render( myScene, myCamera );
- *
- * -------------
+ * ```
  *
  * Also, you can use utility functions to create ShaderMaterial and perform computations (rendering between textures)
  * Note that the shaders can have multiple input textures.
  *
+ * ```js
  * const myFilter1 = gpuCompute.createShaderMaterial( myFilterFragmentShader1, { theTexture: { value: null } } );
  * const myFilter2 = gpuCompute.createShaderMaterial( myFilterFragmentShader2, { theTexture: { value: null } } );
  *
@@ -99,16 +97,19 @@ import { FullScreenQuad } from '../postprocessing/Pass.js';
  * // And compute each frame, before rendering to screen:
  * gpuCompute.doRenderTarget( myFilter1, myRenderTarget );
  * gpuCompute.doRenderTarget( myFilter2, outputRenderTarget );
+ * ```
  *
- *
- *
- * @param {int} sizeX Computation problem size is always 2d: sizeX * sizeY elements.
- * @param {int} sizeY Computation problem size is always 2d: sizeX * sizeY elements.
- * @param {WebGLRenderer} renderer The renderer
-  */
-
+ * @three_import import { GPUComputationRenderer } from 'three/addons/misc/GPUComputationRenderer.js';
+ */
 class GPUComputationRenderer {
 
+	/**
+	 * Constructs a new GPU computation renderer.
+	 *
+	 * @param {number} sizeX - Computation problem size is always 2d: sizeX * sizeY elements.
+ 	 * @param {number} sizeY - Computation problem size is always 2d: sizeX * sizeY elements.
+ 	 * @param {WebGLRenderer} renderer - The renderer.
+	 */
 	constructor( sizeX, sizeY, renderer ) {
 
 		this.variables = [];
@@ -125,6 +126,12 @@ class GPUComputationRenderer {
 
 		const quad = new FullScreenQuad( passThruShader );
 
+		/**
+		 * Sets the data type of the internal textures.
+		 *
+		 * @param {(FloatType|HalfFloatType)} type - The type to set.
+		 * @return {GPUComputationRenderer} A reference to this renderer.
+		 */
 		this.setDataType = function ( type ) {
 
 			dataType = type;
@@ -132,6 +139,14 @@ class GPUComputationRenderer {
 
 		};
 
+		/**
+		 * Adds a compute variable to the renderer.
+		 *
+		 * @param {string} variableName - The variable name.
+		 * @param {string} computeFragmentShader - The compute (fragment) shader source.
+		 * @param {Texture} initialValueTexture - The initial value texture.
+		 * @return {Object} The compute variable.
+		 */
 		this.addVariable = function ( variableName, computeFragmentShader, initialValueTexture ) {
 
 			const material = this.createShaderMaterial( computeFragmentShader );
@@ -154,12 +169,23 @@ class GPUComputationRenderer {
 
 		};
 
+		/**
+		 * Sets variable dependencies.
+		 *
+		 * @param {Object} variable - The compute variable.
+		 * @param {Array<Object>} dependencies - Other compute variables that represents the dependencies.
+		 */
 		this.setVariableDependencies = function ( variable, dependencies ) {
 
 			variable.dependencies = dependencies;
 
 		};
 
+		/**
+		 * Initializes the renderer.
+		 *
+		 * @return {?string} Returns `null` if no errors are detected. Otherwise returns the error message.
+		 */
 		this.init = function () {
 
 			if ( renderer.capabilities.maxVertexTextures === 0 ) {
@@ -228,6 +254,9 @@ class GPUComputationRenderer {
 
 		};
 
+		/**
+		 * Executes the compute. This method is usually called in the animation loop.
+		 */
 		this.compute = function () {
 
 			const currentTextureIndex = this.currentTextureIndex;
@@ -261,18 +290,34 @@ class GPUComputationRenderer {
 
 		};
 
+		/**
+		 * Returns the current render target for the given compute variable.
+		 *
+		 * @param {Object} variable - The compute variable.
+		 * @return {WebGLRenderTarget} The current render target.
+		 */
 		this.getCurrentRenderTarget = function ( variable ) {
 
 			return variable.renderTargets[ this.currentTextureIndex ];
 
 		};
 
+		/**
+		 * Returns the alternate render target for the given compute variable.
+		 *
+		 * @param {Object} variable - The compute variable.
+		 * @return {WebGLRenderTarget} The alternate render target.
+		 */
 		this.getAlternateRenderTarget = function ( variable ) {
 
 			return variable.renderTargets[ this.currentTextureIndex === 0 ? 1 : 0 ];
 
 		};
 
+		/**
+		 * Frees all internal resources. Call this method if you don't need the
+		 * renderer anymore.
+		 */
 		this.dispose = function () {
 
 			quad.dispose();
@@ -304,6 +349,11 @@ class GPUComputationRenderer {
 
 		}
 
+		/**
+		 * Adds a resolution defined for the given material shader.
+		 *
+		 * @param {Object} materialShader - The material shader.
+		 */
 		this.addResolutionDefine = addResolutionDefine;
 
 
@@ -328,6 +378,17 @@ class GPUComputationRenderer {
 
 		this.createShaderMaterial = createShaderMaterial;
 
+		/**
+		 * Creates a new render target from the given parameters.
+		 *
+		 * @param {number} sizeXTexture - The width of the render target.
+		 * @param {number} sizeYTexture - The height of the render target.
+		 * @param {number} wrapS - The wrapS value.
+		 * @param {number} wrapT - The wrapS value.
+		 * @param {number} minFilter - The minFilter value.
+		 * @param {number} magFilter - The magFilter value.
+		 * @return {WebGLRenderTarget} The new render target.
+		 */
 		this.createRenderTarget = function ( sizeXTexture, sizeYTexture, wrapS, wrapT, minFilter, magFilter ) {
 
 			sizeXTexture = sizeXTexture || sizeX;
@@ -353,6 +414,11 @@ class GPUComputationRenderer {
 
 		};
 
+		/**
+		 * Creates a new data texture.
+		 *
+		 * @return {DataTexture} The new data texture.
+		 */
 		this.createTexture = function () {
 
 			const data = new Float32Array( sizeX * sizeY * 4 );
@@ -362,12 +428,14 @@ class GPUComputationRenderer {
 
 		};
 
+		/**
+		 * Renders the given texture into the given render target.
+		 *
+		 * @param {Texture} input - The input.
+		 * @param {WebGLRenderTarget} output - The output.
+		 */
 		this.renderTexture = function ( input, output ) {
 
-			// Takes a texture, and render out in rendertarget
-			// input = Texture
-			// output = RenderTarget
-
 			passThruUniforms.passThruTexture.value = input;
 
 			this.doRenderTarget( passThruShader, output );
@@ -376,6 +444,14 @@ class GPUComputationRenderer {
 
 		};
 
+
+		/**
+		 * Renders the given material into the given render target
+		 * with a full-screen pass.
+		 *
+		 * @param {Material} material - The material.
+		 * @param {WebGLRenderTarget} output - The output.
+		 */
 		this.doRenderTarget = function ( material, output ) {
 
 			const currentRenderTarget = renderer.getRenderTarget();

package/examples/jsm/misc/Gyroscope.js

@@ -12,8 +12,20 @@ const _translationWorld = new Vector3();
 const _quaternionWorld = new Quaternion();
 const _scaleWorld = new Vector3();
 
+/**
+ * A special type of 3D object that takes a position from the scene graph hierarchy
+ * but uses its local rotation as world rotation. It works like real-world gyroscope -
+ * you can move it around using hierarchy while its orientation stays fixed with
+ * respect to the world.
+ *
+ * @augments Object3D
+ * @three_import import { Gyroscope } from 'three/addons/misc/Gyroscope.js';
+ */
 class Gyroscope extends Object3D {
 
+	/**
+	 * Constructs a new gyroscope.
+	 */
 	constructor() {
 
 		super();