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

Returns a constructed ArrayMesh from current information passed in. If an existing ArrayMesh is passed in as an argument, will add an extra surface to the existing ArrayMesh.

The flags argument can be the bitwise OR of Mesh.ARRAY_FLAG_USE_DYNAMIC_UPDATE, Mesh.ARRAY_FLAG_USE_8_BONE_WEIGHTS, or Mesh.ARRAY_FLAG_USES_EMPTY_VERTEX_ARRAY.

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

Generates normals from vertices so you do not have to do it manually. If flip is true, the resulting normals will be inverted. generate_normals() should be called after generating geometry and before committing the mesh using commit() or commit_to_arrays(). For correct display of normal-mapped surfaces, you will also have to generate tangents using generate_tangents().

Note: generate_normals() only works if the primitive type is set to Mesh.PRIMITIVE_TRIANGLES.

Note: generate_normals() takes smooth groups into account. To generate smooth normals, set the smooth group to a value greater than or equal to 0 using set_smooth_group() or leave the smooth group at the default of 0. To generate flat normals, set the smooth group to -1 using set_smooth_group() prior to adding vertices.

void generate_tangents() 🔗

Generates a tangent vector for each vertex. Requires that each vertex already has UVs and normals set (see 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) 🔗

Set to SKIN_8_WEIGHTS to indicate that up to 8 bone influences per vertex may be used.

By default, only 4 bone influences are used (SKIN_4_WEIGHTS).

Note: This function takes an enum, not the exact number of weights.

void set_smooth_group(index: int) 🔗

指定用於下一個頂點的平滑組。如果從未呼叫過，則所有頂點都將具有預設的 0 平滑組，並將與同一組的相鄰頂點一起平滑。要生成具有平坦法線的網格，請將平滑組設定為 -1。

注意：這個函式實際接受的是 uint32_t，所以 C# 使用者如果要生成法線平坦的網格，那麼就應該使用 uint32.MaxValue 而不是 -1。

void set_tangent(tangent: Plane) 🔗

Specifies a tangent to use for the next vertex. If every vertex needs to have this information set and you fail to submit it for the first vertex, this information may not be used at all.

Note: Even though tangent is a Plane, it does not directly represent the tangent plane. Its Plane.x, Plane.y, and Plane.z represent the tangent vector and Plane.d should be either -1 or 1. See also Mesh.ARRAY_TANGENT.

void set_uv(uv: Vector2) 🔗

指定下一個頂點所使用的 UV 座標。如果每個頂點都需要設定此資訊，而你未能為第一個頂點提交此資訊，此資訊可能根本就不會被使用。

void set_uv2(uv2: Vector2) 🔗

指定可選的第二組UV座標，用於next頂點。如果每個頂點都需要設定這個資訊，而你沒有為第一個頂點提交這個資訊，此資訊可能根本就不會被使用。

void set_weights(weights: PackedFloat32Array) 🔗

指定用於下一個頂點的權重值。weights 必須包含 4 個值。如果每個頂點都需要設定該資訊，且為第一個頂點提交失敗，則可能根本不會使用該資訊。