Docs: Document the examples/jsm/lines components. (#1257)

* Docs: Document the examples/jsm/lines components.

* Format

types/three/examples/jsm/lines/Line2.d.ts

@@ -2,10 +2,24 @@ import { LineGeometry } from "./LineGeometry.js";
 import { LineMaterial } from "./LineMaterial.js";
 import { LineSegments2 } from "./LineSegments2.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.
+ */
 export class Line2 extends LineSegments2 {
     geometry: LineGeometry;
     material: LineMaterial;
 
-    constructor(geometry?: LineGeometry, material?: LineMaterial);
+    /**
+     * Read-only flag to check if a given object is of type Line2.
+     */
     readonly isLine2: true;
+
+    /**
+     * @param geometry (optional) Pair(s) of vertices representing each line segment
+     * @param material (optional) Material for the line. Default is a {@link LineMaterial} with random color.
+     */
+    constructor(geometry?: LineGeometry, material?: LineMaterial);
 }

types/three/examples/jsm/lines/LineGeometry.d.ts

@@ -2,9 +2,26 @@ import { Line } from "three";
 
 import { LineSegmentsGeometry } from "./LineSegmentsGeometry.js";
 
+/**
+ * A chain of vertices, forming a polyline.
+ *
+ * This is used in {@link Line2} to describe the shape.
+ */
 export class LineGeometry extends LineSegmentsGeometry {
-    constructor();
+    /**
+     * Read-only flag to check if a given object is of type LineGeometry.
+     */
     readonly isLineGeometry: true;
 
+    /**
+     * Creates a new geometry.
+     * Call [setPositions]{@link LineGeometry.setPositions} to add segments.
+     */
+    constructor();
+
+    /**
+     * Copy the vertex positions of a {@link Line} object into this geometry.
+     * Assumes the source geometry is not using indices.
+     */
     fromLine(line: Line): this;
 }

types/three/examples/jsm/lines/LineMaterial.d.ts

@@ -12,18 +12,71 @@ export interface LineMaterialParameters extends ShaderMaterialParameters {
     worldUnits?: boolean | undefined;
 }
 
+/**
+ * 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}.
+ *
+ * Lines are always rendered with round caps and round joints.
+ */
 export class LineMaterial extends ShaderMaterial {
-    constructor(parameters?: LineMaterialParameters);
-    color: Color;
-    dashed: boolean;
-    dashScale: number;
-    dashSize: number;
-    dashOffset: number;
-    gapSize: number;
-    opacity: number;
     readonly isLineMaterial: true;
-    linewidth: number;
-    resolution: Vector2;
-    alphaToCoverage: boolean;
-    worldUnits: boolean;
+
+    /**
+     * @param parameters (optional) an object with one or more properties defining the material's appearance. Any
+     * property of the material (including any property inherited from {@link ShaderMaterial}) can be passed in here.
+     *
+     * The exception is the property color, which can be passed in as a number or hexadecimal string and is `0xffffff`
+     * (white) by default. Color.set( color ) is called internally.
+     */
+    constructor(parameters?: LineMaterialParameters);
+
+    /**
+     * {@link Color} of the material, by default set to white (0xffffff).
+     */
+    get color(): Color;
+    set color(value: Color);
+
+    /**
+     * Whether the material's sizes (width, dash gaps) are in world units. Default is `false` (screen space units.)
+     */
+    get worldUnits(): boolean;
+    set worldUnits(value: boolean);
+
+    /**
+     * Whether the line is dashed, or solid. Default is `false`.
+     */
+    get dashed(): boolean;
+    set dashed(value: boolean);
+
+    /**
+     * The scale of the dashes and gaps. Default is `1`.
+     */
+    get dashScale(): number;
+    set dashScale(value: number);
+
+    /**
+     * The size of the dash. Default is `1`.
+     */
+    get dashSize(): number;
+    set dashSize(value: number);
+
+    /**
+     * Where in the dash cycle the dash starts. Default is `0`.
+     */
+    get dashOffset(): number;
+    set dashOffset(value: number);
+
+    /**
+     * The size of the gap. Default is `1`.
+     */
+    get gapSize(): number;
+    set gapSize(value: number);
+
+    /**
+     * The size of the viewport, in screen pixels. This must be kept updated to make screen-space rendering accurate.
+     * The {@link LineSegments2.onBeforeRender} callback performs the update for visible objects. Default is `[1, 1]`.
+     */
+    get resolution(): Vector2;
+    set resolution(value: Vector2);
 }

types/three/examples/jsm/lines/LineSegments2.d.ts

@@ -1,14 +1,37 @@
-import { Mesh } from "three";
+import { Mesh, WebGLRenderer } from "three";
 
 import { LineMaterial } from "./LineMaterial.js";
 import { LineSegmentsGeometry } from "./LineSegmentsGeometry.js";
 
+/**
+ * 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. The {@link Line2} extends this object, forming a polyline instead of individual segments.
+ */
 export class LineSegments2 extends Mesh {
     geometry: LineSegmentsGeometry;
     material: LineMaterial;
 
-    constructor(geometry?: LineSegmentsGeometry, material?: LineMaterial);
+    /**
+     * Read-only flag to check if a given object is of type LineSegments2.
+     */
     readonly isLineSegments2: true;
 
+    /**
+     * @param geometry (optional) Pair(s) of vertices representing each line segment.
+     * @param material (optional) Material for the line. Default is a {@link LineMaterial} with random color.
+     */
+    constructor(geometry?: LineSegmentsGeometry, material?: LineMaterial);
+
     computeLineDistances(): this;
+
+    /**
+     * Called by the framework to update the material's resolution property, needed for screen-scaled widths.
+     *
+     * If your object is not visible to a camera (e.g. by [layers]{@link Object3D.layers} or
+     * [visible]{@link Object3D.visible}), you must call this manually whenever the viewport changes.
+     * @param renderer
+     */
+    onBeforeRender(renderer: WebGLRenderer): void;
 }

types/three/examples/jsm/lines/LineSegmentsGeometry.d.ts

@@ -1,16 +1,53 @@
-import { EdgesGeometry, InstancedBufferGeometry, LineSegments, Matrix4, Mesh, WireframeGeometry } from "three";
+import { EdgesGeometry, InstancedBufferGeometry, LineSegments, Mesh, WireframeGeometry } from "three";
 
+/**
+ * A series of vertex pairs, forming line segments.
+ *
+ * This is used in {@link LineSegments2} to describe the shape.
+ */
 export class LineSegmentsGeometry extends InstancedBufferGeometry {
-    constructor();
+    /**
+     * Read-only flag to check if a given object is of type LineSegmentsGeometry.
+     */
     readonly isLineSegmentsGeometry: true;
 
-    applyMatrix4(matrix: Matrix4): this;
-    computeBoundingBox(): void;
-    computeBoundingSphere(): void;
+    /**
+     * Creates a new geometry. Call [setPositions]{@link LineSegmentsGeometry.setPositions} to add segments.
+     */
+    constructor();
+
+    /**
+     * Replace the vertex positions with a new set. The array can be an `Array` or `Float32Array`. The length must be a
+     * multiple of six.
+     * @param array
+     */
+    setPositions(array: number[] | Float32Array): this;
+
+    /**
+     * Replace the per-vertex colors. Every sixtuple describes a segment: `[r1, g1, b1, r2, g2, b2]`. The array can be
+     * an `Array` or `Float32Array`.
+     * @param array
+     */
+    setColors(array: number[] | Float32Array): this;
+
+    /**
+     * Copy the vertex positions of a wireframe geometry into this geometry.
+     */
+    fromWireframeGeometry(geometry: WireframeGeometry): this;
+
+    /**
+     * Copy the vertex positions of an edge geometry into this geometry.
+     */
     fromEdgesGeometry(geometry: EdgesGeometry): this;
-    fromLineSegments(lineSegments: LineSegments): this;
+
+    /**
+     * Copy the vertex positions of a mesh object into this geometry.
+     */
     fromMesh(mesh: Mesh): this;
-    fromWireframeGeometry(geometry: WireframeGeometry): this;
-    setColors(array: number[] | Float32Array): this;
-    setPositions(array: number[] | Float32Array): this;
+
+    /**
+     * Copy the vertex positions of a {@link LineSegments} object into this geometry. Assumes the source geometry is not
+     * using indices.
+     */
+    fromLineSegments(lineSegments: LineSegments): this;
 }