Structs:結構體類型參考
LCC4UnrealRuntime 模塊對外公開的結構體類型。
| 模塊 | LCC4UnrealRuntime |
| 頭文件 | Core/LCCStructure.h |
#include "Core/LCCStructure.h"
標記 BlueprintType 的結構體可以在藍圖中用 Break / Make 節點拆裝。
Performance
FRenderInfo
通用性能參數。用於 ULCCComponentBase::Performance。
這個結構體的設計特點是每個數值都配一個啟用開關。開關關閉時使用插件內置默認值,打開後才用你填的值。Component 上對應的 Setter 會自動把開關置為 true。
| 字段 | 類型 | 默認 | 配套開關 | 說明 |
|---|---|---|---|---|
MaxDistance | uint32 | 300 | bDistanceLimit | 最大渲染距離,單位米 |
MaxSplatNum | uint32 | 3000 | bMaxSplatNumLimit | 每幀最大 Splat 數,單位萬,上限 10000 |
LevelFactor | float | 1 | bCanSetLevelFactor | LOD 距離縮放因子,範圍 0.01~20 |
PreloadDistance | uint32 | 200 | bPreloadDistanceLimit | 預加載距離。實際取值為 MaxDistance + 35 |
StartLevel | uint32 | 0 | bCanSetStartLevel | 起始 Level,範圍 0~20 |
EndLevel | uint32 | 20 | bCanSetEndLevel | 結束 Level,範圍 0~20 |
CollisionLoadMaxDistance | uint32 | 300 | bCollisionDistanceLimit | 碰撞加載最大距離,單位米 |
bUseFullLoad | bool | true | bCanSetUseFullLoad | 小場景全量加載開關。ULCC2Component 構造時改寫為開關啟用、值為 false |
FullLoadSplatNum | uint32 | 1500 | bCanSetFullLoadNum | 全量加載閾值,單位萬 |
輔助方法:
bool HasMaxDistanceLimit() const; // 是否有距離限制
bool HasMaxNumLimit() const; // 是否有數量限制
bool NeedPreload() const; // 是否需要預加載
uint32 GetMaxDistance() const; // 生效的最大距離
uint32 GetMaxSplatNum() const; // 生效的最大數量
float GetLevelFactor() const; // 生效的 LOD 因子
uint32 GetStartLevel() const; // 生效的起始 Level
uint32 GetEndLevel() const; // 生效的結束 Level
uint32 GetMaxCollisionDistance() const;
uint32 GetPreloadDistance() const; // 返回 GetMaxDistance() + 35
bool GetIfUseFullLoad(uint32 SplatNum) const; // 給定數量是否走全量加載
void Reset(); // 只重置數值字段,不重置啟用開關
兩點容易踩的地方:
Reset()只重置數值字段(距離、數量、Level、因子),不重置任何b*啟用開關,也不重置bUseFullLoad與FullLoadSplatNum。FRenderInfo::GetPreloadDistance()返回的是GetMaxDistance() + 35;而組件上的同名函數ULCCComponentBase::GetPreloadDistance()返回的是原始字段值。兩者結果不同。
Getter 返回的是生效值:開關關閉時返回內置默認值,不是你之前填過的值。這一點容易混淆,直接讀字段和調 Getter 可能得到不同結果。
用法要點:
- 通過 Component 的 Setter 修改最省事,不用手動管開關。
- 直接改結構體字段時記得同時把開關置
true,否則不生效。
// 推薦:用 Setter,開關自動處理
Component->SetMaxDistance(200);
// 直接改字段則必須自己開開關
Component->Performance.bDistanceLimit = true;
Component->Performance.MaxDistance = 200;
FLCCRenderInfo
LCC1 專屬性能參數。用於 ULCCComponent::LCCPerformance。
| 字段 | 類型 | 默認 | 配套開關 | 說明 |
|---|---|---|---|---|
SortFactor | float | 1 | bCanSetSortFactor | 排序頻率縮放因子,範圍 0.2~5。值越大排序次數越少、性能越好 |
bAddExtraPreNodes | bool | 由宏決定 | bEnableExtraPreNodes | 追加額外預加載節點,緩解快速轉視角時屏幕邊緣的空洞 |
輔助方法:
float GetSortFactor() const;
bool GetIfAddExtraPreNodes() const;
void Reset();
相關頁面:ULCCComponent
Metadata
FMetaInfoBase
元信息基類,FLCCMetaInfo 與 FLCC2MetaInfo 都繼承它。ULCCComponentBase::GetMetaInfo 的返回類型。
| 字段 | 類型 | 說明 |
|---|---|---|
Name | FString | 數據名稱 |
Version | FString | 數據版本字符串 |
Description | FString | 描述 |
Source | FString | 來源 |
DataType | FString | 數據類型 |
FileType | FString | 文件類型,對應 EFileType |
Offset | TArray<float> | 坐標偏移,3 個元素 |
Shift | TArray<float> | 平移量 |
Epsg | int32 | EPSG 坐標系編號,大於 0 表示有地理坐標信息 |
Scale | TArray<int> | 縮放,3 個元素 |
GUID | FString | 數據唯一標識 |
TotalLevel | int | 總 Level 層數 |
TotalSplats | int | 總 Splat 數量 |
Splats | TArray<int> | 各 Level 的 Splat 數量 |
輔助方法:
bool IsValid() const; // 元信息是否有效
void Reset();
bool IsRTK() const; // 是否含 RTK 地理信息
FVector GetOffset() const; // 偏移轉 FVector,元素數不足 3 時返回零向量並警告
FVector3f GetScale(); // 注意:非 const,且不檢查元素數量
EFileType GetFileType() const; // 文件類型枚舉
float GetVersion() const; // 版本號轉 float
uint32 GetLevel0SplatNum() const; // Level 0 的 Splat 數,單位萬
GetScale() 與 GetOffset() 的健壯性不同:GetOffset() 會檢查元素數量,不足 3 時返回零向量並輸出警告;GetScale() 直接索引前三個元素,Scale 不足 3 個元素時會越界。
IsRTK() 的判斷依據是 Epsg > 0 且偏移非零,只看數據本身。它與 CanUseGeoPlace() 不等價,後者還額外要求 bEnableGeoPlace 已開啟且地理參考系統已創建。
用法要點:
- 加載完成後再讀,未就緒時字段都是零值。
TotalSplats是數據總量。ULCCComponentBase::GetSplatNumber()返回的就是這個字段,兩者是同一個值。
if (Component->CheckIfLoaded())
{
const FMetaInfoBase Meta = Component->GetMetaInfo();
UE_LOG(LogTemp, Log, TEXT("Name: %s"), *Meta.Name);
UE_LOG(LogTemp, Log, TEXT("Levels: %d, total splats: %d"),
Meta.TotalLevel, Meta.TotalSplats);
UE_LOG(LogTemp, Log, TEXT("Level 0 splats: %u (ten thousand)"),
Meta.GetLevel0SplatNum());
UE_LOG(LogTemp, Log, TEXT("Has SH: %s"),
Meta.GetFileType() == EFileType::Quality ? TEXT("yes") : TEXT("no"));
if (Meta.IsRTK())
{
UE_LOG(LogTemp, Log, TEXT("EPSG: %d, offset: %s"),
Meta.Epsg, *Meta.GetOffset().ToString());
}
}
文本藍圖:
[Get Meta Info]
Target = (LCC Component)
│ Return Value ──┐
▼ │
[Break FMetaInfoBase] ◀──┘
Name → [Print String]
Total Splats → [Print String]
Total Level → [Print String]
FLCCMetaInfo
LCC1 完整元信息,繼承 FMetaInfoBase。
| 附加字段 | 類型 | 說明 |
|---|---|---|
CellLengthX | float | 網格 X 方向尺寸 |
CellLengthY | float | 網格 Y 方向尺寸 |
Attributes | TArray<FBoundingBoxInfoWithName> | 各屬性的包圍盒,按名稱索引 |
IndexDataSize | int | 索引數據大小 |
Encoding | FString | 編碼方式 |
BoundingBox | FBoundingBoxInfo | 整體包圍盒 |
IsValid() 的條件比基類嚴格:TotalLevel、TotalSplats、CellLengthX、CellLengthY、IndexDataSize 都必須大於 0。
包圍盒相關方法(均返回 FBox,僅 C++):
FVector2f GetCellLength() const;
int32 GetXNum() const; // X 方向網格數
int32 GetYNum() const; // Y 方向網格數
FBox GetVisibleBoundingBox() const; // 可見包圍盒
FBox GetScaleBox() const;
FBox GetEnvironmentScaleBox() const;
FBox GetEnvironmentVisibleBox() const;
FBox GetShcoef() const; // 球諧取值範圍
FBox GetEnvShcoef() const;
FBox GetNormal() const;
FBox GetEnvNormal() const;
FBox GetColor() const;
FVector2f GetOpacity() const;
FLCC2MetaInfo
LCC2 完整元信息,繼承 FMetaInfoBase。ULCC2Component::GetMetaInfo2 的返回類型。
| 附加字段 | 類型 | 說明 |
|---|---|---|
WorkPath | FString | LCC2 目錄路徑 |
SplatType | EDataSourceType | 數據源格式,SOG / SPZ / PLY |
SHBands | int32 | 該樹中最高球諧階數,0 表示無,取值 1/2/3 |
EnvName | int32 | 環境文件索引,-1 表示無 |
Root | FTreeNode | 八叉樹根節點 |
Files | TArray<FString> | Splat 數據文件列表 |
MeshFiles | TArray<FString> | 網格文件列表 |
BVHFiles | TArray<FString> | BVH 文件列表 |
IsValid() 的條件是 Files 非空。
輔助方法:
FBox GetBounds() const; // 根節點包圍盒,已換算為厘米
關於 SHBands:它決定球諧槽位的步長,因此同一個球諧緩衝裏的所有數據源必須一致。混合了不同階數的樹取最寬的那個。單文件格式(.sog / .spz / .ply)從解碼器頭部讀取精確階數;LCC2 沒有逐文件階數概念,由 FileType 決定,Portable 無球諧,Quality 為 3 階。
Raycast Result
FLCCSplat
射線檢測的命中結果。用於 ULCCComponent 的射線檢測函數。
| 字段 | 類型 | 說明 |
|---|---|---|
Location | FVector | 命中點的世界坐標 |
NodeVector | FLCCVector | 命中點所屬的節點信息 |
FLCCSplat Hit;
if (LineTraceSingle(Start, End, Hit, false, 0.f, 0.f))
{
// 命中位置
const FVector HitPos = Hit.Location;
// 該處當前加載的細節層級
const int32 Level = Hit.NodeVector.Level;
}
相關頁面:ULCCComponent 射線檢測
FLCCVector
節點坐標,定位節點在八叉樹中的位置。
| 字段 | 類型 | 說明 |
|---|---|---|
X | int32 | 節點 X 索引 |
Y | int32 | 節點 Y 索引 |
Level | int32 | 節點所在 Level |
帶參構造和拷貝構造會把三個字段鉗制為非負數,但直接賦值(默認構造後寫字段、或用 operator=)不做鉗制。
輔助方法:
FString ToString() const; // 格式為 "X:%i,Y:%i,Level:%i"
void Reset();
static double Dist2D(const FLCCVector& A, const FLCCVector& B);
相等判斷只比較 X、Y、Level,不比較內部的攝像機信息等運行時字段。
Level 可以用來判斷當前看到的是精細數據還是粗糙數據,數值越小越精細。
Bounding Box
FBoundingBoxInfo
包圍盒信息。
| 字段 | 類型 | 說明 |
|---|---|---|
Min | TArray<float> | 最小點坐標 |
Max | TArray<float> | 最大點坐標 |
FBoundingBoxInfoWithName
帶名稱的包圍盒,用於元信息中的屬性列表。
| 字段 | 類型 | 說明 |
|---|---|---|
Name | FString | 屬性名 |
BoundingBoxInfo | FBoundingBoxInfo | 包圍盒 |
相等判斷只比較 Name。
SOG Metadata
這組結構體用於描述 .sog 文件的元信息,由 ULCCUtilLibrary 的 SOG 解析函數輸出。
FLCC2SogMeta
SOG 元信息主結構。
| 字段 | 類型 | 說明 |
|---|---|---|
Version | int32 | 格式版本 |
Count | int32 | Splat 數量 |
bAntialias | bool | 是否啟用抗鋸齒 |
Instances | FLCC2SogInstances | 實例文件列表 |
Means | FLCC2SogMeans | 位置數據,含最小值、最大值與文件列表 |
Scales | FLCC2SogScales | 縮放數據,含 256 項碼書與文件列表 |
Quats | FLCC2SogQuats | 旋轉數據文件列表 |
Semantics | FLCC2SogSemantics | 語義數據文件列表 |
Sh0 | FLCC2SogSh0 | 零階球諧,含 256 項碼書與文件列表 |
ShN | FLCC2SogShN | 高階球諧,含階數、碼書、數量與文件列表 |
輔助方法:
bool HasShN() const; // 是否含高階球諧,等價於 ShN.Files 非空
用法要點:
- 用
ParseSogMetaFromFile在不加載渲染數據的前提下讀取,開銷很小。 - 可以據此在加載前判斷點數與球諧情況,提前決定畫質配置。
FLCC2SogMeta Meta;
if (ULCCUtilLibrary::ParseSogMetaFromFile(Path, Meta))
{
UE_LOG(LogTemp, Log, TEXT("Version: %d, count: %d, high-order SH: %s"),
Meta.Version, Meta.Count, Meta.HasShN() ? TEXT("yes") : TEXT("no"));
}
FLCC2SogShN
高階球諧數據。
| 字段 | 類型 | 說明 |
|---|---|---|
Bands | int32 | 球諧階數 |
Count | int32 | 數量 |
Files | TArray<FString> | 文件列表 |
Codebook | TStaticArray<float, 256> | 量化碼書,非藍圖可見 |
輔助方法:bool HasShN() const。
FLCC2SogImageData
SOG 圖像數據。
| 字段 | 類型 | 說明 |
|---|---|---|
PixelData | TArray<uint8> | 像素數據,RGBA 格式,每像素 4 字節 |
Width | int32 | 寬度 |
Height | int32 | 高度 |
其他子結構
以下結構都只含文件列表,部分帶量化碼書:
| 結構體 | 字段 |
|---|---|
FLCC2SogInstances | Files |
FLCC2SogSemantics | Files |
FLCC2SogQuats | Files |
FLCC2SogMeans | Mins、Maxs、Files |
FLCC2SogScales | Codebook(256 項)、Files |
FLCC2SogSh0 | Codebook(256 項)、Files |
Codebook 是 TStaticArray<float, 256>,不是 UPROPERTY,藍圖中不可見。
Octree Nodes
這組結構體描述 LCC2 的八叉樹,屬於底層數據,常規開發不需要直接操作。
FTreeNode
八叉樹節點。
| 字段 | 類型 | 說明 |
|---|---|---|
Id | FString | 節點標識 |
XMin / YMin / ZMin | double | AABB 最小點 |
XMax / YMax / ZMax | double | AABB 最大點 |
ChildNum | int32 | 子節點數量 |
Children | TArray<FTreeNode> | 子節點數組,非 UPROPERTY |
Data | FTreeNodeData | 節點數據 |
輔助方法:
void ClearIterative();
用廣度優先收集所有節點後逆序清理,避免樹很深時遞歸析構導致棧溢出。手動持有 FTreeNode 時,在它離開作用域前調用。
FTreeNodeData
節點數據容器,用布爾標記各類數據是否存在。
| 字段 | 類型 | 說明 |
|---|---|---|
bHas3DGS | bool | 是否含 3DGS 數據 |
_3DGS | FTreeNodeData3DGS | 3DGS 數據 |
bHasMesh | bool | 是否含網格數據 |
Mesh | FTreeNodeDataMesh | 網格數據 |
bHasBVH | bool | 是否含 BVH 數據 |
BVH | FTreeNodeDataBVH | BVH 數據 |
FTreeNodeData3DGS
| 字段 | 類型 | 說明 |
|---|---|---|
Name | int32 | 文件索引 |
Start | int32 | 起始偏移 |
Count | int32 | 數量 |
FTreeNodeDataMesh
| 字段 | 類型 | 說明 |
|---|---|---|
Name | int32 | 文件索引 |
Vertex | int32 | 頂點數 |
Face | int32 | 面數 |
FTreeNodeDataBVH
| 字段 | 類型 | 說明 |
|---|---|---|
Name | int32 | 文件索引 |
See Also
- ULCCComponentBase:
FRenderInfo與FMetaInfoBase的使用 - ULCCComponent:
FLCCSplat與FLCCRenderInfo的使用 - ULCCUtilLibrary:SOG 元信息解析函數
- Enums:這些結構體中用到的枚舉類型