@plastic-software/three 0.174.0 → 0.175.0

package/examples/jsm/postprocessing/ShaderPass.js

@@ -4,13 +4,53 @@ import {
 } from 'three';
 import { Pass, FullScreenQuad } from './Pass.js';
 
+/**
+ * This pass can be used to create a post processing effect
+ * with a raw GLSL shader object. Useful for implementing custom
+ * effects.
+ *
+ * ```js
+ * const fxaaPass = new ShaderPass( FXAAShader );
+ * composer.addPass( fxaaPass );
+ * ```
+ *
+ * @augments Pass
+ */
 class ShaderPass extends Pass {
 
-	constructor( shader, textureID ) {
+	/**
+	 * Constructs a new shader pass.
+	 *
+	 * @param {Object|ShaderMaterial} [shader] - A shader object holding vertex and fragment shader as well as
+	 * defines and uniforms. It's also valid to pass a custom shader material.
+	 * @param {string} [textureID='tDiffuse'] - The name of the texture uniform that should sample
+	 * the read buffer.
+	 */
+	constructor( shader, textureID = 'tDiffuse' ) {
 
 		super();
 
-		this.textureID = ( textureID !== undefined ) ? textureID : 'tDiffuse';
+		/**
+		 * The name of the texture uniform that should sample the read buffer.
+		 *
+		 * @type {string}
+		 * @default 'tDiffuse'
+		 */
+		this.textureID = textureID;
+
+		/**
+		 * The pass uniforms.
+		 *
+		 * @type {?Object}
+		 */
+		this.uniforms = null;
+
+		/**
+		 * The pass material.
+		 *
+		 * @type {?ShaderMaterial}
+		 */
+		this.material = null;
 
 		if ( shader instanceof ShaderMaterial ) {
 
@@ -34,10 +74,23 @@ class ShaderPass extends Pass {
 
 		}
 
-		this.fsQuad = new FullScreenQuad( this.material );
+		// internals
+
+		this._fsQuad = new FullScreenQuad( this.material );
 
 	}
 
+	/**
+	 * Performs the shader 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 ( this.uniforms[ this.textureID ] ) {
@@ -46,29 +99,33 @@ class ShaderPass extends Pass {
 
 		}
 
-		this.fsQuad.material = this.material;
+		this._fsQuad.material = this.material;
 
 		if ( this.renderToScreen ) {
 
 			renderer.setRenderTarget( null );
-			this.fsQuad.render( renderer );
+			this._fsQuad.render( renderer );
 
 		} else {
 
 			renderer.setRenderTarget( writeBuffer );
 			// TODO: Avoid using autoClear properties, see https://github.com/mrdoob/three.js/pull/15571#issuecomment-465669600
 			if ( this.clear ) renderer.clear( renderer.autoClearColor, renderer.autoClearDepth, renderer.autoClearStencil );
-			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/TAARenderPass.js

@@ -6,29 +6,79 @@ import { SSAARenderPass } from './SSAARenderPass.js';
 
 /**
  *
- * Temporal Anti-Aliasing Render Pass
+ * Temporal Anti-Aliasing Render Pass.
  *
- * When there is no motion in the scene, the TAA render pass accumulates jittered camera samples across frames to create a high quality anti-aliased result.
+ * When there is no motion in the scene, the TAA render pass accumulates jittered camera
+ * samples across frames to create a high quality anti-aliased result.
  *
- * References:
+ * Note: This effect uses no reprojection so it is no TRAA implementation.
  *
- * TODO: Add support for motion vector pas so that accumulation of samples across frames can occur on dynamics scenes.
+ * ```js
+ * const taaRenderPass = new TAARenderPass( scene, camera );
+ * taaRenderPass.unbiased = false;
+ * composer.addPass( taaRenderPass );
+ * ```
  *
+ * @augments SSAARenderPass
  */
-
 class TAARenderPass extends SSAARenderPass {
 
+	/**
+	 * Constructs a new TAA render pass.
+	 *
+	 * @param {Scene} scene - The scene to render.
+	 * @param {Camera} camera - The camera.
+	 * @param {?(number|Color|string)} [clearColor=0x000000] - The clear color of the render pass.
+	 * @param {?number} [clearAlpha=0] - The clear alpha of the render pass.
+	 */
 	constructor( scene, camera, clearColor, clearAlpha ) {
 
 		super( scene, camera, clearColor, clearAlpha );
 
+		/**
+		 * Overwritten and set to 0 by default.
+		 *
+		 * @type {number}
+		 * @default 0
+		 */
 		this.sampleLevel = 0;
+
+		/**
+		 * Whether to accumulate frames or not. This enables
+		 * the TAA.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.accumulate = false;
+
+		/**
+		 * The accumulation index.
+		 *
+		 * @type {number}
+		 * @default -1
+		 */
 		this.accumulateIndex = - 1;
 
+		// internals
+
+		this._sampleRenderTarget = null;
+		this._holdRenderTarget = null;
+
 	}
 
-	render( renderer, writeBuffer, readBuffer, deltaTime ) {
+	/**
+	 * Performs the TAA render 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 ( this.accumulate === false ) {
 
@@ -41,23 +91,23 @@ class TAARenderPass extends SSAARenderPass {
 
 		const jitterOffsets = _JitterVectors[ 5 ];
 
-		if ( this.sampleRenderTarget === undefined ) {
+		if ( this._sampleRenderTarget === null ) {
 
-			this.sampleRenderTarget = new WebGLRenderTarget( readBuffer.width, readBuffer.height, { type: HalfFloatType } );
-			this.sampleRenderTarget.texture.name = 'TAARenderPass.sample';
+			this._sampleRenderTarget = new WebGLRenderTarget( readBuffer.width, readBuffer.height, { type: HalfFloatType } );
+			this._sampleRenderTarget.texture.name = 'TAARenderPass.sample';
 
 		}
 
-		if ( this.holdRenderTarget === undefined ) {
+		if ( this._holdRenderTarget === null ) {
 
-			this.holdRenderTarget = new WebGLRenderTarget( readBuffer.width, readBuffer.height, { type: HalfFloatType } );
-			this.holdRenderTarget.texture.name = 'TAARenderPass.hold';
+			this._holdRenderTarget = new WebGLRenderTarget( readBuffer.width, readBuffer.height, { type: HalfFloatType } );
+			this._holdRenderTarget.texture.name = 'TAARenderPass.hold';
 
 		}
 
 		if ( this.accumulateIndex === - 1 ) {
 
-			super.render( renderer, this.holdRenderTarget, readBuffer, deltaTime );
+			super.render( renderer, this._holdRenderTarget, readBuffer, deltaTime );
 
 			this.accumulateIndex = 0;
 
@@ -73,8 +123,8 @@ class TAARenderPass extends SSAARenderPass {
 
 		if ( this.accumulateIndex >= 0 && this.accumulateIndex < jitterOffsets.length ) {
 
-			this.copyUniforms[ 'opacity' ].value = sampleWeight;
-			this.copyUniforms[ 'tDiffuse' ].value = writeBuffer.texture;
+			this._copyUniforms[ 'opacity' ].value = sampleWeight;
+			this._copyUniforms[ 'tDiffuse' ].value = writeBuffer.texture;
 
 			// render the scene multiple times, each slightly jitter offset from the last and accumulate the results.
 			const numSamplesPerFrame = Math.pow( 2, this.sampleLevel );
@@ -96,7 +146,7 @@ class TAARenderPass extends SSAARenderPass {
 				renderer.clear();
 				renderer.render( this.scene, this.camera );
 
-				renderer.setRenderTarget( this.sampleRenderTarget );
+				renderer.setRenderTarget( this._sampleRenderTarget );
 				if ( this.accumulateIndex === 0 ) {
 
 					renderer.setClearColor( 0x000000, 0.0 );
@@ -104,7 +154,7 @@ class TAARenderPass extends SSAARenderPass {
 
 				}
 
-				this.fsQuad.render( renderer );
+				this._fsQuad.render( renderer );
 
 				this.accumulateIndex ++;
 
@@ -121,20 +171,20 @@ class TAARenderPass extends SSAARenderPass {
 
 		if ( accumulationWeight > 0 ) {
 
-			this.copyUniforms[ 'opacity' ].value = 1.0;
-			this.copyUniforms[ 'tDiffuse' ].value = this.sampleRenderTarget.texture;
+			this._copyUniforms[ 'opacity' ].value = 1.0;
+			this._copyUniforms[ 'tDiffuse' ].value = this._sampleRenderTarget.texture;
 			renderer.setRenderTarget( writeBuffer );
 			renderer.clear();
-			this.fsQuad.render( renderer );
+			this._fsQuad.render( renderer );
 
 		}
 
 		if ( accumulationWeight < 1.0 ) {
 
-			this.copyUniforms[ 'opacity' ].value = 1.0 - accumulationWeight;
-			this.copyUniforms[ 'tDiffuse' ].value = this.holdRenderTarget.texture;
+			this._copyUniforms[ 'opacity' ].value = 1.0 - accumulationWeight;
+			this._copyUniforms[ 'tDiffuse' ].value = this._holdRenderTarget.texture;
 			renderer.setRenderTarget( writeBuffer );
-			this.fsQuad.render( renderer );
+			this._fsQuad.render( renderer );
 
 		}
 
@@ -143,11 +193,15 @@ class TAARenderPass extends SSAARenderPass {
 
 	}
 
+	/**
+	 * Frees the GPU-related resources allocated by this instance. Call this
+	 * method whenever the pass is no longer used in your app.
+	 */
 	dispose() {
 
 		super.dispose();
 
-		if ( this.holdRenderTarget ) this.holdRenderTarget.dispose();
+		if ( this._holdRenderTarget ) this._holdRenderTarget.dispose();
 
 	}
 

package/examples/jsm/postprocessing/TexturePass.js

@@ -5,19 +5,68 @@ import {
 import { Pass, FullScreenQuad } from './Pass.js';
 import { CopyShader } from '../shaders/CopyShader.js';
 
+/**
+ * This pass can be used to render a texture over the entire screen.
+ *
+ * ```js
+ * const texture = new THREE.TextureLoader().load( 'textures/2294472375_24a3b8ef46_o.jpg' );
+ * texture.colorSpace = THREE.SRGBColorSpace;
+ *
+ * const texturePass = new TexturePass( texture );
+ * composer.addPass( texturePass );
+ * ```
+ *
+ * @augments Pass
+ */
 class TexturePass extends Pass {
 
-	constructor( map, opacity ) {
+	/**
+	 * Constructs a new texture pass.
+	 *
+	 * @param {Texture} map - The texture to render.
+	 * @param {number} [opacity=1] - The opacity.
+	 */
+	constructor( map, opacity = 1 ) {
 
 		super();
 
 		const shader = CopyShader;
 
+		/**
+		 * The texture to render.
+		 *
+		 * @type {Texture}
+		 */
 		this.map = map;
-		this.opacity = ( opacity !== undefined ) ? opacity : 1.0;
 
+		/**
+		 * The opacity.
+		 *
+		 * @type {number}
+		 * @default 1
+		 */
+		this.opacity = opacity;
+
+		/**
+		 * Overwritten to disable the swap.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
+		this.needsSwap = false;
+
+		/**
+		 * The pass uniforms.
+		 *
+		 * @type {Object}
+		 */
 		this.uniforms = UniformsUtils.clone( shader.uniforms );
 
+		/**
+		 * The pass material.
+		 *
+		 * @type {ShaderMaterial}
+		 */
 		this.material = new ShaderMaterial( {
 
 			uniforms: this.uniforms,
@@ -29,18 +78,29 @@ class TexturePass extends Pass {
 
 		} );
 
-		this.needsSwap = false;
+		// internals
 
-		this.fsQuad = new FullScreenQuad( null );
+		this._fsQuad = new FullScreenQuad( null );
 
 	}
 
+	/**
+	 * Performs the 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.fsQuad.material = this.material;
+		this._fsQuad.material = this.material;
 
 		this.uniforms[ 'opacity' ].value = this.opacity;
 		this.uniforms[ 'tDiffuse' ].value = this.map;
@@ -48,17 +108,20 @@ class TexturePass extends Pass {
 
 		renderer.setRenderTarget( this.renderToScreen ? null : readBuffer );
 		if ( this.clear ) renderer.clear();
-		this.fsQuad.render( renderer );
+		this._fsQuad.render( renderer );
 
 		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.material.dispose();
-
-		this.fsQuad.dispose();
+		this._fsQuad.dispose();
 
 	}