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

package/examples/jsm/helpers/TextureHelper.js

@@ -9,8 +9,27 @@ import {
 } from 'three';
 import { mergeGeometries } from '../utils/BufferGeometryUtils.js';
 
+/**
+ * A helper that can be used to display any type of texture for
+ * debugging purposes. Depending on the type of texture (2D, 3D, Array),
+ * the helper becomes a plane or box mesh.
+ *
+ * This helper can only be used with {@link WebGLRenderer}.
+ * When using {@link WebGPURenderer}, import from `TextureHelperGPU.js`.
+ *
+ * @augments Mesh
+ * @three_import import { TextureHelper } from 'three/addons/helpers/TextureHelper.js';
+ */
 class TextureHelper extends Mesh {
 
+	/**
+	 * Constructs a new texture helper.
+	 *
+	 * @param {Texture} texture - The texture to visualize.
+	 * @param {number} [width=1] - The helper's width.
+	 * @param {number} [height=1] - The helper's height.
+	 * @param {number} [depth=1] - The helper's depth.
+	 */
 	constructor( texture, width = 1, height = 1, depth = 1 ) {
 
 		const material = new ShaderMaterial( {
@@ -81,11 +100,20 @@ class TextureHelper extends Mesh {
 
 		super( geometry, material );
 
+		/**
+		 * The texture to visualize.
+		 *
+		 * @type {Texture}
+		 */
 		this.texture = texture;
 		this.type = 'TextureHelper';
 
 	}
 
+	/**
+	 * Frees the GPU-related resources allocated by this instance. Call this
+	 * method whenever this instance is no longer used in your app.
+	 */
 	dispose() {
 
 		this.geometry.dispose();

package/examples/jsm/helpers/TextureHelperGPU.js

@@ -0,0 +1,214 @@
+import {
+	NodeMaterial,
+	BoxGeometry,
+	BufferAttribute,
+	Mesh,
+	PlaneGeometry,
+	DoubleSide,
+	Vector3,
+} from 'three/webgpu';
+import { texture as textureNode, cubeTexture, texture3D, float, vec4, attribute } from 'three/tsl';
+import { mergeGeometries } from '../utils/BufferGeometryUtils.js';
+
+/**
+ * A helper that can be used to display any type of texture for
+ * debugging purposes. Depending on the type of texture (2D, 3D, Array),
+ * the helper becomes a plane or box mesh.
+ *
+ * This helper can only be used with {@link WebGPURenderer}.
+ * When using {@link WebGLRenderer}, import from `TextureHelper.js`.
+ *
+ * @private
+ * @augments Mesh
+ * @three_import import { TextureHelper } from 'three/addons/helpers/TextureHelperGPU.js';
+ */
+class TextureHelper extends Mesh {
+
+	/**
+	 * Constructs a new texture helper.
+	 *
+	 * @param {Texture} texture - The texture to visualize.
+	 * @param {number} [width=1] - The helper's width.
+	 * @param {number} [height=1] - The helper's height.
+	 * @param {number} [depth=1] - The helper's depth.
+	 */
+	constructor( texture, width = 1, height = 1, depth = 1 ) {
+
+		const material = new NodeMaterial();
+		material.side = DoubleSide;
+		material.transparent = true;
+		material.name = 'TextureHelper';
+
+		let colorNode;
+
+		const uvw = attribute( 'uvw' );
+
+		if ( texture.isCubeTexture ) {
+
+			colorNode = cubeTexture( texture ).sample( uvw );
+
+		} else if ( texture.isData3DTexture || texture.isCompressed3DTexture ) {
+
+			colorNode = texture3D( texture ).sample( uvw );
+
+		} else if ( texture.isArrayTexture || texture.isDataArrayTexture || texture.isCompressedArrayTexture ) {
+
+			colorNode = textureNode( texture ).sample( uvw.xy ).depth( uvw.z );
+
+		} else {
+
+			colorNode = textureNode( texture );
+
+		}
+
+		const alphaNode = float( getAlpha( texture ) );
+
+		material.colorNode = vec4( colorNode.rgb, alphaNode );
+
+		const geometry = texture.isCubeTexture
+			? createCubeGeometry( width, height, depth )
+			: createSliceGeometry( texture, width, height, depth );
+
+		super( geometry, material );
+
+		/**
+		 * The texture to visualize.
+		 *
+		 * @type {Texture}
+		 */
+		this.texture = texture;
+		this.type = 'TextureHelper';
+
+	}
+
+	/**
+	 * Frees the GPU-related resources allocated by this instance. Call this
+	 * method whenever this instance is no longer used in your app.
+	 */
+	dispose() {
+
+		this.geometry.dispose();
+		this.material.dispose();
+
+	}
+
+}
+
+function getImageCount( texture ) {
+
+	if ( texture.isCubeTexture ) {
+
+		return 6;
+
+	} else if ( texture.isArrayTexture || texture.isDataArrayTexture || texture.isCompressedArrayTexture ) {
+
+		return texture.image.depth;
+
+	} else if ( texture.isData3DTexture || texture.isCompressed3DTexture ) {
+
+		return texture.image.depth;
+
+	} else {
+
+		return 1;
+
+	}
+
+}
+
+function getAlpha( texture ) {
+
+	if ( texture.isCubeTexture ) {
+
+		return 1;
+
+	} else if ( texture.isArrayTexture || texture.isDataArrayTexture || texture.isCompressedArrayTexture ) {
+
+		return Math.max( 1 / texture.image.depth, 0.25 );
+
+	} else if ( texture.isData3DTexture || texture.isCompressed3DTexture ) {
+
+		return Math.max( 1 / texture.image.depth, 0.25 );
+
+	} else {
+
+		return 1;
+
+	}
+
+}
+
+function createCubeGeometry( width, height, depth ) {
+
+	const geometry = new BoxGeometry( width, height, depth );
+
+	const position = geometry.attributes.position;
+	const uv = geometry.attributes.uv;
+	const uvw = new BufferAttribute( new Float32Array( uv.count * 3 ), 3 );
+
+	const _direction = new Vector3();
+
+	for ( let j = 0, jl = uv.count; j < jl; ++ j ) {
+
+		_direction.fromBufferAttribute( position, j ).normalize();
+
+		const u = _direction.x;
+		const v = _direction.y;
+		const w = _direction.z;
+
+		uvw.setXYZ( j, u, v, w );
+
+	}
+
+	geometry.deleteAttribute( 'uv' );
+	geometry.setAttribute( 'uvw', uvw );
+
+	return geometry;
+
+}
+
+function createSliceGeometry( texture, width, height, depth ) {
+
+	const sliceCount = getImageCount( texture );
+
+	const geometries = [];
+
+	for ( let i = 0; i < sliceCount; ++ i ) {
+
+		const geometry = new PlaneGeometry( width, height );
+
+		if ( sliceCount > 1 ) {
+
+			geometry.translate( 0, 0, depth * ( i / ( sliceCount - 1 ) - 0.5 ) );
+
+		}
+
+		const uv = geometry.attributes.uv;
+		const uvw = new BufferAttribute( new Float32Array( uv.count * 3 ), 3 );
+
+		for ( let j = 0, jl = uv.count; j < jl; ++ j ) {
+
+			const u = uv.getX( j );
+			const v = texture.flipY ? uv.getY( j ) : 1 - uv.getY( j );
+			const w = sliceCount === 1
+				? 1
+				: texture.isArrayTexture || texture.isDataArrayTexture || texture.isCompressedArrayTexture
+					? i
+					: i / ( sliceCount - 1 );
+
+			uvw.setXYZ( j, u, v, w );
+
+		}
+
+		geometry.deleteAttribute( 'uv' );
+		geometry.setAttribute( 'uvw', uvw );
+
+		geometries.push( geometry );
+
+	}
+
+	return mergeGeometries( geometries );
+
+}
+
+export { TextureHelper };

package/examples/jsm/helpers/VertexNormalsHelper.js

@@ -11,8 +11,33 @@ const _v1 = new Vector3();
 const _v2 = new Vector3();
 const _normalMatrix = new Matrix3();
 
+/**
+ * Visualizes an object's vertex normals.
+ *
+ * Requires that normals have been specified in the geometry as a buffer attribute or
+ * have been calculated using {@link BufferGeometry#computeVertexNormals}.
+ * ```js
+ * const geometry = new THREE.BoxGeometry( 10, 10, 10, 2, 2, 2 );
+ * const material = new THREE.MeshStandardMaterial();
+ * const mesh = new THREE.Mesh( geometry, material );
+ * scene.add( mesh );
+ *
+ * const helper = new VertexNormalsHelper( mesh, 1, 0xff0000 );
+ * scene.add( helper );
+ * ```
+ *
+ * @augments LineSegments
+ * @three_import import { VertexNormalsHelper } from 'three/addons/helpers/VertexNormalsHelper.js';
+ */
 class VertexNormalsHelper extends LineSegments {
 
+	/**
+	 * Constructs a new vertex normals helper.
+	 *
+	 * @param {Object3D} object - The object for which to visualize vertex normals.
+	 * @param {number} [size=1] - The helper's size.
+	 * @param {number|Color|string} [color=0xff0000] - The helper's color.
+	 */
 	constructor( object, size = 1, color = 0xff0000 ) {
 
 		const geometry = new BufferGeometry();
@@ -24,18 +49,48 @@ class VertexNormalsHelper extends LineSegments {
 
 		super( geometry, new LineBasicMaterial( { color, toneMapped: false } ) );
 
+		/**
+		 * The object for which to visualize vertex normals.
+		 *
+		 * @type {Object3D}
+		 */
 		this.object = object;
+
+		/**
+		 * The helper's size.
+		 *
+		 * @type {number}
+		 * @default 1
+		 */
 		this.size = size;
-		this.type = 'VertexNormalsHelper';
 
-		//
+		this.type = 'VertexNormalsHelper';
 
+		/**
+		 * Overwritten and set to `false` since the object's world transformation
+		 * is encoded in the helper's geometry data.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.matrixAutoUpdate = false;
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
+		this.isVertexNormalsHelper = true;
+
 		this.update();
 
 	}
 
+	/**
+	 * Updates the vertex normals preview based on the object's world transform.
+	 */
 	update() {
 
 		this.object.updateMatrixWorld( true );
@@ -84,6 +139,10 @@ class VertexNormalsHelper extends LineSegments {
 
 	}
 
+	/**
+	 * Frees the GPU-related resources allocated by this instance. Call this
+	 * method whenever this instance is no longer used in your app.
+	 */
 	dispose() {
 
 		this.geometry.dispose();

package/examples/jsm/helpers/VertexTangentsHelper.js

@@ -9,8 +9,28 @@ import {
 const _v1 = new Vector3();
 const _v2 = new Vector3();
 
+/**
+ * Visualizes an object's vertex tangents.
+ *
+ * Requires that tangents have been specified in the geometry as a buffer attribute or
+ * have been calculated using {@link BufferGeometry#computeTangents}.
+ * ```js
+ * const helper = new VertexTangentsHelper( mesh, 1, 0xff0000 );
+ * scene.add( helper );
+ * ```
+ *
+ * @augments LineSegments
+ * @three_import import { VertexTangentsHelper } from 'three/addons/helpers/VertexTangentsHelper.js';
+ */
 class VertexTangentsHelper extends LineSegments {
 
+	/**
+	 * Constructs a new vertex tangents helper.
+	 *
+	 * @param {Object3D} object - The object for which to visualize vertex tangents.
+	 * @param {number} [size=1] - The helper's size.
+	 * @param {number|Color|string} [color=0xff0000] - The helper's color.
+	 */
 	constructor( object, size = 1, color = 0x00ffff ) {
 
 		const geometry = new BufferGeometry();
@@ -22,18 +42,39 @@ class VertexTangentsHelper extends LineSegments {
 
 		super( geometry, new LineBasicMaterial( { color, toneMapped: false } ) );
 
+		/**
+		 * The object for which to visualize vertex tangents.
+		 *
+		 * @type {Object3D}
+		 */
 		this.object = object;
+
+		/**
+		 * The helper's size.
+		 *
+		 * @type {number}
+		 * @default 1
+		 */
 		this.size = size;
-		this.type = 'VertexTangentsHelper';
 
-		//
+		this.type = 'VertexTangentsHelper';
 
+		/**
+		 * Overwritten and set to `false` since the object's world transformation
+		 * is encoded in the helper's geometry data.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.matrixAutoUpdate = false;
 
 		this.update();
 
 	}
 
+	/**
+	 * Updates the vertex normals preview based on the object's world transform.
+	 */
 	update() {
 
 		this.object.updateMatrixWorld( true );
@@ -76,6 +117,10 @@ class VertexTangentsHelper extends LineSegments {
 
 	}
 
+	/**
+	 * Frees the GPU-related resources allocated by this instance. Call this
+	 * method whenever this instance is no longer used in your app.
+	 */
 	dispose() {
 
 		this.geometry.dispose();

package/examples/jsm/helpers/ViewHelper.js

@@ -17,17 +17,68 @@ import {
 	Vector4
 } from 'three';
 
+/**
+ * A special type of helper that visualizes the camera's transformation
+ * in a small viewport area as an axes helper. Such a helper is often wanted
+ * in 3D modeling tools or scene editors like the [three.js editor](https://threejs.org/editor).
+ *
+ * The helper allows to click on the X, Y and Z axes which animates the camera
+ * so it looks along the selected axis.
+ *
+ * @augments Object3D
+ * @three_import import { ViewHelper } from 'three/addons/helpers/ViewHelper.js';
+ */
 class ViewHelper extends Object3D {
 
+	/**
+	 * Constructs a new view helper.
+	 *
+	 * @param {Camera} camera - The camera whose transformation should be visualized.
+	 * @param {HTMLElement} [domElement] - The DOM element that is used to render the view.
+	 */
 	constructor( camera, domElement ) {
 
 		super();
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isViewHelper = true;
 
+		/**
+		 * Whether the helper is currently animating or not.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default false
+		 */
 		this.animating = false;
+
+		/**
+		 * The helper's center point.
+		 *
+		 * @type {Vector3}
+		 */
 		this.center = new Vector3();
 
+		/**
+		 * Controls the position of the helper in the viewport.
+		 * Use `top`/`bottom` for vertical positioning and `left`/`right` for horizontal.
+		 * If `left` is `null`, `right` is used. If `top` is `null`, `bottom` is used.
+		 *
+		 * @type {{top: number|null, right: number, bottom: number, left: number|null}}
+		 */
+		this.location = {
+			top: null,
+			right: 0,
+			bottom: 0,
+			left: null
+		};
+
 		const color1 = new Color( '#ff4466' );
 		const color2 = new Color( '#88ff44' );
 		const color3 = new Color( '#4488ff' );
@@ -104,6 +155,12 @@ class ViewHelper extends Object3D {
 		const dim = 128;
 		const turnRate = 2 * Math.PI; // turn rate in angles per second
 
+		/**
+		 * Renders the helper in a separate view in the viewport.
+		 * Position is controlled by the `location` property.
+		 *
+		 * @param {WebGLRenderer|WebGPURenderer} renderer - The renderer.
+		 */
 		this.render = function ( renderer ) {
 
 			this.quaternion.copy( camera.quaternion ).invert();
@@ -114,12 +171,36 @@ class ViewHelper extends Object3D {
 
 			//
 
-			const x = domElement.offsetWidth - dim;
+			const location = this.location;
+
+			let x, y;
+
+			if ( location.left !== null ) {
+
+				x = location.left;
+
+			} else {
+
+				x = domElement.offsetWidth - dim - location.right;
+
+			}
+
+			if ( location.top !== null ) {
+
+				// Position from top
+				y = renderer.isWebGPURenderer ? location.top : domElement.offsetHeight - dim - location.top;
+
+			} else {
+
+				// Position from bottom
+				y = renderer.isWebGPURenderer ? domElement.offsetHeight - dim - location.bottom : location.bottom;
+
+			}
 
 			renderer.clearDepth();
 
 			renderer.getViewport( viewport );
-			renderer.setViewport( x, 0, dim, dim );
+			renderer.setViewport( x, y, dim, dim );
 
 			renderer.render( this, orthoCamera );
 
@@ -135,15 +216,44 @@ class ViewHelper extends Object3D {
 		const viewport = new Vector4();
 		let radius = 0;
 
+		/**
+		 * This method should be called when a click or pointer event
+		 * has happened in the app.
+		 *
+		 * @param {PointerEvent} event - The event to process.
+		 * @return {boolean} Whether an intersection with the helper has been detected or not.
+		 */
 		this.handleClick = function ( event ) {
 
 			if ( this.animating === true ) return false;
 
 			const rect = domElement.getBoundingClientRect();
-			const offsetX = rect.left + ( domElement.offsetWidth - dim );
-			const offsetY = rect.top + ( domElement.offsetHeight - dim );
-			mouse.x = ( ( event.clientX - offsetX ) / ( rect.right - offsetX ) ) * 2 - 1;
-			mouse.y = - ( ( event.clientY - offsetY ) / ( rect.bottom - offsetY ) ) * 2 + 1;
+			const location = this.location;
+
+			let offsetX, offsetY;
+
+			if ( location.left !== null ) {
+
+				offsetX = rect.left + location.left;
+
+			} else {
+
+				offsetX = rect.left + domElement.offsetWidth - dim - location.right;
+
+			}
+
+			if ( location.top !== null ) {
+
+				offsetY = rect.top + location.top;
+
+			} else {
+
+				offsetY = rect.top + domElement.offsetHeight - dim - location.bottom;
+
+			}
+
+			mouse.x = ( ( event.clientX - offsetX ) / dim ) * 2 - 1;
+			mouse.y = - ( ( event.clientY - offsetY ) / dim ) * 2 + 1;
 
 			raycaster.setFromCamera( mouse, orthoCamera );
 
@@ -168,6 +278,13 @@ class ViewHelper extends Object3D {
 
 		};
 
+		/**
+		 * Sets labels for each axis. By default, they are unlabeled.
+		 *
+		 * @param {string|undefined} labelX - The label for the x-axis.
+		 * @param {string|undefined} labelY - The label for the y-axis.
+		 * @param {string|undefined} labelZ - The label for the z-axis.
+		 */
 		this.setLabels = function ( labelX, labelY, labelZ ) {
 
 			options.labelX = labelX;
@@ -178,6 +295,13 @@ class ViewHelper extends Object3D {
 
 		};
 
+		/**
+		 * Sets the label style. Has no effect when the axes are unlabeled.
+		 *
+		 * @param {string} [font='24px Arial'] - The label font.
+		 * @param {string} [color='#000000'] - The label color.
+		 * @param {number} [radius=14] - The label radius.
+		 */
 		this.setLabelStyle = function ( font, color, radius ) {
 
 			options.font = font;
@@ -188,6 +312,12 @@ class ViewHelper extends Object3D {
 
 		};
 
+		/**
+		 * Updates the helper. This method should be called in the app's animation
+		 * loop.
+		 *
+		 * @param {number} delta - The delta time in seconds.
+		 */
 		this.update = function ( delta ) {
 
 			const step = delta * turnRate;
@@ -209,6 +339,10 @@ class ViewHelper extends Object3D {
 
 		};
 
+		/**
+		 * 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 () {
 
 			geometry.dispose();
@@ -293,13 +427,51 @@ class ViewHelper extends Object3D {
 
 		}
 
+		function useOffscreenCanvas() {
+
+			let result = false;
+
+			try {
+
+				// this check has been adapted from WebGLTextures
+
+				result = typeof OffscreenCanvas !== 'undefined' && ( new OffscreenCanvas( 1, 1 ).getContext( '2d' ) ) !== null;
+
+			} catch ( err ) {
+
+				// Ignore any errors
+
+			}
+
+			return result;
+
+		}
+
+		function createCanvas( width, height ) {
+
+			let canvas;
+
+			if ( useOffscreenCanvas() ) {
+
+				canvas = new OffscreenCanvas( width, height );
+
+			} else {
+
+				canvas = document.createElement( 'canvas' );
+				canvas.width = width;
+				canvas.height = height;
+
+			}
+
+			return canvas;
+
+		}
+
 		function getSpriteMaterial( color, text ) {
 
 			const { font = '24px Arial', color: labelColor = '#000000', radius = 14 } = options;
 
-			const canvas = document.createElement( 'canvas' );
-			canvas.width = 64;
-			canvas.height = 64;
+			const canvas = createCanvas( 64, 64 );
 
 			const context = canvas.getContext( '2d' );
 			context.beginPath();