@plastic-software/three 0.174.0 → 0.175.1

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,36 +25,31 @@ 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 = [];
@@ -78,10 +73,10 @@ class CCDIKSolver {
 	}
 
 	/**
-	 * Update all IK bones.
+	 * Updates all IK bones by solving the CCD algorithm.
 	 *
 	 * @param {number} [globalBlendFactor=1.0] - Blend factor applied if an IK chain doesn't have its own .blendFactor.
-	 * @return {CCDIKSolver}
+	 * @return {CCDIKSolver} A reference to this instance.
 	 */
 	update( globalBlendFactor = 1.0 ) {
 
@@ -98,11 +93,11 @@ class CCDIKSolver {
 	}
 
 	/**
-	 * Update one IK bone
+	 * Updates one IK bone solving the CCD algorithm.
 	 *
-	 * @param {Object} ik parameter
-	 * @param {number} [overrideBlend=1.0] - If the ik object does not define .blendFactor, this value is used.
-	 * @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, overrideBlend = 1.0 ) {
 
@@ -258,10 +253,10 @@ class CCDIKSolver {
 	}
 
 	/**
-	 * 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 ) {
 
@@ -324,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,
@@ -352,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,
@@ -359,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,
@@ -366,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,
@@ -377,11 +410,6 @@ class CCDIKHelper extends Object3D {
 
 	}
 
-	/**
-	 * Updates IK bones visualization.
-	 *
-	 * @param {boolean} force
-	 */
 	updateMatrixWorld( force ) {
 
 		const mesh = this.root;
@@ -446,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() {
 
@@ -531,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';