Renderer: экземпляр рендеринга

Экземпляр рендеринга LCC, отвечающий за загрузку данных и управление рендерингом одной сцены 3DGS. Он создаётся через LCCManager.GetRender() и не может быть создан напрямую.

Свойства

Методы

Методы сгруппированы по назначению:

• Загрузка данных и жизненный цикл
• Управление во время выполнения и запросы

Загрузка данных и жизненный цикл

Load

public void Load(string _filePath, Action<float> _onProgress, Action _onComplete, Action<string> _onError = null)

Загружает файл данных 3DGS. Поддерживает .lcc2 (локальный файл или удалённый по HTTP) и нативные форматы .ply / .sog / .spz / .splat / .ksplat (только локальные файлы).

Примечания:

• Обратный вызов _onComplete срабатывает после того, как данные фактически попадут на GPU.
• Операции, такие как приём теней и запуск эффектов, должны вызываться внутри обратного вызова _onComplete.
• Нативные форматы всегда используют путь полной загрузки SingleRender (без разбиения на LOD-чанки); прогресс сообщается через _onProgress, а ошибки — через _onError.
• Режим MultiRender не допускает источники данных HTTP или нативные форматы.
• HTTP поддерживает только .lcc2; нативные форматы — только локальные пути и только режим SingleRender.
• SetPlatformType() / SwitchRenderPass() / SetMainCamera() и другие предварительные условия должны быть выполнены сначала.
• Необходимо вызвать Unload() или Dispose() перед повторным вызовом Load(); вызов Load() во время выполняющейся загрузки отклоняется и вызывает _onError.

Пример:

renderer.Load("D:/data/scene.lcc2",
    p => Debug.Log($"Загрузка {p:P0}"),
    () => {
        Debug.Log("Загрузка завершена");
        lccManager.SetShadowReceive(true);
    });

Unload

public void Unload()

Освобождает текущие загруженные данные и возвращается в состояние «создан, но не загружен», сохраняя регистрацию экземпляра в менеджере. Один и тот же экземпляр Renderer можно переиспользовать, многократно выполняя цикл Load → Unload → Load.

Примечания:

• Отличие от Dispose(): регистрация в менеджере не удаляется, и экземпляр можно переиспользовать.
• После Unload() IsEnable равен false; повторный вызов Load() сбрасывает всё состояние данных.
• Выполняется только когда данные завершили загрузку; возвращается сразу, когда данные не загружены или уже вызван Dispose().

Пример:

renderer.Unload();
renderer.Load(newFilePath, null, () => Debug.Log("Перезагружено"));

Dispose

public void Dispose()

Уничтожает экземпляр рендеринга и освобождает все ресурсы GPU и память. После уничтожения экземпляр нельзя использовать, и все публичные методы автоматически становятся неэффективными.

Примечания:

• После вызова автоматически уведомляет LCCManager об удалении ссылки.

Пример:

renderer.Dispose();
renderer = null;

Управление во время выполнения и запросы

SetEnable

public void SetEnable(bool _enable)

Задаёт состояние активации экземпляра рендеринга. При отключении он не участвует в рендеринге или выборе LOD.

Примечания:

• Не освобождает ресурсы и может быть повторно активирован в любое время.

Пример:

renderer.SetEnable(false); // Скрыть
renderer.SetEnable(true);  // Показать

SetAlpha

public void SetAlpha(float alpha)

Задаёт независимую непрозрачность текущего Renderer. В отличие от глобальной альфы уровня процесса LCCManager.SetAlpha(), этот API влияет только на текущий Renderer. Итоговая альфа = покрытие сплата × глобальная альфа LCCManager × альфа этого Renderer.

Примечания:

• Действует только на пути MultiRender / RenderCore (PC / Mac); на этом пути каждый сплат несёт renderID, и шейдер индексирует массив альф по Renderer через renderID.
• Путь FullRender / Mobile не имеет renderID, поэтому этот API там ничего не делает (значение кэшируется и автоматически применяется при последующем переключении на путь RenderCore).

Пример:

renderer.SetAlpha(0.5f);

SetRenderAll

public void SetRenderAll(bool _renderAll)

Задаёт, использовать ли режим полного рендеринга (полный рендеринг данных LOD0). Он вступает в силу при следующем вызове Load() и не влияет на текущий загруженный набор данных.

Примечания:

• Поддерживается только на платформах PC / Mac; на mobile / VR не действует.
• Текущее состояние можно запросить через свойство IsRenderAll.

Пример:

renderer.SetRenderAll(true);
renderer.Load(filePath, null, () => Debug.Log("Полностью загружено"));

SetColliderEnable

// Возвращаемое значение: bool, true=установлено успешно, false=данные не имеют коллайдера или экземпляр неактивен
public bool SetColliderEnable(bool _enable)

Переключает функцию коллайдера. После включения IntersectsSphere() / IntersectsCapsule() и RaycastMesh() становятся доступными.

Примечания:

• Данные должны содержать узел Collider, иначе возвращается false.
• Renderer должен быть активен.

Пример:

bool ok = renderer.SetColliderEnable(true);
if (!ok) Debug.LogWarning("Данные не содержат коллайдера");

SetEnvironment

public void SetEnvironment(bool _env)

Переключает рендеринг данных окружения. Данные окружения — это низкодетальное фоновое облако точек, используемое для заполнения дальних видов.

Примечания:

• Данные должны содержать узлы окружения.
• Данные окружения независимы от системы LOD основных данных.

Пример:

renderer.SetEnvironment(true);

GetBounds

public void GetBounds(out Vector3 max, out Vector3 min)

Получает выровненный по осям ограничивающий параллелепипед (мировые координаты) отрендеренных данных.

Примечания:

• Возвращает Vector3.zero, когда данные загружены не полностью.
• Может использоваться для позиционирования камеры и расчёта угла обзора.

Пример:

renderer.GetBounds(out Vector3 max, out Vector3 min);
Vector3 center = (max + min) / 2f;
Vector3 size = max - min;

GetSourceType

// Возвращаемое значение: SourceType
public SourceType GetSourceType()

Получает тип источника загруженных данных; см. SourceType.

Примечания:

• Возвращает SourceType.None, когда данные не загружены.

GetDataType

// Возвращаемое значение: DataType
public DataType GetDataType()

Получает тип формата загруженных данных; см. DataType.

Примечания:

• Возвращает DataType.None, когда данные не загружены.

GetMeta (по пути к файлу)

// Возвращаемое значение: bool, true=прочитано успешно
public bool GetMeta(string _filePath, out SplatMeta _metaData)

Читает метаданные данных 3DGS по указанному пути к файлу без полной загрузки данных.

Примечания:

• Поддерживает локальные пути и HTTP URL.
• Читает только метаданные заголовка файла и не загружает данные облака точек.
• Возвращает false, когда путь пуст или файл не существует.

Пример:

if (renderer.GetMeta(filePath, out SplatMeta meta))
{
    Debug.Log(meta.source);
    Debug.Log(meta.dataType);
}

GetMeta (по загруженным данным)

// Возвращаемое значение: bool, true=прочитано успешно
public bool GetMeta(out SplatMeta _metaData)

Получает метаданные текущих загруженных данных. Если данные ещё не завершили загрузку, он пытается прочитать из пути к файлу.

Пример:

if (renderer.GetMeta(out SplatMeta meta))
{
    Debug.Log(meta.source);
}

GetMeshBlockInfos

// Возвращаемое значение: List<LCCMeshBlockInfo>, метаданные блоков коллизионного Mesh; null при отсутствии Mesh или недоступности
public List<LCCMeshBlockInfo> GetMeshBlockInfos()

Возвращает метаданные всех коллизионных блоков Mesh (id, мировой / локальный ограничивающий параллелепипед, количество вершин, количество граней). Без I/O и без разбора — только читает метаданные, уже находящиеся в памяти. См. LCCMeshBlockInfo.

Примечания:

• Только платформа PC / Mac + локальный источник данных; должен вызываться в основном потоке.
• Типичное использование: сначала получить мировой ограничивающий параллелепипед каждого блока, выбрать нужные id, затем вызвать GetMeshes(ids) для чтения только этих блоков.
• Нативные форматы (PLY / SOG / SPZ / splat / ksplat) не имеют Mesh и возвращают null (нормально, без журнала).

Пример:

var infos = renderer.GetMeshBlockInfos();
foreach (var info in infos)
{
    Debug.Log($"{info.id}: вершин={info.vertexCount}, граней={info.faceCount}");
}

GetMeshes

// Возвращаемое значение: List<LCCMeshBlock>, все геометрические данные коллизионного Mesh; null при недоступности
public List<LCCMeshBlock> GetMeshes()

Синхронно возвращает геометрические данные всех коллизионных блоков Mesh (вершины + индексы треугольников, в локальных координатах). Это тяжёлая операция (синхронное чтение с диска + разбор + выделение), поэтому вызовите её один раз и кэшируйте самостоятельно — никогда не вызывайте каждый кадр. См. LCCMeshBlock.

Примечания:

• Только платформа PC / Mac + локальный источник данных; должен вызываться в основном потоке.
• Для больших сцен используйте GetMeshBlockInfos() для выбора id + GetMeshes(ids), чтобы избежать выделения огромного объёма управляемой памяти сразу.
• Один блок может иметь более 65535 вершин, поэтому перед построением Mesh необходимо задать mesh.indexFormat = IndexFormat.UInt32.

Пример:

var meshes = renderer.GetMeshes();
foreach (var block in meshes)
{
    // block.vertices / block.triangles находятся в локальной системе координат объекта
}

GetMeshes (по id)

// Возвращаемое значение: List<LCCMeshBlock>, геометрические данные коллизионного Mesh для указанных id; null при отсутствии попаданий
public List<LCCMeshBlock> GetMeshes(IEnumerable<string> _ids)

Синхронно возвращает геометрические данные коллизионных блоков Mesh (в локальных координатах) для указанных id. id предоставляются методом GetMeshBlockInfos().

Примечания:

• Неизвестные id пропускаются с предупреждением; дублирующиеся id дедуплицируются (без повторного чтения с диска); порядок возврата — это порядок обхода id (после дедупликации).
• Возвращает null с предупреждением, когда ввод равен null, пуст или не имеет попаданий.
• Остальные ограничения такие же, как у GetMeshes().

Пример:

var ids = new List<string> { "block-0", "block-3" };
var meshes = renderer.GetMeshes(ids);