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

package/src/core/BufferAttribute.js

@@ -7,8 +7,25 @@ import { fromHalfFloat, toHalfFloat } from '../extras/DataUtils.js';
 const _vector = /*@__PURE__*/ new Vector3();
 const _vector2 = /*@__PURE__*/ new Vector2();
 
+let _id = 0;
+
+/**
+ * This class stores data for an attribute (such as vertex positions, face
+ * indices, normals, colors, UVs, and any custom attributes ) associated with
+ * a geometry, which allows for more efficient passing of data to the GPU.
+ *
+ * When working with vector-like data, the `fromBufferAttribute( attribute, index )`
+ * helper methods on vector and color class might be helpful. E.g. {@link Vector3#fromBufferAttribute}.
+ */
 class BufferAttribute {
 
+	/**
+	 * Constructs a new buffer attribute.
+	 *
+	 * @param {TypedArray} array - The array holding the attribute data.
+	 * @param {number} itemSize - The item size.
+	 * @param {boolean} [normalized=false] - Whether the data are normalized or not.
+	 */
 	constructor( array, itemSize, normalized = false ) {
 
 		if ( Array.isArray( array ) ) {
@@ -17,31 +34,133 @@ class BufferAttribute {
 
 		}
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isBufferAttribute = true;
 
+		/**
+		 * The ID of the buffer attribute.
+		 *
+		 * @name BufferAttribute#id
+		 * @type {number}
+		 * @readonly
+		 */
+		Object.defineProperty( this, 'id', { value: _id ++ } );
+
+		/**
+		 * The name of the buffer attribute.
+		 *
+		 * @type {string}
+		 */
 		this.name = '';
 
+		/**
+		 * The array holding the attribute data. It should have `itemSize * numVertices`
+		 * elements, where `numVertices` is the number of vertices in the associated geometry.
+		 *
+		 * @type {TypedArray}
+		 */
 		this.array = array;
+
+		/**
+		 * The number of values of the array that should be associated with a particular vertex.
+		 * For instance, if this attribute is storing a 3-component vector (such as a position,
+		 * normal, or color), then the value should be `3`.
+		 *
+		 * @type {number}
+		 */
 		this.itemSize = itemSize;
+
+		/**
+		 * Represents the number of items this buffer attribute stores. It is internally computed
+		 * by dividing the `array` length by the `itemSize`.
+		 *
+		 * @type {number}
+		 * @readonly
+		 */
 		this.count = array !== undefined ? array.length / itemSize : 0;
+
+		/**
+		 * Applies to integer data only. Indicates how the underlying data in the buffer maps to
+		 * the values in the GLSL code. For instance, if `array` is an instance of `UInt16Array`,
+		 * and `normalized` is `true`, the values `0 - +65535` in the array data will be mapped to
+		 * `0.0f - +1.0f` in the GLSL attribute. If `normalized` is `false`, the values will be converted
+		 * to floats unmodified, i.e. `65535` becomes `65535.0f`.
+		 *
+		 * @type {boolean}
+		 */
 		this.normalized = normalized;
 
+		/**
+		 * Defines the intended usage pattern of the data store for optimization purposes.
+		 *
+		 * Note: After the initial use of a buffer, its usage cannot be changed. Instead,
+		 * instantiate a new one and set the desired usage before the next render.
+		 *
+		 * @type {(StaticDrawUsage|DynamicDrawUsage|StreamDrawUsage|StaticReadUsage|DynamicReadUsage|StreamReadUsage|StaticCopyUsage|DynamicCopyUsage|StreamCopyUsage)}
+		 * @default StaticDrawUsage
+		 */
 		this.usage = StaticDrawUsage;
+
+		/**
+		 * This can be used to only update some components of stored vectors (for example, just the
+		 * component related to color). Use the `addUpdateRange()` function to add ranges to this array.
+		 *
+		 * @type {Array<Object>}
+		 */
 		this.updateRanges = [];
+
+		/**
+		 * Configures the bound GPU type for use in shaders.
+		 *
+		 * Note: this only has an effect for integer arrays and is not configurable for float arrays.
+		 * For lower precision float types, use `Float16BufferAttribute`.
+		 *
+		 * @type {(FloatType|IntType)}
+		 * @default FloatType
+		 */
 		this.gpuType = FloatType;
 
+		/**
+		 * A version number, incremented every time the `needsUpdate` is set to `true`.
+		 *
+		 * @type {number}
+		 */
 		this.version = 0;
 
 	}
 
+	/**
+	 * A callback function that is executed after the renderer has transferred the attribute
+	 * array data to the GPU.
+	 */
 	onUploadCallback() {}
 
+	/**
+	 * Flag to indicate that this attribute has changed and should be re-sent to
+	 * the GPU. Set this to `true` when you modify the value of the array.
+	 *
+	 * @type {number}
+	 * @default false
+	 * @param {boolean} value
+	 */
 	set needsUpdate( value ) {
 
 		if ( value === true ) this.version ++;
 
 	}
 
+	/**
+	 * Sets the usage of this buffer attribute.
+	 *
+	 * @param {(StaticDrawUsage|DynamicDrawUsage|StreamDrawUsage|StaticReadUsage|DynamicReadUsage|StreamReadUsage|StaticCopyUsage|DynamicCopyUsage|StreamCopyUsage)} value - The usage to set.
+	 * @return {BufferAttribute} A reference to this buffer attribute.
+	 */
 	setUsage( value ) {
 
 		this.usage = value;
@@ -50,18 +169,33 @@ class BufferAttribute {
 
 	}
 
+	/**
+	 * Adds a range of data in the data array to be updated on the GPU.
+	 *
+	 * @param {number} start - Position at which to start update.
+	 * @param {number} count - The number of components to update.
+	 */
 	addUpdateRange( start, count ) {
 
 		this.updateRanges.push( { start, count } );
 
 	}
 
+	/**
+	 * Clears the update ranges.
+	 */
 	clearUpdateRanges() {
 
 		this.updateRanges.length = 0;
 
 	}
 
+	/**
+	 * Copies the values of the given buffer attribute to this instance.
+	 *
+	 * @param {BufferAttribute} source - The buffer attribute to copy.
+	 * @return {BufferAttribute} A reference to this instance.
+	 */
 	copy( source ) {
 
 		this.name = source.name;
@@ -77,6 +211,16 @@ class BufferAttribute {
 
 	}
 
+	/**
+	 * Copies a vector from the given buffer attribute to this one. The start
+	 * and destination position in the attribute buffers are represented by the
+	 * given indices.
+	 *
+	 * @param {number} index1 - The destination index into this buffer attribute.
+	 * @param {BufferAttribute} attribute - The buffer attribute to copy from.
+	 * @param {number} index2 - The source index into the given buffer attribute.
+	 * @return {BufferAttribute} A reference to this instance.
+	 */
 	copyAt( index1, attribute, index2 ) {
 
 		index1 *= this.itemSize;
@@ -92,6 +236,12 @@ class BufferAttribute {
 
 	}
 
+	/**
+	 * Copies the given array data into this buffer attribute.
+	 *
+	 * @param {(TypedArray|Array)} array - The array to copy.
+	 * @return {BufferAttribute} A reference to this instance.
+	 */
 	copyArray( array ) {
 
 		this.array.set( array );
@@ -100,6 +250,13 @@ class BufferAttribute {
 
 	}
 
+	/**
+	 * Applies the given 3x3 matrix to the given attribute. Works with
+	 * item size `2` and `3`.
+	 *
+	 * @param {Matrix3} m - The matrix to apply.
+	 * @return {BufferAttribute} A reference to this instance.
+	 */
 	applyMatrix3( m ) {
 
 		if ( this.itemSize === 2 ) {
@@ -130,6 +287,13 @@ class BufferAttribute {
 
 	}
 
+	/**
+	 * Applies the given 4x4 matrix to the given attribute. Only works with
+	 * item size `3`.
+	 *
+	 * @param {Matrix4} m - The matrix to apply.
+	 * @return {BufferAttribute} A reference to this instance.
+	 */
 	applyMatrix4( m ) {
 
 		for ( let i = 0, l = this.count; i < l; i ++ ) {
@@ -146,6 +310,13 @@ class BufferAttribute {
 
 	}
 
+	/**
+	 * Applies the given 3x3 normal matrix to the given attribute. Only works with
+	 * item size `3`.
+	 *
+	 * @param {Matrix3} m - The normal matrix to apply.
+	 * @return {BufferAttribute} A reference to this instance.
+	 */
 	applyNormalMatrix( m ) {
 
 		for ( let i = 0, l = this.count; i < l; i ++ ) {
@@ -162,6 +333,13 @@ class BufferAttribute {
 
 	}
 
+	/**
+	 * Applies the given 4x4 matrix to the given attribute. Only works with
+	 * item size `3` and with direction vectors.
+	 *
+	 * @param {Matrix4} m - The matrix to apply.
+	 * @return {BufferAttribute} A reference to this instance.
+	 */
 	transformDirection( m ) {
 
 		for ( let i = 0, l = this.count; i < l; i ++ ) {
@@ -178,6 +356,13 @@ class BufferAttribute {
 
 	}
 
+	/**
+	 * Sets the given array data in the buffer attribute.
+	 *
+	 * @param {(TypedArray|Array)} value - The array data to set.
+	 * @param {number} [offset=0] - The offset in this buffer attribute's array.
+	 * @return {BufferAttribute} A reference to this instance.
+	 */
 	set( value, offset = 0 ) {
 
 		// Matching BufferAttribute constructor, do not normalize the array.
@@ -187,6 +372,13 @@ class BufferAttribute {
 
 	}
 
+	/**
+	 * Returns the given component of the vector at the given index.
+	 *
+	 * @param {number} index - The index into the buffer attribute.
+	 * @param {number} component - The component index.
+	 * @return {number} The returned value.
+	 */
 	getComponent( index, component ) {
 
 		let value = this.array[ index * this.itemSize + component ];
@@ -197,6 +389,14 @@ class BufferAttribute {
 
 	}
 
+	/**
+	 * Sets the given value to the given component of the vector at the given index.
+	 *
+	 * @param {number} index - The index into the buffer attribute.
+	 * @param {number} component - The component index.
+	 * @param {number} value - The value to set.
+	 * @return {BufferAttribute} A reference to this instance.
+	 */
 	setComponent( index, component, value ) {
 
 		if ( this.normalized ) value = normalize( value, this.array );
@@ -207,6 +407,12 @@ class BufferAttribute {
 
 	}
 
+	/**
+	 * Returns the x component of the vector at the given index.
+	 *
+	 * @param {number} index - The index into the buffer attribute.
+	 * @return {number} The x component.
+	 */
 	getX( index ) {
 
 		let x = this.array[ index * this.itemSize ];
@@ -217,6 +423,13 @@ class BufferAttribute {
 
 	}
 
+	/**
+	 * Sets the x component of the vector at the given index.
+	 *
+	 * @param {number} index - The index into the buffer attribute.
+	 * @param {number} x - The value to set.
+	 * @return {BufferAttribute} A reference to this instance.
+	 */
 	setX( index, x ) {
 
 		if ( this.normalized ) x = normalize( x, this.array );
@@ -227,6 +440,12 @@ class BufferAttribute {
 
 	}
 
+	/**
+	 * Returns the y component of the vector at the given index.
+	 *
+	 * @param {number} index - The index into the buffer attribute.
+	 * @return {number} The y component.
+	 */
 	getY( index ) {
 
 		let y = this.array[ index * this.itemSize + 1 ];
@@ -237,6 +456,13 @@ class BufferAttribute {
 
 	}
 
+	/**
+	 * Sets the y component of the vector at the given index.
+	 *
+	 * @param {number} index - The index into the buffer attribute.
+	 * @param {number} y - The value to set.
+	 * @return {BufferAttribute} A reference to this instance.
+	 */
 	setY( index, y ) {
 
 		if ( this.normalized ) y = normalize( y, this.array );
@@ -247,6 +473,12 @@ class BufferAttribute {
 
 	}
 
+	/**
+	 * Returns the z component of the vector at the given index.
+	 *
+	 * @param {number} index - The index into the buffer attribute.
+	 * @return {number} The z component.
+	 */
 	getZ( index ) {
 
 		let z = this.array[ index * this.itemSize + 2 ];
@@ -257,6 +489,13 @@ class BufferAttribute {
 
 	}
 
+	/**
+	 * Sets the z component of the vector at the given index.
+	 *
+	 * @param {number} index - The index into the buffer attribute.
+	 * @param {number} z - The value to set.
+	 * @return {BufferAttribute} A reference to this instance.
+	 */
 	setZ( index, z ) {
 
 		if ( this.normalized ) z = normalize( z, this.array );
@@ -267,6 +506,12 @@ class BufferAttribute {
 
 	}
 
+	/**
+	 * Returns the w component of the vector at the given index.
+	 *
+	 * @param {number} index - The index into the buffer attribute.
+	 * @return {number} The w component.
+	 */
 	getW( index ) {
 
 		let w = this.array[ index * this.itemSize + 3 ];
@@ -277,6 +522,13 @@ class BufferAttribute {
 
 	}
 
+	/**
+	 * Sets the w component of the vector at the given index.
+	 *
+	 * @param {number} index - The index into the buffer attribute.
+	 * @param {number} w - The value to set.
+	 * @return {BufferAttribute} A reference to this instance.
+	 */
 	setW( index, w ) {
 
 		if ( this.normalized ) w = normalize( w, this.array );
@@ -287,6 +539,14 @@ class BufferAttribute {
 
 	}
 
+	/**
+	 * Sets the x and y component of the vector at the given index.
+	 *
+	 * @param {number} index - The index into the buffer attribute.
+	 * @param {number} x - The value for the x component to set.
+	 * @param {number} y - The value for the y component to set.
+	 * @return {BufferAttribute} A reference to this instance.
+	 */
 	setXY( index, x, y ) {
 
 		index *= this.itemSize;
@@ -305,6 +565,15 @@ class BufferAttribute {
 
 	}
 
+	/**
+	 * Sets the x, y and z component of the vector at the given index.
+	 *
+	 * @param {number} index - The index into the buffer attribute.
+	 * @param {number} x - The value for the x component to set.
+	 * @param {number} y - The value for the y component to set.
+	 * @param {number} z - The value for the z component to set.
+	 * @return {BufferAttribute} A reference to this instance.
+	 */
 	setXYZ( index, x, y, z ) {
 
 		index *= this.itemSize;
@@ -325,6 +594,16 @@ class BufferAttribute {
 
 	}
 
+	/**
+	 * Sets the x, y, z and w component of the vector at the given index.
+	 *
+	 * @param {number} index - The index into the buffer attribute.
+	 * @param {number} x - The value for the x component to set.
+	 * @param {number} y - The value for the y component to set.
+	 * @param {number} z - The value for the z component to set.
+	 * @param {number} w - The value for the w component to set.
+	 * @return {BufferAttribute} A reference to this instance.
+	 */
 	setXYZW( index, x, y, z, w ) {
 
 		index *= this.itemSize;
@@ -347,6 +626,14 @@ class BufferAttribute {
 
 	}
 
+	/**
+	 * Sets the given callback function that is executed after the Renderer has transferred
+	 * the attribute array data to the GPU. Can be used to perform clean-up operations after
+	 * the upload when attribute data are not needed anymore on the CPU side.
+	 *
+	 * @param {Function} callback - The `onUpload()` callback.
+	 * @return {BufferAttribute} A reference to this instance.
+	 */
 	onUpload( callback ) {
 
 		this.onUploadCallback = callback;
@@ -355,12 +642,22 @@ class BufferAttribute {
 
 	}
 
+	/**
+	 * Returns a new buffer attribute with copied values from this instance.
+	 *
+	 * @return {BufferAttribute} A clone of this instance.
+	 */
 	clone() {
 
 		return new this.constructor( this.array, this.itemSize ).copy( this );
 
 	}
 
+	/**
+	 * Serializes the buffer attribute into JSON.
+	 *
+	 * @return {Object} A JSON object representing the serialized buffer attribute.
+	 */
 	toJSON() {
 
 		const data = {
@@ -379,10 +676,21 @@ class BufferAttribute {
 
 }
 
-//
-
+/**
+ * Convenient class that can be used when creating a `Int8` buffer attribute with
+ * a plain `Array` instance.
+ *
+ * @augments BufferAttribute
+ */
 class Int8BufferAttribute extends BufferAttribute {
 
+	/**
+	 * Constructs a new buffer attribute.
+	 *
+	 * @param {(Array<number>|Int8Array)} array - The array holding the attribute data.
+	 * @param {number} itemSize - The item size.
+	 * @param {boolean} [normalized=false] - Whether the data are normalized or not.
+	 */
 	constructor( array, itemSize, normalized ) {
 
 		super( new Int8Array( array ), itemSize, normalized );
@@ -391,8 +699,21 @@ class Int8BufferAttribute extends BufferAttribute {
 
 }
 
+/**
+ * Convenient class that can be used when creating a `UInt8` buffer attribute with
+ * a plain `Array` instance.
+ *
+ * @augments BufferAttribute
+ */
 class Uint8BufferAttribute extends BufferAttribute {
 
+	/**
+	 * Constructs a new buffer attribute.
+	 *
+	 * @param {(Array<number>|Uint8Array)} array - The array holding the attribute data.
+	 * @param {number} itemSize - The item size.
+	 * @param {boolean} [normalized=false] - Whether the data are normalized or not.
+	 */
 	constructor( array, itemSize, normalized ) {
 
 		super( new Uint8Array( array ), itemSize, normalized );
@@ -401,8 +722,21 @@ class Uint8BufferAttribute extends BufferAttribute {
 
 }
 
+/**
+ * Convenient class that can be used when creating a `UInt8Clamped` buffer attribute with
+ * a plain `Array` instance.
+ *
+ * @augments BufferAttribute
+ */
 class Uint8ClampedBufferAttribute extends BufferAttribute {
 
+	/**
+	 * Constructs a new buffer attribute.
+	 *
+	 * @param {(Array<number>|Uint8ClampedArray)} array - The array holding the attribute data.
+	 * @param {number} itemSize - The item size.
+	 * @param {boolean} [normalized=false] - Whether the data are normalized or not.
+	 */
 	constructor( array, itemSize, normalized ) {
 
 		super( new Uint8ClampedArray( array ), itemSize, normalized );
@@ -411,8 +745,21 @@ class Uint8ClampedBufferAttribute extends BufferAttribute {
 
 }
 
+/**
+ * Convenient class that can be used when creating a `Int16` buffer attribute with
+ * a plain `Array` instance.
+ *
+ * @augments BufferAttribute
+ */
 class Int16BufferAttribute extends BufferAttribute {
 
+	/**
+	 * Constructs a new buffer attribute.
+	 *
+	 * @param {(Array<number>|Int16Array)} array - The array holding the attribute data.
+	 * @param {number} itemSize - The item size.
+	 * @param {boolean} [normalized=false] - Whether the data are normalized or not.
+	 */
 	constructor( array, itemSize, normalized ) {
 
 		super( new Int16Array( array ), itemSize, normalized );
@@ -421,8 +768,21 @@ class Int16BufferAttribute extends BufferAttribute {
 
 }
 
+/**
+ * Convenient class that can be used when creating a `UInt16` buffer attribute with
+ * a plain `Array` instance.
+ *
+ * @augments BufferAttribute
+ */
 class Uint16BufferAttribute extends BufferAttribute {
 
+	/**
+	 * Constructs a new buffer attribute.
+	 *
+	 * @param {(Array<number>|Uint16Array)} array - The array holding the attribute data.
+	 * @param {number} itemSize - The item size.
+	 * @param {boolean} [normalized=false] - Whether the data are normalized or not.
+	 */
 	constructor( array, itemSize, normalized ) {
 
 		super( new Uint16Array( array ), itemSize, normalized );
@@ -431,8 +791,21 @@ class Uint16BufferAttribute extends BufferAttribute {
 
 }
 
+/**
+ * Convenient class that can be used when creating a `Int32` buffer attribute with
+ * a plain `Array` instance.
+ *
+ * @augments BufferAttribute
+ */
 class Int32BufferAttribute extends BufferAttribute {
 
+	/**
+	 * Constructs a new buffer attribute.
+	 *
+	 * @param {(Array<number>|Int32Array)} array - The array holding the attribute data.
+	 * @param {number} itemSize - The item size.
+	 * @param {boolean} [normalized=false] - Whether the data are normalized or not.
+	 */
 	constructor( array, itemSize, normalized ) {
 
 		super( new Int32Array( array ), itemSize, normalized );
@@ -441,8 +814,21 @@ class Int32BufferAttribute extends BufferAttribute {
 
 }
 
+/**
+ * Convenient class that can be used when creating a `UInt32` buffer attribute with
+ * a plain `Array` instance.
+ *
+ * @augments BufferAttribute
+ */
 class Uint32BufferAttribute extends BufferAttribute {
 
+	/**
+	 * Constructs a new buffer attribute.
+	 *
+	 * @param {(Array<number>|Uint32Array)} array - The array holding the attribute data.
+	 * @param {number} itemSize - The item size.
+	 * @param {boolean} [normalized=false] - Whether the data are normalized or not.
+	 */
 	constructor( array, itemSize, normalized ) {
 
 		super( new Uint32Array( array ), itemSize, normalized );
@@ -451,8 +837,24 @@ class Uint32BufferAttribute extends BufferAttribute {
 
 }
 
+/**
+ * Convenient class that can be used when creating a `Float16` buffer attribute with
+ * a plain `Array` instance.
+ *
+ * This class automatically converts to and from FP16 via `Uint16Array` since `Float16Array`
+ * browser support is still problematic.
+ *
+ * @augments BufferAttribute
+ */
 class Float16BufferAttribute extends BufferAttribute {
 
+	/**
+	 * Constructs a new buffer attribute.
+	 *
+	 * @param {(Array<number>|Uint16Array)} array - The array holding the attribute data.
+	 * @param {number} itemSize - The item size.
+	 * @param {boolean} [normalized=false] - Whether the data are normalized or not.
+	 */
 	constructor( array, itemSize, normalized ) {
 
 		super( new Uint16Array( array ), itemSize, normalized );
@@ -603,9 +1005,21 @@ class Float16BufferAttribute extends BufferAttribute {
 
 }
 
-
+/**
+ * Convenient class that can be used when creating a `Float32` buffer attribute with
+ * a plain `Array` instance.
+ *
+ * @augments BufferAttribute
+ */
 class Float32BufferAttribute extends BufferAttribute {
 
+	/**
+	 * Constructs a new buffer attribute.
+	 *
+	 * @param {(Array<number>|Float32Array)} array - The array holding the attribute data.
+	 * @param {number} itemSize - The item size.
+	 * @param {boolean} [normalized=false] - Whether the data are normalized or not.
+	 */
 	constructor( array, itemSize, normalized ) {
 
 		super( new Float32Array( array ), itemSize, normalized );