@plastic-software/three 0.174.0 → 0.175.0

package/examples/jsm/postprocessing/AfterimagePass.js

@@ -10,67 +10,109 @@ import { Pass, FullScreenQuad } from './Pass.js';
 import { CopyShader } from '../shaders/CopyShader.js';
 import { AfterimageShader } from '../shaders/AfterimageShader.js';
 
+/**
+ * Pass for a basic after image effect.
+ *
+ * ```js
+ * const afterimagePass = new AfterimagePass( 0.9 );
+ * composer.addPass( afterimagePass );
+ * ```
+ *
+ * @augments Pass
+ */
 class AfterimagePass extends Pass {
 
+	/**
+	 * Constructs a new after image pass.
+	 *
+	 * @param {number} [damp=0.96] - The damping intensity. A higher value means a stronger after image effect.
+	 */
 	constructor( damp = 0.96 ) {
 
 		super();
 
-		this.shader = AfterimageShader;
-
-		this.uniforms = UniformsUtils.clone( this.shader.uniforms );
+		/**
+		 * The pass uniforms. Use this object if you want to update the
+		 * `damp` value at runtime.
+		 * ```js
+		 * pass.uniforms.damp.value = 0.9;
+		 * ```
+		 *
+		 * @type {Object}
+		 */
+		this.uniforms = UniformsUtils.clone( AfterimageShader.uniforms );
 
 		this.uniforms[ 'damp' ].value = damp;
 
-		this.textureComp = new WebGLRenderTarget( window.innerWidth, window.innerHeight, {
-			magFilter: NearestFilter,
-			type: HalfFloatType
-		} );
-
-		this.textureOld = new WebGLRenderTarget( window.innerWidth, window.innerHeight, {
-			magFilter: NearestFilter,
-			type: HalfFloatType
-		} );
-
+		/**
+		 * The composition material.
+		 *
+		 * @type {ShaderMaterial}
+		 */
 		this.compFsMaterial = new ShaderMaterial( {
 
 			uniforms: this.uniforms,
-			vertexShader: this.shader.vertexShader,
-			fragmentShader: this.shader.fragmentShader
+			vertexShader: AfterimageShader.vertexShader,
+			fragmentShader: AfterimageShader.fragmentShader
 
 		} );
 
-		this.compFsQuad = new FullScreenQuad( this.compFsMaterial );
-
-		const copyShader = CopyShader;
-
+		/**
+		 * The copy material.
+		 *
+		 * @type {ShaderMaterial}
+		 */
 		this.copyFsMaterial = new ShaderMaterial( {
-			uniforms: UniformsUtils.clone( copyShader.uniforms ),
-			vertexShader: copyShader.vertexShader,
-			fragmentShader: copyShader.fragmentShader,
+			uniforms: UniformsUtils.clone( CopyShader.uniforms ),
+			vertexShader: CopyShader.vertexShader,
+			fragmentShader: CopyShader.fragmentShader,
 			blending: NoBlending,
 			depthTest: false,
 			depthWrite: false
 		} );
 
-		this.copyFsQuad = new FullScreenQuad( this.copyFsMaterial );
+		// internals
+
+		this._textureComp = new WebGLRenderTarget( window.innerWidth, window.innerHeight, {
+			magFilter: NearestFilter,
+			type: HalfFloatType
+		} );
+
+		this._textureOld = new WebGLRenderTarget( window.innerWidth, window.innerHeight, {
+			magFilter: NearestFilter,
+			type: HalfFloatType
+		} );
+
+		this._compFsQuad = new FullScreenQuad( this.compFsMaterial );
+		this._copyFsQuad = new FullScreenQuad( this.copyFsMaterial );
 
 	}
 
+	/**
+	 * Performs the after image 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[ 'tOld' ].value = this.textureOld.texture;
+		this.uniforms[ 'tOld' ].value = this._textureOld.texture;
 		this.uniforms[ 'tNew' ].value = readBuffer.texture;
 
-		renderer.setRenderTarget( this.textureComp );
-		this.compFsQuad.render( renderer );
+		renderer.setRenderTarget( this._textureComp );
+		this._compFsQuad.render( renderer );
 
-		this.copyFsQuad.material.uniforms.tDiffuse.value = this.textureComp.texture;
+		this._copyFsQuad.material.uniforms.tDiffuse.value = this._textureComp.texture;
 
 		if ( this.renderToScreen ) {
 
 			renderer.setRenderTarget( null );
-			this.copyFsQuad.render( renderer );
+			this._copyFsQuad.render( renderer );
 
 		} else {
 
@@ -78,35 +120,45 @@ class AfterimagePass extends Pass {
 
 			if ( this.clear ) renderer.clear();
 
-			this.copyFsQuad.render( renderer );
+			this._copyFsQuad.render( renderer );
 
 		}
 
 		// Swap buffers.
-		const temp = this.textureOld;
-		this.textureOld = this.textureComp;
-		this.textureComp = temp;
+		const temp = this._textureOld;
+		this._textureOld = this._textureComp;
+		this._textureComp = temp;
 		// Now textureOld contains the latest image, ready for the next frame.
 
 	}
 
+	/**
+	 * Sets the size of the pass.
+	 *
+	 * @param {number} width - The width to set.
+	 * @param {number} height - The width to set.
+	 */
 	setSize( width, height ) {
 
-		this.textureComp.setSize( width, height );
-		this.textureOld.setSize( width, height );
+		this._textureComp.setSize( width, height );
+		this._textureOld.setSize( width, height );
 
 	}
 
+	/**
+	 * Frees the GPU-related resources allocated by this instance. Call this
+	 * method whenever the pass is no longer used in your app.
+	 */
 	dispose() {
 
-		this.textureComp.dispose();
-		this.textureOld.dispose();
+		this._textureComp.dispose();
+		this._textureOld.dispose();
 
 		this.compFsMaterial.dispose();
 		this.copyFsMaterial.dispose();
 
-		this.compFsQuad.dispose();
-		this.copyFsQuad.dispose();
+		this._compFsQuad.dispose();
+		this._copyFsQuad.dispose();
 
 	}
 

package/examples/jsm/postprocessing/BloomPass.js

@@ -9,25 +9,47 @@ import {
 import { Pass, FullScreenQuad } from './Pass.js';
 import { ConvolutionShader } from '../shaders/ConvolutionShader.js';
 
+/**
+ * A pass for a basic Bloom effect.
+ *
+ * {@link UnrealBloomPass} produces a more advanced Bloom but is also
+ * more expensive.
+ *
+ * ```js
+ * const effectBloom = new BloomPass( 0.75 );
+ * composer.addPass( effectBloom );
+ * ```
+ *
+ * @augments Pass
+ */
 class BloomPass extends Pass {
 
+	/**
+	 * Constructs a new Bloom pass.
+	 *
+	 * @param {number} [strength=1] - The Bloom strength.
+	 * @param {number} [kernelSize=25] - The kernel size.
+	 * @param {number} [sigma=4] - The sigma.
+	 */
 	constructor( strength = 1, kernelSize = 25, sigma = 4 ) {
 
 		super();
 
-		// render targets
-
-		this.renderTargetX = new WebGLRenderTarget( 1, 1, { type: HalfFloatType } ); // will be resized later
-		this.renderTargetX.texture.name = 'BloomPass.x';
-		this.renderTargetY = new WebGLRenderTarget( 1, 1, { type: HalfFloatType } ); // will be resized later
-		this.renderTargetY.texture.name = 'BloomPass.y';
-
 		// combine material
 
+		/**
+		 * The combine pass uniforms.
+		 *
+		 * @type {Object}
+		 */
 		this.combineUniforms = UniformsUtils.clone( CombineShader.uniforms );
-
 		this.combineUniforms[ 'strength' ].value = strength;
 
+		/**
+		 * The combine pass material.
+		 *
+		 * @type {ShaderMaterial}
+		 */
 		this.materialCombine = new ShaderMaterial( {
 
 			name: CombineShader.name,
@@ -43,11 +65,21 @@ class BloomPass extends Pass {
 
 		const convolutionShader = ConvolutionShader;
 
+		/**
+		 * The convolution pass uniforms.
+		 *
+		 * @type {Object}
+		 */
 		this.convolutionUniforms = UniformsUtils.clone( convolutionShader.uniforms );
 
 		this.convolutionUniforms[ 'uImageIncrement' ].value = BloomPass.blurX;
-		this.convolutionUniforms[ 'cKernel' ].value = ConvolutionShader.buildKernel( sigma );
+		this.convolutionUniforms[ 'cKernel' ].value = buildKernel( sigma );
 
+		/**
+		 * The convolution pass material.
+		 *
+		 * @type {ShaderMaterial}
+		 */
 		this.materialConvolution = new ShaderMaterial( {
 
 			name: convolutionShader.name,
@@ -61,67 +93,101 @@ class BloomPass extends Pass {
 
 		} );
 
+		/**
+		 * Overwritten to disable the swap.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.needsSwap = false;
 
-		this.fsQuad = new FullScreenQuad( null );
+		// internals
+
+		this._renderTargetX = new WebGLRenderTarget( 1, 1, { type: HalfFloatType } ); // will be resized later
+		this._renderTargetX.texture.name = 'BloomPass.x';
+		this._renderTargetY = new WebGLRenderTarget( 1, 1, { type: HalfFloatType } ); // will be resized later
+		this._renderTargetY.texture.name = 'BloomPass.y';
+
+		this._fsQuad = new FullScreenQuad( null );
 
 	}
 
+	/**
+	 * Performs the Bloom 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 ) {
 
 		if ( maskActive ) renderer.state.buffers.stencil.setTest( false );
 
 		// Render quad with blurred scene into texture (convolution pass 1)
 
-		this.fsQuad.material = this.materialConvolution;
+		this._fsQuad.material = this.materialConvolution;
 
 		this.convolutionUniforms[ 'tDiffuse' ].value = readBuffer.texture;
 		this.convolutionUniforms[ 'uImageIncrement' ].value = BloomPass.blurX;
 
-		renderer.setRenderTarget( this.renderTargetX );
+		renderer.setRenderTarget( this._renderTargetX );
 		renderer.clear();
-		this.fsQuad.render( renderer );
+		this._fsQuad.render( renderer );
 
 
 		// Render quad with blurred scene into texture (convolution pass 2)
 
-		this.convolutionUniforms[ 'tDiffuse' ].value = this.renderTargetX.texture;
+		this.convolutionUniforms[ 'tDiffuse' ].value = this._renderTargetX.texture;
 		this.convolutionUniforms[ 'uImageIncrement' ].value = BloomPass.blurY;
 
-		renderer.setRenderTarget( this.renderTargetY );
+		renderer.setRenderTarget( this._renderTargetY );
 		renderer.clear();
-		this.fsQuad.render( renderer );
+		this._fsQuad.render( renderer );
 
 		// Render original scene with superimposed blur to texture
 
-		this.fsQuad.material = this.materialCombine;
+		this._fsQuad.material = this.materialCombine;
 
-		this.combineUniforms[ 'tDiffuse' ].value = this.renderTargetY.texture;
+		this.combineUniforms[ 'tDiffuse' ].value = this._renderTargetY.texture;
 
 		if ( maskActive ) renderer.state.buffers.stencil.setTest( true );
 
 		renderer.setRenderTarget( readBuffer );
 		if ( this.clear ) renderer.clear();
-		this.fsQuad.render( renderer );
+		this._fsQuad.render( renderer );
 
 	}
 
+	/**
+	 * Sets the size of the pass.
+	 *
+	 * @param {number} width - The width to set.
+	 * @param {number} height - The width to set.
+	 */
 	setSize( width, height ) {
 
-		this.renderTargetX.setSize( width, height );
-		this.renderTargetY.setSize( width, height );
+		this._renderTargetX.setSize( width, height );
+		this._renderTargetY.setSize( width, height );
 
 	}
 
+	/**
+	 * Frees the GPU-related resources allocated by this instance. Call this
+	 * method whenever the pass is no longer used in your app.
+	 */
 	dispose() {
 
-		this.renderTargetX.dispose();
-		this.renderTargetY.dispose();
+		this._renderTargetX.dispose();
+		this._renderTargetY.dispose();
 
 		this.materialCombine.dispose();
 		this.materialConvolution.dispose();
 
-		this.fsQuad.dispose();
+		this._fsQuad.dispose();
 
 	}
 
@@ -169,4 +235,39 @@ const CombineShader = {
 BloomPass.blurX = new Vector2( 0.001953125, 0.0 );
 BloomPass.blurY = new Vector2( 0.0, 0.001953125 );
 
+
+function gauss( x, sigma ) {
+
+	return Math.exp( - ( x * x ) / ( 2.0 * sigma * sigma ) );
+
+}
+
+function buildKernel( sigma ) {
+
+	// We loop off the sqrt(2 * pi) * sigma term, since we're going to normalize anyway.
+
+	const kMaxKernelSize = 25;
+	let kernelSize = 2 * Math.ceil( sigma * 3.0 ) + 1;
+
+	if ( kernelSize > kMaxKernelSize ) kernelSize = kMaxKernelSize;
+
+	const halfWidth = ( kernelSize - 1 ) * 0.5;
+
+	const values = new Array( kernelSize );
+	let sum = 0.0;
+	for ( let i = 0; i < kernelSize; ++ i ) {
+
+		values[ i ] = gauss( i - halfWidth, sigma );
+		sum += values[ i ];
+
+	}
+
+	// normalize the kernel
+
+	for ( let i = 0; i < kernelSize; ++ i ) values[ i ] /= sum;
+
+	return values;
+
+}
+
 export { BloomPass };

package/examples/jsm/postprocessing/BokehPass.js

@@ -13,16 +13,44 @@ import { Pass, FullScreenQuad } from './Pass.js';
 import { BokehShader } from '../shaders/BokehShader.js';
 
 /**
- * Depth-of-field post-process with bokeh shader
+ * Pass for creating depth of field (DOF) effect.
+ *
+ * ```js
+ * const bokehPass = new BokehPass( scene, camera, {
+ * 	focus: 500
+ * 	aperture: 5,
+ * 	maxblur: 0.01
+ * } );
+ * composer.addPass( bokehPass );
+ * ```
+ *
+ * @augments Pass
  */
-
 class BokehPass extends Pass {
 
+	/**
+	 * Constructs a new Bokeh pass.
+	 *
+	 * @param {Scene} scene - The scene to render the DOF for.
+	 * @param {Camera} camera - The camera.
+	 * @param {BokehPass~Options} params - The pass options.
+	 */
 	constructor( scene, camera, params ) {
 
 		super();
 
+		/**
+		 * The scene to render the DOF for.
+		 *
+		 * @type {Scene}
+		 */
 		this.scene = scene;
+
+		/**
+		 * The camera.
+		 *
+		 * @type {Camera}
+		 */
 		this.camera = camera;
 
 		const focus = ( params.focus !== undefined ) ? params.focus : 1.0;
@@ -31,26 +59,25 @@ class BokehPass extends Pass {
 
 		// render targets
 
-		this.renderTargetDepth = new WebGLRenderTarget( 1, 1, { // will be resized later
+		this._renderTargetDepth = new WebGLRenderTarget( 1, 1, { // will be resized later
 			minFilter: NearestFilter,
 			magFilter: NearestFilter,
 			type: HalfFloatType
 		} );
 
-		this.renderTargetDepth.texture.name = 'BokehPass.depth';
+		this._renderTargetDepth.texture.name = 'BokehPass.depth';
 
 		// depth material
 
-		this.materialDepth = new MeshDepthMaterial();
-		this.materialDepth.depthPacking = RGBADepthPacking;
-		this.materialDepth.blending = NoBlending;
+		this._materialDepth = new MeshDepthMaterial();
+		this._materialDepth.depthPacking = RGBADepthPacking;
+		this._materialDepth.blending = NoBlending;
 
 		// bokeh material
 
-		const bokehShader = BokehShader;
-		const bokehUniforms = UniformsUtils.clone( bokehShader.uniforms );
+		const bokehUniforms = UniformsUtils.clone( BokehShader.uniforms );
 
-		bokehUniforms[ 'tDepth' ].value = this.renderTargetDepth.texture;
+		bokehUniforms[ 'tDepth' ].value = this._renderTargetDepth.texture;
 
 		bokehUniforms[ 'focus' ].value = focus;
 		bokehUniforms[ 'aspect' ].value = camera.aspect;
@@ -59,26 +86,56 @@ class BokehPass extends Pass {
 		bokehUniforms[ 'nearClip' ].value = camera.near;
 		bokehUniforms[ 'farClip' ].value = camera.far;
 
+		/**
+		 * The pass bokeh material.
+		 *
+		 * @type {ShaderMaterial}
+		 */
 		this.materialBokeh = new ShaderMaterial( {
-			defines: Object.assign( {}, bokehShader.defines ),
+			defines: Object.assign( {}, BokehShader.defines ),
 			uniforms: bokehUniforms,
-			vertexShader: bokehShader.vertexShader,
-			fragmentShader: bokehShader.fragmentShader
+			vertexShader: BokehShader.vertexShader,
+			fragmentShader: BokehShader.fragmentShader
 		} );
 
+		/**
+		 * The pass uniforms.  Use this object if you want to update the
+		 * `focus`, `aperture` or `maxblur` values at runtime.
+		 *
+		 * ```js
+		 * pass.uniforms.focus.value = focus;
+		 * pass.uniforms.aperture.value = aperture;
+		 * pass.uniforms.maxblur.value = maxblur;
+		 * ```
+		 *
+		 * @type {Object}
+		 */
 		this.uniforms = bokehUniforms;
 
-		this.fsQuad = new FullScreenQuad( this.materialBokeh );
+		// internals
+
+		this._fsQuad = new FullScreenQuad( this.materialBokeh );
 
 		this._oldClearColor = new Color();
 
 	}
 
+	/**
+	 * Performs the Bokeh 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*/ ) {
 
 		// Render depth into texture
 
-		this.scene.overrideMaterial = this.materialDepth;
+		this.scene.overrideMaterial = this._materialDepth;
 
 		renderer.getClearColor( this._oldClearColor );
 		const oldClearAlpha = renderer.getClearAlpha();
@@ -87,7 +144,7 @@ class BokehPass extends Pass {
 
 		renderer.setClearColor( 0xffffff );
 		renderer.setClearAlpha( 1.0 );
-		renderer.setRenderTarget( this.renderTargetDepth );
+		renderer.setRenderTarget( this._renderTargetDepth );
 		renderer.clear();
 		renderer.render( this.scene, this.camera );
 
@@ -100,13 +157,13 @@ class BokehPass extends Pass {
 		if ( this.renderToScreen ) {
 
 			renderer.setRenderTarget( null );
-			this.fsQuad.render( renderer );
+			this._fsQuad.render( renderer );
 
 		} else {
 
 			renderer.setRenderTarget( writeBuffer );
 			renderer.clear();
-			this.fsQuad.render( renderer );
+			this._fsQuad.render( renderer );
 
 		}
 
@@ -117,25 +174,44 @@ class BokehPass extends Pass {
 
 	}
 
+	/**
+	 * Sets the size of the pass.
+	 *
+	 * @param {number} width - The width to set.
+	 * @param {number} height - The width to set.
+	 */
 	setSize( width, height ) {
 
 		this.materialBokeh.uniforms[ 'aspect' ].value = width / height;
 
-		this.renderTargetDepth.setSize( width, height );
+		this._renderTargetDepth.setSize( width, height );
 
 	}
 
+	/**
+	 * Frees the GPU-related resources allocated by this instance. Call this
+	 * method whenever the pass is no longer used in your app.
+	 */
 	dispose() {
 
-		this.renderTargetDepth.dispose();
+		this._renderTargetDepth.dispose();
 
-		this.materialDepth.dispose();
+		this._materialDepth.dispose();
 		this.materialBokeh.dispose();
 
-		this.fsQuad.dispose();
+		this._fsQuad.dispose();
 
 	}
 
 }
 
+/**
+ * Constructor options of `BokehPass`.
+ *
+ * @typedef {Object} BokehPass~Options
+ * @property {number} [focus=1] - Defines the effect's focus which is the distance along the camera's look direction in world units.
+ * @property {number} [aperture=0.025] - Defines the effect's aperture.
+ * @property {number} [maxblur=1] - Defines the effect's maximum blur.
+ **/
+
 export { BokehPass };