Skip to content

Commit

Permalink
Docs: Document the examples/jsm/lines components. (#1257)
Browse files Browse the repository at this point in the history
* Docs: Document the examples/jsm/lines components.

* Format
  • Loading branch information
Methuselah96 authored Sep 23, 2024
1 parent 946702e commit 6e54c7f
Show file tree
Hide file tree
Showing 5 changed files with 169 additions and 25 deletions.
16 changes: 15 additions & 1 deletion types/three/examples/jsm/lines/Line2.d.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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);
}
19 changes: 18 additions & 1 deletion types/three/examples/jsm/lines/LineGeometry.d.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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;
}
77 changes: 65 additions & 12 deletions types/three/examples/jsm/lines/LineMaterial.d.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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);
}
27 changes: 25 additions & 2 deletions types/three/examples/jsm/lines/LineSegments2.d.ts
Original file line number Diff line number Diff line change
@@ -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;
}
55 changes: 46 additions & 9 deletions types/three/examples/jsm/lines/LineSegmentsGeometry.d.ts
Original file line number Diff line number Diff line change
@@ -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;
}

0 comments on commit 6e54c7f

Please sign in to comment.