super-three 0.171.0 → 0.172.0

package/src/renderers/common/BindGroup.js

@@ -1,14 +1,57 @@
 let _id = 0;
 
+/**
+ * A bind group represents a collection of bindings and thus a collection
+ * or resources. Bind groups are assigned to pipelines to provide them
+ * with the required resources (like uniform buffers or textures).
+ *
+ * @private
+ */
 class BindGroup {
 
+	/**
+	 * Constructs a new bind group.
+	 *
+	 * @param {String} name - The bind group's name.
+	 * @param {Array<Binding>} bindings - An array of bindings.
+	 * @param {Number} index - The group index.
+	 * @param {Array<Binding>} bindingsReference - An array of reference bindings.
+	 */
 	constructor( name = '', bindings = [], index = 0, bindingsReference = [] ) {
 
+		/**
+		 * The bind group's name.
+		 *
+		 * @type {String}
+		 */
 		this.name = name;
+
+		/**
+		 * An array of bindings.
+		 *
+		 * @type {Array<Binding>}
+		 */
 		this.bindings = bindings;
+
+		/**
+		 * The group index.
+		 *
+		 * @type {Number}
+		 */
 		this.index = index;
+
+		/**
+		 * An array of reference bindings.
+		 *
+		 * @type {Array<Binding>}
+		 */
 		this.bindingsReference = bindingsReference;
 
+		/**
+		 * The group's ID.
+		 *
+		 * @type {Number}
+		 */
 		this.id = _id ++;
 
 	}

package/src/renderers/common/Binding.js

@@ -1,19 +1,54 @@
+/**
+ * A binding represents the connection between a resource (like a texture, sampler
+ * or uniform buffer) and the resource definition in a shader stage.
+ *
+ * This module is an abstract base class for all concrete bindings types.
+ *
+ * @abstract
+ * @private
+ */
 class Binding {
 
+	/**
+	 * Constructs a new binding.
+	 *
+	 * @param {String} [name=''] - The binding's name.
+	 */
 	constructor( name = '' ) {
 
+		/**
+		 * The binding's name.
+		 *
+		 * @type {String}
+		 */
 		this.name = name;
 
+		/**
+		 * A bitmask that defines in what shader stages the
+		 * binding's resource is accessible.
+		 *
+		 * @type {String}
+		 */
 		this.visibility = 0;
 
 	}
 
+	/**
+	 * Makes sure binding's resource is visible for the given shader stage.
+	 *
+	 * @param {Number} visibility - The shader stage.
+	 */
 	setVisibility( visibility ) {
 
 		this.visibility |= visibility;
 
 	}
 
+	/**
+	 * Clones the binding.
+	 *
+	 * @return {Binding} The cloned binding.
+	 */
 	clone() {
 
 		return Object.assign( new this.constructor(), this );

package/src/renderers/common/Bindings.js

@@ -1,23 +1,80 @@
 import DataMap from './DataMap.js';
 import { AttributeType } from './Constants.js';
 
+/**
+ * This renderer module manages the bindings of the renderer.
+ *
+ * @private
+ * @augments DataMap
+ */
 class Bindings extends DataMap {
 
+	/**
+	 * Constructs a new bindings management component.
+	 *
+	 * @param {Backend} backend - The renderer's backend.
+	 * @param {Nodes} nodes - Renderer component for managing nodes related logic.
+	 * @param {Textures} textures - Renderer component for managing textures.
+	 * @param {Attributes} attributes - Renderer component for managing attributes.
+	 * @param {Pipelines} pipelines - Renderer component for managing pipelines.
+	 * @param {Info} info - Renderer component for managing metrics and monitoring data.
+	 */
 	constructor( backend, nodes, textures, attributes, pipelines, info ) {
 
 		super();
 
+		/**
+		 * The renderer's backend.
+		 *
+		 * @type {Backend}
+		 */
 		this.backend = backend;
+
+		/**
+		 * Renderer component for managing textures.
+		 *
+		 * @type {Textures}
+		 */
 		this.textures = textures;
+
+		/**
+		 * Renderer component for managing pipelines.
+		 *
+		 * @type {Pipelines}
+		 */
 		this.pipelines = pipelines;
+
+		/**
+		 * Renderer component for managing attributes.
+		 *
+		 * @type {Attributes}
+		 */
 		this.attributes = attributes;
+
+		/**
+		 * Renderer component for managing nodes related logic.
+		 *
+		 * @type {Nodes}
+		 */
 		this.nodes = nodes;
+
+		/**
+		 * Renderer component for managing metrics and monitoring data.
+		 *
+		 * @type {Info}
+		 */
 		this.info = info;
 
 		this.pipelines.bindings = this; // assign bindings to pipelines
 
 	}
 
+	/**
+	 * Returns the bind groups for the given render object.
+	 *
+	 * @param {RenderObject} renderObject - The render object.
+	 * @return {Array<BindGroup>} The bind groups.
+	 */
 	getForRender( renderObject ) {
 
 		const bindings = renderObject.getBindings();
@@ -44,6 +101,12 @@ class Bindings extends DataMap {
 
 	}
 
+	/**
+	 * Returns the bind groups for the given compute node.
+	 *
+	 * @param {Node} computeNode - The compute node.
+	 * @return {Array<BindGroup>} The bind groups.
+	 */
 	getForCompute( computeNode ) {
 
 		const bindings = this.nodes.getForCompute( computeNode ).bindings;
@@ -68,18 +131,33 @@ class Bindings extends DataMap {
 
 	}
 
+	/**
+	 * Updates the bindings for the given compute node.
+	 *
+	 * @param {Node} computeNode - The compute node.
+	 */
 	updateForCompute( computeNode ) {
 
 		this._updateBindings( this.getForCompute( computeNode ) );
 
 	}
 
+	/**
+	 * Updates the bindings for the given render object.
+	 *
+	 * @param {RenderObject} renderObject - The render object.
+	 */
 	updateForRender( renderObject ) {
 
 		this._updateBindings( this.getForRender( renderObject ) );
 
 	}
 
+	/**
+	 * Updates the given array of bindings.
+	 *
+	 * @param {Array<BindGroup>} bindings - The bind groups.
+	 */
 	_updateBindings( bindings ) {
 
 		for ( const bindGroup of bindings ) {
@@ -90,6 +168,11 @@ class Bindings extends DataMap {
 
 	}
 
+	/**
+	 * Initializes the given bind group.
+	 *
+	 * @param {BindGroup} bindGroup - The bind group to initialize.
+	 */
 	_init( bindGroup ) {
 
 		for ( const binding of bindGroup.bindings ) {
@@ -111,6 +194,12 @@ class Bindings extends DataMap {
 
 	}
 
+	/**
+	 * Updates the given bind group.
+	 *
+	 * @param {BindGroup} bindGroup - The bind group to update.
+	 * @param {Array<BindGroup>} bindings - The bind groups.
+	 */
 	_update( bindGroup, bindings ) {
 
 		const { backend } = this;
@@ -128,7 +217,10 @@ class Bindings extends DataMap {
 
 				const updated = this.nodes.updateGroup( binding );
 
-				if ( ! updated ) continue;
+				// every uniforms group is a uniform buffer. So if no update is required,
+				// we move one with the next binding. Otherwise the next if block will update the group.
+
+				if ( updated === false ) continue;
 
 			}
 

package/src/renderers/common/Buffer.js

@@ -1,32 +1,81 @@
 import Binding from './Binding.js';
 import { getFloatLength } from './BufferUtils.js';
 
+/**
+ * Represents a buffer binding type.
+ *
+ * @private
+ * @abstract
+ * @augments Binding
+ */
 class Buffer extends Binding {
 
+	/**
+	 * Constructs a new buffer.
+	 *
+	 * @param {String} name - The buffer's name.
+	 * @param {TypedArray} [buffer=null] - The buffer.
+	 */
 	constructor( name, buffer = null ) {
 
 		super( name );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {Boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isBuffer = true;
 
+		/**
+		 * The bytes per element.
+		 *
+		 * @type {Number}
+		 */
 		this.bytesPerElement = Float32Array.BYTES_PER_ELEMENT;
 
+		/**
+		 * A reference to the internal buffer.
+		 *
+		 * @private
+		 * @type {TypedArray}
+		 */
 		this._buffer = buffer;
 
 	}
 
+	/**
+	 * The buffer's byte length.
+	 *
+	 * @type {Number}
+	 * @readonly
+	 */
 	get byteLength() {
 
 		return getFloatLength( this._buffer.byteLength );
 
 	}
 
+	/**
+	 * A reference to the internal buffer.
+	 *
+	 * @type {Float32Array}
+	 * @readonly
+	 */
 	get buffer() {
 
 		return this._buffer;
 
 	}
 
+	/**
+	 * Updates the binding.
+	 *
+	 * @return {Boolean} Whether the buffer has been updated and must be
+	 * uploaded to the GPU.
+	 */
 	update() {
 
 		return true;

package/src/renderers/common/BufferUtils.js

@@ -1,5 +1,15 @@
 import { GPU_CHUNK_BYTES } from './Constants.js';
 
+/** @module BufferUtils **/
+
+/**
+ * This function is usually called with the length in bytes of an array buffer.
+ * It returns an padded value whic ensure chunk size alignment according to STD140 layout.
+ *
+ * @function
+ * @param {Number} floatLength - The buffer length.
+ * @return {Number} The padded length.
+ */
 function getFloatLength( floatLength ) {
 
 	// ensure chunk size alignment (STD140 layout)
@@ -8,6 +18,15 @@ function getFloatLength( floatLength ) {
 
 }
 
+/**
+ * Given the count of vectors and their vector length, this function computes
+ * a total length in bytes with buffer alignment according to STD140 layout.
+ *
+ * @function
+ * @param {Number} count - The number of vectors.
+ * @param {Number} [vectorLength=4] - The vector length.
+ * @return {Number} The padded length.
+ */
 function getVectorLength( count, vectorLength = 4 ) {
 
 	const strideLength = getStrideLength( vectorLength );
@@ -18,6 +37,14 @@ function getVectorLength( count, vectorLength = 4 ) {
 
 }
 
+/**
+ * This function is called with a vector length and ensure the computed length
+ * matches a predefined stride (in this case `4`).
+ *
+ * @function
+ * @param {Number} vectorLength - The vector length.
+ * @return {Number} The padded length.
+ */
 function getStrideLength( vectorLength ) {
 
 	const strideLength = 4;

package/src/renderers/common/BundleGroup.js

@@ -1,20 +1,77 @@
 import { Group } from '../../objects/Group.js';
 
+/**
+ * A specialized group which eanbles applications access to the
+ * Render Bundle API of WebGPU. The group with all its descendant nodes
+ * are considered as one render bundle and processed as such by
+ * the renderer.
+ *
+ * This module is only fully supported by `WebGPURenderer` with a WebGPU backend.
+ * With a WebGL backend, the group can technically be rendered but without
+ * any performance improvements.
+ *
+ * @augments Group
+ */
 class BundleGroup extends Group {
 
+	/**
+	 * Constructs a new bundle group.
+	 */
 	constructor() {
 
 		super();
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {Boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isBundleGroup = true;
 
+		/**
+		 * This property is only relevant for detecting types
+		 * during serialization/deserialization. It should always
+		 * match the class name.
+		 *
+		 * @type {String}
+		 * @readonly
+		 * @default 'BundleGroup'
+		 */
 		this.type = 'BundleGroup';
 
+		/**
+		 * Whether the bundle is static or not. When set to `true`, the structure
+		 * is assumed to be static and does not change. E.g. no new objects are
+		 * added to the group
+		 *
+		 * If a change is required, an update can still be forced by setting the
+		 * `needsUpdate` flag to `true`.
+		 *
+		 * @type {Boolean}
+		 * @default true
+		 */
 		this.static = true;
+
+		/**
+		 * The bundle group's version.
+		 *
+		 * @type {Number}
+		 * @readonly
+		 * @default 0
+		 */
 		this.version = 0;
 
 	}
 
+	/**
+	 * Set this property to `true` when the bundle group has changed.
+	 *
+	 * @type {Boolean}
+	 * @default false
+	 * @param {Boolean} value
+	 */
 	set needsUpdate( value ) {
 
 		if ( value === true ) this.version ++;

package/src/renderers/common/ChainMap.js

@@ -1,11 +1,33 @@
+/**
+ * Data structure for the renderer. It allows defining values
+ * with chained, hierarchical keys. Keys are meant to be
+ * objects since the module internally works with Weak Maps
+ * for perforamnce reasons.
+ *
+ * @private
+ */
 export default class ChainMap {
 
+	/**
+	 * Constructs a new chained map.
+	 */
 	constructor() {
 
+		/**
+		 * The root Weak Map.
+		 *
+		 * @type {WeakMap}
+		 */
 		this.weakMap = new WeakMap();
 
 	}
 
+	/**
+	 * Returns the value for the given array of keys.
+	 *
+	 * @param {Array<Object>} keys - List of keys.
+	 * @return {Any} The value. Returns `undefined` if no value was found.
+	 */
 	get( keys ) {
 
 		let map = this.weakMap;
@@ -22,6 +44,13 @@ export default class ChainMap {
 
 	}
 
+	/**
+	 * Sets the value for the given keys.
+	 *
+	 * @param {Array<Object>} keys - List of keys.
+	 * @param {Any} value - The value to set.
+	 * @return {ChainMap} A reference to this chain map.
+	 */
 	set( keys, value ) {
 
 		let map = this.weakMap;
@@ -36,10 +65,18 @@ export default class ChainMap {
 
 		}
 
-		return map.set( keys[ keys.length - 1 ], value );
+		map.set( keys[ keys.length - 1 ], value );
+
+		return this;
 
 	}
 
+	/**
+	 * Deletes a value for the given keys.
+	 *
+	 * @param {Array<Object>} keys - The keys.
+	 * @return {Boolean} Returns `true` if the value has been removed successfully and `false` if the value has not be found.
+	 */
 	delete( keys ) {
 
 		let map = this.weakMap;