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.

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))

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

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

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

程序式几何体生成另见 ArrayMeshImmediateMesh 以及 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() 🔗

Commits the data to the same format used by ArrayMesh.add_surface_from_arrays, ImporterMesh.add_surface, and create_from_arrays. This way you can further process the mesh data using the ArrayMesh or ImporterMesh APIs.


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

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


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

Creates this SurfaceTool from existing vertex arrays such as returned by commit_to_arrays, Mesh.surface_get_arrays, Mesh.surface_get_blend_shape_arrays, ImporterMesh.get_surface_arrays, and ImporterMesh.get_surface_blend_shape_arrays. primitive_type controls the type of mesh data, defaulting to 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.

Generates an LOD for a given nd_threshold in linear units (square root of quadric error metric), using at most target_index_count indices.


void generate_normals(flip: bool = false) 🔗

从顶点生成法线,因此不必手动执行。如果 fliptrue,则生成的法线将被反转。generate_normals 的调用,应在生成几何体之后,且在使用 commitcommit_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_typeMesh.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 之后调用,应当在 commitcommit_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 个值。如果每个顶点都需要设置该信息,且为第一个顶点提交失败,则可能根本不会使用该信息。