display.newMesh()

parent _^(optional)

GroupObject. An optional display group in which to insert the mesh.

x / y _^(optional)

Numbers. The location of the object relative to its parent.

options _^(required)

Table. Table containing options for the mesh — see the next section for details.

vertices _^(required)

Array. An array of x and y coordinates of vertices forming the mesh. Meshes are built with these vertices depending on the mode parameter.

parent _^(optional)

GroupObject. An optional display group in which to insert the mesh. If included here, this will override any parent definition specified outside of the options table.

x / y _^(optional)

Numbers. The location of the object relative to its parent. If included here, these will override any x or y definitions specified outside of the options table.

mode _^(optional)

String. String indicating how the mesh should be formed with the provided vertices. Default is "triangles". Acceptable values are "triangles", "strip", "fan", or "indexed". See Mesh Draw Modes below for a description of each mode.

indices _^(optional)

Array. An array of indices required for mode type of "indexed". For example, to mimic the behavior of the "fan" mode, the value of this parameter could be { 1,2,3, 2,3,4, 3,4,5 }.

zeroBasedIndices _^(optional)

Boolean. Convenience parameter with default of false. If set to true, the indices array will be treated as a zero-based array.

uvs _^(optional)

Array. An array of u and v texture coordinates of vertices forming the mesh. If omitted or invalid, UVs will be automatically assigned based on normalized vertices values. Texture coordinates are normalized coordinates where 0,0 is the top-left corner of the image and 1,1 is the bottom-right corner of the image.

Meshes with a mode of "strip" are formed with three consecutive vertices. An example could have vertices with indices 1,2,3, 2,3,4, and 3,4,5. For more information on this type, see here.

fan

Meshes with a mode of "fan" are formed with an initial vertex and two ending vertices. An example could have vertices with indices 1,2,3, 1,3,4, and 1,4,5. For more information on this type, see here.

object.path:setVertex()

Sets the vertex with index index to coordinates x and y:

object.path:setVertex( index, x, y )

object.path:getVertex()

Returns two numbers corresponding to a vertex's coordinates:

object.path:getVertex( index )

object.path:setUV()

Sets the vertex with index index to texture coordinates u and v:

object.path:setUV( index, u, v )

object.path:getUV()

Returns two numbers corresponding to a vertex's texture coordinates:

object.path:getUV( index )

object.path:getVertexOffset()

Returns two numbers corresponding to the horizontal and vertical offsets applied when moving the origin to the center of the mesh. You can offset the mesh object by these values to compensate for initial shift and get precise vertex positions in world coordinates.

object.path:getVertexOffset()

Note that a vertex with coordinates x and y will have world coordinates of mesh.x + x - offsetX and mesh.y + y - offsetY respectively, assuming no scaling is applied. Consider the following command which shifts the object by the offsets and puts a vertex at 0,0 into the previous object origin:

mesh:translate( mesh.path:getVertexOffset() )

Triangles Mode

local mesh = display.newMesh(
    {
        x = 100,
        y = 100,
        mode = "triangles",
        vertices = {
            0,0, 50,0, 0,100,
            0,100, 50,0, 100,100,
            100,100, 50,0, 100,0
        },
        uvs = {
            0,0, 0.5,0, 0,1,
            0,1, 0.5,0, 1,1,
            1,1, 0.5,0, 1,0
        }
    })
mesh:translate( mesh.path:getVertexOffset() )  -- Translate mesh so that vertices have proper world coordinates

mesh.fill = { type="image", filename="cat.png" }

local vertexX, vertexY = mesh.path:getVertex( 3 )
mesh.path:setVertex( 3, vertexX, vertexY-10 )

Indexed Mode

local mesh = display.newMesh(
    {
        x = 100,
        y = 100,
        mode = "indexed",
        vertices = {
            0,0, 0,100, 50,0, 100,100, 100,0
        },
        indices = {
            1,2,3,
            2,3,4,
            3,4,5
        }
    })
mesh:translate( mesh.path:getVertexOffset() )  -- Translate mesh so that vertices have proper world coordinates

mesh.fill = { type="image", filename="cat.png" }

local vertexX, vertexY = mesh.path:getVertex( 3 )
mesh.path:setVertex( 3, vertexX, vertexY-10 )

Strip Mode

local mesh = display.newMesh(
    {
        x = 100,
        y = 100,
        mode = "strip",
        vertices = {
            0,0, 0,100,
            50,0, 100,100,
            100,0
        }
    })
mesh:translate( mesh.path:getVertexOffset() )  -- Translate mesh so that vertices have proper world coordinates

mesh.fill = { type="image", filename="cat.png" }

local vertexX, vertexY = mesh.path:getVertex( 3 )
mesh.path:setVertex( 3, vertexX, vertexY-10 )

Fan Mode

local mesh = display.newMesh(
    {
        x = 100,
        y = 100,
        mode = "fan",
        vertices = {
            50,0,
            0,0, 0,100, 100,100, 100,0
        }
    })
mesh:translate( mesh.path:getVertexOffset() )  -- Translate mesh so that vertices have proper world coordinates

mesh.fill = { type="image", filename="cat.png" }

local vertexX, vertexY = mesh.path:getVertex( 3 )
mesh.path:setVertex( 3, vertexX, vertexY-10 )