Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

SurfaceTool¶

继承： RefCounted < Object

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

描述¶

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

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 中三角形图元模式的正面使用顺时针缠绕顺序。

教程¶

方法¶

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] = [])
void	add_vertex(vertex: Vector3)
void	append_from(existing: Mesh, surface: int, transform: Transform3D)
void	begin(primitive: PrimitiveType)
void	clear()
ArrayMesh	commit(existing: ArrayMesh = null, flags: int = 0)
Array	commit_to_arrays()
void	create_from(existing: Mesh, surface: int)
void	create_from_arrays(arrays: Array, primitive_type: PrimitiveType = 3)
void	create_from_blend_shape(existing: Mesh, surface: int, blend_shape: String)
void	deindex()
PackedInt32Array	generate_lod(nd_threshold: float, target_index_count: int = 3)
void	generate_normals(flip: bool = false)
void	generate_tangents()
AABB	get_aabb() const
CustomFormat	get_custom_format(channel_index: int) const
PrimitiveType	get_primitive_type() const
SkinWeightCount	get_skin_weight_count() const
void	index()
void	optimize_indices_for_cache()
void	set_bones(bones: PackedInt32Array)
void	set_color(color: Color)
void	set_custom(channel_index: int, custom_color: Color)
void	set_custom_format(channel_index: int, format: CustomFormat)
void	set_material(material: Material)
void	set_normal(normal: Vector3)
void	set_skin_weight_count(count: SkinWeightCount)
void	set_smooth_group(index: int)
void	set_tangent(tangent: Plane)
void	set_uv(uv: Vector2)
void	set_uv2(uv2: Vector2)
void	set_weights(weights: PackedFloat32Array)

枚举¶

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 个值。如果每个顶点都需要设置该信息，且为第一个顶点提交失败，则可能根本不会使用该信息。