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

package/src/core/InterleavedBuffer.js

@@ -1,33 +1,115 @@
-import * as MathUtils from '../math/MathUtils.js';
+import { generateUUID } from '../math/MathUtils.js';
 import { StaticDrawUsage } from '../constants.js';
 
+/**
+ * "Interleaved" means that multiple attributes, possibly of different types,
+ * (e.g., position, normal, uv, color) are packed into a single array buffer.
+ *
+ * An introduction into interleaved arrays can be found here: [Interleaved array basics](https://blog.tojicode.com/2011/05/interleaved-array-basics.html)
+ */
 class InterleavedBuffer {
 
+	/**
+	 * Constructs a new interleaved buffer.
+	 *
+	 * @param {TypedArray} array - A typed array with a shared buffer storing attribute data.
+	 * @param {number} stride - The number of typed-array elements per vertex.
+	 */
 	constructor( array, stride ) {
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isInterleavedBuffer = true;
 
+		/**
+		 * A typed array with a shared buffer storing attribute data.
+		 *
+		 * @type {TypedArray}
+		 */
 		this.array = array;
+
+		/**
+		 * The number of typed-array elements per vertex.
+		 *
+		 * @type {number}
+		 */
 		this.stride = stride;
+
+		/**
+		 * The total number of elements in the array
+		 *
+		 * @type {number}
+		 * @readonly
+		 */
 		this.count = array !== undefined ? array.length / stride : 0;
 
+		/**
+		 * 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 = [];
 
+		/**
+		 * A version number, incremented every time the `needsUpdate` is set to `true`.
+		 *
+		 * @type {number}
+		 */
 		this.version = 0;
 
-		this.uuid = MathUtils.generateUUID();
+		/**
+		 * The UUID of the interleaved buffer.
+		 *
+		 * @type {string}
+		 * @readonly
+		 */
+		this.uuid = generateUUID();
 
 	}
 
+	/**
+	 * 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 interleaved buffer.
+	 *
+	 * @param {(StaticDrawUsage|DynamicDrawUsage|StreamDrawUsage|StaticReadUsage|DynamicReadUsage|StreamReadUsage|StaticCopyUsage|DynamicCopyUsage|StreamCopyUsage)} value - The usage to set.
+	 * @return {InterleavedBuffer} A reference to this interleaved buffer.
+	 */
 	setUsage( value ) {
 
 		this.usage = value;
@@ -36,18 +118,33 @@ class InterleavedBuffer {
 
 	}
 
+	/**
+	 * 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 interleaved buffer to this instance.
+	 *
+	 * @param {InterleavedBuffer} source - The interleaved buffer to copy.
+	 * @return {InterleavedBuffer} A reference to this instance.
+	 */
 	copy( source ) {
 
 		this.array = new source.array.constructor( source.array );
@@ -59,14 +156,24 @@ class InterleavedBuffer {
 
 	}
 
-	copyAt( index1, attribute, index2 ) {
+	/**
+	 * Copies a vector from the given interleaved buffer 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 interleaved buffer.
+	 * @param {InterleavedBuffer} interleavedBuffer - The interleaved buffer to copy from.
+	 * @param {number} index2 - The source index into the given interleaved buffer.
+	 * @return {InterleavedBuffer} A reference to this instance.
+	 */
+	copyAt( index1, interleavedBuffer, index2 ) {
 
 		index1 *= this.stride;
-		index2 *= attribute.stride;
+		index2 *= interleavedBuffer.stride;
 
 		for ( let i = 0, l = this.stride; i < l; i ++ ) {
 
-			this.array[ index1 + i ] = attribute.array[ index2 + i ];
+			this.array[ index1 + i ] = interleavedBuffer.array[ index2 + i ];
 
 		}
 
@@ -74,6 +181,13 @@ class InterleavedBuffer {
 
 	}
 
+	/**
+	 * Sets the given array data in the interleaved buffer.
+	 *
+	 * @param {(TypedArray|Array)} value - The array data to set.
+	 * @param {number} [offset=0] - The offset in this interleaved buffer's array.
+	 * @return {InterleavedBuffer} A reference to this instance.
+	 */
 	set( value, offset = 0 ) {
 
 		this.array.set( value, offset );
@@ -82,6 +196,12 @@ class InterleavedBuffer {
 
 	}
 
+	/**
+	 * Returns a new interleaved buffer with copied values from this instance.
+	 *
+	 * @param {Object} [data] - An object with shared array buffers that allows to retain shared structures.
+	 * @return {InterleavedBuffer} A clone of this instance.
+	 */
 	clone( data ) {
 
 		if ( data.arrayBuffers === undefined ) {
@@ -92,7 +212,7 @@ class InterleavedBuffer {
 
 		if ( this.array.buffer._uuid === undefined ) {
 
-			this.array.buffer._uuid = MathUtils.generateUUID();
+			this.array.buffer._uuid = generateUUID();
 
 		}
 
@@ -111,6 +231,14 @@ class InterleavedBuffer {
 
 	}
 
+	/**
+	 * Sets the given callback function that is executed after the Renderer has transferred
+	 * the array data to the GPU. Can be used to perform clean-up operations after
+	 * the upload when data are not needed anymore on the CPU side.
+	 *
+	 * @param {Function} callback - The `onUpload()` callback.
+	 * @return {InterleavedBuffer} A reference to this instance.
+	 */
 	onUpload( callback ) {
 
 		this.onUploadCallback = callback;
@@ -119,6 +247,12 @@ class InterleavedBuffer {
 
 	}
 
+	/**
+	 * Serializes the interleaved buffer into JSON.
+	 *
+	 * @param {Object} [data] - An optional value holding meta information about the serialization.
+	 * @return {Object} A JSON object representing the serialized interleaved buffer.
+	 */
 	toJSON( data ) {
 
 		if ( data.arrayBuffers === undefined ) {
@@ -131,7 +265,7 @@ class InterleavedBuffer {
 
 		if ( this.array.buffer._uuid === undefined ) {
 
-			this.array.buffer._uuid = MathUtils.generateUUID();
+			this.array.buffer._uuid = generateUUID();
 
 		}
 

package/src/core/InterleavedBufferAttribute.js

@@ -1,43 +1,117 @@
 import { Vector3 } from '../math/Vector3.js';
 import { BufferAttribute } from './BufferAttribute.js';
 import { denormalize, normalize } from '../math/MathUtils.js';
+import { log } from '../utils.js';
 
 const _vector = /*@__PURE__*/ new Vector3();
 
+/**
+ * An alternative version of a buffer attribute with interleaved data. Interleaved
+ * attributes share a common interleaved data storage ({@link InterleavedBuffer}) and refer with
+ * different offsets into the buffer.
+ */
 class InterleavedBufferAttribute {
 
+	/**
+	 * Constructs a new interleaved buffer attribute.
+	 *
+	 * @param {InterleavedBuffer} interleavedBuffer - The buffer holding the interleaved data.
+	 * @param {number} itemSize - The item size.
+	 * @param {number} offset - The attribute offset into the buffer.
+	 * @param {boolean} [normalized=false] - Whether the data are normalized or not.
+	 */
 	constructor( interleavedBuffer, itemSize, offset, normalized = false ) {
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isInterleavedBufferAttribute = true;
 
+		/**
+		 * The name of the buffer attribute.
+		 *
+		 * @type {string}
+		 */
 		this.name = '';
 
+		/**
+		 * The buffer holding the interleaved data.
+		 *
+		 * @type {InterleavedBuffer}
+		 */
 		this.data = interleavedBuffer;
+
+		/**
+		 * The item size, see {@link BufferAttribute#itemSize}.
+		 *
+		 * @type {number}
+		 */
 		this.itemSize = itemSize;
+
+		/**
+		 * The attribute offset into the buffer.
+		 *
+		 * @type {number}
+		 */
 		this.offset = offset;
 
+		/**
+		 * Whether the data are normalized or not, see {@link BufferAttribute#normalized}
+		 *
+		 * @type {InterleavedBuffer}
+		 */
 		this.normalized = normalized;
 
 	}
 
+	/**
+	 * The item count of this buffer attribute.
+	 *
+	 * @type {number}
+	 * @readonly
+	 */
 	get count() {
 
 		return this.data.count;
 
 	}
 
+	/**
+	 * The array holding the interleaved buffer attribute data.
+	 *
+	 * @type {TypedArray}
+	 */
 	get array() {
 
 		return this.data.array;
 
 	}
 
+	/**
+	 * 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 ) {
 
 		this.data.needsUpdate = value;
 
 	}
 
+	/**
+	 * Applies the given 4x4 matrix to the given attribute. Only works with
+	 * item size `3`.
+	 *
+	 * @param {Matrix4} m - The matrix to apply.
+	 * @return {InterleavedBufferAttribute} A reference to this instance.
+	 */
 	applyMatrix4( m ) {
 
 		for ( let i = 0, l = this.data.count; i < l; i ++ ) {
@@ -54,6 +128,13 @@ class InterleavedBufferAttribute {
 
 	}
 
+	/**
+	 * 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 {InterleavedBufferAttribute} A reference to this instance.
+	 */
 	applyNormalMatrix( m ) {
 
 		for ( let i = 0, l = this.count; i < l; i ++ ) {
@@ -70,6 +151,13 @@ class InterleavedBufferAttribute {
 
 	}
 
+	/**
+	 * 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 {InterleavedBufferAttribute} A reference to this instance.
+	 */
 	transformDirection( m ) {
 
 		for ( let i = 0, l = this.count; i < l; i ++ ) {
@@ -86,6 +174,13 @@ class InterleavedBufferAttribute {
 
 	}
 
+	/**
+	 * 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.data.stride + this.offset + component ];
@@ -96,6 +191,14 @@ class InterleavedBufferAttribute {
 
 	}
 
+	/**
+	 * 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 {InterleavedBufferAttribute} A reference to this instance.
+	 */
 	setComponent( index, component, value ) {
 
 		if ( this.normalized ) value = normalize( value, this.array );
@@ -106,6 +209,13 @@ class InterleavedBufferAttribute {
 
 	}
 
+	/**
+	 * 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 {InterleavedBufferAttribute} A reference to this instance.
+	 */
 	setX( index, x ) {
 
 		if ( this.normalized ) x = normalize( x, this.array );
@@ -116,6 +226,13 @@ class InterleavedBufferAttribute {
 
 	}
 
+	/**
+	 * 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 {InterleavedBufferAttribute} A reference to this instance.
+	 */
 	setY( index, y ) {
 
 		if ( this.normalized ) y = normalize( y, this.array );
@@ -126,6 +243,13 @@ class InterleavedBufferAttribute {
 
 	}
 
+	/**
+	 * 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 {InterleavedBufferAttribute} A reference to this instance.
+	 */
 	setZ( index, z ) {
 
 		if ( this.normalized ) z = normalize( z, this.array );
@@ -136,6 +260,13 @@ class InterleavedBufferAttribute {
 
 	}
 
+	/**
+	 * 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 {InterleavedBufferAttribute} A reference to this instance.
+	 */
 	setW( index, w ) {
 
 		if ( this.normalized ) w = normalize( w, this.array );
@@ -146,6 +277,12 @@ class InterleavedBufferAttribute {
 
 	}
 
+	/**
+	 * 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.data.array[ index * this.data.stride + this.offset ];
@@ -156,6 +293,12 @@ class InterleavedBufferAttribute {
 
 	}
 
+	/**
+	 * 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.data.array[ index * this.data.stride + this.offset + 1 ];
@@ -166,6 +309,12 @@ class InterleavedBufferAttribute {
 
 	}
 
+	/**
+	 * 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.data.array[ index * this.data.stride + this.offset + 2 ];
@@ -176,6 +325,12 @@ class InterleavedBufferAttribute {
 
 	}
 
+	/**
+	 * 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.data.array[ index * this.data.stride + this.offset + 3 ];
@@ -186,6 +341,14 @@ class InterleavedBufferAttribute {
 
 	}
 
+	/**
+	 * 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 {InterleavedBufferAttribute} A reference to this instance.
+	 */
 	setXY( index, x, y ) {
 
 		index = index * this.data.stride + this.offset;
@@ -204,6 +367,15 @@ class InterleavedBufferAttribute {
 
 	}
 
+	/**
+	 * 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 {InterleavedBufferAttribute} A reference to this instance.
+	 */
 	setXYZ( index, x, y, z ) {
 
 		index = index * this.data.stride + this.offset;
@@ -224,6 +396,16 @@ class InterleavedBufferAttribute {
 
 	}
 
+	/**
+	 * 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 {InterleavedBufferAttribute} A reference to this instance.
+	 */
 	setXYZW( index, x, y, z, w ) {
 
 		index = index * this.data.stride + this.offset;
@@ -246,11 +428,19 @@ class InterleavedBufferAttribute {
 
 	}
 
+	/**
+	 * Returns a new buffer attribute with copied values from this instance.
+	 *
+	 * If no parameter is provided, cloning an interleaved buffer attribute will de-interleave buffer data.
+	 *
+	 * @param {Object} [data] - An object with interleaved buffers that allows to retain the interleaved property.
+	 * @return {BufferAttribute|InterleavedBufferAttribute} A clone of this instance.
+	 */
 	clone( data ) {
 
 		if ( data === undefined ) {
 
-			console.log( 'THREE.InterleavedBufferAttribute.clone(): Cloning an interleaved buffer attribute will de-interleave buffer data.' );
+			log( 'InterleavedBufferAttribute.clone(): Cloning an interleaved buffer attribute will de-interleave buffer data.' );
 
 			const array = [];
 
@@ -288,11 +478,19 @@ class InterleavedBufferAttribute {
 
 	}
 
+	/**
+	 * Serializes the buffer attribute into JSON.
+	 *
+	 * If no parameter is provided, cloning an interleaved buffer attribute will de-interleave buffer data.
+	 *
+	 * @param {Object} [data] - An optional value holding meta information about the serialization.
+	 * @return {Object} A JSON object representing the serialized buffer attribute.
+	 */
 	toJSON( data ) {
 
 		if ( data === undefined ) {
 
-			console.log( 'THREE.InterleavedBufferAttribute.toJSON(): Serializing an interleaved buffer attribute will de-interleave buffer data.' );
+			log( 'InterleavedBufferAttribute.toJSON(): Serializing an interleaved buffer attribute will de-interleave buffer data.' );
 
 			const array = [];