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

package/src/helpers/PolarGridHelper.js

@@ -4,8 +4,34 @@ import { Float32BufferAttribute } from '../core/BufferAttribute.js';
 import { BufferGeometry } from '../core/BufferGeometry.js';
 import { Color } from '../math/Color.js';
 
+/**
+ * This helper is an object to define polar grids. Grids are
+ * two-dimensional arrays of lines.
+ *
+ * ```js
+ * const radius = 10;
+ * const sectors = 16;
+ * const rings = 8;
+ * const divisions = 64;
+ *
+ * const helper = new THREE.PolarGridHelper( radius, sectors, rings, divisions );
+ * scene.add( helper );
+ * ```
+ *
+ * @augments LineSegments
+ */
 class PolarGridHelper extends LineSegments {
 
+	/**
+	 * Constructs a new polar grid helper.
+	 *
+	 * @param {number} [radius=10] - The radius of the polar grid. This can be any positive number.
+	 * @param {number} [sectors=16] - The number of sectors the grid will be divided into. This can be any positive integer.
+	 * @param {number} [rings=16] - The number of rings. This can be any positive integer.
+	 * @param {number} [divisions=64] - The number of line segments used for each circle. This can be any positive integer.
+	 * @param {number|Color|string} [color1=0x444444] - The first color used for grid elements.
+	 * @param {number|Color|string} [color2=0x888888] -  The second color used for grid elements.
+	 */
 	constructor( radius = 10, sectors = 16, rings = 8, divisions = 64, color1 = 0x444444, color2 = 0x888888 ) {
 
 		color1 = new Color( color1 );
@@ -83,6 +109,10 @@ class PolarGridHelper extends LineSegments {
 
 	}
 
+	/**
+	 * Frees the GPU-related resources allocated by this instance. Call this
+	 * method whenever this instance is no longer used in your app.
+	 */
 	dispose() {
 
 		this.geometry.dispose();

package/src/helpers/SkeletonHelper.js

@@ -10,9 +10,24 @@ const _vector = /*@__PURE__*/ new Vector3();
 const _boneMatrix = /*@__PURE__*/ new Matrix4();
 const _matrixWorldInv = /*@__PURE__*/ new Matrix4();
 
-
+/**
+ * A helper object to assist with visualizing a {@link Skeleton}.
+ *
+ * ```js
+ * const helper = new THREE.SkeletonHelper( skinnedMesh );
+ * scene.add( helper );
+ * ```
+ *
+ * @augments LineSegments
+ */
 class SkeletonHelper extends LineSegments {
 
+	/**
+	 * Constructs a new skeleton helper.
+	 *
+	 * @param {Object3D} object -  Usually an instance of {@link SkinnedMesh}. However, any 3D object
+	 * can be used if it represents a hierarchy of bones (see {@link Bone}).
+	 */
 	constructor( object ) {
 
 		const bones = getBoneList( object );
@@ -22,9 +37,6 @@ class SkeletonHelper extends LineSegments {
 		const vertices = [];
 		const colors = [];
 
-		const color1 = new Color( 0, 0, 1 );
-		const color2 = new Color( 0, 1, 0 );
-
 		for ( let i = 0; i < bones.length; i ++ ) {
 
 			const bone = bones[ i ];
@@ -33,8 +45,8 @@ class SkeletonHelper extends LineSegments {
 
 				vertices.push( 0, 0, 0 );
 				vertices.push( 0, 0, 0 );
-				colors.push( color1.r, color1.g, color1.b );
-				colors.push( color2.r, color2.g, color2.b );
+				colors.push( 0, 0, 0 );
+				colors.push( 0, 0, 0 );
 
 			}
 
@@ -47,16 +59,41 @@ class SkeletonHelper extends LineSegments {
 
 		super( geometry, material );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isSkeletonHelper = true;
 
 		this.type = 'SkeletonHelper';
 
+		/**
+		 * The object being visualized.
+		 *
+		 * @type {Object3D}
+		 */
 		this.root = object;
+
+		/**
+		 * The list of bones that the helper visualizes.
+		 *
+		 * @type {Array<Bone>}
+		 */
 		this.bones = bones;
 
 		this.matrix = object.matrixWorld;
 		this.matrixAutoUpdate = false;
 
+		// colors
+
+		const color1 = new Color( 0x0000ff );
+		const color2 = new Color( 0x00ff00 );
+
+		this.setColors( color1, color2 );
+
 	}
 
 	updateMatrixWorld( force ) {
@@ -94,6 +131,35 @@ class SkeletonHelper extends LineSegments {
 
 	}
 
+	/**
+	 * Defines the colors of the helper.
+	 *
+	 * @param {Color} color1 - The first line color for each bone.
+	 * @param {Color} color2 - The second line color for each bone.
+	 * @return {SkeletonHelper} A reference to this helper.
+	 */
+	setColors( color1, color2 ) {
+
+		const geometry = this.geometry;
+		const colorAttribute = geometry.getAttribute( 'color' );
+
+		for ( let i = 0; i < colorAttribute.count; i += 2 ) {
+
+			colorAttribute.setXYZ( i, color1.r, color1.g, color1.b );
+			colorAttribute.setXYZ( i + 1, color2.r, color2.g, color2.b );
+
+		}
+
+		colorAttribute.needsUpdate = true;
+
+		return this;
+
+	}
+
+	/**
+	 * Frees the GPU-related resources allocated by this instance. Call this
+	 * method whenever this instance is no longer used in your app.
+	 */
 	dispose() {
 
 		this.geometry.dispose();
@@ -116,7 +182,7 @@ function getBoneList( object ) {
 
 	for ( let i = 0; i < object.children.length; i ++ ) {
 
-		boneList.push.apply( boneList, getBoneList( object.children[ i ] ) );
+		boneList.push( ...getBoneList( object.children[ i ] ) );
 
 	}
 

package/src/helpers/SpotLightHelper.js

@@ -7,16 +7,51 @@ import { BufferGeometry } from '../core/BufferGeometry.js';
 
 const _vector = /*@__PURE__*/ new Vector3();
 
+/**
+ * This displays a cone shaped helper object for a {@link SpotLight}.
+ *
+ * When the spot light or its target are transformed or light properties are
+ * changed, it's necessary to call the `update()` method of the respective helper.
+ *
+ * ```js
+ * const spotLight = new THREE.SpotLight( 0xffffff );
+ * spotLight.position.set( 10, 10, 10 );
+ * scene.add( spotLight );
+ *
+ * const spotLightHelper = new THREE.SpotLightHelper( spotLight );
+ * scene.add( spotLightHelper );
+ * ```
+ *
+ * @augments Object3D
+ */
 class SpotLightHelper extends Object3D {
 
+	/**
+	 * Constructs a new spot light helper.
+	 *
+	 * @param {HemisphereLight} light - The light to be visualized.
+	 * @param {number|Color|string} [color] - The helper's color. If not set, the helper will take
+	 * the color of the light.
+	 */
 	constructor( light, color ) {
 
 		super();
 
+		/**
+		 * The light being visualized.
+		 *
+		 * @type {SpotLight}
+		 */
 		this.light = light;
 
 		this.matrixAutoUpdate = false;
 
+		/**
+		 * The color parameter passed in the constructor.
+		 * If not set, the helper will take the color of the light.
+		 *
+		 * @type {number|Color|string}
+		 */
 		this.color = color;
 
 		this.type = 'SpotLightHelper';
@@ -54,6 +89,10 @@ class SpotLightHelper extends Object3D {
 
 	}
 
+	/**
+	 * Frees the GPU-related resources allocated by this instance. Call this
+	 * method whenever this instance is no longer used in your app.
+	 */
 	dispose() {
 
 		this.cone.geometry.dispose();
@@ -61,6 +100,10 @@ class SpotLightHelper extends Object3D {
 
 	}
 
+	/**
+	 * Updates the helper to match the position and direction of the
+	 * light being visualized.
+	 */
 	update() {
 
 		this.light.updateWorldMatrix( true, false );

package/src/lights/AmbientLight.js

@@ -1,11 +1,36 @@
 import { Light } from './Light.js';
 
+/**
+ * This light globally illuminates all objects in the scene equally.
+ *
+ * It cannot be used to cast shadows as it does not have a direction.
+ *
+ * ```js
+ * const light = new THREE.AmbientLight( 0x404040 ); // soft white light
+ * scene.add( light );
+ * ```
+ *
+ * @augments Light
+ */
 class AmbientLight extends Light {
 
+	/**
+	 * Constructs a new ambient light.
+	 *
+	 * @param {(number|Color|string)} [color=0xffffff] - The light's color.
+	 * @param {number} [intensity=1] - The light's strength/intensity.
+	 */
 	constructor( color, intensity ) {
 
 		super( color, intensity );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isAmbientLight = true;
 
 		this.type = 'AmbientLight';

package/src/lights/DirectionalLight.js

@@ -2,12 +2,52 @@ import { Light } from './Light.js';
 import { DirectionalLightShadow } from './DirectionalLightShadow.js';
 import { Object3D } from '../core/Object3D.js';
 
+/**
+ * A light that gets emitted in a specific direction. This light will behave
+ * as though it is infinitely far away and the rays produced from it are all
+ * parallel. The common use case for this is to simulate daylight; the sun is
+ * far enough away that its position can be considered to be infinite, and
+ * all light rays coming from it are parallel.
+ *
+ * A common point of confusion for directional lights is that setting the
+ * rotation has no effect. This is because three.js's DirectionalLight is the
+ * equivalent to what is often called a 'Target Direct Light' in other
+ * applications.
+ *
+ * This means that its direction is calculated as pointing from the light's
+ * {@link Object3D#position} to the {@link DirectionalLight#target} position
+ * (as opposed to a 'Free Direct Light' that just has a rotation
+ * component).
+ *
+ * This light can cast shadows - see the {@link DirectionalLightShadow} for details.
+ *
+ * ```js
+ * // White directional light at half intensity shining from the top.
+ * const directionalLight = new THREE.DirectionalLight( 0xffffff, 0.5 );
+ * scene.add( directionalLight );
+ * ```
+ *
+ * @augments Light
+ */
 class DirectionalLight extends Light {
 
+	/**
+	 * Constructs a new directional light.
+	 *
+	 * @param {(number|Color|string)} [color=0xffffff] - The light's color.
+	 * @param {number} [intensity=1] - The light's strength/intensity.
+	 */
 	constructor( color, intensity ) {
 
 		super( color, intensity );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isDirectionalLight = true;
 
 		this.type = 'DirectionalLight';
@@ -15,14 +55,33 @@ class DirectionalLight extends Light {
 		this.position.copy( Object3D.DEFAULT_UP );
 		this.updateMatrix();
 
+		/**
+		 * The directional light points from its position to the
+		 * target's position.
+		 *
+		 * For the target's position to be changed to anything other
+		 * than the default, it must be added to the scene.
+		 *
+		 * It is also possible to set the target to be another 3D object
+		 * in the scene. The light will now track the target object.
+		 *
+		 * @type {Object3D}
+		 */
 		this.target = new Object3D();
 
+		/**
+		 * This property holds the light's shadow configuration.
+		 *
+		 * @type {DirectionalLightShadow}
+		 */
 		this.shadow = new DirectionalLightShadow();
 
 	}
 
 	dispose() {
 
+		super.dispose();
+
 		this.shadow.dispose();
 
 	}
@@ -38,6 +97,17 @@ class DirectionalLight extends Light {
 
 	}
 
+	toJSON( meta ) {
+
+		const data = super.toJSON( meta );
+
+		data.object.shadow = this.shadow.toJSON();
+		data.object.target = this.target.uuid;
+
+		return data;
+
+	}
+
 }
 
 export { DirectionalLight };

package/src/lights/DirectionalLightShadow.js

@@ -1,12 +1,27 @@
 import { LightShadow } from './LightShadow.js';
 import { OrthographicCamera } from '../cameras/OrthographicCamera.js';
 
+/**
+ * Represents the shadow configuration of directional lights.
+ *
+ * @augments LightShadow
+ */
 class DirectionalLightShadow extends LightShadow {
 
+	/**
+	 * Constructs a new directional light shadow.
+	 */
 	constructor() {
 
 		super( new OrthographicCamera( - 5, 5, 5, - 5, 0.5, 500 ) );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isDirectionalLightShadow = true;
 
 	}

package/src/lights/HemisphereLight.js

@@ -2,12 +2,39 @@ import { Light } from './Light.js';
 import { Color } from '../math/Color.js';
 import { Object3D } from '../core/Object3D.js';
 
+/**
+ * A light source positioned directly above the scene, with color fading from
+ * the sky color to the ground color.
+ *
+ * This light cannot be used to cast shadows.
+ *
+ * ```js
+ * const light = new THREE.HemisphereLight( 0xffffbb, 0x080820, 1 );
+ * scene.add( light );
+ * ```
+ *
+ * @augments Light
+ */
 class HemisphereLight extends Light {
 
+	/**
+	 * Constructs a new hemisphere light.
+	 *
+	 * @param {(number|Color|string)} [skyColor=0xffffff] - The light's sky color.
+	 * @param {(number|Color|string)} [groundColor=0xffffff] - The light's ground color.
+	 * @param {number} [intensity=1] - The light's strength/intensity.
+	 */
 	constructor( skyColor, groundColor, intensity ) {
 
 		super( skyColor, intensity );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isHemisphereLight = true;
 
 		this.type = 'HemisphereLight';
@@ -15,6 +42,11 @@ class HemisphereLight extends Light {
 		this.position.copy( Object3D.DEFAULT_UP );
 		this.updateMatrix();
 
+		/**
+		 * The light's ground color.
+		 *
+		 * @type {Color}
+		 */
 		this.groundColor = new Color( groundColor );
 
 	}
@@ -29,6 +61,16 @@ class HemisphereLight extends Light {
 
 	}
 
+	toJSON( meta ) {
+
+		const data = super.toJSON( meta );
+
+		data.object.groundColor = this.groundColor.getHex();
+
+		return data;
+
+	}
+
 }
 
 export { HemisphereLight };

package/src/lights/Light.js

@@ -1,24 +1,60 @@
 import { Object3D } from '../core/Object3D.js';
 import { Color } from '../math/Color.js';
 
+/**
+ * Abstract base class for lights - all other light types inherit the
+ * properties and methods described here.
+ *
+ * @abstract
+ * @augments Object3D
+ */
 class Light extends Object3D {
 
+	/**
+	 * Constructs a new light.
+	 *
+	 * @param {(number|Color|string)} [color=0xffffff] - The light's color.
+	 * @param {number} [intensity=1] - The light's strength/intensity.
+	 */
 	constructor( color, intensity = 1 ) {
 
 		super();
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isLight = true;
 
 		this.type = 'Light';
 
+		/**
+		 * The light's color.
+		 *
+		 * @type {Color}
+		 */
 		this.color = new Color( color );
+
+		/**
+		 * The light's intensity.
+		 *
+		 * @type {number}
+		 * @default 1
+		 */
 		this.intensity = intensity;
 
 	}
 
+	/**
+	 * Frees the GPU-related resources allocated by this instance. Call this
+	 * method whenever this instance is no longer used in your app.
+	 */
 	dispose() {
 
-		// Empty here in base class; some subclasses override.
+		this.dispatchEvent( { type: 'dispose' } );
 
 	}
 
@@ -40,16 +76,6 @@ class Light extends Object3D {
 		data.object.color = this.color.getHex();
 		data.object.intensity = this.intensity;
 
-		if ( this.groundColor !== undefined ) data.object.groundColor = this.groundColor.getHex();
-
-		if ( this.distance !== undefined ) data.object.distance = this.distance;
-		if ( this.angle !== undefined ) data.object.angle = this.angle;
-		if ( this.decay !== undefined ) data.object.decay = this.decay;
-		if ( this.penumbra !== undefined ) data.object.penumbra = this.penumbra;
-
-		if ( this.shadow !== undefined ) data.object.shadow = this.shadow.toJSON();
-		if ( this.target !== undefined ) data.object.target = this.target.uuid;
-
 		return data;
 
 	}

package/src/lights/LightProbe.js

@@ -1,14 +1,51 @@
 import { SphericalHarmonics3 } from '../math/SphericalHarmonics3.js';
 import { Light } from './Light.js';
 
+/**
+ * Light probes are an alternative way of adding light to a 3D scene. Unlike
+ * classical light sources (e.g. directional, point or spot lights), light
+ * probes do not emit light. Instead they store information about light
+ * passing through 3D space. During rendering, the light that hits a 3D
+ * object is approximated by using the data from the light probe.
+ *
+ * Light probes are usually created from (radiance) environment maps. The
+ * class {@link LightProbeGenerator} can be used to create light probes from
+ * cube textures or render targets. However, light estimation data could also
+ * be provided in other forms e.g. by WebXR. This enables the rendering of
+ * augmented reality content that reacts to real world lighting.
+ *
+ * The current probe implementation in three.js supports so-called diffuse
+ * light probes. This type of light probe is functionally equivalent to an
+ * irradiance environment map.
+ *
+ * @augments Light
+ */
 class LightProbe extends Light {
 
+	/**
+	 * Constructs a new light probe.
+	 *
+	 * @param {SphericalHarmonics3} sh - The spherical harmonics which represents encoded lighting information.
+	 * @param {number} [intensity=1] - The light's strength/intensity.
+	 */
 	constructor( sh = new SphericalHarmonics3(), intensity = 1 ) {
 
 		super( undefined, intensity );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isLightProbe = true;
 
+		/**
+		 * A light probe uses spherical harmonics to encode lighting information.
+		 *
+		 * @type {SphericalHarmonics3}
+		 */
 		this.sh = sh;
 
 	}
@@ -23,15 +60,6 @@ class LightProbe extends Light {
 
 	}
 
-	fromJSON( json ) {
-
-		this.intensity = json.intensity; // TODO: Move this bit to Light.fromJSON();
-		this.sh.fromArray( json.sh );
-
-		return this;
-
-	}
-
 	toJSON( meta ) {
 
 		const data = super.toJSON( meta );