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

package/examples/jsm/objects/LensflareMesh.js

@@ -12,20 +12,66 @@ import {
 	UnsignedByteType,
 	Vector2,
 	Vector3,
-	Vector4 } from 'three';
-
-import { texture, textureLoad, uv, ivec2, vec2, vec4, positionGeometry, reference, varyingProperty, materialReference, Fn, Node } from 'three/tsl';
-
+	Vector4,
+	Node
+} from 'three/webgpu';
+
+import { texture, textureLoad, uv, ivec2, vec2, vec4, positionGeometry, reference, varyingProperty, materialReference, Fn } from 'three/tsl';
+
+/**
+ * Creates a simulated lens flare that tracks a light.
+ *
+ * Note that this class can only be used with {@link WebGPURenderer}.
+ * When using {@link WebGLRenderer}, use {@link Lensflare}.
+ *
+ * ```js
+ * const light = new THREE.PointLight( 0xffffff, 1.5, 2000 );
+ *
+ * const lensflare = new LensflareMesh();
+ * lensflare.addElement( new LensflareElement( textureFlare0, 512, 0 ) );
+ * lensflare.addElement( new LensflareElement( textureFlare1, 512, 0 ) );
+ * lensflare.addElement( new LensflareElement( textureFlare2, 60, 0.6 ) );
+ *
+ * light.add( lensflare );
+ * ```
+ *
+ * @augments Mesh
+ * @three_import import { LensflareMesh } from 'three/addons/objects/LensflareMesh.js';
+ */
 class LensflareMesh extends Mesh {
 
+	/**
+	 * Constructs a new lensflare mesh.
+	 */
 	constructor() {
 
 		super( LensflareMesh.Geometry, new MeshBasicNodeMaterial( { opacity: 0, transparent: true } ) );
 
-		this.isLensflare = true;
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
+		this.isLensflareMesh = true;
 
 		this.type = 'LensflareMesh';
+
+		/**
+		 * Overwritten to disable view-frustum culling by default.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.frustumCulled = false;
+
+		/**
+		 * Overwritten to make sure lensflares a rendered last.
+		 *
+		 * @type {number}
+		 * @default Infinity
+		 */
 		this.renderOrder = Infinity;
 
 		//
@@ -64,7 +110,7 @@ class LensflareMesh extends Mesh {
 		material1a.type = 'Lensflare-1a';
 
 		material1a.vertexNode = vertexNode;
-		material1a.fragmentNode = vec4( 1.0, 0.0, 1.0, 1.0 );
+		material1a.colorNode = vec4( 1.0, 0.0, 1.0, 1.0 );
 
 		const material1b = new NodeMaterial();
 
@@ -75,7 +121,7 @@ class LensflareMesh extends Mesh {
 		material1b.type = 'Lensflare-1b';
 
 		material1b.vertexNode = vertexNode;
-		material1b.fragmentNode = texture( tempMap, vec2( uv().flipY() ) );
+		material1b.colorNode = texture( tempMap, vec2( uv().flipY() ) );
 
 		// the following object is used for occlusionMap generation
 
@@ -128,7 +174,7 @@ class LensflareMesh extends Mesh {
 
 		} )();
 
-		material2.fragmentNode = Fn( () => {
+		material2.colorNode = Fn( () => {
 
 			const color = reference( 'color', 'color' );
 			const map = reference( 'map', 'texture' );
@@ -144,7 +190,11 @@ class LensflareMesh extends Mesh {
 
 		} )();
 
-
+		/**
+		 * Adds the given lensflare element to this instance.
+		 *
+		 * @param {LensflareElement} element - The element to add.
+		 */
 		this.addElement = function ( element ) {
 
 			elements.push( element );
@@ -165,7 +215,7 @@ class LensflareMesh extends Mesh {
 
 			renderer.getViewport( viewport );
 
-			viewport.multiplyScalar( window.devicePixelRatio );
+			viewport.multiplyScalar( renderer.getPixelRatio() ).floor();
 
 			const renderTarget = renderer.getRenderTarget();
 			const type = ( renderTarget !== null ) ? renderTarget.texture.type : UnsignedByteType;
@@ -262,6 +312,10 @@ class LensflareMesh extends Mesh {
 
 		};
 
+		/**
+		 * 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 () {
 
 			material1a.dispose();

package/examples/jsm/objects/MarchingCubes.js

@@ -9,17 +9,36 @@ import {
 } from 'three';
 
 /**
- * Port of http://webglsamples.org/blob/blob.html
+ * A marching cubes implementation.
+ *
+ * Port of: {@link http://webglsamples.org/blob/blob.html}
+ *
+ * @three_import import { MarchingCubes } from 'three/addons/objects/MarchingCubes.js';
  */
-
 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 +49,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 +527,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 +638,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 +689,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 +739,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 +793,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 +808,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 +823,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 +881,9 @@ class MarchingCubes extends Mesh {
 
 		};
 
+		/**
+		 * Resets the effect.
+		 */
 		this.reset = function () {
 
 			// wipe the normal cache
@@ -818,6 +900,9 @@ class MarchingCubes extends Mesh {
 
 		};
 
+		/**
+		 * Updates the effect.
+		 */
 		this.update = function () {
 
 			this.count = 0;

package/examples/jsm/objects/Reflector.js

@@ -12,15 +12,66 @@ 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
+ * @three_import import { Reflector } from 'three/addons/objects/Reflector.js';
+ */
 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;
@@ -76,9 +127,10 @@ class Reflector extends Mesh {
 
 			view.subVectors( reflectorWorldPosition, cameraWorldPosition );
 
-			// Avoid rendering when reflector is facing away
+			// Avoid rendering when reflector is facing away unless forcing an update
+			const isFacingAway = view.dot( normal ) > 0;
 
-			if ( view.dot( normal ) > 0 ) return;
+			if ( isFacingAway === true && this.forceUpdate === false ) return;
 
 			view.reflect( normal ).negate();
 			view.add( reflectorWorldPosition );
@@ -172,15 +224,25 @@ class Reflector extends Mesh {
 			}
 
 			scope.visible = true;
+			this.forceUpdate = false;
 
 		};
 
+		/**
+		 * 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();
@@ -261,4 +323,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,20 @@ import {
 	HalfFloatType
 } from 'three';
 
+/**
+ * A special version of {@link Reflector} for usage with {@link SSRPass}.
+ *
+ * @augments Mesh
+ * @three_import import { ReflectorForSSRPass } from 'three/addons/objects/ReflectorForSSRPass.js';
+ */
 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 +252,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 +377,17 @@ 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.
+ * @property {Vector2} [resolution] - Resolution for the Reflector Pass.
+ **/
+
 export { ReflectorForSSRPass };

package/examples/jsm/objects/Refractor.js

@@ -13,15 +13,56 @@ 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
+ * @three_import import { Refractor } from 'three/addons/objects/Refractor.js';
+ */
 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 +284,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 +374,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,32 @@ 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
+ * @three_import import { ShadowMesh } from 'three/addons/objects/ShadowMesh.js';
+ */
 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 +49,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