@needle-tools/three 0.169.20-experimental.0 → 0.183.2-canary.0

package/examples/jsm/postprocessing/FilmPass.js

@@ -5,16 +5,48 @@ 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
+ * @three_import import { FilmPass } from 'three/addons/postprocessing/FilmPass.js';
+ */
 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 +56,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 +84,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();
 
 	}
 

package/examples/jsm/postprocessing/GTAOPass.js

@@ -26,28 +26,119 @@ import { generatePdSamplePointInitializer, PoissonDenoiseShader } from '../shade
 import { CopyShader } from '../shaders/CopyShader.js';
 import { SimplexNoise } from '../math/SimplexNoise.js';
 
+/**
+ * A pass for an GTAO effect.
+ *
+ * `GTAOPass` provides better quality than {@link SSAOPass} but is also more expensive.
+ *
+ * ```js
+ * const gtaoPass = new GTAOPass( scene, camera, width, height );
+ * gtaoPass.output = GTAOPass.OUTPUT.Denoise;
+ * composer.addPass( gtaoPass );
+ * ```
+ *
+ * @augments Pass
+ * @three_import import { GTAOPass } from 'three/addons/postprocessing/GTAOPass.js';
+ */
 class GTAOPass extends Pass {
 
-	constructor( scene, camera, width, height, parameters, aoParameters, pdParameters ) {
+	/**
+	 * Constructs a new GTAO 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 {Object} [parameters] - The pass parameters.
+	 * @param {Object} [aoParameters] - The AO parameters.
+	 * @param {Object} [pdParameters] - The denoise parameters.
+	 */
+	constructor( scene, camera, width = 512, height = 512, parameters, aoParameters, pdParameters ) {
 
 		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;
+
+		/**
+		 * The camera.
+		 *
+		 * @type {Camera}
+		 */
 		this.camera = camera;
+
+		/**
+		 * The scene to render the AO for.
+		 *
+		 * @type {Scene}
+		 */
 		this.scene = scene;
+
+		/**
+		 * The output configuration.
+		 *
+		 * @type {number}
+		 * @default 0
+		 */
 		this.output = 0;
 		this._renderGBuffer = true;
-		this._visibilityCache = new Map();
+		this._visibilityCache = [];
+
+		/**
+		 * The AO blend intensity.
+		 *
+		 * @type {number}
+		 * @default 1
+		 */
 		this.blendIntensity = 1.;
 
+		/**
+		 * The number of Poisson Denoise rings.
+		 *
+		 * @type {number}
+		 * @default 2
+		 */
 		this.pdRings = 2.;
+
+		/**
+		 * The Poisson Denoise radius exponent.
+		 *
+		 * @type {number}
+		 * @default 2
+		 */
 		this.pdRadiusExponent = 2.;
+
+		/**
+		 * The Poisson Denoise sample count.
+		 *
+		 * @type {number}
+		 * @default 16
+		 */
 		this.pdSamples = 16;
 
 		this.gtaoNoiseTexture = generateMagicSquareNoise();
-		this.pdNoiseTexture = this.generateNoise();
+		this.pdNoiseTexture = this._generateNoise();
 
 		this.gtaoRenderTarget = new WebGLRenderTarget( this.width, this.height, { type: HalfFloatType } );
 		this.pdRenderTarget = this.gtaoRenderTarget.clone();
@@ -127,9 +218,9 @@ class GTAOPass extends Pass {
 			blendEquationAlpha: AddEquation
 		} );
 
-		this.fsQuad = new FullScreenQuad( null );
+		this._fsQuad = new FullScreenQuad( null );
 
-		this.originalClearColor = new Color();
+		this._originalClearColor = new Color();
 
 		this.setGBuffer( parameters ? parameters.depthTexture : undefined, parameters ? parameters.normalTexture : undefined );
 
@@ -147,6 +238,34 @@ class GTAOPass extends Pass {
 
 	}
 
+	/**
+	 * Sets the size of the pass.
+	 *
+	 * @param {number} width - The width to set.
+	 * @param {number} height - The height to set.
+	 */
+	setSize( width, height ) {
+
+		this.width = width;
+		this.height = height;
+
+		this.gtaoRenderTarget.setSize( width, height );
+		this.normalRenderTarget.setSize( width, height );
+		this.pdRenderTarget.setSize( width, height );
+
+		this.gtaoMaterial.uniforms.resolution.value.set( width, height );
+		this.gtaoMaterial.uniforms.cameraProjectionMatrix.value.copy( this.camera.projectionMatrix );
+		this.gtaoMaterial.uniforms.cameraProjectionMatrixInverse.value.copy( this.camera.projectionMatrixInverse );
+
+		this.pdMaterial.uniforms.resolution.value.set( width, height );
+		this.pdMaterial.uniforms.cameraProjectionMatrixInverse.value.copy( this.camera.projectionMatrixInverse );
+
+	}
+
+	/**
+	 * Frees the GPU-related resources allocated by this instance. Call this
+	 * method whenever the pass is no longer used in your app.
+	 */
 	dispose() {
 
 		this.gtaoNoiseTexture.dispose();
@@ -158,16 +277,30 @@ class GTAOPass extends Pass {
 		this.pdMaterial.dispose();
 		this.copyMaterial.dispose();
 		this.depthRenderMaterial.dispose();
-		this.fsQuad.dispose();
+		this._fsQuad.dispose();
 
 	}
 
+	/**
+	 * A texture holding the computed AO.
+	 *
+	 * @type {Texture}
+	 * @readonly
+	 */
 	get gtaoMap() {
 
 		return this.pdRenderTarget.texture;
 
 	}
 
+	/**
+	 * Configures the GBuffer of this pass. If no arguments are passed,
+	 * the pass creates an internal render target for holding depth
+	 * and normal data.
+	 *
+	 * @param {DepthTexture} [depthTexture] - The depth texture.
+	 * @param {DepthTexture} [normalTexture] - The normal texture.
+	 */
 	setGBuffer( depthTexture, normalTexture ) {
 
 		if ( depthTexture !== undefined ) {
@@ -209,6 +342,12 @@ class GTAOPass extends Pass {
 
 	}
 
+	/**
+	 * Configures the clip box of the GTAO shader with the given AABB.
+	 *
+	 * @param {?Box3} box - The AABB enclosing the scene that should receive AO. When passing
+	 * `null`, to clip box is used.
+	 */
 	setSceneClipBox( box ) {
 
 		if ( box ) {
@@ -227,6 +366,11 @@ class GTAOPass extends Pass {
 
 	}
 
+	/**
+	 * Updates the GTAO material from the given parameter object.
+	 *
+	 * @param {Object} parameters - The GTAO material parameters.
+	 */
 	updateGtaoMaterial( parameters ) {
 
 		if ( parameters.radius !== undefined ) {
@@ -276,6 +420,11 @@ class GTAOPass extends Pass {
 
 	}
 
+	/**
+	 * Updates the Denoise material from the given parameter object.
+	 *
+	 * @param {Object} parameters - The denoise parameters.
+	 */
 	updatePdMaterial( parameters ) {
 
 		let updateShader = false;
@@ -335,15 +484,26 @@ class GTAOPass extends Pass {
 
 	}
 
+	/**
+	 * Performs the GTAO 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 AO)
 
 		if ( this._renderGBuffer ) {
 
-			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();
 
 		}
 
@@ -354,12 +514,12 @@ class GTAOPass extends Pass {
 		this.gtaoMaterial.uniforms.cameraProjectionMatrix.value.copy( this.camera.projectionMatrix );
 		this.gtaoMaterial.uniforms.cameraProjectionMatrixInverse.value.copy( this.camera.projectionMatrixInverse );
 		this.gtaoMaterial.uniforms.cameraWorldMatrix.value.copy( this.camera.matrixWorld );
-		this.renderPass( renderer, this.gtaoMaterial, this.gtaoRenderTarget, 0xffffff, 1.0 );
+		this._renderPass( renderer, this.gtaoMaterial, this.gtaoRenderTarget, 0xffffff, 1.0 );
 
 		// render poisson denoise
 
 		this.pdMaterial.uniforms.cameraProjectionMatrixInverse.value.copy( this.camera.projectionMatrixInverse );
-		this.renderPass( renderer, this.pdMaterial, this.pdRenderTarget, 0xffffff, 1.0 );
+		this._renderPass( renderer, this.pdMaterial, this.pdRenderTarget, 0xffffff, 1.0 );
 
 		// output result to screen
 
@@ -372,7 +532,7 @@ class GTAOPass extends Pass {
 
 				this.copyMaterial.uniforms.tDiffuse.value = readBuffer.texture;
 				this.copyMaterial.blending = NoBlending;
-				this.renderPass( renderer, this.copyMaterial, this.renderToScreen ? null : writeBuffer );
+				this._renderPass( renderer, this.copyMaterial, this.renderToScreen ? null : writeBuffer );
 
 				break;
 
@@ -380,7 +540,7 @@ class GTAOPass extends Pass {
 
 				this.copyMaterial.uniforms.tDiffuse.value = this.gtaoRenderTarget.texture;
 				this.copyMaterial.blending = NoBlending;
-				this.renderPass( renderer, this.copyMaterial, this.renderToScreen ? null : writeBuffer );
+				this._renderPass( renderer, this.copyMaterial, this.renderToScreen ? null : writeBuffer );
 
 				break;
 
@@ -388,7 +548,7 @@ class GTAOPass extends Pass {
 
 				this.copyMaterial.uniforms.tDiffuse.value = this.pdRenderTarget.texture;
 				this.copyMaterial.blending = NoBlending;
-				this.renderPass( renderer, this.copyMaterial, this.renderToScreen ? null : writeBuffer );
+				this._renderPass( renderer, this.copyMaterial, this.renderToScreen ? null : writeBuffer );
 
 				break;
 
@@ -396,7 +556,7 @@ class GTAOPass extends Pass {
 
 				this.depthRenderMaterial.uniforms.cameraNear.value = this.camera.near;
 				this.depthRenderMaterial.uniforms.cameraFar.value = this.camera.far;
-				this.renderPass( renderer, this.depthRenderMaterial, this.renderToScreen ? null : writeBuffer );
+				this._renderPass( renderer, this.depthRenderMaterial, this.renderToScreen ? null : writeBuffer );
 
 				break;
 
@@ -404,7 +564,7 @@ class GTAOPass extends Pass {
 
 				this.copyMaterial.uniforms.tDiffuse.value = this.normalRenderTarget.texture;
 				this.copyMaterial.blending = NoBlending;
-				this.renderPass( renderer, this.copyMaterial, this.renderToScreen ? null : writeBuffer );
+				this._renderPass( renderer, this.copyMaterial, this.renderToScreen ? null : writeBuffer );
 
 				break;
 
@@ -412,11 +572,11 @@ class GTAOPass extends Pass {
 
 				this.copyMaterial.uniforms.tDiffuse.value = readBuffer.texture;
 				this.copyMaterial.blending = NoBlending;
-				this.renderPass( renderer, this.copyMaterial, this.renderToScreen ? null : writeBuffer );
+				this._renderPass( renderer, this.copyMaterial, this.renderToScreen ? null : writeBuffer );
 
 				this.blendMaterial.uniforms.intensity.value = this.blendIntensity;
 				this.blendMaterial.uniforms.tDiffuse.value = this.pdRenderTarget.texture;
-				this.renderPass( renderer, this.blendMaterial, this.renderToScreen ? null : writeBuffer );
+				this._renderPass( renderer, this.blendMaterial, this.renderToScreen ? null : writeBuffer );
 
 				break;
 
@@ -427,10 +587,12 @@ class GTAOPass extends Pass {
 
 	}
 
-	renderPass( renderer, passMaterial, renderTarget, clearColor, clearAlpha ) {
+	// 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;
 
@@ -446,19 +608,19 @@ class GTAOPass 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;
 
@@ -481,61 +643,44 @@ class GTAOPass extends Pass {
 		this.scene.overrideMaterial = null;
 
 		renderer.autoClear = originalAutoClear;
-		renderer.setClearColor( this.originalClearColor );
+		renderer.setClearColor( this._originalClearColor );
 		renderer.setClearAlpha( originalClearAlpha );
 
 	}
 
-	setSize( width, height ) {
-
-		this.width = width;
-		this.height = height;
-
-		this.gtaoRenderTarget.setSize( width, height );
-		this.normalRenderTarget.setSize( width, height );
-		this.pdRenderTarget.setSize( width, height );
-
-		this.gtaoMaterial.uniforms.resolution.value.set( width, height );
-		this.gtaoMaterial.uniforms.cameraProjectionMatrix.value.copy( this.camera.projectionMatrix );
-		this.gtaoMaterial.uniforms.cameraProjectionMatrixInverse.value.copy( this.camera.projectionMatrixInverse );
-
-		this.pdMaterial.uniforms.resolution.value.set( width, height );
-		this.pdMaterial.uniforms.cameraProjectionMatrixInverse.value.copy( this.camera.projectionMatrixInverse );
-
-	}
-
-	overrideVisibility() {
+	_overrideVisibility() {
 
 		const scene = this.scene;
 		const cache = this._visibilityCache;
 
 		scene.traverse( function ( object ) {
 
-			cache.set( object, object.visible );
+			if ( ( object.isPoints || object.isLine || object.isLine2 ) && object.visible ) {
 
-			if ( object.isPoints || object.isLine ) object.visible = false;
+				object.visible = false;
+				cache.push( object );
+
+			}
 
 		} );
 
 	}
 
-	restoreVisibility() {
+	_restoreVisibility() {
 
-		const scene = this.scene;
 		const cache = this._visibilityCache;
 
-		scene.traverse( function ( object ) {
+		for ( let i = 0; i < cache.length; i ++ ) {
 
-			const visible = cache.get( object );
-			object.visible = visible;
+			cache[ i ].visible = true;
 
-		} );
+		}
 
-		cache.clear();
+		cache.length = 0;
 
 	}
 
-	generateNoise( size = 64 ) {
+	_generateNoise( size = 64 ) {
 
 		const simplex = new SimplexNoise();