ALCCClippingVolume：3DGS 裁剪體

裁剪體 Actor，用盒形或球形體積裁掉 LCC 場景的一部分。


模塊	`LCC4UnrealRuntime`
頭文件	`Tools/LCCClippingVolume.h`
父類	`AVolume`
面板顯示名	LCC Clipping Volume

#include "Tools/LCCClippingVolume.h"

使用步驟、演示效果與屬性面板說明見場景編輯 - 裁剪框。本頁只列接口。

Properties

屬性	類型	說明
`bEnabled`	`bool`	是否參與裁剪
`Mode`	`EClipType`	`Inside` 裁掉體積內部，`Outside` 裁掉體積外部
`VolumeType`	`EClipVolumeType`	`Box` 盒形，`Sphere` 球形

取值含義見 EClipType 與 EClipVolumeType。

三個屬性都沒有 Setter，運行時賦值後需要調用 Refresh 才生效。運行時改變換也一樣。

Methods

SetUpdateComponent

UFUNCTION(BlueprintCallable, Category = "XGrids")
void SetUpdateComponent(ULCCComponentBase* Component);

綁定要更新的 LCC Component。

參數	類型	說明
`Component`	`ULCCComponentBase*`	目標 Component

Refresh() 需要這個綁定才能生效，它內部就是把綁定的 Component 標記為需要重建渲染狀態。沒綁定時 Refresh() 不會觸發渲染更新。

用 AddClippingVolume 添加時通常已建立關聯；運行時動態創建的裁剪體如果改動不生效，先檢查是否調過這個方法。

Refresh

UFUNCTION(BlueprintCallable, Category = "XGrids")
void Refresh();

手動觸發一次裁剪結果更新，內部會把綁定的 LCC Component 標記為需要重建渲染狀態。

運行時改動裁剪體後必須調用它，修改才會生效，包括：

改屬性：bEnabled、Mode、VolumeType。這幾個屬性沒有 Setter，直接賦值不會通知渲染側。
改變換：SetActorLocation、SetActorRotation、SetActorScale3D。

自動更新只發生在編輯器裏：細節面板改屬性走 PostEditChangeProperty，拖動 gizmo 走 EditorApplyTranslation 等函數，這些路徑都在 WITH_EDITOR 下，運行時不存在。

前提是已經調過 SetUpdateComponent 或通過 AddClippingVolume 建立了關聯。沒有綁定 Component 時不會觸發任何渲染更新。

批量修改多個裁剪體時，逐個改完屬性後各自調一次 Refresh()。

運行時創建

#include "Tools/LCCClippingVolume.h"
#include "LCCComponentBase.h"

ALCCClippingVolume* AMyTool::CreateBoxClip(
    ULCCComponentBase* Component, const FVector& Location, const FVector& Extent)
{
    ALCCClippingVolume* Volume = GetWorld()->SpawnActor<ALCCClippingVolume>(
        ALCCClippingVolume::StaticClass(), Location, FRotator::ZeroRotator);
    if (!Volume)
    {
        return nullptr;
    }

    Volume->VolumeType = EClipVolumeType::Box;
    Volume->Mode = EClipType::Inside;
    Volume->bEnabled = true;

    // AVolume 的尺寸通過縮放控制
    Volume->SetActorScale3D(Extent / 100.0f);

    Volume->SetUpdateComponent(Component);
    Component->AddClippingVolume(Volume);

    return Volume;
}

臨時開關裁剪效果不要增刪數組，直接改 bEnabled 更輕量。注意改完要調 Refresh()：

for (ALCCClippingVolume* Volume : MyVolumes)
{
    if (Volume)
    {
        Volume->bEnabled = bEnable;
        Volume->Refresh();
    }
}

運行時移動裁剪體做動畫，同樣每次都要刷新：

// 讓裁剪體掃過場景
FVector Loc = ClipVolume->GetActorLocation();
Loc.X += 200.0f * DeltaTime;
ClipVolume->SetActorLocation(Loc);
ClipVolume->Refresh();          // 運行時變換不會自動更新

藍圖節點見場景編輯 - 藍圖方法。

Notes

裁剪只影響渲染，不影響碰撞。裁掉的區域仍可被射線打中、仍會擋住角色。
多個裁剪體同時作用時各自獨立判定，效果疊加。既有 Inside 又有 Outside 時容易出現意外結果。
同時生效的裁剪體數量有上限，未授權時為 50 個，超出的不參與渲染並輸出警告。裁剪體與剖切面共用這個配額。授權說明見版本與授權。
銷毀裁剪體只會觸發一次渲染更新，不會從 Component 的 ClippingVolumes 數組裏移除元素，數組中會殘留失效指針（渲染時會自動跳過）。需要保持數組乾淨的話，銷毀前先調 RemoveClippingVolume。