display.newMesh()

类型 函数
库 display.*
返回值 ShapeObject（形状对象）
修订 版本 2024.3703
关键词 形状, 网格, 矢量对象
另请参阅 形状 — 路径、填充、描边 (指南)
显示对象 (指南)

概述

通过提供形状的顶点绘制网格形状。局部原点位于网格的中心，锚点初始化为此局部原点。

语法

display.newMesh( [parent,] [x, y,] options )

display.newMesh( options )
parent (可选)

GroupObject（组对象）. 用于插入网格的可选显示组。

x / y (可选)

数字. 对象相对于其父级的位置。

options (必需)

表. 包含网格选项的表 — 有关详细信息，请参阅下一节。

选项参考

options 表接受以下网格参数

vertices (必需)

数组. 构成网格的顶点的 **x** 和 **y** 坐标数组。根据 mode 参数使用这些顶点构建网格。

parent (可选)

GroupObject（组对象）. 用于插入网格的可选显示组。如果在此处包含，它将覆盖在 options 表之外指定的任何 parent 定义。

x / y (可选)

数字. 对象相对于其父级的位置。如果在此处包含，它们将覆盖在 options 表之外指定的任何 x 或 y 定义。

mode (可选)

字符串. 指示如何使用提供的顶点形成网格的字符串。默认为 "triangles"。可接受的值为 "triangles"、"strip"、"fan" 或 "indexed"。有关每种模式的描述，请参阅下面的网格绘制模式。

indices (可选)

数组. "indexed" 类型的 mode 所需的索引数组。例如，要模拟 "strip" 模式的行为，此参数的值可以是{ 1,2,3, 2,3,4, 3,4,5 }.

zeroBasedIndices (可选)

布尔值. 默认值为 false 的便捷参数。如果设置为 true，则 indices 数组将被视为从零开始的数组。

uvs (可选)

数组. 构成网格的顶点的 **u** 和 **v** 纹理坐标数组。如果省略或无效，将根据标准化的 vertices 值自动分配 UV。纹理坐标是标准化坐标，其中 0,0 是图像的左上角，1,1 是图像的右下角。

网格绘制模式

triangles/indexed（三角形/索引）

mode 为 "triangles" 或 "indexed" 的网格由三个连续顶点的不相交组形成。"triangles" 模式的示例可以具有索引为 1,2,3、4,5,6 和 7,8,9 的顶点。但是请注意，"triangles" 模式可能会导致多个三角形共享重复的顶点 — 要避免这种情况，您可以使用 "indexed" 类型并定义一个 indices 表，其中包含指向所用顶点的索引。

虽然这些方法可以用来编码任何网格，但如果一个顶点被多个三角形使用，它们都会有一些重复。在 "triangles" 的情况下，这是顶点本身。在 "indexed" 的情况下，这是顶点索引。重复索引的成本要低得多，因为它们是单个整数，而不是具有坐标和纹理坐标的整个顶点。

在某些情况下，可以通过 "strip" 或 "fan" 模式避免这种重复（请参阅下文）。

strip（条带）

mode 为 "strip" 的网格由三个连续顶点形成。例如，可以具有索引为 1,2,3、2,3,4 和 3,4,5 的顶点。有关此类型的更多信息，请参阅此处。

fan（扇形）

mode 为 "fan" 的网格由一个初始顶点和两个结束顶点形成。例如，可以具有索引为 1,2,3、1,3,4 和 1,4,5 的顶点。有关此类型的更多信息，请参阅此处。

注意事项

方法

（继承自 ShapeObject（形状对象） 的属性）

形状对象具有一个 path 属性，该属性公开用于操作网格的方法。大多数方法都接受 index 参数，该参数是相关顶点的 Lua 数组索引（第一个顶点的索引为 1）。所有参数均为 数字。

object.path:setVertex()

将索引为 index 的顶点设置为坐标 x 和 y

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

返回对应于顶点坐标的两个 数字

object.path:getVertex( index )
object.path:setUV()

将索引为 index 的顶点设置为纹理坐标 u 和 v

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

返回对应于顶点纹理坐标的两个 数字

object.path:getUV( index )
object.path:getVertexOffset()

返回两个 数字，对应于将原点移动到网格中心时应用的水平和垂直偏移量。您可以通过这些值偏移网格对象，以补偿初始偏移并在世界坐标中获得精确的顶点位置。

object.path:getVertexOffset()

请注意，假设未应用缩放，则坐标为 x 和 y 的顶点的世界坐标将分别为mesh.x + x - offsetX和mesh.y + y - offsetY。考虑以下命令，该命令将对象按偏移量移动并将位于 0,0 处的顶点放入先前的对象原点

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

更新网格的 vertices、uvs 和 indices

object.path:update( options )

options 表接受用于更新网格的 vertices、uvs 和 indices。这些都是可选的，可以随意排除

local options = {
    vertices = {},
    uvs = {},
    indices = {}
}
mesh.path:update( options )

示例

三角形模式
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 )
索引模式
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 )
条带模式
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 )
扇形模式
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 )