Renderer: Document more modules (#30213)

* Renderer: Document more modules

* Renderer: Fix reference.

* RenderObject: Clean up.

src/renderers/common/Animation.js

@@ -9,13 +9,13 @@ class Animation {
 	/**
 	 * Constructs a new animation loop management component.
 	 *
-	 * @param {Nodes} nodes - Renderer component for managing nodes relatd logic.
+	 * @param {Nodes} nodes - Renderer component for managing nodes related logic.
 	 * @param {Info} info - Renderer component for managing metrics and monitoring data.
 	 */
 	constructor( nodes, info ) {
 
 		/**
-		 * Renderer component for managing nodes relatd logic.
+		 * Renderer component for managing nodes related logic.
 		 *
 		 * @type {Nodes}
 		 */

src/renderers/common/Background.js

@@ -21,7 +21,7 @@ class Background extends DataMap {
 	 * Constructs a new background management component.
 	 *
 	 * @param {Renderer} renderer - The renderer.
-	 * @param {Nodes} nodes - Renderer component for managing nodes relatd logic.
+	 * @param {Nodes} nodes - Renderer component for managing nodes related logic.
 	 */
 	constructor( renderer, nodes ) {
 
@@ -35,7 +35,7 @@ class Background extends DataMap {
 		this.renderer = renderer;
 
 		/**
-		 * Renderer component for managing nodes relatd logic.
+		 * Renderer component for managing nodes related logic.
 		 *
 		 * @type {Nodes}
 		 */

src/renderers/common/Info.js

@@ -1,12 +1,61 @@
+/**
+ * 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} previousFrameCalls - The number of render calls of the previous frame.
+		 * @property {Number} timestamp - The timestamp of the frame when using `renderer.renderAsync()`.
+		 * @property {Number} timestampCalls - The number of render calls using `renderer.renderAsync()`.
+		 */
 		this.render = {
 			calls: 0,
 			frameCalls: 0,
@@ -19,6 +68,17 @@ class Info {
 			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} previousFrameCalls - The number of compute calls of the previous frame.
+		 * @property {Number} timestamp - The timestamp of the frame when using `renderer.computeAsync()`.
+		 * @property {Number} timestampCalls - The number of render calls using `renderer.computeAsync()`.
+		 */
 		this.compute = {
 			calls: 0,
 			frameCalls: 0,
@@ -27,6 +87,14 @@ class Info {
 			timestampCalls: 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 +102,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,6 +137,12 @@ class Info {
 
 	}
 
+	/**
+	 * Used by async render methods to updated timestamp metrics.
+	 *
+	 * @param {('render'|'compute')} type - The type of render call.
+	 * @param {Number} time - The duration of the compute/render call in milliseconds.
+	 */
 	updateTimestamp( type, time ) {
 
 		if ( this[ type ].timestampCalls === 0 ) {
@@ -85,6 +166,9 @@ class Info {
 
 	}
 
+	/**
+	 * Resets frame related metrics.
+	 */
 	reset() {
 
 		const previousRenderFrameCalls = this.render.frameCalls;
@@ -105,6 +189,9 @@ class Info {
 
 	}
 
+	/**
+	 * Performs a complete reset of the object.
+	 */
 	dispose() {
 
 		this.reset();

src/renderers/common/Pipelines.js

@@ -3,18 +3,62 @@ 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
+ */
 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 progammable stage objects which
+		 * represent the actual shader code.
+		 *
+		 * @type {Object<String,Map>}
+		 */
 		this.programs = {
 			vertex: new Map(),
 			fragment: new Map(),
@@ -23,6 +67,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;
@@ -89,6 +140,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;
@@ -175,6 +233,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;
@@ -211,6 +275,9 @@ class Pipelines extends DataMap {
 
 	}
 
+	/**
+	 * Frees internal resources.
+	 */
 	dispose() {
 
 		super.dispose();
@@ -224,12 +291,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
@@ -252,6 +334,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} 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
@@ -268,6 +361,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 );
 
 		}
@@ -276,24 +373,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 shdaer program to release.
+	 */
 	_releaseProgram( program ) {
 
 		const code = program.code;
@@ -303,6 +429,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 );
@@ -311,6 +444,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 );

src/renderers/common/RenderContext.js

@@ -1,44 +1,203 @@
 import { Vector4 } from '../../math/Vector4.js';
 import { hashArray } from '../../nodes/core/NodeUtils.js';
 
-let id = 0;
-
+let _id = 0;
+
+/**
+ * Any render or compute command is executed in a specific context that defines
+ * the state of the renderer and its backend. Typical examples for such context
+ * data are the current clear values or data from the active framebuffer. This
+ * module is used to represent these contexts as objects.
+ *
+ * @private
+ */
 class RenderContext {
 
+	/**
+	 * Constructs a new render context.
+	 */
 	constructor() {
 
-		this.id = id ++;
-
+		/**
+		 * The context's ID.
+		 *
+		 * @type {Number}
+		 */
+		this.id = _id ++;
+
+		/**
+		 * Whether the current active framebuffer has a color attachment.
+		 *
+		 * @type {Boolean}
+		 * @default true
+		 */
 		this.color = true;
+
+		/**
+		 * Whether the color attachment should be cleared or not.
+		 *
+		 * @type {Boolean}
+		 * @default true
+		 */
 		this.clearColor = true;
+
+		/**
+		 * The clear color value.
+		 *
+		 * @type {Object}
+		 * @default true
+		 */
 		this.clearColorValue = { r: 0, g: 0, b: 0, a: 1 };
 
+		/**
+		 * Whether the current active framebuffer has a depth attachment.
+		 *
+		 * @type {Boolean}
+		 * @default true
+		 */
 		this.depth = true;
+
+		/**
+		 * Whether the depth attachment should be cleared or not.
+		 *
+		 * @type {Boolean}
+		 * @default true
+		 */
 		this.clearDepth = true;
+
+		/**
+		 * The clear depth value.
+		 *
+		 * @type {Number}
+		 * @default 1
+		 */
 		this.clearDepthValue = 1;
 
+		/**
+		 * Whether the current active framebuffer has a stencil attachment.
+		 *
+		 * @type {Boolean}
+		 * @default false
+		 */
 		this.stencil = false;
+
+		/**
+		 * Whether the stencil attachment should be cleared or not.
+		 *
+		 * @type {Boolean}
+		 * @default true
+		 */
 		this.clearStencil = true;
+
+		/**
+		 * The clear stencil value.
+		 *
+		 * @type {Number}
+		 * @default 1
+		 */
 		this.clearStencilValue = 1;
 
+		/**
+		 * By default the viewport encloses the entire framebuffer If a smaller
+		 * viewport is manually defined, this property is to `true` by the renderer.
+		 *
+		 * @type {Boolean}
+		 * @default false
+		 */
 		this.viewport = false;
+
+		/**
+		 * The viewport value. This value is in physical pixels meaning it incorporates
+		 * the renderer's pixel ratio. The viewport property of render targets or
+		 * the renderer is in logical pixels.
+		 *
+		 * @type {Vector4}
+		 */
 		this.viewportValue = new Vector4();
 
+		/**
+		 * When the scissor test is active and scissor rectangle smaller than the
+		 * framebuffers dimensions, this property is to `true` by the renderer.
+		 *
+		 * @type {Boolean}
+		 * @default false
+		 */
 		this.scissor = false;
+
+		/**
+		 * The scissor rectangle.
+		 *
+		 * @type {Vector4}
+		 */
 		this.scissorValue = new Vector4();
 
+		/**
+		 * The textures of the active render target.
+		 * `null` when no render target is set.
+		 *
+		 * @type {Array<Texture>?}
+		 * @default null
+		 */
 		this.textures = null;
+
+		/**
+		 * The depth texture of the active render target.
+		 * `null` when no render target is set.
+		 *
+		 * @type {DepthTexture?}
+		 * @default null
+		 */
 		this.depthTexture = null;
+
+		/**
+		 * The active cube face.
+		 *
+		 * @type {Number}
+		 * @default 0
+		 */
 		this.activeCubeFace = 0;
+
+		/**
+		 * The number of MSAA samples. This value is always `1` when
+		 * MSAA isn't used.
+		 *
+		 * @type {Number}
+		 * @default 1
+		 */
 		this.sampleCount = 1;
 
+		/**
+		 * The framebuffers width in physical pixels.
+		 *
+		 * @type {Number}
+		 * @default 0
+		 */
 		this.width = 0;
+
+		/**
+		 * The framebuffers height in physical pixels.
+		 *
+		 * @type {Number}
+		 * @default 0
+		 */
 		this.height = 0;
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {Boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isRenderContext = true;
 
 	}
 
+	/**
+	 * Returns the cache key of this render context.
+	 *
+	 * @return {Number} The cache key.
+	 */
 	getCacheKey() {
 
 		return getCacheKey( this );
@@ -47,6 +206,12 @@ class RenderContext {
 
 }
 
+/**
+ * Computes a cache key for the given render context.
+ *
+ * @param {RenderContext} renderContext - The render context.
+ * @return {Number} The cache key.
+ */
 export function getCacheKey( renderContext ) {
 
 	const { textures, activeCubeFace } = renderContext;

src/renderers/common/RenderContexts.js

@@ -1,14 +1,36 @@
 import ChainMap from './ChainMap.js';
 import RenderContext from './RenderContext.js';
 
+/**
+ * This module manages the render contexts of the renderer.
+ *
+ * @private
+ */
 class RenderContexts {
 
+	/**
+	 * Constructs a new render context management component.
+	 */
 	constructor() {
 
+		/**
+		 * A dictionary that manages render contexts in chain maps
+		 * for each attachment state.
+		 *
+		 * @type {Object<String,ChainMap>}
+		 */
 		this.chainMaps = {};
 
 	}
 
+	/**
+	 * Returns a render context for the given scene, camera and render target.
+	 *
+	 * @param {Scene?} [scene=null] - The scene. The parameter can become `null` e.g. when the renderer clears a render target.
+	 * @param {Camera?} [camera=null] - The camera that is used to render the scene. The parameter can become `null` e.g. when the renderer clears a render target.
+	 * @param {RenderTarget?} [renderTarget=null] - The active render target.
+	 * @return {RenderContext} The render context.
+	 */
 	get( scene = null, camera = null, renderTarget = null ) {
 
 		const chainKey = [];
@@ -55,12 +77,21 @@ class RenderContexts {
 
 	}
 
+	/**
+	 * Returns a chain map for the given attachment state.
+	 *
+	 * @param {String} attachmentState - The attachment state.
+	 * @return {ChainMap} The chain map.
+	 */
 	getChainMap( attachmentState ) {
 
 		return this.chainMaps[ attachmentState ] || ( this.chainMaps[ attachmentState ] = new ChainMap() );
 
 	}
 
+	/**
+	 * Frees internal resources.
+	 */
 	dispose() {
 
 		this.chainMaps = {};

src/renderers/common/RenderObject.js

@@ -36,49 +36,254 @@ function getKeys( obj ) {
 
 }
 
+/**
+ * A render object is the renderer's representation of single entity that gets drawn
+ * with a draw command. There is no unique mapping of render objects to 3D objects in the
+ * scene since render objects also depend from the used material, the current render context
+ * and the current scene's lighting.
+ *
+ * In general, the basic process of the renderer is:
+ *
+ * - Analyze the 3D objects in the scene and generate render lists containing render items.
+ * - Process the render lists by calling one or more render commands for each render item.
+ * - For each render command, request a render object and perform the draw.
+ *
+ * The module provides an interface to get data required for the draw command like the actual
+ * draw parameters or vertex buffers. It also holds a series of caching related methods since
+ * creating render objects should only be done when necessary.
+ *
+ * @private
+ */
 export default class RenderObject {
 
+	/**
+	 * Constructs a new render object.
+	 *
+	 * @param {Nodes} nodes - Renderer component for managing nodes related logic.
+	 * @param {Geometries} geometries - Renderer component for managing geometries.
+	 * @param {Renderer} renderer - The renderer.
+	 * @param {Object3D} object - The 3D object.
+	 * @param {Material} material - The 3D object's material.
+	 * @param {Scene} scene - The scene the 3D object belongs to.
+	 * @param {Camera} camera - The camera the object should be rendered with.
+	 * @param {LightsNode} lightsNode - The lights node.
+	 * @param {RenderContext} renderContext - The render context.
+	 * @param {ClippingContext} clippingContext - The clipping context.
+	 */
 	constructor( nodes, geometries, renderer, object, material, scene, camera, lightsNode, renderContext, clippingContext ) {
 
+		this.id = _id ++;
+
+		/**
+		 * Renderer component for managing nodes related logic.
+		 *
+		 * @type {Nodes}
+		 * @private
+		 */
 		this._nodes = nodes;
-		this._geometries = geometries;
 
-		this.id = _id ++;
+		/**
+		 * Renderer component for managing geometries.
+		 *
+		 * @type {Geometries}
+		 * @private
+		 */
+		this._geometries = geometries;
 
+		/**
+		 * The renderer.
+		 *
+		 * @type {Renderer}
+		 */
 		this.renderer = renderer;
+
+		/**
+		 * The 3D object.
+		 *
+		 * @type {Object3D}
+		 */
 		this.object = object;
+
+		/**
+		 * The 3D object's material.
+		 *
+		 * @type {Material}
+		 */
 		this.material = material;
+
+		/**
+		 * The scene the 3D object belongs to.
+		 *
+		 * @type {Scene}
+		 */
 		this.scene = scene;
+
+		/**
+		 * The camera the 3D object should be rendered with.
+		 *
+		 * @type {Camera}
+		 */
 		this.camera = camera;
+
+		/**
+		 * The lights node.
+		 *
+		 * @type {LightsNode}
+		 */
 		this.lightsNode = lightsNode;
+
+		/**
+		 * The render context.
+		 *
+		 * @type {RenderContext}
+		 */
 		this.context = renderContext;
 
+		/**
+		 * The 3D object's geometry.
+		 *
+		 * @type {BufferGeometry}
+		 */
 		this.geometry = object.geometry;
+
+		/**
+		 * The render object's version.
+		 *
+		 * @type {Number}
+		 */
 		this.version = material.version;
 
+		/**
+		 * The draw range of the geometry.
+		 *
+		 * @type {Object?}
+		 * @default null
+		 */
 		this.drawRange = null;
 
+		/**
+		 * An array holding the buffer attributes
+		 * of the render object. This entails attribute
+		 * definitions on geometry and node level.
+		 *
+		 * @type {Array<BufferAttribute>?}
+		 * @default null
+		 */
 		this.attributes = null;
+
+		/**
+		 * A reference to a render pipeline the render
+		 * object is processed with.
+		 *
+		 * @type {RenderPipeline}
+		 * @default null
+		 */
 		this.pipeline = null;
+
+		/**
+		 * An array holding the vertex buffers which can
+		 * be buffer attributes but also interleaved buffers.
+		 *
+		 * @type {Array<BufferAttribute|InterleavedBuffer>?}
+		 * @default null
+		 */
 		this.vertexBuffers = null;
+
+		/**
+		 * The parameters for the draw command.
+		 *
+		 * @type {Object?}
+		 * @default null
+		 */
 		this.drawParams = null;
 
+		/**
+		 * If this render object is used inside a render bundle,
+		 * this property points to the respective bundle group.
+		 *
+		 * @type {BundleGroup?}
+		 * @default null
+		 */
 		this.bundle = null;
 
+		/**
+		 * The clipping context.
+		 *
+		 * @type {ClippingContext}
+		 */
 		this.clippingContext = clippingContext;
+
+		/**
+		 * The clipping context's cache key.
+		 *
+		 * @type {String}
+		 */
 		this.clippingContextCacheKey = clippingContext !== null ? clippingContext.cacheKey : '';
 
+		/**
+		 * The initial node cache key.
+		 *
+		 * @type {Number}
+		 */
 		this.initialNodesCacheKey = this.getDynamicCacheKey();
+
+		/**
+		 * The initial cache key.
+		 *
+		 * @type {Number}
+		 */
 		this.initialCacheKey = this.getCacheKey();
 
+		/**
+		 * The node builder state.
+		 *
+		 * @type {NodeBuilderState?}
+		 * @private
+		 * @default null
+		 */
 		this._nodeBuilderState = null;
+
+		/**
+		 * An array of bindings.
+		 *
+		 * @type {Array<BindGroup>?}
+		 * @private
+		 * @default null
+		 */
 		this._bindings = null;
+
+		/**
+		 * Reference to the node material observer.
+		 *
+		 * @type {NodeMaterialObserver?}
+		 * @private
+		 * @default null
+		 */
 		this._monitor = null;
 
+		/**
+		 * An event listener which is defined by `RenderObjects`. It performs
+		 * clean up tasks when `dispose()` on this render object.
+		 *
+		 * @method
+		 */
 		this.onDispose = null;
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {Boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isRenderObject = true;
 
+		/**
+		 * An event listener which is executed when `dispose()` is called on
+		 * the render object's material.
+		 *
+		 * @method
+		 */
 		this.onMaterialDispose = () => {
 
 			this.dispose();
@@ -89,12 +294,23 @@ export default class RenderObject {
 
 	}
 
-	updateClipping( parent ) {
+	/**
+	 * Updates the clipping context.
+	 *
+	 * @param {ClippingContext} context - The clipping context to set.
+	 */
+	updateClipping( context ) {
 
-		this.clippingContext = parent;
+		this.clippingContext = context;
 
 	}
 
+	/**
+	 * Whether the clipping requires an update or not.
+	 *
+	 * @type {Boolean}
+	 * @readonly
+	 */
 	get clippingNeedsUpdate() {
 
 		if ( this.clippingContext === null || this.clippingContext.cacheKey === this.clippingContextCacheKey ) return false;
@@ -105,48 +321,90 @@ export default class RenderObject {
 
 	}
 
+	/**
+	 * The number of clipping planes defined in context of hardware clipping.
+	 *
+	 * @type {Number}
+	 * @readonly
+	 */
 	get hardwareClippingPlanes() {
 
 		return this.material.hardwareClipping === true ? this.clippingContext.unionClippingCount : 0;
 
 	}
 
+	/**
+	 * Returns the node builder state of this render object.
+	 *
+	 * @return {NodeBuilderState} The node buider state.
+	 */
 	getNodeBuilderState() {
 
 		return this._nodeBuilderState || ( this._nodeBuilderState = this._nodes.getForRender( this ) );
 
 	}
 
+	/**
+	 * Returns the node material observer of this render object.
+	 *
+	 * @return {NodeMaterialObserver} The node material observer.
+	 */
 	getMonitor() {
 
 		return this._monitor || ( this._monitor = this.getNodeBuilderState().monitor );
 
 	}
 
+	/**
+	 * Returns an array of bind groups of this render object.
+	 *
+	 * @return {Array<BindGroup>} The bindings.
+	 */
 	getBindings() {
 
 		return this._bindings || ( this._bindings = this.getNodeBuilderState().createBindings() );
 
 	}
 
+	/**
+	 * Returns the index of the render object's geometry.
+	 *
+	 * @return {BufferAttribute?} The index. Returns `null` for non-indexed geometries.
+	 */
 	getIndex() {
 
 		return this._geometries.getIndex( this );
 
 	}
 
+	/**
+	 * Returns the indirect buffer attribute.
+	 *
+	 * @return {BufferAttribute?} The indirect attribute. `null` if no indirect drawing is used.
+	 */
 	getIndirect() {
 
 		return this._geometries.getIndirect( this );
 
 	}
 
+	/**
+	 * Returns an array that acts as a key for identifying the render object in a chain map.
+	 *
+	 * @return {Array<Object>} An array with object references.
+	 */
 	getChainArray() {
 
 		return [ this.object, this.material, this.context, this.lightsNode ];
 
 	}
 
+	/**
+	 * This method is used when the geometry of a 3D object has been exchanged and the
+	 * respective render object now requires an update.
+	 *
+	 * @param {BufferGeometry} geometry - The geometry to set.
+	 */
 	setGeometry( geometry ) {
 
 		this.geometry = geometry;
@@ -154,6 +412,12 @@ export default class RenderObject {
 
 	}
 
+	/**
+	 * Returns the buffer attributes of the render object. The returned array holds
+	 * attribute definitions on geometry and node level.
+	 *
+	 * @return {Array<BufferAttribute>} An array with buffer attributes.
+	 */
 	getAttributes() {
 
 		if ( this.attributes !== null ) return this.attributes;
@@ -184,6 +448,11 @@ export default class RenderObject {
 
 	}
 
+	/**
+	 * Returns the vertex buffers of the render object.
+	 *
+	 * @return {Array<BufferAttribute|InterleavedBuffer>} An array with buffer attribute or interleaved buffers.
+	 */
 	getVertexBuffers() {
 
 		if ( this.vertexBuffers === null ) this.getAttributes();
@@ -192,6 +461,11 @@ export default class RenderObject {
 
 	}
 
+	/**
+	 * Returns the draw parameters for the render object.
+	 *
+	 * @return {{vertexCount: Number, firstVertex: Number, instanceCount: Number, firstInstance: Number}} The draw parameters.
+	 */
 	getDrawParameters() {
 
 		const { object, material, geometry, group, drawRange } = this;
@@ -258,6 +532,13 @@ export default class RenderObject {
 
 	}
 
+	/**
+	 * Returns the render object's geometry cache key.
+	 *
+	 * The geometry cache key is part of the material cache key.
+	 *
+	 * @return {String} The geometry cache key.
+	 */
 	getGeometryCacheKey() {
 
 		const { geometry } = this;
@@ -287,6 +568,13 @@ export default class RenderObject {
 
 	}
 
+	/**
+	 * Returns the render object's material cache key.
+	 *
+	 * The material cache key is part of the render object cache key.
+	 *
+	 * @return {String} The material cache key.
+	 */
 	getMaterialCacheKey() {
 
 		const { object, material } = this;
@@ -385,18 +673,46 @@ export default class RenderObject {
 
 	}
 
+	/**
+	 * Whether the geometry requires an update or not.
+	 *
+	 * @type {Boolean}
+	 * @readonly
+	 */
 	get needsGeometryUpdate() {
 
 		return this.geometry.id !== this.object.geometry.id;
 
 	}
 
+	/**
+	 * Whether the render object requires an update or not.
+	 *
+	 * Note: There are two distinct places where render objects are checked for an update.
+	 *
+	 * 1. In `RenderObjects.get()` which is executed when the render object is request. This
+	 * method checks the `needsUpdate` flag and recreates the render object if necessary.
+	 * 2. In `Renderer._renderObjectDirect()` right after getting the render object via
+	 * `RenderObjects.get()`. The render object's NodeMaterialObserver is then used to detect
+	 * a need for a refresh due to material, geometry or object related value changes.
+	 *
+	 * TODO: Investigate if it's possible to merge boths steps so there is only a single place
+	 * that performs the 'needsUpdate' check.
+	 *
+	 * @type {Boolean}
+	 * @readonly
+	 */
 	get needsUpdate() {
 
 		return /*this.object.static !== true &&*/ ( this.initialNodesCacheKey !== this.getDynamicCacheKey() || this.clippingNeedsUpdate );
 
 	}
 
+	/**
+	 * Returns the dynamic cache key which represents a key that is computed per draw command.
+	 *
+	 * @return {String} The cache key.
+	 */
 	getDynamicCacheKey() {
 
 		// Environment Nodes Cache Key
@@ -413,12 +729,20 @@ export default class RenderObject {
 
 	}
 
+	/**
+	 * Returns the render object's cache key.
+	 *
+	 * @return {String} The cache key.
+	 */
 	getCacheKey() {
 
 		return this.getMaterialCacheKey() + this.getDynamicCacheKey();
 
 	}
 
+	/**
+	 * Frees internal resources.
+	 */
 	dispose() {
 
 		this.material.removeEventListener( 'dispose', this.onMaterialDispose );

src/renderers/common/RenderObjects.js

@@ -1,40 +1,109 @@
 import ChainMap from './ChainMap.js';
 import RenderObject from './RenderObject.js';
 
-const chainArray = [];
+const _chainArray = [];
 
+/**
+ * This module manages the render objects of the renderer.
+ *
+ * @private
+ */
 class RenderObjects {
 
+	/**
+	 * Constructs a new render object management component.
+	 *
+	 * @param {Renderer} renderer - The renderer.
+	 * @param {Nodes} nodes - Renderer component for managing nodes related logic.
+	 * @param {Geometries} geometries - Renderer component for managing geometries.
+	 * @param {Pipelines} pipelines - Renderer component for managing pipelines.
+	 * @param {Bindings} bindings - Renderer component for managing bindings.
+	 * @param {Info} info - Renderer component for managing metrics and monitoring data.
+	 */
 	constructor( renderer, nodes, geometries, pipelines, bindings, info ) {
 
+		/**
+		 * The renderer.
+		 *
+		 * @type {Renderer}
+		 */
 		this.renderer = renderer;
+
+		/**
+		 * Renderer component for managing nodes related logic.
+		 *
+		 * @type {Nodes}
+		 */
 		this.nodes = nodes;
+
+		/**
+		 * Renderer component for managing geometries.
+		 *
+		 * @type {Geometries}
+		 */
 		this.geometries = geometries;
+
+		/**
+		 * Renderer component for managing pipelines.
+		 *
+		 * @type {Pipelines}
+		 */
 		this.pipelines = pipelines;
+
+		/**
+		 * Renderer component for managing bindings.
+		 *
+		 * @type {Bindings}
+		 */
 		this.bindings = bindings;
+
+		/**
+		 * Renderer component for managing metrics and monitoring data.
+		 *
+		 * @type {Info}
+		 */
 		this.info = info;
 
+		/**
+		 * A dictionary that manages render contexts in chain maps
+		 * for each pass ID.
+		 *
+		 * @type {Object<String,ChainMap>}
+		 */
 		this.chainMaps = {};
 
 	}
 
+	/**
+	 * Returns a render object for the given object and state data.
+	 *
+	 * @param {Object3D} object - The 3D object.
+	 * @param {Material} material - The 3D object's material.
+	 * @param {Scene} scene - The scene the 3D object belongs to.
+	 * @param {Camera} camera - The camera the 3D object should be rendered with.
+	 * @param {LightsNode} lightsNode - The lights node.
+	 * @param {RenderContext} renderContext - The render context.
+	 * @param {ClippingContext} clippingContext - The clipping context.
+	 * @param {String?} passId - An optional ID for identifying the pass.
+	 * @return {RenderObject} The render object.
+	 */
 	get( object, material, scene, camera, lightsNode, renderContext, clippingContext, passId ) {
 
 		const chainMap = this.getChainMap( passId );
 
 		// reuse chainArray
-		chainArray[ 0 ] = object;
-		chainArray[ 1 ] = material;
-		chainArray[ 2 ] = renderContext;
-		chainArray[ 3 ] = lightsNode;
+		_chainArray[ 0 ] = object;
+		_chainArray[ 1 ] = material;
+		_chainArray[ 2 ] = renderContext;
+		_chainArray[ 3 ] = lightsNode;
 
-		let renderObject = chainMap.get( chainArray );
+		let renderObject = chainMap.get( _chainArray );
 
 		if ( renderObject === undefined ) {
 
 			renderObject = this.createRenderObject( this.nodes, this.geometries, this.renderer, object, material, scene, camera, lightsNode, renderContext, clippingContext, passId );
 
-			chainMap.set( chainArray, renderObject );
+			chainMap.set( _chainArray, renderObject );
 
 		} else {
 
@@ -68,18 +137,43 @@ class RenderObjects {
 
 	}
 
+	/**
+	 * Returns a chain map for the given pass ID.
+	 *
+	 * @param {String} [passId='default'] - The pass ID.
+	 * @return {ChainMap} The chain map.
+	 */
 	getChainMap( passId = 'default' ) {
 
 		return this.chainMaps[ passId ] || ( this.chainMaps[ passId ] = new ChainMap() );
 
 	}
 
+	/**
+	 * Frees internal resources.
+	 */
 	dispose() {
 
 		this.chainMaps = {};
 
 	}
 
+	/**
+	 * Factory method for creating render objects with the given list of parameters.
+	 *
+	 * @param {Nodes} nodes - Renderer component for managing nodes related logic.
+	 * @param {Geometries} geometries - Renderer component for managing geometries.
+	 * @param {Renderer} renderer - The renderer.
+	 * @param {Object3D} object - The 3D object.
+	 * @param {Material} material - The object's material.
+	 * @param {Scene} scene - The scene the 3D object belongs to.
+	 * @param {Camera} camera - The camera the object should be rendered with.
+	 * @param {LightsNode} lightsNode - The lights node.
+	 * @param {RenderContext} renderContext - The render context.
+	 * @param {ClippingContext} clippingContext - The clipping context.
+	 * @param {String?} passId - An optional ID for identifying the pass.
+	 * @return {RenderObject} The render object.
+	 */
 	createRenderObject( nodes, geometries, renderer, object, material, scene, camera, lightsNode, renderContext, clippingContext, passId ) {
 
 		const chainMap = this.getChainMap( passId );

src/renderers/common/Renderer.js

@@ -209,8 +209,8 @@ class Renderer {
 		this.stencil = stencil;
 
 		/**
-		 * Holds a series of statistical information about the graphics board memory
-		 * and the rendering process. Useful for debugging or monitoring.
+		 * Holds a series of statistical information about the GPU memory
+		 * and the rendering process. Useful for debugging and monitoring.
 		 *
 		 * @type {Boolean}
 		 */
@@ -2795,7 +2795,7 @@ class Renderer {
 
 			renderBundleData.renderObjects.push( renderObject );
 
-			renderObject.bundle = this._currentRenderBundle.scene;
+			renderObject.bundle = this._currentRenderBundle.bundleGroup;
 
 		}
 
@@ -2806,7 +2806,7 @@ class Renderer {
 	}
 
 	/**
-	 * A different implementation for `_handleObjectFunction` which only creates the creates the render object pipeline.
+	 * A different implementation for `_handleObjectFunction` which only makes sure the object is ready for rendering.
 	 * Used in `compileAsync()`.
 	 *
 	 * @private