XGRIDS文檔

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

屬性類型默認範圍說明
SHBandsint3231~3球諧階數。默認取數據裏存的階數，也是上限
LightingScalefloat0.00~1場景光照介入前的 3DGS 原始顏色亮度
AlphaThresholdfloat0.50.01~0.99中值深度判定的累積不透明度閾值，高級項
NormalModeELCC2NormalGenerationModeFixed—法線生成模式，決定 3DGS 如何響應場景光
FixedNormalFVector(0, 0, 1)—Fixed 模式下整片 3DGS 共用的世界法線
NormalPoleFVector(1, 0, 1)—Hemispherical 模式下的表面朝向
NormalHemiSpreadfloat0.50~4Hemispherical 模式下的明暗變化強度

法線相關屬性帶 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。

參數類型說明
InSHBandsint32階數，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。

See Also