@plastic-software/three 0.167.3 → 0.174.0

package/src/renderers/common/Uniform.js

@@ -1,30 +1,84 @@
 import { Color } from '../../math/Color.js';
+import { Matrix2 } from '../../math/Matrix2.js';
 import { Matrix3 } from '../../math/Matrix3.js';
 import { Matrix4 } from '../../math/Matrix4.js';
 import { Vector2 } from '../../math/Vector2.js';
 import { Vector3 } from '../../math/Vector3.js';
 import { Vector4 } from '../../math/Vector4.js';
 
+/**
+ * Abstract base class for uniforms.
+ *
+ * @abstract
+ * @private
+ */
 class Uniform {
 
+	/**
+	 * Constructs a new uniform.
+	 *
+	 * @param {string} name - The uniform's name.
+	 * @param {any} value - The uniform's value.
+	 */
 	constructor( name, value ) {
 
+		/**
+		 * The uniform's name.
+		 *
+		 * @type {string}
+		 */
 		this.name = name;
+
+		/**
+		 * The uniform's value.
+		 *
+		 * @type {any}
+		 */
 		this.value = value;
 
-		this.boundary = 0; // used to build the uniform buffer according to the STD140 layout
+		/**
+		 * Used to build the uniform buffer according to the STD140 layout.
+		 * Derived uniforms will set this property to a data type specific
+		 * value.
+		 *
+		 * @type {number}
+		 */
+		this.boundary = 0;
+
+		/**
+		 * The item size. Derived uniforms will set this property to a data
+		 * type specific value.
+		 *
+		 * @type {number}
+		 */
 		this.itemSize = 0;
 
-		this.offset = 0; // this property is set by WebGPUUniformsGroup and marks the start position in the uniform buffer
+		/**
+		 * This property is set by {@link UniformsGroup} and marks
+		 * the start position in the uniform buffer.
+		 *
+		 * @type {number}
+		 */
+		this.offset = 0;
 
 	}
 
+	/**
+	 * Sets the uniform's value.
+	 *
+	 * @param {any} value - The value to set.
+	 */
 	setValue( value ) {
 
 		this.value = value;
 
 	}
 
+	/**
+	 * Returns the uniform's value.
+	 *
+	 * @return {any} The value.
+	 */
 	getValue() {
 
 		return this.value;
@@ -33,12 +87,31 @@ class Uniform {
 
 }
 
+/**
+ * Represents a Number uniform.
+ *
+ * @private
+ * @augments Uniform
+ */
 class NumberUniform extends Uniform {
 
+	/**
+	 * Constructs a new Number uniform.
+	 *
+	 * @param {string} name - The uniform's name.
+	 * @param {number} value - The uniform's value.
+	 */
 	constructor( name, value = 0 ) {
 
 		super( name, value );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isNumberUniform = true;
 
 		this.boundary = 4;
@@ -48,12 +121,31 @@ class NumberUniform extends Uniform {
 
 }
 
+/**
+ * Represents a Vector2 uniform.
+ *
+ * @private
+ * @augments Uniform
+ */
 class Vector2Uniform extends Uniform {
 
+	/**
+	 * Constructs a new Number uniform.
+	 *
+	 * @param {string} name - The uniform's name.
+	 * @param {Vector2} value - The uniform's value.
+	 */
 	constructor( name, value = new Vector2() ) {
 
 		super( name, value );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isVector2Uniform = true;
 
 		this.boundary = 8;
@@ -63,12 +155,31 @@ class Vector2Uniform extends Uniform {
 
 }
 
+/**
+ * Represents a Vector3 uniform.
+ *
+ * @private
+ * @augments Uniform
+ */
 class Vector3Uniform extends Uniform {
 
+	/**
+	 * Constructs a new Number uniform.
+	 *
+	 * @param {string} name - The uniform's name.
+	 * @param {Vector3} value - The uniform's value.
+	 */
 	constructor( name, value = new Vector3() ) {
 
 		super( name, value );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isVector3Uniform = true;
 
 		this.boundary = 16;
@@ -78,12 +189,31 @@ class Vector3Uniform extends Uniform {
 
 }
 
+/**
+ * Represents a Vector4 uniform.
+ *
+ * @private
+ * @augments Uniform
+ */
 class Vector4Uniform extends Uniform {
 
+	/**
+	 * Constructs a new Number uniform.
+	 *
+	 * @param {string} name - The uniform's name.
+	 * @param {Vector4} value - The uniform's value.
+	 */
 	constructor( name, value = new Vector4() ) {
 
 		super( name, value );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isVector4Uniform = true;
 
 		this.boundary = 16;
@@ -93,12 +223,31 @@ class Vector4Uniform extends Uniform {
 
 }
 
+/**
+ * Represents a Color uniform.
+ *
+ * @private
+ * @augments Uniform
+ */
 class ColorUniform extends Uniform {
 
+	/**
+	 * Constructs a new Number uniform.
+	 *
+	 * @param {string} name - The uniform's name.
+	 * @param {Color} value - The uniform's value.
+	 */
 	constructor( name, value = new Color() ) {
 
 		super( name, value );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isColorUniform = true;
 
 		this.boundary = 16;
@@ -108,12 +257,66 @@ class ColorUniform extends Uniform {
 
 }
 
+/**
+ * Represents a Matrix2 uniform.
+ *
+ * @private
+ * @augments Uniform
+ */
+class Matrix2Uniform extends Uniform {
+
+	/**
+	 * Constructs a new Number uniform.
+	 *
+	 * @param {string} name - The uniform's name.
+	 * @param {Matrix2} value - The uniform's value.
+	 */
+	constructor( name, value = new Matrix2() ) {
+
+		super( name, value );
+
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
+		this.isMatrix2Uniform = true;
+
+		this.boundary = 16;
+		this.itemSize = 4;
+
+	}
+
+}
+
+
+/**
+ * Represents a Matrix3 uniform.
+ *
+ * @private
+ * @augments Uniform
+ */
 class Matrix3Uniform extends Uniform {
 
+	/**
+	 * Constructs a new Number uniform.
+	 *
+	 * @param {string} name - The uniform's name.
+	 * @param {Matrix3} value - The uniform's value.
+	 */
 	constructor( name, value = new Matrix3() ) {
 
 		super( name, value );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isMatrix3Uniform = true;
 
 		this.boundary = 48;
@@ -123,12 +326,31 @@ class Matrix3Uniform extends Uniform {
 
 }
 
+/**
+ * Represents a Matrix4 uniform.
+ *
+ * @private
+ * @augments Uniform
+ */
 class Matrix4Uniform extends Uniform {
 
+	/**
+	 * Constructs a new Number uniform.
+	 *
+	 * @param {string} name - The uniform's name.
+	 * @param {Matrix4} value - The uniform's value.
+	 */
 	constructor( name, value = new Matrix4() ) {
 
 		super( name, value );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isMatrix4Uniform = true;
 
 		this.boundary = 64;
@@ -141,5 +363,5 @@ class Matrix4Uniform extends Uniform {
 export {
 	NumberUniform,
 	Vector2Uniform, Vector3Uniform, Vector4Uniform, ColorUniform,
-	Matrix3Uniform, Matrix4Uniform
+	Matrix2Uniform, Matrix3Uniform, Matrix4Uniform
 };

package/src/renderers/common/UniformBuffer.js

@@ -1,11 +1,30 @@
 import Buffer from './Buffer.js';
 
+/**
+ * Represents a uniform buffer binding type.
+ *
+ * @private
+ * @augments Buffer
+ */
 class UniformBuffer extends Buffer {
 
+	/**
+	 * Constructs a new uniform buffer.
+	 *
+	 * @param {string} name - The buffer's name.
+	 * @param {TypedArray} [buffer=null] - The buffer.
+	 */
 	constructor( name, buffer = null ) {
 
 		super( name, buffer );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isUniformBuffer = true;
 
 	}

package/src/renderers/common/UniformsGroup.js

@@ -1,22 +1,59 @@
 import UniformBuffer from './UniformBuffer.js';
 import { GPU_CHUNK_BYTES } from './Constants.js';
 
+/**
+ * This class represents a uniform buffer binding but with
+ * an API that allows to maintain individual uniform objects.
+ *
+ * @private
+ * @augments UniformBuffer
+ */
 class UniformsGroup extends UniformBuffer {
 
+	/**
+	 * Constructs a new uniforms group.
+	 *
+	 * @param {string} name - The group's name.
+	 */
 	constructor( name ) {
 
 		super( name );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isUniformsGroup = true;
 
+		/**
+		 * An array with the raw uniform values.
+		 *
+		 * @private
+		 * @type {?Array<number>}
+		 * @default null
+		 */
 		this._values = null;
 
-		// the order of uniforms in this array must match the order of uniforms in the shader
-
+		/**
+		 * An array of uniform objects.
+		 *
+		 * The order of uniforms in this array must match the order of uniforms in the shader.
+		 *
+		 * @type {Array<Uniform>}
+		 */
 		this.uniforms = [];
 
 	}
 
+	/**
+	 * Adds a uniform to this group.
+	 *
+	 * @param {Uniform} uniform - The uniform to add.
+	 * @return {UniformsGroup} A reference to this group.
+	 */
 	addUniform( uniform ) {
 
 		this.uniforms.push( uniform );
@@ -25,6 +62,12 @@ class UniformsGroup extends UniformBuffer {
 
 	}
 
+	/**
+	 * Removes a uniform from this group.
+	 *
+	 * @param {Uniform} uniform - The uniform to remove.
+	 * @return {UniformsGroup} A reference to this group.
+	 */
 	removeUniform( uniform ) {
 
 		const index = this.uniforms.indexOf( uniform );
@@ -39,6 +82,11 @@ class UniformsGroup extends UniformBuffer {
 
 	}
 
+	/**
+	 * An array with the raw uniform values.
+	 *
+	 * @type {Array<number>}
+	 */
 	get values() {
 
 		if ( this._values === null ) {
@@ -51,6 +99,11 @@ class UniformsGroup extends UniformBuffer {
 
 	}
 
+	/**
+	 * A Float32 array buffer with the uniform values.
+	 *
+	 * @type {Float32Array}
+	 */
 	get buffer() {
 
 		let buffer = this._buffer;
@@ -69,6 +122,11 @@ class UniformsGroup extends UniformBuffer {
 
 	}
 
+	/**
+	 * The byte length of the buffer with correct buffer alignment.
+	 *
+	 * @type {number}
+	 */
 	get byteLength() {
 
 		let offset = 0; // global buffer offset in bytes
@@ -110,6 +168,15 @@ class UniformsGroup extends UniformBuffer {
 
 	}
 
+	/**
+	 * Updates this group by updating each uniform object of
+	 * the internal uniform list. The uniform objects check if their
+	 * values has actually changed so this method only returns
+	 * `true` if there is a real value change.
+	 *
+	 * @return {boolean} Whether the uniforms have been updated and
+	 * must be uploaded to the GPU.
+	 */
 	update() {
 
 		let updated = false;
@@ -128,6 +195,13 @@ class UniformsGroup extends UniformBuffer {
 
 	}
 
+	/**
+	 * Updates a given uniform by calling an update method matching
+	 * the uniforms type.
+	 *
+	 * @param {Uniform} uniform - The uniform to update.
+	 * @return {boolean} Whether the uniform has been updated or not.
+	 */
 	updateByType( uniform ) {
 
 		if ( uniform.isNumberUniform ) return this.updateNumber( uniform );
@@ -142,6 +216,12 @@ class UniformsGroup extends UniformBuffer {
 
 	}
 
+	/**
+	 * Updates a given Number uniform.
+	 *
+	 * @param {NumberUniform} uniform - The Number uniform.
+	 * @return {boolean} Whether the uniform has been updated or not.
+	 */
 	updateNumber( uniform ) {
 
 		let updated = false;
@@ -149,10 +229,11 @@ class UniformsGroup extends UniformBuffer {
 		const a = this.values;
 		const v = uniform.getValue();
 		const offset = uniform.offset;
+		const type = uniform.getType();
 
 		if ( a[ offset ] !== v ) {
 
-			const b = this.buffer;
+			const b = this._getBufferForType( type );
 
 			b[ offset ] = a[ offset ] = v;
 			updated = true;
@@ -163,6 +244,12 @@ class UniformsGroup extends UniformBuffer {
 
 	}
 
+	/**
+	 * Updates a given Vector2 uniform.
+	 *
+	 * @param {Vector2Uniform} uniform - The Vector2 uniform.
+	 * @return {boolean} Whether the uniform has been updated or not.
+	 */
 	updateVector2( uniform ) {
 
 		let updated = false;
@@ -170,10 +257,11 @@ class UniformsGroup extends UniformBuffer {
 		const a = this.values;
 		const v = uniform.getValue();
 		const offset = uniform.offset;
+		const type = uniform.getType();
 
 		if ( a[ offset + 0 ] !== v.x || a[ offset + 1 ] !== v.y ) {
 
-			const b = this.buffer;
+			const b = this._getBufferForType( type );
 
 			b[ offset + 0 ] = a[ offset + 0 ] = v.x;
 			b[ offset + 1 ] = a[ offset + 1 ] = v.y;
@@ -186,6 +274,12 @@ class UniformsGroup extends UniformBuffer {
 
 	}
 
+	/**
+	 * Updates a given Vector3 uniform.
+	 *
+	 * @param {Vector3Uniform} uniform - The Vector3 uniform.
+	 * @return {boolean} Whether the uniform has been updated or not.
+	 */
 	updateVector3( uniform ) {
 
 		let updated = false;
@@ -193,10 +287,11 @@ class UniformsGroup extends UniformBuffer {
 		const a = this.values;
 		const v = uniform.getValue();
 		const offset = uniform.offset;
+		const type = uniform.getType();
 
 		if ( a[ offset + 0 ] !== v.x || a[ offset + 1 ] !== v.y || a[ offset + 2 ] !== v.z ) {
 
-			const b = this.buffer;
+			const b = this._getBufferForType( type );
 
 			b[ offset + 0 ] = a[ offset + 0 ] = v.x;
 			b[ offset + 1 ] = a[ offset + 1 ] = v.y;
@@ -210,6 +305,12 @@ class UniformsGroup extends UniformBuffer {
 
 	}
 
+	/**
+	 * Updates a given Vector4 uniform.
+	 *
+	 * @param {Vector4Uniform} uniform - The Vector4 uniform.
+	 * @return {boolean} Whether the uniform has been updated or not.
+	 */
 	updateVector4( uniform ) {
 
 		let updated = false;
@@ -217,10 +318,11 @@ class UniformsGroup extends UniformBuffer {
 		const a = this.values;
 		const v = uniform.getValue();
 		const offset = uniform.offset;
+		const type = uniform.getType();
 
 		if ( a[ offset + 0 ] !== v.x || a[ offset + 1 ] !== v.y || a[ offset + 2 ] !== v.z || a[ offset + 4 ] !== v.w ) {
 
-			const b = this.buffer;
+			const b = this._getBufferForType( type );
 
 			b[ offset + 0 ] = a[ offset + 0 ] = v.x;
 			b[ offset + 1 ] = a[ offset + 1 ] = v.y;
@@ -235,6 +337,12 @@ class UniformsGroup extends UniformBuffer {
 
 	}
 
+	/**
+	 * Updates a given Color uniform.
+	 *
+	 * @param {ColorUniform} uniform - The Color uniform.
+	 * @return {boolean} Whether the uniform has been updated or not.
+	 */
 	updateColor( uniform ) {
 
 		let updated = false;
@@ -259,6 +367,12 @@ class UniformsGroup extends UniformBuffer {
 
 	}
 
+	/**
+	 * Updates a given Matrix3 uniform.
+	 *
+	 * @param {Matrix3Uniform} uniform - The Matrix3 uniform.
+	 * @return {boolean} Whether the uniform has been updated or not.
+	 */
 	updateMatrix3( uniform ) {
 
 		let updated = false;
@@ -291,6 +405,12 @@ class UniformsGroup extends UniformBuffer {
 
 	}
 
+	/**
+	 * Updates a given Matrix4 uniform.
+	 *
+	 * @param {Matrix4Uniform} uniform - The Matrix4 uniform.
+	 * @return {boolean} Whether the uniform has been updated or not.
+	 */
 	updateMatrix4( uniform ) {
 
 		let updated = false;
@@ -312,8 +432,30 @@ class UniformsGroup extends UniformBuffer {
 
 	}
 
+	/**
+	 * Returns a typed array that matches the given data type.
+	 *
+	 * @param {string} type - The data type.
+	 * @return {TypedArray} The typed array.
+	 */
+	_getBufferForType( type ) {
+
+		if ( type === 'int' || type === 'ivec2' || type === 'ivec3' || type === 'ivec4' ) return new Int32Array( this.buffer.buffer );
+		if ( type === 'uint' || type === 'uvec2' || type === 'uvec3' || type === 'uvec4' ) return new Uint32Array( this.buffer.buffer );
+		return this.buffer;
+
+	}
+
 }
 
+/**
+ * Sets the values of the second array to the first array.
+ *
+ * @private
+ * @param {TypedArray} a - The first array.
+ * @param {TypedArray} b - The second array.
+ * @param {number} offset - An index offset for the first array.
+ */
 function setArray( a, b, offset ) {
 
 	for ( let i = 0, l = b.length; i < l; i ++ ) {
@@ -324,6 +466,15 @@ function setArray( a, b, offset ) {
 
 }
 
+/**
+ * Returns `true` if the given arrays are equal.
+ *
+ * @private
+ * @param {TypedArray} a - The first array.
+ * @param {TypedArray} b - The second array.
+ * @param {number} offset - An index offset for the first array.
+ * @return {boolean} Whether the given arrays are equal or not.
+ */
 function arraysEqual( a, b, offset ) {
 
 	for ( let i = 0, l = b.length; i < l; i ++ ) {