mesh

Creating and drawing a basic mesh
function setup()
   -- create a sphere mesh
   msh = mesh.sphere()
end

function draw()
   background(64)
   -- draw the mesh every frame
   msh:draw()
end
class mesh

Represents a drawable shape made of vertices and primitives (typically triangles)

Vertices

Each vertex contains a number of attributes:

  • position (vec3) - the position

  • normal (vec3) - the surface normal orientation

  • tangent (vec4) - the tangent to the surface normal (automatically calculated)

  • uv (vec2) - the texture coordinate (uv) of the vertex

  • color - the color

  • boneWeights - the weight of each bone’s influence on this vertex (used for skinning)

  • boneIndices - the index of each bone that can influence this vertex (used for skinning)

These attributes can be get/set directly by setting all of them at once via tables (i.e. msh.positions = {...}) or by using methods that set attributes one vertex at a time (i.e. msh:position(i, p))

Triangle Meshes

A triangle mesh is drawn using its vertices which are connected using triangles primitives. Every group of consecutive three indices make up an individual triangle

There are plans to add more primitive types such as points, lines, triangle fans and triangle strips

Shaders and Materials

Both shaders and materials can be applied to a mesh. Setting a shader/material will override any previous shaders/materials on the mesh

When no shader/material is set, the default unlit mesh material will be used instead

Sub-Meshes

A mesh consists of one or more sub-meshes, each of which can have a distinct shader/material. The submeshIndex property can be used to switch between the current active submeshes for mesh editing purposes

Bones

TODO

static mesh([submeshCount])

Create an empty mesh

Parameters:

submeshCount (integer) – The number of submeshes that this mesh will be created with (optoinal)

static read(key)

Loads a mesh from a file

The following mesh formats are currently supported:

  • GLTF / GLB

  • FBX

  • OBJ

  • STL

Skinned animations are supported but morph targets are currently not

Saving meshes is not currently supported

Parameters:

key – The asset key to load

texture: image

The mesh texture, used by the default mesh shader (and accessible to custom shaders as well) for basic surface textures

shader: shader

Custom shader for this mesh, used when mesh:draw() is invoked

material: material

The same as assigning a shader but with a material instead

submeshIndex: integer

The current sub-mesh index. Useful for multi-material meshes

submeshCount: integer

The total number of sub-meshes within this mesh

vertexCount: integer

The total number of vertices in the currently selected sub-mesh

3.x compatiblity note: This was originally called count

indexCount: integer

The total number of indices in the currently selected sub-mesh

3.x compatiblity note: meshes originally did not contain indices and therefore did not have an index count

bounds: bounds.abbb

The local bounds of this mesh (no scaling or rotation applied)

positions: table<vec3>

Gets/sets the positions of the mesh vertices

normals: table<vec3>

Gets/sets the normals of the mesh vertices

colors: table<color>

Gets/sets the colors of the mesh vertices

uvs: table<vec2>

Gets/sets the uvs of the mesh vertices

indices: table<integer>

Gets/sets the indices of the mesh

vertices: table<vec2|vec3>

Gets/sets the positions of the mesh vertices while also ensuring that each set of three indices match their corresponding vertices

3.x compatiblity note: works the same as the original vertices property

texCoords: table<vec2>

Gets/sets the uvs of the mesh vertices

3.x compatiblity note: works the same as the uvs property for the sake of backwards compatiblity

root: entity

Meshes loaded via mesh.read() may contain sub-objects and bones used for animations, these can be accessed as entities in a simple scene-like hierarchy

WARNING: do not attempt to delete any nodes within the root as it may have unintended side effects

animations: table<animation>

Contains the list of all animations for this mesh

Mesh Drawing

draw([instances])

Draws the mesh to the screen with the current camera, matrix and context settings

drawIndirect(indirectBuffer[, start = 0, num  = 1])

Draws the mesh indirectly using indirectBuffer

Used in combination with compute shaders for indirect drawing operations

Mesh Manipulation

addRect(position, size[, rotation, uvRect])

Appends a 2D rectangle to this mesh centered at position with the size of size, rotation of rotation (in degrees) and the uv rectangle uvRect

This function supports dynamic number type arguments

Returns:

the index of the new rectangle

Return type:

integer

setRect(index, position, size[, rotation])

Sets existing rectangle position, size and rotation using an index from a previous call to addRect()

setRectTex(index, uvRect)

Sets existing rectangle uvs using an index from a previous call to addRect()

setRectColor(index, color)

Sets existing rectangle color using an index from a previous call to addRect()

resizeVertices(size)

Sets the number of vertices in the mesh (must be positive)

resizeIndices(size)

Sets the number of indices in the mesh (must be positive)

addElement(p1, p2, p3[, ...])

Adds a new element to the mesh consisting of N indices (i.e. add three indices for a new triangle)

clear()

Clears the mesh, reducing vertices and indices to zero

position(index)
position(index, position)

Gets/sets the position of the vertex at index

normal(index)
normal(index, normal)

Gets/sets the normal of the vertex at index

color(index)
color(index, color)

Gets/sets the color of the vertex at index

uv(index)
uv(index, uv)

Gets/sets the uv of the vertex at index

index(index)
index(index, i)

Gets/sets the index at index

Mesh Generation

static sphere([radius = 1, slices = 32, segments = 16, sliceStart = 0, sliceSweep = 360, segmentStart = 0, segmentSweep = 180])

Generates a sphere mesh with various settings

Parameters:

  • radius (number) – The radius of the sphere

  • slices (number) – Subdivisions around the z-azis (longitudes)

  • segments (number) – Subdivisions along the z-azis (latitudes)

  • sliceStart (number) – Counterclockwise angle around the z-axis relative to x-axis

  • sliceSweep (number) – Counterclockwise angle

  • segmentStart (number) – Counterclockwise angle relative to the z-axis

  • segmentSweep (number) – Counterclockwise angle

static icoSphere([radius = 1, subdivisions = 4])

Generates an ico-sphere, aka spherical subdivided icosahedron

Parameters:

  • radius (number) – The radius of the ico-sphere

  • subdivisions (number) – Subdivisions for the ico-sphere

static box([size = vec3(1, 1, 1), segments = vec3(8, 8, 8)])

Rectangular box centered at origin aligned along the x, y and z axis

Parameters:

  • size (vec3) – Half of the side length in x, y and z directions

  • segments (vec3) – The number of segments in x, y and z directions

static roundedBox([radius = 0.25, size = vec3(1, 1, 1), slices = 4, segments = vec3(8, 8, 8)])

Rectangular box with rounded edges centered at origin aligned along the x, y and z axis

Parameters:

  • radius (number) – The corner radius of the rounded edges

  • size (vec3) – Half of the side length in x, y and z directions

  • slices – The number of subdivisions in the rounded edges / corners

  • segments (vec3) – The number of segments in x, y and z directions

static cone([radius = 1, size = 1, slices = 32, segments = 8, rings = 4, start = 0, sweep = 360])

A cone with a cap centered at origin pointing towards positive y-axis

Parameters:

  • radius (number) – Radius of the flat (negative z) end along the xz-plane

  • size (number) – Half of the length of the cone along the y-axis

  • slices (integer) – Number of subdivisions around the y-axis

  • segments (integer) – Number of subdivisions along the y-axis

  • rings (integer) – Number of subdivisions of the cap

  • start (number) – Counterclockwise angle around the y-axis relative to the positive x-axis

  • sweep (number) – Counterclockwise angle around the y-axis

static cylinder([radius = 1, size = 1, slices = 32, segments = 8, rings = 4, start = 0, sweep = 360])

Capped cylinder centered at origin aligned along the y-axis

Parameters:

  • radius (number) – Radius of the flat (negative z) end along the xz-plane

  • size – Half of the length of the cylinder along the y-axis

  • slices (integer) – Number of subdivisions around the y-axis

  • segments (number) – Number of subdivisions along the y-axis

  • rings – Number of subdivisions of the cap

  • start – Counterclockwise angle around the y-axis relative to the positive x-axis

  • sweep – Counterclockwise angle around the y-axis

static capsule([radius = 1, size = 1, slices = 32, segments = 8, rings = 4, start = 0, sweep = 360])

Capsule centered at origin aligned along the y-axis

Parameters:

  • radius (number) – Radius of the capsule along the xz-plane

  • size – Half of the length capsule along the y-axis

  • slices (integer) – Number of subdivisions around the y-axis

  • segments (number) – Number of subdivisions along the z-axis

  • rings – Number of subdivisions on the caps

  • start – Counterclockwise angle around the y-axis relative to x-axis

  • sweep – Counterclockwise angle around the y-axis

static disk([radius = 1, innerRadius = 1, slices = 32, rings = 4, start = 0, sweep = 360])

A circular disk centered at origin on the xz-plane

Parameters:

  • radius (number) – Outer radius of the disk on the xz-plane

  • innerRadius (number) – Radius of the inner circle on the xz-plane

  • slices (integer) – Number of subdivisions around the y-axis

  • rings (integer) – Number of subdivisions along the radius

  • start (number) – Counterclockwise angle relative to the y-axis

  • sweep (number) – Counterclockwise angle

static plane([size = vec2(1, 1), segments = vec2(8, 8)])

A flat plane centered at the origin on the xy-plane

Parameters:

  • size (vec2) – Half of the side length in x and z direction

  • segments (vec2) – Number of subdivisions in the x and z directions

static torus([minor = 0.25, major = 1, slices = 32, segments = 8, minorStart = 0, minorSweep = 360, majorStart = 0, majorSweep = 360])

Generates a torus

Parameters:

  • minor (number) – Radius of the minor (inner) ring

  • major (number) – Radius of the major (outer) ring

  • slices (integer) – Subdivisions around the minor ring

  • segments (integer) – Subdivisions around the major ring

  • minorStart (number) – Counterclockwise angle relative to the xz-plane

  • minorSweep (number) – Counterclockwise angle around the circle

  • majorStart (number) – Counterclockwise angle around the y-axis relative to the x-axis

  • majorSweep (number) – Counterclockwise angle around the y-axis

static torusKnot([radius = 1, size = 1, slices = 32, segments = 8, rings = 4, start = 0, sweep = 360])

Generates a torus knot

Parameters:

  • p (number)

  • q (number)

  • slices (integer)

  • segments (integer)

static teapot([subdivisions = 8])

Generates the Utah teapot using the original data The lid is pointing towards the z axis and the spout towards the x axis

Parameters:

segments (integer)