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

package/examples/jsm/effects/AsciiEffect.js

@@ -1,25 +1,33 @@
 /**
- * Ascii generation is based on https://github.com/hassadee/jsascii/blob/master/jsascii.js
+ * A class that creates an ASCII effect.
  *
- * 16 April 2012 - @blurspline
+ * The ASCII generation is based on [jsascii](https://github.com/hassadee/jsascii/blob/master/jsascii.js).
+ *
+ * @three_import import { AsciiEffect } from 'three/addons/effects/AsciiEffect.js';
  */
-
 class AsciiEffect {
 
+	/**
+	 * Constructs a new ASCII effect.
+	 *
+	 * @param {WebGLRenderer} renderer - The renderer.
+	 * @param {string} [charSet=' .:-=+*#%@'] - The char set.
+	 * @param {AsciiEffect~Options} [options] - The configuration parameter.
+	 */
 	constructor( renderer, charSet = ' .:-=+*#%@', options = {} ) {
 
 		// ' .,:;=|iI+hHOE#`$';
 		// darker bolder character set from https://github.com/saw/Canvas-ASCII-Art/
-		// ' .\'`^",:;Il!i~+_-?][}{1)(|/tfjrxnuvczXYUJCLQ0OZmwqpdbkhao*#MW&8%B@$'.split('');
+		// ' .\'`^",:;Il!i~+_-?][}{1)(|/tfjrxnuvczXYUJCLQ0OZmwqpdbkhao*#MW&8%B@$'
 
 		// Some ASCII settings
 
-		const fResolution = options[ 'resolution' ] || 0.15; // Higher for more details
+		const fResolution = options[ 'resolution' ] || 0.15;
 		const iScale = options[ 'scale' ] || 1;
-		const bColor = options[ 'color' ] || false; // nice but slows down rendering!
-		const bAlpha = options[ 'alpha' ] || false; // Transparency
-		const bBlock = options[ 'block' ] || false; // blocked characters. like good O dos
-		const bInvert = options[ 'invert' ] || false; // black is white, white is black
+		const bColor = options[ 'color' ] || false;
+		const bAlpha = options[ 'alpha' ] || false;
+		const bBlock = options[ 'block' ] || false;
+		const bInvert = options[ 'invert' ] || false;
 		const strResolution = options[ 'strResolution' ] || 'low';
 
 		let width, height;
@@ -33,6 +41,12 @@ class AsciiEffect {
 		let iWidth, iHeight;
 		let oImg;
 
+		/**
+		 * Resizes the effect.
+		 *
+		 * @param {number} w - The width of the effect in logical pixels.
+		 * @param {number} h - The height of the effect in logical pixels.
+		 */
 		this.setSize = function ( w, h ) {
 
 			width = w;
@@ -44,7 +58,13 @@ class AsciiEffect {
 
 		};
 
-
+		/**
+		 * When using this effect, this method should be called instead of the
+		 * default {@link WebGLRenderer#render}.
+		 *
+		 * @param {Object3D} scene - The scene to render.
+		 * @param {Camera} camera - The camera.
+		 */
 		this.render = function ( scene, camera ) {
 
 			renderer.render( scene, camera );
@@ -52,6 +72,12 @@ class AsciiEffect {
 
 		};
 
+		/**
+		 * The DOM element of the effect. This element must be used instead of the
+		 * default {@link WebGLRenderer#domElement}.
+		 *
+		 * @type {HTMLDivElement}
+		 */
 		this.domElement = domElement;
 
 
@@ -77,8 +103,8 @@ class AsciiEffect {
 
 			}
 
-			oAscii.cellSpacing = 0;
-			oAscii.cellPadding = 0;
+			oAscii.cellSpacing = '0';
+			oAscii.cellPadding = '0';
 
 			const oStyle = oAscii.style;
 			oStyle.whiteSpace = 'pre';
@@ -94,8 +120,6 @@ class AsciiEffect {
 		}
 
 
-		const aDefaultCharList = ( ' .,:;i1tfLCG08@' ).split( '' );
-		const aDefaultColorCharList = ( ' CGO08@' ).split( '' );
 		const strFont = 'courier new, monospace';
 
 		const oCanvasImg = renderer.domElement;
@@ -114,9 +138,19 @@ class AsciiEffect {
 
 		}
 
-		let aCharList = ( bColor ? aDefaultColorCharList : aDefaultCharList );
+		let aCharList;
+		if ( charSet ) {
+
+			aCharList = ( charSet ).split( '' );
+
+		} else {
+
+			const aDefaultCharList = ( ' .,:;i1tfLCG08@' ).split( '' );
+			const aDefaultColorCharList = ( ' CGO08@' ).split( '' );
+			aCharList = ( bColor ? aDefaultColorCharList : aDefaultCharList );
+
+		}
 
-		if ( charSet ) aCharList = charSet;
 
 		// Setup dom
 
@@ -184,6 +218,8 @@ class AsciiEffect {
 			// Coloring loop starts now
 			let strChars = '';
 
+			const maxIdx = aCharList.length - 1;
+
 			// console.time('rendering');
 
 			for ( let y = 0; y < iHeight; y += 2 ) {
@@ -196,13 +232,11 @@ class AsciiEffect {
 					const iGreen = oImgData[ iOffset + 1 ];
 					const iBlue = oImgData[ iOffset + 2 ];
 					const iAlpha = oImgData[ iOffset + 3 ];
-					let iCharIdx;
 
-					let fBrightness;
-
-					fBrightness = ( 0.3 * iRed + 0.59 * iGreen + 0.11 * iBlue ) / 255;
+					let fBrightness = ( 0.3 * iRed + 0.59 * iGreen + 0.11 * iBlue ) / 255;
 					// fBrightness = (0.3*iRed + 0.5*iGreen + 0.3*iBlue) / 255;
 
+
 					if ( iAlpha == 0 ) {
 
 						// should calculate alpha instead, but quick hack :)
@@ -211,11 +245,11 @@ class AsciiEffect {
 
 					}
 
-					iCharIdx = Math.floor( ( 1 - fBrightness ) * ( aCharList.length - 1 ) );
+					let iCharIdx = Math.round( ( 1 - fBrightness ) * maxIdx );
 
 					if ( bInvert ) {
 
-						iCharIdx = aCharList.length - iCharIdx - 1;
+						iCharIdx = maxIdx - iCharIdx;
 
 					}
 
@@ -260,4 +294,17 @@ class AsciiEffect {
 
 }
 
+/**
+ * This type represents configuration settings of `AsciiEffect`.
+ *
+ * @typedef {Object} AsciiEffect~Options
+ * @property {number} [resolution=0.15] - A higher value leads to more details.
+ * @property {number} [scale=1] - The scale of the effect.
+ * @property {boolean} [color=false] - Whether colors should be enabled or not. Better quality but slows down rendering.
+ * @property {boolean} [alpha=false] - Whether transparency should be enabled or not.
+ * @property {boolean} [block=false] - Whether blocked characters should be enabled or not.
+ * @property {boolean} [invert=false] - Whether colors should be inverted or not.
+ * @property {('low'|'medium'|'high')} [strResolution='low'] - The string resolution.
+ **/
+
 export { AsciiEffect };

package/examples/jsm/effects/OutlineEffect.js

@@ -7,12 +7,12 @@ import {
 } from 'three';
 
 /**
- * Reference: https://en.wikipedia.org/wiki/Cel_shading
+ * An outline effect for toon shaders.
  *
- * API
- *
- * 1. Traditional
+ * Note that this class can only be used with {@link WebGLRenderer}.
+ * When using {@link WebGPURenderer}, use {@link ToonOutlinePassNode}.
  *
+ * ```js
  * const effect = new OutlineEffect( renderer );
  *
  * function render() {
@@ -20,50 +20,18 @@ import {
  * 	effect.render( scene, camera );
  *
  * }
+ * ```
  *
- * 2. VR compatible
- *
- * const effect = new OutlineEffect( renderer );
- * let renderingOutline = false;
- *
- * scene.onAfterRender = function () {
- *
- * 	if ( renderingOutline ) return;
- *
- * 	renderingOutline = true;
- *
- * 	effect.renderOutline( scene, camera );
- *
- * 	renderingOutline = false;
- *
- * };
- *
- * function render() {
- *
- * 	renderer.render( scene, camera );
- *
- * }
- *
- * // How to set default outline parameters
- * new OutlineEffect( renderer, {
- * 	defaultThickness: 0.01,
- * 	defaultColor: [ 0, 0, 0 ],
- * 	defaultAlpha: 0.8,
- * 	defaultKeepAlive: true // keeps outline material in cache even if material is removed from scene
- * } );
- *
- * // How to set outline parameters for each material
- * material.userData.outlineParameters = {
- * 	thickness: 0.01,
- * 	color: [ 0, 0, 0 ],
- * 	alpha: 0.8,
- * 	visible: true,
- * 	keepAlive: true
- * };
+ * @three_import import { OutlineEffect } from 'three/addons/effects/OutlineEffect.js';
  */
-
 class OutlineEffect {
 
+	/**
+	 * Constructs a new outline effect.
+	 *
+	 * @param {WebGLRenderer} renderer - The renderer.
+	 * @param {OutlineEffect~Options} [parameters] - The configuration parameter.
+	 */
 	constructor( renderer, parameters = {} ) {
 
 		this.enabled = true;
@@ -367,7 +335,7 @@ class OutlineEffect {
 
 			let keys;
 
-			// clear originialMaterials
+			// clear originalMaterials
 			keys = Object.keys( originalMaterials );
 
 			for ( let i = 0, il = keys.length; i < il; i ++ ) {
@@ -413,6 +381,13 @@ class OutlineEffect {
 
 		}
 
+		/**
+		 * When using this effect, this method should be called instead of the
+		 * default {@link WebGLRenderer#render}.
+		 *
+		 * @param {Object3D} scene - The scene to render.
+		 * @param {Camera} camera - The camera.
+		 */
 		this.render = function ( scene, camera ) {
 
 			if ( this.enabled === false ) {
@@ -433,6 +408,30 @@ class OutlineEffect {
 
 		};
 
+		/**
+		 * This method can be used to render outlines in VR.
+		 *
+		 * ```js
+		 * const effect = new OutlineEffect( renderer );
+		 * let renderingOutline = false;
+		 *
+		 * scene.onAfterRender = function () {
+		 *
+		 * 	if ( renderingOutline ) return;
+		 *
+		 * 	renderingOutline = true;
+		 * 	effect.renderOutline( scene, camera );
+		 * 	renderingOutline = false;
+		 * };
+		 *
+		 * function render() {
+		 * 	renderer.render( scene, camera );
+		 * }
+		 * ```
+		 *
+		 * @param {Object3D} scene - The scene to render.
+		 * @param {Camera} camera - The camera.
+		 */
 		this.renderOutline = function ( scene, camera ) {
 
 			const currentAutoClear = renderer.autoClear;
@@ -460,75 +459,15 @@ class OutlineEffect {
 
 		};
 
-		/*
-		 * See #9918
+		/**
+		 * Resizes the effect.
 		 *
-		 * The following property copies and wrapper methods enable
-		 * OutlineEffect to be called from other *Effect, like
-		 *
-		 * effect = new StereoEffect( new OutlineEffect( renderer ) );
-		 *
-		 * function render () {
-		 *
-	 	 * 	effect.render( scene, camera );
-		 *
-		 * }
+		 * @param {number} width - The width of the effect in logical pixels.
+		 * @param {number} height - The height of the effect in logical pixels.
 		 */
-		this.autoClear = renderer.autoClear;
-		this.domElement = renderer.domElement;
-		this.shadowMap = renderer.shadowMap;
-
-		this.clear = function ( color, depth, stencil ) {
+		this.setSize = function ( width, height ) {
 
-			renderer.clear( color, depth, stencil );
-
-		};
-
-		this.getPixelRatio = function () {
-
-			return renderer.getPixelRatio();
-
-		};
-
-		this.setPixelRatio = function ( value ) {
-
-			renderer.setPixelRatio( value );
-
-		};
-
-		this.getSize = function ( target ) {
-
-			return renderer.getSize( target );
-
-		};
-
-		this.setSize = function ( width, height, updateStyle ) {
-
-			renderer.setSize( width, height, updateStyle );
-
-		};
-
-		this.setViewport = function ( x, y, width, height ) {
-
-			renderer.setViewport( x, y, width, height );
-
-		};
-
-		this.setScissor = function ( x, y, width, height ) {
-
-			renderer.setScissor( x, y, width, height );
-
-		};
-
-		this.setScissorTest = function ( boolean ) {
-
-			renderer.setScissorTest( boolean );
-
-		};
-
-		this.setRenderTarget = function ( renderTarget ) {
-
-			renderer.setRenderTarget( renderTarget );
+			renderer.setSize( width, height );
 
 		};
 
@@ -536,4 +475,15 @@ class OutlineEffect {
 
 }
 
+/**
+ * This type represents configuration settings of `OutlineEffect`.
+ *
+ * @typedef {Object} OutlineEffect~Options
+ * @property {number} [defaultThickness=0.003] - The outline thickness.
+ * @property {Array<number>} [defaultColor=[0,0,0]] - The outline color.
+ * @property {number} [defaultAlpha=1] - The outline alpha value.
+ * @property {boolean} [defaultKeepAlive=false] - Whether to keep alive cached internal materials or not.
+ **/
+
+
 export { OutlineEffect };

package/examples/jsm/effects/ParallaxBarrierEffect.js

@@ -8,8 +8,21 @@ import {
 } from 'three';
 import { FullScreenQuad } from '../postprocessing/Pass.js';
 
+/**
+ * A class that creates an parallax barrier effect.
+ *
+ * Note that this class can only be used with {@link WebGLRenderer}.
+ * When using {@link WebGPURenderer}, use {@link ParallaxBarrierPassNode}.
+ *
+ * @three_import import { ParallaxBarrierEffect } from 'three/addons/effects/ParallaxBarrierEffect.js';
+ */
 class ParallaxBarrierEffect {
 
+	/**
+	 * Constructs a new parallax barrier effect.
+	 *
+	 * @param {WebGLRenderer} renderer - The renderer.
+	 */
 	constructor( renderer ) {
 
 		const _stereo = new StereoCamera();
@@ -72,6 +85,12 @@ class ParallaxBarrierEffect {
 
 		const _quad = new FullScreenQuad( _material );
 
+		/**
+		 * Resizes the effect.
+		 *
+		 * @param {number} width - The width of the effect in logical pixels.
+		 * @param {number} height - The height of the effect in logical pixels.
+		 */
 		this.setSize = function ( width, height ) {
 
 			renderer.setSize( width, height );
@@ -83,6 +102,13 @@ class ParallaxBarrierEffect {
 
 		};
 
+		/**
+		 * When using this effect, this method should be called instead of the
+		 * default {@link WebGLRenderer#render}.
+		 *
+		 * @param {Object3D} scene - The scene to render.
+		 * @param {Camera} camera - The camera.
+		 */
 		this.render = function ( scene, camera ) {
 
 			const currentRenderTarget = renderer.getRenderTarget();
@@ -108,6 +134,10 @@ class ParallaxBarrierEffect {
 
 		};
 
+		/**
+		 * Frees internal resources. This method should be called
+		 * when the effect is no longer required.
+		 */
 		this.dispose = function () {
 
 			_renderTargetL.dispose();

package/examples/jsm/effects/StereoEffect.js

@@ -3,26 +3,57 @@ import {
 	Vector2
 } from 'three';
 
+/**
+ * A class that creates an stereo effect.
+ *
+ * Note that this class can only be used with {@link WebGLRenderer}.
+ * When using {@link WebGPURenderer}, use {@link StereoPassNode}.
+ *
+ * @three_import import { StereoEffect } from 'three/addons/effects/StereoEffect.js';
+ */
 class StereoEffect {
 
+	/**
+	 * Constructs a new stereo effect.
+	 *
+	 * @param {WebGLRenderer} renderer - The renderer.
+	 */
 	constructor( renderer ) {
 
 		const _stereo = new StereoCamera();
 		_stereo.aspect = 0.5;
 		const size = new Vector2();
 
+		/**
+		 * Sets the given eye separation.
+		 *
+		 * @param {number} eyeSep - The eye separation to set.
+		 */
 		this.setEyeSeparation = function ( eyeSep ) {
 
 			_stereo.eyeSep = eyeSep;
 
 		};
 
+		/**
+		 * Resizes the effect.
+		 *
+		 * @param {number} width - The width of the effect in logical pixels.
+		 * @param {number} height - The height of the effect in logical pixels.
+		 */
 		this.setSize = function ( width, height ) {
 
 			renderer.setSize( width, height );
 
 		};
 
+		/**
+		 * When using this effect, this method should be called instead of the
+		 * default {@link WebGLRenderer#render}.
+		 *
+		 * @param {Object3D} scene - The scene to render.
+		 * @param {Camera} camera - The camera.
+		 */
 		this.render = function ( scene, camera ) {
 
 			if ( scene.matrixWorldAutoUpdate === true ) scene.updateMatrixWorld();

package/examples/jsm/environments/ColorEnvironment.js

@@ -0,0 +1,59 @@
+import {
+	BackSide,
+	Mesh,
+	MeshBasicMaterial,
+	SphereGeometry,
+	Scene
+} from 'three';
+
+/**
+ * This class represents a scene with a uniform color that can be used as
+ * input for {@link PMREMGenerator#fromScene}. The resulting PMREM represents
+ * uniform ambient lighting and can be used for Image Based Lighting by
+ * assigning it to {@link Scene#environment}.
+ *
+ * ```js
+ * const environment = new ColorEnvironment( 0x00ff00 );
+ * const pmremGenerator = new THREE.PMREMGenerator( renderer );
+ *
+ * const envMap = pmremGenerator.fromScene( environment ).texture;
+ * scene.environment = envMap;
+ * ```
+ *
+ * @augments Scene
+ * @three_import import { ColorEnvironment } from 'three/addons/environments/ColorEnvironment.js';
+ */
+class ColorEnvironment extends Scene {
+
+	/**
+	 * Constructs a new color environment.
+	 *
+	 * @param {number|Color} color - The color of the environment.
+	 */
+	constructor( color = 0xffffff ) {
+
+		super();
+
+		this.name = 'ColorEnvironment';
+
+		const geometry = new SphereGeometry( 1, 16, 16 );
+		const material = new MeshBasicMaterial( { color: color, side: BackSide } );
+
+		this.add( new Mesh( geometry, material ) );
+
+	}
+
+	/**
+	 * Frees internal resources. This method should be called
+	 * when the environment is no longer required.
+	 */
+	dispose() {
+
+		this.children[ 0 ].geometry.dispose();
+		this.children[ 0 ].material.dispose();
+
+	}
+
+}
+
+export { ColorEnvironment };

package/examples/jsm/environments/DebugEnvironment.js

@@ -8,8 +8,31 @@ import {
 	Scene,
 } from 'three';
 
+/**
+ * This class represents a scene with a very basic room setup that can be used as
+ * input for {@link PMREMGenerator#fromScene}. The resulting PMREM represents the room's
+ * lighting and can be used for Image Based Lighting by assigning it to {@link Scene#environment}
+ * or directly as an environment map to PBR materials.
+ *
+ * This class uses a simple room setup and should only be used for development purposes.
+ * A more appropriate setup for production is {@link RoomEnvironment}.
+ *
+ * ```js
+ * const environment = new DebugEnvironment();
+ * const pmremGenerator = new THREE.PMREMGenerator( renderer );
+ *
+ * const envMap = pmremGenerator.fromScene( environment ).texture;
+ * scene.environment = envMap;
+ * ```
+ *
+ * @augments Scene
+ * @three_import import { DebugEnvironment } from 'three/addons/environments/DebugEnvironment.js';
+ */
 class DebugEnvironment extends Scene {
 
+	/**
+	 * Constructs a new debug environment.
+	 */
 	constructor() {
 
 		super();
@@ -47,6 +70,33 @@ class DebugEnvironment extends Scene {
 
 	}
 
+	/**
+	 * Frees internal resources. This method should be called
+	 * when the environment is no longer required.
+	 */
+	dispose() {
+
+		const resources = new Set();
+
+		this.traverse( ( object ) => {
+
+			if ( object.isMesh ) {
+
+				resources.add( object.geometry );
+				resources.add( object.material );
+
+			}
+
+		} );
+
+		for ( const resource of resources ) {
+
+			resource.dispose();
+
+		}
+
+	}
+
 }
 
 export { DebugEnvironment };