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

Eredita: RefCounted < Object

Strumento di supporto per la creazione di geometrie.

Descrizione

SurfaceTool serve per costruire una Mesh specificando gli attributi dei vertici singolarmente. Può essere utilizzato per costruire una Mesh da uno script. È necessario aggiungere tutte le proprietà, eccetto gli indici, prima di chiamare add_vertex(). Ad esempio, per aggiungere i colori dei vertici e gli 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));

Il suddetto SurfaceTool ora contiene un vertice di un triangolo che ha una coordinata UV e un Color specificato. Se un altro vertice fosse aggiunto senza chiamare set_uv() o set_color(), sarebbero utilizzati gli ultimi valori.

Gli attributi dei vertici devono essere passati prima di chiamare add_vertex(). Altrimenti, si verificherà un errore commettendo le informazioni del vertice in una mesh.

Inoltre, gli attributi utilizzati prima di aggiungere il primo vertice determinano il formato della mesh. Ad esempio, se si aggiungono solo gli UV al primo vertice, non è possibile aggiungere il colore a nessuno dei vertici successivi.

Vedi anche ArrayMesh, ImmediateMesh e MeshDataTool per la generazione di geometria procedurale.

Nota: Godot utilizza l'ordine di avvolgimento in senso orario per le facce frontali delle modalità di primitiva triangolare.

Tutorial

Metodi

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)

Enumerazioni

enum CustomFormat: 🔗

CustomFormat CUSTOM_RGBA8_UNORM = 0

Limita l'intervallo dei dati passati a set_custom() normalizzato da 0 a 1 (senza segno), memorizzato in 8 bit per canale. Vedi Mesh.ARRAY_CUSTOM_RGBA8_UNORM.

CustomFormat CUSTOM_RGBA8_SNORM = 1

Limita l'intervallo dei dati passati a set_custom() normalizzato da -1 a 1 (con segno), memorizzato in 8 bit per canale. Vedi Mesh.ARRAY_CUSTOM_RGBA8_SNORM.

CustomFormat CUSTOM_RG_HALF = 2

Memorizza i dati passati a set_custom() in valori in virgola mobile a mezza precisione, utilizzando i canali di colore rosso e verde. Vedi Mesh.ARRAY_CUSTOM_RG_HALF.

CustomFormat CUSTOM_RGBA_HALF = 3

Memorizza i dati passati a set_custom() in valori in virgola mobile a mezza precisione, utilizzando tutti i canali di colore. Vedi Mesh.ARRAY_CUSTOM_RGBA_HALF.

CustomFormat CUSTOM_R_FLOAT = 4

Memorizza i dati passati a set_custom() in valori in virgola mobile a precisione completa, utilizzando solo il canale di colore rosso. Vedi Mesh.ARRAY_CUSTOM_R_FLOAT.

CustomFormat CUSTOM_RG_FLOAT = 5

Memorizza i dati passati a set_custom() in valori in virgola mobile a precisione completa, utilizzando solo i canali di colore rosso e verde. Vedi Mesh.ARRAY_CUSTOM_RG_FLOAT.

CustomFormat CUSTOM_RGB_FLOAT = 6

Memorizza i dati passati a set_custom() in valori in virgola mobile a precisione completa, utilizzando solo i canali di colore rosso, blu e verde. Vedi Mesh.ARRAY_CUSTOM_RGB_FLOAT.

CustomFormat CUSTOM_RGBA_FLOAT = 7

Memorizza i dati passati a set_custom() in valori in virgola mobile a precisione completa, utilizzando tutti i canali di colore. Vedi Mesh.ARRAY_CUSTOM_RGBA_FLOAT.

CustomFormat CUSTOM_MAX = 8

Utilizzato per indicare un canale personalizzato disabilitato.

enum SkinWeightCount: 🔗

SkinWeightCount SKIN_4_WEIGHTS = 0

Ogni singolo vertice può essere influenzato solo da 4 pesi di ossa.

SkinWeightCount SKIN_8_WEIGHTS = 1

Ogni singolo vertice può essere influenzato da un massimo di 8 pesi di ossa.

Descrizioni dei metodi

void add_index(index: int) 🔗

Aggiunge un vertice all'array di indici se si utilizzano vertici indicizzati. Non è necessario chiamarlo prima di aggiungere i vertici.

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

Inserisce un ventaglio triangolare costituito da un array di dati nella Mesh in fase di costruzione.

Richiede che il tipo di primitiva sia impostato su Mesh.PRIMITIVE_TRIANGLES.

void add_vertex(vertex: Vector3) 🔗

Specifica la posizione del vertice attuale. Dovrebbe essere chiamato dopo aver specificato le altre proprietà del vertice (ad esempio il colore, l'UV).

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

Aggiunge i vertici da una determinata superficie della Mesh all'array attuale di vertici con il Transform3D specificato.

void begin(primitive: PrimitiveType) 🔗

Chiamato prima di aggiungere qualsiasi vertice. Accetta il tipo di primitiva come argomento (ad esempio Mesh.PRIMITIVE_TRIANGLES).

void clear() 🔗

Cancella tutte le informazioni passate finora allo strumento di superficie.

ArrayMesh commit(existing: ArrayMesh = null, flags: int = 0) 🔗

Restituisce un ArrayMesh costruito dalle informazioni attuali passate. Se un ArrayMesh esistente viene passato come argomento, aggiungerà una superficie aggiuntiva all'ArrayMesh esistente.

L'argomento flags può essere l'OR bit a bit di Mesh.ARRAY_FLAG_USE_DYNAMIC_UPDATE, Mesh.ARRAY_FLAG_USE_8_BONE_WEIGHTS o Mesh.ARRAY_FLAG_USES_EMPTY_VERTEX_ARRAY.

Array commit_to_arrays() 🔗

Commette i dati nello stesso formato utilizzato da ArrayMesh.add_surface_from_arrays(), ImporterMesh.add_surface() e create_from_arrays(). In questo modo è possibile elaborare ulteriormente i dati della mesh utilizzando le API di ArrayMesh o ImporterMesh.

void create_from(existing: Mesh, surface: int) 🔗

Crea un array di vertici da una Mesh esistente.

void create_from_arrays(arrays: Array, primitive_type: PrimitiveType = 3) 🔗

Crea questo SurfaceTool dagli array di vertici esistenti come quelli restituiti da commit_to_arrays(), Mesh.surface_get_arrays(), Mesh.surface_get_blend_shape_arrays(), ImporterMesh.get_surface_arrays() e ImporterMesh.get_surface_blend_shape_arrays(). primitive_type controlla il tipo di dati della mesh, il cui valore predefinito è Mesh.PRIMITIVE_TRIANGLES.

void create_from_blend_shape(existing: Mesh, surface: int, blend_shape: String) 🔗

Crea un array di vertici dalla forma di fusione specificata di una Mesh esistente. Può essere utilizzato per estrarre una posa specifica da una forma di fusione.

void deindex() 🔗

Rimuove l'array degli indici espandendo la matrice dei vertici.

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

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

Genera un LOD per la soglia nd_threshold in unità lineari (radice quadrata della metrica di errore quadrico), utilizzando al massimo target_index_count indici.

void generate_normals(flip: bool = false) 🔗

Genera le normali dai vertici in modo da non doverlo fare manualmente. Se flip è true, le normali risultanti saranno invertite. generate_normals() dovrebbe essere chiamato dopo la generazione della geometria e prima di commettere le mesh usando commit() o commit_to_arrays(). Per visualizzare correttamente le superfici mappate con le normali, sarà necessario anche generare le tangenti usando generate_tangents().

Nota: generate_normals() funziona solo se il tipo di primitiva è impostato su Mesh.PRIMITIVE_TRIANGLES.

Nota: generate_normals() tiene conto dei gruppi lisci. Per generare normali lisce, imposta il gruppo di lisciatura su un valore maggiore o uguale a 0 tramite set_smooth_group() o lascia il gruppo sul valore predefinito di 0. Per generare normali piatte, imposta il gruppo di lisciatura su -1 tramite set_smooth_group() prima di aggiungere i vertici.

void generate_tangents() 🔗

Genera un vettore tangente per ogni vertice. Richiede che ogni vertice abbia già impostato gli UV e le normali (vedi generate_normals()).

AABB get_aabb() const 🔗

Restituisce la bounding box allineata agli assi delle posizioni dei vertici.

CustomFormat get_custom_format(channel_index: int) const 🔗

Restituisce il formato per il canale personalizzato all'indice channel_index (attualmente fino a 4). Restituisce CUSTOM_MAX se questo canale personalizzato non è utilizzato.

PrimitiveType get_primitive_type() const 🔗

Restituisce il tipo di geometria della mesh, come ad esempio Mesh.PRIMITIVE_TRIANGLES.

SkinWeightCount get_skin_weight_count() const 🔗

Come predefinito, restituisce SKIN_4_WEIGHTS per indicare che sono utilizzate solo 4 influenze delle ossa per ogni vertice.

Restituisce SKIN_8_WEIGHTS se sono utilizzate fino a 8 influenze.

Nota: Questa funzione restituisce un'enumerazione, non il numero esatto di pesi.

void index() 🔗

Riduce l'array dei vertici creando un array di indici. Ciò può migliorare le prestazioni evitando che i vertici siano riutilizzati.

void optimize_indices_for_cache() 🔗

Ottimizza l'ordinamento dei triangoli per migliorare le prestazioni. Richiede che get_primitive_type() sia Mesh.PRIMITIVE_TRIANGLES.

void set_bones(bones: PackedInt32Array) 🔗

Specifica un array di ossa da utilizzare per il prossimo vertice. bones deve contenere 4 numeri interi.

void set_color(color: Color) 🔗

Specifica un Color da usare per il prossimo vertice . Se ogni vertice deve avere questa informazione impostata e non la si invia per il primo vertice, tale informazione potrebbe non essere usata affatto.

Nota: Il materiale deve avere BaseMaterial3D.vertex_color_use_as_albedo abilitato affinché il colore del vertice sia visibile.

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

Imposta il valore personalizzato su questo vertice per il canale all'indice channel_index.

È necessario chiamare prima set_custom_format() per il canale all'indice channel_index. I formati che non sono RGBA ignoreranno gli altri canali di colore.

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

Imposta il formato colore per il canale personalizzato all'indice channel_index. Usa CUSTOM_MAX per disabilitare.

Deve essere richiamato dopo begin() e impostato prima di commit() o commit_to_arrays().

void set_material(material: Material) 🔗

Imposta il Material da utilizzare per la Mesh che stai costruendo.

void set_normal(normal: Vector3) 🔗

Specifica una normale da usare per il prossimo vertice. Se ogni vertice deve avere questa informazione impostata e non la si invia per il primo vertice, tale informazione potrebbe non essere usata affatto.

void set_skin_weight_count(count: SkinWeightCount) 🔗

Imposta su SKIN_8_WEIGHTS per indicare che è possibile utilizzare fino a 8 influenze delle ossa per ogni vertice.

Come predefinito, sono utilizzate solo 4 influenze delle ossa (SKIN_4_WEIGHTS)

Nota: Questa funzione accetta un'enumerazione, non il numero esatto di pesi.

void set_smooth_group(index: int) 🔗

Specifica il gruppo di lisciatura da usare per il prossimo vertice. Se non viene mai chiamato, tutti i vertici avranno il gruppo di lisciatura predefinito di 0 e saranno lisciati con i vertici adiacenti dello stesso gruppo. Per produrre una mesh con normali piatte, imposta il gruppo di lisciatura su -1.

Nota: Questa funzione in realtà accetta un uint32_t, quindi gli utenti in C# dovrebbero usare uint32.MaxValue invece di -1 per produrre una mesh con normali piatte.

void set_tangent(tangent: Plane) 🔗

Specifica un Color da usare per il prossimo vertice. Se ogni vertice deve avere questa informazione impostata e non la si invia per il primo vertice, tale informazione potrebbe non essere usata affatto.

Nota: Sebbene tangent sia un Plane, non rappresenta direttamente il piano tangente. I suoi Plane.x, Plane.y e Plane.z rappresentano il vettore tangente e Plane.d dovrebbero essere -1 o 1. Vedi anche Mesh.ARRAY_TANGENT.

void set_uv(uv: Vector2) 🔗

Specifica le coordinate UV da usare per il prossimo vertice. Se ogni vertice deve avere questa informazione impostata e non la si invia per il primo vertice, tale informazione potrebbe non essere usata affatto.

void set_uv2(uv2: Vector2) 🔗

Specifica le coordinate UV secondarie da usare per il prossimo vertice. Se ogni vertice deve avere questa informazione impostata e non la si invia per il primo vertice, tale informazione potrebbe non essere usata affatto.

void set_weights(weights: PackedFloat32Array) 🔗

Specifica i valori di peso da usare per il prossimo vertice. Se ogni vertice deve avere questa informazione impostata e non la si invia per il primo vertice, tale informazione potrebbe non essere usata affatto.