@plastic-software/three 0.174.0 → 0.175.0

package/examples/jsm/postprocessing/RenderTransitionPass.js

@@ -5,68 +5,159 @@ import {
 } from 'three';
 import { FullScreenQuad, Pass } from './Pass.js';
 
+/**
+ * A special type of render pass for implementing transition effects.
+ * When active, the pass will transition from scene A to scene B.
+ *
+ * ```js
+ * const renderTransitionPass = new RenderTransitionPass( fxSceneA.scene, fxSceneA.camera, fxSceneB.scene, fxSceneB.camera );
+ * renderTransitionPass.setTexture( textures[ 0 ] );
+ * composer.addPass( renderTransitionPass );
+ * ```
+ *
+ * @augments Pass
+ */
 class RenderTransitionPass extends Pass {
 
+	/**
+	 * Constructs a render transition pass.
+	 *
+	 * @param {Scene} sceneA - The first scene.
+	 * @param {Camera} cameraA - The camera of the first scene.
+	 * @param {Scene} sceneB - The second scene.
+	 * @param {Camera} cameraB - The camera of the second scene.
+	 */
 	constructor( sceneA, cameraA, sceneB, cameraB ) {
 
 		super();
 
-		this.material = this.createMaterial();
-		this.fsQuad = new FullScreenQuad( this.material );
-
+		/**
+		 * The first scene.
+		 *
+		 * @type {Scene}
+		 */
 		this.sceneA = sceneA;
+
+
+		/**
+		 * The camera of the first scene.
+		 *
+		 * @type {Camera}
+		 */
 		this.cameraA = cameraA;
+
+		/**
+		 * The second scene.
+		 *
+		 * @type {Scene}
+		 */
 		this.sceneB = sceneB;
+
+		/**
+		 * The camera of the second scene.
+		 *
+		 * @type {Camera}
+		 */
 		this.cameraB = cameraB;
 
-		this.renderTargetA = new WebGLRenderTarget();
-		this.renderTargetA.texture.type = HalfFloatType;
-		this.renderTargetB = new WebGLRenderTarget();
-		this.renderTargetB.texture.type = HalfFloatType;
+		/**
+		 * The pass material.
+		 *
+		 * @type {ShaderMaterial}
+		 */
+		this.material = this._createMaterial();
+
+		// internals
+
+		this._renderTargetA = new WebGLRenderTarget();
+		this._renderTargetA.texture.type = HalfFloatType;
+		this._renderTargetB = new WebGLRenderTarget();
+		this._renderTargetB.texture.type = HalfFloatType;
+
+		this._fsQuad = new FullScreenQuad( this.material );
 
 	}
 
+	/**
+	 * Sets the transition factor. Must be in the range `[0,1]`.
+	 * This value determines to what degree both scenes are mixed.
+	 *
+	 * @param {boolenumberan} value - The transition factor.
+	 */
 	setTransition( value ) {
 
 		this.material.uniforms.mixRatio.value = value;
 
 	}
 
+	/**
+	 * Toggles the usage of a texture for the effect.
+	 *
+	 * @param {boolean} value - Whether to use a texture for the transition effect or not.
+	 */
 	useTexture( value ) {
 
 		this.material.uniforms.useTexture.value = value ? 1 : 0;
 
 	}
 
+	/**
+	 * Sets the effect texture.
+	 *
+	 * @param {Texture} value - The effect texture.
+	 */
 	setTexture( value ) {
 
 		this.material.uniforms.tMixTexture.value = value;
 
 	}
 
+	/**
+	 * Sets the texture threshold. This value defined how strong the texture effects
+	 * the transition. Must be in the range `[0,1]` (0 means full effect, 1 means no effect).
+	 *
+	 * @param {boolenumberan} value - The threshold value.
+	 */
 	setTextureThreshold( value ) {
 
 		this.material.uniforms.threshold.value = value;
 
 	}
 
+	/**
+	 * Sets the size of the pass.
+	 *
+	 * @param {number} width - The width to set.
+	 * @param {number} height - The width to set.
+	 */
 	setSize( width, height ) {
 
-		this.renderTargetA.setSize( width, height );
-		this.renderTargetB.setSize( width, height );
+		this._renderTargetA.setSize( width, height );
+		this._renderTargetB.setSize( width, height );
 
 	}
 
-	render( renderer, writeBuffer ) {
-
-		renderer.setRenderTarget( this.renderTargetA );
+	/**
+	 * Performs the transition 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 */ ) {
+
+		renderer.setRenderTarget( this._renderTargetA );
 		renderer.render( this.sceneA, this.cameraA );
-		renderer.setRenderTarget( this.renderTargetB );
+		renderer.setRenderTarget( this._renderTargetB );
 		renderer.render( this.sceneB, this.cameraB );
 
-		const uniforms = this.fsQuad.material.uniforms;
-		uniforms.tDiffuse1.value = this.renderTargetA.texture;
-		uniforms.tDiffuse2.value = this.renderTargetB.texture;
+		const uniforms = this._fsQuad.material.uniforms;
+		uniforms.tDiffuse1.value = this._renderTargetA.texture;
+		uniforms.tDiffuse2.value = this._renderTargetB.texture;
 
 		if ( this.renderToScreen ) {
 
@@ -80,20 +171,27 @@ class RenderTransitionPass extends Pass {
 
 		}
 
-		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.renderTargetA.dispose();
-		this.renderTargetB.dispose();
 		this.material.dispose();
-		this.fsQuad.dispose();
+
+		this._renderTargetA.dispose();
+		this._renderTargetB.dispose();
+		this._fsQuad.dispose();
 
 	}
 
-	createMaterial() {
+	// internals
+
+	_createMaterial() {
 
 		return new ShaderMaterial( {
 			uniforms: {

package/examples/jsm/postprocessing/SAOPass.js

@@ -23,25 +23,69 @@ import { BlurShaderUtils, DepthLimitedBlurShader } from '../shaders/DepthLimited
 import { CopyShader } from '../shaders/CopyShader.js';
 
 /**
- * SAO implementation inspired from bhouston previous SAO work
+ * A SAO implementation inspired from @bhouston previous SAO work.
+ *
+ * `SAOPass` provides better quality than {@link SSAOPass} but is also more expensive.
+ *
+ * ```js
+ * const saoPass = new SAOPass( scene, camera );
+ * composer.addPass( saoPass );
+ * ```
+ *
+ * @augments Pass
  */
-
 class SAOPass extends Pass {
 
+	/**
+	 * Constructs a new SAO pass.
+	 *
+	 * @param {Scene} scene - The scene to compute the AO for.
+	 * @param {Camera} camera - The camera.
+	 * @param {Vector2} [resolution] - The effect's resolution.
+	 */
 	constructor( scene, camera, resolution = new Vector2( 256, 256 ) ) {
 
 		super();
 
+		/**
+		 * The scene to render the AO for.
+		 *
+		 * @type {Scene}
+		 */
 		this.scene = scene;
+
+		/**
+		 * The camera.
+		 *
+		 * @type {Camera}
+		 */
 		this.camera = camera;
 
+		/**
+		 * Overwritten to perform a clear operation by default.
+		 *
+		 * @type {boolean}
+		 * @default true
+		 */
 		this.clear = true;
+
+		/**
+		 * Overwritten to disable the swap.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.needsSwap = false;
 
-		this.originalClearColor = new Color();
+		this._originalClearColor = new Color();
 		this._oldClearColor = new Color();
-		this.oldClearAlpha = 1;
+		this._oldClearAlpha = 1;
 
+		/**
+		 * The SAO paramter.
+		 *
+		 * @type {Object}
+		 */
 		this.params = {
 			output: 0,
 			saoBias: 0.5,
@@ -55,6 +99,12 @@ class SAOPass extends Pass {
 			saoBlurDepthCutoff: 0.01
 		};
 
+		/**
+		 * The effect's resolution.
+		 *
+		 * @type {Vector2}
+		 * @default (256,256)
+		 */
 		this.resolution = new Vector2( resolution.x, resolution.y );
 
 		this.saoRenderTarget = new WebGLRenderTarget( this.resolution.x, this.resolution.y, { type: HalfFloatType } );
@@ -135,6 +185,17 @@ class SAOPass extends Pass {
 
 	}
 
+	/**
+	 * Performs the SAO 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*/ ) {
 
 		// Rendering readBuffer first when rendering to screen
@@ -143,12 +204,12 @@ class SAOPass extends Pass {
 			this.materialCopy.blending = NoBlending;
 			this.materialCopy.uniforms[ 'tDiffuse' ].value = readBuffer.texture;
 			this.materialCopy.needsUpdate = true;
-			this.renderPass( renderer, this.materialCopy, null );
+			this._renderPass( renderer, this.materialCopy, null );
 
 		}
 
 		renderer.getClearColor( this._oldClearColor );
-		this.oldClearAlpha = renderer.getClearAlpha();
+		this._oldClearAlpha = renderer.getClearAlpha();
 		const oldAutoClear = renderer.autoClear;
 		renderer.autoClear = false;
 
@@ -181,16 +242,16 @@ class SAOPass extends Pass {
 		}
 
 		// render normal and depth
-		this.renderOverride( renderer, this.normalMaterial, this.normalRenderTarget, 0x7777ff, 1.0 );
+		this._renderOverride( renderer, this.normalMaterial, this.normalRenderTarget, 0x7777ff, 1.0 );
 
 		// Rendering SAO texture
-		this.renderPass( renderer, this.saoMaterial, this.saoRenderTarget, 0xffffff, 1.0 );
+		this._renderPass( renderer, this.saoMaterial, this.saoRenderTarget, 0xffffff, 1.0 );
 
 		// Blurring SAO texture
 		if ( this.params.saoBlur ) {
 
-			this.renderPass( renderer, this.vBlurMaterial, this.blurIntermediateRenderTarget, 0xffffff, 1.0 );
-			this.renderPass( renderer, this.hBlurMaterial, this.saoRenderTarget, 0xffffff, 1.0 );
+			this._renderPass( renderer, this.vBlurMaterial, this.blurIntermediateRenderTarget, 0xffffff, 1.0 );
+			this._renderPass( renderer, this.hBlurMaterial, this.saoRenderTarget, 0xffffff, 1.0 );
 
 		}
 
@@ -221,17 +282,64 @@ class SAOPass extends Pass {
 		}
 
 		// Rendering SAOPass result on top of previous pass
-		this.renderPass( renderer, outputMaterial, this.renderToScreen ? null : readBuffer );
+		this._renderPass( renderer, outputMaterial, this.renderToScreen ? null : readBuffer );
 
-		renderer.setClearColor( this._oldClearColor, this.oldClearAlpha );
+		renderer.setClearColor( this._oldClearColor, this._oldClearAlpha );
 		renderer.autoClear = oldAutoClear;
 
 	}
 
-	renderPass( renderer, passMaterial, renderTarget, clearColor, clearAlpha ) {
+	/**
+	 * Sets the size of the pass.
+	 *
+	 * @param {number} width - The width to set.
+	 * @param {number} height - The width to set.
+	 */
+	setSize( width, height ) {
+
+		this.saoRenderTarget.setSize( width, height );
+		this.blurIntermediateRenderTarget.setSize( width, height );
+		this.normalRenderTarget.setSize( width, height );
+
+		this.saoMaterial.uniforms[ 'size' ].value.set( width, height );
+		this.saoMaterial.uniforms[ 'cameraInverseProjectionMatrix' ].value.copy( this.camera.projectionMatrixInverse );
+		this.saoMaterial.uniforms[ 'cameraProjectionMatrix' ].value = this.camera.projectionMatrix;
+		this.saoMaterial.needsUpdate = true;
+
+		this.vBlurMaterial.uniforms[ 'size' ].value.set( width, height );
+		this.vBlurMaterial.needsUpdate = true;
+
+		this.hBlurMaterial.uniforms[ 'size' ].value.set( width, height );
+		this.hBlurMaterial.needsUpdate = true;
+
+	}
+
+	/**
+	 * Frees the GPU-related resources allocated by this instance. Call this
+	 * method whenever the pass is no longer used in your app.
+	 */
+	dispose() {
+
+		this.saoRenderTarget.dispose();
+		this.blurIntermediateRenderTarget.dispose();
+		this.normalRenderTarget.dispose();
+
+		this.normalMaterial.dispose();
+		this.saoMaterial.dispose();
+		this.vBlurMaterial.dispose();
+		this.hBlurMaterial.dispose();
+		this.materialCopy.dispose();
+
+		this.fsQuad.dispose();
+
+	}
+
+	// internal
+
+	_renderPass( renderer, passMaterial, renderTarget, clearColor, clearAlpha ) {
 
 		// save original state
-		renderer.getClearColor( this.originalClearColor );
+		renderer.getClearColor( this._originalClearColor );
 		const originalClearAlpha = renderer.getClearAlpha();
 		const originalAutoClear = renderer.autoClear;
 
@@ -252,14 +360,14 @@ class SAOPass extends Pass {
 
 		// restore original state
 		renderer.autoClear = originalAutoClear;
-		renderer.setClearColor( this.originalClearColor );
+		renderer.setClearColor( this._originalClearColor );
 		renderer.setClearAlpha( originalClearAlpha );
 
 	}
 
-	renderOverride( renderer, overrideMaterial, renderTarget, clearColor, clearAlpha ) {
+	_renderOverride( renderer, overrideMaterial, renderTarget, clearColor, clearAlpha ) {
 
-		renderer.getClearColor( this.originalClearColor );
+		renderer.getClearColor( this._originalClearColor );
 		const originalClearAlpha = renderer.getClearAlpha();
 		const originalAutoClear = renderer.autoClear;
 
@@ -282,46 +390,11 @@ class SAOPass extends Pass {
 
 		// restore original state
 		renderer.autoClear = originalAutoClear;
-		renderer.setClearColor( this.originalClearColor );
+		renderer.setClearColor( this._originalClearColor );
 		renderer.setClearAlpha( originalClearAlpha );
 
 	}
 
-	setSize( width, height ) {
-
-		this.saoRenderTarget.setSize( width, height );
-		this.blurIntermediateRenderTarget.setSize( width, height );
-		this.normalRenderTarget.setSize( width, height );
-
-		this.saoMaterial.uniforms[ 'size' ].value.set( width, height );
-		this.saoMaterial.uniforms[ 'cameraInverseProjectionMatrix' ].value.copy( this.camera.projectionMatrixInverse );
-		this.saoMaterial.uniforms[ 'cameraProjectionMatrix' ].value = this.camera.projectionMatrix;
-		this.saoMaterial.needsUpdate = true;
-
-		this.vBlurMaterial.uniforms[ 'size' ].value.set( width, height );
-		this.vBlurMaterial.needsUpdate = true;
-
-		this.hBlurMaterial.uniforms[ 'size' ].value.set( width, height );
-		this.hBlurMaterial.needsUpdate = true;
-
-	}
-
-	dispose() {
-
-		this.saoRenderTarget.dispose();
-		this.blurIntermediateRenderTarget.dispose();
-		this.normalRenderTarget.dispose();
-
-		this.normalMaterial.dispose();
-		this.saoMaterial.dispose();
-		this.vBlurMaterial.dispose();
-		this.hBlurMaterial.dispose();
-		this.materialCopy.dispose();
-
-		this.fsQuad.dispose();
-
-	}
-
 }
 
 SAOPass.OUTPUT = {