Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

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 ( int index )

void

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

void

add_vertex ( Vector3 vertex )

void

append_from ( Mesh existing, int surface, Transform3D transform )

void

begin ( PrimitiveType primitive )

void

clear ( )

ArrayMesh

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

Array

commit_to_arrays ( )

void

create_from ( Mesh existing, int surface )

void

create_from_blend_shape ( Mesh existing, int surface, String blend_shape )

void

deindex ( )

PackedInt32Array

generate_lod ( float nd_threshold, int target_index_count=3 )

void

generate_normals ( bool flip=false )

void

generate_tangents ( )

AABB

get_aabb ( ) const

CustomFormat

get_custom_format ( int channel_index ) const

PrimitiveType

get_primitive_type ( ) const

SkinWeightCount

get_skin_weight_count ( ) const

void

index ( )

void

optimize_indices_for_cache ( )

void

set_bones ( PackedInt32Array bones )

void

set_color ( Color color )

void

set_custom ( int channel_index, Color custom_color )

void

set_custom_format ( int channel_index, CustomFormat format )

void

set_material ( Material material )

void

set_normal ( Vector3 normal )

void

set_skin_weight_count ( SkinWeightCount count )

void

set_smooth_group ( int index )

void

set_tangent ( Plane tangent )

void

set_uv ( Vector2 uv )

void

set_uv2 ( Vector2 uv2 )

void

set_weights ( PackedFloat32Array weights )


枚举

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 ( int index )

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


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

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

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


void add_vertex ( Vector3 vertex )

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


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

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


void begin ( PrimitiveType primitive )

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


void clear ( )

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


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

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

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


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

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


PackedInt32Array generate_lod ( float nd_threshold, int target_index_count=3 )

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

已弃用。内部不再使用,并且无法保留法线或 UV。请考虑改用 ImporterMesh.generate_lods


void generate_normals ( bool flip=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 ( int channel_index ) 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 ( PackedInt32Array bones )

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


void set_color ( Color color )

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

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


void set_custom ( int channel_index, Color custom_color )

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

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


void set_custom_format ( int channel_index, CustomFormat format )

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

必须在 begin 之后调用,应当在 commitcommit_to_arrays 之前设置。


void set_material ( Material material )

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


void set_normal ( Vector3 normal )

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


void set_skin_weight_count ( SkinWeightCount count )

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

默认情况下,仅使用 4 个骨骼影响(SKIN_4_WEIGHTS

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


void set_smooth_group ( int index )

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

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


void set_tangent ( Plane tangent )

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


void set_uv ( Vector2 uv )

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


void set_uv2 ( Vector2 uv2 )

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


void set_weights ( PackedFloat32Array weights )

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