API Docs

Class: LineMesh

PD. LineMesh

A dynamically expanding geometry for rendering non-indexed lines.

In THREE, dashed lines only support non-indexed BufferGeometry, where each individual line segment is defined by a pair of x,y,z triplets within the position buffer. This means that continuous lines must be formed from multiple segments where each vertex other than the start and end is replicated twice. Thus, this kind of geometry should be used sparingly to conserve GPU memory.

THREE (and WebGL) uses TypedArrays to store vertices and colors in its buffers. Each of these arrays must be re-allocated if the number of vertices changes. When interactively dragging a vertex or line segment within a model, this could happen up to 60 times a second, and for several different meshes at once.

Fortunately, this can be dealt with by pre-allocating a reasonably large amount of memory for each TypedArray so that it can tolerate some reasonable variation without needing to be resized. The THREE.BufferGeometry.setDrawRange() method is then used to limit rendering to only the current content of the buffer and ignore any leftover. If the content expands over the limit and more space is required, then the arrays will be expanded in large enough chunks to meet the requirements only once or twice per interactive event. These arrays can then be reduced to a more optimal size later when the application becomes idle. This approach can significantly reduce or even eliminate the need for garbage collection during highly dynamic interactions.

Also, to help dynamically construct geometry, this class also provides methods for creating primitives such as line strips and line loops. To reuse the mesh with new geometry, simply call the PD.LineMesh#reset first, add the geometry and then call PD.LineMesh#update to refresh the buffers.

new LineMesh( [config])

Creates a new dynamic dashed lines object.

Parameters:
Name Type Argument Description
config object <optional>

An optional configuration object.
Properties of config:
Name Type Argument Description
sizeIncrement number <optional>

An amount by which dynamic buffers incrementally expand their capacity, defaults to 2048.
maxVertices number <optional>

An initial size for the vertex attribute buffers, defaults to 2048 (48KB).
material THREE.Material <optional>

An optional material to use for rendering the lines.
linewidth number <optional>

The thickness of the line in pixels, default is 1.
opacity number <optional>

An opacity for lines if using the default material (0-1), defaults to 1.
color number <optional>

The default color as a hex value if using the default material, defaults to 0x000000.
dashed boolean <optional>

Whether or not to render the lines as dashed.
dashOffset number <optional>

The offset of the dash from the start, defaults to 0.
dashScale number <optional>

The scale of the dashed part of a line, defaults to 1.
dashSize number <optional>

The size of the dash. This is both the gap with the stroke, defaults to 1.
gapSize number <optional>

The size of the gap between dashes, defaults to 1.
userData object <optional>

An object containing attributes and/or associated data to be available via the userData property.
Author:
  • drajmarsh
Examples
// Using addLine().
const mesh1 = new PD.LineMesh();
/// ...
mesh1.reset();
/// ...
mesh1.setColor(1.0, 0.0, 0.0);
let v1 = new THREE.Vector3(0, 0, 0);
let v2 = new THREE.Vector3(10, 0, 0);
let v3 = new THREE.Vector3(10, 10, 0);
let v4 = new THREE.Vector3(0, 10, 0);
mesh1.addLine(v1, v2);
mesh1.addLine(v2, v3);
mesh1.addLine(v3, v4);
mesh1.addLine(v4, v1);
/// ...
mesh1.update();
// Using addLineLoop().
const mesh2 = new PD.LineMesh();
/// ...
mesh2.reset();
/// ...
mesh2.setColor(1.0, 0.0, 0.0);
mesh2.addLineLoop(
    new THREE.Vector3(0, 0, 0),
    new THREE.Vector3(10, 0, 0),
    THREE.Vector3(10, 10, 0),
    new THREE.Vector3(0, 10, 0)
);
/// ...
mesh1.update();

Extends

  • THREE.LineSegments

Members

:THREE.Box3

boundingBox

Store a reference to the geometry bounding box when it is created.

This is a direct reference to this.geometry.boundingBox.

Type
  • THREE.Box3
:boolean

dashed

Whether or not to render all lines in the mesh as dashed.

Type
  • boolean
:THREE.Color

defaultColor

The default colour of mesh triangles, stored as THREE.Color.

If not specified, this value defaults to { r:0.5, g:0.5, b:0.5 }. It can be set at any time using the PD.LineMesh#setColor and PD.LineMesh#color methods.

If the mesh has a colors attribute buffer, the current value of this property is added as the default for each new vertex. If not, it is used as a uniform by the shader that renders the mesh as well as during ray tracing and other types of mesh analysis.

Type
  • THREE.Color
:THREE.BufferGeometry

geometry

Assembles attribute and line buffers as a new THREE geometry object.

Type
  • THREE.BufferGeometry
:boolean

hasChanged

Whether or not the geometry has recently changed and the buffer attributes need regeneration.

Type
  • boolean
:boolean

hasColors

Whether or not to include a buffer for vertex color attributes.

Type
  • boolean
:boolean

isLineMesh <readonly>

A flag identifying this object as dynamic lines.

Type
  • boolean
:number

lineCount

Stores the current number of vertices in each mesh.

Type
  • number
:number

maxVertices

The maximum addressable vertex attribute index.

Type
  • number
:number

opacity

The opacity of the line material.

Type
  • number
:number

sizeIncrement

The amount by which mesh buffers should increment when resizing.

Type
  • number
:object

userData

A map object for holding arbitrary data or attributes.

Use this property to add any additional properties or attributes that you need to be associated with this mesh. Do not add them to the object itself to maintain any hidden class optimisations.

Type
  • object

Methods

addLine(v1, v2)

Appends a new line to the surface mesh.

Parameters:
Name Type Description
v1 THREE.Vector3 | Array

The position of the first vertex.
v2 THREE.Vector3 | Array

The position of the second vertex.
Returns:

Returns the index of the new line.

Type
number

addLineLoop(vertices)

Appends a loop of lines joining the given vertex indices.

Parameters:
Name Type Description
vertices Array

Send either an array of vertexes or multiple arguments.
Returns:

Returns the index of the first added line.

Type
number

addLineStrip(vertices)

Appends a sequence of one or more lines joining the given vertex indices.

Parameters:
Name Type Description
vertices Array

Send either an array of vertexes or multiple arguments.
Returns:

Returns the index of the first added line.

Type
number

addShape(shape, position, scale [, outline])

Adds a shape such as a font glyph to the mesh.

Parameters:
Name Type Argument Description
shape THREE.Shape

The shape to add to the mesh.
position THREE.Vector3

The position of the shape in model coordinates.
scale THREE.Vector3 | number

The scale factor to apply to the shape.
outline boolean <optional>

Whether or not to add the shape outline, defaults to false.
Returns:

Returns the index of the first triangle line.

Type
number

getColor()

Retrieves the default vertex colour.

Returns:

Returns the default colour object.

Type
THREE.Color

getLineCount()

Retrieves the current number of shared vertices stored in the mesh.

Returns:

Returns the current number of shared vertices in the mesh.

Type
number

optimize( [fraction])

Checks the data in each geometry buffer and resizes them based on the given fraction.

The optional fraction parameter allows the caller to control how much optimisation is done. It basically allows for some amount of space at the end of each buffer to allow its content to expand into if more vertices or indexes are added during an interactive event.

Parameters:
Name Type Argument Description
fraction number <optional>

The fraction leftover space to expand into (0 to 1), defaults to 0.25.
Returns:

Returns true if any of the buffers changed size as a result.

Type
boolean

reset()

Resets internal indices so that you can reuse the buffer geometry.

The aim of this method is to maintain all existing buffer arrays whilst allowing new values to be inserted at the beginning. In most highly dynamic situations, the overall size of the mesh doesn't change much, if at all, so this is useful for avoiding unnecessary build-up of garbage collection.

NOTE: You must always call the update() method to finalise each mesh and update the GPU with the new buffers.

Returns:

Returns this instance to support method chaining.

Type
PD.LineMesh

resizeVertexBuffers(newSize)

Resizes the vertex position, normal and color buffers.

Parameters:
Name Type Description
newSize number

The new size of these arrays.
Returns:

Returns true if any of the buffers were resized.

Type
boolean

setColor(r, g, b)

Sets the default vertex color to the three components.

Parameters:
Name Type Description
r number

The red component (0-1), or an object with r, g and b properties.
g number

The green component (0-1).
b number

The blue component (0-1).
Returns:

Returns the colour object.

Type
THREE.Color

setSizeIncrement(increment)

Sets the size increment for vertex and index buffers when they need to change size.

The increment is given as the number of elements to add/remove as different buffers can contain a different number of bytes per element.

Parameters:
Name Type Description
increment number

The new buffer increment value (1 to 65535).
Returns:

Returns the current increment value.

Type
number

update()

Finalises the buffer geometry in each mesh and updates them on the GPU.

Returns:

Returns this instance to support method chaining.

Type
PD.LineMesh