@plastic-software/three 0.174.0 → 0.175.0

package/examples/jsm/postprocessing/ClearPass.js

@@ -3,20 +3,70 @@ import {
 } from 'three';
 import { Pass } from './Pass.js';
 
+/**
+ * This class can be used to force a clear operation for the current read or
+ * default framebuffer (when rendering to screen).
+ *
+ * ```js
+ * const clearPass = new ClearPass();
+ * composer.addPass( clearPass );
+ * ```
+ *
+ * @augments Pass
+ */
 class ClearPass extends Pass {
 
-	constructor( clearColor, clearAlpha ) {
+	/**
+	 * Constructs a new clear pass.
+	 *
+	 * @param {(number|Color|string)} [clearColor=0x000000] - The clear color.
+	 * @param {number} [clearAlpha=0] - The clear alpha.
+	 */
+	constructor( clearColor = 0x000000, clearAlpha = 0 ) {
 
 		super();
 
+		/**
+		 * Overwritten to disable the swap.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.needsSwap = false;
 
-		this.clearColor = ( clearColor !== undefined ) ? clearColor : 0x000000;
-		this.clearAlpha = ( clearAlpha !== undefined ) ? clearAlpha : 0;
+		/**
+		 * The clear color.
+		 *
+		 * @type {(number|Color|string)}
+		 * @default 0x000000
+		 */
+		this.clearColor = clearColor;
+
+		/**
+		 * The clear alpha.
+		 *
+		 * @type {number}
+		 * @default 0
+		 */
+		this.clearAlpha = clearAlpha;
+
+		// internals
+
 		this._oldClearColor = new Color();
 
 	}
 
+	/**
+	 * Performs the clear operation. This affects the current read or the default framebuffer.
+	 *
+	 * @param {WebGLRenderer} renderer - The renderer.
+	 * @param {WebGLRenderTarget} writeBuffer - The write buffer. This buffer is intended as the rendering
+	 * destination for the pass.
+	 * @param {WebGLRenderTarget} readBuffer - The read buffer. The pass can access the result from the
+	 * previous pass from this buffer.
+	 * @param {number} deltaTime - The delta time in seconds.
+	 * @param {boolean} maskActive - Whether masking is active or not.
+	 */
 	render( renderer, writeBuffer, readBuffer /*, deltaTime, maskActive */ ) {
 
 		let oldClearAlpha;

package/examples/jsm/postprocessing/CubeTexturePass.js

@@ -10,30 +10,78 @@ import {
 } from 'three';
 import { Pass } from './Pass.js';
 
+/**
+ * This pass can be used to render a cube texture over the entire screen.
+ *
+ * ```js
+ * const cubeMap = new THREE.CubeTextureLoader().load( urls );
+ *
+ * const cubeTexturePass = new CubeTexturePass( camera, cubemap );
+ * composer.addPass( cubeTexturePass );
+ * ```
+ *
+ * @augments Pass
+ */
 class CubeTexturePass extends Pass {
 
+	/**
+	 * Constructs a new cube texture pass.
+	 *
+	 * @param {PerspectiveCamera} camera - The camera.
+	 * @param {CubeTexture} tCube - The cube texture to render.
+	 * @param {number} [opacity=1] - The opacity.
+	 */
 	constructor( camera, tCube, opacity = 1 ) {
 
 		super();
 
+		/**
+		 * The camera.
+		 *
+		 * @type {PerspectiveCamera}
+		 */
 		this.camera = camera;
 
+		/**
+		 * The cube texture to render.
+		 *
+		 * @type {CubeTexture}
+		 */
+		this.tCube = tCube;
+
+		/**
+		 * The opacity.
+		 *
+		 * @type {number}
+		 * @default 1
+		 */
+		this.opacity = opacity;
+
+		/**
+		 * Overwritten to disable the swap.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.needsSwap = false;
 
-		this.cubeShader = ShaderLib[ 'cube' ];
-		this.cubeMesh = new Mesh(
+		// internals
+
+		const cubeShader = ShaderLib[ 'cube' ];
+
+		this._cubeMesh = new Mesh(
 			new BoxGeometry( 10, 10, 10 ),
 			new ShaderMaterial( {
-				uniforms: UniformsUtils.clone( this.cubeShader.uniforms ),
-				vertexShader: this.cubeShader.vertexShader,
-				fragmentShader: this.cubeShader.fragmentShader,
+				uniforms: UniformsUtils.clone( cubeShader.uniforms ),
+				vertexShader: cubeShader.vertexShader,
+				fragmentShader: cubeShader.fragmentShader,
 				depthTest: false,
 				depthWrite: false,
 				side: BackSide
 			} )
 		);
 
-		Object.defineProperty( this.cubeMesh.material, 'envMap', {
+		Object.defineProperty( this._cubeMesh.material, 'envMap', {
 
 			get: function () {
 
@@ -43,40 +91,52 @@ class CubeTexturePass extends Pass {
 
 		} );
 
-		this.tCube = tCube;
-		this.opacity = opacity;
-
-		this.cubeScene = new Scene();
-		this.cubeCamera = new PerspectiveCamera();
-		this.cubeScene.add( this.cubeMesh );
+		this._cubeScene = new Scene();
+		this._cubeCamera = new PerspectiveCamera();
+		this._cubeScene.add( this._cubeMesh );
 
 	}
 
+	/**
+	 * Performs the cube texture pass.
+	 *
+	 * @param {WebGLRenderer} renderer - The renderer.
+	 * @param {WebGLRenderTarget} writeBuffer - The write buffer. This buffer is intended as the rendering
+	 * destination for the pass.
+	 * @param {WebGLRenderTarget} readBuffer - The read buffer. The pass can access the result from the
+	 * previous pass from this buffer.
+	 * @param {number} deltaTime - The delta time in seconds.
+	 * @param {boolean} maskActive - Whether masking is active or not.
+	 */
 	render( renderer, writeBuffer, readBuffer/*, deltaTime, maskActive*/ ) {
 
 		const oldAutoClear = renderer.autoClear;
 		renderer.autoClear = false;
 
-		this.cubeCamera.projectionMatrix.copy( this.camera.projectionMatrix );
-		this.cubeCamera.quaternion.setFromRotationMatrix( this.camera.matrixWorld );
+		this._cubeCamera.projectionMatrix.copy( this.camera.projectionMatrix );
+		this._cubeCamera.quaternion.setFromRotationMatrix( this.camera.matrixWorld );
 
-		this.cubeMesh.material.uniforms.tCube.value = this.tCube;
-		this.cubeMesh.material.uniforms.tFlip.value = ( this.tCube.isCubeTexture && this.tCube.isRenderTargetTexture === false ) ? - 1 : 1;
-		this.cubeMesh.material.uniforms.opacity.value = this.opacity;
-		this.cubeMesh.material.transparent = ( this.opacity < 1.0 );
+		this._cubeMesh.material.uniforms.tCube.value = this.tCube;
+		this._cubeMesh.material.uniforms.tFlip.value = ( this.tCube.isCubeTexture && this.tCube.isRenderTargetTexture === false ) ? - 1 : 1;
+		this._cubeMesh.material.uniforms.opacity.value = this.opacity;
+		this._cubeMesh.material.transparent = ( this.opacity < 1.0 );
 
 		renderer.setRenderTarget( this.renderToScreen ? null : readBuffer );
 		if ( this.clear ) renderer.clear();
-		renderer.render( this.cubeScene, this.cubeCamera );
+		renderer.render( this._cubeScene, this._cubeCamera );
 
 		renderer.autoClear = oldAutoClear;
 
 	}
 
+	/**
+	 * Frees the GPU-related resources allocated by this instance. Call this
+	 * method whenever the pass is no longer used in your app.
+	 */
 	dispose() {
 
-		this.cubeMesh.geometry.dispose();
-		this.cubeMesh.material.dispose();
+		this._cubeMesh.geometry.dispose();
+		this._cubeMesh.material.dispose();
 
 	}
 

package/examples/jsm/postprocessing/DotScreenPass.js

@@ -5,33 +5,77 @@ import {
 import { Pass, FullScreenQuad } from './Pass.js';
 import { DotScreenShader } from '../shaders/DotScreenShader.js';
 
+/**
+ * Pass for creating a dot-screen effect.
+ *
+ * ```js
+ * const pass = new DotScreenPass( new THREE.Vector2( 0, 0 ), 0.5, 0.8 );
+ * composer.addPass( pass );
+ * ```
+ *
+ * @augments Pass
+ */
 class DotScreenPass extends Pass {
 
+	/**
+	 * Constructs a new dot screen pass.
+	 *
+	 * @param {Vector2} center - The center point.
+	 * @param {number} angle - The rotation of the effect in radians.
+	 * @param {number} scale - The scale of the effect. A higher value means smaller dots.
+	 */
 	constructor( center, angle, scale ) {
 
 		super();
 
-		const shader = DotScreenShader;
-
-		this.uniforms = UniformsUtils.clone( shader.uniforms );
+		/**
+		 * The pass uniforms. Use this object if you want to update the
+		 * `center`, `angle` or `scale` values at runtime.
+		 * ```js
+		 * pass.uniforms.center.value.copy( center );
+		 * pass.uniforms.angle.value = 0;
+		 * pass.uniforms.scale.value = 0.5;
+		 * ```
+		 *
+		 * @type {Object}
+		 */
+		this.uniforms = UniformsUtils.clone( DotScreenShader.uniforms );
 
 		if ( center !== undefined ) this.uniforms[ 'center' ].value.copy( center );
 		if ( angle !== undefined ) this.uniforms[ 'angle' ].value = angle;
 		if ( scale !== undefined ) this.uniforms[ 'scale' ].value = scale;
 
+		/**
+		 * The pass material.
+		 *
+		 * @type {ShaderMaterial}
+		 */
 		this.material = new ShaderMaterial( {
 
-			name: shader.name,
+			name: DotScreenShader.name,
 			uniforms: this.uniforms,
-			vertexShader: shader.vertexShader,
-			fragmentShader: shader.fragmentShader
+			vertexShader: DotScreenShader.vertexShader,
+			fragmentShader: DotScreenShader.fragmentShader
 
 		} );
 
-		this.fsQuad = new FullScreenQuad( this.material );
+		// internals
+
+		this._fsQuad = new FullScreenQuad( this.material );
 
 	}
 
+	/**
+	 * Performs the dot screen pass.
+	 *
+	 * @param {WebGLRenderer} renderer - The renderer.
+	 * @param {WebGLRenderTarget} writeBuffer - The write buffer. This buffer is intended as the rendering
+	 * destination for the pass.
+	 * @param {WebGLRenderTarget} readBuffer - The read buffer. The pass can access the result from the
+	 * previous pass from this buffer.
+	 * @param {number} deltaTime - The delta time in seconds.
+	 * @param {boolean} maskActive - Whether masking is active or not.
+	 */
 	render( renderer, writeBuffer, readBuffer /*, deltaTime, maskActive */ ) {
 
 		this.uniforms[ 'tDiffuse' ].value = readBuffer.texture;
@@ -40,23 +84,27 @@ class DotScreenPass extends Pass {
 		if ( this.renderToScreen ) {
 
 			renderer.setRenderTarget( null );
-			this.fsQuad.render( renderer );
+			this._fsQuad.render( renderer );
 
 		} else {
 
 			renderer.setRenderTarget( writeBuffer );
 			if ( this.clear ) renderer.clear();
-			this.fsQuad.render( renderer );
+			this._fsQuad.render( renderer );
 
 		}
 
 	}
 
+	/**
+	 * Frees the GPU-related resources allocated by this instance. Call this
+	 * method whenever the pass is no longer used in your app.
+	 */
 	dispose() {
 
 		this.material.dispose();
 
-		this.fsQuad.dispose();
+		this._fsQuad.dispose();
 
 	}
 

package/examples/jsm/postprocessing/EffectComposer.js

@@ -9,10 +9,51 @@ import { CopyShader } from '../shaders/CopyShader.js';
 import { ShaderPass } from './ShaderPass.js';
 import { ClearMaskPass, MaskPass } from './MaskPass.js';
 
+/**
+ * Used to implement post-processing effects in three.js.
+ * The class manages a chain of post-processing passes to produce the final visual result.
+ * Post-processing passes are executed in order of their addition/insertion.
+ * The last pass is automatically rendered to screen.
+ *
+ * This module can only be used with {@link WebGLRenderer}.
+ *
+ * ```js
+ * const composer = new EffectComposer( renderer );
+ *
+ * // adding some passes
+ * const renderPass = new RenderPass( scene, camera );
+ * composer.addPass( renderPass );
+ *
+ * const glitchPass = new GlitchPass();
+ * composer.addPass( glitchPass );
+ *
+ * const outputPass = new OutputPass()
+ * composer.addPass( outputPass );
+ *
+ * function animate() {
+ *
+ * 	composer.render(); // instead of renderer.render()
+ *
+ * }
+ * ```
+ */
 class EffectComposer {
 
+	/**
+	 * Constructs a new effect composer.
+	 *
+	 * @param {WebGLRenderer} renderer - The renderer.
+	 * @param {WebGLRenderTarget} [renderTarget] - This render target and a clone will
+	 * be used as the internal read and write buffers. If not given, the composer creates
+	 * the buffers automatically.
+	 */
 	constructor( renderer, renderTarget ) {
 
+		/**
+		 * The renderer.
+		 *
+		 * @type {WebGLRenderer}
+		 */
 		this.renderer = renderer;
 
 		this._pixelRatio = renderer.getPixelRatio();
@@ -37,20 +78,59 @@ class EffectComposer {
 		this.renderTarget2 = renderTarget.clone();
 		this.renderTarget2.texture.name = 'EffectComposer.rt2';
 
+		/**
+		 * A reference to the internal write buffer. Passes usually write
+		 * their result into this buffer.
+		 *
+		 * @type {WebGLRenderTarget}
+		 */
 		this.writeBuffer = this.renderTarget1;
+
+		/**
+		 * A reference to the internal read buffer. Passes usually read
+		 * the previous render result from this buffer.
+		 *
+		 * @type {WebGLRenderTarget}
+		 */
 		this.readBuffer = this.renderTarget2;
 
+		/**
+		 * Whether the final pass is rendered to the screen (default framebuffer) or not.
+		 *
+		 * @type {boolean}
+		 * @default true
+		 */
 		this.renderToScreen = true;
 
+		/**
+		 * An array representing the (ordered) chain of post-processing passes.
+		 *
+		 * @type {Array<Pass>}
+		 */
 		this.passes = [];
 
+		/**
+		 * A copy pass used for internal swap operations.
+		 *
+		 * @private
+		 * @type {ShaderPass}
+		 */
 		this.copyPass = new ShaderPass( CopyShader );
 		this.copyPass.material.blending = NoBlending;
 
+		/**
+		 * The intenral clock for managing time data.
+		 *
+		 * @private
+		 * @type {Clock}
+		 */
 		this.clock = new Clock();
 
 	}
 
+	/**
+	 * Swaps the internal read/write buffers.
+	 */
 	swapBuffers() {
 
 		const tmp = this.readBuffer;
@@ -59,6 +139,11 @@ class EffectComposer {
 
 	}
 
+	/**
+	 * Adds the given pass to the pass chain.
+	 *
+	 * @param {Pass} pass - The pass to add.
+	 */
 	addPass( pass ) {
 
 		this.passes.push( pass );
@@ -66,6 +151,12 @@ class EffectComposer {
 
 	}
 
+	/**
+	 * Inserts the given pass at a given index.
+	 *
+	 * @param {Pass} pass - The pass to insert.
+	 * @param {number} index - The index into the pass chain.
+	 */
 	insertPass( pass, index ) {
 
 		this.passes.splice( index, 0, pass );
@@ -73,6 +164,11 @@ class EffectComposer {
 
 	}
 
+	/**
+	 * Removes the given pass from the pass chain.
+	 *
+	 * @param {Pass} pass - The pass to remove.
+	 */
 	removePass( pass ) {
 
 		const index = this.passes.indexOf( pass );
@@ -85,6 +181,12 @@ class EffectComposer {
 
 	}
 
+	/**
+	 * Returns `true` if the pass for the given index is the last enabled pass in the pass chain.
+	 *
+	 * @param {number} passIndex - The pass index.
+	 * @return {boolean} Whether the the pass for the given index is the last pass in the pass chain.
+	 */
 	isLastEnabledPass( passIndex ) {
 
 		for ( let i = passIndex + 1; i < this.passes.length; i ++ ) {
@@ -101,6 +203,12 @@ class EffectComposer {
 
 	}
 
+	/**
+	 * Executes all enabled post-processing passes in order to produce the final frame.
+	 *
+	 * @param {number} deltaTime - The delta time in seconds. If not given, the composer computes
+	 * its own time delta value.
+	 */
 	render( deltaTime ) {
 
 		// deltaTime value is in seconds
@@ -165,6 +273,12 @@ class EffectComposer {
 
 	}
 
+	/**
+	 * Resets the internal state of the EffectComposer.
+	 *
+	 * @param {WebGLRenderTarget} [renderTarget] - This render target has the same purpose like
+	 * the one from the constructor. If set, it is used to setup the read and write buffers.
+	 */
 	reset( renderTarget ) {
 
 		if ( renderTarget === undefined ) {
@@ -189,6 +303,13 @@ class EffectComposer {
 
 	}
 
+	/**
+	 * Resizes the internal read and write buffers as well as all passes. Similar to {@link WebGLRenderer#setSize},
+	 * this method honors the current pixel ration.
+	 *
+	 * @param {number} width - The width in logical pixels.
+	 * @param {number} height - The height in logical pixels.
+	 */
 	setSize( width, height ) {
 
 		this._width = width;
@@ -208,6 +329,12 @@ class EffectComposer {
 
 	}
 
+	/**
+	 * Sets device pixel ratio. This is usually used for HiDPI device to prevent blurring output.
+	 * Setting the pixel ratio will automatically resize the composer.
+	 *
+	 * @param {number} pixelRatio - The pixel ratio to set.
+	 */
 	setPixelRatio( pixelRatio ) {
 
 		this._pixelRatio = pixelRatio;
@@ -216,6 +343,10 @@ class EffectComposer {
 
 	}
 
+	/**
+	 * Frees the GPU-related resources allocated by this instance. Call this
+	 * method whenever the composer is no longer used in your app.
+	 */
 	dispose() {
 
 		this.renderTarget1.dispose();

package/examples/jsm/postprocessing/FilmPass.js

@@ -5,16 +5,47 @@ import {
 import { Pass, FullScreenQuad } from './Pass.js';
 import { FilmShader } from '../shaders/FilmShader.js';
 
+/**
+ * This pass can be used to create a film grain effect.
+ *
+ * ```js
+ * const filmPass = new FilmPass();
+ * composer.addPass( filmPass );
+ * ```
+ *
+ * @augments Pass
+ */
 class FilmPass extends Pass {
 
+	/**
+	 * Constructs a new film pass.
+	 *
+	 * @param {number} [intensity=0.5] - The grain intensity in the range `[0,1]` (0 = no effect, 1 = full effect).
+	 * @param {boolean} [grayscale=false] - Whether to apply a grayscale effect or not.
+	 */
 	constructor( intensity = 0.5, grayscale = false ) {
 
 		super();
 
 		const shader = FilmShader;
 
+		/**
+		 * The pass uniforms. Use this object if you want to update the
+		 * `intensity` or `grayscale` values at runtime.
+		 * ```js
+		 * pass.uniforms.intensity.value = 1;
+		 * pass.uniforms.grayscale.value = true;
+		 * ```
+		 *
+		 * @type {Object}
+		 */
 		this.uniforms = UniformsUtils.clone( shader.uniforms );
 
+		/**
+		 * The pass material.
+		 *
+		 * @type {ShaderMaterial}
+		 */
 		this.material = new ShaderMaterial( {
 
 			name: shader.name,
@@ -24,13 +55,26 @@ class FilmPass extends Pass {
 
 		} );
 
-		this.uniforms.intensity.value = intensity; // (0 = no effect, 1 = full effect)
+		this.uniforms.intensity.value = intensity;
 		this.uniforms.grayscale.value = grayscale;
 
-		this.fsQuad = new FullScreenQuad( this.material );
+		// internals
+
+		this._fsQuad = new FullScreenQuad( this.material );
 
 	}
 
+	/**
+	 * Performs the film pass.
+	 *
+	 * @param {WebGLRenderer} renderer - The renderer.
+	 * @param {WebGLRenderTarget} writeBuffer - The write buffer. This buffer is intended as the rendering
+	 * destination for the pass.
+	 * @param {WebGLRenderTarget} readBuffer - The read buffer. The pass can access the result from the
+	 * previous pass from this buffer.
+	 * @param {number} deltaTime - The delta time in seconds.
+	 * @param {boolean} maskActive - Whether masking is active or not.
+	 */
 	render( renderer, writeBuffer, readBuffer, deltaTime /*, maskActive */ ) {
 
 		this.uniforms[ 'tDiffuse' ].value = readBuffer.texture;
@@ -39,23 +83,27 @@ class FilmPass extends Pass {
 		if ( this.renderToScreen ) {
 
 			renderer.setRenderTarget( null );
-			this.fsQuad.render( renderer );
+			this._fsQuad.render( renderer );
 
 		} else {
 
 			renderer.setRenderTarget( writeBuffer );
 			if ( this.clear ) renderer.clear();
-			this.fsQuad.render( renderer );
+			this._fsQuad.render( renderer );
 
 		}
 
 	}
 
+	/**
+	 * Frees the GPU-related resources allocated by this instance. Call this
+	 * method whenever the pass is no longer used in your app.
+	 */
 	dispose() {
 
 		this.material.dispose();
 
-		this.fsQuad.dispose();
+		this._fsQuad.dispose();
 
 	}