@plastic-software/three 0.174.0 → 0.175.0

package/examples/jsm/postprocessing/Pass.js

@@ -5,34 +5,97 @@ import {
 	Mesh
 } from 'three';
 
+/**
+ * Abstract base class for all post processing passes.
+ *
+ * This module is only relevant for post processing with {@link WebGLRenderer}.
+ *
+ * @abstract
+ */
 class Pass {
 
+	/**
+	 * Constructs a new pass.
+	 */
 	constructor() {
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isPass = true;
 
-		// if set to true, the pass is processed by the composer
+		/**
+		 * If set to `true`, the pass is processed by the composer.
+		 *
+		 * @type {boolean}
+		 * @default true
+		 */
 		this.enabled = true;
 
-		// if set to true, the pass indicates to swap read and write buffer after rendering
+		/**
+		 * If set to `true`, the pass indicates to swap read and write buffer after rendering.
+		 *
+		 * @type {boolean}
+		 * @default true
+		 */
 		this.needsSwap = true;
 
-		// if set to true, the pass clears its buffer before rendering
+		/**
+		 * If set to `true`, the pass clears its buffer before rendering
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.clear = false;
 
-		// if set to true, the result of the pass is rendered to screen. This is set automatically by EffectComposer.
+		/**
+		 * If set to `true`, the result of the pass is rendered to screen. The last pass in the composers
+		 * pass chain gets automatically rendered to screen, no matter how this property is configured.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.renderToScreen = false;
 
 	}
 
+	/**
+	 * Sets the size of the pass.
+	 *
+	 * @abstract
+	 * @param {number} width - The width to set.
+	 * @param {number} height - The width to set.
+	 */
 	setSize( /* width, height */ ) {}
 
+	/**
+	 * This method holds the render logic of a pass. It must be implemented in all derived classes.
+	 *
+	 * @abstract
+	 * @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 */ ) {
 
 		console.error( 'THREE.Pass: .render() must be implemented in derived pass.' );
 
 	}
 
+	/**
+	 * Frees the GPU-related resources allocated by this instance. Call this
+	 * method whenever the pass is no longer used in your app.
+	 *
+	 * @abstract
+	 */
 	dispose() {}
 
 }
@@ -58,26 +121,57 @@ class FullscreenTriangleGeometry extends BufferGeometry {
 
 const _geometry = new FullscreenTriangleGeometry();
 
+
+/**
+ * This module is a helper for passes which need to render a full
+ * screen effect which is quite common in context of post processing.
+ *
+ * The intended usage is to reuse a single full screen quad for rendering
+ * subsequent passes by just reassigning the `material` reference.
+ *
+ * This module can only be used with {@link WebGLRenderer}.
+ *
+ * @augments Mesh
+ */
 class FullScreenQuad {
 
+	/**
+	 * Constructs a new full screen quad.
+	 *
+	 * @param {?Material} material - The material to render te full screen quad with.
+	 */
 	constructor( material ) {
 
 		this._mesh = new Mesh( _geometry, material );
 
 	}
 
+	/**
+	 * Frees the GPU-related resources allocated by this instance. Call this
+	 * method whenever the instance is no longer used in your app.
+	 */
 	dispose() {
 
 		this._mesh.geometry.dispose();
 
 	}
 
+	/**
+	 * Renders the full screen quad.
+	 *
+	 * @param {WebGLRenderer} renderer - The renderer.
+	 */
 	render( renderer ) {
 
 		renderer.render( this._mesh, _camera );
 
 	}
 
+	/**
+	 * The quad's material.
+	 *
+	 * @type {?Material}
+	 */
 	get material() {
 
 		return this._mesh.material;

package/examples/jsm/postprocessing/RenderPass.js

@@ -3,27 +3,110 @@ import {
 } from 'three';
 import { Pass } from './Pass.js';
 
+/**
+ * This class represents a render pass. It takes a camera and a scene and produces
+ * a beauty pass for subsequent post processing effects.
+ *
+ * ```js
+ * const renderPass = new RenderPass( scene, camera );
+ * composer.addPass( renderPass );
+ * ```
+ *
+ * @augments Pass
+ */
 class RenderPass extends Pass {
 
+	/**
+	 * Constructs a new render pass.
+	 *
+	 * @param {Scene} scene - The scene to render.
+	 * @param {Camera} camera - The camera.
+	 * @param {?Material} [overrideMaterial=null] - The override material. If set, this material is used
+	 * for all objects in the scene.
+	 * @param {?(number|Color|string)} [clearColor=null] - The clear color of the render pass.
+	 * @param {?number} [clearAlpha=null] - The clear alpha of the render pass.
+	 */
 	constructor( scene, camera, overrideMaterial = null, clearColor = null, clearAlpha = null ) {
 
 		super();
 
+		/**
+		 * The scene to render.
+		 *
+		 * @type {Scene}
+		 */
 		this.scene = scene;
+
+		/**
+		 * The camera.
+		 *
+		 * @type {Camera}
+		 */
 		this.camera = camera;
 
+		/**
+		 * The override material. If set, this material is used
+		 * for all objects in the scene.
+		 *
+		 * @type {?Material}
+		 * @default null
+		 */
 		this.overrideMaterial = overrideMaterial;
 
+		/**
+		 * The clear color of the render pass.
+		 *
+		 * @type {?(number|Color|string)}
+		 * @default null
+		 */
 		this.clearColor = clearColor;
+
+		/**
+		 * The clear alpha of the render pass.
+		 *
+		 * @type {?number}
+		 * @default null
+		 */
 		this.clearAlpha = clearAlpha;
 
+		/**
+		 * Overwritten to perform a clear operation by default.
+		 *
+		 * @type {boolean}
+		 * @default true
+		 */
 		this.clear = true;
+
+		/**
+		 * If set to `true`, only the depth can be cleared when `clear` is to `false`.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.clearDepth = false;
+
+		/**
+		 * Overwritten to disable the swap.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.needsSwap = false;
 		this._oldClearColor = new Color();
 
 	}
 
+	/**
+	 * Performs a beauty pass with the configured scene and camera.
+	 *
+	 * @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;

package/examples/jsm/postprocessing/RenderPixelatedPass.js

@@ -10,87 +10,170 @@ import {
 } from 'three';
 import { Pass, FullScreenQuad } from './Pass.js';
 
+/**
+ * A special type of render pass that produces a pixelated beauty pass.
+ *
+ * ```js
+ * const renderPixelatedPass = new RenderPixelatedPass( 6, scene, camera );
+ * composer.addPass( renderPixelatedPass );
+ * ```
+ *
+ * @augments Pass
+ */
 class RenderPixelatedPass extends Pass {
 
+	/**
+	 * Constructs a new render pixelated pass.
+	 *
+	 * @param {number} pixelSize - The effect's pixel size.
+	 * @param {Scene} scene - The scene to render.
+	 * @param {Camera} camera - The camera.
+	 * @param {{normalEdgeStrength:number,depthEdgeStrength:number}} options - The pass options.
+	 */
 	constructor( pixelSize, scene, camera, options = {} ) {
 
 		super();
 
+		/**
+		 * The effect's pixel size.
+		 *
+		 * @type {number}
+		 */
 		this.pixelSize = pixelSize;
-		this.resolution = new Vector2();
-		this.renderResolution = new Vector2();
 
-		this.pixelatedMaterial = this.createPixelatedMaterial();
-		this.normalMaterial = new MeshNormalMaterial();
-
-		this.fsQuad = new FullScreenQuad( this.pixelatedMaterial );
+		/**
+		 * The scene to render.
+		 *
+		 * @type {Scene}
+		 */
 		this.scene = scene;
+
+		/**
+		 * The camera.
+		 *
+		 * @type {Camera}
+		 */
 		this.camera = camera;
 
+		/**
+		 * The normal edge strength.
+		 *
+		 * @type {number}
+		 * @default 0.3
+		 */
 		this.normalEdgeStrength = options.normalEdgeStrength || 0.3;
+
+		/**
+		 * The normal edge strength.
+		 *
+		 * @type {number}
+		 * @default 0.4
+		 */
 		this.depthEdgeStrength = options.depthEdgeStrength || 0.4;
 
-		this.beautyRenderTarget = new WebGLRenderTarget();
-		this.beautyRenderTarget.texture.minFilter = NearestFilter;
-		this.beautyRenderTarget.texture.magFilter = NearestFilter;
-		this.beautyRenderTarget.texture.type = HalfFloatType;
-		this.beautyRenderTarget.depthTexture = new DepthTexture();
+		/**
+		 * The pixelated material.
+		 *
+		 * @type {ShaderMaterial}
+		 */
+		this.pixelatedMaterial = this._createPixelatedMaterial();
+
+		// internals
+
+		this._resolution = new Vector2();
+		this._renderResolution = new Vector2();
 
-		this.normalRenderTarget = new WebGLRenderTarget();
-		this.normalRenderTarget.texture.minFilter = NearestFilter;
-		this.normalRenderTarget.texture.magFilter = NearestFilter;
-		this.normalRenderTarget.texture.type = HalfFloatType;
+		this._normalMaterial = new MeshNormalMaterial();
+
+		this._beautyRenderTarget = new WebGLRenderTarget();
+		this._beautyRenderTarget.texture.minFilter = NearestFilter;
+		this._beautyRenderTarget.texture.magFilter = NearestFilter;
+		this._beautyRenderTarget.texture.type = HalfFloatType;
+		this._beautyRenderTarget.depthTexture = new DepthTexture();
+
+		this._normalRenderTarget = new WebGLRenderTarget();
+		this._normalRenderTarget.texture.minFilter = NearestFilter;
+		this._normalRenderTarget.texture.magFilter = NearestFilter;
+		this._normalRenderTarget.texture.type = HalfFloatType;
+
+		this._fsQuad = new FullScreenQuad( this.pixelatedMaterial );
 
 	}
 
+	/**
+	 * Frees the GPU-related resources allocated by this instance. Call this
+	 * method whenever the pass is no longer used in your app.
+	 */
 	dispose() {
 
-		this.beautyRenderTarget.dispose();
-		this.normalRenderTarget.dispose();
+		this._beautyRenderTarget.dispose();
+		this._normalRenderTarget.dispose();
 
 		this.pixelatedMaterial.dispose();
-		this.normalMaterial.dispose();
+		this._normalMaterial.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 ) {
 
-		this.resolution.set( width, height );
-		this.renderResolution.set( ( width / this.pixelSize ) | 0, ( height / this.pixelSize ) | 0 );
-		const { x, y } = this.renderResolution;
-		this.beautyRenderTarget.setSize( x, y );
-		this.normalRenderTarget.setSize( x, y );
-		this.fsQuad.material.uniforms.resolution.value.set( x, y, 1 / x, 1 / y );
+		this._resolution.set( width, height );
+		this._renderResolution.set( ( width / this.pixelSize ) | 0, ( height / this.pixelSize ) | 0 );
+		const { x, y } = this._renderResolution;
+		this._beautyRenderTarget.setSize( x, y );
+		this._normalRenderTarget.setSize( x, y );
+		this._fsQuad.material.uniforms.resolution.value.set( x, y, 1 / x, 1 / y );
 
 	}
 
+	/**
+	 * Sets the effect's pixel size.
+	 *
+	 * @param {number} pixelSize - The pixel size to set.
+	 */
 	setPixelSize( pixelSize ) {
 
 		this.pixelSize = pixelSize;
-		this.setSize( this.resolution.x, this.resolution.y );
+		this.setSize( this._resolution.x, this._resolution.y );
 
 	}
 
-	render( renderer, writeBuffer ) {
-
-		const uniforms = this.fsQuad.material.uniforms;
+	/**
+	 * Performs the pixelation 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 uniforms = this._fsQuad.material.uniforms;
 		uniforms.normalEdgeStrength.value = this.normalEdgeStrength;
 		uniforms.depthEdgeStrength.value = this.depthEdgeStrength;
 
-		renderer.setRenderTarget( this.beautyRenderTarget );
+		renderer.setRenderTarget( this._beautyRenderTarget );
 		renderer.render( this.scene, this.camera );
 
 		const overrideMaterial_old = this.scene.overrideMaterial;
-		renderer.setRenderTarget( this.normalRenderTarget );
-		this.scene.overrideMaterial = this.normalMaterial;
+		renderer.setRenderTarget( this._normalRenderTarget );
+		this.scene.overrideMaterial = this._normalMaterial;
 		renderer.render( this.scene, this.camera );
 		this.scene.overrideMaterial = overrideMaterial_old;
 
-		uniforms.tDiffuse.value = this.beautyRenderTarget.texture;
-		uniforms.tDepth.value = this.beautyRenderTarget.depthTexture;
-		uniforms.tNormal.value = this.normalRenderTarget.texture;
+		uniforms.tDiffuse.value = this._beautyRenderTarget.texture;
+		uniforms.tDepth.value = this._beautyRenderTarget.depthTexture;
+		uniforms.tNormal.value = this._normalRenderTarget.texture;
 
 		if ( this.renderToScreen ) {
 
@@ -104,25 +187,20 @@ class RenderPixelatedPass extends Pass {
 
 		}
 
-		this.fsQuad.render( renderer );
+		this._fsQuad.render( renderer );
 
 	}
 
-	createPixelatedMaterial() {
+	// internals
+
+	_createPixelatedMaterial() {
 
 		return new ShaderMaterial( {
 			uniforms: {
 				tDiffuse: { value: null },
 				tDepth: { value: null },
 				tNormal: { value: null },
-				resolution: {
-					value: new Vector4(
-						this.renderResolution.x,
-						this.renderResolution.y,
-						1 / this.renderResolution.x,
-						1 / this.renderResolution.y,
-					)
-				},
+				resolution: { value: new Vector4() },
 				normalEdgeStrength: { value: 0 },
 				depthEdgeStrength: { value: 0 }
 			},