LCCManager:核心管理器
LCC Unity SDK 的核心管理器,負責管理所有 Renderer 實例、相機、全局渲染狀態,以及編輯操作(裁切 / 高亮 / 調色)、貼花投影、吸附、交互查詢(射線 / 碰撞)等。整個場景中應僅存在一個 LCCManager 實例。
| 命名空間 | LCCCore |
| 父類 | MonoBehaviour |
LCCManager 沒有公開屬性,所有功能透過方法調用。方法按用途分為以下幾組:
初始化與配置
以下方法用於在加載數據前完成平台、渲染模式、容量等前置配置。多數方法必須在任何 Renderer.Load() 之前調用。
SetPlatformType
public void SetPlatformType(PlatformType _type)
設置 SDK 目標運行平台,影響內部渲染策略與資源分配。
| 參數 | 類型 | 說明 |
|---|---|---|
_type | PlatformType | 目標平台,取值見 PlatformType |
說明:
- 必須在任何
GetRender()調用之前執行。
調用示例:
lccManager.SetPlatformType(PlatformType.PC);
SwitchRenderPass
public void SwitchRenderPass(ActiveRenderMode _mode)
設置全局渲染架構模式。MultiRender 使用共享 GPU Buffer,可同時渲染最多 255 個 Renderer;SingleRender 由 SDK 根據數據量自動選擇渲染路徑。
| 參數 | 類型 | 說明 |
|---|---|---|
_mode | ActiveRenderMode | 渲染模式,取值見 ActiveRenderMode |
說明:
- 必須在任何
Renderer.Load()之前調用。 - 僅 PC / Mac 平台有效;移動端 / VR 平台會自動採用適配策略,調用本方法會被拒絕。
MultiRender模式不支持 HTTP 數據源,HTTP 數據請使用SingleRender。- 一旦有任意 Renderer 完成
Load(),模式即被鎖定,不能再切換。
調用示例:
lccManager.SwitchRenderPass(ActiveRenderMode.MultiRender);
GetRender(重載 1:綁定 Transform)
// 返回值:Renderer,失敗返回 null
public Renderer GetRender(Transform _transform)
創建一個新的渲染實例並綁定到指定 Transform。創建後需調用 Renderer.Load() 加載數據。
| 參數 | 類型 | 說明 |
|---|---|---|
_transform | Transform | 渲染實例掛載的 Transform |
說明:
- 需先調用
SetPlatformType()與SetMainCamera()。 MultiRender模式下最多支持 255 個 Renderer。
調用示例:
var go = new GameObject("LCCScene");
var renderer = lccManager.GetRender(go.transform);
renderer.Load(filePath, null, () => Debug.Log("Loaded"));
GetRender(重載 2:自動創建 GameObject)
// 返回值:Renderer,失敗返回 null
public Renderer GetRender(out GameObject gameObject)
自動創建名為 LCCRenderer 的 GameObject 並將渲染實例綁定到其 Transform 上。
| 參數 | 類型 | 說明 |
|---|---|---|
gameObject | out GameObject | 輸出自動創建的 GameObject,失敗時為 null |
調用示例:
var renderer = lccManager.GetRender(out GameObject go);
renderer.Load(filePath, null, () => Debug.Log("Loaded"));
SetMaxBufferSplat
public void SetMaxBufferSplat(int _count)
設置 GPU Buffer 最大容量(Splat 數量)。一次性分配,不可動態修改。
| 參數 | 類型 | 說明 |
|---|---|---|
_count | int | 最大 Splat 數量,單位:萬(傳入值 × 10000 = 實際數量) |
說明:
- 必須在任何
Renderer.Load()之前調用,且需先調用SetPlatformType()。 - 容量越大顯存佔用越高,按需設置。
- 平台上限:PC / Mac / PCVR 4500 萬,Android / iOS 600 萬,VR(Pico / Quest / PicoSwan / AVP / OpenXR)200 萬。
- 默認值:PC / Mac 3000 萬,Android / iOS 300 萬,VR 100 萬。
調用示例:
lccManager.SetMaxBufferSplat(3000); // 3000 萬點
SetFullRenderSplat
public void SetFullRenderSplat(int _count)
設置 PC / Mac 全量渲染的上限閾值。當數據量小於此值時走全量渲染路徑,否則走分塊渲染路徑。
| 參數 | 類型 | 說明 |
|---|---|---|
_count | int | 全量渲染上限,單位:萬,取值範圍 [100, 4500] |
說明:
- 僅 PC / Mac / PCVR 平台支持。
- 必須在任何
Renderer.Load()之前調用,且需先調用SetPlatformType()。
調用示例:
lccManager.SetFullRenderSplat(2500); // 2500 萬點
SetMaxRenderSplats
public void SetMaxRenderSplats(int _count)
設置運行時每幀最大渲染 Splat 數量。可在 Load() 之後動態調用。
| 參數 | 類型 | 說明 |
|---|---|---|
_count | int | 運行時最大渲染 Splat 數量,單位:萬 |
說明:
- 可在運行時動態調整。
- 不能超過
SetMaxBufferSplat()設置的容量上限,超出會自動鉗制。 - 全量渲染模式下調用無效。
調用示例:
lccManager.SetMaxRenderSplats(2500); // 2500 萬點
GetLoadRatio
// 返回值:float,[0,1] 當前數據加載進度
public float GetLoadRatio()
查詢當前畫面數據的加載進度。
說明:
- 全量渲染模式下恆返回
1.0。 - 分塊渲染模式下返回當前視角下已加載完成節點的比例,數值隨相機移動實時變化,並非單調遞增的總體進度。
調用示例:
float ratio = lccManager.GetLoadRatio();
progressBar.value = ratio;
SetSelectionMode
public void SetSelectionMode(SelectionMode mode)
設置節點篩選策略。
| 參數 | 類型 | 說明 |
|---|---|---|
mode | SelectionMode | 篩選策略,取值見 SelectionMode |
說明:
Auto(默認):根據場景整體包圍盒自動決策,當場景最大維度超過約 380 米時自動升級到Large。Normal:適用於中小場景。Large:適用於超大場景(1000 米以上)。- 切換模式立即生效。
調用示例:
lccManager.SetSelectionMode(SelectionMode.Auto);
運行時渲染控制
以下方法可在運行時動態調用,用於調整渲染精度、顯示效果與渲染開關。
SetDetailLevel
public void SetDetailLevel(float sse)
設置渲染精度等級。值越大渲染越精細、性能消耗越高。
| 參數 | 類型 | 說明 |
|---|---|---|
sse | float | 精度等級,範圍 [1, 100],超出自動鉗制 |
說明:
- 採用對數映射:低值區間變化敏感,高值區間變化平緩。
- 運行時可動態調整。
- 僅在
Normal篩選模式下生效。
調用示例:
lccManager.SetDetailLevel(50f); // 中等精度
SetStartLod
public void SetStartLod(int lod)
設置 LOD 展開起點(0-based)。0 表示最精細,數字越大層級越粗。
| 參數 | 類型 | 說明 |
|---|---|---|
lod | int | LOD 起始層級,範圍 [0, 10],超出自動鉗制 |
說明:
- 實際生效上限受數據總層級數限制。
調用示例:
lccManager.SetStartLod(0);
SetAutoFov
public void SetAutoFov(bool _auto)
設置是否自動管理渲染 FOV。開啟(默認)後 SDK 在首幀鎖定一個像素焦距基準,此後每幀按當前視口高度反解垂直 FOV 並寫回 Camera.fieldOfView;關閉後 fieldOfView 交由外部(SetFOV() 或直接改相機)掌握。
| 參數 | 類型 | 說明 |
|---|---|---|
_auto | bool | 是否自動 FOV |
說明:
- 默認開啟。
- 開啟時會持續改寫主相機
Camera.fieldOfView,此時調用SetFOV()會被忽略。 - 關閉後需手動調用
SetFOV()設置參數。
調用示例:
lccManager.SetAutoFov(true);
SetFOV
public void SetFOV(int _width, int _height, float _verticalFov, float _aspect)
手動設置垂直 FOV(度)。直接改寫主相機的 Camera.fieldOfView,使 Inspector 中的 FOV 與渲染實際使用的 FOV 一致。_width / _height / _aspect 為歷史簽名保留參數,實際投影以主相機自身視口為準(需要異於相機的尺寸 / FOV 離屏出圖請用 SetRecordMode())。
| 參數 | 類型 | 說明 |
|---|---|---|
_width | int | 像素寬度 |
_height | int | 像素高度 |
_verticalFov | float | 垂直 FOV(度) |
_aspect | float | 寬高比 |
說明:
- 需先調用
SetAutoFov(false),否則自動 FOV 每幀反解會覆蓋手動值。 - 垂直 FOV 鉗制到
[1, 179]度。 - VR / PCVR 平台、錄製中、正交相機下調用會被拒絕(告警並返回)。
調用示例:
lccManager.SetFOV(1920, 1080, 60f, 1.778f);
SetRenderEnable
public void SetRenderEnable(Renderer _renderer, bool _isEnable)
在運行時控制指定 Renderer 的渲染開關。禁用後不參與遍歷和繪製。
| 參數 | 類型 | 說明 |
|---|---|---|
_renderer | Renderer | 目標渲染實例 |
_isEnable | bool | 是否啟用渲染 |
調用示例:
lccManager.SetRenderEnable(renderer, false); // 隱藏
SetEnvironment
public void SetEnvironment(Renderer _renderer, bool _isRender)
控制指定 Renderer 的環境數據渲染。環境數據為低精度背景點雲,用於填充遠景。
| 參數 | 類型 | 說明 |
|---|---|---|
_renderer | Renderer | 目標渲染實例 |
_isRender | bool | 是否渲染環境數據 |
說明:
- 數據需包含環境節點。
調用示例:
lccManager.SetEnvironment(renderer, true);
SetZDepth
public void SetZDepth(bool zwrite)
開關 Z 深度寫入,同時調整渲染隊列。
| 參數 | 類型 | 說明 |
|---|---|---|
zwrite | bool | 是否開啟 Z 深度寫入 |
調用示例:
lccManager.SetZDepth(true);
SetAlpha
public void SetAlpha(float alpha)
設置全局透明度。
| 參數 | 類型 | 說明 |
|---|---|---|
alpha | float | 全局透明度,範圍 [0, 1],超出自動鉗制 |
調用示例:
lccManager.SetAlpha(0.8f);
SetLightIntensity
public void SetLightIntensity(float intensity)
設置全局光照強度。
| 參數 | 類型 | 說明 |
|---|---|---|
intensity | float | 光照強度,範圍 [0, 1],超出自動鉗制 |
調用示例:
lccManager.SetLightIntensity(0.7f);
SetLowPassFilter
public void SetLowPassFilter(float _filter)
設置全局低通濾波強度,用於抑制高頻鋸齒 / 噪點。
| 參數 | 類型 | 說明 |
|---|---|---|
_filter | float | 低通濾波強度,範圍 [0, 1],超出自動鉗制 |
調用示例:
lccManager.SetLowPassFilter(0.3f);
SetLockFPS
public void SetLockFPS(bool _isLock)
開關幀率鎖定(靜態 / 動態幀率切換)。
| 參數 | 類型 | 說明 |
|---|---|---|
_isLock | bool | 是否鎖定幀率 |
調用示例:
lccManager.SetLockFPS(true);
SetRenderLayer
public void SetRenderLayer(int _layer)
設置 LCC 渲染使用的 Unity Layer,用於相機 CullingMask 控制可見性。
| 參數 | 類型 | 說明 |
|---|---|---|
_layer | int | Unity 渲染層級,範圍 [0, 31] |
說明:
- 運行時可動態調整。
調用示例:
lccManager.SetRenderLayer(8); // 使用 Layer 8
SetForceRefresh
public void SetForceRefresh()
強制刷新渲染。清除內部相機信息緩存,使下一幀重新計算視錐、LOD 等參數。適用於外部修改相機參數後需要立即生效的場景。
調用示例:
lccManager.SetForceRefresh();
SetMipMode
public void SetMipMode(MipMode _mipMode)
切換 Mip 渲染模式。Mip 模式使用 mipmap 採樣(默認),Non_Mip 模式禁用 mipmap。
| 參數 | 類型 | 說明 |
|---|---|---|
_mipMode | MipMode | 目標模式,取值見 MipMode |
說明:
- 若當前模式與傳入模式相同則直接返回。
- 切換立即生效。
調用示例:
lccManager.SetMipMode(MipMode.Non_Mip);
SetGraphicsAPI
public void SetGraphicsAPI(GraphicsDeviceType type)
設置圖形 API 類型。DX11 模式下啟用 HDR。
| 參數 | 類型 | 說明 |
|---|---|---|
type | GraphicsDeviceType | 圖形 API 類型(Unity 內置枚舉) |
調用示例:
lccManager.SetGraphicsAPI(GraphicsDeviceType.Direct3D11);
SetDebugMode
public void SetDebugMode(bool debug)
開關調試模式。
| 參數 | 類型 | 說明 |
|---|---|---|
debug | bool | 是否開啟調試模式 |
說明:
- 僅 PC / Mac 平台支持。
調用示例:
lccManager.SetDebugMode(true);
SetEditorMode
public void SetEditorMode(bool _isEditor)
開關編輯器模式。
| 參數 | 類型 | 說明 |
|---|---|---|
_isEditor | bool | 是否開啟編輯器模式 |
說明:
- 僅 PC / Mac 平台支持。
調用示例:
lccManager.SetEditorMode(true);
SetAECMode
public void SetAECMode(bool _aec)
開關 AEC(建築 / 工程 / 施工)模式。
| 參數 | 類型 | 說明 |
|---|---|---|
_aec | bool | 是否開啟 AEC 模式 |
說明:
- 僅 PC / Mac 平台支持。
調用示例:
lccManager.SetAECMode(true);
SetSemantic
// 返回值:bool,false=參數無效
public bool SetSemantic(bool enable, Vector4[] color = null)
開關語義渲染模式。啟用時可傳入顏色數組定義各語義類別的顯示顏色。
| 參數 | 類型 | 說明 |
|---|---|---|
enable | bool | 是否啟用語義渲染 |
color | Vector4[] | 語義顏色數組,長度必須為 100,否則返回 false;傳 null 使用默認顏色 |
調用示例:
Vector4[] colors = new Vector4[100];
colors[0] = new Vector4(1, 0, 0, 1); // 類別 0 = 紅色
lccManager.SetSemantic(true, colors);
SwitchRenderMode
public void SwitchRenderMode(RenderMode mode, Texture2D tex = null)
切換點雲渲染與 3DGS 渲染模式。點雲模式下可提供高程色帶紋理。
| 參數 | 類型 | 說明 |
|---|---|---|
mode | RenderMode | 渲染模式,取值見 RenderMode |
tex | Texture2D | 高程色帶圖(可選) |
說明:
- 僅 PC / Mac 平台支持。
調用示例:
lccManager.SwitchRenderMode(RenderMode.PointCloud, elevationTex);
SetRecordMode
public void SetRecordMode(bool isRecord, Vector2 renderSize, float verticalFov)
設置錄製模式。錄製模式下使用固定分辨率和 FOV 渲染,適用於高清視頻錄製。
| 參數 | 類型 | 說明 |
|---|---|---|
isRecord | bool | 是否錄製模式 |
renderSize | Vector2 | 錄製分辨率 |
verticalFov | float | 垂直 FOV(度) |
說明:
- 僅 PC / Mac 平台支持。
- 錄製模式下相機焦距固定,不隨 Camera 組件變化。
- 結束錄製後調用
SetRecordMode(false, ...)恢復。
調用示例:
lccManager.SetRecordMode(true, new Vector2(3840, 2160), 60f);
SetVRPerformance
public void SetVRPerformance(bool _enabled)
設置 VR 高性能排序模式。true 使用 GPU 基數排序(GpuSorter),false 回退到 CPU / BitonicSorter 兜底。
| 參數 | 類型 | 說明 |
|---|---|---|
_enabled | bool | 是否啟用 GPU 高性能排序 |
說明:
- 僅對 VR 頭顯(Pico / Quest / PicoSwan / OpenXR)的排序路徑生效,默認開啟。
- 無 compute 設備(如 Mali)時由排序上游自動回退到 CPU,不受此開關影響。
調用示例:
lccManager.SetVRPerformance(true);
光照與陰影
以下方法用於控制 3DGS 表面的陰影接收與自定義點光源。陰影相關方法需在 LCC 場景加載完成後調用。
SetShadowReceive
public void SetShadowReceive(bool enable)
開關點雲陰影接收功能。開啟後場景中 Mesh 物體的陰影可以投射到 3DGS 點雲表面上。
| 參數 | 類型 | 說明 |
|---|---|---|
enable | bool | 是否接收陰影 |
說明:
- 默認關閉。
- 需要場景中有投射陰影的 Mesh 物體和 Directional Light 光源。
調用示例:
lccManager.SetShadowReceive(true);
SetShadowColor
public void SetShadowColor(Color color)
設置陰影區域的顏色。
| 參數 | 類型 | 說明 |
|---|---|---|
color | Color | 陰影顏色(RGBA) |
說明:
- 默認值
(0.3, 0.3, 0.3, 1)。 - 需先開啟
SetShadowReceive(true)。
調用示例:
lccManager.SetShadowColor(new Color(0.3f, 0.3f, 0.3f, 1f));
SetShadowStrength
public void SetShadowStrength(float strength)
設置陰影強度。0 為無陰影,1 為最強陰影。
| 參數 | 類型 | 說明 |
|---|---|---|
strength | float | 陰影強度,範圍 [0, 1],超出自動鉗制 |
說明:
- 默認值
1.0。 - 需先開啟
SetShadowReceive(true)。
調用示例:
lccManager.SetShadowStrength(0.8f);
SetLights
// 返回值:int,0=成功,-1=超出最大數量限制
public int SetLights(List<PointLightData> lights)
設置自定義點光源列表。傳入 null 或空列表可關閉自定義光照。
| 參數 | 類型 | 說明 |
|---|---|---|
lights | List<PointLightData> | 點光源列表,字段見 PointLightData |
說明:
PointLightData.lightType:0為點光源(忽略 direction / spotAngle),1為聚光燈(需設置 direction / spotAngle)。- 傳入
null或空列表關閉自定義光照。
調用示例:
using Unity.Mathematics; // float3
var lights = new List<PointLightData>();
lights.Add(new PointLightData {
position = new float3(0, 5, 0),
lightType = 0, // 0=點光源, 1=聚光燈
color = new float3(1, 1, 1),
intensity = 2f,
range = 10f
});
lccManager.SetLights(lights);
相機管理
SetMainCamera
public void SetMainCamera(Camera _cam)
設置主渲染相機。LCC 使用此相機進行視錐裁剪、LOD 選擇、排序等操作。
| 參數 | 類型 | 說明 |
|---|---|---|
_cam | Camera | 主渲染相機,傳 null 可清除 |
說明:
- 必須在
Renderer.Load()之前設置。 - 僅 PC / Mac 平台支持。
調用示例:
lccManager.SetMainCamera(Camera.main);
AddCamera
public void AddCamera(Camera _cam)
添加一個副相機。副相機參與渲染但不影響 LOD 選擇。
| 參數 | 類型 | 說明 |
|---|---|---|
_cam | Camera | 副相機 |
說明:
- 僅 PC / Mac 平台支持。
- 不能將主相機添加為副相機。
調用示例:
lccManager.AddCamera(secondCamera);
RemoveCamera
public void RemoveCamera(Camera _cam)
移除一個已添加的副相機。
| 參數 | 類型 | 說明 |
|---|---|---|
_cam | Camera | 要移除的副相機 |
說明:
- 僅 PC / Mac 平台支持。
調用示例:
lccManager.RemoveCamera(secondCamera);
裁切 / 高亮 / 調色
裁切、高亮、調色三類編輯操作,均支持透過 2D 紋理、3D 幾何體或兩者混合定義作用區域。相關數據結構見 Data2D、Data3D、DataMix、ToneMix。
SetClip(平面裁切)
// 返回值:int,0=成功
public int SetClip(Vector3 planePoint, Vector3 planeNormal, bool inside = true)
使用無限平面裁切點雲,保留法線方向一側或反側的點。
| 參數 | 類型 | 說明 |
|---|---|---|
planePoint | Vector3 | 平面上一點 |
planeNormal | Vector3 | 平面法線 |
inside | bool | true 保留法線方向側 |
說明:
- 與其他裁切模式互斥。
調用示例:
lccManager.SetClip(Vector3.zero, Vector3.up, true); // 保留地面以上
SetClip(2D 紋理裁切)
// 返回值:int,0=成功,1=列表為空,2=超出最大數量
public int SetClip(List<Data2D> _2Ds)
使用 2D 投影紋理蒙版裁切點雲。
| 參數 | 類型 | 說明 |
|---|---|---|
_2Ds | List<Data2D> | 2D 紋理選區列表 |
調用示例:
var clips = new List<Data2D>();
clips.Add(new Data2D {
texture = maskTex,
mv = modelViewMatrix,
mvp = mvpMatrix,
mode = SelectMode.normal
});
lccManager.SetClip(clips);
SetClip(3D 幾何體裁切)
// 返回值:int,0=成功,1=列表為空,2=超出最大數量,3=有效幾何體為 0
public int SetClip(List<Data3D> _3Ds)
使用 3D 幾何體裁切點雲,支持布爾運算組合多個幾何體。
| 參數 | 類型 | 說明 |
|---|---|---|
_3Ds | List<Data3D> | 3D 幾何體列表 |
說明:
- 至少需要一個
operation == normal的幾何體。
調用示例:
var clips = new List<Data3D>();
clips.Add(new Data3D {
type = ShapeType.box,
invMat = boxInverseMatrix,
operation = OperationMode.normal,
mode = SelectMode.normal
});
lccManager.SetClip(clips);
SetClip(混合模式裁切)
// 返回值:int,0=成功,1=列表為空,2=超出最大數量
public int SetClip(List<DataMix> mix)
同時使用 2D 紋理和 3D 幾何體混合定義裁切區域。每個條目透過 editType 指定類型。
| 參數 | 類型 | 說明 |
|---|---|---|
mix | List<DataMix> | 混合選區列表(2D + 3D) |
調用示例:
var mix = new List<DataMix>();
mix.Add(new DataMix {
editType = EditType.Edit3D,
type = ShapeType.box,
invMat = matrix,
operation = OperationMode.normal,
mode = SelectMode.normal
});
lccManager.SetClip(mix);
QuitClipMode
public void QuitClipMode()
退出裁切模式,恢復完整點雲顯示。
調用示例:
lccManager.QuitClipMode();
SetHighlight(2D 紋理高亮)
// 返回值:int,0=成功,1=列表為空,2=超出最大數量
public int SetHighlight(List<Data2D> _2Ds)
使用 2D 投影紋理蒙版對點雲進行高亮顯示,高亮區域外的點雲變暗。
| 參數 | 類型 | 說明 |
|---|---|---|
_2Ds | List<Data2D> | 2D 紋理選區列表 |
說明:
- 與 3D 高亮和混合高亮互斥。
調用示例:
var highlights = new List<Data2D>();
highlights.Add(new Data2D {
texture = maskTex,
mv = modelViewMatrix,
mvp = mvpMatrix,
mode = SelectMode.normal
});
lccManager.SetHighlight(highlights);
SetHighlight(3D 幾何體高亮)
// 返回值:int,0=成功,1=列表為空,2=超出最大數量,3=有效幾何體為 0
public int SetHighlight(List<Data3D> _3Ds)
使用 3D 幾何體定義高亮區域,支持布爾運算組合。
| 參數 | 類型 | 說明 |
|---|---|---|
_3Ds | List<Data3D> | 3D 幾何體列表 |
說明:
- 至少需要一個
operation == normal的幾何體。
調用示例:
var highlights = new List<Data3D>();
highlights.Add(new Data3D {
type = ShapeType.box,
invMat = boxInverseMatrix,
operation = OperationMode.normal,
mode = SelectMode.normal
});
lccManager.SetHighlight(highlights);
SetHighlight(混合模式高亮)
// 返回值:int,0=成功,1=列表為空,2=超出最大數量
public int SetHighlight(List<DataMix> mix)
同時使用 2D 紋理和 3D 幾何體混合定義高亮區域。
| 參數 | 類型 | 說明 |
|---|---|---|
mix | List<DataMix> | 混合選區列表 |
調用示例:
var mix = new List<DataMix>();
mix.Add(new DataMix {
editType = EditType.Edit3D,
type = ShapeType.box,
invMat = matrix,
operation = OperationMode.normal,
mode = SelectMode.normal
});
lccManager.SetHighlight(mix);
QuitHighlightMode
public void QuitHighlightMode()
退出高亮模式,恢復點雲正常顯示。
調用示例:
lccManager.QuitHighlightMode();
SetTone
// 返回值:int,0=成功,1=列表為空,2=超出最大數量
public int SetTone(List<ToneMix> mix)
對選定區域進行調色處理,支持亮度、飽和度、對比度調整和 LUT 濾鏡。可透過 2D 紋理或 3D 幾何體定義調色區域。
| 參數 | 類型 | 說明 |
|---|---|---|
mix | List<ToneMix> | 調色混合列表 |
說明:
brightness/saturation/contrast默認值為1.0。lutid為 LUT 濾鏡索引,0表示不使用。
調用示例:
var tones = new List<ToneMix>();
tones.Add(new ToneMix {
editType = EditType.Edit3D,
type = ShapeType.box,
invMat = boxMatrix,
operation = OperationMode.normal,
mode = SelectMode.normal,
brightness = 1.2f,
saturation = 1.0f,
contrast = 1.1f,
lutid = 0
});
lccManager.SetTone(tones);
QuitToneMode
public void QuitToneMode()
退出調色模式,恢復點雲原始色彩。
調用示例:
lccManager.QuitToneMode();
貼花投影
貼花投影可將一張紋理沿投影儀方向投射到 3DGS 表面。貼花是世界固定的全局狀態,對所有相機一致。典型流程為:開啟貼花 → 設置紋理 → 設置投影儀位姿。以下方法僅 PC / Mac 平台支持。
SetDecalEnabled
public void SetDecalEnabled(bool enable)
開關貼花投影。需另外調用 SetDecalTexture() 與 SetDecalProjection() 設置內容與投影儀位姿。
| 參數 | 類型 | 說明 |
|---|---|---|
enable | bool | 是否開啟貼花投影 |
說明:
- 關閉時不會清空已緩存的紋理 / 參數。
調用示例:
lccManager.SetDecalEnabled(true);
lccManager.SetDecalTexture(decalTex);
lccManager.SetDecalProjection(projectorPos, projectorRot, 60f, 1.778f, 0.1f, 20f);
SetDecalTexture
public void SetDecalTexture(Texture2D tex)
設置貼花紋理。RGB 為顏色,A 為貼花自身遮罩,會與全局不透明度、邊緣羽化相乘。
| 參數 | 類型 | 說明 |
|---|---|---|
tex | Texture2D | 貼花紋理,傳 null 會清空引用 |
調用示例:
lccManager.SetDecalTexture(logoTex);
SetDecalProjection
public void SetDecalProjection(Vector3 pos, Quaternion rot, float fov, float aspect, float near, float far)
設置貼花投影儀的位姿與透視參數。投影儀沿其 forward(+Z)方向投影,視錐內的點被貼花覆蓋。
| 參數 | 類型 | 說明 |
|---|---|---|
pos | Vector3 | 投影儀世界座標 |
rot | Quaternion | 投影儀朝向 |
fov | float | 垂直 FOV(度),鉗制 [1, 179] |
aspect | float | 寬高比,最小 1e-4 |
near | float | 近裁剪面,最小 1e-3 |
far | float | 遠裁剪面,最小 near + 1e-3 |
調用示例:
lccManager.SetDecalProjection(new Vector3(0, 10, 0), Quaternion.Euler(90, 0, 0), 60f, 1.778f, 0.1f, 20f);
SetDecalOpacity
public void SetDecalOpacity(float opacity)
設置貼花整體不透明度。
| 參數 | 類型 | 說明 |
|---|---|---|
opacity | float | 貼花整體不透明度,範圍 [0, 1],超出自動鉗制 |
調用示例:
lccManager.SetDecalOpacity(0.8f);
SetDecalEdgeFade
public void SetDecalEdgeFade(float edgeFade)
設置貼花邊緣羽化寬度。0 為硬邊,值越大邊緣過渡越柔和。
| 參數 | 類型 | 說明 |
|---|---|---|
edgeFade | float | 邊緣羽化寬度(UV 空間比例),範圍 [0, 0.5),超出自動鉗制 |
調用示例:
lccManager.SetDecalEdgeFade(0.1f);
SetDecalOcclusion
public void SetDecalOcclusion(bool enable)
開關貼花遮擋剔除(基於投影儀深度圖),開啟後被遮擋的表面不會被貼花覆蓋。
| 參數 | 類型 | 說明 |
|---|---|---|
enable | bool | 是否開啟貼花遮擋剔除 |
說明:
- 僅 PC / Mac 平台,且僅 URP 管線支持。
- 開啟前應已調用
SetDecalProjection()設定投影儀。 - 依賴
SetDecalOcclusionSettings()配置的質量參數。
調用示例:
lccManager.SetDecalOcclusion(true);
SetDecalOcclusionSettings
public void SetDecalOcclusionSettings(DecalOcclusionSettings settings)
一次性設置貼花遮擋剔除的全部質量參數。字段含義見 DecalOcclusionSettings。
| 參數 | 類型 | 說明 |
|---|---|---|
settings | DecalOcclusionSettings | 遮擋剔除質量參數 |
說明:
- 隨時可調,參數立即生效。
調用示例:
lccManager.SetDecalOcclusionSettings(DecalOcclusionSettings.Default);
lccManager.SetDecalOcclusionSettings(new DecalOcclusionSettings {
opacityCutoff = 0.1f,
depthBias = 0.05f,
footprintMaxPx = 2,
resolution = 1024
});
吸附
吸附功能可在射線檢測時自動搜索附近的邊緣 / 角點進行對齊,常用於測量、標註等精確交互。以下方法僅 PC / Mac 平台支持。
SetSnapEnabled
public void SetSnapEnabled(bool enable)
開關吸附功能。啟用後 RaycastWithSnap() 會自動搜索附近的邊緣 / 角點進行吸附。
| 參數 | 類型 | 說明 |
|---|---|---|
enable | bool | 是否啟用吸附 |
說明:
- 默認關閉。
- 移動端 / VR 調用無效並輸出警告。
調用示例:
lccManager.SetSnapEnabled(true);
SetSnapRadius
public void SetSnapRadius(float pixels)
設置吸附搜索半徑。在此像素範圍內搜索最近的邊緣 / 角點。
| 參數 | 類型 | 說明 |
|---|---|---|
pixels | float | 吸附搜索半徑(像素) |
說明:
- 默認 20 像素。
- 值越大搜索範圍越廣,但可能吸附到非預期目標。
調用示例:
lccManager.SetSnapRadius(30f);
SetEdgeThreshold
public void SetEdgeThreshold(float threshold)
設置邊緣檢測閾值。值越小檢測到的邊緣越多。
| 參數 | 類型 | 說明 |
|---|---|---|
threshold | float | 邊緣檢測閾值,建議範圍 [0.1, 0.8] |
說明:
- 默認
0.3。 - 值過小會產生大量噪聲邊緣。
調用示例:
lccManager.SetEdgeThreshold(0.2f);
SetSnapPreviewEnabled
public void SetSnapPreviewEnabled(bool enable)
開關吸附預覽功能。啟用後鼠標移動時實時顯示最近的吸附目標指示器。
| 參數 | 類型 | 說明 |
|---|---|---|
enable | bool | 是否啟用吸附預覽 |
說明:
- 需先調用
SetSnapEnabled(true)。 - 預覽會持續消耗 GPU 資源(每幀檢測)。
調用示例:
lccManager.SetSnapPreviewEnabled(true);
UpdateSnapPreview
public void UpdateSnapPreview(Vector2 mousePos, Camera cam)
更新吸附預覽狀態。在鼠標移動時調用,更新預覽指示器位置。
| 參數 | 類型 | 說明 |
|---|---|---|
mousePos | Vector2 | 當前鼠標屏幕座標 |
cam | Camera | 相機 |
說明:
- 需先調用
SetSnapPreviewEnabled(true)。 - 建議在
Update中持續調用。
調用示例:
void Update()
{
lccManager.UpdateSnapPreview(Input.mousePosition, Camera.main);
}
GetSnapPreviewState
// 返回值:SnapPreviewState
public SnapPreviewState GetSnapPreviewState()
獲取當前吸附預覽狀態,包括是否有吸附目標、目標類型、目標屏幕位置和到鼠標的像素距離。字段見 SnapPreviewState。
說明:
- 需先調用
SetSnapPreviewEnabled(true)和UpdateSnapPreview()。 - 無目標時返回
default(SnapPreviewState)。 screenPos是屏幕座標,不是世界座標;要拿世界座標請用RaycastWithSnap()取HitResult.hitPos。
調用示例:
var state = lccManager.GetSnapPreviewState();
if (state.hasTarget)
{
// state.snapType: Corner / Edge
// state.screenPos: 吸附目標屏幕座標
// state.distanceToMouse: 像素距離
}
射線檢測與碰撞查詢
射線檢測用於拾取 3DGS 表面上的點,碰撞查詢用於角色 / 物體與點雲的物理交互。命中結果透過 HitResult 返回。
注意:
HitResult的命中點世界座標字段名為hitPos(不是position)。
Raycast(屏幕座標)
// 返回值:bool,true=命中
public bool Raycast(Vector3 mousePos, out HitResult _finalResult)
從屏幕座標發射射線檢測點雲命中。使用 SetMainCamera() 設置的主相機生成射線。
| 參數 | 類型 | 說明 |
|---|---|---|
mousePos | Vector3 | 屏幕座標 |
_finalResult | out HitResult | 命中結果 |
說明:
- 需先調用
SetMainCamera()設置主相機。 - 返回距離相機最近的命中點。
- 精度受
SetRaycastDelta()影響,最大距離由SetMaxRaycastDistance()控制。
調用示例:
if (lccManager.Raycast(Input.mousePosition, out HitResult hit))
{
Debug.Log(hit.hitPos);
}
Raycast(Ray)
// 返回值:bool,true=命中
public bool Raycast(Ray _ray, out HitResult _finalResult)
使用自定義 Ray 進行射線檢測,遍歷所有激活的 Renderer 返回最近命中。
| 參數 | 類型 | 說明 |
|---|---|---|
_ray | Ray | 射線 |
_finalResult | out HitResult | 命中結果 |
調用示例:
Ray ray = new Ray(origin, direction);
if (lccManager.Raycast(ray, out HitResult hit))
{
Debug.Log(hit.hitPos);
}
RaycastMesh(屏幕座標)
// 返回值:bool,true=命中
public bool RaycastMesh(Vector3 mousePos, out HitResult _finalResult, float _distance = 70.0f)
從屏幕座標發射射線檢測點雲碰撞網格。使用 Collider 數據進行檢測,比 Raycast() 更快但精度較低。
| 參數 | 類型 | 說明 |
|---|---|---|
mousePos | Vector3 | 屏幕座標 |
_finalResult | out HitResult | 命中結果 |
_distance | float | 最大檢測距離,默認 70.0 |
說明:
- 需要數據包含 Collider 節點,且需先調用
Renderer.SetColliderEnable(true)。
調用示例:
if (lccManager.RaycastMesh(Input.mousePosition, out HitResult hit))
{
Debug.Log(hit.hitPos);
}
RaycastMesh(Ray + Bounds)
// 返回值:bool,true=命中
public bool RaycastMesh(Ray ray, out HitResult result, out Bounds hitBounds, float maxDist = 70.0f)
使用自定義 Ray 進行碰撞網格檢測,同時返回命中節點的包圍盒信息。
| 參數 | 類型 | 說明 |
|---|---|---|
ray | Ray | 射線 |
result | out HitResult | 命中結果 |
hitBounds | out Bounds | 命中節點的包圍盒 |
maxDist | float | 最大檢測距離,默認 70.0 |
說明:
- 需要數據包含 Collider 節點。
調用示例:
Ray ray = Camera.main.ScreenPointToRay(Input.mousePosition);
if (lccManager.RaycastMesh(ray, out HitResult hit, out Bounds bounds))
{
Debug.Log(bounds.center);
}
RaycastWithSnap
// 返回值:bool,true=命中
public bool RaycastWithSnap(Vector2 screenPos, Camera cam, out HitResult result)
帶吸附功能的射線檢測。先進行普通射線檢測,再在命中點附近搜索邊緣 / 角點進行吸附。
| 參數 | 類型 | 說明 |
|---|---|---|
screenPos | Vector2 | 屏幕座標 |
cam | Camera | 相機 |
result | out HitResult | 命中結果(含吸附信息) |
說明:
- 需先調用
SetSnapEnabled(true)。 - 僅 PC / Mac 平台支持,移動端 / VR 不可用。
- 吸附優先級:Corner > Edge > None。
HitResult.snapType為吸附類型,HitResult.hitPos為吸附後的世界座標,HitResult.originalHitPos為吸附前的原始命中點。
調用示例:
if (lccManager.RaycastWithSnap(mousePos, cam, out HitResult hit))
{
// hit.snapType: Corner / Edge / None
// hit.hitPos: 吸附後的世界座標
// hit.originalHitPos: 吸附前的原始命中點
}
SetRaycastDelta
public void SetRaycastDelta(float delta)
設置射線檢測的精度參數。值越小精度越高但性能消耗越大。
| 參數 | 類型 | 說明 |
|---|---|---|
delta | float | 射線檢測精度,範圍 [0.1, 10.0],超出自動鉗制 |
說明:
- 默認值
0.1。 - 影響所有
Raycast()方法的檢測精度。
調用示例:
lccManager.SetRaycastDelta(0.5f);
SetMaxRaycastDistance
public void SetMaxRaycastDistance(float _distance)
設置 Raycast() 方法的最大檢測距離。
| 參數 | 類型 | 說明 |
|---|---|---|
_distance | float | 最大射線檢測距離,範圍 [10, 10000],超出自動鉗制 |
說明:
- 影響
Raycast(Vector3)/Raycast(Ray)兩個重載;不影響RaycastMesh()(其有獨立的距離入參)。
調用示例:
lccManager.SetMaxRaycastDistance(500f);
IntersectsSphere
// 返回值:bool,true=相交
public bool IntersectsSphere(Sphere sphere)
// 返回值:bool,true=相交
public bool IntersectsSphere(Sphere sphere, out Vector3 delta)
檢測球體與點雲碰撞體是否相交。第二個重載額外返回穿透向量,可用於物理推出。
| 參數 | 類型 | 說明 |
|---|---|---|
sphere | Sphere | 球體 |
delta | out Vector3 | 穿透向量(推出方向和距離) |
說明:
- 需要數據包含 Collider 節點,且需先調用
Renderer.SetColliderEnable(true)。 - 遍歷所有激活的 Renderer。
調用示例:
var sphere = new Sphere(transform.position, 0.5f);
if (lccManager.IntersectsSphere(sphere, out Vector3 delta))
{
transform.position += delta;
}
IntersectsCapsule
// 返回值:bool,true=相交
public bool IntersectsCapsule(Capsule capsule)
// 返回值:bool,true=相交
public bool IntersectsCapsule(Capsule capsule, out Vector3 delta)
檢測膠囊體與點雲碰撞體是否相交,常用於角色控制器碰撞檢測。第二個重載返回穿透向量。
| 參數 | 類型 | 說明 |
|---|---|---|
capsule | Capsule | 膠囊體 |
delta | out Vector3 | 穿透向量 |
說明:
- 需要數據包含 Collider 節點,且需先調用
Renderer.SetColliderEnable(true)。
調用示例:
var capsule = new Capsule(footPos, headPos, 0.3f);
if (lccManager.IntersectsCapsule(capsule, out Vector3 delta))
{
characterController.Move(delta);
}
特效
TriggerVFX
public void TriggerVFX(Vector3 vfxOriginW, int vfxid = 0)
在指定世界座標觸發特效,特效從該座標點向外擴展蔓延。
| 參數 | 類型 | 說明 |
|---|---|---|
vfxOriginW | Vector3 | 特效的世界座標原點 |
vfxid | int | 特效效果 ID,默認 0 |
說明:
- 需在 LCC 場景加載完成後調用。
調用示例:
lccManager.TriggerVFX(hitPoint, 0);
實例查詢
GetAllRenderers
// 返回值:List<Renderer>,所有已註冊的 Renderer 實例副本
public List<Renderer> GetAllRenderers()
獲取當前所有已註冊的 Renderer 實例列表(返回副本)。
調用示例:
var renderers = lccManager.GetAllRenderers();
foreach (var r in renderers) { /* ... */ }