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() 等前置配置。
• 重新 Load 前必须先调用 Unload() 或 Dispose()；加载进行中再次 Load 会被拒绝并触发 _onError。

调用示例：

renderer.Load("D:/data/scene.lcc2",
    p => Debug.Log($"Loading {p:P0}"),
    () => {
        Debug.Log("Load complete");
        lccManager.SetShadowReceive(true);
    });

Unload

public void Unload()

释放当前已加载数据，回到「已创建未加载」状态，保留实例的管理器注册。可反复 Load → Unload → Load 循环复用同一个 Renderer 实例。

说明：

• 与 Dispose() 的差异：不移除管理器注册，实例可继续复用。
• Unload() 后 IsEnable 为 false，再次 Load() 会重置所有数据状态。
• 仅在数据已加载完成时执行；未加载或已 Dispose() 时直接返回。

调用示例：

renderer.Unload();
renderer.Load(newFilePath, null, () => Debug.Log("Reloaded"));

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() 的进程级全局 alpha，本接口只影响当前 Renderer。最终 alpha = splat 覆盖率 × LCCManager 全局 alpha × 本 Renderer alpha。

说明：

• 仅在 MultiRender / RenderCore 路径（PC / Mac）生效；该路径下每个 splat 携带 renderID，shader 按 renderID 索引 per-Renderer alpha 数组。
• FullRender / Mobile 路径无 renderID，本接口对其为 no-op（值已缓存，后续切入 RenderCore 路径会自动应用）。

调用示例：

renderer.SetAlpha(0.5f);

SetRenderAll

public void SetRenderAll(bool _renderAll)

设置是否使用全量渲染模式（全量渲染 LOD0 数据）。设置后在下次 Load() 调用时生效，不影响当前已加载的数据集。

说明：

• 仅 PC / Mac 平台支持，移动端 / VR 调用无效。
• 配合 IsRenderAll 属性查询当前状态。

调用示例：

renderer.SetRenderAll(true);
renderer.Load(filePath, null, () => Debug.Log("Full loaded"));

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 分块元信息；无 Mesh 或不可用时返回 null
public List<LCCMeshBlockInfo> GetMeshBlockInfos()

返回全部碰撞 Mesh 分块的元信息（id、世界 / 本地包围盒、顶点数、面数）。零 I/O、零解析，只读内存中已有的 meta。字段见 LCCMeshBlockInfo。

说明：

• 仅 PC / Mac 平台 + 本地数据源；只能主线程调用。
• 典型用法：先用它拿各块世界 BBox，挑出需要的 id，再调 GetMeshes(ids) 只读那几块。
• 原生格式（PLY / SOG / SPZ / splat / ksplat）无 Mesh，返回 null（属正常情况，不打日志）。

调用示例：

var infos = renderer.GetMeshBlockInfos();
foreach (var info in infos)
{
    Debug.Log($"{info.id}: verts={info.vertexCount}, faces={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>，指定 id 的碰撞 Mesh 几何数据；无命中时返回 null
public List<LCCMeshBlock> GetMeshes(IEnumerable<string> _ids)

同步返回指定 id 的碰撞 Mesh 分块几何数据（本地坐标系）。id 由 GetMeshBlockInfos() 提供。

说明：

• 未知 id 跳过并告警；重复 id 去重（不重复读盘）；返回顺序为 ids 的遍历顺序（去重后）。
• 入参为 null、为空、或无一命中时返回 null 并告警。
• 其余约束同 GetMeshes()。

调用示例：

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