The godot.SurfaceTool is used to construct a godot.Mesh by specifying vertex attributes individually. It can be used to construct a godot.Mesh from a script. All properties except indices need to be added before calling godot.SurfaceTool.addVertex. For example, to add vertex colors and UVs:
var st = SurfaceTool.new()
st.begin(Mesh.PRIMITIVE_TRIANGLES)
st.add_color(Color(1, 0, 0))
st.add_uv(Vector2(0, 0))
st.add_vertex(Vector3(0, 0, 0))
The above godot.SurfaceTool now contains one vertex of a triangle which has a UV coordinate and a specified godot.Color. If another vertex were added without calling godot.SurfaceTool.addUv or godot.SurfaceTool.addColor, then the last values would be used.
Vertex attributes must be passed before calling godot.SurfaceTool.addVertex. 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 godot.ArrayMesh, godot.ImmediateGeometry and godot.MeshDataTool for procedural geometry generation.
Note: Godot uses clockwise [https://learnopengl.com/Advanced-OpenGL/Face-culling](winding order) for front faces of triangle primitive modes.
Constructor
Methods
addBones(bones:HaxeArray<Int>):Void
Specifies an array of bones to use for the next vertex. bones must contain 4 integers.
addColor(color:Color):Void
Specifies a godot.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 godot.SpatialMaterial.vertexColorUseAsAlbedo enabled for the vertex color to be visible.
addIndex(index:Int):Void
Adds an index to index array if you are using indexed vertices. Does not need to be called before adding vertices.
addNormal(normal:Vector3):Void
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.
addSmoothGroup(smooth:Bool):Void
Specifies whether the current vertex (if using only vertex arrays) or current index (if also using index arrays) should use smooth normals for normal calculation.
addTangent(tangent:Plane):Void
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.
addTriangleFan(vertices:Array<Vector3>, ?uvs:Array<Vector2>, ?colors:Array<Color>, ?uv2s:Array<Vector2>, ?normals:Array<Vector3>, ?tangents:Array):Void
Inserts a triangle fan made of array data into godot.Mesh being constructed.
Requires the primitive type be set to godot.Mesh_PrimitiveType.triangles.
Parameters:
uvs | If the parameter is null, then the default value is Array.Empty<Vector2>() |
|---|---|
colors | If the parameter is null, then the default value is Array.Empty<Color>() |
uv2s | If the parameter is null, then the default value is Array.Empty<Vector2>() |
normals | If the parameter is null, then the default value is Array.Empty<Vector3>() |
tangents | If the parameter is null, then the default value is new Godot.Collections.Array { } |
addUv(uv:Vector2):Void
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.
addUv2(uv2:Vector2):Void
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.
addVertex(vertex:Vector3):Void
Specifies the position of current vertex. Should be called after specifying other vertex properties (e.g. Color, UV).
addWeights(weights:HaxeArray<Single>):Void
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.
appendFrom(existing:Mesh, surface:Int, transform:Transform):Void
Append vertices from a given godot.Mesh surface onto the current vertex array with specified godot.Transform.
Note: Using godot.SurfaceTool.appendFrom on a godot.Thread is much slower as the GPU must communicate data back to the CPU, while also causing the main thread to stall (as OpenGL is not thread-safe). Consider requesting a copy of the mesh, converting it to an godot.ArrayMesh and adding vertices manually instead.
begin(primitive:Mesh_PrimitiveType):Void
Called before adding any vertices. Takes the primitive type as an argument (e.g. godot.Mesh_PrimitiveType.triangles).
commit(?existing:ArrayMesh, ?flags:UInt):ArrayMesh
Returns a constructed godot.ArrayMesh from current information passed in. If an existing godot.ArrayMesh is passed in as an argument, will add an extra surface to the existing godot.ArrayMesh.
Default flag is godot.Mesh_ArrayFormat.compressDefault if compression is enabled. If compression is disabled the default flag is godot.Mesh_ArrayFormat.flagUseOctahedralCompression. See ARRAY_COMPRESS_* constants in godot.Mesh_ArrayFormat for other flags.
commitToArrays():Array
Commits the data to the same format used by godot.ArrayMesh.addSurfaceFromArrays. This way you can further process the mesh data using the godot.ArrayMesh API.
createFromBlendShape(existing:Mesh, surface:Int, blendShape:String):Void
Creates a vertex array from the specified blend shape of an existing godot.Mesh. This can be used to extract a specific pose from a blend shape.
generateNormals(?flip:Bool):Void
Generates normals from vertices so you do not have to do it manually. If flip is true, the resulting normals will be inverted. godot.SurfaceTool.generateNormals should be called after generating geometry and before committing the mesh using godot.SurfaceTool.commit or godot.SurfaceTool.commitToArrays. For correct display of normal-mapped surfaces, you will also have to generate tangents using godot.SurfaceTool.generateTangents.
Note: godot.SurfaceTool.generateNormals only works if the primitive type to be set to godot.Mesh_PrimitiveType.triangles.
generateTangents():Void
Generates a tangent vector for each vertex. Requires that each vertex have UVs and normals set already (see godot.SurfaceTool.generateNormals).
index():Void
Shrinks the vertex array by creating an index array. This can improve performance by avoiding vertex reuse.
setMaterial(material:Material):Void
Sets godot.Material to be used by the godot.Mesh you are constructing.