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
andtriangle 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 purposesBones
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 hierarchyWARNING: 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 ofsize
, rotation ofrotation
(in degrees) and the uv rectangleuvRect
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 sphereslices (
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-axissliceSweep (
number
) – Counterclockwise anglesegmentStart (
number
) – Counterclockwise angle relative to the z-axissegmentSweep (
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-spheresubdivisions (
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 directionssegments (
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 edgessize (
vec3
) – Half of the side length in x, y and z directionsslices – 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-planesize (
number
) – Half of the length of the cone along the y-axisslices (
integer
) – Number of subdivisions around the y-axissegments (
integer
) – Number of subdivisions along the y-axisrings (
integer
) – Number of subdivisions of the capstart (
number
) – Counterclockwise angle around the y-axis relative to the positive x-axissweep (
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-planesize – Half of the length of the cylinder along the y-axis
slices (
integer
) – Number of subdivisions around the y-axissegments (
number
) – Number of subdivisions along the y-axisrings – 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-planesize – Half of the length capsule along the y-axis
slices (
integer
) – Number of subdivisions around the y-axissegments (
number
) – Number of subdivisions along the z-axisrings – 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-planeinnerRadius (
number
) – Radius of the inner circle on the xz-planeslices (
integer
) – Number of subdivisions around the y-axisrings (
integer
) – Number of subdivisions along the radiusstart (
number
) – Counterclockwise angle relative to the y-axissweep (
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 directionsegments (
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) ringmajor (
number
) – Radius of the major (outer) ringslices (
integer
) – Subdivisions around the minor ringsegments (
integer
) – Subdivisions around the major ringminorStart (
number
) – Counterclockwise angle relative to the xz-planeminorSweep (
number
) – Counterclockwise angle around the circlemajorStart (
number
) – Counterclockwise angle around the y-axis relative to the x-axismajorSweep (
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
) –