From f9c4319e009bd8d642e0746f74814efbe1def71c Mon Sep 17 00:00:00 2001 From: Michael Herzog Date: Mon, 23 Dec 2024 14:10:18 +0100 Subject: [PATCH] Renderer: Document more modules. (#30194) --- src/renderers/common/BufferUtils.js | 27 ++++ src/renderers/common/ComputePipeline.js | 24 +++ src/renderers/common/Geometries.js | 98 ++++++++++++ src/renderers/common/Lighting.js | 26 ++++ src/renderers/common/Pipeline.js | 22 +++ src/renderers/common/PostProcessing.js | 78 +++++++++- src/renderers/common/ProgrammableStage.js | 53 ++++++- src/renderers/common/QuadMesh.js | 59 ++++++- src/renderers/common/RenderList.js | 178 ++++++++++++++++++++++ src/renderers/common/RenderLists.js | 31 ++++ src/renderers/common/RenderPipeline.js | 24 +++ src/renderers/common/RendererUtils.js | 95 +++++++++++- 12 files changed, 699 insertions(+), 16 deletions(-) diff --git a/src/renderers/common/BufferUtils.js b/src/renderers/common/BufferUtils.js index 0cbdd4c773d3cc..1a953071afc290 100644 --- a/src/renderers/common/BufferUtils.js +++ b/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; diff --git a/src/renderers/common/ComputePipeline.js b/src/renderers/common/ComputePipeline.js index 8f29dc4756dbbe..7735939208cbb4 100644 --- a/src/renderers/common/ComputePipeline.js +++ b/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; } diff --git a/src/renderers/common/Geometries.js b/src/renderers/common/Geometries.js index 271f8a7991c009..ff9fc573521b22 100644 --- a/src/renderers/common/Geometries.js +++ b/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} 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} + */ this.wireframes = new WeakMap(); + /** + * This Weak Map is used to make sure buffer attributes are + * updated only once per render call. + * + * @type {WeakMap} + */ 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; diff --git a/src/renderers/common/Lighting.js b/src/renderers/common/Lighting.js index 9a1d4f36f68966..a92f22aad1f01e 100644 --- a/src/renderers/common/Lighting.js +++ b/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} 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 diff --git a/src/renderers/common/Pipeline.js b/src/renderers/common/Pipeline.js index 8f0f30418f5893..a12f9f01e0cd33 100644 --- a/src/renderers/common/Pipeline.js +++ b/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; } diff --git a/src/renderers/common/PostProcessing.js b/src/renderers/common/PostProcessing.js index 3792420048329f..28ca40aad8571b 100644 --- a/src/renderers/common/PostProcessing.js +++ b/src/renderers/common/PostProcessing.js @@ -6,24 +6,83 @@ import QuadMesh from '../../renderers/common/QuadMesh.js'; const _material = /*@__PURE__*/ new NodeMaterial(); const _quadMesh = /*@__PURE__*/ new QuadMesh( _material ); +/** + * This module is responsible to manage the post processing setups in apps. + * You usually create a single instance of this class and use it to define + * the output of your post processing effect chain. + * ```js + * const postProcessing = new PostProcessing( renderer ); + * + * const scenePass = pass( scene, camera ); + * + * postProcessing.outputNode = scenePass; + * ``` + */ class PostProcessing { + /** + * Constructs a new post processing management module. + * + * @param {Renderer} renderer - A reference to the renderer. + * @param {Node} outputNode - An optional output node. + */ constructor( renderer, outputNode = vec4( 0, 0, 1, 1 ) ) { + /** + * A reference to the renderer. + * + * @type {Renderer} + */ this.renderer = renderer; + + /** + * A node which defines the final output of the post + * processing. This is usually the last node in a chain + * of effect nodes. + * + * @type {Node} + */ this.outputNode = outputNode; + /** + * Whether the default output tone mapping and color + * space transformation should be enabled or not. + * + * It is enabled by default by it must be disabled when + * effects must be executed after tone mapping and color + * space conversion. A typical example is FXAA which + * requires sRGB input. + * + * When set to `false`, the app must control the output + * transformation with `RenderOutputNode`. + * + * ```js + * const outputPass = renderOutput( scenePass ); + * ``` + * + * @type {Boolean} + */ this.outputColorTransform = true; + /** + * Must be set to `true` when the output node changes. + * + * @type {Node} + */ this.needsUpdate = true; _material.name = 'PostProcessing'; } + /** + * When `PostProcessing` is used to apply post processing effects, + * the application must use this version of `render()` inside + * its animation loop (not the one from the renderer). + */ render() { - this.update(); + this._update(); const renderer = this.renderer; @@ -44,7 +103,12 @@ class PostProcessing { } - update() { + /** + * Updates the state of the module. + * + * @private + */ + _update() { if ( this.needsUpdate === true ) { @@ -62,9 +126,17 @@ class PostProcessing { } + /** + * When `PostProcessing` is used to apply post processing effects, + * the application must use this version of `renderAsync()` inside + * its animation loop (not the one from the renderer). + * + * @async + * @return {Promise} A Promise that resolves when the render has been finished. + */ async renderAsync() { - this.update(); + this._update(); const renderer = this.renderer; diff --git a/src/renderers/common/ProgrammableStage.js b/src/renderers/common/ProgrammableStage.js index c69627bf0cd9c8..f33d92d33060f3 100644 --- a/src/renderers/common/ProgrammableStage.js +++ b/src/renderers/common/ProgrammableStage.js @@ -1,16 +1,65 @@ let _id = 0; +/** + * Class for representing programmable stages which are vertex, + * fragment or compute shaders. Unlike fixed-function states (like blending), + * they represent the programmable part of a pipeline. + * + * @private + */ class ProgrammableStage { - constructor( code, type, transforms = null, attributes = null ) { + /** + * Constructs a new programmable stage. + * + * @param {String} code - The shader code. + * @param {('vertex'|'fragment'|'compute')} stage - The type of stage. + * @param {Array?} [transforms=null] - The transforms (only relevant for compute stages with WebGL 2 which uses Transform Feedback). + * @param {Array?} [attributes=null] - The attributes (only relevant for compute stages with WebGL 2 which uses Transform Feedback). + */ + constructor( code, stage, transforms = null, attributes = null ) { + /** + * The id of the programmable stage. + * + * @type {Number} + */ this.id = _id ++; + /** + * The shader code. + * + * @type {String} + */ this.code = code; - this.stage = type; + + /** + * The type of stage. + * + * @type {String} + */ + this.stage = stage; + + /** + * The transforms (only relevant for compute stages with WebGL 2 which uses Transform Feedback). + * + * @type {Array?} + */ this.transforms = transforms; + + /** + * The attributes (only relevant for compute stages with WebGL 2 which uses Transform Feedback). + * + * @type {Array?} + */ this.attributes = attributes; + /** + * How often the programmable stage is currently in use. + * + * @type {Number} + * @default 0 + */ this.usedTimes = 0; } diff --git a/src/renderers/common/QuadMesh.js b/src/renderers/common/QuadMesh.js index 1274e4ba75276f..a0968c9fe975a0 100644 --- a/src/renderers/common/QuadMesh.js +++ b/src/renderers/common/QuadMesh.js @@ -3,14 +3,23 @@ import { Float32BufferAttribute } from '../../core/BufferAttribute.js'; import { Mesh } from '../../objects/Mesh.js'; import { OrthographicCamera } from '../../cameras/OrthographicCamera.js'; -// Helper for passes that need to fill the viewport with a single quad. - const _camera = /*@__PURE__*/ new OrthographicCamera( - 1, 1, 1, - 1, 0, 1 ); -// https://github.com/mrdoob/three.js/pull/21358 - +/** + * The purpose of this special geometry is to fill the entire viewport with a single triangle. + * + * Reference: {@link https://github.com/mrdoob/three.js/pull/21358} + * + * @private + * @augments BufferGeometry + */ class QuadGeometry extends BufferGeometry { + /** + * Constructs a new quad geometry. + * + * @param {Boolean} [flipY=false] - Whether the uv coordinates should be flipped along the vertical axis or not. + */ constructor( flipY = false ) { super(); @@ -26,24 +35,64 @@ class QuadGeometry extends BufferGeometry { const _geometry = /*@__PURE__*/ new QuadGeometry(); + +/** + * This module is a helper for passes which need to render a full + * screen effect which is quite common in context of post processing. + * + * The intended usage is to reuse a single quad mesh for rendering + * subsequent passes by just reassigning the `material` reference. + * + * @augments BufferGeometry + */ class QuadMesh extends Mesh { + /** + * Constructs a new quad mesh. + * + * @param {Material?} [material=null] - The material to render the quad mesh with. + */ constructor( material = null ) { super( _geometry, material ); + /** + * The camera to render the quad mesh with. + * + * @type {OrthographicCamera} + * @readonly + */ this.camera = _camera; + /** + * This flag can be used for type testing. + * + * @type {Boolean} + * @readonly + * @default true + */ this.isQuadMesh = true; } - renderAsync( renderer ) { + /** + * Async version of `render()`. + * + * @async + * @param {Renderer} renderer - The renderer. + * @return {Promise} A Promise that resolves when the render has been finished. + */ + async renderAsync( renderer ) { return renderer.renderAsync( this, _camera ); } + /** + * Renders the quad mesh + * + * @param {Renderer} renderer - The renderer. + */ render( renderer ) { renderer.render( this, _camera ); diff --git a/src/renderers/common/RenderList.js b/src/renderers/common/RenderList.js index d819ee90bbb4c2..59412530bba172 100644 --- a/src/renderers/common/RenderList.js +++ b/src/renderers/common/RenderList.js @@ -1,5 +1,14 @@ import { DoubleSide } from '../../constants.js'; +/** + * Default sorting function for opaque render items. + * + * @private + * @function + * @param {Object} a - The first render item. + * @param {Object} b - The second render item. + * @return {Number} A numeric value which defines the sort order. + */ function painterSortStable( a, b ) { if ( a.groupOrder !== b.groupOrder ) { @@ -26,6 +35,15 @@ function painterSortStable( a, b ) { } +/** + * Default sorting function for transparent render items. + * + * @private + * @function + * @param {Object} a - The first render item. + * @param {Object} b - The second render item. + * @return {Number} A numeric value which defines the sort order. + */ function reversePainterSortStable( a, b ) { if ( a.groupOrder !== b.groupOrder ) { @@ -48,6 +66,14 @@ function reversePainterSortStable( a, b ) { } +/** + * Returns `true` if the given transparent material requires a double pass. + * + * @private + * @function + * @param {Material} material - The transparent material. + * @return {Boolean} Whether the given material requires a double pass or not. + */ function needsDoublePass( material ) { const hasTransmission = material.transmission > 0 || material.transmissionNode; @@ -56,28 +82,120 @@ function needsDoublePass( material ) { } +/** + * When the renderer analyzes the scene at the beginning of a render call, + * it stores 3D object for further processing in render lists. Depending on the + * properties of a 3D objects (like their transformation or material state), the + * objects are maintained in ordered lists for the actual rendering. + * + * Render lists are unique per scene and camera combination. + * + * @private + * @augments Pipeline + */ class RenderList { + /** + * Constructs a render list. + * + * @param {Lighting} lighting - The lighting management component. + * @param {Scene} scene - The scene. + * @param {Camera} camera - The camera the scene is rendered with. + */ constructor( lighting, scene, camera ) { + /** + * 3D objects are transformed into render items and stored in this array. + * + * @type {Array} + */ this.renderItems = []; + + /** + * The current render items index. + * + * @type {Number} + * @default 0 + */ this.renderItemsIndex = 0; + /** + * A list with opaque render items. + * + * @type {Array} + */ this.opaque = []; + + /** + * A list with transparent render items which require + * double pass rendering (e.g. transmissive objects). + * + * @type {Array} + */ this.transparentDoublePass = []; + + /** + * A list with transparent render items. + * + * @type {Array} + */ this.transparent = []; + + /** + * A list with transparent render bundle data. + * + * @type {Array} + */ this.bundles = []; + /** + * The render list's lights node. This node is later + * relevant for the actual analytical light nodes which + * compute the scene's lighting in the shader. + * + * @type {LightsNode} + */ this.lightsNode = lighting.getNode( scene, camera ); + + /** + * The scene's lights stored in an array. This array + * is used to setup the lights node. + * + * @type {Array} + */ this.lightsArray = []; + /** + * The scene. + * + * @type {Scene} + */ this.scene = scene; + + /** + * The camera the scene is rendered with. + * + * @type {Camera} + */ this.camera = camera; + /** + * How many objects perform occlusion query tests. + * + * @type {Number} + * @default 0 + */ this.occlusionQueryCount = 0; } + /** + * This method is called right at the beginning of a render call + * before the scene is analyzed. It prepares the internal data + * structures for the upcoming render lists generation. + * + * @return {RenderList} A reference to this render list. + */ begin() { this.renderItemsIndex = 0; @@ -95,6 +213,22 @@ class RenderList { } + /** + * Returns a render item for the giving render item state. The state is defined + * by a series of object-related parameters. + * + * The method avoids object creation by holding render items and reusing them in + * subsequent render calls (just with different property values). + * + * @param {Object3D} object - The 3D object. + * @param {BufferGeometry} geometry - The 3D object's geometry. + * @param {Material} material - The 3D object's material. + * @param {Number} groupOrder - The current group order. + * @param {Number} z - Th 3D object's depth value (z value in clip space). + * @param {Number?} group - {Object?} group - Only relevant for objects using multiple materials. This represents a group entry from the respective `BufferGeometry`. + * @param {ClippingContext} clippingContext - The current clipping context. + * @return {Object} The render item. + */ getNextRenderItem( object, geometry, material, groupOrder, z, group, clippingContext ) { let renderItem = this.renderItems[ this.renderItemsIndex ]; @@ -135,6 +269,18 @@ class RenderList { } + /** + * Pushes the given object as a render item to the internal render lists. + * The selected lists depend on the object properties. + * + * @param {Object3D} object - The 3D object. + * @param {BufferGeometry} geometry - The 3D object's geometry. + * @param {Material} material - The 3D object's material. + * @param {Number} groupOrder - The current group order. + * @param {Number} z - Th 3D object's depth value (z value in clip space). + * @param {Number?} group - {Object?} group - Only relevant for objects using multiple materials. This represents a group entry from the respective `BufferGeometry`. + * @param {ClippingContext} clippingContext - The current clipping context. + */ push( object, geometry, material, groupOrder, z, group, clippingContext ) { const renderItem = this.getNextRenderItem( object, geometry, material, groupOrder, z, group, clippingContext ); @@ -155,6 +301,18 @@ class RenderList { } + /** + * Inserts the given object as a render item at the start of the internal render lists. + * The selected lists depend on the object properties. + * + * @param {Object3D} object - The 3D object. + * @param {BufferGeometry} geometry - The 3D object's geometry. + * @param {Material} material - The 3D object's material. + * @param {Number} groupOrder - The current group order. + * @param {Number} z - Th 3D object's depth value (z value in clip space). + * @param {Number?} group - {Object?} group - Only relevant for objects using multiple materials. This represents a group entry from the respective `BufferGeometry`. + * @param {ClippingContext} clippingContext - The current clipping context. + */ unshift( object, geometry, material, groupOrder, z, group, clippingContext ) { const renderItem = this.getNextRenderItem( object, geometry, material, groupOrder, z, group, clippingContext ); @@ -173,18 +331,34 @@ class RenderList { } + /** + * Pushes render bundle group data into the render list. + * + * @param {Object} group - Bundle group data. + */ pushBundle( group ) { this.bundles.push( group ); } + /** + * Pushes a light into the render list. + * + * @param {Light} light - The light. + */ pushLight( light ) { this.lightsArray.push( light ); } + /** + * Sorts the internal render lists. + * + * @param {Function} customOpaqueSort - A custom sort function for opaque objects. + * @param {Function} customTransparentSort - A custom sort function for transparent objects. + */ sort( customOpaqueSort, customTransparentSort ) { if ( this.opaque.length > 1 ) this.opaque.sort( customOpaqueSort || painterSortStable ); @@ -193,6 +367,10 @@ class RenderList { } + /** + * This method performs finalizing tasks right after the render lists + * have been generated. + */ finish() { // update lights diff --git a/src/renderers/common/RenderLists.js b/src/renderers/common/RenderLists.js index 60cb94c30f2a81..57a334418c04df 100644 --- a/src/renderers/common/RenderLists.js +++ b/src/renderers/common/RenderLists.js @@ -1,16 +1,44 @@ import ChainMap from './ChainMap.js'; import RenderList from './RenderList.js'; +/** + * This renderer module manages the render lists which are unique + * per scene and camera combination. + * + * @private + */ class RenderLists { + /** + * Constructs a render lists management component. + * + * @param {Lighting} lighting - The lighting management component. + */ constructor( lighting ) { + /** + * The lighting management component. + * + * @type {Lighting} + */ this.lighting = lighting; + /** + * The internal chain map which holds the render lists. + * + * @type {ChainMap} + */ this.lists = new ChainMap(); } + /** + * Returns a render list for the given scene and camera. + * + * @param {Scene} scene - The scene. + * @param {Camera} camera - The camera. + * @return {RenderList} The render list. + */ get( scene, camera ) { const lists = this.lists; @@ -29,6 +57,9 @@ class RenderLists { } + /** + * Frees all internal resources. + */ dispose() { this.lists = new ChainMap(); diff --git a/src/renderers/common/RenderPipeline.js b/src/renderers/common/RenderPipeline.js index d9aeadda798322..bcc91a22b5c2fa 100644 --- a/src/renderers/common/RenderPipeline.js +++ b/src/renderers/common/RenderPipeline.js @@ -1,12 +1,36 @@ import Pipeline from './Pipeline.js'; +/** + * Class for representing render pipelines. + * + * @private + * @augments Pipeline + */ class RenderPipeline extends Pipeline { + /** + * Constructs a new render pipeline. + * + * @param {String} cacheKey - The pipeline's cache key. + * @param {ProgrammableStage} vertexProgram - The pipeline's vertex shader. + * @param {ProgrammableStage} fragmentProgram - The pipeline's fragment shader. + */ constructor( cacheKey, vertexProgram, fragmentProgram ) { super( cacheKey ); + /** + * The pipeline's vertex shader. + * + * @type {ProgrammableStage} + */ this.vertexProgram = vertexProgram; + + /** + * The pipeline's fragment shader. + * + * @type {ProgrammableStage} + */ this.fragmentProgram = fragmentProgram; } diff --git a/src/renderers/common/RendererUtils.js b/src/renderers/common/RendererUtils.js index 8f733db63def06..35c60f9547b72f 100644 --- a/src/renderers/common/RendererUtils.js +++ b/src/renderers/common/RendererUtils.js @@ -1,7 +1,17 @@ import { Color } from '../../math/Color.js'; -// renderer state - +/** @module RendererUtils **/ + +/** + * Saves the state of the given renderer and stores it into the given state object. + * + * If not state object is provided, the function creates one. + * + * @function + * @param {Renderer} renderer - The renderer. + * @param {Object} [state={}] - The state. + * @return {Object} The state. + */ export function saveRendererState( renderer, state = {} ) { state.toneMapping = renderer.toneMapping; @@ -22,6 +32,17 @@ export function saveRendererState( renderer, state = {} ) { } +/** + * Saves the state of the given renderer and stores it into the given state object. + * Besides, the function also resets the state of the renderer to its default values. + * + * If not state object is provided, the function creates one. + * + * @function + * @param {Renderer} renderer - The renderer. + * @param {Object} [state={}] - The state. + * @return {Object} The state. + */ export function resetRendererState( renderer, state ) { state = saveRendererState( renderer, state ); @@ -35,6 +56,13 @@ export function resetRendererState( renderer, state ) { } +/** + * Restores the state of the given renderer from the given state object. + * + * @function + * @param {Renderer} renderer - The renderer. + * @param {Object} state - The state to restore. + */ export function restoreRendererState( renderer, state ) { renderer.toneMapping = state.toneMapping; @@ -50,8 +78,16 @@ export function restoreRendererState( renderer, state ) { } -// scene state - +/** + * Saves the state of the given scene and stores it into the given state object. + * + * If not state object is provided, the function creates one. + * + * @function + * @param {Scene} scene - The scene. + * @param {Object} [state={}] - The state. + * @return {Object} The state. + */ export function saveSceneState( scene, state = {} ) { state.background = scene.background; @@ -64,6 +100,17 @@ export function saveSceneState( scene, state = {} ) { } +/** + * Saves the state of the given scene and stores it into the given state object. + * Besides, the function also resets the state of the scene to its default values. + * + * If not state object is provided, the function creates one. + * + * @function + * @param {Scene} scene - The scene. + * @param {Object} [state={}] - The state. + * @return {Object} The state. + */ export function resetSceneState( scene, state ) { state = saveSceneState( scene, state ); @@ -78,6 +125,13 @@ export function resetSceneState( scene, state ) { } +/** + * Restores the state of the given scene from the given state object. + * + * @function + * @param {Scene} scene - The scene. + * @param {Object} state - The state to restore. + */ export function restoreSceneState( scene, state ) { scene.background = state.background; @@ -88,8 +142,17 @@ export function restoreSceneState( scene, state ) { } -// renderer and scene state - +/** + * Saves the state of the given renderer and scene and stores it into the given state object. + * + * If not state object is provided, the function creates one. + * + * @function + * @param {Renderer} renderer - The renderer. + * @param {Scene} scene - The scene. + * @param {Object} [state={}] - The state. + * @return {Object} The state. + */ export function saveRendererAndSceneState( renderer, scene, state = {} ) { state = saveRendererState( renderer, state ); @@ -99,6 +162,18 @@ export function saveRendererAndSceneState( renderer, scene, state = {} ) { } +/** + * Saves the state of the given renderer and scene and stores it into the given state object. + * Besides, the function also resets the state of the renderer and scene to its default values. + * + * If not state object is provided, the function creates one. + * + * @function + * @param {Renderer} renderer - The renderer. + * @param {Scene} scene - The scene. + * @param {Object} [state={}] - The state. + * @return {Object} The state. + */ export function resetRendererAndSceneState( renderer, scene, state ) { state = resetRendererState( renderer, state ); @@ -108,6 +183,14 @@ export function resetRendererAndSceneState( renderer, scene, state ) { } +/** + * Restores the state of the given renderer and scene from the given state object. + * + * @function + * @param {Renderer} renderer - The renderer. + * @param {Scene} scene - The scene. + * @param {Object} state - The state to restore. + */ export function restoreRendererAndSceneState( renderer, scene, state ) { restoreRendererState( renderer, state );