SurfaceTool

继承： RefCounted < Object

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

描述

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

GDScriptC#

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

var st = new SurfaceTool();
st.Begin(Mesh.PrimitiveType.Triangles);
st.SetColor(new Color(1, 0, 0));
st.SetUV(new Vector2(0, 0));
st.AddVertex(new Vector3(0, 0, 0));

上面的 SurfaceTool 现在就包含了三角形中的一个顶点，具有 UV 坐标和指定的 Color。如果又添加了一个顶点，而没有调用 set_uv 或 set_color，则会使用之前的值。

顶点属性必须在调用 add_vertex 之前传递。不传的话，就会在向网格提交顶点信息时出错。

另外，添加第一个顶点前所使用的属性会用来确定网格的格式。例如，如果你只为第一个顶点添加了 UV，那么你就无法为后续的顶点添加颜色。

程序式几何体生成另见 ArrayMesh、ImmediateMesh 以及 MeshDataTool。

注意：Godot 中三角形图元模式的正面使用顺时针 缠绕顺序。

教程

• 使用 SurfaceTool

• 3D 体素演示

方法

枚举

enum CustomFormat: 🔗

CustomFormat CUSTOM_RGBA8_UNORM = 0

将传递给 set_custom 的数据限制到无符号归一化的 0 到 1 范围内，每个通道存储 8 个比特位。见 Mesh.ARRAY_CUSTOM_RGBA8_UNORM。

CustomFormat CUSTOM_RGBA8_SNORM = 1

将传递给 set_custom 的数据限制到带符号归一化的 -1 到 1 范围内，每个通道存储 8 个比特位。见 Mesh.ARRAY_CUSTOM_RGBA8_SNORM。

CustomFormat CUSTOM_RG_HALF = 2

将传递给 set_custom 的数据存储为半精度浮点数，只使用红色和绿色通道。见 Mesh.ARRAY_CUSTOM_RG_HALF。

CustomFormat CUSTOM_RGBA_HALF = 3

将传递给 set_custom 的数据存储为半精度浮点数，使用所有颜色通道。见 Mesh.ARRAY_CUSTOM_RGBA_HALF。

CustomFormat CUSTOM_R_FLOAT = 4

将传递给 set_custom 的数据存储为全精度浮点数，只使用红色通道。见 Mesh.ARRAY_CUSTOM_R_FLOAT。

CustomFormat CUSTOM_RG_FLOAT = 5

将传递给 set_custom 的数据存储为全精度浮点数，只使用红色和绿色通道。见 Mesh.ARRAY_CUSTOM_RG_FLOAT。

CustomFormat CUSTOM_RGB_FLOAT = 6

将传递给 set_custom 的数据存储为全精度浮点数，只使用红色、绿色和蓝色通道。见 Mesh.ARRAY_CUSTOM_RGB_FLOAT。

CustomFormat CUSTOM_RGBA_FLOAT = 7

将传递给 set_custom 的数据存储为全精度浮点数，使用所有颜色通道。见 Mesh.ARRAY_CUSTOM_RGBA_FLOAT。

CustomFormat CUSTOM_MAX = 8

用于表示已禁用的自定义通道。

enum SkinWeightCount: 🔗

SkinWeightCount SKIN_4_WEIGHTS = 0

每个单独的顶点只能受到 4 个骨骼权重的影响。

SkinWeightCount SKIN_8_WEIGHTS = 1

每个单独的顶点最多能够受到 8 个骨骼权重的影响。

方法说明

void add_index(index: int) 🔗

如果你在使用顶点索引，则向索引数组中添加一个顶点。不需要在添加顶点前调用。

void add_triangle_fan(vertices: PackedVector3Array, uvs: PackedVector2Array = PackedVector2Array(), colors: PackedColorArray = PackedColorArray(), uv2s: PackedVector2Array = PackedVector2Array(), normals: PackedVector3Array = PackedVector3Array(), tangents: Array[Plane] = []) 🔗

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

需要将图元类型设置为 Mesh.PRIMITIVE_TRIANGLES。

void add_vertex(vertex: Vector3) 🔗

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

void append_from(existing: Mesh, surface: int, transform: Transform3D) 🔗

使用指定的 Transform3D 将来自给定 Mesh 表面的顶点追加到当前的顶点数组中。

void begin(primitive: PrimitiveType) 🔗

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

void clear() 🔗

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

ArrayMesh commit(existing: ArrayMesh = null, flags: int = 0) 🔗

根据传入的当前信息返回构造的 ArrayMesh。如果将一个已有的 ArrayMesh 作为参数传入，则会向该已有的 ArrayMesh 添加一个额外的表面。

修订说明：flags 的记录可能值，它在 4.0 中发生了变化。可能是 ArrayFormat 的一些组合。

Array commit_to_arrays() 🔗

将数据提交为 ArrayMesh.add_surface_from_arrays、ImporterMesh.add_surface 和 create_from_arrays 使用的相同格式。这样，你可以使用 ArrayMesh 或 ImporterMesh API 进一步处理网格数据。

void create_from(existing: Mesh, surface: int) 🔗

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

void create_from_arrays(arrays: Array, primitive_type: PrimitiveType = 3) 🔗

从现有顶点数组（例如 commit_to_arrays、Mesh.surface_get_arrays、Mesh.surface_get_blend_shape_arrays、ImporterMesh.get_surface_arrays 和 ImporterMesh.get_surface_blend_shape_arrays 返回的数组）创建该 SurfaceTool。primitive_type 控制网格数据的类型，默认为 Mesh.PRIMITIVE_TRIANGLES。

void create_from_blend_shape(existing: Mesh, surface: int, blend_shape: String) 🔗

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

void deindex() 🔗

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

PackedInt32Array generate_lod(nd_threshold: float, target_index_count: int = 3) 🔗

已弃用： This method is unused internally, as it does not preserve normals or UVs. Consider using ImporterMesh.generate_lods instead.

为给定的 nd_threshold 生成 LOD，使用线性单位（四次误差的平方根），最多使用 target_index_count 个索引。

void generate_normals(flip: bool = false) 🔗

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

注意：generate_normals 仅在图元类型被设置为 Mesh.PRIMITIVE_TRIANGLES 时有效。

注意：generate_normals 考虑了平滑组。要生成平滑法线，请使用 set_smooth_group 将平滑组设置为大于或等于 0 的值，或者将平滑组保留为默认值 0。要生成平面法线，请在添加顶点之前，使用 set_smooth_group 将平滑组设置为 -1。

void generate_tangents() 🔗

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

AABB get_aabb() const 🔗

返回顶点位置的轴对齐边界框。

CustomFormat get_custom_format(channel_index: int) const 🔗

返回索引为 channel_index 的自定义通道的格式（索引最多为 4）。如果这个自定义通道尚未使用，则返回 CUSTOM_MAX。

PrimitiveType get_primitive_type() const 🔗

返回网格几何体的类型，例如 Mesh.PRIMITIVE_TRIANGLES。

SkinWeightCount get_skin_weight_count() const 🔗

默认情况下，返回 SKIN_4_WEIGHTS 以指示每个顶点仅使用 4 个骨骼影响。

如果使用最多 8 个影响，则返回 SKIN_8_WEIGHTS。

注意：该函数返回一个枚举，而不是确切的权重数量。

void index() 🔗

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

void optimize_indices_for_cache() 🔗

优化三角形排序以提高性能。要求 get_primitive_type 为 Mesh.PRIMITIVE_TRIANGLES。

void set_bones(bones: PackedInt32Array) 🔗

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

void set_color(color: Color) 🔗

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

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

void set_custom(channel_index: int, custom_color: Color) 🔗

设置这个顶点的 channel_index 通道的自定义值。

必须先为 channel_index 通道调用 set_custom_format。非 RGBA 格式会忽略其他颜色通道。

void set_custom_format(channel_index: int, format: CustomFormat) 🔗

设置索引为 channel_index 的自定义通道的颜色格式。禁用请使用 CUSTOM_MAX。

必须在 begin 之后调用，应当在 commit 或 commit_to_arrays 之前设置。

void set_material(material: Material) 🔗

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

void set_normal(normal: Vector3) 🔗

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

void set_skin_weight_count(count: SkinWeightCount) 🔗

设置为 SKIN_8_WEIGHTS 表示每个顶点最多可以使用 8 个骨骼影响。

默认情况下，仅使用 4 个骨骼影响（SKIN_4_WEIGHTS）

注意：该函数接受一个枚举，而不是权重的确切数量。

void set_smooth_group(index: int) 🔗

指定用于下一个顶点的平滑组。如果从未调用过，则所有顶点都将具有默认的 0 平滑组，并将与同一组的相邻顶点一起平滑。要生成具有平坦法线的网格，请将平滑组设置为 -1。

注意：这个函数实际接受的是 uint32_t，所以 C# 用户如果要生成法线平坦的网格，那么就应该使用 uint32.MaxValue 而不是 -1。

void set_tangent(tangent: Plane) 🔗

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

void set_uv(uv: Vector2) 🔗

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

void set_uv2(uv2: Vector2) 🔗

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

void set_weights(weights: PackedFloat32Array) 🔗

指定用于下一个顶点的权重值。weights 必须包含 4 个值。如果每个顶点都需要设置该信息，且为第一个顶点提交失败，则可能根本不会使用该信息。