SurfaceTool

package
v0.0.0-...-357ca8a Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 20, 2025 License: MIT Imports: 32 Imported by: 0

Documentation

Overview

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. For example, to add vertex colors and UVs: 

package main

import (
	"graphics.gd/classdb/Mesh"
	"graphics.gd/classdb/SurfaceTool"
	"graphics.gd/variant/Color"
	"graphics.gd/variant/Vector2"
	"graphics.gd/variant/Vector3"
)

func ExampleSurfaceTool() {
	var st = SurfaceTool.New()
	st.Begin(Mesh.PrimitiveTriangles)
	st.SetColor(Color.RGBA{1, 0, 0, 1})
	st.SetUv(Vector2.New(0, 0))
	st.AddVertex(Vector3.New(0, 0, 0))

}

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

Vertex attributes must be passed before calling 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 ArrayMesh, ImmediateMesh and MeshDataTool for procedural geometry generation.

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

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Advanced 

type Advanced = class

Advanced exposes a 1:1 low-level instance of the class, undocumented, for those who know what they are doing.

type Any 

type Any interface {
	gd.IsClass
	AsSurfaceTool() Instance
}

type CustomFormat 

type CustomFormat int //gd:SurfaceTool.CustomFormat

const (
	// Limits range of data passed to [SetCustom] to unsigned normalized 0 to 1 stored in 8 bits per channel. See [Mesh.ArrayCustomRgba8Unorm].
	//
	// [SetCustom]: https://pkg.go.dev/graphics.gd/classdb/#Instance.SetCustom
	CustomRgba8Unorm CustomFormat = 0
	// Limits range of data passed to [SetCustom] to signed normalized -1 to 1 stored in 8 bits per channel. See [Mesh.ArrayCustomRgba8Snorm].
	//
	// [SetCustom]: https://pkg.go.dev/graphics.gd/classdb/#Instance.SetCustom
	CustomRgba8Snorm CustomFormat = 1
	// Stores data passed to [SetCustom] as half precision floats, and uses only red and green color channels. See [Mesh.ArrayCustomRgHalf].
	//
	// [SetCustom]: https://pkg.go.dev/graphics.gd/classdb/#Instance.SetCustom
	CustomRgHalf CustomFormat = 2
	// Stores data passed to [SetCustom] as half precision floats and uses all color channels. See [Mesh.ArrayCustomRgbaHalf].
	//
	// [SetCustom]: https://pkg.go.dev/graphics.gd/classdb/#Instance.SetCustom
	CustomRgbaHalf CustomFormat = 3
	// Stores data passed to [SetCustom] as full precision floats, and uses only red color channel. See [Mesh.ArrayCustomRFloat].
	//
	// [SetCustom]: https://pkg.go.dev/graphics.gd/classdb/#Instance.SetCustom
	CustomRFloat CustomFormat = 4
	// Stores data passed to [SetCustom] as full precision floats, and uses only red and green color channels. See [Mesh.ArrayCustomRgFloat].
	//
	// [SetCustom]: https://pkg.go.dev/graphics.gd/classdb/#Instance.SetCustom
	CustomRgFloat CustomFormat = 5
	// Stores data passed to [SetCustom] as full precision floats, and uses only red, green and blue color channels. See [Mesh.ArrayCustomRgbFloat].
	//
	// [SetCustom]: https://pkg.go.dev/graphics.gd/classdb/#Instance.SetCustom
	CustomRgbFloat CustomFormat = 6
	// Stores data passed to [SetCustom] as full precision floats, and uses all color channels. See [Mesh.ArrayCustomRgbaFloat].
	//
	// [SetCustom]: https://pkg.go.dev/graphics.gd/classdb/#Instance.SetCustom
	CustomRgbaFloat CustomFormat = 7
	// Used to indicate a disabled custom channel.
	CustomMax CustomFormat = 8
)

type Expanded 

type Expanded = MoreArgs

type Extension 

type Extension[T gdclass.Interface] struct{ gdclass.Extension[T, Instance] }

Extension can be embedded in a new struct to create an extension of this class. T should be the type that is embedding this Extension

func (*Extension[T]) AsObject 

func (self *Extension[T]) AsObject() [1]gd.Object

func (*Extension[T]) AsRefCounted 

func (self *Extension[T]) AsRefCounted() [1]gd.RefCounted

func (*Extension[T]) AsSurfaceTool 

func (self *Extension[T]) AsSurfaceTool() Instance

type ID 

type ID Object.ID

ID is a typed object ID (reference) to an instance of this class, use it to store references to objects with unknown lifetimes, as an ID will not panic on use if the underlying object has been destroyed.

func (ID) Instance 

func (id ID) Instance() (Instance, bool)

type Instance 

type Instance [1]gdclass.SurfaceTool

Instance of the class with convieniently typed arguments and results. 

var Nil Instance

Nil is a nil/null instance of the class. Equivalent to the zero value.

func New 

func New() Instance

func (Instance) AddIndex 

func (self Instance) AddIndex(index int)

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

func (Instance) AddTriangleFan 

func (self Instance) AddTriangleFan(vertices []Vector3.XYZ)

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

Requires the primitive type be set to [Mesh.PrimitiveTriangles].

func (Instance) AddVertex 

func (self Instance) AddVertex(vertex Vector3.XYZ)

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

func (Instance) AppendFrom 

func (self Instance) AppendFrom(existing Mesh.Instance, surface int, transform Transform3D.BasisOrigin)

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

func (Instance) AsObject 

func (self Instance) AsObject() [1]gd.Object

func (Instance) AsRefCounted 

func (self Instance) AsRefCounted() [1]gd.RefCounted

func (Instance) AsSurfaceTool 

func (self Instance) AsSurfaceTool() Instance

func (Instance) Begin 

func (self Instance) Begin(primitive Mesh.PrimitiveType)

Called before adding any vertices. Takes the primitive type as an argument (e.g. [Mesh.PrimitiveTriangles]).

func (Instance) Clear 

func (self Instance) Clear()

Clear all information passed into the surface tool so far.

func (Instance) Commit 

func (self Instance) Commit() ArrayMesh.Instance

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.ArrayFlagUseDynamicUpdate], [Mesh.ArrayFlagUse8BoneWeights], or [Mesh.ArrayFlagUsesEmptyVertexArray].

func (Instance) CommitToArrays 

func (self Instance) CommitToArrays() []any

Commits the data to the same format used by ArrayMesh.AddSurfaceFromArrays, ImporterMesh.AddSurface, and CreateFromArrays. This way you can further process the mesh data using the ArrayMesh or ImporterMesh APIs.

func (Instance) CreateFrom 

func (self Instance) CreateFrom(existing Mesh.Instance, surface int)

Creates a vertex array from an existing Mesh.

func (Instance) CreateFromArrays 

func (self Instance) CreateFromArrays(arrays []any)

Creates this SurfaceTool from existing vertex arrays such as returned by CommitToArrays, Mesh.SurfaceGetArrays, Mesh.SurfaceGetBlendShapeArrays, ImporterMesh.GetSurfaceArrays, and ImporterMesh.GetSurfaceBlendShapeArrays. 'primitive_type' controls the type of mesh data, defaulting to [Mesh.PrimitiveTriangles].

func (Instance) CreateFromBlendShape 

func (self Instance) CreateFromBlendShape(existing Mesh.Instance, surface int, blend_shape 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.

func (Instance) Deindex 

func (self Instance) Deindex()

Removes the index array by expanding the vertex array.

func (Instance) GenerateLod 

func (self Instance) GenerateLod(nd_threshold Float.X) []int32

Generates an LOD for a given 'nd_threshold' in linear units (square root of quadric error metric), using at most 'target_index_count' indices.

func (Instance) GenerateNormals 

func (self Instance) GenerateNormals()

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

Note: GenerateNormals only works if the primitive type is set to [Mesh.PrimitiveTriangles].

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

func (Instance) GenerateTangents 

func (self Instance) GenerateTangents()

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

func (Instance) GetAabb 

func (self Instance) GetAabb() AABB.PositionSize

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

func (Instance) GetCustomFormat 

func (self Instance) GetCustomFormat(channel_index int) CustomFormat

Returns the format for custom 'channel_index' (currently up to 4). Returns CustomMax if this custom channel is unused.

func (Instance) GetPrimitiveType 

func (self Instance) GetPrimitiveType() Mesh.PrimitiveType

Returns the type of mesh geometry, such as [Mesh.PrimitiveTriangles].

func (Instance) GetSkinWeightCount 

func (self Instance) GetSkinWeightCount() SkinWeightCount

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.

func (Instance) ID 

func (self Instance) ID() ID

func (Instance) Index 

func (self Instance) Index()

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

func (Instance) MoreArgs 

func (self Instance) MoreArgs() MoreArgs

MoreArgs enables certain functions to be called with additional 'optional' arguments.

func (Instance) OptimizeIndicesForCache 

func (self Instance) OptimizeIndicesForCache()

Optimizes triangle sorting for performance. Requires that GetPrimitiveType is [Mesh.PrimitiveTriangles].

func (Instance) SetBones 

func (self Instance) SetBones(bones []int32)

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

func (Instance) SetColor 

func (self Instance) SetColor(color Color.RGBA)

Specifies a Color.RGBA 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 BaseMaterial3D.VertexColorUseAsAlbedo enabled for the vertex color to be visible.

func (Instance) SetCustom 

func (self Instance) SetCustom(channel_index int, custom_color Color.RGBA)

Sets the custom value on this vertex for 'channel_index'.

SetCustomFormat must be called first for this 'channel_index'. Formats which are not RGBA will ignore other color channels.

func (Instance) SetCustomFormat 

func (self Instance) SetCustomFormat(channel_index int, format CustomFormat)

Sets the color format for this custom 'channel_index'. Use CustomMax to disable.

Must be invoked after Begin and should be set before Commit or CommitToArrays.

func (Instance) SetMaterial 

func (self Instance) SetMaterial(material Material.Instance)

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

func (Instance) SetNormal 

func (self Instance) SetNormal(normal Vector3.XYZ)

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.

func (*Instance) SetObject 

func (self *Instance) SetObject(obj [1]gd.Object) bool

func (Instance) SetSkinWeightCount 

func (self Instance) SetSkinWeightCount(count 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.

func (Instance) SetSmoothGroup 

func (self Instance) SetSmoothGroup(index int)

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.

func (Instance) SetTangent 

func (self Instance) SetTangent(tangent Plane.NormalD)

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.

func (Instance) SetUv 

func (self Instance) SetUv(uv Vector2.XY)

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.

func (Instance) SetUv2 

func (self Instance) SetUv2(uv2 Vector2.XY)

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.

func (Instance) SetWeights 

func (self Instance) SetWeights(weights []float32)

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.

func (Instance) Virtual 

func (self Instance) Virtual(name string) reflect.Value

type MoreArgs 

type MoreArgs [1]gdclass.SurfaceTool

MoreArgs is a container for Instance functions with additional 'optional' arguments.

func (MoreArgs) AddTriangleFan 

func (self MoreArgs) AddTriangleFan(vertices []Vector3.XYZ, uvs []Vector2.XY, colors []Color.RGBA, uv2s []Vector2.XY, normals []Vector3.XYZ, tangents []Plane.NormalD)

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

Requires the primitive type be set to [Mesh.PrimitiveTriangles].

func (MoreArgs) Commit 

func (self MoreArgs) Commit(existing ArrayMesh.Instance, flags int) ArrayMesh.Instance

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.ArrayFlagUseDynamicUpdate], [Mesh.ArrayFlagUse8BoneWeights], or [Mesh.ArrayFlagUsesEmptyVertexArray].

func (MoreArgs) CreateFromArrays 

func (self MoreArgs) CreateFromArrays(arrays []any, primitive_type Mesh.PrimitiveType)

Creates this SurfaceTool from existing vertex arrays such as returned by CommitToArrays, Mesh.SurfaceGetArrays, Mesh.SurfaceGetBlendShapeArrays, ImporterMesh.GetSurfaceArrays, and ImporterMesh.GetSurfaceBlendShapeArrays. 'primitive_type' controls the type of mesh data, defaulting to [Mesh.PrimitiveTriangles].

func (MoreArgs) GenerateLod 

func (self MoreArgs) GenerateLod(nd_threshold Float.X, target_index_count int) []int32

Generates an LOD for a given 'nd_threshold' in linear units (square root of quadric error metric), using at most 'target_index_count' indices.

func (MoreArgs) GenerateNormals 

func (self MoreArgs) GenerateNormals(flip 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 should be called after generating geometry and before committing the mesh using Commit or CommitToArrays. For correct display of normal-mapped surfaces, you will also have to generate tangents using GenerateTangents.

Note: GenerateNormals only works if the primitive type is set to [Mesh.PrimitiveTriangles].

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

type SkinWeightCount 

type SkinWeightCount int //gd:SurfaceTool.SkinWeightCount

const (
	// Each individual vertex can be influenced by only 4 bone weights.
	Skin4Weights SkinWeightCount = 0
	// Each individual vertex can be influenced by up to 8 bone weights.
	Skin8Weights SkinWeightCount = 1
)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.