Table of Contents

Class SurfaceTool

Namespace
Godot
Assembly
GodotSharp.dll

The SurfaceTool is used to construct a Mesh by specifying vertex attributes individually. It can be used to construct a Mesh from a script. All properties except indices need to be added before calling AddVertex(Vector3). For example, to add vertex colors and UVs:

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

The above SurfaceTool now contains one vertex of a triangle which has a UV coordinate and a specified Color. If another vertex were added without calling SetUV(Vector2) or SetColor(Color), then the last values would be used.

Vertex attributes must be passed before calling AddVertex(Vector3). Failure to do so will result in an error when committing the vertex information to a mesh.

Additionally, the attributes used before the first vertex is added determine the format of the mesh. For example, if you only add UVs to the first vertex, you cannot add color to any of the subsequent vertices.

See also ArrayMesh, ImmediateMesh and MeshDataTool for procedural geometry generation.

Note: Godot uses clockwise winding order for front faces of triangle primitive modes.

public class SurfaceTool : RefCounted, IDisposable
Inheritance
SurfaceTool
Implements
Inherited Members

Constructors

SurfaceTool() 

public SurfaceTool()

Methods

AddIndex(int)

Adds a vertex to index array if you are using indexed vertices. Does not need to be called before adding vertices.

public void AddIndex(int index)

Parameters

index int

AddTriangleFan(Vector3[], Vector2[], Color[], Vector2[], Vector3[], Array<Plane>)

Inserts a triangle fan made of array data into Mesh being constructed.

Requires the primitive type be set to Triangles.

public void AddTriangleFan(Vector3[] vertices, Vector2[] uvs = null, Color[] colors = null, Vector2[] uv2S = null, Vector3[] normals = null, Array<Plane> tangents = null)

Parameters

vertices Vector3[]
uvs Vector2[]

If the parameter is null, then the default value is Array.Empty<Vector2>().

colors Color[]

If the parameter is null, then the default value is Array.Empty<Color>().

uv2S Vector2[]

If the parameter is null, then the default value is Array.Empty<Vector2>().

normals Vector3[]

If the parameter is null, then the default value is Array.Empty<Vector3>().

tangents Array<Plane>

AddVertex(Vector3)

Specifies the position of current vertex. Should be called after specifying other vertex properties (e.g. Color, UV).

public void AddVertex(Vector3 vertex)

Parameters

vertex Vector3

AppendFrom(Mesh, int, Transform3D)

Append vertices from a given Mesh surface onto the current vertex array with specified Transform3D.

public void AppendFrom(Mesh existing, int surface, Transform3D transform)

Parameters

existing Mesh
surface int
transform Transform3D

Begin(PrimitiveType)

Called before adding any vertices. Takes the primitive type as an argument (e.g. Triangles).

public void Begin(Mesh.PrimitiveType primitive)

Parameters

primitive Mesh.PrimitiveType

Clear()

Clear all information passed into the surface tool so far.

public void Clear()

Commit(ArrayMesh, ulong)

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.

FIXME: Document possible values for flags, it changed in 4.0. Likely some combinations of Mesh.ArrayFormat.

public ArrayMesh Commit(ArrayMesh existing = null, ulong flags = 0)

Parameters

existing ArrayMesh
flags ulong

Returns

ArrayMesh

CommitToArrays()

Commits the data to the same format used by AddSurfaceFromArrays(PrimitiveType, Array, Array<Array>, Dictionary, ArrayFormat). This way you can further process the mesh data using the ArrayMesh API.

public Array CommitToArrays()

Returns

Array

CreateFrom(Mesh, int)

Creates a vertex array from an existing Mesh.

public void CreateFrom(Mesh existing, int surface)

Parameters

existing Mesh
surface int

CreateFromBlendShape(Mesh, int, string)

Creates a vertex array from the specified blend shape of an existing Mesh. This can be used to extract a specific pose from a blend shape.

public void CreateFromBlendShape(Mesh existing, int surface, string blendShape)

Parameters

existing Mesh
surface int
blendShape string

Deindex()

Removes the index array by expanding the vertex array.

public void Deindex()

GenerateLod(float, int)

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

Deprecated. Unused internally and fails to preserve normals or UVs. Consider using GenerateLods(float, float, Array) instead.

[Obsolete("This method is deprecated.")]
public int[] GenerateLod(float ndThreshold, int targetIndexCount = 3)

Parameters

ndThreshold float
targetIndexCount int

Returns

int[]

GenerateNormals(bool)

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

Note: GenerateNormals(bool) only works if the primitive type to be set to Triangles.

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

public void GenerateNormals(bool flip = false)

Parameters

flip bool

GenerateTangents()

Generates a tangent vector for each vertex. Requires that each vertex have UVs and normals set already (see GenerateNormals(bool)).

public void GenerateTangents()

GetAabb()

Returns the axis-aligned bounding box of the vertex positions.

public Aabb GetAabb()

Returns

Aabb

GetCustomFormat(int)

Returns the format for custom channelIndex (currently up to 4). Returns Max if this custom channel is unused.

public SurfaceTool.CustomFormat GetCustomFormat(int channelIndex)

Parameters

channelIndex int

Returns

SurfaceTool.CustomFormat

GetPrimitiveType()

Returns the type of mesh geometry, such as Triangles.

public Mesh.PrimitiveType GetPrimitiveType()

Returns

Mesh.PrimitiveType

GetSkinWeightCount()

By default, returns Skin4Weights to indicate only 4 bone influences per vertex are used.

Returns Skin8Weights if up to 8 influences are used.

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

public SurfaceTool.SkinWeightCount GetSkinWeightCount()

Returns

SurfaceTool.SkinWeightCount

HasGodotClassMethod(in godot_string_name)

Check if the type contains a method with the given name. This method is used by Godot to check if a method exists before invoking it. Do not call or override this method.

protected override bool HasGodotClassMethod(in godot_string_name method)

Parameters

method godot_string_name

Name of the method to check for.

Returns

bool

HasGodotClassSignal(in godot_string_name)

Check if the type contains a signal with the given name. This method is used by Godot to check if a signal exists before raising it. Do not call or override this method.

protected override bool HasGodotClassSignal(in godot_string_name signal)

Parameters

signal godot_string_name

Name of the signal to check for.

Returns

bool

Index()

Shrinks the vertex array by creating an index array. This can improve performance by avoiding vertex reuse.

public void Index()

InvokeGodotClassMethod(in godot_string_name, NativeVariantPtrArgs, out godot_variant)

Invokes the method with the given name, using the given arguments. This method is used by Godot to invoke methods from the engine side. Do not call or override this method.

protected override bool InvokeGodotClassMethod(in godot_string_name method, NativeVariantPtrArgs args, out godot_variant ret)

Parameters

method godot_string_name

Name of the method to invoke.

args NativeVariantPtrArgs

Arguments to use with the invoked method.

ret godot_variant

Value returned by the invoked method.

Returns

bool

OptimizeIndicesForCache()

Optimizes triangle sorting for performance. Requires that GetPrimitiveType() is Triangles.

public void OptimizeIndicesForCache()

SetBones(int[])

Specifies an array of bones to use for the next vertex. bones must contain 4 integers.

public void SetBones(int[] bones)

Parameters

bones int[]

SetColor(Color)

Specifies a Color 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: The material must have VertexColorUseAsAlbedo enabled for the vertex color to be visible.

public void SetColor(Color color)

Parameters

color Color

SetCustom(int, Color)

Sets the custom value on this vertex for channelIndex.

SetCustomFormat(int, CustomFormat) must be called first for this channelIndex. Formats which are not RGBA will ignore other color channels.

public void SetCustom(int channelIndex, Color customColor)

Parameters

channelIndex int
customColor Color

SetCustomFormat(int, CustomFormat)

Sets the color format for this custom channelIndex. Use Max to disable.

Must be invoked after Begin(PrimitiveType) and should be set before Commit(ArrayMesh, ulong) or CommitToArrays().

public void SetCustomFormat(int channelIndex, SurfaceTool.CustomFormat format)

Parameters

channelIndex int
format SurfaceTool.CustomFormat

SetMaterial(Material)

Sets Material to be used by the Mesh you are constructing.

public void SetMaterial(Material material)

Parameters

material Material

SetNormal(Vector3)

Specifies a normal 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.

public void SetNormal(Vector3 normal)

Parameters

normal Vector3

SetSkinWeightCount(SkinWeightCount)

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

By default, only 4 bone influences are used (Skin4Weights)

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

public void SetSkinWeightCount(SurfaceTool.SkinWeightCount count)

Parameters

count SurfaceTool.SkinWeightCount

SetSmoothGroup(uint)

Specifies the smooth group to use for the next vertex. If this is never called, all vertices will have the default smooth group of 0 and will be smoothed with adjacent vertices of the same group. To produce a mesh with flat normals, set the smooth group to -1.

Note: This function actually takes a uint32_t, so C# users should use uint32.MaxValue instead of -1 to produce a mesh with flat normals.

public void SetSmoothGroup(uint index)

Parameters

index uint

SetTangent(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.

public void SetTangent(Plane tangent)

Parameters

tangent Plane

SetUV(Vector2)

Specifies a set of UV coordinates 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.

public void SetUV(Vector2 uV)

Parameters

uV Vector2

SetUV2(Vector2)

Specifies an optional second set of UV coordinates 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.

public void SetUV2(Vector2 uV2)

Parameters

uV2 Vector2

SetWeights(float[])

Specifies weight values to use for the next vertex. weights must contain 4 values. 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.

public void SetWeights(float[] weights)

Parameters

weights float[]
Edit this page