diff --git a/types/three/examples/jsm/lines/Line2.d.ts b/types/three/examples/jsm/lines/Line2.d.ts index 2e60c6664..b5b242325 100644 --- a/types/three/examples/jsm/lines/Line2.d.ts +++ b/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); } diff --git a/types/three/examples/jsm/lines/LineGeometry.d.ts b/types/three/examples/jsm/lines/LineGeometry.d.ts index ff9ed81e1..fd8322293 100644 --- a/types/three/examples/jsm/lines/LineGeometry.d.ts +++ b/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; } diff --git a/types/three/examples/jsm/lines/LineMaterial.d.ts b/types/three/examples/jsm/lines/LineMaterial.d.ts index 7b5610594..d7b2b342e 100644 --- a/types/three/examples/jsm/lines/LineMaterial.d.ts +++ b/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); } diff --git a/types/three/examples/jsm/lines/LineSegments2.d.ts b/types/three/examples/jsm/lines/LineSegments2.d.ts index 91a479183..ffe0c2f6b 100644 --- a/types/three/examples/jsm/lines/LineSegments2.d.ts +++ b/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; } diff --git a/types/three/examples/jsm/lines/LineSegmentsGeometry.d.ts b/types/three/examples/jsm/lines/LineSegmentsGeometry.d.ts index ee96d5117..d9bdb86f2 100644 --- a/types/three/examples/jsm/lines/LineSegmentsGeometry.d.ts +++ b/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; }