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

package/examples/jsm/lines/LineGeometry.js

@@ -1,17 +1,52 @@
-import { LineSegmentsGeometry } from '../lines/LineSegmentsGeometry.js';
-
+import { LineSegmentsGeometry } from './LineSegmentsGeometry.js';
+
+/**
+ * A chain of vertices, forming a polyline.
+ *
+ * This is used in {@link Line2} to describe the shape.
+ *
+ * ```js
+ * const points = [
+ * 	new THREE.Vector3( - 10, 0, 0 ),
+ * 	new THREE.Vector3( 0, 5, 0 ),
+ * 	new THREE.Vector3( 10, 0, 0 ),
+ * ];
+ *
+ * const geometry = new LineGeometry();
+ * geometry.setFromPoints( points );
+ * ```
+ *
+ * @augments LineSegmentsGeometry
+ * @three_import import { LineLineGeometry2 } from 'three/addons/lines/LineGeometry.js';
+ */
 class LineGeometry extends LineSegmentsGeometry {
 
+	/**
+	 * Constructs a new line geometry.
+	 */
 	constructor() {
 
 		super();
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isLineGeometry = true;
 
 		this.type = 'LineGeometry';
 
 	}
 
+	/**
+	 * Sets the given line positions for this geometry.
+	 *
+	 * @param {Float32Array|Array<number>} array - The position data to set.
+	 * @return {LineGeometry} A reference to this geometry.
+	 */
 	setPositions( array ) {
 
 		// converts [ x1, y1, z1,  x2, y2, z2, ... ] to pairs format
@@ -37,6 +72,12 @@ class LineGeometry extends LineSegmentsGeometry {
 
 	}
 
+	/**
+	 * Sets the given line colors for this geometry.
+	 *
+	 * @param {Float32Array|Array<number>} array - The position data to set.
+	 * @return {LineGeometry} A reference to this geometry.
+	 */
 	setColors( array ) {
 
 		// converts [ r1, g1, b1,  r2, g2, b2, ... ] to pairs format
@@ -62,6 +103,43 @@ class LineGeometry extends LineSegmentsGeometry {
 
 	}
 
+	/**
+	 * Setups this line segments geometry from the given sequence of points.
+	 *
+	 * @param {Array<Vector3|Vector2>} points - An array of points in 2D or 3D space.
+	 * @return {LineGeometry} A reference to this geometry.
+	 */
+	setFromPoints( points ) {
+
+		// converts a vector3 or vector2 array to pairs format
+
+		const length = points.length - 1;
+		const positions = new Float32Array( 6 * length );
+
+		for ( let i = 0; i < length; i ++ ) {
+
+			positions[ 6 * i ] = points[ i ].x;
+			positions[ 6 * i + 1 ] = points[ i ].y;
+			positions[ 6 * i + 2 ] = points[ i ].z || 0;
+
+			positions[ 6 * i + 3 ] = points[ i + 1 ].x;
+			positions[ 6 * i + 4 ] = points[ i + 1 ].y;
+			positions[ 6 * i + 5 ] = points[ i + 1 ].z || 0;
+
+		}
+
+		super.setPositions( positions );
+
+		return this;
+
+	}
+
+	/**
+	 * Setups this line segments geometry from the given line.
+	 *
+	 * @param {Line} line - The line that should be used as a data source for this geometry.
+	 * @return {LineGeometry} A reference to this geometry.
+	 */
 	fromLine( line ) {
 
 		const geometry = line.geometry;

package/examples/jsm/lines/LineMaterial.js

@@ -311,6 +311,9 @@ ShaderLib[ 'line' ] = {
 
 		void main() {
 
+			float alpha = opacity;
+			vec4 diffuseColor = vec4( diffuse, alpha );
+
 			#include <clipping_planes_fragment>
 
 			#ifdef USE_DASH
@@ -321,8 +324,6 @@ ShaderLib[ 'line' ] = {
 
 			#endif
 
-			float alpha = opacity;
-
 			#ifdef WORLD_UNITS
 
 				// Find the closest points on the view ray and the line segment
@@ -387,8 +388,6 @@ ShaderLib[ 'line' ] = {
 
 			#endif
 
-			vec4 diffuseColor = vec4( diffuse, alpha );
-
 			#include <logdepthbuf_fragment>
 			#include <color_fragment>
 
@@ -403,14 +402,34 @@ ShaderLib[ 'line' ] = {
 		`
 };
 
+/**
+ * A material for drawing wireframe-style geometries.
+ *
+ * Unlike {@link LineBasicMaterial}, it supports arbitrary line widths and allows using world units
+ * instead of screen space units. This material is used with {@link LineSegments2} and {@link Line2}.
+ *
+ * This module can only be used with {@link WebGLRenderer}. When using {@link WebGPURenderer},
+ * use {@link Line2NodeMaterial}.
+ *
+ * @augments ShaderMaterial
+ * @three_import import { LineMaterial } from 'three/addons/lines/LineMaterial.js';
+ */
 class LineMaterial extends ShaderMaterial {
 
+	/**
+	 * Constructs a new line segments geometry.
+	 *
+	 * @param {Object} [parameters] - An object with one or more properties
+	 * defining the material's appearance. Any property of the material
+	 * (including any property from inherited materials) can be passed
+	 * in here. Color values can be passed any type of value accepted
+	 * by {@link Color#set}.
+	 */
 	constructor( parameters ) {
 
 		super( {
 
 			type: 'LineMaterial',
-
 			uniforms: UniformsUtils.clone( ShaderLib[ 'line' ].uniforms ),
 
 			vertexShader: ShaderLib[ 'line' ].vertexShader,
@@ -420,12 +439,25 @@ class LineMaterial extends ShaderMaterial {
 
 		} );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isLineMaterial = true;
 
 		this.setValues( parameters );
 
 	}
 
+	/**
+	 * The material's color.
+	 *
+	 * @type {Color}
+	 * @default (1,1,1)
+	 */
 	get color() {
 
 		return this.uniforms.diffuse.value;
@@ -438,6 +470,12 @@ class LineMaterial extends ShaderMaterial {
 
 	}
 
+	/**
+	 * Whether the material's sizes (width, dash gaps) are in world units.
+	 *
+	 * @type {boolean}
+	 * @default false
+	 */
 	get worldUnits() {
 
 		return 'WORLD_UNITS' in this.defines;
@@ -446,6 +484,12 @@ class LineMaterial extends ShaderMaterial {
 
 	set worldUnits( value ) {
 
+		if ( ( value === true ) !== this.worldUnits ) {
+
+			this.needsUpdate = true;
+
+		}
+
 		if ( value === true ) {
 
 			this.defines.WORLD_UNITS = '';
@@ -458,6 +502,13 @@ class LineMaterial extends ShaderMaterial {
 
 	}
 
+	/**
+	 * Controls line thickness in CSS pixel units when `worldUnits` is `false` (default),
+	 * or in world units when `worldUnits` is `true`.
+	 *
+	 * @type {number}
+	 * @default 1
+	 */
 	get linewidth() {
 
 		return this.uniforms.linewidth.value;
@@ -471,6 +522,12 @@ class LineMaterial extends ShaderMaterial {
 
 	}
 
+	/**
+	 * Whether the line is dashed, or solid.
+	 *
+	 * @type {boolean}
+	 * @default false
+	 */
 	get dashed() {
 
 		return 'USE_DASH' in this.defines;
@@ -497,6 +554,12 @@ class LineMaterial extends ShaderMaterial {
 
 	}
 
+	/**
+	 * The scale of the dashes and gaps.
+	 *
+	 * @type {number}
+	 * @default 1
+	 */
 	get dashScale() {
 
 		return this.uniforms.dashScale.value;
@@ -509,6 +572,12 @@ class LineMaterial extends ShaderMaterial {
 
 	}
 
+	/**
+	 * The size of the dash.
+	 *
+	 * @type {number}
+	 * @default 1
+	 */
 	get dashSize() {
 
 		return this.uniforms.dashSize.value;
@@ -521,6 +590,12 @@ class LineMaterial extends ShaderMaterial {
 
 	}
 
+	/**
+	 * Where in the dash cycle the dash starts.
+	 *
+	 * @type {number}
+	 * @default 0
+	 */
 	get dashOffset() {
 
 		return this.uniforms.dashOffset.value;
@@ -533,6 +608,12 @@ class LineMaterial extends ShaderMaterial {
 
 	}
 
+	/**
+	 * The size of the gap.
+	 *
+	 * @type {number}
+	 * @default 0
+	 */
 	get gapSize() {
 
 		return this.uniforms.gapSize.value;
@@ -545,6 +626,12 @@ class LineMaterial extends ShaderMaterial {
 
 	}
 
+	/**
+	 * The opacity.
+	 *
+	 * @type {number}
+	 * @default 1
+	 */
 	get opacity() {
 
 		return this.uniforms.opacity.value;
@@ -558,6 +645,13 @@ class LineMaterial extends ShaderMaterial {
 
 	}
 
+	/**
+	 * The size of the viewport, in screen pixels. This must be kept updated to make
+	 * screen-space rendering accurate.The `LineSegments2.onBeforeRender` callback
+	 * performs the update for visible objects.
+	 *
+	 * @type {Vector2}
+	 */
 	get resolution() {
 
 		return this.uniforms.resolution.value;
@@ -570,6 +664,12 @@ class LineMaterial extends ShaderMaterial {
 
 	}
 
+	/**
+	 * Whether to use alphaToCoverage or not. When enabled, this can improve the
+	 * anti-aliasing of line edges when using MSAA.
+	 *
+	 * @type {boolean}
+	 */
 	get alphaToCoverage() {
 
 		return 'USE_ALPHA_TO_COVERAGE' in this.defines;

package/examples/jsm/lines/LineSegments2.js

@@ -10,8 +10,8 @@ import {
 	Vector3,
 	Vector4
 } from 'three';
-import { LineSegmentsGeometry } from '../lines/LineSegmentsGeometry.js';
-import { LineMaterial } from '../lines/LineMaterial.js';
+import { LineSegmentsGeometry } from './LineSegmentsGeometry.js';
+import { LineMaterial } from './LineMaterial.js';
 
 const _viewport = new Vector4();
 
@@ -224,22 +224,66 @@ function raycastScreenSpace( lineSegments, camera, intersects ) {
 
 }
 
+/**
+ * A series of lines drawn between pairs of vertices.
+ *
+ * This adds functionality beyond {@link LineSegments}, like arbitrary line width and changing width
+ * to be in world units. {@link Line2} extends this object, forming a polyline instead of individual
+ * segments.
+ *
+ * This module can only be used with {@link WebGLRenderer}. When using {@link WebGPURenderer},
+ * import the class from `lines/webgpu/LineSegments2.js`.
+ *
+ *  ```js
+ * const geometry = new LineSegmentsGeometry();
+ * geometry.setPositions( positions );
+ * geometry.setColors( colors );
+ *
+ * const material = new LineMaterial( { linewidth: 5, vertexColors: true } };
+ *
+ * const lineSegments = new LineSegments2( geometry, material );
+ * scene.add( lineSegments );
+ * ```
+ *
+ * @augments Mesh
+ * @three_import import { LineSegments2 } from 'three/addons/lines/LineSegments2.js';
+ */
 class LineSegments2 extends Mesh {
 
+	/**
+	 * Constructs a new wide line.
+	 *
+	 * @param {LineSegmentsGeometry} [geometry] - The line geometry.
+	 * @param {LineMaterial} [material] - The line material.
+	 */
 	constructor( geometry = new LineSegmentsGeometry(), material = new LineMaterial( { color: Math.random() * 0xffffff } ) ) {
 
 		super( geometry, material );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isLineSegments2 = true;
 
 		this.type = 'LineSegments2';
 
 	}
 
-	// for backwards-compatibility, but could be a method of LineSegmentsGeometry...
-
+	/**
+	 * Computes an array of distance values which are necessary for rendering dashed lines.
+	 * For each vertex in the geometry, the method calculates the cumulative length from the
+	 * current point to the very beginning of the line.
+	 *
+	 * @return {LineSegments2} A reference to this instance.
+	 */
 	computeLineDistances() {
 
+		// for backwards-compatibility, but could be a method of LineSegmentsGeometry...
+
 		const geometry = this.geometry;
 
 		const instanceStart = geometry.attributes.instanceStart;
@@ -265,6 +309,12 @@ class LineSegments2 extends Mesh {
 
 	}
 
+	/**
+	 * Computes intersection points between a casted ray and this instance.
+	 *
+	 * @param {Raycaster} raycaster - The raycaster.
+	 * @param {Array<Object>} intersects - The target array that holds the intersection points.
+	 */
 	raycast( raycaster, intersects ) {
 
 		const worldUnits = this.material.worldUnits;

package/examples/jsm/lines/LineSegmentsGeometry.js

@@ -12,12 +12,30 @@ import {
 const _box = new Box3();
 const _vector = new Vector3();
 
+/**
+ * A series of vertex pairs, forming line segments.
+ *
+ * This is used in {@link LineSegments2} to describe the shape.
+ *
+ * @augments InstancedBufferGeometry
+ * @three_import import { LineSegmentsGeometry } from 'three/addons/lines/LineSegmentsGeometry.js';
+ */
 class LineSegmentsGeometry extends InstancedBufferGeometry {
 
+	/**
+	 * Constructs a new line segments geometry.
+	 */
 	constructor() {
 
 		super();
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isLineSegmentsGeometry = true;
 
 		this.type = 'LineSegmentsGeometry';
@@ -32,6 +50,12 @@ class LineSegmentsGeometry extends InstancedBufferGeometry {
 
 	}
 
+	/**
+	 * Applies the given 4x4 transformation matrix to the geometry.
+	 *
+	 * @param {Matrix4} matrix - The matrix to apply.
+	 * @return {LineSegmentsGeometry} A reference to this instance.
+	 */
 	applyMatrix4( matrix ) {
 
 		const start = this.attributes.instanceStart;
@@ -63,6 +87,13 @@ class LineSegmentsGeometry extends InstancedBufferGeometry {
 
 	}
 
+	/**
+	 * Sets the given line positions for this geometry. The length must be a multiple of six since
+	 * each line segment is defined by a start end vertex in the pattern `(xyz xyz)`.
+	 *
+	 * @param {Float32Array|Array<number>} array - The position data to set.
+	 * @return {LineSegmentsGeometry} A reference to this geometry.
+	 */
 	setPositions( array ) {
 
 		let lineSegments;
@@ -82,6 +113,8 @@ class LineSegmentsGeometry extends InstancedBufferGeometry {
 		this.setAttribute( 'instanceStart', new InterleavedBufferAttribute( instanceBuffer, 3, 0 ) ); // xyz
 		this.setAttribute( 'instanceEnd', new InterleavedBufferAttribute( instanceBuffer, 3, 3 ) ); // xyz
 
+		this.instanceCount = this.attributes.instanceStart.count;
+
 		//
 
 		this.computeBoundingBox();
@@ -91,6 +124,13 @@ class LineSegmentsGeometry extends InstancedBufferGeometry {
 
 	}
 
+	/**
+	 * Sets the given line colors for this geometry. The length must be a multiple of six since
+	 * each line segment is defined by a start end color in the pattern `(rgb rgb)`.
+	 *
+	 * @param {Float32Array|Array<number>} array - The position data to set.
+	 * @return {LineSegmentsGeometry} A reference to this geometry.
+	 */
 	setColors( array ) {
 
 		let colors;
@@ -114,6 +154,12 @@ class LineSegmentsGeometry extends InstancedBufferGeometry {
 
 	}
 
+	/**
+	 * Setups this line segments geometry from the given wireframe geometry.
+	 *
+	 * @param {WireframeGeometry} geometry - The geometry that should be used as a data source for this geometry.
+	 * @return {LineSegmentsGeometry} A reference to this geometry.
+	 */
 	fromWireframeGeometry( geometry ) {
 
 		this.setPositions( geometry.attributes.position.array );
@@ -122,6 +168,12 @@ class LineSegmentsGeometry extends InstancedBufferGeometry {
 
 	}
 
+	/**
+	 * Setups this line segments geometry from the given edges geometry.
+	 *
+	 * @param {EdgesGeometry} geometry - The geometry that should be used as a data source for this geometry.
+	 * @return {LineSegmentsGeometry} A reference to this geometry.
+	 */
 	fromEdgesGeometry( geometry ) {
 
 		this.setPositions( geometry.attributes.position.array );
@@ -130,6 +182,12 @@ class LineSegmentsGeometry extends InstancedBufferGeometry {
 
 	}
 
+	/**
+	 * Setups this line segments geometry from the given mesh.
+	 *
+	 * @param {Mesh} mesh - The mesh geometry that should be used as a data source for this geometry.
+	 * @return {LineSegmentsGeometry} A reference to this geometry.
+	 */
 	fromMesh( mesh ) {
 
 		this.fromWireframeGeometry( new WireframeGeometry( mesh.geometry ) );
@@ -140,6 +198,13 @@ class LineSegmentsGeometry extends InstancedBufferGeometry {
 
 	}
 
+	/**
+	 * Setups this line segments geometry from the given line segments.
+	 *
+	 * @param {LineSegments} lineSegments - The line segments that should be used as a data source for this geometry.
+	 * Assumes the source geometry is not using indices.
+	 * @return {LineSegmentsGeometry} A reference to this geometry.
+	 */
 	fromLineSegments( lineSegments ) {
 
 		const geometry = lineSegments.geometry;
@@ -228,14 +293,6 @@ class LineSegmentsGeometry extends InstancedBufferGeometry {
 
 	}
 
-	applyMatrix( matrix ) {
-
-		console.warn( 'THREE.LineSegmentsGeometry: applyMatrix() has been renamed to applyMatrix4().' );
-
-		return this.applyMatrix4( matrix );
-
-	}
-
 }
 
 export { LineSegmentsGeometry };

package/examples/jsm/lines/Wireframe.js

@@ -5,29 +5,66 @@ import {
 	Vector3,
 	Vector4
 } from 'three';
-import { LineSegmentsGeometry } from '../lines/LineSegmentsGeometry.js';
-import { LineMaterial } from '../lines/LineMaterial.js';
+import { LineSegmentsGeometry } from './LineSegmentsGeometry.js';
+import { LineMaterial } from './LineMaterial.js';
 
 const _start = new Vector3();
 const _end = new Vector3();
 const _viewport = new Vector4();
 
+/**
+ * A class for creating wireframes based on wide lines.
+ *
+ * This module can only be used with {@link WebGLRenderer}. When using {@link WebGPURenderer},
+ * import the class from `lines/webgpu/Wireframe.js`.
+ *
+ * ```js
+ * const geometry = new THREE.IcosahedronGeometry();
+ * const wireframeGeometry = new WireframeGeometry2( geo );
+ *
+ * const wireframe = new Wireframe( wireframeGeometry, material );
+ * scene.add( wireframe );
+ * ```
+ *
+ * @augments Mesh
+ * @three_import import { Wireframe } from 'three/addons/lines/Wireframe.js';
+ */
 class Wireframe extends Mesh {
 
+	/**
+	 * Constructs a new wireframe.
+	 *
+	 * @param {LineSegmentsGeometry} [geometry] - The line geometry.
+	 * @param {LineMaterial} [material] - The line material.
+	 */
 	constructor( geometry = new LineSegmentsGeometry(), material = new LineMaterial( { color: Math.random() * 0xffffff } ) ) {
 
 		super( geometry, material );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isWireframe = true;
 
 		this.type = 'Wireframe';
 
 	}
 
-	// for backwards-compatibility, but could be a method of LineSegmentsGeometry...
-
+	/**
+	 * Computes an array of distance values which are necessary for rendering dashed lines.
+	 * For each vertex in the geometry, the method calculates the cumulative length from the
+	 * current point to the very beginning of the line.
+	 *
+	 * @return {Wireframe} A reference to this instance.
+	 */
 	computeLineDistances() {
 
+		// for backwards-compatibility, but could be a method of LineSegmentsGeometry...
+
 		const geometry = this.geometry;
 
 		const instanceStart = geometry.attributes.instanceStart;

package/examples/jsm/lines/WireframeGeometry2.js

@@ -1,14 +1,39 @@
 import {
 	WireframeGeometry
 } from 'three';
-import { LineSegmentsGeometry } from '../lines/LineSegmentsGeometry.js';
-
+import { LineSegmentsGeometry } from './LineSegmentsGeometry.js';
+
+/**
+ * A special type of line segments geometry intended for wireframe rendering.
+ *
+ * This is used in {@link Wireframe} to describe the shape.
+ *
+ * ```js
+ * const geometry = new THREE.IcosahedronGeometry();
+ * const wireframeGeometry = new WireframeGeometry2( geo );
+ * ```
+ *
+ * @augments LineSegmentsGeometry
+ * @three_import import { WireframeGeometry2 } from 'three/addons/lines/WireframeGeometry2.js';
+ */
 class WireframeGeometry2 extends LineSegmentsGeometry {
 
+	/**
+	 * Constructs a new wireframe geometry.
+	 *
+	 * @param {BufferGeometry} [geometry] - The geometry to render the wireframe for.
+	 */
 	constructor( geometry ) {
 
 		super();
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isWireframeGeometry2 = true;
 
 		this.type = 'WireframeGeometry2';