@plastic-software/three 0.174.0 → 0.175.0

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,16 @@ 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
- * };
+ * ```
  */
-
 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;
@@ -413,6 +379,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 +406,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 +457,15 @@ class OutlineEffect {
 
 		};
 
-		/*
-		 * See #9918
-		 *
-		 * The following property copies and wrapper methods enable
-		 * OutlineEffect to be called from other *Effect, like
-		 *
-		 * effect = new StereoEffect( new OutlineEffect( renderer ) );
-		 *
-		 * function render () {
+		/**
+		 * Resizes the effect.
 		 *
-	 	 * 	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 ) {
-
-			renderer.clear( color, depth, stencil );
+		this.setSize = function ( width, height ) {
 
-		};
-
-		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 +473,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,19 @@ 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}.
+ */
 class ParallaxBarrierEffect {
 
+	/**
+	 * Constructs a new parallax barrier effect.
+	 *
+	 * @param {WebGLRenderer} renderer - The renderer.
+	 */
 	constructor( renderer ) {
 
 		const _stereo = new StereoCamera();
@@ -72,6 +83,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 +100,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 +132,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/PeppersGhostEffect.js

@@ -5,11 +5,17 @@ import {
 } from 'three';
 
 /**
- * peppers ghost effect based on http://www.instructables.com/id/Reflective-Prism/?ALLSTEPS
+ * A class that implements a peppers ghost effect.
+ *
+ * Reference: [Reflective Prism]{@link http://www.instructables.com/id/Reflective-Prism/?ALLSTEPS}
  */
-
 class PeppersGhostEffect {
 
+	/**
+	 * Constructs a new peppers ghost effect.
+	 *
+	 * @param {(WebGPURenderer|WebGLRenderer)} renderer - The renderer.
+	 */
 	constructor( renderer ) {
 
 		const scope = this;
@@ -32,6 +38,12 @@ class PeppersGhostEffect {
 		// Initialization
 		renderer.autoClear = false;
 
+		/**
+		 * 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 ) {
 
 			_halfWidth = width / 2;
@@ -51,6 +63,13 @@ class PeppersGhostEffect {
 
 		};
 
+		/**
+		 * 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/effects/StereoEffect.js

@@ -3,26 +3,55 @@ 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}.
+ */
 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/DebugEnvironment.js

@@ -8,8 +8,30 @@ 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
+ */
 class DebugEnvironment extends Scene {
 
+	/**
+	 * Constructs a new debug environment.
+	 */
 	constructor() {
 
 		super();
@@ -47,6 +69,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 };

package/examples/jsm/environments/RoomEnvironment.js

@@ -1,7 +1,3 @@
-/**
- * https://github.com/google/model-viewer/blob/master/packages/model-viewer/src/three-components/EnvironmentScene.ts
- */
-
 import {
  	BackSide,
  	BoxGeometry,
@@ -12,6 +8,25 @@ import {
  	Scene,
 } from 'three';
 
+/**
+ * This class represents a scene with a 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.
+ *
+ * The implementation is based on the [EnvironmentScene](https://github.com/google/model-viewer/blob/master/packages/model-viewer/src/three-components/EnvironmentScene.ts)
+ * component from the `model-viewer` project.
+ *
+ * ```js
+ * const environment = new RoomEnvironment();
+ * const pmremGenerator = new THREE.PMREMGenerator( renderer );
+ *
+ * const envMap = pmremGenerator.fromScene( environment ).texture;
+ * scene.environment = envMap;
+ * ```
+ *
+ * @augments Scene
+ */
 class RoomEnvironment extends Scene {
 
 	constructor() {
@@ -108,6 +123,10 @@ class RoomEnvironment extends Scene {
 
 	}
 
+	/**
+	 * Frees internal resources. This method should be called
+	 * when the environment is no longer required.
+	 */
 	dispose() {
 
 		const resources = new Set();

package/examples/jsm/exporters/DRACOExporter.js

@@ -1,24 +1,34 @@
 import { Color, ColorManagement, SRGBColorSpace } from 'three';
 
+/* global DracoEncoderModule */
+
 /**
- * Export draco compressed files from threejs geometry objects.
+ * An exporter to compress geometry with the Draco library.
  *
- * Draco files are compressed and usually are smaller than conventional 3D file formats.
+ * [Draco]{@link https://google.github.io/draco/} is an open source library for compressing and
+ * decompressing 3D meshes and point clouds. Compressed geometry can be significantly smaller,
+ * at the cost of additional decoding time on the client device.
  *
- * The exporter receives a options object containing
- *  - decodeSpeed, indicates how to tune the encoder regarding decode speed (0 gives better speed but worst quality)
- *  - encodeSpeed, indicates how to tune the encoder parameters (0 gives better speed but worst quality)
- *  - encoderMethod
- *  - quantization, indicates the presision of each type of data stored in the draco file in the order (POSITION, NORMAL, COLOR, TEX_COORD, GENERIC)
- *  - exportUvs
- *  - exportNormals
- *  - exportColor
+ * Standalone Draco files have a `.drc` extension, and contain vertex positions,
+ * normals, colors, and other attributes. Draco files *do not* contain materials,
+ * textures, animation, or node hierarchies – to use these features, embed Draco geometry
+ * inside of a glTF file. A normal glTF file can be converted to a Draco-compressed glTF file
+ * using [glTF-Pipeline]{@link https://github.com/AnalyticalGraphicsInc/gltf-pipeline}.
+ *
+ * ```js
+ * const exporter = new DRACOExporter();
+ * const data = exporter.parse( mesh, options );
+ * ```
  */
-
-/* global DracoEncoderModule */
-
 class DRACOExporter {
 
+	/**
+	 * Parses the given mesh or point cloud and generates the Draco output.
+	 *
+	 * @param {(Mesh|Points)} object - The mesh or point cloud to export.
+	 * @param {DRACOExporter~Options} options - The export options.
+	 * @return {ArrayBuffer} The exported Draco.
+	 */
 	parse( object, options = {} ) {
 
 		options = Object.assign( {
@@ -249,7 +259,24 @@ function createVertexColorSRGBArray( attribute ) {
 
 // Encoder methods
 
+/**
+ * Edgebreaker encoding.
+ *
+ * @static
+ * @constant
+ * @type {number}
+ * @default 1
+ */
 DRACOExporter.MESH_EDGEBREAKER_ENCODING = 1;
+
+/**
+ * Sequential encoding.
+ *
+ * @static
+ * @constant
+ * @type {number}
+ * @default 0
+ */
 DRACOExporter.MESH_SEQUENTIAL_ENCODING = 0;
 
 // Geometry type
@@ -266,4 +293,17 @@ DRACOExporter.COLOR = 2;
 DRACOExporter.TEX_COORD = 3;
 DRACOExporter.GENERIC = 4;
 
+/**
+ * Export options of `DRACOExporter`.
+ *
+ * @typedef {Object} DRACOExporter~Options
+ * @property {number} [decodeSpeed=5] - Indicates how to tune the encoder regarding decode speed (0 gives better speed but worst quality).
+ * @property {number} [encodeSpeed=5] - Indicates how to tune the encoder parameters (0 gives better speed but worst quality).
+ * @property {number} [encoderMethod=1] - Either sequential (very little compression) or Edgebreaker. Edgebreaker traverses the triangles of the mesh in a deterministic, spiral-like way which provides most of the benefits of this data format.
+ * @property {Array<number>} [quantization=[ 16, 8, 8, 8, 8 ]] - Indicates the precision of each type of data stored in the draco file in the order (POSITION, NORMAL, COLOR, TEX_COORD, GENERIC).
+ * @property {boolean} [exportUvs=true] - Whether to export UVs or not.
+ * @property {boolean} [exportNormals=true] - Whether to export normals or not.
+ * @property {boolean} [exportColor=false] - Whether to export colors or not.
+ **/
+
 export { DRACOExporter };

package/examples/jsm/exporters/EXRExporter.js

@@ -1,10 +1,3 @@
-/**
- * @author sciecode / https://github.com/sciecode
- *
- * EXR format references:
- * 	https://www.openexr.com/documentation/openexrfilelayout.pdf
- */
-
 import {
 	FloatType,
 	HalfFloatType,
@@ -19,13 +12,41 @@ const NO_COMPRESSION = 0;
 const ZIPS_COMPRESSION = 2;
 const ZIP_COMPRESSION = 3;
 
+/**
+ * An exporter for EXR.
+ *
+ * EXR ( Extended Dynamic Range) is an [open format specification]{@link https://github.com/AcademySoftwareFoundation/openexr}
+ * for professional-grade image storage format of the motion picture industry. The purpose of
+ * format is to accurately and efficiently represent high-dynamic-range scene-linear image data
+ * and associated metadata. The library is widely used in host application software where accuracy
+ * is critical, such as photorealistic rendering, texture access, image compositing, deep compositing,
+ * and DI.
+ *
+ * ```js
+ * const exporter = new EXRExporter();
+ * const result = await exporter.parse( renderer, options );
+ * ```
+ */
 class EXRExporter {
 
+	/**
+	 * This method has two variants.
+	 *
+	 * - When exporting a data texture, it receives two parameters. The texture and the exporter options.
+	 * - When exporting a render target (e.g. a PMREM), it receives three parameters. The renderer, the
+	 * render target and the exporter options.
+	 *
+	 * @async
+	 * @param {(DataTexture|WebGPURenderer|WebGLRenderer)} arg1 - The data texture to export or a renderer.
+	 * @param {(EXRExporter~Options|RenderTarget)} arg2 - The exporter options or a render target.
+	 * @param {EXRExporter~Options} [arg3] - The exporter options.
+	 * @return {Promise<Uint8Array>} A Promise that resolves with the exported EXR.
+	 */
 	async parse( arg1, arg2, arg3 ) {
 
 		if ( ! arg1 || ! ( arg1.isWebGLRenderer || arg1.isWebGPURenderer || arg1.isDataTexture ) ) {
 
-			throw Error( 'EXRExporter.parse: Unsupported first parameter, expected instance of WebGLRenderer or DataTexture.' );
+			throw Error( 'EXRExporter.parse: Unsupported first parameter, expected instance of WebGLRenderer, WebGPURenderer or DataTexture.' );
 
 		} else if ( arg1.isWebGLRenderer || arg1.isWebGPURenderer ) {
 
@@ -584,4 +605,12 @@ function getFloat32( arr, i ) {
 
 }
 
+/**
+ * Export options of `EXRExporter`.
+ *
+ * @typedef {Object} EXRExporter~Options
+ * @property {(HalfFloatType|FloatType)} [type=HalfFloatType] - Output data type.
+ * @property {(NO_COMPRESSION|ZIP_COMPRESSION|ZIPS_COMPRESSION)} [type=ZIP_COMPRESSION] - The compression algorithm.
+ **/
+
 export { EXRExporter, NO_COMPRESSION, ZIP_COMPRESSION, ZIPS_COMPRESSION };