Renderer: Document more modules. (#30188)

* Renderer: Document more modules.

* Update BundleGroup.js

Author: Mugen87

src/renderers/common/Animation.js

@@ -1,16 +1,63 @@
+
+/**
+ * This module manages the internal animation loop of the renderer.
+ *
+ * @private
+ */
 class Animation {
 
+	/**
+	 * Constructs a new animation loop management component.
+	 *
+	 * @param {Nodes} nodes - Renderer component for managing nodes relatd logic.
+	 * @param {Info} info - Renderer component for managing metrics and monitoring data.
+	 */
 	constructor( nodes, info ) {
 
+		/**
+		 * Renderer component for managing nodes relatd logic.
+		 *
+		 * @type {Nodes}
+		 */
 		this.nodes = nodes;
+
+		/**
+		 * Renderer component for managing metrics and monitoring data.
+		 *
+		 * @type {Info}
+		 */
 		this.info = info;
 
+		/**
+		 * A reference to the context from `requestAnimationFrame()` can
+		 * be called (usually `window`).
+		 *
+		 * @type {Window|XRSession}
+		 */
 		this._context = self;
+
+		/**
+		 * The user-defined animation loop.
+		 *
+		 * @type {Function?}
+		 * @default null
+		 */
 		this._animationLoop = null;
+
+		/**
+		 * The requestId whic is returned from the `requestAnimationFrame()` call.
+		 * Can be used to cancel the stop the animation loop.
+		 *
+		 * @type {Number?}
+		 * @default null
+		 */
 		this._requestId = null;
 
 	}
 
+	/**
+	 * Starts the internal animation loop.
+	 */
 	start() {
 
 		const update = ( time, frame ) => {
@@ -31,6 +78,9 @@ class Animation {
 
 	}
 
+	/**
+	 * Stops the internal animation loop.
+	 */
 	stop() {
 
 		this._context.cancelAnimationFrame( this._requestId );
@@ -39,18 +89,31 @@ class Animation {
 
 	}
 
+	/**
+	 * Defines the user-level animation loop.
+	 *
+	 * @param {Function} callback - The animation loop.
+	 */
 	setAnimationLoop( callback ) {
 
 		this._animationLoop = callback;
 
 	}
 
+	/**
+	 * Defines the context in which `requestAnimationFrame()` is executed.
+	 *
+	 * @param {Window|XRSession} context - The context to set.
+	 */
 	setContext( context ) {
 
 		this._context = context;
 
 	}
 
+	/**
+	 * Frees all internal resources and stops the animation loop.
+	 */
 	dispose() {
 
 		this.stop();

src/renderers/common/Attributes.js

@@ -3,16 +3,38 @@ import { AttributeType } from './Constants.js';
 
 import { DynamicDrawUsage } from '../../constants.js';
 
+/**
+ * This renderer module manages geometry attributes.
+ *
+ * @private
+ * @augments DataMap
+ */
 class Attributes extends DataMap {
 
+	/**
+	 * Constructs a new attribute management component.
+	 *
+	 * @param {Backend} backend - The renderer's backend.
+	 */
 	constructor( backend ) {
 
 		super();
 
+		/**
+		 * The renderer's backend.
+		 *
+		 * @type {Backend}
+		 */
 		this.backend = backend;
 
 	}
 
+	/**
+	 * Deletes the data for the given attribute.
+	 *
+	 * @param {BufferAttribute} attribute - The attribute.
+	 * @return {Object} The deleted attribute data.
+	 */
 	delete( attribute ) {
 
 		const attributeData = super.delete( attribute );
@@ -27,6 +49,13 @@ class Attributes extends DataMap {
 
 	}
 
+	/**
+	 * Updates the given attribute. This method creates attribute buffers
+	 * for new attributes and updates data for existing ones.
+	 *
+	 * @param {BufferAttribute} attribute - The attribute to update.
+	 * @param {Number} type - The attribute type.
+	 */
 	update( attribute, type ) {
 
 		const data = this.get( attribute );
@@ -69,6 +98,13 @@ class Attributes extends DataMap {
 
 	}
 
+	/**
+	 * Utility method for handling interleaved buffer attributes correctly.
+	 * To process them, their `InterleavedBuffer` is returned.
+	 *
+	 * @param {BufferAttribute} attribute - The attribute.
+	 * @return {BufferAttribute|InterleavedBuffer}
+	 */
 	_getBufferAttribute( attribute ) {
 
 		if ( attribute.isInterleavedBufferAttribute ) attribute = attribute.data;

src/renderers/common/Background.js

@@ -9,17 +9,50 @@ import { BackSide, LinearSRGBColorSpace } from '../../constants.js';
 
 const _clearColor = /*@__PURE__*/ new Color4();
 
+/**
+ * This renderer module manages the background.
+ *
+ * @private
+ * @augments DataMap
+ */
 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.
+	 */
 	constructor( renderer, nodes ) {
 
 		super();
 
+		/**
+		 * The renderer.
+		 *
+		 * @type {Renderer}
+		 */
 		this.renderer = renderer;
+
+		/**
+		 * Renderer component for managing nodes relatd logic.
+		 *
+		 * @type {Nodes}
+		 */
 		this.nodes = nodes;
 
 	}
 
+	/**
+	 * Updates the background for the given scene. Depending on how `Scene.background`
+	 * or `Scene.backgroundNode` are configured, this method might configure a simple clear
+	 * or add a mesh to the render list for rendering the background as a textured plane
+	 * or skybox.
+	 *
+	 * @param {Scene} scene - The scene.
+	 * @param {RenderList} renderList - The current render list.
+	 * @param {RenderContext} renderContext - The current render context.
+	 */
 	update( scene, renderList, renderContext ) {
 
 		const renderer = this.renderer;

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

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;