@plastic-software/three 0.174.0 → 0.175.1

package/examples/jsm/objects/MarchingCubes.js

@@ -9,17 +9,34 @@ import {
 } from 'three';
 
 /**
- * Port of http://webglsamples.org/blob/blob.html
+ * A marching cubes implementation.
+ *
+ * Port of: {@link http://webglsamples.org/blob/blob.html}
  */
-
 class MarchingCubes extends Mesh {
 
+	/**
+	 * Constructs a new marching cubes instance.
+	 *
+	 * @param {number} resolution - The effect's resolution.
+	 * @param {Material} material - The cube's material.
+	 * @param {boolean} [enableUvs=false] - Whether texture coordinates should be animated or not.
+	 * @param {boolean} [enableColors=false] - Whether colors should be animated or not.
+	 * @param {number} [maxPolyCount=10000] - The maximum size of the geometry buffers.
+	 */
 	constructor( resolution, material, enableUvs = false, enableColors = false, maxPolyCount = 10000 ) {
 
 		const geometry = new BufferGeometry();
 
 		super( geometry, material );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isMarchingCubes = true;
 
 		const scope = this;
@@ -30,7 +47,20 @@ class MarchingCubes extends Mesh {
 		const nlist = new Float32Array( 12 * 3 );
 		const clist = new Float32Array( 12 * 3 );
 
+		/**
+		 * Whether texture coordinates should be animated or not.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.enableUvs = enableUvs;
+
+		/**
+		 * Whether colors should be animated or not.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.enableColors = enableColors;
 
 		// functions have to be object properties
@@ -495,9 +525,17 @@ class MarchingCubes extends Mesh {
 		// Metaballs
 		/////////////////////////////////////
 
-		// Adds a reciprocal ball (nice and blobby) that, to be fast, fades to zero after
-		// a fixed distance, determined by strength and subtract.
-
+		/**
+		 * Adds a reciprocal ball (nice and blobby) that, to be fast, fades to zero after
+		 * a fixed distance, determined by strength and subtract.
+		 *
+		 * @param {number} ballx - The x-coordinate of the ball.
+		 * @param {number} bally - The y-coordinate of the ball.
+		 * @param {number} ballz - The z-coordinate of the ball.
+		 * @param {number} strength - The strength factor.
+		 * @param {number} subtract - The subtract factor.
+		 * @param {Color} colors - The color.
+		 */
 		this.addBall = function ( ballx, bally, ballz, strength, subtract, colors ) {
 
 			const sign = Math.sign( strength );
@@ -598,6 +636,12 @@ class MarchingCubes extends Mesh {
 
 		};
 
+		/**
+		 * Adds a plane along the x-axis.
+		 *
+		 * @param {number} strength - The strength factor.
+		 * @param {number} subtract - The subtract factor.
+		 */
 		this.addPlaneX = function ( strength, subtract ) {
 
 			// cache attribute lookups
@@ -643,6 +687,12 @@ class MarchingCubes extends Mesh {
 
 		};
 
+		/**
+		 * Adds a plane along the y-axis.
+		 *
+		 * @param {number} strength - The strength factor.
+		 * @param {number} subtract - The subtract factor.
+		 */
 		this.addPlaneY = function ( strength, subtract ) {
 
 			// cache attribute lookups
@@ -687,6 +737,12 @@ class MarchingCubes extends Mesh {
 
 		};
 
+		/**
+		 * Adds a plane along the z-axis.
+		 *
+		 * @param {number} strength - The strength factor.
+		 * @param {number} subtract - The subtract factor.
+		 */
 		this.addPlaneZ = function ( strength, subtract ) {
 
 			// cache attribute lookups
@@ -735,6 +791,14 @@ class MarchingCubes extends Mesh {
 		// Updates
 		/////////////////////////////////////
 
+		/**
+		 * Sets the cell value for the given coordinates.
+		 *
+		 * @param {number} x - The x value.
+		 * @param {number} y - The y value.
+		 * @param {number} z - The z value.
+		 * @param {number} value - The value to set.
+		 */
 		this.setCell = function ( x, y, z, value ) {
 
 			const index = this.size2 * z + this.size * y + x;
@@ -742,6 +806,14 @@ class MarchingCubes extends Mesh {
 
 		};
 
+		/**
+		 * Returns the cell value for the given coordinates.
+		 *
+		 * @param {number} x - The x value.
+		 * @param {number} y - The y value.
+		 * @param {number} z - The z value.
+		 * @return {number} The value.
+		 */
 		this.getCell = function ( x, y, z ) {
 
 			const index = this.size2 * z + this.size * y + x;
@@ -749,6 +821,11 @@ class MarchingCubes extends Mesh {
 
 		};
 
+		/**
+		 * Applies a blur with the given intensity.
+		 *
+		 * @param {number} [intensity=1] - The intensity of the blur.
+		 */
 		this.blur = function ( intensity = 1 ) {
 
 			const field = this.field;
@@ -802,6 +879,9 @@ class MarchingCubes extends Mesh {
 
 		};
 
+		/**
+		 * Resets the effect.
+		 */
 		this.reset = function () {
 
 			// wipe the normal cache
@@ -818,6 +898,9 @@ class MarchingCubes extends Mesh {
 
 		};
 
+		/**
+		 * Updates the effect.
+		 */
 		this.update = function () {
 
 			this.count = 0;

package/examples/jsm/objects/Reflector.js

@@ -12,16 +12,65 @@ import {
 	HalfFloatType
 } from 'three';
 
+/**
+ * Can be used to create a flat, reflective surface like a mirror.
+ *
+ * Note that this class can only be used with {@link WebGLRenderer}.
+ * When using {@link WebGPURenderer}, use {@link ReflectorNode}.
+ *
+ * ```js
+ * const geometry = new THREE.PlaneGeometry( 100, 100 );
+ *
+ * const reflector = new Reflector( geometry, {
+ * 	clipBias: 0.003,
+ * 	textureWidth: window.innerWidth * window.devicePixelRatio,
+ * 	textureHeight: window.innerHeight * window.devicePixelRatio,
+ * 	color: 0xc1cbcb
+ * } );
+ *
+ * scene.add( reflector );
+ * ```
+ *
+ * @augments Mesh
+ */
 class Reflector extends Mesh {
 
+	/**
+	 * Constructs a new reflector.
+	 *
+	 * @param {BufferGeometry} geometry - The reflector's geometry.
+	 * @param {Reflector~Options} [options] - The configuration options.
+	 */
 	constructor( geometry, options = {} ) {
 
 		super( geometry );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isReflector = true;
 
 		this.type = 'Reflector';
+
+		/**
+		 * Whether to force an update, no matter if the reflector
+		 * is in view or not.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.forceUpdate = false;
+
+		/**
+		 * The reflector's virtual camera. This is used to render
+		 * the scene from the mirror's point of view.
+		 *
+		 * @type {PerspectiveCamera}
+		 */
 		this.camera = new PerspectiveCamera();
 
 		const scope = this;
@@ -178,12 +227,21 @@ class Reflector extends Mesh {
 
 		};
 
+		/**
+		 * Returns the reflector's internal render target.
+		 *
+		 * @return {WebGLRenderTarget} The internal render target
+		 */
 		this.getRenderTarget = function () {
 
 			return renderTarget;
 
 		};
 
+		/**
+		 * Frees the GPU-related resources allocated by this instance. Call this
+		 * method whenever this instance is no longer used in your app.
+		 */
 		this.dispose = function () {
 
 			renderTarget.dispose();
@@ -264,4 +322,16 @@ Reflector.ReflectorShader = {
 		}`
 };
 
+/**
+ * Constructor options of `Reflector`.
+ *
+ * @typedef {Object} Reflector~Options
+ * @property {number|Color|string} [color=0x7F7F7F] - The reflector's color.
+ * @property {number} [textureWidth=512] - The texture width. A higher value results in more clear reflections but is also more expensive.
+ * @property {number} [textureHeight=512] - The texture height. A higher value results in more clear reflections but is also more expensive.
+ * @property {number} [clipBias=0] - The clip bias.
+ * @property {Object} [shader] - Can be used to pass in a custom shader that defines how the reflective view is projected onto the reflector's geometry.
+ * @property {number} [multisample=4] - How many samples to use for MSAA. `0` disables MSAA.
+ **/
+
 export { Reflector };

package/examples/jsm/objects/ReflectorForSSRPass.js

@@ -15,8 +15,19 @@ import {
 	HalfFloatType
 } from 'three';
 
+/**
+ * A special version of {@link Reflector} for usage with {@link SSRPass}.
+ *
+ * @augments Mesh
+ */
 class ReflectorForSSRPass extends Mesh {
 
+	/**
+	 * Constructs a new reflector.
+	 *
+	 * @param {BufferGeometry} geometry - The reflector's geometry.
+	 * @param {ReflectorForSSRPass~Options} [options] - The configuration options.
+	 */
 	constructor( geometry, options = {} ) {
 
 		super( geometry );
@@ -240,12 +251,28 @@ class ReflectorForSSRPass extends Mesh {
 
 		};
 
+		/**
+		 * Returns the reflector's internal render target.
+		 *
+		 * @return {WebGLRenderTarget} The internal render target
+		 */
 		this.getRenderTarget = function () {
 
 			return renderTarget;
 
 		};
 
+		/**
+		 * Frees the GPU-related resources allocated by this instance. Call this
+		 * method whenever this instance is no longer used in your app.
+		 */
+		this.dispose = function () {
+
+			renderTarget.dispose();
+			scope.material.dispose();
+
+		};
+
 	}
 
 }
@@ -349,4 +376,16 @@ ReflectorForSSRPass.ReflectorShader = {
 	`,
 };
 
+/**
+ * Constructor options of `ReflectorForSSRPass`.
+ *
+ * @typedef {Object} ReflectorForSSRPass~Options
+ * @property {number|Color|string} [color=0x7F7F7F] - The reflector's color.
+ * @property {number} [textureWidth=512] - The texture width. A higher value results in more clear reflections but is also more expensive.
+ * @property {number} [textureHeight=512] - The texture height. A higher value results in more clear reflections but is also more expensive.
+ * @property {number} [clipBias=0] - The clip bias.
+ * @property {Object} [shader] - Can be used to pass in a custom shader that defines how the reflective view is projected onto the reflector's geometry.
+ * @property {boolean} [useDepthTexture=true] - Whether to store depth values in a texture or not.
+ **/
+
 export { ReflectorForSSRPass };

package/examples/jsm/objects/Refractor.js

@@ -13,15 +13,55 @@ import {
 	HalfFloatType
 } from 'three';
 
+/**
+ * Can be used to create a flat, refractive surface like for special
+ * windows or water effects.
+ *
+ * Note that this class can only be used with {@link WebGLRenderer}.
+ * When using {@link WebGPURenderer}, use {@link viewportSharedTexture}.
+ *
+ * ```js
+ * const geometry = new THREE.PlaneGeometry( 100, 100 );
+ *
+ * const refractor = new Refractor( refractorGeometry, {
+ * 	color: 0xcbcbcb,
+ * 	textureWidth: 1024,
+ * 	textureHeight: 1024
+ * } );
+ *
+ * scene.add( refractor );
+ * ```
+ *
+ * @augments Mesh
+ */
 class Refractor extends Mesh {
 
+	/**
+	 * Constructs a new refractor.
+	 *
+	 * @param {BufferGeometry} geometry - The refractor's geometry.
+	 * @param {Refractor~Options} [options] - The configuration options.
+	 */
 	constructor( geometry, options = {} ) {
 
 		super( geometry );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isRefractor = true;
 
 		this.type = 'Refractor';
+
+		/**
+		 * The reflector's virtual camera.
+		 *
+		 * @type {PerspectiveCamera}
+		 */
 		this.camera = new PerspectiveCamera();
 
 		const scope = this;
@@ -243,12 +283,21 @@ class Refractor extends Mesh {
 
 		};
 
+		/**
+		 * Returns the reflector's internal render target.
+		 *
+		 * @return {WebGLRenderTarget} The internal render target
+		 */
 		this.getRenderTarget = function () {
 
 			return renderTarget;
 
 		};
 
+		/**
+		 * Frees the GPU-related resources allocated by this instance. Call this
+		 * method whenever this instance is no longer used in your app.
+		 */
 		this.dispose = function () {
 
 			renderTarget.dispose();
@@ -324,4 +373,16 @@ Refractor.RefractorShader = {
 
 };
 
+/**
+ * Constructor options of `Refractor`.
+ *
+ * @typedef {Object} Refractor~Options
+ * @property {number|Color|string} [color=0x7F7F7F] - The refractor's color.
+ * @property {number} [textureWidth=512] - The texture width. A higher value results in more clear refractions but is also more expensive.
+ * @property {number} [textureHeight=512] - The texture height. A higher value results in more clear refractions but is also more expensive.
+ * @property {number} [clipBias=0] - The clip bias.
+ * @property {Object} [shader] - Can be used to pass in a custom shader that defines how the refractive view is projected onto the reflector's geometry.
+ * @property {number} [multisample=4] - How many samples to use for MSAA. `0` disables MSAA.
+ **/
+
 export { Refractor };

package/examples/jsm/objects/ShadowMesh.js

@@ -6,14 +6,31 @@ import {
 	IncrementStencilOp
 } from 'three';
 
-/**
- * A shadow Mesh that follows a shadow-casting Mesh in the scene, but is confined to a single plane.
- */
-
 const _shadowMatrix = new Matrix4();
 
+/**
+ * A Shadow Mesh that follows a shadow-casting mesh in the scene,
+ * but is confined to a single plane. This technique can be used as
+ * a very performant alternative to classic shadow mapping. However,
+ * it has serious limitations like:
+ *
+ * - Shadows can only be casted on flat planes.
+ * - No soft shadows support.
+ *
+ * ```js
+ * const cubeShadow = new ShadowMesh( cube );
+ * scene.add( cubeShadow );
+ * ```
+ *
+ * @augments Mesh
+ */
 class ShadowMesh extends Mesh {
 
+	/**
+	 * Constructs a new shadow mesh.
+	 *
+	 * @param {Mesh} mesh - The shadow-casting reference mesh.
+	 */
 	constructor( mesh ) {
 
 		const shadowMaterial = new MeshBasicMaterial( {
@@ -31,15 +48,47 @@ class ShadowMesh extends Mesh {
 
 		super( mesh.geometry, shadowMaterial );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isShadowMesh = true;
 
+		/**
+		 * Represent the world matrix of the reference mesh.
+		 *
+		 * @type {Matrix4}
+		 */
 		this.meshMatrix = mesh.matrixWorld;
 
+		/**
+		 * Overwritten to disable view-frustum culling by default.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.frustumCulled = false;
+
+		/**
+		 * Overwritten to disable automatic matrix update. The local
+		 * matrix is computed manually in {@link ShadowMesh#update}.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.matrixAutoUpdate = false;
 
 	}
 
+	/**
+	 * Updates the shadow mesh so it follows its shadow-casting reference mesh.
+	 *
+	 * @param {Plane} plane - The plane onto the shadow mesh is projected.
+	 * @param {Vector4} lightPosition4D - The light position.
+	 */
 	update( plane, lightPosition4D ) {
 
 		// based on https://www.opengl.org/archives/resources/features/StencilTalk/tsld021.htm

package/examples/jsm/objects/Sky.js

@@ -8,21 +8,31 @@ import {
 } from 'three';
 
 /**
- * Based on "A Practical Analytic Model for Daylight"
- * aka The Preetham Model, the de facto standard analytic skydome model
- * https://www.researchgate.net/publication/220720443_A_Practical_Analytic_Model_for_Daylight
+ * Represents a skydome for scene backgrounds. Based on [A Practical Analytic Model for Daylight]{@link https://www.researchgate.net/publication/220720443_A_Practical_Analytic_Model_for_Daylight}
+ * aka The Preetham Model, the de facto standard for analytical skydomes.
  *
- * First implemented by Simon Wallner
- * http://simonwallner.at/project/atmospheric-scattering/
+ * Note that this class can only be used with {@link WebGLRenderer}.
+ * When using {@link WebGPURenderer}, use {@link SkyMesh}.
  *
- * Improved by Martin Upitis
- * http://blenderartists.org/forum/showthread.php?245954-preethams-sky-impementation-HDR
+ * More references:
  *
- * Three.js integration by zz85 http://twitter.com/blurspline
+ * - {@link http://simonwallner.at/project/atmospheric-scattering/}
+ * - {@link http://blenderartists.org/forum/showthread.php?245954-preethams-sky-impementation-HDR}
+ *
+ *
+ * ```js
+ * const sky = new Sky();
+ * sky.scale.setScalar( 10000 );
+ * scene.add( sky );
+ * ```
+ *
+ * @augments Mesh
 */
-
 class Sky extends Mesh {
 
+	/**
+	 * Constructs a new skydome.
+	 */
 	constructor() {
 
 		const shader = Sky.SkyShader;
@@ -38,6 +48,13 @@ class Sky extends Mesh {
 
 		super( new BoxGeometry( 1, 1, 1 ), material );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isSky = true;
 
 	}

package/examples/jsm/objects/SkyMesh.js

@@ -9,34 +9,85 @@ import {
 import { Fn, float, vec3, acos, add, mul, clamp, cos, dot, exp, max, mix, modelViewProjection, normalize, positionWorld, pow, smoothstep, sub, varying, varyingProperty, vec4, uniform, cameraPosition } from 'three/tsl';
 
 /**
- * Based on "A Practical Analytic Model for Daylight"
- * aka The Preetham Model, the de facto standard analytic skydome model
- * https://www.researchgate.net/publication/220720443_A_Practical_Analytic_Model_for_Daylight
+ * Represents a skydome for scene backgrounds. Based on [A Practical Analytic Model for Daylight]{@link https://www.researchgate.net/publication/220720443_A_Practical_Analytic_Model_for_Daylight}
+ * aka The Preetham Model, the de facto standard for analytical skydomes.
  *
- * First implemented by Simon Wallner
- * http://simonwallner.at/project/atmospheric-scattering/
+ * Note that this class can only be used with {@link WebGLRenderer}.
+ * When using {@link WebGPURenderer}, use {@link SkyMesh}.
  *
- * Improved by Martin Upitis
- * http://blenderartists.org/forum/showthread.php?245954-preethams-sky-impementation-HDR
+ * More references:
  *
- * Three.js integration by zz85 http://twitter.com/blurspline
+ * - {@link http://simonwallner.at/project/atmospheric-scattering/}
+ * - {@link http://blenderartists.org/forum/showthread.php?245954-preethams-sky-impementation-HDR}
+ *
+ * ```js
+ * const sky = new SkyMesh();
+ * sky.scale.setScalar( 10000 );
+ * scene.add( sky );
+ * ```
+ *
+ * @augments Mesh
 */
-
 class SkyMesh extends Mesh {
 
+	/**
+	 * Constructs a new skydome.
+	 */
 	constructor() {
 
 		const material = new NodeMaterial();
 
 		super( new BoxGeometry( 1, 1, 1 ), material );
 
+		/**
+		 * The turbidity uniform.
+		 *
+		 * @type {UniformNode<float>}
+		 */
 		this.turbidity = uniform( 2 );
+
+		/**
+		 * The rayleigh uniform.
+		 *
+		 * @type {UniformNode<float>}
+		 */
 		this.rayleigh = uniform( 1 );
+
+		/**
+		 * The mieCoefficient uniform.
+		 *
+		 * @type {UniformNode<float>}
+		 */
 		this.mieCoefficient = uniform( 0.005 );
+
+		/**
+		 * The mieDirectionalG uniform.
+		 *
+		 * @type {UniformNode<float>}
+		 */
 		this.mieDirectionalG = uniform( 0.8 );
+
+		/**
+		 * The sun position uniform.
+		 *
+		 * @type {UniformNode<vec3>}
+		 */
 		this.sunPosition = uniform( new Vector3() );
+
+		/**
+		 * The up position.
+		 *
+		 * @type {UniformNode<vec3>}
+		 */
 		this.upUniform = uniform( new Vector3( 0, 1, 0 ) );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isSky = true;
 
 		const vertexNode = /*@__PURE__*/ Fn( () => {