ImmediateMesh

ImmediateMesh — ресурс Mesh, не команда рисования поверх кадра и не Entity. SurfaceBegin начинает одну поверхность, SurfaceAddVertex добавляет углы, SurfaceEnd публикует готовую поверхность. Для показа назначьте ресурс MeshInstance3D.Mesh и разместите экземпляр в дереве. Геометрия сохраняется между кадрами: повторный Begin/End добавляет ещё одну поверхность, а не заменяет предыдущую.

using var mesh = new ImmediateMesh();
mesh.SurfaceBegin(Mesh.PrimitiveType.Lines);
mesh.SurfaceSetColor(new Color(1, 0, 0));
mesh.SurfaceAddVertex(new Vector3(0, 0, 2));
mesh.SurfaceAddVertex(new Vector3(1, 0, 2));
mesh.SurfaceEnd();
int surfaceCount = mesh.GetSurfaceCount(); // 1

Пример создаёт данные линии без видимого объекта. При назначении mesh экземпляру сохраняйте ресурс живым на всё время использования; не завершайте его using раньше. Для видимого цвета нужен материал, использующий vertex color, например StandardMaterial3D с VertexColorUseAsAlbedo = true. Сам SurfaceSetColor материал не настраивает. Unshaded-материал подходит для диагностических линий без зависимости от света. Толщина линии в пикселях этим API не задаётся.

Порядок работы: Begin → необязательные setters атрибутов → добавление вершин → End. Одновременно открыта только одна поверхность. End без вершин отклоняется и не закрывает сборку. Для Lines добавляйте пары, для Triangles — тройки углов; индексов, bones/weights, custom-каналов, blend shapes и LOD этот builder не создаёт. Большую повторяющуюся геометрию удобнее подготовить через ArrayMesh или SurfaceTool, а не пересобирать здесь каждый кадр.

Атрибуты запоминаются для следующих вершин. Первый вызов setter также заполняет уже добавленные вершины текущей поверхности этим значением. Следующий вызов меняет только будущие вершины. Это отличается от SurfaceTool: канал можно включить после первой вершины. После успешного End признаки каналов сбрасываются — задавайте нужные атрибуты заново при каждом Begin. Color хранится в 8 бит на канал: значения ограничиваются диапазоном 0…1 и квантуются. Normals/tangents упаковываются, поэтому чтение не обязано дать побитово исходные float.

SurfaceAddVertex2D задаёт Vector2 в буфере mesh; он не создаёт CanvasItem и не переключает сцену в 2D. В одной поверхности нельзя смешивать 2D и 3D. SurfaceEnd сбрасывает размерность для следующей поверхности. Известный дефект версии 1.0.0: ClearSurfaces во время незавершённой 2D-сборки не сбрасывает её размерность. Следующий первый Vector3 теряет Z, дальнейший Vector3 отклоняется. После такого прерывания создайте новый ImmediateMesh; повторный ClearSurfaces дефект не устраняет.

SurfaceEnd отправляет Changed, а ClearSurfaces — нет. Если зависимый код ждёт уведомление после очистки, отправьте EmitChanged явно. ClearSurfaces удаляет все готовые поверхности и отменяет текущую сборку. Полученные SurfaceGetArrays — снимок данных, не live-редактор. Формат и число вершин можно проверять по этим массивам; не переносите C++-виртуальные SurfaceGetArrayLen/SurfaceGetFormat в C# — этих публичных методов здесь нет.

Для треугольников подготовьте normals и UV самостоятельно. Если заданы normals без tangents, движок создаёт вспомогательный tangent из normal, не из UV-развёртки. Для normal mapping задайте согласованные tangents или используйте SurfaceTool.GenerateTangents. SurfaceSetUV2 только записывает координаты, не разворачивает геометрию и не запекает свет.

17 Windows headless-проверок подтвердили CPU-данные и воспроизвели дефект размерности. Полный native-прогон отмечен неуспешным из-за диагностического сообщения в этом сценарии, хотя его ожидаемое поведение зафиксировано. Видимая отрисовка, normal mapping, произвольная геометрия и производительность не подтверждены; движок не исправлялся.

Объявления сверены с C# SDK 1.0.0. Раскройте имя, чтобы увидеть сигнатуры и описание.

public ImmediateMesh();

public void ClearSurfaces();

public void SurfaceAddVertex(Vector3 vertex);

public void SurfaceAddVertex2D(Vector2 vertex);

public void SurfaceBegin(Mesh.PrimitiveType primitive, Material material = null);

public void SurfaceEnd();

public void SurfaceSetColor(Color color);

public void SurfaceSetNormal(Vector3 normal);

public void SurfaceSetTangent(Plane tangent);

public void SurfaceSetUV(Vector2 uV);

public void SurfaceSetUV2(Vector2 uV2);