super-three 0.171.0 → 0.173.0

package/src/renderers/common/PostProcessing.js

@@ -3,27 +3,93 @@ import { vec4, renderOutput } from '../../nodes/TSL.js';
 import { LinearSRGBColorSpace, NoToneMapping } from '../../constants.js';
 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<vec4>} 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<vec4>}
+		 */
 		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<vec4>}
+		 */
 		this.needsUpdate = true;
 
-		_material.name = 'PostProcessing';
+		const material = new NodeMaterial();
+		material.name = 'PostProcessing';
+
+		/**
+		 * The full screen quad that is used to render
+		 * the effects.
+		 *
+		 * @private
+		 * @type {QuadMesh}
+		 */
+		this._quadMesh = new QuadMesh( material );
 
 	}
 
+	/**
+	 * 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;
 
@@ -35,7 +101,7 @@ class PostProcessing {
 
 		//
 
-		_quadMesh.render( renderer );
+		this._quadMesh.render( renderer );
 
 		//
 
@@ -44,7 +110,21 @@ class PostProcessing {
 
 	}
 
-	update() {
+	/**
+	 * Frees internal resources.
+	 */
+	dispose() {
+
+		this._quadMesh.material.dispose();
+
+	}
+
+	/**
+	 * Updates the state of the module.
+	 *
+	 * @private
+	 */
+	_update() {
 
 		if ( this.needsUpdate === true ) {
 
@@ -53,8 +133,8 @@ class PostProcessing {
 			const toneMapping = renderer.toneMapping;
 			const outputColorSpace = renderer.outputColorSpace;
 
-			_quadMesh.material.fragmentNode = this.outputColorTransform === true ? renderOutput( this.outputNode, toneMapping, outputColorSpace ) : this.outputNode.context( { toneMapping, outputColorSpace } );
-			_quadMesh.material.needsUpdate = true;
+			this._quadMesh.material.fragmentNode = this.outputColorTransform === true ? renderOutput( this.outputNode, toneMapping, outputColorSpace ) : this.outputNode.context( { toneMapping, outputColorSpace } );
+			this._quadMesh.material.needsUpdate = true;
 
 			this.needsUpdate = false;
 
@@ -62,9 +142,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;
 
@@ -76,7 +164,7 @@ class PostProcessing {
 
 		//
 
-		await _quadMesh.renderAsync( renderer );
+		await this._quadMesh.renderAsync( renderer );
 
 		//
 

package/src/renderers/common/ProgrammableStage.js

@@ -1,16 +1,74 @@
 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 {String} name - The name of the shader.
+	 * @param {Array<Object>?} [transforms=null] - The transforms (only relevant for compute stages with WebGL 2 which uses Transform Feedback).
+	 * @param {Array<Object>?} [attributes=null] - The attributes (only relevant for compute stages with WebGL 2 which uses Transform Feedback).
+	 */
+	constructor( code, stage, name, 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 name of the stage.
+		 * This is used for debugging purposes.
+		 *
+		 * @type {String}
+		 */
+		this.name = name;
+
+		/**
+		 * The transforms (only relevant for compute stages with WebGL 2 which uses Transform Feedback).
+		 *
+		 * @type {Array<Object>?}
+		 */
 		this.transforms = transforms;
+
+		/**
+		 * The attributes (only relevant for compute stages with WebGL 2 which uses Transform Feedback).
+		 *
+		 * @type {Array<Object>?}
+		 */
 		this.attributes = attributes;
 
+		/**
+		 * How often the programmable stage is currently in use.
+		 *
+		 * @type {Number}
+		 * @default 0
+		 */
 		this.usedTimes = 0;
 
 	}

package/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 Mesh
+ */
 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 );

package/src/renderers/common/RenderBundle.js

@@ -1,18 +1,24 @@
+/**
+ * This module is used to represent render bundles inside the renderer
+ * for further processing.
+ *
+ * @private
+ */
 class RenderBundle {
 
-	constructor( scene, camera ) {
+	/**
+	 * Constructs a new bundle group.
+	 *
+	 * @param {BundleGroup} bundleGroup - The bundle group.
+	 * @param {Camera} camera - The camera the bundle group is rendered with.
+	 */
+	constructor( bundleGroup, camera ) {
 
-		this.scene = scene;
+		this.bundleGroup = bundleGroup;
 		this.camera = camera;
 
 	}
 
-	clone() {
-
-		return Object.assign( new this.constructor(), this );
-
-	}
-
 }
 
 export default RenderBundle;

package/src/renderers/common/RenderBundles.js

@@ -1,35 +1,64 @@
 import ChainMap from './ChainMap.js';
 import RenderBundle from './RenderBundle.js';
 
+const _chainKeys = [];
+
+/**
+ * This renderer module manages render bundles.
+ *
+ * @private
+ */
 class RenderBundles {
 
+	/**
+	 * Constructs a new render bundle management component.
+	 */
 	constructor() {
 
-		this.lists = new ChainMap();
+		/**
+		 * A chain map for maintaining the render bundles.
+		 *
+		 * @type {ChainMap}
+		 */
+		this.bundles = new ChainMap();
 
 	}
 
-	get( scene, camera ) {
+	/**
+	 * Returns a render bundle for the given bundle group and camera.
+	 *
+	 * @param {BundleGroup} bundleGroup - The bundle group.
+	 * @param {Camera} camera - The camera the bundle group is rendered with.
+	 * @return {RenderBundle} The render bundle.
+	 */
+	get( bundleGroup, camera ) {
+
+		const bundles = this.bundles;
 
-		const lists = this.lists;
-		const keys = [ scene, camera ];
+		_chainKeys[ 0 ] = bundleGroup;
+		_chainKeys[ 1 ] = camera;
 
-		let list = lists.get( keys );
+		let bundle = bundles.get( _chainKeys );
 
-		if ( list === undefined ) {
+		if ( bundle === undefined ) {
 
-			list = new RenderBundle( scene, camera );
-			lists.set( keys, list );
+			bundle = new RenderBundle( bundleGroup, camera );
+			bundles.set( _chainKeys, bundle );
 
 		}
 
-		return list;
+		_chainKeys.length = 0;
+
+		return bundle;
 
 	}
 
+	/**
+	 * Frees all internal resources.
+	 */
 	dispose() {
 
-		this.lists = new ChainMap();
+		this.bundles = new ChainMap();
 
 	}
 

package/src/renderers/common/RenderContext.js

@@ -1,44 +1,235 @@
 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 active render target.
+		 *
+		 * @type {RenderTarget?}
+		 * @default null
+		 */
+		this.renderTarget = null;
+
+		/**
+		 * 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 active mipmap level.
+		 *
+		 * @type {Number}
+		 * @default 0
+		 */
+		this.activeMipmapLevel = 0;
+
+		/**
+		 * The number of MSAA samples. This value is always `1` when
+		 * MSAA isn't used.
+		 *
+		 * @type {Number}
+		 * @default 1
+		 */
 		this.sampleCount = 1;
 
+		/**
+		 * The active render target's width in physical pixels.
+		 *
+		 * @type {Number}
+		 * @default 0
+		 */
 		this.width = 0;
+
+		/**
+		 * The active render target's height in physical pixels.
+		 *
+		 * @type {Number}
+		 * @default 0
+		 */
 		this.height = 0;
 
+		/**
+		 * The occlusion query count.
+		 *
+		 * @type {Number}
+		 * @default 0
+		 */
+		this.occlusionQueryCount = 0;
+
+		/**
+		 * The current clipping context.
+		 *
+		 * @type {ClippingContext?}
+		 * @default null
+		 */
+		this.clippingContext = null;
+
+		/**
+		 * 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 +238,14 @@ class RenderContext {
 
 }
 
+/**
+ * Computes a cache key for the given render context. This key
+ * should identify the render target state so it is possible to
+ * configure the correct attachments in the respective backend.
+ *
+ * @param {RenderContext} renderContext - The render context.
+ * @return {Number} The cache key.
+ */
 export function getCacheKey( renderContext ) {
 
 	const { textures, activeCubeFace } = renderContext;