super-three 0.171.0 → 0.173.0

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

@@ -2,40 +2,68 @@ 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;
 
-		// tiled lighting
-
-		const keys = [ scene, camera ];
+		_chainKeys[ 0 ] = scene;
+		_chainKeys[ 1 ] = camera;
 
-		let node = this.get( keys );
+		let node = this.get( _chainKeys );
 
 		if ( node === undefined ) {
 
 			node = this.createNode();
-			this.set( keys, node );
+			this.set( _chainKeys, node );
 
 		}
 
+		_chainKeys.length = 0;
+
 		return node;
 
 	}

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;
 
 	}

package/src/renderers/common/Pipelines.js

@@ -3,18 +3,63 @@ import RenderPipeline from './RenderPipeline.js';
 import ComputePipeline from './ComputePipeline.js';
 import ProgrammableStage from './ProgrammableStage.js';
 
+/**
+ * This renderer module manages the pipelines of the renderer.
+ *
+ * @private
+ * @augments DataMap
+ */
 class Pipelines extends DataMap {
 
+	/**
+	 * Constructs a new pipeline management component.
+	 *
+	 * @param {Backend} backend - The renderer's backend.
+	 * @param {Nodes} nodes - Renderer component for managing nodes related logic.
+	 */
 	constructor( backend, nodes ) {
 
 		super();
 
+		/**
+		 * The renderer's backend.
+		 *
+		 * @type {Backend}
+		 */
 		this.backend = backend;
-		this.nodes = nodes;
 
-		this.bindings = null; // set by the bindings
+		/**
+		 * Renderer component for managing nodes related logic.
+		 *
+		 * @type {Nodes}
+		 */
+		this.nodes = nodes;
 
+		/**
+		 * A references to the bindings management component.
+		 * This reference will be set inside the `Bindings`
+		 * constructor.
+		 *
+		 * @type {Bindings?}
+		 * @default null
+		 */
+		this.bindings = null;
+
+		/**
+		 * Internal cache for maintaining pipelines.
+		 * The key of the map is a cache key, the value the pipeline.
+		 *
+		 * @type {Map<String,Pipeline>}
+		 */
 		this.caches = new Map();
+
+		/**
+		 * This dictionary maintains for each shader stage type (vertex,
+		 * fragment and compute) the programmable stage objects which
+		 * represent the actual shader code.
+		 *
+		 * @type {Object<String,Map>}
+		 */
 		this.programs = {
 			vertex: new Map(),
 			fragment: new Map(),
@@ -23,6 +68,13 @@ class Pipelines extends DataMap {
 
 	}
 
+	/**
+	 * Returns a compute pipeline for the given compute node.
+	 *
+	 * @param {Node} computeNode - The compute node.
+	 * @param {Array<BindGroup>} bindings - The bindings.
+	 * @return {ComputePipeline} The compute pipeline.
+	 */
 	getForCompute( computeNode, bindings ) {
 
 		const { backend } = this;
@@ -52,7 +104,7 @@ class Pipelines extends DataMap {
 
 				if ( previousPipeline && previousPipeline.computeProgram.usedTimes === 0 ) this._releaseProgram( previousPipeline.computeProgram );
 
-				stageCompute = new ProgrammableStage( nodeBuilderState.computeShader, 'compute', nodeBuilderState.transforms, nodeBuilderState.nodeAttributes );
+				stageCompute = new ProgrammableStage( nodeBuilderState.computeShader, 'compute', computeNode.name, nodeBuilderState.transforms, nodeBuilderState.nodeAttributes );
 				this.programs.compute.set( nodeBuilderState.computeShader, stageCompute );
 
 				backend.createProgram( stageCompute );
@@ -89,6 +141,13 @@ class Pipelines extends DataMap {
 
 	}
 
+	/**
+	 * Returns a render pipeline for the given render object.
+	 *
+	 * @param {RenderObject} renderObject - The render object.
+	 * @param {Array<Promise>?} [promises=null] - An array of compilation promises which is only relevant in context of `Renderer.compileAsync()`.
+	 * @return {RenderPipeline} The render pipeline.
+	 */
 	getForRender( renderObject, promises = null ) {
 
 		const { backend } = this;
@@ -111,6 +170,8 @@ class Pipelines extends DataMap {
 
 			const nodeBuilderState = renderObject.getNodeBuilderState();
 
+			const name = renderObject.material ? renderObject.material.name : '';
+
 			// programmable stages
 
 			let stageVertex = this.programs.vertex.get( nodeBuilderState.vertexShader );
@@ -119,7 +180,7 @@ class Pipelines extends DataMap {
 
 				if ( previousPipeline && previousPipeline.vertexProgram.usedTimes === 0 ) this._releaseProgram( previousPipeline.vertexProgram );
 
-				stageVertex = new ProgrammableStage( nodeBuilderState.vertexShader, 'vertex' );
+				stageVertex = new ProgrammableStage( nodeBuilderState.vertexShader, 'vertex', name );
 				this.programs.vertex.set( nodeBuilderState.vertexShader, stageVertex );
 
 				backend.createProgram( stageVertex );
@@ -132,7 +193,7 @@ class Pipelines extends DataMap {
 
 				if ( previousPipeline && previousPipeline.fragmentProgram.usedTimes === 0 ) this._releaseProgram( previousPipeline.fragmentProgram );
 
-				stageFragment = new ProgrammableStage( nodeBuilderState.fragmentShader, 'fragment' );
+				stageFragment = new ProgrammableStage( nodeBuilderState.fragmentShader, 'fragment', name );
 				this.programs.fragment.set( nodeBuilderState.fragmentShader, stageFragment );
 
 				backend.createProgram( stageFragment );
@@ -173,6 +234,12 @@ class Pipelines extends DataMap {
 
 	}
 
+	/**
+	 * Deletes the pipeline for the given render object.
+	 *
+	 * @param {RenderObject} object - The render object.
+	 * @return {Object?} The deleted dictionary.
+	 */
 	delete( object ) {
 
 		const pipeline = this.get( object ).pipeline;
@@ -209,6 +276,9 @@ class Pipelines extends DataMap {
 
 	}
 
+	/**
+	 * Frees internal resources.
+	 */
 	dispose() {
 
 		super.dispose();
@@ -222,12 +292,27 @@ class Pipelines extends DataMap {
 
 	}
 
+	/**
+	 * Updates the pipeline for the given render object.
+	 *
+	 * @param {RenderObject} renderObject - The render object.
+	 */
 	updateForRender( renderObject ) {
 
 		this.getForRender( renderObject );
 
 	}
 
+	/**
+	 * Returns a compute pipeline for the given parameters.
+	 *
+	 * @private
+	 * @param {Node} computeNode - The compute node.
+	 * @param {ProgrammableStage} stageCompute - The programmable stage representing the compute shader.
+	 * @param {String} cacheKey - The cache key.
+	 * @param {Array<BindGroup>} bindings - The bindings.
+	 * @return {ComputePipeline} The compute pipeline.
+	 */
 	_getComputePipeline( computeNode, stageCompute, cacheKey, bindings ) {
 
 		// check for existing pipeline
@@ -250,6 +335,17 @@ class Pipelines extends DataMap {
 
 	}
 
+	/**
+	 * Returns a render pipeline for the given parameters.
+	 *
+	 * @private
+	 * @param {RenderObject} renderObject - The render object.
+	 * @param {ProgrammableStage} stageVertex - The programmable stage representing the vertex shader.
+	 * @param {ProgrammableStage} stageFragment - The programmable stage representing the fragment shader.
+	 * @param {String} cacheKey - The cache key.
+	 * @param {Array<Promise>?} promises - An array of compilation promises which is only relevant in context of `Renderer.compileAsync()`.
+	 * @return {ComputePipeline} The compute pipeline.
+	 */
 	_getRenderPipeline( renderObject, stageVertex, stageFragment, cacheKey, promises ) {
 
 		// check for existing pipeline
@@ -266,6 +362,10 @@ class Pipelines extends DataMap {
 
 			renderObject.pipeline = pipeline;
 
+			// The `promises` array is `null` by default and only set to an empty array when
+			// `Renderer.compileAsync()` is used. The next call actually fills the array with
+			// pending promises that resolve when the render pipelines are ready for rendering.
+
 			this.backend.createRenderPipeline( renderObject, promises );
 
 		}
@@ -274,24 +374,53 @@ class Pipelines extends DataMap {
 
 	}
 
+	/**
+	 * Computes a cache key representing a compute pipeline.
+	 *
+	 * @private
+	 * @param {Node} computeNode - The compute node.
+	 * @param {ProgrammableStage} stageCompute - The programmable stage representing the compute shader.
+	 * @return {String} The cache key.
+	 */
 	_getComputeCacheKey( computeNode, stageCompute ) {
 
 		return computeNode.id + ',' + stageCompute.id;
 
 	}
 
+	/**
+	 * Computes a cache key representing a render pipeline.
+	 *
+	 * @private
+	 * @param {RenderObject} renderObject - The render object.
+	 * @param {ProgrammableStage} stageVertex - The programmable stage representing the vertex shader.
+	 * @param {ProgrammableStage} stageFragment - The programmable stage representing the fragment shader.
+	 * @return {String} The cache key.
+	 */
 	_getRenderCacheKey( renderObject, stageVertex, stageFragment ) {
 
 		return stageVertex.id + ',' + stageFragment.id + ',' + this.backend.getRenderCacheKey( renderObject );
 
 	}
 
+	/**
+	 * Releases the given pipeline.
+	 *
+	 * @private
+	 * @param {Pipeline} pipeline - The pipeline to release.
+	 */
 	_releasePipeline( pipeline ) {
 
 		this.caches.delete( pipeline.cacheKey );
 
 	}
 
+	/**
+	 * Releases the shader program.
+	 *
+	 * @private
+	 * @param {Object} program - The shader program to release.
+	 */
 	_releaseProgram( program ) {
 
 		const code = program.code;
@@ -301,6 +430,13 @@ class Pipelines extends DataMap {
 
 	}
 
+	/**
+	 * Returns `true` if the compute pipeline for the given compute node requires an update.
+	 *
+	 * @private
+	 * @param {Node} computeNode - The compute node.
+	 * @return {Boolean} Whether the compute pipeline for the given compute node requires an update or not.
+	 */
 	_needsComputeUpdate( computeNode ) {
 
 		const data = this.get( computeNode );
@@ -309,6 +445,13 @@ class Pipelines extends DataMap {
 
 	}
 
+	/**
+	 * Returns `true` if the render pipeline for the given render object requires an update.
+	 *
+	 * @private
+	 * @param {RenderObject} renderObject - The render object.
+	 * @return {Boolean} Whether the render object for the given render object requires an update or not.
+	 */
 	_needsRenderUpdate( renderObject ) {
 
 		const data = this.get( renderObject );