super-three 0.173.5 → 0.175.0

package/examples/jsm/Addons.js

@@ -46,7 +46,7 @@ export * from './exporters/USDZExporter.js';
 export * from './geometries/BoxLineGeometry.js';
 export * from './geometries/ConvexGeometry.js';
 export * from './geometries/DecalGeometry.js';
-export * from './geometries/ParametricGeometries.js';
+export * from './geometries/ParametricFunctions.js';
 export * from './geometries/ParametricGeometry.js';
 export * from './geometries/RoundedBoxGeometry.js';
 export * from './geometries/TeapotGeometry.js';

package/examples/jsm/animation/AnimationClipCreator.js

@@ -7,8 +7,21 @@ import {
 	VectorKeyframeTrack
 } from 'three';
 
+/**
+ * A utility class with factory methods for creating basic animation clips.
+ *
+ * @hideconstructor
+ */
 class AnimationClipCreator {
 
+	/**
+	 * Creates an animation clip that rotates a 3D object 360 degrees
+	 * in the given period of time around the given axis.
+	 *
+	 * @param {number} period - The duration of the animation.
+	 * @param {('x'|'y'|'z')} [axis='x'] - The axis of rotation.
+	 * @return {AnimationClip} The created animation clip.
+	 */
 	static CreateRotationAnimation( period, axis = 'x' ) {
 
 		const times = [ 0, period ], values = [ 0, 360 ];
@@ -17,10 +30,18 @@ class AnimationClipCreator {
 
 		const track = new NumberKeyframeTrack( trackName, times, values );
 
-		return new AnimationClip( null, period, [ track ] );
+		return new AnimationClip( '', period, [ track ] );
 
 	}
 
+	/**
+	 * Creates an animation clip that scales a 3D object from `0` to `1`
+	 * in the given period of time along the given axis.
+	 *
+	 * @param {number} period - The duration of the animation.
+	 * @param {('x'|'y'|'z')} [axis='x'] - The axis to scale the 3D object along.
+	 * @return {AnimationClip} The created animation clip.
+	 */
 	static CreateScaleAxisAnimation( period, axis = 'x' ) {
 
 		const times = [ 0, period ], values = [ 0, 1 ];
@@ -29,10 +50,18 @@ class AnimationClipCreator {
 
 		const track = new NumberKeyframeTrack( trackName, times, values );
 
-		return new AnimationClip( null, period, [ track ] );
+		return new AnimationClip( '', period, [ track ] );
 
 	}
 
+	/**
+	 * Creates an animation clip that translates a 3D object in a shake pattern
+	 * in the given period.
+	 *
+	 * @param {number} duration - The duration of the animation.
+	 * @param {Vector3} shakeScale - The scale of the shake.
+	 * @return {AnimationClip} The created animation clip.
+	 */
 	static CreateShakeAnimation( duration, shakeScale ) {
 
 		const times = [], values = [], tmp = new Vector3();
@@ -51,10 +80,18 @@ class AnimationClipCreator {
 
 		const track = new VectorKeyframeTrack( trackName, times, values );
 
-		return new AnimationClip( null, duration, [ track ] );
+		return new AnimationClip( '', duration, [ track ] );
 
 	}
 
+	/**
+	 * Creates an animation clip that scales a 3D object in a pulse pattern
+	 * in the given period.
+	 *
+	 * @param {number} duration - The duration of the animation.
+	 * @param {number} pulseScale - The scale of the pulse.
+	 * @return {AnimationClip} The created animation clip.
+	 */
 	static CreatePulsationAnimation( duration, pulseScale ) {
 
 		const times = [], values = [], tmp = new Vector3();
@@ -73,10 +110,16 @@ class AnimationClipCreator {
 
 		const track = new VectorKeyframeTrack( trackName, times, values );
 
-		return new AnimationClip( null, duration, [ track ] );
+		return new AnimationClip( '', duration, [ track ] );
 
 	}
 
+	/**
+	 * Creates an animation clip that toggles the visibility of a 3D object.
+	 *
+	 * @param {number} duration - The duration of the animation.
+	 * @return {AnimationClip} The created animation clip.
+	 */
 	static CreateVisibilityAnimation( duration ) {
 
 		const times = [ 0, duration / 2, duration ], values = [ true, false, true ];
@@ -85,10 +128,18 @@ class AnimationClipCreator {
 
 		const track = new BooleanKeyframeTrack( trackName, times, values );
 
-		return new AnimationClip( null, duration, [ track ] );
+		return new AnimationClip( '', duration, [ track ] );
 
 	}
 
+	/**
+	 * Creates an animation clip that animates the `color` property of a 3D object's
+	 * material.
+	 *
+	 * @param {number} duration - The duration of the animation.
+	 * @param {Array<Color>} colors - An array of colors that should be sequentially animated.
+	 * @return {AnimationClip} The created animation clip.
+	 */
 	static CreateMaterialColorAnimation( duration, colors ) {
 
 		const times = [], values = [],
@@ -107,7 +158,7 @@ class AnimationClipCreator {
 
 		const track = new ColorKeyframeTrack( trackName, times, values );
 
-		return new AnimationClip( null, duration, [ track ] );
+		return new AnimationClip( '', duration, [ track ] );
 
 	}
 

package/examples/jsm/animation/CCDIKSolver.js

@@ -25,54 +25,66 @@ const _axis = new Vector3();
 const _vector = new Vector3();
 const _matrix = new Matrix4();
 
-
 /**
- * CCD Algorithm
- *  - https://web.archive.org/web/20221206080850/https://sites.google.com/site/auraliusproject/ccd-algorithm
+ * This class solves the Inverse Kinematics Problem with a [CCD Algorithm]{@link https://web.archive.org/web/20221206080850/https://sites.google.com/site/auraliusproject/ccd-algorithm}.
  *
- * // ik parameter example
- * //
- * // target, effector, index in links are bone index in skeleton.bones.
- * // the bones relation should be
- * // <-- parent                                  child -->
- * // links[ n ], links[ n - 1 ], ..., links[ 0 ], effector
- * iks = [ {
- *	target: 1,
- *	effector: 2,
- *	links: [ { index: 5, limitation: new Vector3( 1, 0, 0 ) }, { index: 4, enabled: false }, { index : 3 } ],
- *	iteration: 10,
- *	minAngle: 0.0,
- *	maxAngle: 1.0,
- * } ];
+ * `CCDIKSolver` is designed to work with instances of {@link SkinnedMesh}.
  */
-
 class CCDIKSolver {
 
 	/**
-	 * @param {THREE.SkinnedMesh} mesh
-	 * @param {Array<Object>} iks
+	 * @param {SkinnedMesh} mesh - The skinned mesh.
+	 * @param {Array<CCDIKSolver~IK>} [iks=[]] - The IK objects.
 	 */
 	constructor( mesh, iks = [] ) {
 
+		/**
+		 * The skinned mesh.
+		 *
+		 * @type {SkinnedMesh}
+		 */
 		this.mesh = mesh;
+
+		/**
+		 * The IK objects.
+		 *
+		 * @type {SkinnedMesh}
+		 */
 		this.iks = iks;
 
+		this._initialQuaternions = [];
+		this._workingQuaternion = new Quaternion();
+
+		for ( const ik of iks ) {
+
+			const chainQuats = [];
+			for ( let i = 0; i < ik.links.length; i ++ ) {
+
+			  chainQuats.push( new Quaternion() );
+
+			}
+
+			this._initialQuaternions.push( chainQuats );
+
+		}
+
 		this._valid();
 
 	}
 
 	/**
-	 * Update all IK bones.
+	 * Updates all IK bones by solving the CCD algorithm.
 	 *
-	 * @return {CCDIKSolver}
+	 * @param {number} [globalBlendFactor=1.0] - Blend factor applied if an IK chain doesn't have its own .blendFactor.
+	 * @return {CCDIKSolver} A reference to this instance.
 	 */
-	update() {
+	update( globalBlendFactor = 1.0 ) {
 
 		const iks = this.iks;
 
 		for ( let i = 0, il = iks.length; i < il; i ++ ) {
 
-			this.updateOne( iks[ i ] );
+			this.updateOne( iks[ i ], globalBlendFactor );
 
 		}
 
@@ -81,14 +93,18 @@ class CCDIKSolver {
 	}
 
 	/**
-	 * Update one IK bone
+	 * Updates one IK bone solving the CCD algorithm.
 	 *
-	 * @param {Object} ik parameter
-	 * @return {CCDIKSolver}
+	 * @param {CCDIKSolver~IK} ik - The IK to update.
+	 * @param {number} [overrideBlend=1.0] - If the IK object does not define `blendFactor`, this value is used.
+	 * @return {CCDIKSolver} A reference to this instance.
 	 */
-	updateOne( ik ) {
+	updateOne( ik, overrideBlend = 1.0 ) {
 
+		const chainBlend = ik.blendFactor !== undefined ? ik.blendFactor : overrideBlend;
 		const bones = this.mesh.skeleton.bones;
+		const chainIndex = this.iks.indexOf( ik );
+		const initialQuaternions = this._initialQuaternions[ chainIndex ];
 
 		// for reference overhead reduction in loop
 		const math = Math;
@@ -103,6 +119,17 @@ class CCDIKSolver {
 		const links = ik.links;
 		const iteration = ik.iteration !== undefined ? ik.iteration : 1;
 
+		if ( chainBlend < 1.0 ) {
+
+			for ( let j = 0; j < links.length; j ++ ) {
+
+			  const linkIndex = links[ j ].index;
+			  initialQuaternions[ j ].copy( bones[ linkIndex ].quaternion );
+
+			}
+
+		}
+
 		for ( let i = 0; i < iteration; i ++ ) {
 
 			let rotated = false;
@@ -205,15 +232,31 @@ class CCDIKSolver {
 
 		}
 
-		return this;
+		if ( chainBlend < 1.0 ) {
+
+			for ( let j = 0; j < links.length; j ++ ) {
+
+			  const linkIndex = links[ j ].index;
+			  const link = bones[ linkIndex ];
+
+			  this._workingQuaternion.copy( initialQuaternions[ j ] ).slerp( link.quaternion, chainBlend );
+
+			  link.quaternion.copy( this._workingQuaternion );
+			  link.updateMatrixWorld( true );
+
+			}
+
+		}
+
+		  return this;
 
 	}
 
 	/**
-	 * Creates Helper
+	 * Creates a helper for visualizing the CCDIK.
 	 *
-	 * @param {number} sphereSize
-	 * @return {CCDIKHelper}
+	 * @param {number} sphereSize - The sphere size.
+	 * @return {CCDIKHelper} The created helper.
 	 */
 	createHelper( sphereSize ) {
 
@@ -276,27 +319,50 @@ function setPositionOfBoneToAttributeArray( array, index, bone, matrixWorldInv )
 }
 
 /**
- * Visualize IK bones
+ * Helper for visualizing IK bones.
+ *
+ * @augments Object3D
  */
 class CCDIKHelper extends Object3D {
 
 	/**
-	 * @param {SkinnedMesh} mesh
- 	 * @param {Array<Object>} [iks=[]]
- 	 * @param {number} [sphereSize=0.25]
+	 * @param {SkinnedMesh} mesh - The skinned mesh.
+ 	 * @param {Array<CCDIKSolver~IK>} [iks=[]] - The IK objects.
+ 	 * @param {number} [sphereSize=0.25] - The sphere size.
 	 */
 	constructor( mesh, iks = [], sphereSize = 0.25 ) {
 
 		super();
 
+		/**
+		 * The skinned mesh this helper refers to.
+		 *
+		 * @type {SkinnedMesh}
+		 */
 		this.root = mesh;
+
+		/**
+		 * The IK objects.
+		 *
+		 * @type {Array<CCDIKSolver~IK>}
+		 */
 		this.iks = iks;
 
 		this.matrix.copy( mesh.matrixWorld );
 		this.matrixAutoUpdate = false;
 
+		/**
+		 * The helpers sphere geometry.
+		 *
+		 * @type {SkinnedMesh}
+		 */
 		this.sphereGeometry = new SphereGeometry( sphereSize, 16, 8 );
 
+		/**
+		 * The material for the target spheres.
+		 *
+		 * @type {MeshBasicMaterial}
+		 */
 		this.targetSphereMaterial = new MeshBasicMaterial( {
 			color: new Color( 0xff8888 ),
 			depthTest: false,
@@ -304,6 +370,11 @@ class CCDIKHelper extends Object3D {
 			transparent: true
 		} );
 
+		/**
+		 * The material for the effector spheres.
+		 *
+		 * @type {MeshBasicMaterial}
+		 */
 		this.effectorSphereMaterial = new MeshBasicMaterial( {
 			color: new Color( 0x88ff88 ),
 			depthTest: false,
@@ -311,6 +382,11 @@ class CCDIKHelper extends Object3D {
 			transparent: true
 		} );
 
+		/**
+		 * The material for the link spheres.
+		 *
+		 * @type {MeshBasicMaterial}
+		 */
 		this.linkSphereMaterial = new MeshBasicMaterial( {
 			color: new Color( 0x8888ff ),
 			depthTest: false,
@@ -318,6 +394,11 @@ class CCDIKHelper extends Object3D {
 			transparent: true
 		} );
 
+		/**
+		 * A global line material.
+		 *
+		 * @type {LineBasicMaterial}
+		 */
 		this.lineMaterial = new LineBasicMaterial( {
 			color: new Color( 0xff0000 ),
 			depthTest: false,
@@ -329,11 +410,6 @@ class CCDIKHelper extends Object3D {
 
 	}
 
-	/**
-	 * Updates IK bones visualization.
-	 *
-	 * @param {Boolean} force
-	 */
 	updateMatrixWorld( force ) {
 
 		const mesh = this.root;
@@ -398,7 +474,8 @@ class CCDIKHelper extends Object3D {
 	}
 
 	/**
-	 * Frees the GPU-related resources allocated by this instance. Call this method whenever this instance is no longer used in your app.
+	 * Frees the GPU-related resources allocated by this instance.
+	 * Call this method whenever this instance is no longer used in your app.
 	 */
 	dispose() {
 
@@ -483,4 +560,29 @@ class CCDIKHelper extends Object3D {
 
 }
 
+/**
+ * This type represents IK configuration objects.
+ *
+ * @typedef {Object} CCDIKSolver~IK
+ * @property {number} target - The target bone index which refers to a bone in the `Skeleton.bones` array.
+ * @property {number} effector - The effector bone index which refers to a bone in the `Skeleton.bones` array.
+ * @property {Array<CCDIKSolver~BoneLink>} links - An array of bone links.
+ * @property {number} [iteration=1] - Iteration number of calculation. Smaller is faster but less precise.
+ * @property {number} [minAngle] - Minimum rotation angle in a step in radians.
+ * @property {number} [maxAngle] - Minimum rotation angle in a step in radians.
+ * @property {number} [blendFactor] - The blend factor.
+ **/
+
+/**
+ * This type represents bone links.
+ *
+ * @typedef {Object} CCDIKSolver~BoneLink
+ * @property {number} index - The index of a linked bone which refers to a bone in the `Skeleton.bones` array.
+ * @property {number} [limitation] - Rotation axis.
+ * @property {number} [rotationMin] - Rotation minimum limit.
+ * @property {number} [rotationMax] - Rotation maximum limit.
+ * @property {boolean} [enabled=true] - Whether the link is enabled or not.
+ **/
+
+
 export { CCDIKSolver, CCDIKHelper };

package/examples/jsm/capabilities/WebGL.js

@@ -1,5 +1,15 @@
+/**
+ * A utility module with basic WebGL 2 capability testing.
+ *
+ * @hideconstructor
+ */
 class WebGL {
 
+	/**
+	 * Returns `true` if WebGL 2 is available.
+	 *
+	 * @return {boolean} Whether WebGL 2 is available or not.
+	 */
 	static isWebGL2Available() {
 
 		try {
@@ -15,6 +25,13 @@ class WebGL {
 
 	}
 
+	/**
+	 * Returns `true` if the given color space is available. This method can only be used
+	 * if WebGL 2 is supported.
+	 *
+	 * @param {string} colorSpace - The color space to test.
+	 * @return {boolean} Whether the given color space is available or not.
+	 */
 	static isColorSpaceAvailable( colorSpace ) {
 
 		try {
@@ -32,13 +49,21 @@ class WebGL {
 
 	}
 
+	/**
+	 * Returns a `div` element representing a formatted error message that can be appended in
+	 * web sites if WebGL 2 isn't supported.
+	 *
+	 * @return {HTMLDivElement} A `div` element representing a formatted error message that WebGL 2 isn't supported.
+	 */
 	static getWebGL2ErrorMessage() {
 
-		return this.getErrorMessage( 2 );
+		return this._getErrorMessage( 2 );
 
 	}
 
-	static getErrorMessage( version ) {
+	// private
+
+	static _getErrorMessage( version ) {
 
 		const names = {
 			1: 'WebGL',
@@ -105,7 +130,7 @@ class WebGL {
 
 		console.warn( 'getWebGLErrorMessage() has been deprecated and will be removed in r178. Use getWebGL2ErrorMessage() instead.' );
 
-		return this.getErrorMessage( 1 );
+		return this._getErrorMessage( 1 );
 
 	}
 

package/examples/jsm/capabilities/WebGPU.js

@@ -6,20 +6,30 @@ if ( typeof window !== 'undefined' && isAvailable ) {
 
 }
 
+/**
+ * A utility module with basic WebGPU capability testing.
+ *
+ * @hideconstructor
+ */
 class WebGPU {
 
+	/**
+	 * Returns `true` if WebGPU is available.
+	 *
+	 * @return {boolean} Whether WebGPU is available or not.
+	 */
 	static isAvailable() {
 
 		return Boolean( isAvailable );
 
 	}
 
-	static getStaticAdapter() {
-
-		return isAvailable;
-
-	}
-
+	/**
+	 * Returns a `div` element representing a formatted error message that can be appended in
+	 * web sites if WebGPU isn't supported.
+	 *
+	 * @return {HTMLDivElement} A `div` element representing a formatted error message that WebGPU isn't supported.
+	 */
 	static getErrorMessage() {
 
 		const message = 'Your browser does not support <a href="https://gpuweb.github.io/gpuweb/" style="color:blue">WebGPU</a> yet';