SurfaceTool

Herramienta de ayuda para crear geometría.

Descripción

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

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

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 set_uv() or set_color(), then the last values would be used.

Vertex attributes must be passed before calling add_vertex(). 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.

Tutoriales

Métodos

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)

Enumeraciones

enum CustomFormat: 🔗

CustomFormat CUSTOM_RGBA8_UNORM = 0

Limita el rango de datos pasados a set_custom() a valores normalizados sin signo de 0 a 1, almacenados en 8 bits por canal. Ver Mesh.ARRAY_CUSTOM_RGBA8_UNORM.

CustomFormat CUSTOM_RGBA8_SNORM = 1

Limita el rango de datos pasados a set_custom() a valores normalizados con signo de -1 a 1, almacenados en 8 bits por canal. Ver Mesh.ARRAY_CUSTOM_RGBA8_SNORM.

CustomFormat CUSTOM_RG_HALF = 2

Almacena los datos pasados a set_custom() como floats de media precisión, y usa solo los canales de color rojo y verde. Véase Mesh.ARRAY_CUSTOM_RG_HALF.

CustomFormat CUSTOM_RGBA_HALF = 3

Almacena los datos pasados a set_custom() como floats de media precisión y usa todos los canales de color. Véase Mesh.ARRAY_CUSTOM_RGBA_HALF.

CustomFormat CUSTOM_R_FLOAT = 4

Almacena los datos pasados a set_custom() como floats de precisión completa, y usa solo el canal de color rojo. Véase Mesh.ARRAY_CUSTOM_R_FLOAT.

CustomFormat CUSTOM_RG_FLOAT = 5

Almacena los datos pasados a set_custom() como floats de precisión completa, y usa solo los canales de color rojo y verde. Véase Mesh.ARRAY_CUSTOM_RG_FLOAT.

CustomFormat CUSTOM_RGB_FLOAT = 6

Almacena los datos pasados a set_custom() como floats de precisión completa, y usa solo los canales de color rojo, verde y azul. Véase Mesh.ARRAY_CUSTOM_RGB_FLOAT.

CustomFormat CUSTOM_RGBA_FLOAT = 7

Almacena los datos pasados a set_custom() como floats de precisión completa, y usa todos los canales de color. Véase Mesh.ARRAY_CUSTOM_RGBA_FLOAT.

CustomFormat CUSTOM_MAX = 8

Usado para indicar un canal personalizado desactivado.

enum SkinWeightCount: 🔗

SkinWeightCount SKIN_4_WEIGHTS = 0

Each individual vertex can be influenced by only 4 bone weights.

SkinWeightCount SKIN_8_WEIGHTS = 1

Each individual vertex can be influenced by up to 8 bone weights.

Descripciones de Métodos

void add_index(index: int) 🔗

Añade un vértice al array de índices si se utilizan vértices indexados. No es necesario llamarlo antes de añadir vértices.

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

Inserta un triangulo fan hecho de un array de datos en la Mesh que se está construyendo.

Requiere que el tipo primitivo se establezca en Mesh.PRIMITIVE_TRIANGLES.

void add_vertex(vertex: Vector3) 🔗

Especifica la posición del vértice actual. Debe ser llamado después de especificar otras propiedades del vértice (por ejemplo, Color, UV).

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

Añade vértices de una superficie Mesh dada al array de vértices actual con la Transform3D especificada.

void begin(primitive: PrimitiveType) 🔗

Llamado antes de añadir cualquier vértice. Toma el tipo primitivo como argumento (por ejemplo, Mesh.PRIMITIVE_TRIANGLES).

void clear() 🔗

Despeja toda la información pasada a la herramienta de la superficie hasta ahora.

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

Crea un array de vértices a partir de una Mesh existente.

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

Crea un array de vértices a partir de la forma de mezcla especificada de una Mesh existente. Esto puede ser usado para extraer una pose específica de una forma de mezcla.

void deindex() 🔗

Elimina el array de índices expandiendo el array de vértices.

PackedInt32Array generate_lod(nd_threshold: float, target_index_count: int = 3) 🔗

Obsoleto: This method is unused internally, as it does not preserve normals or UVs. Consider using ImporterMesh.generate_lods() instead.

Genera un LOD para un nd_threshold dado en unidades lineales (raíz cuadrada de la métrica de error cuadrático), utilizando como máximo target_index_count índices.

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

Genera un vector tangente para cada vértice. Requiere que cada vértice ya tenga los UV y las normales establecidos (ver generate_normals()).

AABB get_aabb() const 🔗

Devuelve el cuadro delimitador alineado con los ejes de las posiciones de los vértices.

CustomFormat get_custom_format(channel_index: int) const 🔗

Devuelve el formato para channel_index personalizado (actualmente hasta 4). Devuelve CUSTOM_MAX si este canal personalizado no se usa.

PrimitiveType get_primitive_type() const 🔗

Devuelve el tipo de geometría de la malla, como Mesh.PRIMITIVE_TRIANGLES.

SkinWeightCount get_skin_weight_count() const 🔗

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

Returns SKIN_8_WEIGHTS if up to 8 influences are used.

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

void index() 🔗

Reduce el array de vértices creando un array de índice. Esto puede mejorar el rendimiento al evitar la reutilización de vértices.

void optimize_indices_for_cache() 🔗

Optimiza la ordenación de triángulos para mejorar el rendimiento. Requiere que get_primitive_type() sea Mesh.PRIMITIVE_TRIANGLES.

void set_bones(bones: PackedInt32Array) 🔗

Especifica un array de huesos para usar para el siguiente vértice. bones debe contener 4 enteros.

void set_color(color: Color) 🔗

Especifica un Color para usar para el siguiente vértice. Si cada vértice necesita tener esta información establecida y no la envías para el primer vértice, es posible que esta información no se utilice en absoluto.

Nota: El material debe tener BaseMaterial3D.vertex_color_use_as_albedo activado para que el color del vértice sea visible.

void set_custom(channel_index: int, custom_color: Color) 🔗

Establece el valor personalizado en este vértice para channel_index.

set_custom_format() debe ser llamado primero para este channel_index. Los formatos que no son RGBA ignorarán otros canales de color.

void set_custom_format(channel_index: int, format: CustomFormat) 🔗

Establece el formato de color para este channel_index personalizado. Usa CUSTOM_MAX para desactivarlo.

Debe invocarse después de begin() y debe establecerse antes de commit() o commit_to_arrays().

void set_material(material: Material) 🔗

Establece Material para ser usado por la Mesh que estás construyendo.

void set_normal(normal: Vector3) 🔗

Especifica una normal para usar para el siguiente vértice. Si cada vértice necesita tener esta información establecida y no la envías para el primer vértice, es posible que esta información no se utilice en absoluto.

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

Especifica el grupo suavizado a usar para el siguiente vértice. Si nunca se llama a esto, todos los vértices tendrán el grupo suavizado por defecto de 0 y se suavizarán con los vértices adyacentes del mismo grupo. Para producir una malla con normales planas, establece el grupo suavizado a -1.

Nota: Esta función en realidad toma un uint32_t, por lo que los usuarios de C# deben usar uint32.MaxValue en lugar de -1 para producir una malla con normales planas.

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

Especifica un conjunto de coordenadas UV para usar para el siguiente vértice. Si cada vértice necesita tener esta información establecida y no la envías para el primer vértice, es posible que esta información no se utilice en absoluto.

void set_uv2(uv2: Vector2) 🔗

Especifica un segundo conjunto opcional de coordenadas UV para usar en el siguiente vértice. Si cada vértice necesita tener esta información establecida y no la envías para el primer vértice, puede que esta información no se use en absoluto.

void set_weights(weights: PackedFloat32Array) 🔗

Especifica los valores de peso a usar para el siguiente vértice. weights debe contener 4 valores. Si cada vértice necesita tener esta información establecida y no la envías para el primer vértice, puede que esta información no se use en absoluto.