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) { /* ... */ }