@plastic-software/three 0.174.0 → 0.175.0

package/examples/jsm/postprocessing/SSAARenderPass.js

@@ -10,41 +10,102 @@ import { Pass, FullScreenQuad } from './Pass.js';
 import { CopyShader } from '../shaders/CopyShader.js';
 
 /**
-*
-* Supersample Anti-Aliasing Render Pass
-*
-* This manual approach to SSAA re-renders the scene ones for each sample with camera jitter and accumulates the results.
-*
-* References: https://en.wikipedia.org/wiki/Supersampling
-*
-*/
-
+ * Supersample Anti-Aliasing Render Pass.
+ *
+ * This manual approach to SSAA re-renders the scene ones for each sample with camera jitter and accumulates the results.
+ *
+ * ```js
+ * const ssaaRenderPass = new SSAARenderPass( scene, camera );
+ * ssaaRenderPass.sampleLevel = 3;
+ * composer.addPass( ssaaRenderPass );
+ * ```
+ *
+ * @augments Pass
+ */
 class SSAARenderPass extends Pass {
 
-	constructor( scene, camera, clearColor, clearAlpha ) {
+	/**
+	 * Constructs a new SSAA 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 = 0x000000, clearAlpha = 0 ) {
 
 		super();
 
+		/**
+		 * The scene to render.
+		 *
+		 * @type {Scene}
+		 */
 		this.scene = scene;
+
+		/**
+		 * The camera.
+		 *
+		 * @type {Camera}
+		 */
 		this.camera = camera;
 
-		this.sampleLevel = 4; // specified as n, where the number of samples is 2^n, so sampleLevel = 4, is 2^4 samples, 16.
+		/**
+		 * The sample level. Specified as n, where the number of
+		 * samples is 2^n, so sampleLevel = 4, is 2^4 samples, 16.
+		 *
+		 * @type {number}
+		 * @default 4
+		 */
+		this.sampleLevel = 4;
+
+		/**
+		 * Whether the pass should be unbiased or not. This property has the most
+		 * visible effect when rendering to a RGBA8 buffer because it mitigates
+		 * rounding errors. By default RGBA16F is used.
+		 *
+		 * @type {boolean}
+		 * @default true
+		 */
 		this.unbiased = true;
 
+		/**
+		 * Whether to use a stencil buffer or not. This property can't
+		 * be changed after the first render.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.stencilBuffer = false;
 
-		// as we need to clear the buffer in this pass, clearColor must be set to something, defaults to black.
-		this.clearColor = ( clearColor !== undefined ) ? clearColor : 0x000000;
-		this.clearAlpha = ( clearAlpha !== undefined ) ? clearAlpha : 0;
+		/**
+		 * The clear color of the render pass.
+		 *
+		 * @type {?(number|Color|string)}
+		 * @default 0x000000
+		 */
+		this.clearColor = clearColor;
+
+		/**
+		 * The clear alpha of the render pass.
+		 *
+		 * @type {?number}
+		 * @default 0
+		 */
+		this.clearAlpha = clearAlpha;
+
+		// internals
+
+		this._sampleRenderTarget = null;
+
 		this._oldClearColor = new Color();
 
-		const copyShader = CopyShader;
-		this.copyUniforms = UniformsUtils.clone( copyShader.uniforms );
+		this._copyUniforms = UniformsUtils.clone( CopyShader.uniforms );
 
-		this.copyMaterial = new ShaderMaterial(	{
-			uniforms: this.copyUniforms,
-			vertexShader: copyShader.vertexShader,
-			fragmentShader: copyShader.fragmentShader,
+		this._copyMaterial = new ShaderMaterial(	{
+			uniforms: this._copyUniforms,
+			vertexShader: CopyShader.vertexShader,
+			fragmentShader: CopyShader.fragmentShader,
 			transparent: true,
 			depthTest: false,
 			depthWrite: false,
@@ -52,37 +113,58 @@ class SSAARenderPass extends Pass {
 			blending: AdditiveBlending
 		} );
 
-		this.fsQuad = new FullScreenQuad( this.copyMaterial );
+		this._fsQuad = new FullScreenQuad( this._copyMaterial );
 
 	}
 
+	/**
+	 * Frees the GPU-related resources allocated by this instance. Call this
+	 * method whenever the pass is no longer used in your app.
+	 */
 	dispose() {
 
-		if ( this.sampleRenderTarget ) {
+		if ( this._sampleRenderTarget ) {
 
-			this.sampleRenderTarget.dispose();
-			this.sampleRenderTarget = null;
+			this._sampleRenderTarget.dispose();
+			this._sampleRenderTarget = null;
 
 		}
 
-		this.copyMaterial.dispose();
+		this._copyMaterial.dispose();
 
-		this.fsQuad.dispose();
+		this._fsQuad.dispose();
 
 	}
 
+	/**
+	 * Sets the size of the pass.
+	 *
+	 * @param {number} width - The width to set.
+	 * @param {number} height - The width to set.
+	 */
 	setSize( width, height ) {
 
-		if ( this.sampleRenderTarget )	this.sampleRenderTarget.setSize( width, height );
+		if ( this._sampleRenderTarget )	this._sampleRenderTarget.setSize( width, height );
 
 	}
 
-	render( renderer, writeBuffer, readBuffer ) {
+	/**
+	 * Performs the SSAA 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.sampleRenderTarget ) {
+		if ( ! this._sampleRenderTarget ) {
 
-			this.sampleRenderTarget = new WebGLRenderTarget( readBuffer.width, readBuffer.height, { type: HalfFloatType, stencilBuffer: this.stencilBuffer } );
-			this.sampleRenderTarget.texture.name = 'SSAARenderPass.sample';
+			this._sampleRenderTarget = new WebGLRenderTarget( readBuffer.width, readBuffer.height, { type: HalfFloatType, stencilBuffer: this.stencilBuffer } );
+			this._sampleRenderTarget.texture.name = 'SSAARenderPass.sample';
 
 		}
 
@@ -96,7 +178,7 @@ class SSAARenderPass extends Pass {
 
 		const baseSampleWeight = 1.0 / jitterOffsets.length;
 		const roundingRange = 1 / 32;
-		this.copyUniforms[ 'tDiffuse' ].value = this.sampleRenderTarget.texture;
+		this._copyUniforms[ 'tDiffuse' ].value = this._sampleRenderTarget.texture;
 
 		const viewOffset = {
 
@@ -145,9 +227,9 @@ class SSAARenderPass extends Pass {
 
 			}
 
-			this.copyUniforms[ 'opacity' ].value = sampleWeight;
+			this._copyUniforms[ 'opacity' ].value = sampleWeight;
 			renderer.setClearColor( this.clearColor, this.clearAlpha );
-			renderer.setRenderTarget( this.sampleRenderTarget );
+			renderer.setRenderTarget( this._sampleRenderTarget );
 			renderer.clear();
 			renderer.render( this.scene, this.camera );
 
@@ -160,7 +242,7 @@ class SSAARenderPass extends Pass {
 
 			}
 
-			this.fsQuad.render( renderer );
+			this._fsQuad.render( renderer );
 
 		}
 

package/examples/jsm/postprocessing/SSAOPass.js

@@ -27,35 +27,123 @@ import { SimplexNoise } from '../math/SimplexNoise.js';
 import { SSAOBlurShader, SSAODepthShader, SSAOShader } from '../shaders/SSAOShader.js';
 import { CopyShader } from '../shaders/CopyShader.js';
 
+/**
+ * A pass for a basic SSAO effect.
+ *
+ * {@link SAOPass} and {@link GTAPass} produce a more advanced AO but are also
+ * more expensive.
+ *
+ * ```js
+ * const ssaoPass = new SSAOPass( scene, camera, width, height );
+ * composer.addPass( ssaoPass );
+ * ```
+ *
+ * @augments Pass
+ */
 class SSAOPass extends Pass {
 
-	constructor( scene, camera, width, height, kernelSize = 32 ) {
+	/**
+	 * Constructs a new SSAO pass.
+	 *
+	 * @param {Scene} scene - The scene to compute the AO for.
+	 * @param {Camera} camera - The camera.
+	 * @param {number} [width=512] - The width of the effect.
+	 * @param {number} [height=512] - The height of the effect.
+	 * @param {number} [kernelSize=32] - The kernel size.
+	 */
+	constructor( scene, camera, width = 512, height = 512, kernelSize = 32 ) {
 
 		super();
 
-		this.width = ( width !== undefined ) ? width : 512;
-		this.height = ( height !== undefined ) ? height : 512;
+		/**
+		 * The width of the effect.
+		 *
+		 * @type {number}
+		 * @default 512
+		 */
+		this.width = width;
+
+		/**
+		 * The height of the effect.
+		 *
+		 * @type {number}
+		 * @default 512
+		 */
+		this.height = height;
 
+		/**
+		 * 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;
 
+		/**
+		 * The camera.
+		 *
+		 * @type {Camera}
+		 */
 		this.camera = camera;
+
+		/**
+		 * The scene to render the AO for.
+		 *
+		 * @type {Scene}
+		 */
 		this.scene = scene;
 
+		/**
+		 * The kernel radius controls how wide the
+		 * AO spreads.
+		 *
+		 * @type {number}
+		 * @default 8
+		 */
 		this.kernelRadius = 8;
 		this.kernel = [];
 		this.noiseTexture = null;
+
+		/**
+		 * The output configuration.
+		 *
+		 * @type {number}
+		 * @default 0
+		 */
 		this.output = 0;
 
+		/**
+		 * Defines the minimum distance that should be
+		 * affected by the AO.
+		 *
+		 * @type {number}
+		 * @default 0.005
+		 */
 		this.minDistance = 0.005;
+
+		/**
+		 * Defines the maximum distance that should be
+		 * affected by the AO.
+		 *
+		 * @type {number}
+		 * @default 0.1
+		 */
 		this.maxDistance = 0.1;
 
 		this._visibilityCache = new Map();
 
 		//
 
-		this.generateSampleKernel( kernelSize );
-		this.generateRandomKernelRotations();
+		this._generateSampleKernel( kernelSize );
+		this._generateRandomKernelRotations();
 
 		// depth texture
 
@@ -146,12 +234,18 @@ class SSAOPass extends Pass {
 			blendEquationAlpha: AddEquation
 		} );
 
-		this.fsQuad = new FullScreenQuad( null );
+		// internals
+
+		this._fsQuad = new FullScreenQuad( null );
 
-		this.originalClearColor = new Color();
+		this._originalClearColor = new Color();
 
 	}
 
+	/**
+	 * Frees the GPU-related resources allocated by this instance. Call this
+	 * method whenever the pass is no longer used in your app.
+	 */
 	dispose() {
 
 		// dispose render targets
@@ -169,28 +263,39 @@ class SSAOPass extends Pass {
 
 		// dispose full screen quad
 
-		this.fsQuad.dispose();
+		this._fsQuad.dispose();
 
 	}
 
+	/**
+	 * Performs the SSAO 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 normals and depth (honor only meshes, points and lines do not contribute to SSAO)
 
-		this.overrideVisibility();
-		this.renderOverride( renderer, this.normalMaterial, this.normalRenderTarget, 0x7777ff, 1.0 );
-		this.restoreVisibility();
+		this._overrideVisibility();
+		this._renderOverride( renderer, this.normalMaterial, this.normalRenderTarget, 0x7777ff, 1.0 );
+		this._restoreVisibility();
 
 		// render SSAO
 
 		this.ssaoMaterial.uniforms[ 'kernelRadius' ].value = this.kernelRadius;
 		this.ssaoMaterial.uniforms[ 'minDistance' ].value = this.minDistance;
 		this.ssaoMaterial.uniforms[ 'maxDistance' ].value = this.maxDistance;
-		this.renderPass( renderer, this.ssaoMaterial, this.ssaoRenderTarget );
+		this._renderPass( renderer, this.ssaoMaterial, this.ssaoRenderTarget );
 
 		// render blur
 
-		this.renderPass( renderer, this.blurMaterial, this.blurRenderTarget );
+		this._renderPass( renderer, this.blurMaterial, this.blurRenderTarget );
 
 		// output result to screen
 
@@ -200,7 +305,7 @@ class SSAOPass extends Pass {
 
 				this.copyMaterial.uniforms[ 'tDiffuse' ].value = this.ssaoRenderTarget.texture;
 				this.copyMaterial.blending = NoBlending;
-				this.renderPass( renderer, this.copyMaterial, this.renderToScreen ? null : readBuffer );
+				this._renderPass( renderer, this.copyMaterial, this.renderToScreen ? null : readBuffer );
 
 				break;
 
@@ -208,13 +313,13 @@ class SSAOPass extends Pass {
 
 				this.copyMaterial.uniforms[ 'tDiffuse' ].value = this.blurRenderTarget.texture;
 				this.copyMaterial.blending = NoBlending;
-				this.renderPass( renderer, this.copyMaterial, this.renderToScreen ? null : readBuffer );
+				this._renderPass( renderer, this.copyMaterial, this.renderToScreen ? null : readBuffer );
 
 				break;
 
 			case SSAOPass.OUTPUT.Depth:
 
-				this.renderPass( renderer, this.depthRenderMaterial, this.renderToScreen ? null : readBuffer );
+				this._renderPass( renderer, this.depthRenderMaterial, this.renderToScreen ? null : readBuffer );
 
 				break;
 
@@ -222,7 +327,7 @@ class SSAOPass extends Pass {
 
 				this.copyMaterial.uniforms[ 'tDiffuse' ].value = this.normalRenderTarget.texture;
 				this.copyMaterial.blending = NoBlending;
-				this.renderPass( renderer, this.copyMaterial, this.renderToScreen ? null : readBuffer );
+				this._renderPass( renderer, this.copyMaterial, this.renderToScreen ? null : readBuffer );
 
 				break;
 
@@ -230,7 +335,7 @@ class SSAOPass extends Pass {
 
 				this.copyMaterial.uniforms[ 'tDiffuse' ].value = this.blurRenderTarget.texture;
 				this.copyMaterial.blending = CustomBlending;
-				this.renderPass( renderer, this.copyMaterial, this.renderToScreen ? null : readBuffer );
+				this._renderPass( renderer, this.copyMaterial, this.renderToScreen ? null : readBuffer );
 
 				break;
 
@@ -241,10 +346,35 @@ class SSAOPass extends Pass {
 
 	}
 
-	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.width = width;
+		this.height = height;
+
+		this.ssaoRenderTarget.setSize( width, height );
+		this.normalRenderTarget.setSize( width, height );
+		this.blurRenderTarget.setSize( width, height );
+
+		this.ssaoMaterial.uniforms[ 'resolution' ].value.set( width, height );
+		this.ssaoMaterial.uniforms[ 'cameraProjectionMatrix' ].value.copy( this.camera.projectionMatrix );
+		this.ssaoMaterial.uniforms[ 'cameraInverseProjectionMatrix' ].value.copy( this.camera.projectionMatrixInverse );
+
+		this.blurMaterial.uniforms[ 'resolution' ].value.set( width, height );
+
+	}
+
+	// internals
+
+	_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;
 
@@ -260,19 +390,19 @@ class SSAOPass extends Pass {
 
 		}
 
-		this.fsQuad.material = passMaterial;
-		this.fsQuad.render( renderer );
+		this._fsQuad.material = passMaterial;
+		this._fsQuad.render( renderer );
 
 		// 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;
 
@@ -297,29 +427,12 @@ class SSAOPass extends Pass {
 		// restore original state
 
 		renderer.autoClear = originalAutoClear;
-		renderer.setClearColor( this.originalClearColor );
+		renderer.setClearColor( this._originalClearColor );
 		renderer.setClearAlpha( originalClearAlpha );
 
 	}
 
-	setSize( width, height ) {
-
-		this.width = width;
-		this.height = height;
-
-		this.ssaoRenderTarget.setSize( width, height );
-		this.normalRenderTarget.setSize( width, height );
-		this.blurRenderTarget.setSize( width, height );
-
-		this.ssaoMaterial.uniforms[ 'resolution' ].value.set( width, height );
-		this.ssaoMaterial.uniforms[ 'cameraProjectionMatrix' ].value.copy( this.camera.projectionMatrix );
-		this.ssaoMaterial.uniforms[ 'cameraInverseProjectionMatrix' ].value.copy( this.camera.projectionMatrixInverse );
-
-		this.blurMaterial.uniforms[ 'resolution' ].value.set( width, height );
-
-	}
-
-	generateSampleKernel( kernelSize ) {
+	_generateSampleKernel( kernelSize ) {
 
 		const kernel = this.kernel;
 
@@ -342,7 +455,7 @@ class SSAOPass extends Pass {
 
 	}
 
-	generateRandomKernelRotations() {
+	_generateRandomKernelRotations() {
 
 		const width = 4, height = 4;
 
@@ -368,7 +481,7 @@ class SSAOPass extends Pass {
 
 	}
 
-	overrideVisibility() {
+	_overrideVisibility() {
 
 		const scene = this.scene;
 		const cache = this._visibilityCache;
@@ -383,7 +496,7 @@ class SSAOPass extends Pass {
 
 	}
 
-	restoreVisibility() {
+	_restoreVisibility() {
 
 		const scene = this.scene;
 		const cache = this._visibilityCache;