super-three 0.173.4 → 0.175.0

package/src/core/UniformsGroup.js

@@ -3,23 +3,72 @@ import { StaticDrawUsage } from '../constants.js';
 
 let _id = 0;
 
+/**
+ * A class for managing multiple uniforms in a single group. The renderer will process
+ * such a definition as a single UBO.
+ *
+ * Since this class can only be used in context of {@link ShaderMaterial}, it is only supported
+ * in {@link WebGLRenderer}.
+ *
+ * @augments EventDispatcher
+ */
 class UniformsGroup extends EventDispatcher {
 
+	/**
+	 * Constructs a new uniforms group.
+	 */
 	constructor() {
 
 		super();
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isUniformsGroup = true;
 
+		/**
+		 * The ID of the 3D object.
+		 *
+		 * @name UniformsGroup#id
+		 * @type {number}
+		 * @readonly
+		 */
 		Object.defineProperty( this, 'id', { value: _id ++ } );
 
+		/**
+		 * The name of the uniforms group.
+		 *
+		 * @type {string}
+		 */
 		this.name = '';
 
+		/**
+		 * The buffer usage.
+		 *
+		 * @type {(StaticDrawUsage|DynamicDrawUsage|StreamDrawUsage|StaticReadUsage|DynamicReadUsage|StreamReadUsage|StaticCopyUsage|DynamicCopyUsage|StreamCopyUsage)}
+		 * @default StaticDrawUsage
+		 */
 		this.usage = StaticDrawUsage;
+
+		/**
+		 * An array holding the uniforms.
+		 *
+		 * @type {Array<Uniform>}
+		 */
 		this.uniforms = [];
 
 	}
 
+	/**
+	 * Adds the given uniform to this uniforms group.
+	 *
+	 * @param {Uniform} uniform - The uniform to add.
+	 * @return {UniformsGroup} A reference to this uniforms group.
+	 */
 	add( uniform ) {
 
 		this.uniforms.push( uniform );
@@ -28,6 +77,12 @@ class UniformsGroup extends EventDispatcher {
 
 	}
 
+	/**
+	 * Removes the given uniform from this uniforms group.
+	 *
+	 * @param {Uniform} uniform - The uniform to remove.
+	 * @return {UniformsGroup} A reference to this uniforms group.
+	 */
 	remove( uniform ) {
 
 		const index = this.uniforms.indexOf( uniform );
@@ -38,6 +93,12 @@ class UniformsGroup extends EventDispatcher {
 
 	}
 
+	/**
+	 * Sets the name of this uniforms group.
+	 *
+	 * @param {string} name - The name to set.
+	 * @return {UniformsGroup} A reference to this uniforms group.
+	 */
 	setName( name ) {
 
 		this.name = name;
@@ -46,6 +107,12 @@ class UniformsGroup extends EventDispatcher {
 
 	}
 
+	/**
+	 * Sets the usage of this uniforms group.
+	 *
+	 * @param {(StaticDrawUsage|DynamicDrawUsage|StreamDrawUsage|StaticReadUsage|DynamicReadUsage|StreamReadUsage|StaticCopyUsage|DynamicCopyUsage|StreamCopyUsage)} value - The usage to set.
+	 * @return {UniformsGroup} A reference to this uniforms group.
+	 */
 	setUsage( value ) {
 
 		this.usage = value;
@@ -54,14 +121,24 @@ class UniformsGroup extends EventDispatcher {
 
 	}
 
+	/**
+	 * Frees the GPU-related resources allocated by this instance. Call this
+	 * method whenever this instance is no longer used in your app.
+	 *
+	 * @fires Texture#dispose
+	 */
 	dispose() {
 
 		this.dispatchEvent( { type: 'dispose' } );
 
-		return this;
-
 	}
 
+	/**
+	 * Copies the values of the given uniforms group to this instance.
+	 *
+	 * @param {UniformsGroup} source - The uniforms group to copy.
+	 * @return {UniformsGroup} A reference to this uniforms group.
+	 */
 	copy( source ) {
 
 		this.name = source.name;
@@ -87,6 +164,11 @@ class UniformsGroup extends EventDispatcher {
 
 	}
 
+	/**
+	 * Returns a new uniforms group with copied values from this instance.
+	 *
+	 * @return {UniformsGroup} A clone of this instance.
+	 */
 	clone() {
 
 		return new this.constructor().copy( this );

package/src/extras/Controls.js

@@ -1,30 +1,117 @@
 import { EventDispatcher } from '../core/EventDispatcher.js';
 
+/**
+ * Abstract base class for controls.
+ *
+ * @abstract
+ * @augments EventDispatcher
+ */
 class Controls extends EventDispatcher {
 
+	/**
+	 * Constructs a new controls instance.
+	 *
+	 * @param {Object3D} object - The object that is managed by the controls.
+	 * @param {?HTMLDOMElement} domElement - The HTML element used for event listeners.
+	 */
 	constructor( object, domElement = null ) {
 
 		super();
 
+		/**
+		 * The object that is managed by the controls.
+		 *
+		 * @type {Object3D}
+		 */
 		this.object = object;
+
+		/**
+		 * The HTML element used for event listeners.
+		 *
+		 * @type {?HTMLDOMElement}
+		 * @default null
+		 */
 		this.domElement = domElement;
 
+		/**
+		 * Whether the controls responds to user input or not.
+		 *
+		 * @type {boolean}
+		 * @default true
+		 */
 		this.enabled = true;
 
+		/**
+		 * The internal state of the controls.
+		 *
+		 * @type {number}
+		 * @default -1
+		 */
 		this.state = - 1;
 
+		/**
+		 * This object defines the keyboard input of the controls.
+		 *
+		 * @type {Object}
+		 */
 		this.keys = {};
+
+		/**
+		 * This object defines what type of actions are assigned to the available mouse buttons.
+		 * It depends on the control implementation what kind of mouse buttons and actions are supported.
+		 *
+		 * @type {{LEFT: ?number, MIDDLE: ?number, RIGHT: ?number}}
+		 */
 		this.mouseButtons = { LEFT: null, MIDDLE: null, RIGHT: null };
+
+		/**
+		 * This object defines what type of actions are assigned to what kind of touch interaction.
+		 * It depends on the control implementation what kind of touch interaction and actions are supported.
+		 *
+		 * @type {{ONE: ?number, TWO: ?number}}
+		 */
 		this.touches = { ONE: null, TWO: null };
 
 	}
 
-	connect() {}
+	/**
+	 * Connects the controls to the DOM. This method has so called "side effects" since
+	 * it adds the module's event listeners to the DOM.
+	 *
+	 * @param {HTMLDOMElement} element - The DOM element to connect to.
+	 */
+	connect( element ) {
+
+		if ( element === undefined ) {
+
+			console.warn( 'THREE.Controls: connect() now requires an element.' ); // @deprecated, the warning can be removed with r185
+			return;
+
+		}
+
+		if ( this.domElement !== null ) this.disconnect();
+
+		this.domElement = element;
+
+	}
 
+	/**
+	 * Disconnects the controls from the DOM.
+	 */
 	disconnect() {}
 
+	/**
+	 * Call this method if you no longer want use to the controls. It frees all internal
+	 * resources and removes all event listeners.
+	 */
 	dispose() {}
 
+	/**
+	 * Controls should implement this method if they have to update their internal state
+	 * per simulation step.
+	 *
+	 * @param {number} [delta] - The time delta in seconds.
+	 */
 	update( /* delta */ ) {}
 
 }

package/src/extras/DataUtils.js

@@ -139,8 +139,13 @@ function _generateTables() {
 
 }
 
-// float32 to float16
-
+/**
+ * Returns a half precision floating point value (FP16) from the given single
+ * precision floating point value (FP32).
+ *
+ * @param {number} val - A single precision floating point value.
+ * @return {number} The FP16 value.
+ */
 function toHalfFloat( val ) {
 
 	if ( Math.abs( val ) > 65504 ) console.warn( 'THREE.DataUtils.toHalfFloat(): Value out of range.' );
@@ -154,8 +159,13 @@ function toHalfFloat( val ) {
 
 }
 
-// float16 to float32
-
+/**
+ * Returns a single precision floating point value (FP32) from the given half
+ * precision floating point value (FP16).
+ *
+ * @param {number} val - A half precision floating point value.
+ * @return {number} The FP32 value.
+ */
 function fromHalfFloat( val ) {
 
 	const m = val >> 10;
@@ -164,10 +174,40 @@ function fromHalfFloat( val ) {
 
 }
 
-const DataUtils = {
-	toHalfFloat: toHalfFloat,
-	fromHalfFloat: fromHalfFloat,
-};
+/**
+ * A class containing utility functions for data.
+ *
+ * @hideconstructor
+ */
+class DataUtils {
+
+	/**
+	 * Returns a half precision floating point value (FP16) from the given single
+	 * precision floating point value (FP32).
+	 *
+	 * @param {number} val - A single precision floating point value.
+	 * @return {number} The FP16 value.
+	 */
+	static toHalfFloat( val ) {
+
+		return toHalfFloat( val );
+
+	}
+
+	/**
+	 * Returns a single precision floating point value (FP32) from the given half
+	 * precision floating point value (FP16).
+	 *
+	 * @param {number} val - A half precision floating point value.
+	 * @return {number} The FP32 value.
+	 */
+	static fromHalfFloat( val ) {
+
+		return fromHalfFloat( val );
+
+	}
+
+}
 
 export {
 	toHalfFloat,