ULCC2Component：LCC2 管线组件

LCC2 管线专属 Component，继承 ULCCComponentBase。额外提供球谐阶数控制、光照法线系统和深度阈值控制。


模块	`LCC4UnrealRuntime`
头文件	`LCC2Component.h`
父类	`ULCCComponentBase`
由谁持有	`ALCC2Actor`、`ASogActor`、`ASpzActor`、`APlyActor`

#include "LCC2Component.h"

获取实例：

ULCC2Component* Comp = Cast<ULCC2Component>(LCC2Actor->GetLCCComponent());

这个组件同时服务四种数据格式：LCC2 目录、.sog、.spz、.ply。后三种通过构造虚拟元信息复用同一套渲染管线，所以拿到的都是 ULCC2Component。

注：基类上的多视口接口（SetPlayerLoadMode、SetPlayerRenderMode、SetSceneCaptureLoadMode、SetSceneCaptureRenderMode、ModifyPlayerTransform、CancelModifyPlayerTransform）在 LCC2 管线上不适用，调用不报错但达不到预期效果。详见 ULCCComponent。

Properties

属性	类型	默认	范围	说明
`SHBands`	`int32`	3	1~3	球谐阶数。默认取数据里存的阶数，也是上限
`LightingScale`	`float`	0.0	0~1	场景光照介入前的 3DGS 原始颜色亮度
`AlphaThreshold`	`float`	0.5	0.01~0.99	中值深度判定的累积不透明度阈值，高级项
`NormalMode`	`ELCC2NormalGenerationMode`	`Fixed`	—	法线生成模式，决定 3DGS 如何响应场景光
`FixedNormal`	`FVector`	(0, 0, 1)	—	`Fixed` 模式下整片 3DGS 共用的世界法线
`NormalPole`	`FVector`	(1, 0, 1)	—	`Hemispherical` 模式下的表面朝向
`NormalHemiSpread`	`float`	0.5	0~4	`Hemispherical` 模式下的明暗变化强度

法线相关属性带 EditConditionHides，细节面板上只显示当前 NormalMode 用得到的那几项。

另外两点与基类不同：

MetaInfo（类型 FLCC2MetaInfo）是私有成员，C++ 侧外部访问不到，只对蓝图可见（细节面板只读）。C++ 里用 GetMetaInfo2 取完整字段。
构造时会把 Performance 的全量加载设置改写为「开关启用、值为 false」，与 FRenderInfo 默认值相反。也就是说 LCC2 默认不走全量加载，需要时显式打开。

Spherical Harmonics

SetSHBands / GetSHBands

UFUNCTION(BlueprintCallable, Category = "XGrids")
void SetSHBands(int32 InSHBands);

UFUNCTION(BlueprintPure, Category = "XGrids")
int32 GetSHBands() const;

设置参与计算的球谐阶数，范围 1~3。对该组件渲染的所有格式生效，包括 LCC2、SOG、SPZ、PLY。

参数	类型	说明
`InSHBands`	`int32`	阶数，1 最省，3 最完整。超出数据实际存储的阶数无效

用法要点：

默认值取自加载的数据，同时也是上限。数据只存了 2 阶时设 3 不会有额外效果。
相比直接 SetUseShcoef(false) 完全关掉球谐，降阶是更细的取舍。
生效前提是 bUseShcoef 已开启且渲染模式为 3DGS，否则该值不参与计算。
画质与开销的权衡见画面调节 - SH 阶数。

ULCC2Component* Comp = Cast<ULCC2Component>(Actor->GetLCCComponent());
if (Comp)
{
    // 中配设备降到 2 阶
    Comp->SetSHBands(2);
}

按档位配置的写法：

void ConfigureSH(ULCC2Component* Comp, EQualityTier Tier)
{
    if (!Comp || !Comp->CanSetShcoef())
    {
        return;   // 数据本身没球谐，不用管
    }

    switch (Tier)
    {
    case EQualityTier::High:
        Comp->SetUseShcoef(true);
        Comp->SetSHBands(3);
        break;
    case EQualityTier::Medium:
        Comp->SetUseShcoef(true);
        Comp->SetSHBands(2);
        break;
    case EQualityTier::Low:
        Comp->SetUseShcoef(false);   // 直接关掉
        break;
    }
}

Lighting

LightingScale

UPROPERTY(Interp, EditAnywhere, BlueprintReadWrite, Category = "XGrids|Lighting",
    meta = (UIMin = "0.0", UIMax = "1.0", ClampMin = "0.0", ClampMax = "1.0"))
float LightingScale = 0.0f;

场景光照介入前的 3DGS 基础颜色亮度，范围 0~1，默认 0。0 表示完全由场景光照驱动，1 表示保留完整原始亮度。

取值影响与调法见法线与光照 - LCC2 光照亮度。

用法要点：

只在 LightMode 为 Lit 时有意义，Unlit 下不起作用。
是 BlueprintReadWrite 属性，直接赋值即可，没有 Setter 函数。
带 Interp，可以在 Sequencer 里做昼夜变化的关键帧。

Comp->SetLightMode(ELightMode::Lit);
Comp->LightingScale = 0.3f;    // 保留三成原始亮度，其余交给场景光

NormalMode

UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "XGrids|Lighting")
ELCC2NormalGenerationMode NormalMode = ELCC2NormalGenerationMode::Fixed;

控制 3DGS 表面如何响应场景光照。3DGS 数据本身没有几何法线，前三种模式都是用近似手段构造法线，只有 ProxyMesh 提供真实法线。

四种模式的效果对比、适用场景与调参方法见法线与光照，取值定义见 Enums。

// Fixed 模式，指定法线朝上
Comp->NormalMode = ELCC2NormalGenerationMode::Fixed;
Comp->FixedNormal = FVector(0.0, 0.0, 1.0);

// Hemispherical 模式，调整光照扫过的方向与对比
Comp->NormalMode = ELCC2NormalGenerationMode::Hemispherical;
Comp->NormalPole = FVector(1.0, 0.0, 1.0);
Comp->NormalHemiSpread = 1.2f;

FixedNormal

UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "XGrids|Lighting",
    meta = (EditCondition = "NormalMode == ELCC2NormalGenerationMode::Fixed", EditConditionHides))
FVector FixedNormal = FVector(0.0, 0.0, 1.0);

Fixed 模式专用。整片 3DGS 共用的世界空间法线，默认朝上。不需要归一化。

用法要点：

整片共用一个法线，意味着整片的亮度是同一个值，等于 dot(法线, 光照方向)。
光从法线的背面照过来时整片会变暗甚至全黑。室外场景法线朝上、光源在上方，通常没问题。
如果场景主体是一面墙，把法线改成墙的朝向会更合理。

NormalPole

UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "XGrids|Lighting",
    meta = (EditCondition = "NormalMode == ELCC2NormalGenerationMode::Hemispherical", EditConditionHides))
FVector NormalPole = FVector(1.0, 0.0, 1.0);

Hemispherical 模式专用。表面被当作朝向哪个方向，决定方向光旋转时明暗边界如何在 3DGS 上移动。不需要归一化。

调法：先摆好方向光，然后调整这个向量，观察明暗分界线的走向是否符合预期。

NormalHemiSpread

UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "XGrids|Lighting",
    meta = (UIMin = "0.0", UIMax = "4.0", ClampMin = "0.0",
        EditCondition = "NormalMode == ELCC2NormalGenerationMode::Hemispherical", EditConditionHides))
float NormalHemiSpread = 0.5f;

Hemispherical 模式专用。明暗在表面上的变化强度，范围 0~4，默认 0.5。

值越小明暗越平、越均匀；值越大受光区与阴影区的反差越强。

AlphaThreshold

UPROPERTY(Interp, EditAnywhere, BlueprintReadWrite, Category = "XGrids", AdvancedDisplay,
    meta = (UIMin = "0.01", UIMax = "0.99", ClampMin = "0.01", ClampMax = "0.99"))
float AlphaThreshold = 0.5f;

中值深度判定的累积不透明度阈值，范围 0.01~0.99，默认 0.5。属于高级项。

从近到远累加不透明度，累计值达到该阈值时把当前深度记为该像素的代表深度。值偏小深度偏向摄像机一侧，偏大则偏向远侧。

影响 3DGS 与传统网格的遮挡关系、阴影投射与后处理。默认值适用于大多数情况，取值说明见画面调节 - 深度阈值。

GetEffectiveNormalGenerationMode

UFUNCTION(BlueprintPure, Category = "XGrids")
ELCC2NormalGenerationMode GetEffectiveNormalGenerationMode() const;

返回经过授权校验后实际生效的法线模式。

返回值：已授权时返回 NormalMode 的原值；选了受授权限制的 ProxyMesh 但未授权时返回 Fixed。

用法要点：

存储的 NormalMode 属性不会被修改，只是渲染时按降级后的模式走。所以读 NormalMode 和读这个函数可能不一致。
做 UI 提示时用它。用户选了 ProxyMesh 但实际跑的是 Fixed，界面上应该给出说明。

const ELCC2NormalGenerationMode Requested = Comp->NormalMode;
const ELCC2NormalGenerationMode Effective = Comp->GetEffectiveNormalGenerationMode();

if (Requested != Effective)
{
    UE_LOG(LogTemp, Warning,
        TEXT("ProxyMesh mode requires a license, fell back to Fixed"));
}

文本蓝图：

[Get Effective Normal Generation Mode]
        Target = (LCC2 Component)
        │ Return Value ──┐
        ▼                │
[Equal (Enum)] ◀─────────┘
        A = (Return Value)
        B = Proxy Mesh
        │
        ▼
[Branch]
        │ False
        ▼
[Print String]  In String = "ProxyMesh 需要授权，已回退为 Fixed"

Other Methods

GetMetaInfo2

FLCC2MetaInfo GetMetaInfo2();

返回 LCC2 的完整元信息。仅 C++ 可用。

比基类的 GetMetaInfo() 多出工作路径、数据源类型、球谐阶数、八叉树根节点、文件列表等字段。字段说明见 Structs。

GetLccVersion

virtual ELCCVersion GetLccVersion() const override;

固定返回 ELCCVersion::LCC2。