SurfaceTool

Inherits: Reference < Object

创建几何图形的辅助工具。

描述

SurfaceTool 用于通过单独指定顶点属性来构造 Mesh。可以用来从脚本中构造 Mesh。在调用 add_vertex 之前，需要添加除索引之外的所有属性。例如，添加顶点颜色和 UV。

var st = SurfaceTool.new()
st.begin(Mesh.PRIMITIVE_TRIANGLES)
st.add_color(Color(1, 0, 0))
st.add_uv(Vector2(0, 0))
st.add_vertex(Vector3(0, 0, 0))

上面的 SurfaceTool 现在包含了一个三角形的顶点，它有 UV 坐标和指定的 Color。如果在没有调用 add_uv 或 add_color 的情况下添加另一个顶点，那么就会使用最后的值。

顶点属性必须在调用 add_vertex 之前传递。如果不这样做，在提交顶点信息到网格时将会导致错误。

此外，在添加第一个顶点之前使用的属性决定了网格的格式。例如，如果你只为第一个顶点添加 UV，你就不能为任何后续的顶点添加颜色。

参阅 ArrayMesh、ImmediateGeometry 和 MeshDataTool 以了解程序式几何体的生成。

注意：Godot 对三角形基本模式的正面使用顺时针缠绕顺序。

教程

• 3D Voxel Demo

方法

方法说明

• void add_bones ( PoolIntArray bones )

指定下一个顶点所使用的骨骼数组。 bones 必须包含 4 个整数。

• void add_color ( Color color )

指定下一个顶点所使用的 Color。如果每个顶点都需要设置此信息，而您未能为第一个顶点提交此信息，此信息可能根本就不会被使用。

注意：材质必须启用SpatialMaterial.vertex_color_use_as_albedo才能使顶点颜色可见。

• void add_index ( int index )

如果您使用索引顶点，则向索引数组添加索引。在添加顶点之前不需要调用。

• void add_normal ( Vector3 normal )

指定下一个顶点所使用的法线。如果每个顶点都需要设置此信息，而你没有为第一个顶点提交，则可能根本无法使用此信息。

• void add_smooth_group ( bool smooth )

指定当前顶点（如果仅使用顶点数组）或当前索引（如果还使用索引数组）是否应使用平滑法线进行法线计算。

• void add_tangent ( Plane tangent )

指定下一个顶点所使用的切线。如果每个顶点都需要设置此信息，而你没有为第一个顶点提交，则可能根本无法使用此信息。

• void add_triangle_fan ( PoolVector3Array vertices, PoolVector2Array uvs=PoolVector2Array( ), PoolColorArray colors=PoolColorArray( ), PoolVector2Array uv2s=PoolVector2Array( ), PoolVector3Array normals=PoolVector3Array( ), Array tangents=[ ] )

将一个由数组数据组成的三角扇插入正在构建的 Mesh 中。

需要将基本类型设置为 Mesh.PRIMITIVE_TRIANGLES。

• void add_uv ( Vector2 uv )

指定下一个顶点所使用的 UV 坐标。如果每个顶点都需要设置此信息，而您未能为第一个顶点提交此信息，此信息可能根本就不会被使用。

• void add_uv2 ( Vector2 uv2 )

指定可选的第二组UV坐标，用于next顶点。如果每个顶点都需要设置这个信息，而你没有为第一个顶点提交这个信息，此信息可能根本就不会被使用。

• void add_vertex ( Vector3 vertex )

指定当前顶点的位置。应在指定其他顶点属性（例如颜色、UV）后调用。

• void add_weights ( PoolRealArray weights )

指定下一个顶点所使用的权重值。 weights 必须包含 4 个值。如果每个顶点都需要设置此信息，而您未能为第一个顶点提交此信息，此信息可能根本就不会被使用。

• void append_from ( Mesh existing, int surface, Transform transform )

将指定 Mesh 表面的顶点应用 Transform 后，追加到当前的顶点数组中。

注意： 在 Thread 中使用 append_from 会更慢，因为 GPU 必须将数据送回 CPU，会把主线程暂停（因为 OpenGL 是线程不安全的）。请考虑先把该网格复制一份，转成 ArrayMesh 后再手动添加顶点。

• void begin ( PrimitiveType primitive )

在添加任何顶点之前被调用。接收原始类型作为参数（例如：原始三角形Mesh.PRIMITIVE_TRIANGLES）。

• void clear ( )

清除到目前为止传入表面工具(surface tool)的所有信息。

• ArrayMesh commit ( ArrayMesh existing=null, int flags=2194432 )

从传入的当前信息返回构造的 ArrayMesh。如果现有的 ArrayMesh 作为参数传入，则会向现有的 ArrayMesh 添加额外的面。

如果启用压缩，则默认标志为 Mesh.ARRAY_COMPRESS_DEFAULT。如果禁用压缩，则默认标志为 Mesh.ARRAY_FLAG_USE_OCTAHEDRAL_COMPRESSION。有关其他标志，参阅 ArrayFormat 中的 ARRAY_COMPRESS_* 常量。

• Array commit_to_arrays ( )

将数据提交给ArrayMesh.add_surface_from_arrays使用的相同格式。这样你就可以使用ArrayMesh的API接口进一步处理网格数据。

• void create_from ( Mesh existing, int surface )

从现有的网格 Mesh 创建一个顶点数组。

• void create_from_blend_shape ( Mesh existing, int surface, String blend_shape )

从现有 Mesh 的指定混合形状创建一个顶点数组。这可用于从混合形状中提取特定姿势。

• void deindex ( )

通过扩展顶点数组移除索引数组。

• void generate_normals ( bool flip=false )

从顶点生成法线，因此您不必手动执行。如果 flip 为 true，则生成的法线将被反转。 generate_normals 应在生成几何体之后 调用，在之前使用 commit 或 commit_to_arrays 提交网格。为了正确显示法线贴图表面，您还必须使用 generate_tangents 生成切线。

注意： generate_normals 仅当基本类型设置为 Mesh.PRIMITIVE_TRIANGLES 时才有效。

• void generate_tangents ( )

为每个顶点生成切向量。要求每个顶点已经设置了 UV 和法线，参阅 generate_normals。

• void index ( )

通过创建索引数组来缩小顶点数组。这可以避免顶点重复而提高性能。

• void set_material ( Material material )

设置要由您正在构建的 Mesh 使用的 Material。