Up to date

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

Використання SurfaceTool¶

The SurfaceTool provides a useful interface for constructing geometry. The interface is similar to the ImmediateMesh node. You set each per-vertex attribute (e.g. normal, uv, color) and then when you add a vertex it captures the attributes.

SurfaceTool також має такі корисні функції як index() (використовувати індекс вершин) і generate_normals() (автоматично задати нормалі).

Атрибути потрібно додавати перед тим як додавати вершину:

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.

st.SetNormal(); // Overwritten by normal below.
st.SetNormal(); // Added to next vertex.
st.SetColor(); // Added to next vertex.
st.AddVertex(); // Captures normal and color above.
st.SetNormal(); // Normal never added to a vertex.

Коли закінчите задавати геометрію в SurfaceTool, викличіть функцію commit() щоб завершити побудову меша. Якщо до функції commit() передати ArrayMesh то раніше створена геометрія буде додана до ArrayMesh в кінець списку. Якщо ж до функції нічого не передати, то вона сама поверне ArrayMesh.

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

st.Commit(mesh);
// Or:
var mesh = st.Commit();

Цей код побудує трикутник з індексами

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

var st = new SurfaceTool();

st.Begin(Mesh.PrimitiveType.Triangles);

// Prepare attributes for AddVertex.
st.SetNormal(new Vector3(0, 0, 1));
st.SetUV(new Vector2(0, 0));
// Call last for each vertex, adds the above attributes.
st.AddVertex(new Vector3(-1, -1, 0));

st.SetNormal(new Vector3(0, 0, 1));
st.SetUV(new Vector2(0, 1));
st.AddVertex(new Vector3(-1, 1, 0));

st.SetNormal(new Vector3(0, 0, 1));
st.SetUV(new Vector2(1, 1));
st.AddVertex(new Vector3(1, 1, 0));

// Commit to a mesh.
var mesh = st.Commit();

Ви можете додати індекси або викликавши метод add_index() та вручну додавши вершини до списку індексів, або викликавши index(), який прибере зі списку вершин вершини що повторюються.

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

// Creates a quad from four corner vertices.
// AddIndex does not need to be called before AddVertex.
st.AddIndex(0);
st.AddIndex(1);
st.AddIndex(2);

st.AddIndex(1);
st.AddIndex(3);
st.AddIndex(2);

// Alternatively:
st.Index();

Схожим чином, якщо у вас є список індексів вершин, але ви хочете щоб вершини кожного трикутника була окремими (бо ви хочете задавати нормалі та колір трикутникам а не вершинам), то ви можете використати deindex().

st.deindex()

st.Deindex();

Якщо ви не додали нормалей самостійно, то ви можете зробити це з функцією generate_normals(), яка повинна викликатись після того як геометрія була створена, але ще не записана до об'єкта функціями commit() чи commit_to_arrays(). Виклик generate_normals(true) виверне нормалі навиворіт. Між іншим, generate_normals() працює лише тоді, коли тип геометрії заданий як Mesh.PRIMITIVE_TRIANGLES.

You may notice that normal mapping or other material properties look broken on the generated mesh. This is because normal mapping requires the mesh to feature tangents, which are separate from normals. You can either add custom tangents manually, or generate them automatically with generate_tangents(). This method requires that each vertex have UVs and normals set already.

st.generate_normals()
st.generate_tangents()

st.GenerateNormals();
st.GenerateTangents();

Типово, нормалі обчислюються окремо для кожного трикутника окремо. Якщо ж ви хочете щоб ваша поверхня була гладенькою, перед тим як додавати вершини до неї, викличіть add_smooth_group(). Функцію потрібно застосовувати не пізніше виклику add_vertex() (для не індексованої геометрії) або add_index() (для індексованої).