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