@plastic-software/three 0.174.0 → 0.175.0

package/src/core/GLBufferAttribute.js

@@ -1,27 +1,107 @@
+/**
+ * An alternative version of a buffer attribute with more control over the VBO.
+ *
+ * The renderer does not construct a VBO for this kind of attribute. Instead, it uses
+ * whatever VBO is passed in constructor and can later be altered via the `buffer` property.
+ *
+ * The most common use case for this class is when some kind of GPGPU calculation interferes
+ * or even produces the VBOs in question.
+ *
+ * Notice that this class can only be used with {@link WebGLRenderer}.
+ */
 class GLBufferAttribute {
 
+	/**
+	 * Constructs a new GL buffer attribute.
+	 *
+	 * @param {WebGLBuffer} buffer - The native WebGL buffer.
+	 * @param {number} type - The native data type (e.g. `gl.FLOAT`).
+	 * @param {number} itemSize - The item size.
+	 * @param {number} elementSize - The corresponding size (in bytes) for the given `type` parameter.
+	 * @param {number} count - The expected number of vertices in VBO.
+	 */
 	constructor( buffer, type, itemSize, elementSize, count ) {
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isGLBufferAttribute = true;
 
+		/**
+		 * The name of the buffer attribute.
+		 *
+		 * @type {string}
+		 */
 		this.name = '';
 
+		/**
+		 * The native WebGL buffer.
+		 *
+		 * @type {WebGLBuffer}
+		 */
 		this.buffer = buffer;
+
+		/**
+		 * The native data type.
+		 *
+		 * @type {number}
+		 */
 		this.type = type;
+
+		/**
+		 * The item size, see {@link BufferAttribute#itemSize}.
+		 *
+		 * @type {number}
+		 */
 		this.itemSize = itemSize;
+
+		/**
+		 * The corresponding size (in bytes) for the given `type` parameter.
+		 *
+		 * @type {number}
+		 */
 		this.elementSize = elementSize;
+
+		/**
+		 * The expected number of vertices in VBO.
+		 *
+		 * @type {number}
+		 */
 		this.count = count;
 
+		/**
+		 * A version number, incremented every time the `needsUpdate` is set to `true`.
+		 *
+		 * @type {number}
+		 */
 		this.version = 0;
 
 	}
 
+	/**
+	 * 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 given native WebGL buffer.
+	 *
+	 * @param {WebGLBuffer} buffer - The buffer to set.
+	 * @return {BufferAttribute} A reference to this instance.
+	 */
 	setBuffer( buffer ) {
 
 		this.buffer = buffer;
@@ -30,6 +110,13 @@ class GLBufferAttribute {
 
 	}
 
+	/**
+	 * Sets the given native data type and element size.
+	 *
+	 * @param {number} type - The native data type (e.g. `gl.FLOAT`).
+	 * @param {number} elementSize - The corresponding size (in bytes) for the given `type` parameter.
+	 * @return {BufferAttribute} A reference to this instance.
+	 */
 	setType( type, elementSize ) {
 
 		this.type = type;
@@ -39,6 +126,12 @@ class GLBufferAttribute {
 
 	}
 
+	/**
+	 * Sets the item size.
+	 *
+	 * @param {number} itemSize - The item size.
+	 * @return {BufferAttribute} A reference to this instance.
+	 */
 	setItemSize( itemSize ) {
 
 		this.itemSize = itemSize;
@@ -47,6 +140,12 @@ class GLBufferAttribute {
 
 	}
 
+	/**
+	 * Sets the count (the expected number of vertices in VBO).
+	 *
+	 * @param {number} count - The count.
+	 * @return {BufferAttribute} A reference to this instance.
+	 */
 	setCount( count ) {
 
 		this.count = count;

package/src/core/InstancedBufferAttribute.js

@@ -1,13 +1,42 @@
 import { BufferAttribute } from './BufferAttribute.js';
 
+/**
+ * An instanced version of a buffer attribute.
+ *
+ * @augments BufferAttribute
+ */
 class InstancedBufferAttribute extends BufferAttribute {
 
+	/**
+	 * Constructs a new instanced 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.
+	 * @param {number} [meshPerAttribute=1] - How often a value of this buffer attribute should be repeated.
+	 */
 	constructor( array, itemSize, normalized, meshPerAttribute = 1 ) {
 
 		super( array, itemSize, normalized );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isInstancedBufferAttribute = true;
 
+		/**
+		 * Defines how often a value of this buffer attribute should be repeated. A
+		 * value of one means that each value of the instanced attribute is used for
+		 * a single instance. A value of two means that each value is used for two
+		 * consecutive instances (and so on).
+		 *
+		 * @type {number}
+		 * @default 1
+		 */
 		this.meshPerAttribute = meshPerAttribute;
 
 	}

package/src/core/InstancedBufferGeometry.js

@@ -1,14 +1,34 @@
 import { BufferGeometry } from './BufferGeometry.js';
 
+/**
+ * An instanced version of a geometry.
+ */
 class InstancedBufferGeometry extends BufferGeometry {
 
+	/**
+	 * Constructs a new instanced buffer geometry.
+	 */
 	constructor() {
 
 		super();
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isInstancedBufferGeometry = true;
 
 		this.type = 'InstancedBufferGeometry';
+
+		/**
+		 * The instance count.
+		 *
+		 * @type {number}
+		 * @default Infinity
+		 */
 		this.instanceCount = Infinity;
 
 	}

package/src/core/InstancedInterleavedBuffer.js

@@ -1,13 +1,39 @@
 import { InterleavedBuffer } from './InterleavedBuffer.js';
 
+/**
+ * An instanced version of an interleaved buffer.
+ *
+ * @augments InterleavedBuffer
+ */
 class InstancedInterleavedBuffer extends InterleavedBuffer {
 
+	/**
+	 * Constructs a new instanced 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.
+	 * @param {number} [meshPerAttribute=1] - Defines how often a value of this interleaved buffer should be repeated.
+	 */
 	constructor( array, stride, meshPerAttribute = 1 ) {
 
 		super( array, stride );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isInstancedInterleavedBuffer = true;
 
+		/**
+		 * Defines how often a value of this buffer attribute should be repeated,
+		 * see {@link InstancedBufferAttribute#meshPerAttribute}.
+		 *
+		 * @type {number}
+		 * @default 1
+		 */
 		this.meshPerAttribute = meshPerAttribute;
 
 	}

package/src/core/InterleavedBuffer.js

@@ -1,33 +1,115 @@
 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]{@link 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;
 
+		/**
+		 * 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 ) {
@@ -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 ) {