@plastic-software/three 0.174.0 → 0.175.0

package/examples/jsm/modifiers/CurveModifier.js

@@ -19,10 +19,11 @@ import {
 /**
  * Make a new DataTexture to store the descriptions of the curves.
  *
- * @param { number } numberOfCurves the number of curves needed to be described by this texture.
- * @returns { DataTexture }
+ * @private
+ * @param {number} numberOfCurves - The number of curves needed to be described by this texture.
+ * @returns {DataTexture}
  */
-export function initSplineTexture( numberOfCurves = 1 ) {
+function initSplineTexture( numberOfCurves = 1 ) {
 
 	const dataArray = new Uint16Array( TEXTURE_WIDTH * TEXTURE_HEIGHT * numberOfCurves * CHANNELS );
 	const dataTexture = new DataTexture(
@@ -44,13 +45,14 @@ export function initSplineTexture( numberOfCurves = 1 ) {
 }
 
 /**
- * Write the curve description to the data texture
+ * Write the curve description to the data texture.
  *
- * @param { DataTexture } texture The DataTexture to write to
- * @param { Curve } splineCurve The curve to describe
- * @param { number } offset Which curve slot to write to
+ * @private
+ * @param {DataTexture} texture - The data texture to write to.
+ * @param {Curve} splineCurve - The curve to describe.
+ * @param {number} offset - Which curve slot to write to.
  */
-export function updateSplineTexture( texture, splineCurve, offset = 0 ) {
+function updateSplineTexture( texture, splineCurve, offset = 0 ) {
 
 	const numberOfPoints = Math.floor( TEXTURE_WIDTH * ( TEXTURE_HEIGHT / 4 ) );
 	splineCurve.arcLengthDivisions = numberOfPoints / 2;
@@ -78,7 +80,6 @@ export function updateSplineTexture( texture, splineCurve, offset = 0 ) {
 
 }
 
-
 function setTextureValue( texture, index, x, y, z, o ) {
 
 	const image = texture.image;
@@ -92,12 +93,12 @@ function setTextureValue( texture, index, x, y, z, o ) {
 }
 
 /**
- * Create a new set of uniforms for describing the curve modifier
+ * Create a new set of uniforms for describing the curve modifier.
  *
- * @param { DataTexture } splineTexture which holds the curve description
- * @returns { Object } The uniforms object to be used in the shader
+ * @param {DataTexture} splineTexture - Which holds the curve description.
+ * @returns {Object} The uniforms object to be used in the shader.
  */
-export function getUniforms( splineTexture ) {
+function getUniforms( splineTexture ) {
 
 	const uniforms = {
 		spineTexture: { value: splineTexture },
@@ -111,7 +112,7 @@ export function getUniforms( splineTexture ) {
 
 }
 
-export function modifyShader( material, uniforms, numberOfCurves = 1 ) {
+function modifyShader( material, uniforms, numberOfCurves = 1 ) {
 
 	if ( material.__ok ) return;
 	material.__ok = true;
@@ -198,13 +199,18 @@ vec3 transformedNormal = normalMatrix * (basis * objectNormal);
 }
 
 /**
- * A helper class for making meshes bend around curves
+ * A modifier for making meshes bend around curves.
+ *
+ * This module can only be used with {@link WebGLRenderer}. When using {@link WebGPURenderer},
+ * import the class from `CurveModifierGPU.js`.
  */
 export class Flow {
 
 	/**
-	 * @param {Mesh} mesh The mesh to clone and modify to bend around the curve
-	 * @param {number} numberOfCurves The amount of space that should preallocated for additional curves
+	 * Constructs a new Flow instance.
+	 *
+	 * @param {Mesh} mesh - The mesh to clone and modify to bend around the curve.
+	 * @param {number} numberOfCurves - The amount of space that should preallocated for additional curves.
 	 */
 	constructor( mesh, numberOfCurves = 1 ) {
 
@@ -252,9 +258,15 @@ export class Flow {
 
 	}
 
+	/**
+	 * Updates the curve for the given curve index.
+	 *
+	 * @param {number} index - The curve index.
+	 * @param {Curve} curve - The curve that should be used to bend the mesh.
+	 */
 	updateCurve( index, curve ) {
 
-		if ( index >= this.curveArray.length ) throw Error( 'Index out of range for Flow' );
+		if ( index >= this.curveArray.length ) throw Error( 'Flow: Index out of range.' );
 		const curveLength = curve.getLength();
 		this.uniforms.spineLength.value = curveLength;
 		this.curveLengthArray[ index ] = curveLength;
@@ -263,6 +275,11 @@ export class Flow {
 
 	}
 
+	/**
+	 * Moves the mesh along the curve.
+	 *
+	 * @param {number} amount - The offset.
+	 */
 	moveAlongCurve( amount ) {
 
 		this.uniforms.pathOffset.value += amount;
@@ -270,19 +287,25 @@ export class Flow {
 	}
 
 }
-const matrix = new Matrix4();
+
+const _matrix = new Matrix4();
 
 /**
- * A helper class for creating instanced versions of flow, where the instances are placed on the curve.
+ * An instanced version of {@link Flow} for making meshes bend around curves, where the instances are placed on the curve.
+ *
+ * This module can only be used with {@link WebGLRenderer}.
+ *
+ * @augments Flow
  */
 export class InstancedFlow extends Flow {
 
 	/**
+	 * Constructs a new InstancedFlow instance.
 	 *
-	 * @param {number} count The number of instanced elements
-	 * @param {number} curveCount The number of curves to preallocate for
-	 * @param {Geometry} geometry The geometry to use for the instanced mesh
-	 * @param {Material} material The material to use for the instanced mesh
+	 * @param {number} count - The number of instanced elements.
+	 * @param {number} curveCount - The number of curves to preallocate for.
+	 * @param {Geometry} geometry - The geometry to use for the instanced mesh.
+	 * @param {Material} material - The material to use for the instanced mesh.
 	 */
 	constructor( count, curveCount, geometry, material ) {
 
@@ -304,25 +327,25 @@ export class InstancedFlow extends Flow {
 	 * The extra information about which curve and curve position is stored in the translation components of the matrix for the instanced objects
 	 * This writes that information to the matrix and marks it as needing update.
 	 *
-	 * @param {number} index of the instanced element to update
+	 * @param {number} index - The index of tge instanced element to update.
 	 */
 	writeChanges( index ) {
 
-		matrix.makeTranslation(
+		_matrix.makeTranslation(
 			this.curveLengthArray[ this.whichCurve[ index ] ],
 			this.whichCurve[ index ],
 			this.offsets[ index ]
 		);
-		this.object3D.setMatrixAt( index, matrix );
+		this.object3D.setMatrixAt( index, _matrix );
 		this.object3D.instanceMatrix.needsUpdate = true;
 
 	}
 
 	/**
-	 * Move an individual element along the curve by a specific amount
+	 * Move an individual element along the curve by a specific amount.
 	 *
-	 * @param {number} index Which element to update
-	 * @param {number} offset Move by how much
+	 * @param {number} index - Which element to update.
+	 * @param {number} offset - The offset.
 	 */
 	moveIndividualAlongCurve( index, offset ) {
 
@@ -332,14 +355,14 @@ export class InstancedFlow extends Flow {
 	}
 
 	/**
-	 * Select which curve to use for an element
+	 * Select which curve to use for an element.
 	 *
-	 * @param {number} index the index of the instanced element to update
-	 * @param {number} curveNo the index of the curve it should use
+	 * @param {number} index - The index of the instanced element to update.
+	 * @param {number} curveNo - The index of the curve it should use.
 	 */
 	setCurve( index, curveNo ) {
 
-		if ( isNaN( curveNo ) ) throw Error( 'curve index being set is Not a Number (NaN)' );
+		if ( isNaN( curveNo ) ) throw Error( 'InstancedFlow: Curve index being set is Not a Number (NaN).' );
 		this.whichCurve[ index ] = curveNo;
 		this.writeChanges( index );
 

package/examples/jsm/modifiers/CurveModifierGPU.js

@@ -19,10 +19,11 @@ import { modelWorldMatrix, normalLocal, vec2, vec3, vec4, mat3, varyingProperty,
 /**
  * Make a new DataTexture to store the descriptions of the curves.
  *
- * @param { number } [numberOfCurves=1] the number of curves needed to be described by this texture.
- * @returns { DataTexture } The new DataTexture
+ * @private
+ * @param {number} [numberOfCurves=1] - The number of curves needed to be described by this texture.
+ * @returns  {DataTexture} The new data texture.
  */
-export function initSplineTexture( numberOfCurves = 1 ) {
+function initSplineTexture( numberOfCurves = 1 ) {
 
 	const dataArray = new Uint16Array( TEXTURE_WIDTH * TEXTURE_HEIGHT * numberOfCurves * CHANNELS );
 	const dataTexture = new DataTexture(
@@ -44,13 +45,14 @@ export function initSplineTexture( numberOfCurves = 1 ) {
 }
 
 /**
- * Write the curve description to the data texture
+ * Write the curve description to the data texture.
  *
- * @param { DataTexture } texture The DataTexture to write to
- * @param { Curve } splineCurve The curve to describe
- * @param { number } offset Which curve slot to write to
+ * @private
+ * @param {DataTexture} texture - The data texture to write to.
+ * @param {Curve} splineCurve - The curve to describe.
+ * @param {number} [offset=0] - Which curve slot to write to.
  */
-export function updateSplineTexture( texture, splineCurve, offset = 0 ) {
+function updateSplineTexture( texture, splineCurve, offset = 0 ) {
 
 	const numberOfPoints = Math.floor( TEXTURE_WIDTH * ( TEXTURE_HEIGHT / 4 ) );
 	splineCurve.arcLengthDivisions = numberOfPoints / 2;
@@ -93,12 +95,13 @@ function setTextureValue( texture, index, x, y, z, o ) {
 }
 
 /**
- * Create a new set of uniforms for describing the curve modifier
+ * Create a new set of uniforms for describing the curve modifier.
  *
- * @param { DataTexture } splineTexture which holds the curve description
- * @returns { Object } The uniforms object
+ * @private
+ * @param {DataTexture} splineTexture - Which holds the curve description.
+ * @returns {Object} The uniforms object.
  */
-export function getUniforms( splineTexture ) {
+function getUniforms( splineTexture ) {
 
 	return {
 		spineTexture: splineTexture,
@@ -111,7 +114,7 @@ export function getUniforms( splineTexture ) {
 
 }
 
-export function modifyShader( material, uniforms, numberOfCurves ) {
+function modifyShader( material, uniforms, numberOfCurves ) {
 
 	const spineTexture = uniforms.spineTexture;
 
@@ -157,13 +160,18 @@ export function modifyShader( material, uniforms, numberOfCurves ) {
 }
 
 /**
- * A helper class for making meshes bend around curves
+ * A modifier for making meshes bend around curves.
+ *
+ * This module can only be used with {@link WebGPURenderer}. When using {@link WebGLRenderer},
+ * import the class from `CurveModifier.js`.
  */
 export class Flow {
 
 	/**
-	 * @param {Mesh} mesh The mesh to clone and modify to bend around the curve
-	 * @param {number} numberOfCurves The amount of space that should preallocated for additional curves
+	 * Constructs a new Flow instance.
+	 *
+	 * @param {Mesh} mesh - The mesh to clone and modify to bend around the curve.
+	 * @param {number} numberOfCurves - The amount of space that should preallocated for additional curves.
 	 */
 	constructor( mesh, numberOfCurves = 1 ) {
 
@@ -212,9 +220,15 @@ export class Flow {
 
 	}
 
+	/**
+	 * Updates the curve for the given curve index.
+	 *
+	 * @param {number} index - The curve index.
+	 * @param {Curve} curve - The curve that should be used to bend the mesh.
+	 */
 	updateCurve( index, curve ) {
 
-		if ( index >= this.curveArray.length ) throw Error( 'Index out of range for Flow' );
+		if ( index >= this.curveArray.length ) throw Error( 'Flow: Index out of range.' );
 
 		const curveLength = curve.getLength();
 
@@ -226,6 +240,11 @@ export class Flow {
 
 	}
 
+	/**
+	 * Moves the mesh along the curve.
+	 *
+	 * @param {number} amount - The offset.
+	 */
 	moveAlongCurve( amount ) {
 
 		this.uniforms.pathOffset += amount;

package/examples/jsm/modifiers/EdgeSplitModifier.js

@@ -9,8 +9,26 @@ const _A = new Vector3();
 const _B = new Vector3();
 const _C = new Vector3();
 
+/**
+ * The modifier can be used to split faces at sharp edges. This allows to compute
+ * normals without smoothing the edges which can lead to an improved visual result.
+ *
+ * ```js
+ * const modifier = new EdgeSplitModifier();
+ * geometry = modifier.modify( geometry, Math.PI * 0.4 );
+ * ```
+ */
 class EdgeSplitModifier {
 
+	/**
+	 * Returns a new, modified version of the given geometry by applying an edge-split operation.
+	 * Please note that the resulting geometry is always indexed.
+	 *
+	 * @param {BufferGeometry} geometry - The geometry to modify.
+	 * @param {number} cutOffAngle - The cut off angle in radians.
+	 * @param {boolean} [tryKeepNormals=true] - Whether to try to keep normals or not.
+	 * @return {BufferGeometry} A new, modified geometry.
+	 */
 	modify( geometry, cutOffAngle, tryKeepNormals = true ) {
 
 		function computeNormals() {

package/examples/jsm/modifiers/SimplifyModifier.js

@@ -8,18 +8,30 @@ import {
 } from 'three';
 import * as BufferGeometryUtils from '../utils/BufferGeometryUtils.js';
 
-/**
- *	Simplification Geometry Modifier
- *    - based on code and technique
- *	  - by Stan Melax in 1998
- *	  - Progressive Mesh type Polygon Reduction Algorithm
- *    - http://www.melax.com/polychop/
- */
-
 const _cb = new Vector3(), _ab = new Vector3();
 
+/**
+ * This class can be used to modify a geometry by simplifying it. A typical use
+ * case for such a modifier is automatic LOD generation.
+ *
+ * The implementation is based on [Progressive Mesh type Polygon Reduction Algorithm]{@link https://web.archive.org/web/20230610044040/http://www.melax.com/polychop/}
+ * by Stan Melax in 1998.
+ *
+ * ```js
+ * const modifier = new SimplifyModifier();
+ * geometry = modifier.modify( geometry );
+ * ```
+ */
 class SimplifyModifier {
 
+	/**
+	 * Returns a new, modified version of the given geometry by applying a simplification.
+	 * Please note that the resulting geometry is always non-indexed.
+	 *
+	 * @param {BufferGeometry} geometry - The geometry to modify.
+	 * @param {number} count - The number of vertices to remove.
+	 * @return {BufferGeometry} A new, modified geometry.
+	 */
 	modify( geometry, count ) {
 
 		geometry = geometry.clone();

package/examples/jsm/modifiers/TessellateModifier.js

@@ -7,18 +7,49 @@ import {
 } from 'three';
 
 /**
- * Break faces with edges longer than maxEdgeLength
+ * This class can be used to modify a geometry by breaking its edges if they
+ * are longer than maximum length.
+ *
+ * ```js
+ * const modifier = new TessellateModifier( 8, 6 );
+ * geometry = modifier.modify( geometry );
+ * ```
  */
-
 class TessellateModifier {
 
+	/**
+	 * Constructs a new Tessellate modifier.
+	 *
+	 * @param {number} [maxEdgeLength=0.1] - The maximum edge length.
+	 * @param {number} [maxIterations=6] - The number of iterations.
+	 */
 	constructor( maxEdgeLength = 0.1, maxIterations = 6 ) {
 
+		/**
+		 * The maximum edge length.
+		 *
+		 * @type {number}
+		 * @default 0.1
+		 */
 		this.maxEdgeLength = maxEdgeLength;
+
+		/**
+		 * The maximum edge length.
+		 *
+		 * @type {number}
+		 * @default 0.1
+		 */
 		this.maxIterations = maxIterations;
 
 	}
 
+	/**
+	 * Returns a new, modified version of the given geometry by applying a tesselation.
+	 * Please note that the resulting geometry is always non-indexed.
+	 *
+	 * @param {BufferGeometry} geometry - The geometry to modify.
+	 * @return {BufferGeometry} A new, modified geometry.
+	 */
 	modify( geometry ) {
 
 		if ( geometry.index !== null ) {

package/examples/jsm/objects/GroundedSkybox.js

@@ -1,14 +1,32 @@
 import { Mesh, MeshBasicMaterial, SphereGeometry, Vector3 } from 'three';
 
 /**
- * A ground-projected skybox. The height is how far the camera that took the photo was above the ground -
- * a larger value will magnify the downward part of the image. By default the object is centered at the camera,
- * so it is often helpful to set skybox.position.y = height to put the ground at the origin. Set the radius
- * large enough to ensure your user's camera stays inside.
+ * A ground-projected skybox.
+ *
+ * By default the object is centered at the camera, so it is often helpful to set
+ * `skybox.position.y = height` to put the ground at the origin.
+ *
+ * ```js
+ * const height = 15, radius = 100;
+ *
+ * const skybox = new GroundedSkybox( envMap, height, radius );
+ * skybox.position.y = height;
+ * scene.add( skybox );
+ * ```
+ *
+ * @augments Mesh
  */
-
 class GroundedSkybox extends Mesh {
 
+	/**
+	 * Constructs a new ground-projected skybox.
+	 *
+	 * @param {Texture} map - The environment map to use.
+	 * @param {number} height - The height is how far the camera that took the photo was above the ground.
+	 * A larger value will magnify the downward part of the image.
+	 * @param {number} radius - The radius of the skybox. Must be large enough to ensure the scene's camera stays inside.
+	 * @param {number} [resolution=128] - The geometry resolution of the skybox.
+	 */
 	constructor( map, height, radius, resolution = 128 ) {
 
 		if ( height <= 0 || radius <= 0 || resolution <= 0 ) {

package/examples/jsm/objects/Lensflare.js

@@ -15,16 +15,59 @@ import {
 	Vector4
 } from 'three';
 
+/**
+ * Creates a simulated lens flare that tracks a light.
+ *
+ * Note that this class can only be used with {@link WebGLRenderer}.
+ * When using {@link WebGPURenderer}, use {@link LensflareMesh}.
+ *
+ * ```js
+ * const light = new THREE.PointLight( 0xffffff, 1.5, 2000 );
+ *
+ * const lensflare = new Lensflare();
+ * lensflare.addElement( new LensflareElement( textureFlare0, 512, 0 ) );
+ * lensflare.addElement( new LensflareElement( textureFlare1, 512, 0 ) );
+ * lensflare.addElement( new LensflareElement( textureFlare2, 60, 0.6 ) );
+ *
+ * light.add( lensflare );
+ * ```
+ *
+ * @augments Mesh
+ */
 class Lensflare extends Mesh {
 
+	/**
+	 * Constructs a new lensflare.
+	 */
 	constructor() {
 
 		super( Lensflare.Geometry, new MeshBasicMaterial( { opacity: 0, transparent: true } ) );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isLensflare = true;
 
 		this.type = 'Lensflare';
+
+		/**
+		 * Overwritten to disable view-frustum culling by default.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.frustumCulled = false;
+
+		/**
+		 * Overwritten to make sure lensflares a rendered last.
+		 *
+		 * @type {number}
+		 * @default Infinity
+		 */
 		this.renderOrder = Infinity;
 
 		//
@@ -149,6 +192,11 @@ class Lensflare extends Mesh {
 
 		const mesh2 = new Mesh( geometry, material2 );
 
+		/**
+		 * Adds the given lensflare element to this instance.
+		 *
+		 * @param {LensflareElement} element - The element to add.
+		 */
 		this.addElement = function ( element ) {
 
 			elements.push( element );
@@ -263,6 +311,10 @@ class Lensflare extends Mesh {
 
 		};
 
+		/**
+		 * Frees the GPU-related resources allocated by this instance. Call this
+		 * method whenever this instance is no longer used in your app.
+		 */
 		this.dispose = function () {
 
 			material1a.dispose();
@@ -284,15 +336,52 @@ class Lensflare extends Mesh {
 
 }
 
-//
-
+/**
+ * Represents a single flare that can be added to a {@link Lensflare} container.
+ */
 class LensflareElement {
 
+	/**
+	 * Constructs a new lensflare element.
+	 *
+	 * @param {Texture} texture - The flare's texture.
+	 * @param {number} [size=1] - The size in pixels.
+	 * @param {number} [distance=0] - The normalized distance (`[0,1]`) from the light source.
+	 * A value of `0` means the flare is located at light source.
+	 * @param {Color} [color] - The flare's color
+	 */
 	constructor( texture, size = 1, distance = 0, color = new Color( 0xffffff ) ) {
 
+		/**
+		 * The flare's texture.
+		 *
+		 * @type {Texture}
+		 */
 		this.texture = texture;
+
+		/**
+		 * The size in pixels.
+		 *
+		 * @type {number}
+		 * @default 1
+		 */
 		this.size = size;
+
+		/**
+		 * The normalized distance (`[0,1]`) from the light source.
+		 * A value of `0` means the flare is located at light source.
+		 *
+		 * @type {number}
+		 * @default 0
+		 */
 		this.distance = distance;
+
+		/**
+		 * The flare's color
+		 *
+		 * @type {Color}
+		 * @default (1,1,1)
+		 */
 		this.color = color;
 
 	}

package/examples/jsm/objects/LensflareMesh.js

@@ -18,16 +18,59 @@ import {
 
 import { texture, textureLoad, uv, ivec2, vec2, vec4, positionGeometry, reference, varyingProperty, materialReference, Fn } from 'three/tsl';
 
+/**
+ * Creates a simulated lens flare that tracks a light.
+ *
+ * Note that this class can only be used with {@link WebGPURenderer}.
+ * When using {@link WebGLRenderer}, use {@link Lensflare}.
+ *
+ * ```js
+ * const light = new THREE.PointLight( 0xffffff, 1.5, 2000 );
+ *
+ * const lensflare = new LensflareMesh();
+ * lensflare.addElement( new LensflareElement( textureFlare0, 512, 0 ) );
+ * lensflare.addElement( new LensflareElement( textureFlare1, 512, 0 ) );
+ * lensflare.addElement( new LensflareElement( textureFlare2, 60, 0.6 ) );
+ *
+ * light.add( lensflare );
+ * ```
+ *
+ * @augments Mesh
+ */
 class LensflareMesh extends Mesh {
 
+	/**
+	 * Constructs a new lensflare mesh.
+	 */
 	constructor() {
 
 		super( LensflareMesh.Geometry, new MeshBasicNodeMaterial( { opacity: 0, transparent: true } ) );
 
-		this.isLensflare = true;
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
+		this.isLensflareMesh = true;
 
 		this.type = 'LensflareMesh';
+
+		/**
+		 * Overwritten to disable view-frustum culling by default.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.frustumCulled = false;
+
+		/**
+		 * Overwritten to make sure lensflares a rendered last.
+		 *
+		 * @type {number}
+		 * @default Infinity
+		 */
 		this.renderOrder = Infinity;
 
 		//
@@ -146,7 +189,11 @@ class LensflareMesh extends Mesh {
 
 		} )();
 
-
+		/**
+		 * Adds the given lensflare element to this instance.
+		 *
+		 * @param {LensflareElement} element - The element to add.
+		 */
 		this.addElement = function ( element ) {
 
 			elements.push( element );
@@ -264,6 +311,10 @@ class LensflareMesh extends Mesh {
 
 		};
 
+		/**
+		 * Frees the GPU-related resources allocated by this instance. Call this
+		 * method whenever this instance is no longer used in your app.
+		 */
 		this.dispose = function () {
 
 			material1a.dispose();