Skip to content

Commit

Permalink
Docs: Document the examples/jsm/lines components. (mrdoob#29381)
Browse files Browse the repository at this point in the history
* Docs: Document the examples/jsm/lines components. (mrdoob#27034, mrdoob#29353)

* Docs: Link from LineBasicMaterial.linewidth to LineMaterial.
  • Loading branch information
tommie authored and LD2Studio committed Sep 13, 2024
1 parent 96b6686 commit 70f7450
Show file tree
Hide file tree
Showing 7 changed files with 426 additions and 3 deletions.
4 changes: 3 additions & 1 deletion docs/api/en/materials/LineBasicMaterial.html
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down
65 changes: 65 additions & 0 deletions docs/examples/en/lines/Line2.html
Original file line number Diff line number Diff line change
@@ -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>
84 changes: 84 additions & 0 deletions docs/examples/en/lines/LineGeometry.html
Original file line number Diff line number Diff line change
@@ -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>
92 changes: 92 additions & 0 deletions docs/examples/en/lines/LineMaterial.html
Original file line number Diff line number Diff line change
@@ -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>
69 changes: 69 additions & 0 deletions docs/examples/en/lines/LineSegments2.html
Original file line number Diff line number Diff line change
@@ -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>
Loading

0 comments on commit 70f7450

Please sign in to comment.