Renderer: Document more modules. (#30194)

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;

src/renderers/common/ComputePipeline.js

@@ -1,13 +1,37 @@
 import Pipeline from './Pipeline.js';
 
+/**
+ * Class for representing compute pipelines.
+ *
+ * @private
+ * @augments Pipeline
+ */
 class ComputePipeline extends Pipeline {
 
+	/**
+	 * Constructs a new render pipeline.
+	 *
+	 * @param {String} cacheKey - The pipeline's cache key.
+	 * @param {ProgrammableStage} computeProgram - The pipeline's compute shader.
+	 */
 	constructor( cacheKey, computeProgram ) {
 
 		super( cacheKey );
 
+		/**
+		 * The pipeline's compute shader.
+		 *
+		 * @type {ProgrammableStage}
+		 */
 		this.computeProgram = computeProgram;
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {Boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isComputePipeline = true;
 
 	}

src/renderers/common/Geometries.js

@@ -3,6 +3,14 @@ import { AttributeType } from './Constants.js';
 
 import { Uint16BufferAttribute, Uint32BufferAttribute } from '../../core/BufferAttribute.js';
 
+/**
+ * Returns `true` if the given array has values that require an Uint32 array type.
+ *
+ * @private
+ * @function
+ * @param {Array<Number>} array - The array to test.
+ * @return {Booolean} Whether the given array has values that require an Uint32 array type or not.
+ */
 function arrayNeedsUint32( array ) {
 
 	// assumes larger values usually on last
@@ -17,12 +25,28 @@ function arrayNeedsUint32( array ) {
 
 }
 
+/**
+ * Returns the wireframe version for the given geometry.
+ *
+ * @private
+ * @function
+ * @param {BufferGeometry} geometry - The geometry.
+ * @return {Number} The versio.
+ */
 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 +91,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 +154,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 +167,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,6 +216,11 @@ class Geometries extends DataMap {
 
 	}
 
+	/**
+	 * Updates the geometry attributes of the given render object.
+	 *
+	 * @param {RenderObject} renderObject - The render object.
+	 */
 	updateAttributes( renderObject ) {
 
 		// attributes
@@ -184,6 +263,12 @@ class Geometries extends DataMap {
 
 	}
 
+	/**
+	 * 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;
@@ -220,12 +305,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;

src/renderers/common/Lighting.js

@@ -3,20 +3,46 @@ import ChainMap from './ChainMap.js';
 
 const _defaultLights = /*@__PURE__*/ new LightsNode();
 
+/**
+ * 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 {Boolean} Whether if the given render object has an initialized geometry or not.
+	 */
 	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

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