SurfaceTool¶

创建几何体的辅助工具。

描述¶

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 以进行程序化几何生成。

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

方法¶

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

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

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

将给定Mesh表面的顶点附加到具有指定Transform3D的当前顶点数组上。

void begin(primitive: PrimitiveType) 🔗

在添加任何顶点之前调用。将原始类型作为参数（例如Mesh.PRIMITIVE_TRIANGLES）。

void clear() 🔗

清除到目前为止传递到表面工具的所有信息。

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

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

flags参数可以是Mesh.ARRAY_FLAG_USE_DYNAMIC_UPDATE、Mesh.ARRAY_FLAG_USE_8_BONE_WEIGHTS或Mesh.ARRAY_FLAG_USES_EMPTY_VERTEX_ARRAY的按位或。

Array commit_to_arrays() 🔗

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

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

从现有Mesh创建顶点数组。

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

从现有顶点数组创建此SurfaceTool，例如由commit_to_arrays()、Mesh.surface_get_arrays()、Mesh.surface_get_blend_shape_arrays()、ImporterMesh.get_surface_arrays()和ImporterMesh.get_surface_blend_shape_arrays()返回。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) 🔗

已弃用： 内部已不再使用这个方法，因为它不会保留法线和 UV。请考虑改用 ImporterMesh.generate_lods()。

以线性单位（二次误差度量的平方根）为给定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) 🔗

指定用于next顶点的骨数组。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) 🔗

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

注意：这个函数实际上需要一个uint32_t，所以C#用户应该使用uint32. MaxValue而不是-1来生成具有平坦法线的网格。

void set_tangent(tangent: Plane) 🔗

指定用于next顶点的切线。如果每个顶点都需要设置此信息，而您未能为第一个顶点提交此信息，则可能根本不使用此信息。

void set_uv(uv: Vector2) 🔗

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

void set_uv2(uv2: Vector2) 🔗

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

void set_weights(weights: PackedFloat32Array) 🔗

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