API Docs Class: MeshBuilder

new MeshBuilder( [config])

Creates a new mesh builder object.

Parameters:

Name Type Argument Description

config

object

An object with optional values for setting up the mesh.

Properties of `config`:

Name	Type	Argument	Description
`defaultNormal`	Array	<optional>	The surface normal given as an [x,y,z] array (defaults to [0,0,1]).
`defaultColor`	Array	<optional>	The colour of the mesh, given as an [r,g,b,a] array (defaults to [0.8,0.8,0.8,1.0]).
`defaultUV`	Array	<optional>	The texture coordinate given as an [u,v] array (defaults to [0.0,0.0]).
`normals`	boolean	<optional>	If true creates a 'normals' vertex array, defaults to false.
`colors`	boolean	<optional>	If true creates a 'colors' vertex array, defaults to false.
`uvs`	boolean	<optional>	If true creates a 'uvs' vertex array, defaults to false.

Author:

drajmarsh

Examples

// Emulating immediate mode.
const mesh1 = new PD.MeshBuilder({ lines: true, color: true, uvs: true });
mesh1.begin(gl.QUADS)
     .normal(0, 0, 1)
     .color(1.0, 0.0, 0.0, 1.0)
     .uv(0, 0)
     .vertex(0, 0, 0)
     .uv(1, 0)
     .vertex(10, 0, 0)
     .uv(1, 1)
     .vertex(10, 10, 0)
     .uv(0, 1)
     .vertex(0, 10, 0)
     .end()
     ;

// With outline example.
const mesh2 = new PD.MeshBuilder({ lines: true });
mesh2.setNormal([0, 0, 1]);
mesh2.setColor([1.0, 0.0, 0.0, 1.0]);
let v1 = mesh2.addVertex([0, 0, 0]);
let v2 = mesh2.addVertex([10, 0, 0]);
let v3 = mesh2.addVertex([10, 10, 0]);
let v4 = mesh2.addVertex([0, 10, 0]);
mesh2.addTriangle(v1, v2, v3);
mesh2.addTriangle(v1, v3, v4);
mesh2.addLine(v1, v2);
mesh2.addLine(v2, v3);
mesh2.addLine(v3, v4);
mesh2.addLine(v4, v1);

// Example with colors and texture coordinates.
const mesh3 = new PD.MeshBuilder({ colors: true, uvs: true, lines: true });
const normal3 = [ 0, 0, 1 ];
mesh3.addQuad(
    mesh3.addVertex([ 0,  0, 0], [1.0, 0.0, 0.0], normal3, [0, 0]),
    mesh3.addVertex([10,  0, 0], [0.0, 1.0, 0.0], normal3, [1, 0]),
    mesh3.addVertex([10, 10, 0], [0.0, 0.0, 1.0], normal3, [1, 1]),
    mesh3.addVertex([ 0, 10, 0], [1.0, 0.0, 1.0], normal3, [0, 1])
);
let index = mesh3.vertexCount();
mesh3.addLineLoop(index - 4, index - 3, index - 2, index - 1);

// Example using a data object.
const mesh4 = new PD.MeshBuilder({ colors: true, normals: true, uvs: true, lines: true });
const vtx_data = {};
vtx_data.pos = [0, 0, 0];
vtx_data.normal = [-1, -1, 1];
vtx_data.color = [1.0, 0.0, 0.0];
vtx_data.uv = [0, 0];
mesh4.addVertexFromObject(vtx_data);
vtx_data.pos = [10, 0, 0];
vtx_data.normal = [1, -1, 1];
vtx_data.color = [0.0, 1.0, 0.0];
vtx_data.uv = [1, 0];
mesh4.addVertexFromObject(vtx_data);
vtx_data.pos = [10, 10, 0];
vtx_data.normal = [1, 1, 1];
vtx_data.color = [0.0, 0.0, 1.0];
vtx_data.uv = [1, 1];
mesh4.addVertexFromObject(vtx_data);
vtx_data.pos = [0, 10, 0];
vtx_data.normal = [-1, 1, 1];
vtx_data.color = [1.0, 0.0, 1.0];
vtx_data.uv = [0, 1];
mesh4.addVertexFromObject(vtx_data);
let index = mesh4.vertexCount();
mesh4.addQuad(index - 4, index - 3, index - 2, index - 1);
mesh4.addLineLoop(index - 4, index - 3, index - 2, index - 1);

Members

:Array|null colors

Stores vertex colors as an array of [r,g,b] color values.

This is an optional flat array of floating point numbers where each triplet of values represent the red, green and blue components of the vertex color.

Type

Array | null

:Array defaultColor

The default colour of mesh triangles, stored as an [r,g,b,a] color array.

If not specified, this value defaults to [0.8, 0.8, 0.8, 1.0]. It can be set at any time using the PD.MeshBuilder#setColor and PD.MeshBuilder#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

Array

:Array defaultNormal

The default surface normal stored as an [x,y,z] vector array.

If not specified, this value defaults to [0, 0, 1]. It can be set at any time using the PD.MeshBuilder#setNormal and PD.MeshBuilder#normal methods.

If the mesh has a normals attribute buffer, the current value of this property is added as an attribute 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

Array

:Array defaultUV

The default texture coordinate of the vertex, stored as an [u,v] array.

If not specified, this value defaults to [0.0, 0.0]; It can be set at any time using the PD.MeshBuilder#setUV and PD.MeshBuilder#uv methods.

If the mesh has a uvs attribute buffer, the current value of this property is added as an attribute for each new vertex.

Type

Array

:boolean hasChanged

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

Type

boolean

:boolean isMeshBuilder <readonly>

A flag identifying this object as a mesh builder.

Type

boolean

:boolean lineColors

Whether or not to include colors in outline buffer geometry.

Type

boolean

:Array lines

Stores outlines as an array of a,b vertex indices.

This is a flat array of integer indexes into the currently allocated vertex attribute arrays. Each pair of entries define the start and end vertices of a line.

Type

Array

:Array|null normals

Stores vertex normals as an array of [x,y,z] vectors.

This is an optional flat array of floating point numbers where each triplet of values represent the x, y and z components of the surface normal of a vertex.

Type

Array | null

:Array positions

Stores vertex positions as an array of [x,y,z] coordinates.

This is a flat array of floating point numbers where each triplet of values represent the x, y and z axis position of a vertex in model space. This is not an optional attribute as all geometry needs vertex positions.

Type

Array

:THREE.Float32BufferAttribute|null sharedColorAttribute

The vertex color attribute for sharing between geometries.

Type

THREE.Float32BufferAttribute | null

:THREE.Float32BufferAttribute|null sharedPositionAttribute

The vertex position attribute for sharing between geometries.

Type

THREE.Float32BufferAttribute | null

:Array triangles

Stores triangles as an array of a,b,c vertex indices.

This is a flat array of integer indexes into the currently allocated vertex attribute arrays. Each triplet of entries define the three vertices of a triangle.

Type

Array

:Array|null uvs

Stores texture coordinates as an array of [u,v] values.

This is an optional flat array of floating point numbers where each pair of values represent the U and V components of the vertex texture coordinate.

Type

Array | null

:number vertexCount

Stores the current number of vertices in the mesh.

Type

number

Methods

addArrowLine(index1, index2, size)

Adds a new line with an arrow head extension.

Parameters:

Name	Type	Description
`index1`	number	The attribute index of the vertex that starts the line.
`index2`	number	The attribute index of the vertex that ends the line.
`size`	number	The size of the arrow head extension, in model coordinates.

Returns:

Returns the starting index of the first of 1 or 3 newly added lines.

Type: number

addDashedLine(index1, index2, size)

Adds a new dashed line style with rear, center and forward lines.

Parameters:

Name	Type	Description
`index1`	number	The attribute index of the vertex that starts the line.
`index2`	number	The attribute index of the vertex that ends the line.
`size`	number	The size of each dash in model coordinates.

Returns:

Returns the starting index of the first of 2 or 3 newly added lines.

Type: number

addDraftingLine(index1, index2, size [, forward])

Adds a new architectural style extension with rear, center and forward lines.

Parameters:

Name	Type	Argument	Description
`index1`	number		The attribute index of the vertex that starts the line.
`index2`	number		The attribute index of the vertex that ends the line.
`size`	number		The size of the extension in model coordinates.
`forward`	boolean	<optional>	When true only the forward extension is drawn, otherwise both.

Returns:

Returns the starting index of the first of 2 or 3 newly added lines.

Type: number

addDraftingLines(indices, size)

Adds architectural style extensions to first and last in series.

Parameters:

Name	Type	Description
`indices`	Array	An array of vertex indices defining the line.
`size`	number	The size of the extended overrun, in model coordinates.

Returns:

Returns the starting index of the first newly added line.

Type: number

addLine(index1, index2)

Adds a new line with the given vertex indices.

Parameters:

Name	Type	Description
`index1`	number	The attribute index of the vertex that starts the line.
`index2`	number	The attribute index of the vertex that ends the line.

Returns:

Returns the index of the newly added line.

Type: number

addLineLoop(indices)

Adds a closed loop of lines joining the given vertex indices.

Parameters:

Name	Type	Description
`indices`	number	Send either an array of indexes or multiple arguments.

Returns:

Returns the index of the first added line.

Type: number

addLineStrip(indices)

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

Parameters:

Name	Type	Description
`indices`	number	Send either an array of indexes or multiple arguments.

Returns:

Returns the index of the first added line.

Type: number

addPrimitive(mode, vertices)

Adds a new primitive with the given primitive type and vertex positions.

Internally, this method uses the PD.MeshBuilder#begin and PD.MeshBuilder#end paradigm for creating the face. Refer to those methods for more details.

The minimum number of vertices for each primitive is 1 for a point, 2 for a line and 3 for a triangle. Modes that require certain multiples of vertices are gl.LINES (2) and gl.TRIANGLES (3).

Parameters:

Name	Type	Description
`mode`	number	Specifies the primitive type to be generated.
`vertices`	Array	An array of [x,y,z] vector arrays for each vertex.

Throws:

Occurs if mode is invalid or vertices is not an array of acceptable vertices.
Type TypeError

Returns:

Returns the index of the first added triangle.

Type: number

addQuad(index1, index2, index3, index4)

Adds two new triangles that share an edge.

A quad is a rectangular or trapezoidal shape consisting of two triangles. The vertex indices should be given in radial order around the quad's perimeter.

The two triangles are formed from the given indices in the order (1,2,3) and (1,3,4), so should always run in a counter-clockwise direction around the rectangle.

  4 +------+ 3
    |     /|
    |    / |
    |   /  |
    |  /   |
    | /    |
    |/     |
  1 +------+ 2

Parameters:

Name	Type	Description
`index1`	number	The attribute index of the first quad vertex.
`index2`	number	The attribute index of the second quad vertex.
`index3`	number	The attribute index of the third quad vertex.
`index4`	number	The attribute index of the fourth quad vertex.

Returns:

Returns the index of the first added triangle.

Type: number

addSketchLine(index1, index2, size [, lines] [, forward])

Adds a new sketchy line style with rear, center and forward lines.

Parameters:

Name	Type	Argument	Description
`index1`	number		The attribute index of the vertex that starts the line.
`index2`	number		The attribute index of the vertex that ends the line.
`size`	number		The size of the extension in model coordinates.
`lines`	number	<optional>	An optional number of sketchy lines to draw, defaults to 1.
`forward`	boolean	<optional>	When true only the forward extension is drawn, otherwise both.

Returns:

Returns the starting index of the first of 2 or 3 newly added lines.

Type: number

addTriangle(index1, index2, index3)

Adds a new triangle with the given vertex indices.

NOTE: This method does not do any range checking of the given attribute indices. This allows you to add all the triangle indexes first and then add the vertices later, such as when using an PD.Utils.Indexer to ensure only unique vertices are added.

Parameters:

Name	Type	Description
`index1`	number	The attribute index of the first triangle vertex.
`index2`	number	The attribute index of the second triangle vertex.
`index3`	number	The attribute index of the third triangle vertex.

Returns:

Returns the index of the newly added triangle.

Type: number

addVertex(pos_array [, color_array] [, normal_array] [, uv_array])

Adds a new vertex as an [x,y,z] coordinate array and applies optional color, normal and uv.

Parameters:

Name	Type	Argument	Description
`pos_array`	Array		This must be given as a [x,y,z] coordinate array as it is stored in the 'vertices' array directly. This allows you to share vertices that reference the same [x,y,z] array.
`color_array`	Array	<optional>	An optional color value given as a [r,g,b,a] color array, otherwise `defaultColor` is used.
`normal_array`	Array	<optional>	An optional vertex normal given as a [x,y,z] vector array, otherwise `defaultNormal` is used.
`uv_array`	Array	<optional>	An optional texture coordinate given as a [u,v] array, otherwise `defaultUV` is used.

Returns:

Returns the index of the newly added vertex, or -1 if not successfully added.

Type: number

addVertexFromObject(data)

Adds a new vertex based on properties of the given object.

NOTE: The arrays given for each property are stored directly, not copied. This allows you to share the same positions, normals, colors and texture coordinates across multiple vertices without creating many copies of the same array. This can be very memory efficient as complex rectilinear meshes often require a large number of vertices which all share a relatively small number of positions, normals, colors and uvs.

However, this means that you should take great care when altering any of the vertex data arrays themselves after they have been assigned as that data will also change for every other vertex assigned that same array. Instead, it is usually safer to assign new data arrays when modifying a vertex.

Parameters:

Name Type Description

data

object

An object containing pos, normal, color and/or uv properties.

Properties of `data`:

Name	Type	Argument	Description
`pos`	Array		A 3D position given as a [x,y,z] coordinate array in model units.
`normal`	Array	<optional>	An optional vertex normal given as a normalised [x,y,z] array in the range 0 to 1, otherwise `this.defaultNormal` is used.
`color`	Array	<optional>	An optional color value given as a [r,g,b,a] array in the range 0 to 1, otherwise `this.defaultColor` is used.
`uv`	Array	<optional>	An optional texture coordinate given as a [u,v] array in the range 0 to 1, otherwise `this.defaultUV` is used.

Throws:

Throws an error if data.pos property is not an array.
Type TypeError

Returns:

Returns the index of the newly added vertex, or -1 if not successfully added.

Type: number

begin(mode)

Starts the vertices that define a primitive or a group of like primitives.

The single argument specifies one of the many ways vertices will be interpreted. Taking n as an integer count starting at one, and N as the total number of vertices specified, the interpretations are as follows:

PD.PRIMITIVE.LINES:
Treats each pair of vertices as an independent line segment.

    0               1
    +---------------+

    +__
    3  ''--__
             ''-+
                2

Vertices n - 1 and n define line n. N/2 lines are drawn.

PD.PRIMITIVE.LINE_STRIP:
Draws a connected group of line segments from the first vertex to the last.

    0               1
    +---------------+
                   /
    +__           /
    3  ''--__    /
             ''-+
                2

Vertices n and n + 1 define line n. N-1 lines are drawn.

PD.PRIMITIVE.LINE_LOOP:
Draws a connected group of line segments from the first vertex to the last, then back to the first.

    0               1
    +---------------+
    |              /
    +__           /
    3  ''--__    /
             ''-+
                2

Vertices n and n + 1 define line n. The last line, however, is defined by vertices N and 1. N lines are drawn.

PD.PRIMITIVE.TRIANGLES:
Treats each triplet of vertices as an independent triangle.

    1     3     5
    +     +--<--+         A: 0,1,2
    |\_    \_ B |         B: 3,4,5
    |  \_    \_ |
    | A  \     \|
    +--<--+     +
    0     2     4

Vertices n, n + 1 and n + 2 define triangle n. N/3 triangles are drawn.

PD.PRIMITIVE.TRIANGLE_STRIP:
Draws a connected group of triangles. One triangle is defined for each vertex presented after the first two vertices.

    1     3     5     7
    +-->--+-->--+---  +   A: 0,1,2
    |\_ B |\_ D |\_       B: 2,1,3
    |  \_ |  \_ |  \      C: 2,3,4
    | A  \| C  \|         D: 4,3,5
    +--<--+--<--+---  +
    0     2     4     6

For even n, vertices n + 1, n and n + 2 define triangle n. For odd n, vertices n, n + 1 and n + 2 define triangle n. N-2 triangles are drawn.

PD.PRIMITIVE.TRIANGLE_FAN:
Draws a connected group of triangles. One triangle is defined for each vertex presented after the first two vertices.

    2     3     4
    +-->--+-->--+         A: 0,1,2
    |\_ B | C _/|         B: 0,2,3
    |  \_ | _/  |         C: 0,3,4
    | A  \|/  D |         D: 0,4,5
    +--<--+--<--+
    1     0     5

Vertices 0, n + 1, and n + 2 define triangle n. N-2 triangles are drawn.

Lines and triangles that are incompletely specified are not drawn. Incomplete specification results when either too few vertices are provided to specify even a single primitive or when an incorrect multiple of vertices is specified. The incomplete primitive is ignored, the rest are drawn.

The minimum number of vertices for each primitive is 1 for a point, 2 for a line and 3 for a triangle. Modes that require a certain multiple of vertices are gl.LINES (2) and gl.TRIANGLES (3).

Parameters:

Name	Type	Description
`mode`	PD.PRIMITIVE	Specifies the primitive type to be generated from vertices added between `gl.begin()` and `gl.end()`.

Throws:

Occurs if begin() is called again before end().
Type Error

Returns:

Returns this mesh object to support method chaining.

Type: PD.MeshBuilder

color(r, g, b [, a])

Sets the default color for all subsequent vertices from red, green and blue components.

This is the value used when the PD.MeshBuilder#vertex method is called, or when the PD.MeshBuilder#addVertex or PD.MeshBuilder#addVertexFromObject methods are called without a color attribute.

NOTE: All the color*() methods are designed to be as fast as possible and do not do any argument checking. Thus, this method MUST ALWAYS be called with three floating point values as its arguments. If you want to use a number/string, array or object, use the colorFromHex(), colorFromArray(), colorFromXYZ() or colorFromRGB() methods instead.

Color values should always be given in floating-point format between 0 and 1. The use of values outside this range will likely exhibit some weird behaviour but is permitted as color components are clamped to this range before they are interpolated or written into a color buffer.

Parameters:

Name	Type	Argument	Description
`r`	number		The red component of the color (0 to 1).
`g`	number		The green component of the color (0 to 1).
`b`	number		The blue component of the color (0 to 1).
`a`	number	<optional>	The alpha component of the color (0 to 1), defaults to 1.0.

Returns:

Returns this mesh object to support method chaining.

Type: PD.MeshBuilder

colorFromArray(array)

Sets the default color for all subsequent vertices from an array.

This is the value used when the PD.MeshBuilder#vertex method is called, or when the PD.MeshBuilder#addVertex or PD.MeshBuilder#addVertexFromObject methods are called without a color attribute.

NOTE: All the color*() methods are designed to be as fast as possible and do not do any argument checking. Thus, this method MUST ALWAYS be called with a single [r,g,b] color array as its argument. If you want to use components, number/string or object, use the color(), colorFromHex(), colorFromXYZ() or colorFromRGB() methods instead.

Parameters:

Name	Type	Description
`array`	Array	A [r,g,b[,a]] color array with values in the range 0 to 1.

Returns:

Returns this mesh object to support method chaining.

Type: PD.MeshBuilder

colorFromHex(color)

Sets the default color for all subsequent vertices from a hexadecimal string or number.

This is the value used when the PD.MeshBuilder#vertex method is called, or when the PD.MeshBuilder#addVertex or PD.MeshBuilder#addVertexFromObject methods are called without a color attribute.

NOTE: All the color*() methods are designed to be as fast as possible and do not do any argument checking. Thus, this method MUST ALWAYS be called with a single string or number value as its argument. If you want to use components, an array or object, use the color(), colorFromArray(), colorFromXYZ() or colorFromRGB() methods instead.

Parameters:

Name	Type	Description
`color`	string \| number	A color value as a HEX string in the form 'AARRGGBB' or a number in the form 0xRRGGBB.

Returns:

Returns this mesh object to support method chaining.

Type: PD.MeshBuilder

colorFromRGB(obj [, alpha])

Sets the default color for all subsequent vertices from a color object.

This is the value used when the PD.MeshBuilder#vertex method is called, or when the PD.MeshBuilder#addVertex or PD.MeshBuilder#addVertexFromObject methods are called without a color attribute.

NOTE: All the color*() methods are designed to be as fast as possible and do not do any argument checking. Thus, this method MUST ALWAYS be called with a single {r,g,b} color object as its argument. If you want to use components, a number/string, an array or {x,y,z} object, use the color(), colorFromHex(), colorFromArray() or colorFromXYZ() methods instead.

Parameters:

Name	Type	Argument	Description
`obj`	THREE.Color		A color value object with `r`, `g` and `b` properties with values in the range 0 to 1.
`alpha`	number	<optional>	An optional alpha value for the color, defaults to 1.

Returns:

Returns this mesh object to support method chaining.

Type: PD.MeshBuilder

colorFromXYZ(obj [, alpha])

Sets the default color for all subsequent vertices from a vector object.

This is the value used when the PD.MeshBuilder#vertex method is called, or when the PD.MeshBuilder#addVertex or PD.MeshBuilder#addVertexFromObject methods are called without a color attribute.

NOTE: All the color*() methods are designed to be as fast as possible and do not do any argument checking. Thus, this method MUST ALWAYS be called with a single {x,y,z} vector object as its argument. If you want to use components, a number/string, an array or {r,g,b} object, use the color(), colorFromHex(), colorFromArray() or colorFromRGB() methods instead.

Parameters:

Name	Type	Argument	Description
`obj`	THREE.Vector3		A color value object with `x`, `y` and `z` properties with values in the range 0 to 1.
`alpha`	number	<optional>	An optional alpha value for the color, defaults to 1.

Returns:

Returns this mesh object to support method chaining.

Type: PD.MeshBuilder

copyToPolyMesh(mesh [, matrix] [, normalMatrix])

Copies the current vertices, triangles and lines to the given mesh.

Parameters:

Name	Type	Argument	Description
`mesh`	PD.Mesh		The mesh to add geometry to.
`matrix`	THREE.Matrix4	<optional>	An optional Matrix4 to apply to each vertex.
`normalMatrix`	THREE.Matrix3	<optional>	An optional normalised Matrix3 to apply to each normal.

Returns:

Returns true if vertices for added to the mesh.

Type: boolean

createLineGeometry( [geometry])

Create a new buffer geometry object containing lines.

Parameters:

Name	Type	Argument	Description
`geometry`	THREE.BufferGeometry	<optional>	An optional buffer geometry object receive the new data.

Throws:

Throws an error if the geometry argument is not a valid THREE.BufferGeometry object.
Type TypeError

Returns:

Returns the newly created surface geometry.

Type: THREE.BufferGeometry

createMesh( [surfaceMaterial] [, surfaceMaterial] [, mesh])

Create a new buffer geometry object containing triangles.

Parameters:

Name	Type	Argument	Description
`surfaceMaterial`	THREE.Material	<optional>	The material to use when rendering triangle geometry.
`surfaceMaterial`	THREE.Material	<optional>	The material to use when rendering line geometry.
`mesh`	THREE.Mesh	<optional>	An optional mesh object receive the new surface and outline data.

Throws:

Throws an error if the mesh argument is not a valid THREE.Mesh object or it already has other children.
Type TypeError

Returns:

Returns the newly created or updated mesh.

Type: THREE.Mesh

createMeshGeometry( [geometry])

Create a new buffer geometry object containing triangles.

Parameters:

Name	Type	Argument	Description
`geometry`	THREE.BufferGeometry	<optional>	An optional buffer geometry object receive the new data.

Throws:

Throws an error if the geometry argument is not a valid THREE.BufferGeometry object.
Type TypeError

Returns:

Returns the newly created surface geometry.

Type: THREE.BufferGeometry

end()

Finalises and generates the primitive from the vertices.

Returns:

Returns this mesh object to support method chaining.

Type: PD.MeshBuilder

getVertexColor(index)

Retrieves the vertex color at the given index.

Parameters:

Name	Type	Description
`index`	number	The index of the vertex in the `colors` array.

Throws:

Throws an error if index is out of range in the colors array.
Type Error

Returns:

Returns the vertex color as a [r,g,b,a] color array.

Type: Array

getVertexNormal(index)

Retrieves the vertex normal at the given index.

Parameters:

Name	Type	Description
`index`	number	The index of the vertex in the `normals` array.

Throws:

Throws an error if index is out of range in the normals array.
Type Error

Returns:

Returns the vertex normal as a [x,y,z] vector array.

Type: Array

getVertexPos(index)

Retrieves the vertex position at the given index.

Parameters:

Name	Type	Description
`index`	number	The index of the vertex within the `positions` array.

Throws:

Throws an error if index is out of range in the positions array.
Type Error

Returns:

Returns the vertex position as a [x,y,z] coordinate array.

Type: Array

getVertexUV(index)

Retrieves the vertex texture coordinate at the given index.

Parameters:

Name	Type	Description
`index`	number	The index of the vertex in the `uvs` array.

Throws:

Throws an error if index is out of range in the colors array.
Type Error

Returns:

Returns the vertex uv as a [u,v] array.

Type: Array

hasContent()

Returns true if the mesh has vertices and at least one triangle, point or line.

Returns:

Returns true if the mesh has renderable content, else false.

Type: boolean

lineCount()

Returns the number of lines currently defined in the mesh.

Returns:

Returns the number of lines in the mesh.

Type: number

normal(x, y, z)

Sets the surface normal for all subsequent vertices from axial components.

This is the value used when the PD.MeshBuilder#vertex method is called, or when the PD.MeshBuilder#addVertex or PD.MeshBuilder#addVertexFromObject methods are called without a normal attribute.

Surface normals are stored as x, y and z components and should always be of unit length with a total magnitude of 1.0. Normals that are not of unit length may not be lit appropriately depending on the shader/material used to render them.

Parameters:

Name	Type	Description
`x`	number	The X-axis component normalised direction vector (0 to 1).
`y`	number	The Y-axis component normalised direction vector (0 to 1).
`z`	number	The Z-axis component normalised direction vector (0 to 1).

Returns:

Returns this mesh object to support method chaining.

Type: PD.MeshBuilder

normalFromArray(array)

Sets the surface normal for all subsequent vertices from an array.

This is the value used when the PD.MeshBuilder#vertex method is called, or when the PD.MeshBuilder#addVertex or PD.MeshBuilder#addVertexFromObject methods are called without a normal attribute.

Parameters:

Name	Type	Description
`array`	Array	A [x,y,z] vector array defining a normalised direction with values in the range 0 to 1.

Returns:

Returns this mesh object to support method chaining.

Type: PD.PolyMesh

normalFromObject(obj)

Sets the surface normal for all subsequent vertices from a vector object.

This is the value used when the PD.MeshBuilder#vertex method is called, or when the PD.MeshBuilder#addVertex or PD.MeshBuilder#addVertexFromObject methods are called without a normal attribute.

Parameters:

Name	Type	Description
`obj`	THREE.Vector3	An object with `x`, `y` and `z` properties defining a normalised direction vector with values in the range 0 to 1.

Returns:

Returns this mesh object to support method chaining.

Type: PD.MeshBuilder

padVertexColors()

Makes sure the colors array size matches the positions array size.

If colors need padding, this is done with the current default color.

Returns:

Returns this mesh instance to support method chaining.

Type: PD.MeshBuilder

padVertexNormals()

Makes sure the normals array size matches the positions array size.

If normals need padding, this is done with the current default normal.

Returns:

Returns this mesh instance to support method chaining.

Type: PD.MeshBuilder

padVertexUVs()

Makes sure the uvs array size matches the positions array size.

If texture coordinates need padding, this is done with the current default UV.

Returns:

Returns this mesh instance to support method chaining.

Type: PD.MeshBuilder

reset()

Clears the entire contents of the mesh.

Returns:

Returns this mesh object to support method chaining.

Type: object

setColor(color)

Sets the default color for all subsequent vertices.

This is the value used when the PD.MeshBuilder#vertex method is called, or when the PD.MeshBuilder#addVertex or PD.MeshBuilder#addVertexFromObject methods are called without a color attribute.

Parameters:

Name	Type	Description
`color`	Array	A color value given as an given as a [r,g,b[,a]] color array with values in the range 0 to 1.

Returns:

Returns this mesh object to support method chaining.

Type: PD.MeshBuilder

setNormal(array)

Sets the surface normal for all subsequent vertices.

This is the value used when the PD.MeshBuilder#vertex method is called, or when the PD.MeshBuilder#addVertex or PD.MeshBuilder#addVertexFromObject methods are called without a normal attribute.

Parameters:

Name	Type	Description
`array`	Array	The normalised direction vector as a [x,y,z] array with values in the range 0 to 1.

Returns:

Returns this mesh object to support method chaining.

Type: PD.MeshBuilder

setUV(array)

Sets the texture coordinate for all subsequent vertices.

This is the value used when the PD.MeshBuilder#vertex method is called, or when the PD.MeshBuilder#addVertex or PD.MeshBuilder#addVertexFromObject methods are called without a uv attribute.

Parameters:

Name	Type	Description
`array`	Array	The normalised texture coordinate given as an [x,y] array with values in the range 0 to 1.

Returns:

Returns this mesh object to support method chaining.

Type: PD.MeshBuilder

setVertexColor(index, color)

Sets the color data for the given vertex index.

Parameters:

Name	Type	Description
`index`	number	The index of the vertex in the `colors` array.
`color`	Array	The vertex color given as a [r,g,b,a] array in the range 0 to 1.

Throws:

Throws a TypeError if color is not a valid [r,g,b,a] vector array.

Type

TypeError
Throws an error if index is out of range in the normals array.

Type

Error

Returns:

Returns true if set, false if out of range.

Type: boolean

setVertexNormal(index, normal)

Sets the normal data for the given vertex index.

Parameters:

Name	Type	Description
`index`	number	The index of the vertex in the `normals` array.
`normal`	Array	The vertex normal given as a normalised [x,y,z] vector array in the range 0 to 1.

Throws:

Throws a TypeError if normal is not a valid [x,y,z] vector array.

Type

TypeError
Throws an error if index is out of range in the normals array.

Type

Error

Returns:

Returns true if set, false if out of range.

Type: boolean

setVertexPos(index, position)

Sets the position data for the given vertex index.

Parameters:

Name	Type	Description
`index`	number	The index of the vertex within the `positions` array.
`position`	Array	The vertex position given as a [x,y,z] coordinate array.

Throws:

Throws a TypeError if position is not a valid [x,y,z] coordinate array.

Type

TypeError
Throws an error if index is out of range in the positions array.

Type

Error

Returns:

Returns true if set, false if out of range.

Type: boolean

setVertexUV(index, uv)

Sets the texture coordinate data for the given vertex index.

Parameters:

Name	Type	Description
`index`	number	The index of the vertex in the `uvs` array.
`uv`	Array	The texture coordinate given as a [u,v] array in the range 0 to 1.

Throws:

Throws a TypeError if uv is not a valid [u,v] array.

Type

TypeError
Throws an error if index is out of range in the normals array.

Type

Error

Returns:

Returns true if set, false if out of range.

Type: boolean

triangleCount()

Returns the number of triangles currently defined in the mesh.

Returns:

Returns the number of triangles in the mesh.

Type: number

updateSharedAttributes()

Creates or updates the sharable position and color buffer attributes.

Returns:

Returns this mesh object to support method chaining.

Type: object

uv(u, v)

Sets the texture coordinate for all subsequent vertices from u and v components.

This is the value used when the PD.MeshBuilder#vertex method is called, or when the PD.MeshBuilder#addVertex or PD.MeshBuilder#addVertexFromObject methods are called without a uv attribute.

Parameters:

Name	Type	Description
`u`	number	The U component of the normalised texture coordinate (0 to 1).
`v`	number	The V component of the normalised texture coordinate (0 to 1).

Returns:

Returns this mesh object to support method chaining.

Type: PD.MeshBuilder

uvFromArray(array)

Sets the texture coordinate for all subsequent vertices from an array.

This is the value used when the PD.MeshBuilder#vertex method is called, or when the PD.MeshBuilder#addVertex or PD.MeshBuilder#addVertexFromObject methods are called without a uv attribute.

Parameters:

Name	Type	Description
`array`	Array	A [u,v] texture coordinate array with values in the range 0 to 1.

Returns:

Returns this mesh object to support method chaining.

Type: PD.PolyMesh

uvFromUV(obj)

Sets the texture coordinate for all subsequent vertices from a UV object.

This is the value used when the PD.MeshBuilder#vertex method is called, or when the PD.MeshBuilder#addVertex or PD.MeshBuilder#addVertexFromObject methods are called without a uv attribute.

Parameters:

Name	Type	Description
`obj`	object	An object with `u` and `v` properties with values in the range 0 to 1.

Returns:

Returns this mesh object to support method chaining.

Type: PD.MeshBuilder

uvFromXY(obj)

Sets the texture coordinate for all subsequent vertices from vector object.

This is the value used when the PD.MeshBuilder#vertex method is called, or when the PD.MeshBuilder#addVertex or PD.MeshBuilder#addVertexFromObject methods are called without a uv attribute.

Parameters:

Name	Type	Description
`obj`	THREE.Vector2	An object with `x` and `y` properties with values in the range 0 to 1.

Returns:

Returns this mesh object to support method chaining.

Type: PD.MeshBuilder

vertex(x, y, z)

Adds a new vertex to the mesh together with default color, normal and texture attributes.

Parameters:

Name	Type	Description
`x`	number	The X-axis position of the vertex, in model units.
`y`	number	The Y-axis position of the vertex, in model units.
`z`	number	The Z-axis position of the vertex, in model units.

Returns:

Returns this mesh object to support method chaining.

Type: PD.MeshBuilder

vertexCount()

Returns the number of vertices currently defined in the mesh.

Returns:

Returns the number of triangles in the mesh.

Type: number

vertexFromArray(array)

Adds a new vertex to the mesh together with default color, normal and texture attributes.

Parameters:

Name	Type	Description
`array`	Array	An [x,y,z] coordinate array defining the position of the vertex in model units.

Returns:

Returns this mesh object to support method chaining.

Type: PD.MeshBuilder

vertexFromXYZ(obj)

Adds a new vertex to the mesh together with default color, normal and texture attributes.

Parameters:

Name	Type	Description
`obj`	object	An object with `x`, `y` and `z` properties defining the position of the vertex in model units.

Returns:

Returns this mesh object to support method chaining.

Type: PD.MeshBuilder

Class: MeshBuilder

new MeshBuilder( [config])

Parameters:

Properties of config:

Examples

Members

colors

Type

defaultColor

Type

defaultNormal

Type

defaultUV

Type

hasChanged

Type

isMeshBuilder <readonly>

Type

lineColors

Type

lines

Type

normals

Type

positions

Type

sharedColorAttribute

Type

sharedPositionAttribute

Type

triangles

Type

uvs

Type

vertexCount

Type

Methods

addArrowLine(index1, index2, size)

Parameters:

Returns:

addDashedLine(index1, index2, size)

Parameters:

Returns:

addDraftingLine(index1, index2, size [, forward])

Parameters:

Returns:

addDraftingLines(indices, size)

Parameters:

Returns:

addLine(index1, index2)

Parameters:

Returns:

addLineLoop(indices)

Parameters:

Returns:

addLineStrip(indices)

Parameters:

Returns:

addPrimitive(mode, vertices)

Parameters:

Throws:

Returns:

addQuad(index1, index2, index3, index4)

Parameters:

Returns:

addSketchLine(index1, index2, size [, lines] [, forward])

Parameters:

Returns:

addTriangle(index1, index2, index3)

Parameters:

Returns:

addVertex(pos_array [, color_array] [, normal_array] [, uv_array])

Parameters:

Returns:

addVertexFromObject(data)

Parameters:

Properties of data:

Throws:

Returns:

begin(mode)

Properties of `config`:

Properties of `data`: