@plastic-software/three 0.174.0 → 0.175.1

package/examples/jsm/postprocessing/UnrealBloomPass.js

@@ -14,28 +14,86 @@ import { CopyShader } from '../shaders/CopyShader.js';
 import { LuminosityHighPassShader } from '../shaders/LuminosityHighPassShader.js';
 
 /**
- * UnrealBloomPass is inspired by the bloom pass of Unreal Engine. It creates a
+ * This pass is inspired by the bloom pass of Unreal Engine. It creates a
  * mip map chain of bloom textures and blurs them with different radii. Because
  * of the weighted combination of mips, and because larger blurs are done on
  * higher mips, this effect provides good quality and performance.
  *
+ * When using this pass, tone mapping must be enabled in the renderer settings.
+ *
  * Reference:
- * - https://docs.unrealengine.com/latest/INT/Engine/Rendering/PostProcessEffects/Bloom/
+ * - [Bloom in Unreal Engine]{@link https://docs.unrealengine.com/latest/INT/Engine/Rendering/PostProcessEffects/Bloom/}
+ *
+ * ```js
+ * const resolution = new THREE.Vector2( window.innerWidth, window.innerHeight );
+ * const bloomPass = new UnrealBloomPass( resolution, 1.5, 0.4, 0.85 );
+ * composer.addPass( bloomPass );
+ * ```
+ *
+ * @augments Pass
  */
 class UnrealBloomPass extends Pass {
 
-	constructor( resolution, strength, radius, threshold ) {
+	/**
+	 * Constructs a new Unreal Bloom pass.
+	 *
+	 * @param {Vector2} [resolution] - The effect's resolution.
+	 * @param {number} [strength=1] - The Bloom strength.
+	 * @param {number} radius - The Bloom radius.
+	 * @param {number} threshold - The luminance threshold limits which bright areas contribute to the Bloom effect.
+	 */
+	constructor( resolution, strength = 1, radius, threshold ) {
 
 		super();
 
-		this.strength = ( strength !== undefined ) ? strength : 1;
+		/**
+		 * The Bloom strength.
+		 *
+		 * @type {number}
+		 * @default 1
+		 */
+		this.strength = strength;
+
+		/**
+		 * The Bloom radius.
+		 *
+		 * @type {number}
+		 */
 		this.radius = radius;
+
+		/**
+		 * The luminance threshold limits which bright areas contribute to the Bloom effect.
+		 *
+		 * @type {number}
+		 */
 		this.threshold = threshold;
+
+		/**
+		 * The effect's resolution.
+		 *
+		 * @type {Vector2}
+		 * @default (256,256)
+		 */
 		this.resolution = ( resolution !== undefined ) ? new Vector2( resolution.x, resolution.y ) : new Vector2( 256, 256 );
 
-		// create color only once here, reuse it later inside the render function
+		/**
+		 * The effect's clear color
+		 *
+		 * @type {Color}
+		 * @default (0,0,0)
+		 */
 		this.clearColor = new Color( 0, 0, 0 );
 
+		/**
+		 * Overwritten to disable the swap.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
+		this.needsSwap = false;
+
+		// internals
+
 		// render targets
 		this.renderTargetsHorizontal = [];
 		this.renderTargetsVertical = [];
@@ -92,7 +150,7 @@ class UnrealBloomPass extends Pass {
 
 		for ( let i = 0; i < this.nMips; i ++ ) {
 
-			this.separableBlurMaterials.push( this.getSeparableBlurMaterial( kernelSizeArray[ i ] ) );
+			this.separableBlurMaterials.push( this._getSeparableBlurMaterial( kernelSizeArray[ i ] ) );
 
 			this.separableBlurMaterials[ i ].uniforms[ 'invSize' ].value = new Vector2( 1 / resx, 1 / resy );
 
@@ -104,7 +162,7 @@ class UnrealBloomPass extends Pass {
 
 		// composite material
 
-		this.compositeMaterial = this.getCompositeMaterial( this.nMips );
+		this.compositeMaterial = this._getCompositeMaterial( this.nMips );
 		this.compositeMaterial.uniforms[ 'blurTexture1' ].value = this.renderTargetsVertical[ 0 ].texture;
 		this.compositeMaterial.uniforms[ 'blurTexture2' ].value = this.renderTargetsVertical[ 1 ].texture;
 		this.compositeMaterial.uniforms[ 'blurTexture3' ].value = this.renderTargetsVertical[ 2 ].texture;
@@ -120,32 +178,31 @@ class UnrealBloomPass extends Pass {
 
 		// blend material
 
-		const copyShader = CopyShader;
-
-		this.copyUniforms = UniformsUtils.clone( copyShader.uniforms );
+		this.copyUniforms = UniformsUtils.clone( CopyShader.uniforms );
 
 		this.blendMaterial = new ShaderMaterial( {
 			uniforms: this.copyUniforms,
-			vertexShader: copyShader.vertexShader,
-			fragmentShader: copyShader.fragmentShader,
+			vertexShader: CopyShader.vertexShader,
+			fragmentShader: CopyShader.fragmentShader,
 			blending: AdditiveBlending,
 			depthTest: false,
 			depthWrite: false,
 			transparent: true
 		} );
 
-		this.enabled = true;
-		this.needsSwap = false;
-
 		this._oldClearColor = new Color();
-		this.oldClearAlpha = 1;
+		this._oldClearAlpha = 1;
 
-		this.basic = new MeshBasicMaterial();
+		this._basic = new MeshBasicMaterial();
 
-		this.fsQuad = new FullScreenQuad( null );
+		this._fsQuad = new FullScreenQuad( null );
 
 	}
 
+	/**
+	 * Frees the GPU-related resources allocated by this instance. Call this
+	 * method whenever the pass is no longer used in your app.
+	 */
 	dispose() {
 
 		for ( let i = 0; i < this.renderTargetsHorizontal.length; i ++ ) {
@@ -172,14 +229,20 @@ class UnrealBloomPass extends Pass {
 
 		this.compositeMaterial.dispose();
 		this.blendMaterial.dispose();
-		this.basic.dispose();
+		this._basic.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 ) {
 
 		let resx = Math.round( width / 2 );
@@ -201,10 +264,21 @@ class UnrealBloomPass extends Pass {
 
 	}
 
+	/**
+	 * Performs the Bloom 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.getClearColor( this._oldClearColor );
-		this.oldClearAlpha = renderer.getClearAlpha();
+		this._oldClearAlpha = renderer.getClearAlpha();
 		const oldAutoClear = renderer.autoClear;
 		renderer.autoClear = false;
 
@@ -216,12 +290,12 @@ class UnrealBloomPass extends Pass {
 
 		if ( this.renderToScreen ) {
 
-			this.fsQuad.material = this.basic;
-			this.basic.map = readBuffer.texture;
+			this._fsQuad.material = this._basic;
+			this._basic.map = readBuffer.texture;
 
 			renderer.setRenderTarget( null );
 			renderer.clear();
-			this.fsQuad.render( renderer );
+			this._fsQuad.render( renderer );
 
 		}
 
@@ -229,11 +303,11 @@ class UnrealBloomPass extends Pass {
 
 		this.highPassUniforms[ 'tDiffuse' ].value = readBuffer.texture;
 		this.highPassUniforms[ 'luminosityThreshold' ].value = this.threshold;
-		this.fsQuad.material = this.materialHighPassFilter;
+		this._fsQuad.material = this.materialHighPassFilter;
 
 		renderer.setRenderTarget( this.renderTargetBright );
 		renderer.clear();
-		this.fsQuad.render( renderer );
+		this._fsQuad.render( renderer );
 
 		// 2. Blur All the mips progressively
 
@@ -241,19 +315,19 @@ class UnrealBloomPass extends Pass {
 
 		for ( let i = 0; i < this.nMips; i ++ ) {
 
-			this.fsQuad.material = this.separableBlurMaterials[ i ];
+			this._fsQuad.material = this.separableBlurMaterials[ i ];
 
 			this.separableBlurMaterials[ i ].uniforms[ 'colorTexture' ].value = inputRenderTarget.texture;
 			this.separableBlurMaterials[ i ].uniforms[ 'direction' ].value = UnrealBloomPass.BlurDirectionX;
 			renderer.setRenderTarget( this.renderTargetsHorizontal[ i ] );
 			renderer.clear();
-			this.fsQuad.render( renderer );
+			this._fsQuad.render( renderer );
 
 			this.separableBlurMaterials[ i ].uniforms[ 'colorTexture' ].value = this.renderTargetsHorizontal[ i ].texture;
 			this.separableBlurMaterials[ i ].uniforms[ 'direction' ].value = UnrealBloomPass.BlurDirectionY;
 			renderer.setRenderTarget( this.renderTargetsVertical[ i ] );
 			renderer.clear();
-			this.fsQuad.render( renderer );
+			this._fsQuad.render( renderer );
 
 			inputRenderTarget = this.renderTargetsVertical[ i ];
 
@@ -261,18 +335,18 @@ class UnrealBloomPass extends Pass {
 
 		// Composite All the mips
 
-		this.fsQuad.material = this.compositeMaterial;
+		this._fsQuad.material = this.compositeMaterial;
 		this.compositeMaterial.uniforms[ 'bloomStrength' ].value = this.strength;
 		this.compositeMaterial.uniforms[ 'bloomRadius' ].value = this.radius;
 		this.compositeMaterial.uniforms[ 'bloomTintColors' ].value = this.bloomTintColors;
 
 		renderer.setRenderTarget( this.renderTargetsHorizontal[ 0 ] );
 		renderer.clear();
-		this.fsQuad.render( renderer );
+		this._fsQuad.render( renderer );
 
 		// Blend it additively over the input texture
 
-		this.fsQuad.material = this.blendMaterial;
+		this._fsQuad.material = this.blendMaterial;
 		this.copyUniforms[ 'tDiffuse' ].value = this.renderTargetsHorizontal[ 0 ].texture;
 
 		if ( maskActive ) renderer.state.buffers.stencil.setTest( true );
@@ -280,23 +354,25 @@ class UnrealBloomPass extends Pass {
 		if ( this.renderToScreen ) {
 
 			renderer.setRenderTarget( null );
-			this.fsQuad.render( renderer );
+			this._fsQuad.render( renderer );
 
 		} else {
 
 			renderer.setRenderTarget( readBuffer );
-			this.fsQuad.render( renderer );
+			this._fsQuad.render( renderer );
 
 		}
 
 		// Restore renderer settings
 
-		renderer.setClearColor( this._oldClearColor, this.oldClearAlpha );
+		renderer.setClearColor( this._oldClearColor, this._oldClearAlpha );
 		renderer.autoClear = oldAutoClear;
 
 	}
 
-	getSeparableBlurMaterial( kernelRadius ) {
+	// internals
+
+	_getSeparableBlurMaterial( kernelRadius ) {
 
 		const coefficients = [];
 
@@ -352,7 +428,7 @@ class UnrealBloomPass extends Pass {
 
 	}
 
-	getCompositeMaterial( nMips ) {
+	_getCompositeMaterial( nMips ) {
 
 		return new ShaderMaterial( {
 

package/examples/jsm/renderers/CSS2DRenderer.js

@@ -5,14 +5,38 @@ import {
 	Vector3
 } from 'three';
 
+/**
+ * The only type of 3D object that is supported by {@link CSS2DRenderer}.
+ *
+ * @augments Object3D
+ */
 class CSS2DObject extends Object3D {
 
+	/**
+	 * Constructs a new CSS2D object.
+	 *
+	 * @param {DOMElement} [element] - The DOM element.
+	 */
 	constructor( element = document.createElement( 'div' ) ) {
 
 		super();
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isCSS2DObject = true;
 
+		/**
+		 * The DOM element which defines the appearance of this 3D object.
+		 *
+		 * @type {DOMElement}
+		 * @readonly
+		 * @default true
+		 */
 		this.element = element;
 
 		this.element.style.position = 'absolute';
@@ -20,7 +44,14 @@ class CSS2DObject extends Object3D {
 
 		this.element.setAttribute( 'draggable', false );
 
-		this.center = new Vector2( 0.5, 0.5 ); // ( 0, 0 ) is the lower left; ( 1, 1 ) is the top right
+		/**
+		 * The 3D objects center point.
+		 * `( 0, 0 )` is the lower left, `( 1, 1 )` is the top right.
+		 *
+		 * @type {Vector2}
+		 * @default (0.5,0.5)
+		 */
+		this.center = new Vector2( 0.5, 0.5 );
 
 		this.addEventListener( 'removed', function () {
 
@@ -63,8 +94,23 @@ const _viewProjectionMatrix = new Matrix4();
 const _a = new Vector3();
 const _b = new Vector3();
 
+/**
+ * This renderer is a simplified version of {@link CSS3DRenderer}. The only transformation that is
+ * supported is translation.
+ *
+ * The renderer is very useful if you want to combine HTML based labels with 3D objects. Here too,
+ * the respective DOM elements are wrapped into an instance of {@link CSS2DObject} and added to the
+ * scene graph. All other types of renderable 3D objects (like meshes or point clouds) are ignored.
+ *
+ * `CSS2DRenderer` only supports 100% browser and display zoom.
+ */
 class CSS2DRenderer {
 
+	/**
+	 * Constructs a new CSS2D renderer.
+	 *
+	 * @param {CSS2DRenderer~Parameters} [parameters] - The parameters.
+	 */
 	constructor( parameters = {} ) {
 
 		const _this = this;
@@ -80,8 +126,18 @@ class CSS2DRenderer {
 
 		domElement.style.overflow = 'hidden';
 
+		/**
+		 * The DOM where the renderer appends its child-elements.
+		 *
+		 * @type {DOMElement}
+		 */
 		this.domElement = domElement;
 
+		/**
+		 * Returns an object containing the width and height of the renderer.
+		 *
+		 * @return {{width:number,height:number}} The size of the renderer.
+		 */
 		this.getSize = function () {
 
 			return {
@@ -91,6 +147,12 @@ class CSS2DRenderer {
 
 		};
 
+		/**
+		 * Renders the given scene using the given camera.
+		 *
+		 * @param {Object3D} scene - A scene or any other type of 3D object.
+		 * @param {Camera} camera - The camera.
+		 */
 		this.render = function ( scene, camera ) {
 
 			if ( scene.matrixWorldAutoUpdate === true ) scene.updateMatrixWorld();
@@ -104,6 +166,12 @@ class CSS2DRenderer {
 
 		};
 
+		/**
+		 * Resizes the renderer to the given width and height.
+		 *
+		 * @param {number} width - The width of the renderer.
+		 * @param {number} height - The height of the renderer.
+		 */
 		this.setSize = function ( width, height ) {
 
 			_width = width;
@@ -235,4 +303,12 @@ class CSS2DRenderer {
 
 }
 
+/**
+ * Constructor parameters of `CSS2DRenderer`.
+ *
+ * @typedef {Object} CSS2DRenderer~Parameters
+ * @property {DOMElement} [element] - A DOM element where the renderer appends its child-elements.
+ * If not passed in here, a new div element will be created.
+ **/
+
 export { CSS2DObject, CSS2DRenderer };

package/examples/jsm/renderers/CSS3DRenderer.js

@@ -5,22 +5,44 @@ import {
 	Vector3
 } from 'three';
 
-/**
- * Based on http://www.emagix.net/academic/mscs-project/item/camera-sync-with-css3-and-webgl-threejs
- */
+// Based on http://www.emagix.net/academic/mscs-project/item/camera-sync-with-css3-and-webgl-threejs
 
 const _position = new Vector3();
 const _quaternion = new Quaternion();
 const _scale = new Vector3();
 
+/**
+ * The base 3D object that is supported by {@link CSS3DRenderer}.
+ *
+ * @augments Object3D
+ */
 class CSS3DObject extends Object3D {
 
+	/**
+	 * Constructs a new CSS3D object.
+	 *
+	 * @param {DOMElement} [element] - The DOM element.
+	 */
 	constructor( element = document.createElement( 'div' ) ) {
 
 		super();
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isCSS3DObject = true;
 
+		/**
+		 * The DOM element which defines the appearance of this 3D object.
+		 *
+		 * @type {DOMElement}
+		 * @readonly
+		 * @default true
+		 */
 		this.element = element;
 		this.element.style.position = 'absolute';
 		this.element.style.pointerEvents = 'auto';
@@ -59,14 +81,38 @@ class CSS3DObject extends Object3D {
 
 }
 
+/**
+ * A specialized version of {@link CSS3DObject} that represents
+ * DOM elements as sprites.
+ *
+ * @augments CSS3DObject
+ */
 class CSS3DSprite extends CSS3DObject {
 
+	/**
+	 * Constructs a new CSS3D sprite object.
+	 *
+	 * @param {DOMElement} [element] - The DOM element.
+	 */
 	constructor( element ) {
 
 		super( element );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isCSS3DSprite = true;
 
+		/**
+		 * The sprite's rotation in radians.
+		 *
+		 * @type {number}
+		 * @default 0
+		 */
 		this.rotation2D = 0;
 
 	}
@@ -88,8 +134,28 @@ class CSS3DSprite extends CSS3DObject {
 const _matrix = new Matrix4();
 const _matrix2 = new Matrix4();
 
+/**
+ * This renderer can be used to apply hierarchical 3D transformations to DOM elements
+ * via the CSS3 [transform]{@link https://www.w3schools.com/cssref/css3_pr_transform.asp} property.
+ * `CSS3DRenderer` is particularly interesting if you want to apply 3D effects to a website without
+ * canvas based rendering. It can also be used in order to combine DOM elements with WebGLcontent.
+ *
+ * There are, however, some important limitations:
+ *
+ * - It's not possible to use the material system of *three.js*.
+ * - It's also not possible to use geometries.
+ * - The renderer only supports 100% browser and display zoom.
+ *
+ * So `CSS3DRenderer` is just focused on ordinary DOM elements. These elements are wrapped into special
+ * 3D objects ({@link CSS3DObject} or {@link CSS3DSprite}) and then added to the scene graph.
+ */
 class CSS3DRenderer {
 
+	/**
+	 * Constructs a new CSS3D renderer.
+	 *
+	 * @param {CSS3DRenderer~Parameters} [parameters] - The parameters.
+	 */
 	constructor( parameters = {} ) {
 
 		const _this = this;
@@ -106,6 +172,11 @@ class CSS3DRenderer {
 
 		domElement.style.overflow = 'hidden';
 
+		/**
+		 * The DOM where the renderer appends its child-elements.
+		 *
+		 * @type {DOMElement}
+		 */
 		this.domElement = domElement;
 
 		const viewElement = document.createElement( 'div' );
@@ -119,6 +190,11 @@ class CSS3DRenderer {
 
 		viewElement.appendChild( cameraElement );
 
+		/**
+		 * Returns an object containing the width and height of the renderer.
+		 *
+		 * @return {{width:number,height:number}} The size of the renderer.
+		 */
 		this.getSize = function () {
 
 			return {
@@ -128,6 +204,12 @@ class CSS3DRenderer {
 
 		};
 
+		/**
+		 * Renders the given scene using the given camera.
+		 *
+		 * @param {Object3D} scene - A scene or any other type of 3D object.
+		 * @param {Camera} camera - The camera.
+		 */
 		this.render = function ( scene, camera ) {
 
 			const fov = camera.projectionMatrix.elements[ 5 ] * _heightHalf;
@@ -179,6 +261,12 @@ class CSS3DRenderer {
 
 		};
 
+		/**
+		 * Resizes the renderer to the given width and height.
+		 *
+		 * @param {number} width - The width of the renderer.
+		 * @param {number} height - The height of the renderer.
+		 */
 		this.setSize = function ( width, height ) {
 
 			_width = width;
@@ -350,4 +438,12 @@ class CSS3DRenderer {
 
 }
 
+/**
+ * Constructor parameters of `CSS3DRenderer`.
+ *
+ * @typedef {Object} CSS3DRenderer~Parameters
+ * @property {DOMElement} [element] - A DOM element where the renderer appends its child-elements.
+ * If not passed in here, a new div element will be created.
+ **/
+
 export { CSS3DObject, CSS3DSprite, CSS3DRenderer };

package/examples/jsm/renderers/Projector.js

@@ -120,10 +120,16 @@ class RenderableSprite {
 
 }
 
-//
-
+/**
+ * This class can project a given scene in 3D space into a 2D representation
+ * used for rendering with a 2D API. `Projector` is currently used by {@link SVGRenderer}
+ * and was previously used by the legacy `CanvasRenderer`.
+ */
 class Projector {
 
+	/**
+	 * Constructs a new projector.
+	 */
 	constructor() {
 
 		let _object, _objectCount, _objectPoolLength = 0,
@@ -403,6 +409,16 @@ class Projector {
 
 		}
 
+		/**
+		 * Projects the given scene in 3D space into a 2D representation. The result
+		 * is an object with renderable items.
+		 *
+		 * @param {Object3D} scene - A scene or any other type of 3D object.
+		 * @param {Camera} camera - The camera.
+		 * @param {boolean} sortObjects - Whether to sort objects or not.
+		 * @param {boolean} sortElements - Whether to sort elements (faces, lines and sprites) or not.
+		 * @return {{objects:Array<Objects>,lights:Array<Objects>,elements:Array<Objects>}} The projected scene as renderable objects.
+		 */
 		this.projectScene = function ( scene, camera, sortObjects, sortElements ) {
 
 			_faceCount = 0;