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。