Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

Nutzen des SurfaceTools

Das SurfaceTool bietet eine nützliche Schnittstelle für die Konstruktion von Geometrie. Die Schnittstelle ist ähnlich wie der ImmediateMesh-Node. Man setzt jedes Attribut pro Vertex (z.B. normal, uv, Farbe) und wenn man dann einen Vertex hinzufügt, werden die Attribute erfasst.

Das SurfaceTool bietet auch einige nützliche Hilfsfunktionen wie index() und generate_normals().

Attribute werden hinzugefügt, bevor jeder Vertex hinzugefügt wird:

st.set_normal() # Overwritten by normal below.
st.set_normal() # Added to next vertex.
st.set_color() # Added to next vertex.
st.add_vertex() # Captures normal and color above.
st.set_normal() # Normal never added to a vertex.

Wenn die Erzeugung der Geometrie mit dem SurfaceTool abgeschlossen ist, rufen Sie commit() auf, um die Erzeugung des Meshs zu beenden. Wenn ein ArrayMesh an commit() übergeben wird, dann wird eine neue Oberfläche an das Ende des ArrayMeshs angehängt. Wenn nichts übergeben wird, gibt commit() ein ArrayMesh zurück.

st.commit(mesh)
# Or:
var mesh = st.commit()

Code erstellt ein Dreieck mit Indizes

var st = SurfaceTool.new()

st.begin(Mesh.PRIMITIVE_TRIANGLES)

# Prepare attributes for add_vertex.
st.set_normal(Vector3(0, 0, 1))
st.set_uv(Vector2(0, 0))
# Call last for each vertex, adds the above attributes.
st.add_vertex(Vector3(-1, -1, 0))

st.set_normal(Vector3(0, 0, 1))
st.set_uv(Vector2(0, 1))
st.add_vertex(Vector3(-1, 1, 0))

st.set_normal(Vector3(0, 0, 1))
st.set_uv(Vector2(1, 1))
st.add_vertex(Vector3(1, 1, 0))

# Commit to a mesh.
var mesh = st.commit()

Sie können optional ein Index-Array hinzufügen, entweder durch den Aufruf von add_index() und Hinzufügen von Vertices zum Index-Array oder durch den Aufruf von index(), der das Vertex-Array verkleinert, um doppelte Vertices zu entfernen.

# Creates a quad from four corner vertices.
# add_index does not need to be called before add_vertex.
st.add_index(0)
st.add_index(1)
st.add_index(2)

st.add_index(1)
st.add_index(3)
st.add_index(2)

# Alternatively:
st.index()

Ähnlich verhält es sich, wenn Sie ein Index-Array haben, aber wollen, dass jeder Vertex eindeutig ist (z.B. weil Sie eindeutige Normalen oder Farben pro Fläche statt pro Vertex verwenden wollen), können Sie deindex() aufrufen.

st.deindex()

Wenn Sie keine eigenen Normalen hinzufügen, können Sie sie mit generate_normals() hinzufügen, was nach der Erzeugung der Geometrie und vor der Übergabe des Meshs mit commit() oder commit_to_arrays() aufgerufen werden sollte. Der Aufruf von generate_normals(true) wird die resultierenden Normalen umkehren. Nebenbei bemerkt, generate_normals() funktioniert nur, wenn der primitive Typ auf Mesh.PRIMITIVE_TRIANGLES gesetzt ist.

Möglicherweise werden Sie feststellen, dass das Normal Mapping oder andere Material-Propertys auf dem generierten Mesh nicht korrekt aussehen. Das liegt daran, dass die Normalenabbildung erfordert, dass das Mesh Tangenten aufweist, die von den Normalen getrennt sind. Sie können entweder manuell eigene Tangenten hinzufügen oder sie automatisch mit generate_tangents() erzeugen. Diese Methode setzt voraus, dass jeder Vertex bereits UVs und Normalen gesetzt hat.

st.generate_normals()
st.generate_tangents()

Standardmäßig werden bei der Erzeugung von Normalen diese pro Fläche berechnet. Wenn Sie glatte Vertexnormalen wollen, rufen Sie add_smooth_group() auf, wenn Sie Vertices hinzufügen. add_smooth_group() muss während der Erstellung der Geometrie aufgerufen werden, z.B. vor dem Aufruf von add_vertex() (wenn nicht indiziert) oder add_index() (wenn indiziert).