@plastic-software/three 0.174.0 → 0.175.1

package/examples/jsm/lines/LineMaterial.js

@@ -403,8 +403,28 @@ 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
+ */
 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( {
@@ -419,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;
@@ -437,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;
@@ -457,6 +496,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;
@@ -470,6 +516,12 @@ class LineMaterial extends ShaderMaterial {
 
 	}
 
+	/**
+	 * Whether the line is dashed, or solid.
+	 *
+	 * @type {boolean}
+	 * @default false
+	 */
 	get dashed() {
 
 		return 'USE_DASH' in this.defines;
@@ -496,6 +548,12 @@ class LineMaterial extends ShaderMaterial {
 
 	}
 
+	/**
+	 * The scale of the dashes and gaps.
+	 *
+	 * @type {number}
+	 * @default 1
+	 */
 	get dashScale() {
 
 		return this.uniforms.dashScale.value;
@@ -508,6 +566,12 @@ class LineMaterial extends ShaderMaterial {
 
 	}
 
+	/**
+	 * The size of the dash.
+	 *
+	 * @type {number}
+	 * @default 1
+	 */
 	get dashSize() {
 
 		return this.uniforms.dashSize.value;
@@ -520,6 +584,12 @@ class LineMaterial extends ShaderMaterial {
 
 	}
 
+	/**
+	 * Where in the dash cycle the dash starts.
+	 *
+	 * @type {number}
+	 * @default 0
+	 */
 	get dashOffset() {
 
 		return this.uniforms.dashOffset.value;
@@ -532,6 +602,12 @@ class LineMaterial extends ShaderMaterial {
 
 	}
 
+	/**
+	 * The size of the gap.
+	 *
+	 * @type {number}
+	 * @default 0
+	 */
 	get gapSize() {
 
 		return this.uniforms.gapSize.value;
@@ -544,6 +620,12 @@ class LineMaterial extends ShaderMaterial {
 
 	}
 
+	/**
+	 * The opacity.
+	 *
+	 * @type {number}
+	 * @default 1
+	 */
 	get opacity() {
 
 		return this.uniforms.opacity.value;
@@ -557,6 +639,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;
@@ -569,6 +658,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

@@ -224,22 +224,65 @@ 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
+ */
 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 +308,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,29 @@ 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
+ */
 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 +49,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 +86,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;
@@ -93,6 +123,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;
@@ -116,6 +153,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 );
@@ -124,6 +167,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 );
@@ -132,6 +181,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 ) );
@@ -142,6 +197,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;
@@ -230,14 +292,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

@@ -12,22 +12,58 @@ 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
+ */
 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

@@ -3,12 +3,36 @@ import {
 } from 'three';
 import { LineSegmentsGeometry } from '../lines/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
+ */
 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';

package/examples/jsm/lines/webgpu/Line2.js

@@ -3,13 +3,37 @@ import { Line2NodeMaterial } from 'three/webgpu';
 import { LineSegments2 } from './LineSegments2.js';
 import { LineGeometry } from '../LineGeometry.js';
 
-
+/**
+ * A polyline drawn between vertices.
+ *
+ * This adds functionality beyond {@link Line}, like arbitrary line width and changing width to
+ * be in world units.It extends {@link LineSegments2}, simplifying constructing segments from a
+ * chain of points.
+ *
+ * This module can only be used with {@link WebGPURenderer}. When using {@link WebGLRenderer},
+ * import the class from `lines/Line2.js`.
+ *
+ * @augments LineSegments2
+ */
 class Line2 extends LineSegments2 {
 
+	/**
+	 * Constructs a new wide line.
+	 *
+	 * @param {LineGeometry} [geometry] - The line geometry.
+	 * @param {Line2NodeMaterial} [material] - The line material.
+	 */
 	constructor( geometry = new LineGeometry(), material = new Line2NodeMaterial( { color: Math.random() * 0xffffff } ) ) {
 
 		super( geometry, material );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isLine2 = true;
 
 		this.type = 'Line2';

package/examples/jsm/lines/webgpu/LineSegments2.js

@@ -223,24 +223,56 @@ 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 WebGPURenderer}. When using {@link WebGLRenderer},
+ * import the class from `lines/LineSegments2.js`.
+ *
+ * @augments Mesh
+ */
 class LineSegments2 extends Mesh {
 
+	/**
+	 * Constructs a new wide line.
+	 *
+	 * @param {LineSegmentsGeometry} [geometry] - The line geometry.
+	 * @param {Line2NodeMaterial} [material] - The line material.
+	 */
 	constructor( geometry = new LineSegmentsGeometry(), material = new Line2NodeMaterial( { 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';
 
-		this.resolution = new Vector2();
+		this._resolution = new Vector2();
 
 	}
 
-	// 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;
@@ -269,10 +301,16 @@ class LineSegments2 extends Mesh {
 	onBeforeRender( renderer ) {
 
 		renderer.getViewport( _viewport );
-		this.resolution.set( _viewport.z, _viewport.w );
+		this._resolution.set( _viewport.z, _viewport.w );
 
 	}
 
+	/**
+	 * 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;
@@ -312,7 +350,7 @@ class LineSegments2 extends Mesh {
 		} else {
 
 			const distanceToSphere = Math.max( camera.near, _sphere.distanceToPoint( _ray.origin ) );
-			sphereMargin = getWorldSpaceHalfWidth( camera, distanceToSphere, this.resolution );
+			sphereMargin = getWorldSpaceHalfWidth( camera, distanceToSphere, this._resolution );
 
 		}
 
@@ -342,7 +380,7 @@ class LineSegments2 extends Mesh {
 		} else {
 
 			const distanceToBox = Math.max( camera.near, _box.distanceToPoint( _ray.origin ) );
-			boxMargin = getWorldSpaceHalfWidth( camera, distanceToBox, this.resolution );
+			boxMargin = getWorldSpaceHalfWidth( camera, distanceToBox, this._resolution );
 
 		}
 

package/examples/jsm/lines/webgpu/Wireframe.js

@@ -11,22 +11,50 @@ import { LineSegmentsGeometry } from '../../lines/LineSegmentsGeometry.js';
 const _start = new Vector3();
 const _end = new Vector3();
 
+/**
+ * A class for creating wireframes based on wide lines.
+ *
+ * This module can only be used with {@link WebGPURenderer}. When using {@link WebGLRenderer},
+ * import the class from `lines/Wireframe.js`.
+ *
+ * @augments Mesh
+ */
 class Wireframe extends Mesh {
 
+	/**
+	 * Constructs a new wireframe.
+	 *
+	 * @param {LineSegmentsGeometry} [geometry] - The line geometry.
+	 * @param {Line2NodeMaterial} [material] - The line material.
+	 */
 	constructor( geometry = new LineSegmentsGeometry(), material = new Line2NodeMaterial( { 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;