Back to Beyond the Codea in-app reference

mesh() function

Introduction

Codea's in-app reference documents most of the mesh() function. The function returns a userdata value that represents a mesh of triangles (each specified by three vertices in 3D space):

myMesh = mesh() -- myMesh now references a mesh userdata value

myMesh:resize()

The mesh() constructor sets aside memory, initially, for 3,000 vertices (equivalent to 500 rectangles) (and their associated colours and UV (texture co-ordinates). If additional capacity is required (for example, by the myMesh:addRect() function - see below), the existing capacity is doubled.

Before version 1.4.3 of Codea, there was a bug that caused the last vertex in the mesh to be deleted when the capacity of the buffer doubled. From version 1.4.3, that bug has been fixed.

The myMesh:resize(newLength] syntax is used to set the length of an existing mesh to the newLength.

myMesh["vertices"] or myMesh.vertices

The myMesh["vertices"] or myMesh.vertices syntax is used: (1) to call a function that sets the vertices of the mesh userdata; or (2) to call a function that returns the vertices of the mesh userdata as a table.

myMesh = mesh()
vt1 = {vec2(0, 0), vec2(100, 0), vec2(0, 100)}
myMesh.vertices = vt1
vt2 = myMesh.vertices

After the vertices of a mesh have been set using the .vertices function, changing the table referenced by vt1 (in the example above) has no effect on the mesh.

myMesh:addRect()

The myMesh:addRect() syntax is used to call a function that adds two triangles to the mesh in the shape of a rectangle, with the colours of the vertices set to opaque white (color(255, 255, 255, 255)). The function returns a value that indexes the rectangle added.

myMesh = mesh()
index1 = myMesh:addRect(50, 50, 100, 100)
index2 = myMesh:addRect(150, 50, 100, 100)
print(index1, index2) -- Outputs 1       2

The six vertices of the rectangle at rectangle index n are indexed at n * 6 - 5 to n * 6, by myMesh:vertex().

If adding a rectangle would exceed the capacity set aside for the mesh, the capacity is doubled.

Before version 1.4.3 of Codea, there was a bug that caused the last vertex in the mesh to be deleted when the capacity of the buffer doubled. The fix for the bug has been released in version 1.4.3.

myMesh:vertex()

The myMesh:vertex() syntax is used to call a function that either: (1) returns a vertex in a mesh, as a vec3 userdata; or (2) modifies an existing vertex in a mesh.

myMesh = mesh()
myMesh:addRect(50, 50, 100, 100)
for i = 1, 6 do
    print (myMesh:vertex(i))
end

-- Output:
-- (0.000000, 100.000000, 0.000000)
-- (0.000000, 0.000000, 0.000000)
-- (100.000000, 0.000000, 0.000000)
-- (0.000000, 100.000000, 0.000000)
-- (100.000000, 0.000000, 0.000000)
-- (100.000000, 100.000000, 0.000000)

myMesh["colors"] or myMesh.colors

The myMesh["colors"] or myMesh.colors syntax is used: (1) to call a function that sets the colours of the vertices of the mesh userdata; or (2) to call a function that returns the colours of the mesh userdata, as a table of color userdata values.

myMesh = mesh()
vt1 = {vec2(0, 0), vec2(100, 0), vec2(0, 100)}
vct1 = {color(255, 0, 0), color(0, 255, 0), color(0, 0, 255)}
myMesh.vertices = vt1
myMesh.colors = vct1
vct2 = myMesh.colors

After the colours of the vertices of a mesh have been set using the .colors function, changing the table referenced by vct1 (in the example above) has no effect on the mesh.

myMesh:color()

The myMesh:color() syntax is used to call a function that either: (1) returns the colour of a vertex in a mesh, as a color userdata value; or (2) modifies the colour of an existing vertex in a mesh.

myMesh = mesh()
myMesh:addRect(50, 50, 100, 100)
myMesh:color(3, 255, 0, 0, 255) -- Change colour of third vertex in the mesh
for i = 1, 6 do
    print (myMesh:color(i))
end

-- Output:
-- (255, 255, 255, 255)
-- (255, 255, 255, 255)
-- (255, 0, 0, 255)
-- (255, 255, 255, 255)
-- (255, 255, 255, 255)
-- (255, 255, 255, 255)

myMesh:setColors()

The myMesh:setColors(...) syntax (equivalent to myMesh.setColors(myMesh, ...)) is used to call a function that sets the colour of every vertex in the mesh.

myMesh["texture"] or myMesh.texture

myMesh["texture"] or myMesh.texture can be used to refer to a string or image userdata to be used as the texture the mesh.

myMesh = mesh()
vt1 = {vec2(0, 0), vec2(100, 0), vec2(0, 100)}
vUVt1 = {vec2(0, 0), vec2(1, 0), vec2(0, 1)}
myMesh.vertices = vt1
myMesh:setColors(255, 255, 255, 255)
myMesh.texture = "Planet Cute:Icon" -- Set the texture for the mesh, using a string
myMesh.texCoords = vUVt1

myMesh["texCoords"] or myMesh.texCoords

The myMesh["texCoords"] or myMesh.texCoords syntax is used: (1) to call a function that sets the UV (texture co-ordinates) of the vertices of the mesh userdata; or (2) to call a function that returns the UV of the mesh userdata, as a table of vec2 userdata values.

myMesh = mesh()
vt1 = {vec2(0, 0), vec2(100, 0), vec2(0, 100)}
vUVt1 = {vec2(0, 0), vec2(1, 0), vec2(0, 1)} -- A table of UV for vertices
myMesh.vertices = vt1
myMesh:setColors(255, 255, 255, 255)
myMesh.texture = "Planet Cute:Icon"
myMesh.texCoords = vUVt1 -- Set the UV for the mesh

After the UV of the vertices of a mesh have been set using the .texCoords function, changing the table referenced by vUVt1 (in the example above) has no effect on the mesh.

myMesh:texCoord()

The myMesh:texCoord() syntax is used to call a function that either: (1) returns the UV (texture co-ordinates of a vertex in a mesh, as a vec2 userdata value; or (2) modifies the UV of an existing vertex in a mesh.

myMesh:draw()

The myMesh:draw() syntax (equivalent to myMesh.draw(myMesh)) is used to call a function that draws the mesh.

If the colours of the vertices are not set, then their are taken to be the colour last set by fill() function. If a texture is set for the mesh, then the colours tint the texture.

If both a texture and the UV (texture co-ordinates) are set for the mesh, then the texture, tinted by the colours of its vertices, is used to render the mesh.