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

* Docs: Document the examples/jsm/lines components. (#27034, #29353) * Docs: Link from LineBasicMaterial.linewidth to LineMaterial.
mrdoob · Sep 10, 2024 · d859185 · d859185
1 parent eada853
commit d859185
Show file tree

Hide file tree

Showing 7 changed files with 426 additions and 3 deletions.
diff --git a/docs/api/en/materials/LineBasicMaterial.html b/docs/api/en/materials/LineBasicMaterial.html
@@ -69,7 +69,9 @@ <h3>[property:Float linewidth]</h3>
 			Due to limitations of the
 			[link:https://www.khronos.org/registry/OpenGL/specs/gl/glspec46.core.pdf OpenGL Core Profile] 
 			with the [page:WebGLRenderer WebGL] renderer on most
-			platforms linewidth will always be `1` regardless of the set value.
+			platforms linewidth will always be `1` regardless of the set value.<br /><br />
+
+			If you need wider lines, consider using [page:Line2] or [page:LineSegments2] with [page:LineMaterial].
 		</p>
 
 		<h3>[property:String linecap]</h3>

diff --git a/docs/examples/en/lines/Line2.html b/docs/examples/en/lines/Line2.html
@@ -0,0 +1,65 @@
+<!DOCTYPE html>
+<html lang="en">
+	<head>
+		<meta charset="utf-8" />
+		<base href="../../../" />
+		<script src="page.js"></script>
+		<link type="text/css" rel="stylesheet" href="page.css" />
+	</head>
+	<body>
+		[page:Object3D] &rarr; [page:Mesh] &rarr; [page:LineSegments2] &rarr;
+
+		<h1>[name]</h1>
+
+		<p class="desc">
+			A polyline drawn between vertices.
+		</p>
+
+		<p class="desc">
+			This adds functionality beyond [page:Line], like arbitrary line width and changing width to be in world units.
+			It extends [page:LineSegments2], simplifying constructing segments from a chain of points.
+		</p>
+
+		<h2>Import</h2>
+
+		<p>
+			[name] is an add-on, and therefore must be imported explicitly.
+			See [link:#manual/introduction/Installation Installation / Addons].
+		</p>
+
+		<code>
+			import { Line2 } from 'three/addons/lines/Line2.js';
+		</code>
+
+		<h2>Examples</h2>
+
+		<p>
+			[example:webgl_lines_fat WebGL / lines / fat ]<br />
+			[example:webgl_lines_fat_raycasting WebGL / lines / fat / raycasting ]<br />
+			[example:webgpu_lines_fat WebGPU / lines / fat / raycasting ]
+		</p>
+
+		<h2>Constructor</h2>
+
+		<h3>[name]( [param:LineGeometry geometry], [param:LineMaterial material] )</h3>
+		<p>
+			[page:LineGeometry geometry] — (optional) Pair(s) of vertices representing each line segment.<br />
+			[page:Material material] — (optional) Material for the line. Default is a [page:LineMaterial] with random color.
+		</p>
+
+		<h2>Properties</h2>
+		<p>See the base [page:LineSegments2] class for common properties.</p>
+
+		<h3>[property:Boolean isLine2]</h3>
+		<p>Read-only flag to check if a given object is of type [name].</p>
+
+		<h2>Methods</h2>
+		<p>See the base [page:LineSegments2] class for common methods.</p>
+
+		<h2>Source</h2>
+
+		<p>
+			[link:https://github.com/mrdoob/three.js/blob/master/examples/jsm/lines/Line2.js examples/jsm/lines/Line2.js]
+		</p>
+	</body>
+</html>
diff --git a/docs/examples/en/lines/LineGeometry.html b/docs/examples/en/lines/LineGeometry.html
@@ -0,0 +1,84 @@
+<!DOCTYPE html>
+<html lang="en">
+	<head>
+		<meta charset="utf-8" />
+		<base href="../../../" />
+		<script src="page.js"></script>
+		<link type="text/css" rel="stylesheet" href="page.css" />
+	</head>
+	<body>
+		[page:BufferGeometry] &rarr; [page:InstancedBufferGeometry] &rarr; [page:LineSegmentsGeometry] &rarr;
+
+		<h1>[name]</h1>
+
+		<p class="desc">
+			A chain of vertices, forming a polyline.
+		</p>
+
+		<p class="desc">
+			This is used in [page:Line2] to describe the shape.
+		</p>
+
+		<h2>Import</h2>
+
+		<p>
+			[name] is an add-on, and therefore must be imported explicitly.
+			See [link:#manual/introduction/Installation Installation / Addons].
+		</p>
+
+		<code>
+			import { LineGeometry } from 'three/addons/lines/LineGeometry.js';
+		</code>
+
+		<h2>Examples</h2>
+
+		<p>
+			[example:webgl_lines_fat WebGL / lines / fat ]<br />
+			[example:webgl_lines_fat_raycasting WebGL / lines / fat / raycasting ]<br />
+			[example:webgpu_lines_fat WebGPU / lines / fat / raycasting ]
+		</p>
+
+		<h2>Constructor</h2>
+
+		<h3>[name]()</h3>
+		<p>
+			Creates a new geometry.
+			Call [page:LineGeometry.setPositions setPositions] to add segments.
+		</p>
+
+		<h2>Properties</h2>
+		<p>See the base [page:LineSegmentsGeometry] class for common properties.</p>
+
+		<h3>[property:Boolean isLineGeometry]</h3>
+		<p>Read-only flag to check if a given object is of type [name].</p>
+
+		<h2>Methods</h2>
+		<p>See the base [page:LineSegmentsGeometry] class for common methods.</p>
+
+		<h3>[method:this fromLine]( [param:Line line] )</h3>
+		<p>
+			Copy the vertex positions of a [page:Line] object into this geometry.
+			Assumes the source geometry is not using indices.
+		</p>
+
+		<h3>[method:this setColors]( [param:Array array] )</h3>
+		<p>
+			Replace the per-vertex colors.
+			Every triple describes a line vertex: `[r1, g1, b1]`.
+			The array can be an `Array` or `Float32Array`.
+		</p>
+
+		<h3>[method:this setPositions]( [param:Array array] )</h3>
+		<p>
+			Replace the vertex positions with a new set.
+			The array can be an `Array` or `Float32Array`.
+			The length must be a multiple of three.
+		</p>
+
+		<h2>Source</h2>
+
+		<p>
+			[link:https://github.com/mrdoob/three.js/blob/master/examples/jsm/lines/LineGeometry.js examples/jsm/lines/LineGeometry.js]
+		</p>
+	</body>
+</html>
diff --git a/docs/examples/en/lines/LineMaterial.html b/docs/examples/en/lines/LineMaterial.html
@@ -0,0 +1,92 @@
+<!DOCTYPE html>
+<html lang="en">
+	<head>
+		<meta charset="utf-8" />
+		<base href="../../../" />
+		<script src="page.js"></script>
+		<link type="text/css" rel="stylesheet" href="page.css" />
+	</head>
+	<body>
+		[page:Material] &rarr; [page:ShaderMaterial] &rarr;
+
+		<h1>[name]</h1>
+
+		<p class="desc">
+			A material for drawing wireframe-style geometries.
+			Unlike [page:LineBasicMaterial], it supports arbitrary line widths and allows using world units instead of screen space units.
+			This material is used with [page:LineSegments2] and [page:Line2].
+		</p>
+
+		<p class="desc">
+			Lines are always rendered with round caps and round joints.
+		</p>
+
+		<h2>Examples</h2>
+		<p>
+			[example:webgl_lines_fat WebGL / lines / fat ]<br />
+			[example:webgl_lines_fat_raycasting WebGL / lines / fat / raycasting ]<br />
+			[example:webgl_lines_fat_wireframe WebGL / lines / fat / wireframe ]<br />
+			[example:webgpu_lines_fat WebGPU / lines / fat / raycasting ]
+		</p>
+
+		<h2>Constructor</h2>
+		<h3>[name]( [param:Object parameters] )</h3>
+
+		<p>
+			[page:Object parameters] - (optional) an object with one or more properties defining the material's appearance.
+			Any property of the material (including any property inherited from [page:ShaderMaterial]) can be passed in here.
+		</p>
+
+		<p>
+			The exception is the property [page:Hexadecimal color], which can be passed in as a number or hexadecimal string and is `0xffffff` (white) by default.
+			[page:Color.set]( color ) is called internally.
+		</p>
+
+		<h2>Properties</h2>
+		<p>See the base [page:ShaderMaterial] class for common properties.</p>
+
+		<h3>[property:Color color]</h3>
+		<p>[page:Color] of the material, by default set to white (0xffffff).</p>
+
+		<h3>[property:Boolean dashed]</h3>
+		<p>Whether the line is dashed, or solid. Default is `false`.</p>
+
+		<h3>[property:number dashOffset]</h3>
+		<p>Where in the dash cycle the dash starts. Default is `0`.</p>
+
+		<h3>[property:number dashScale]</h3>
+		<p>The scale of the dashes and gaps. Default is `1`.</p>
+
+		<h3>[property:number dashSize]</h3>
+		<p>The size of the dash. Default is `1`.</p>
+
+		<h3>[property:number gapSize]</h3>
+		<p>The size of the gap. Default is `1`.</p>
+
+		<h3>[property:Float linewidth]</h3>
+		<p>Controls line thickness. Default is `1`.</p>
+
+		<h3>[property:Vector2 resolution]</h3>
+		<p>
+			The size of the viewport, in screen pixels.
+			This must be kept updated to make screen-space rendering accurate.
+			The [page:LineSegments2.onBeforeRender] callback performs the update for visible objects.
+			Default is `[1, 1]`.
+		</p>
+
+		<h3>[property:Boolean worldUnits]</h3>
+		<p>
+			Whether the material's sizes (width, dash gaps) are in world units.
+			Default is `false` (screen space units.)
+		</p>
+
+		<h2>Methods</h2>
+		<p>See the base [page:ShaderMaterial] class for common methods.</p>
+
+		<h2>Source</h2>
+
+		<p>
+			[link:https://github.com/mrdoob/three.js/blob/master/examples/jsm/lines/LineMaterial.js examples/jsm/lines/LineMaterial.js]
+		</p>
+	</body>
+</html>
diff --git a/docs/examples/en/lines/LineSegments2.html b/docs/examples/en/lines/LineSegments2.html
@@ -0,0 +1,69 @@
+<!DOCTYPE html>
+<html lang="en">
+	<head>
+		<meta charset="utf-8" />
+		<base href="../../../" />
+		<script src="page.js"></script>
+		<link type="text/css" rel="stylesheet" href="page.css" />
+	</head>
+	<body>
+		[page:Object3D] &rarr; [page:Mesh] &rarr;
+
+		<h1>[name]</h1>
+
+		<p class="desc">
+			A series of lines drawn between pairs of vertices.
+		</p>
+
+		<p class="desc">
+			This adds functionality beyond [page:LineSegments], like arbitrary line width and changing width to be in world units.
+			The [page:Line2] extends this object, forming a polyline instead of individual segments.
+		</p>
+
+		<h2>Import</h2>
+
+		<p>
+			[name] is an add-on, and therefore must be imported explicitly.
+			See [link:#manual/introduction/Installation Installation / Addons].
+		</p>
+
+		<code>
+			import { LineSegments2 } from 'three/addons/lines/LineSegments2.js';
+		</code>
+
+		<h2>Example</h2>
+
+		<p>[example:webgl_lines_fat_raycasting WebGL / lines / fat / raycasting ]</p>
+
+		<h2>Constructor</h2>
+
+		<h3>[name]( [param:LineSegmentsGeometry geometry], [param:LineMaterial material] )</h3>
+		<p>
+			[page:LineSegmentsGeometry geometry] — (optional) Pair(s) of vertices representing each line segment.<br />
+			[page:Material material] — (optional) Material for the line. Default is a [page:LineMaterial] with random color.
+		</p>
+
+		<h2>Properties</h2>
+		<p>See the base [page:Mesh] class for common properties.</p>
+
+		<h3>[property:Boolean isLineSegments2]</h3>
+		<p>Read-only flag to check if a given object is of type [name].</p>
+
+		<h2>Methods</h2>
+		<p>See the base [page:Mesh] class for common methods.</p>
+
+		<h3>[method:undefined onBeforeRender]( [param:WebGLRenderer renderer] )</h3>
+		<p>
+			Called by the framework to update the material's resolution property, needed for screen-scaled widths.
+		</p>
+		<p>
+			If your object is not visible to a camera (e.g. by [page:Object3D.layers layers] or [page:Object3D.visible visible],) you must call this manually whenever the viewport changes.
+		</p>
+
+		<h2>Source</h2>
+
+		<p>
+			[link:https://github.com/mrdoob/three.js/blob/master/examples/jsm/lines/LineSegments2.js examples/jsm/lines/LineSegments2.js]
+		</p>
+	</body>
+</html>