@plastic-software/three 0.167.3 → 0.174.0

package/src/renderers/common/DataMap.js

@@ -1,11 +1,32 @@
+/**
+ * Data structure for the renderer. It is intended to manage
+ * data of objects in dictionaries.
+ *
+ * @private
+ */
 class DataMap {
 
+	/**
+	 * Constructs a new data map.
+	 */
 	constructor() {
 
+		/**
+		 * `DataMap` internally uses a weak map
+		 * to manage its data.
+		 *
+		 * @type {WeakMap}
+		 */
 		this.data = new WeakMap();
 
 	}
 
+	/**
+	 * Returns the dictionary for the given object.
+	 *
+	 * @param {Object} object - The object.
+	 * @return {Object} The dictionary.
+	 */
 	get( object ) {
 
 		let map = this.data.get( object );
@@ -21,9 +42,15 @@ class DataMap {
 
 	}
 
+	/**
+	 * Deletes the dictionary for the given object.
+	 *
+	 * @param {Object} object - The object.
+	 * @return {?Object} The deleted dictionary.
+	 */
 	delete( object ) {
 
-		let map;
+		let map = null;
 
 		if ( this.data.has( object ) ) {
 
@@ -37,12 +64,21 @@ class DataMap {
 
 	}
 
+	/**
+	 * Returns `true` if the given object has a dictionary defined.
+	 *
+	 * @param {Object} object - The object to test.
+	 * @return {boolean} Whether a dictionary is defined or not.
+	 */
 	has( object ) {
 
 		return this.data.has( object );
 
 	}
 
+	/**
+	 * Frees internal resources.
+	 */
 	dispose() {
 
 		this.data = new WeakMap();

package/src/renderers/common/Geometries.js

@@ -1,28 +1,31 @@
 import DataMap from './DataMap.js';
 import { AttributeType } from './Constants.js';
+import { arrayNeedsUint32 } from '../../utils.js';
 
 import { Uint16BufferAttribute, Uint32BufferAttribute } from '../../core/BufferAttribute.js';
 
-function arrayNeedsUint32( array ) {
-
-	// assumes larger values usually on last
-
-	for ( let i = array.length - 1; i >= 0; -- i ) {
-
-		if ( array[ i ] >= 65535 ) return true; // account for PRIMITIVE_RESTART_FIXED_INDEX, #24565
-
-	}
-
-	return false;
-
-}
-
+/**
+ * Returns the wireframe version for the given geometry.
+ *
+ * @private
+ * @function
+ * @param {BufferGeometry} geometry - The geometry.
+ * @return {number} The version.
+ */
 function getWireframeVersion( geometry ) {
 
 	return ( geometry.index !== null ) ? geometry.index.version : geometry.attributes.position.version;
 
 }
 
+/**
+ * Returns a wireframe index attribute for the given geometry.
+ *
+ * @private
+ * @function
+ * @param {BufferGeometry} geometry - The geometry.
+ * @return {BufferAttribute} The wireframe index attribute.
+ */
 function getWireframeIndex( geometry ) {
 
 	const indices = [];
@@ -67,21 +70,61 @@ function getWireframeIndex( geometry ) {
 
 }
 
+/**
+ * This renderer module manages geometries.
+ *
+ * @private
+ * @augments DataMap
+ */
 class Geometries extends DataMap {
 
+	/**
+	 * Constructs a new geometry management component.
+	 *
+	 * @param {Attributes} attributes - Renderer component for managing attributes.
+	 * @param {Info} info - Renderer component for managing metrics and monitoring data.
+	 */
 	constructor( attributes, info ) {
 
 		super();
 
+		/**
+		 * Renderer component for managing attributes.
+		 *
+		 * @type {Attributes}
+		 */
 		this.attributes = attributes;
+
+		/**
+		 * Renderer component for managing metrics and monitoring data.
+		 *
+		 * @type {Info}
+		 */
 		this.info = info;
 
+		/**
+		 * Weak Map for managing attributes for wireframe rendering.
+		 *
+		 * @type {WeakMap<BufferGeometry,BufferAttribute>}
+		 */
 		this.wireframes = new WeakMap();
 
+		/**
+		 * This Weak Map is used to make sure buffer attributes are
+		 * updated only once per render call.
+		 *
+		 * @type {WeakMap<BufferAttribute,number>}
+		 */
 		this.attributeCall = new WeakMap();
 
 	}
 
+	/**
+	 * Returns `true` if the given render object has an initialized geometry.
+	 *
+	 * @param {RenderObject} renderObject - The render object.
+	 * @return {boolean} Whether if the given render object has an initialized geometry or not.
+	 */
 	has( renderObject ) {
 
 		const geometry = renderObject.geometry;
@@ -90,6 +133,11 @@ class Geometries extends DataMap {
 
 	}
 
+	/**
+	 * Prepares the geometry of the given render object for rendering.
+	 *
+	 * @param {RenderObject} renderObject - The render object.
+	 */
 	updateForRender( renderObject ) {
 
 		if ( this.has( renderObject ) === false ) this.initGeometry( renderObject );
@@ -98,6 +146,11 @@ class Geometries extends DataMap {
 
 	}
 
+	/**
+	 * Initializes the geometry of the given render object.
+	 *
+	 * @param {RenderObject} renderObject - The render object.
+	 */
 	initGeometry( renderObject ) {
 
 		const geometry = renderObject.geometry;
@@ -142,8 +195,15 @@ class Geometries extends DataMap {
 
 	}
 
+	/**
+	 * Updates the geometry attributes of the given render object.
+	 *
+	 * @param {RenderObject} renderObject - The render object.
+	 */
 	updateAttributes( renderObject ) {
 
+		// attributes
+
 		const attributes = renderObject.getAttributes();
 
 		for ( const attribute of attributes ) {
@@ -160,6 +220,8 @@ class Geometries extends DataMap {
 
 		}
 
+		// indexes
+
 		const index = this.getIndex( renderObject );
 
 		if ( index !== null ) {
@@ -168,8 +230,24 @@ class Geometries extends DataMap {
 
 		}
 
+		// indirect
+
+		const indirect = renderObject.geometry.indirect;
+
+		if ( indirect !== null ) {
+
+			this.updateAttribute( indirect, AttributeType.INDIRECT );
+
+		}
+
 	}
 
+	/**
+	 * Updates the given attribute.
+	 *
+	 * @param {BufferAttribute} attribute - The attribute to update.
+	 * @param {number} type - The attribute type.
+	 */
 	updateAttribute( attribute, type ) {
 
 		const callId = this.info.render.calls;
@@ -206,6 +284,25 @@ class Geometries extends DataMap {
 
 	}
 
+	/**
+	 * Returns the indirect buffer attribute of the given render object.
+	 *
+	 * @param {RenderObject} renderObject - The render object.
+	 * @return {?BufferAttribute} The indirect attribute. `null` if no indirect drawing is used.
+	 */
+	getIndirect( renderObject ) {
+
+		return renderObject.geometry.indirect;
+
+	}
+
+	/**
+	 * Returns the index of the given render object's geometry. This is implemented
+	 * in a method to return a wireframe index if necessary.
+	 *
+	 * @param {RenderObject} renderObject - The render object.
+	 * @return {?BufferAttribute} The index. Returns `null` for non-indexed geometries.
+	 */
 	getIndex( renderObject ) {
 
 		const { geometry, material } = renderObject;

package/src/renderers/common/IndirectStorageBufferAttribute.js

@@ -0,0 +1,38 @@
+import StorageBufferAttribute from './StorageBufferAttribute.js';
+
+/**
+ * This special type of buffer attribute is intended for compute shaders.
+ * It can be used to encode draw parameters for indirect draw calls.
+ *
+ * Note: This type of buffer attribute can only be used with `WebGPURenderer`
+ * and a WebGPU backend.
+ *
+ * @augments StorageBufferAttribute
+ */
+class IndirectStorageBufferAttribute extends StorageBufferAttribute {
+
+	/**
+	 * Constructs a new storage buffer attribute.
+	 *
+	 * @param {number|Uint32Array} count - The item count. It is also valid to pass a `Uint32Array` as an argument.
+	 * The subsequent parameter is then obsolete.
+	 * @param {number} itemSize - The item size.
+	 */
+	constructor( count, itemSize ) {
+
+		super( count, itemSize, Uint32Array );
+
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
+		this.isIndirectStorageBufferAttribute = true;
+
+	}
+
+}
+
+export default IndirectStorageBufferAttribute;

package/src/renderers/common/Info.js

@@ -1,12 +1,59 @@
+/**
+ * This renderer module provides a series of statistical information
+ * about the GPU memory and the rendering process. Useful for debugging
+ * and monitoring.
+ */
 class Info {
 
+	/**
+	 * Constructs a new info component.
+	 */
 	constructor() {
 
+		/**
+		 * Whether frame related metrics should automatically
+		 * be resetted or not. This property should be set to `false`
+		 * by apps which manage their own animation loop. They must
+		 * then call `renderer.info.reset()` once per frame manually.
+		 *
+		 * @type {boolean}
+		 * @default true
+		 */
 		this.autoReset = true;
 
+		/**
+		 * The current frame ID. This ID is managed
+		 * by `NodeFrame`.
+		 *
+		 * @type {number}
+		 * @readonly
+		 * @default 0
+		 */
 		this.frame = 0;
+
+		/**
+		 * The number of render calls since the
+		 * app has been started.
+		 *
+		 * @type {number}
+		 * @readonly
+		 * @default 0
+		 */
 		this.calls = 0;
 
+		/**
+		 * Render related metrics.
+		 *
+		 * @type {Object}
+		 * @readonly
+		 * @property {number} calls - The number of render calls since the app has been started.
+		 * @property {number} frameCalls - The number of render calls of the current frame.
+		 * @property {number} drawCalls - The number of draw calls of the current frame.
+		 * @property {number} triangles - The number of rendered triangle primitives of the current frame.
+		 * @property {number} points - The number of rendered point primitives of the current frame.
+		 * @property {number} lines - The number of rendered line primitives of the current frame.
+		 * @property {number} timestamp - The timestamp of the frame when using `renderer.renderAsync()`.
+		 */
 		this.render = {
 			calls: 0,
 			frameCalls: 0,
@@ -15,18 +62,31 @@ class Info {
 			points: 0,
 			lines: 0,
 			timestamp: 0,
-			previousFrameCalls: 0,
-			timestampCalls: 0
 		};
 
+		/**
+		 * Compute related metrics.
+		 *
+		 * @type {Object}
+		 * @readonly
+		 * @property {number} calls - The number of compute calls since the app has been started.
+		 * @property {number} frameCalls - The number of compute calls of the current frame.
+		 * @property {number} timestamp - The timestamp of the frame when using `renderer.computeAsync()`.
+		 */
 		this.compute = {
 			calls: 0,
 			frameCalls: 0,
-			timestamp: 0,
-			previousFrameCalls: 0,
-			timestampCalls: 0
+			timestamp: 0
 		};
 
+		/**
+		 * Memory related metrics.
+		 *
+		 * @type {Object}
+		 * @readonly
+		 * @property {number} geometries - The number of active geometries.
+		 * @property {number} frameCalls - The number of active textures.
+		 */
 		this.memory = {
 			geometries: 0,
 			textures: 0
@@ -34,6 +94,13 @@ class Info {
 
 	}
 
+	/**
+	 * This method should be executed per draw call and updates the corresponding metrics.
+	 *
+	 * @param {Object3D} object - The 3D object that is going to be rendered.
+	 * @param {number} count - The vertex or index count.
+	 * @param {number} instanceCount - The instance count.
+	 */
 	update( object, count, instanceCount ) {
 
 		this.render.drawCalls ++;
@@ -62,38 +129,11 @@ class Info {
 
 	}
 
-	updateTimestamp( type, time ) {
-
-		if ( this[ type ].timestampCalls === 0 ) {
-
-			this[ type ].timestamp = 0;
-
-		}
-
-
-		this[ type ].timestamp += time;
-
-		this[ type ].timestampCalls ++;
-
-
-		if ( this[ type ].timestampCalls >= this[ type ].previousFrameCalls ) {
-
-			this[ type ].timestampCalls = 0;
-
-		}
-
-
-	}
-
+	/**
+	 * Resets frame related metrics.
+	 */
 	reset() {
 
-		const previousRenderFrameCalls = this.render.frameCalls;
-		this.render.previousFrameCalls = previousRenderFrameCalls;
-
-		const previousComputeFrameCalls = this.compute.frameCalls;
-		this.compute.previousFrameCalls = previousComputeFrameCalls;
-
-
 		this.render.drawCalls = 0;
 		this.render.frameCalls = 0;
 		this.compute.frameCalls = 0;
@@ -105,6 +145,9 @@ class Info {
 
 	}
 
+	/**
+	 * Performs a complete reset of the object.
+	 */
 	dispose() {
 
 		this.reset();

package/src/renderers/common/Lighting.js

@@ -0,0 +1,73 @@
+import { LightsNode } from '../../nodes/Nodes.js';
+import ChainMap from './ChainMap.js';
+
+const _defaultLights = /*@__PURE__*/ new LightsNode();
+const _chainKeys = [];
+
+/**
+ * This renderer module manages the lights nodes which are unique
+ * per scene and camera combination.
+ *
+ * The lights node itself is later configured in the render list
+ * with the actual lights from the scene.
+ *
+ * @private
+ * @augments ChainMap
+ */
+class Lighting extends ChainMap {
+
+	/**
+	 * Constructs a lighting management component.
+	 */
+	constructor() {
+
+		super();
+
+	}
+
+	/**
+	 * Creates a new lights node for the given array of lights.
+	 *
+	 * @param {Array<Light>} lights - The render object.
+	 * @return {LightsNode} The lights node.
+	 */
+	createNode( lights = [] ) {
+
+		return new LightsNode().setLights( lights );
+
+	}
+
+	/**
+	 * Returns a lights node for the given scene and camera.
+	 *
+	 * @param {Scene} scene - The scene.
+	 * @param {Camera} camera - The camera.
+	 * @return {LightsNode} The lights node.
+	 */
+	getNode( scene, camera ) {
+
+		// ignore post-processing
+
+		if ( scene.isQuadMesh ) return _defaultLights;
+
+		_chainKeys[ 0 ] = scene;
+		_chainKeys[ 1 ] = camera;
+
+		let node = this.get( _chainKeys );
+
+		if ( node === undefined ) {
+
+			node = this.createNode();
+			this.set( _chainKeys, node );
+
+		}
+
+		_chainKeys.length = 0;
+
+		return node;
+
+	}
+
+}
+
+export default Lighting;

package/src/renderers/common/Pipeline.js

@@ -1,9 +1,31 @@
+/**
+ * Abstract class for representing pipelines.
+ *
+ * @private
+ * @abstract
+ */
 class Pipeline {
 
+	/**
+	 * Constructs a new pipeline.
+	 *
+	 * @param {string} cacheKey - The pipeline's cache key.
+	 */
 	constructor( cacheKey ) {
 
+		/**
+		 * The pipeline's cache key.
+		 *
+		 * @type {string}
+		 */
 		this.cacheKey = cacheKey;
 
+		/**
+		 * How often the pipeline is currently in use.
+		 *
+		 * @type {number}
+		 * @default 0
+		 */
 		this.usedTimes = 0;
 
 	}