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 を参照する。

3 つのプロパティにはいずれも 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();

クリッピングの結果の更新を手動で 1 回トリガーする。内部でバインドされた LCC Component にレンダリング状態の再構築が必要であるとマークする。

実行時にクリッピングボリュームを変更した後は必ず呼ぶ必要があり、そうしないと変更が反映されない。対象は次のものである。

プロパティの変更：bEnabled、Mode、VolumeType。これらのプロパティには Setter がなく、直接代入してもレンダリング側に通知されない。
トランスフォームの変更：SetActorLocation、SetActorRotation、SetActorScale3D。

自動更新はエディター内でのみ起きる。Details パネルでプロパティを変更すると PostEditChangeProperty を通り、ギズモをドラッグすると EditorApplyTranslation などの関数を通る。これらの経路はいずれも WITH_EDITOR の下にあり、実行時には存在しない。

前提として SetUpdateComponent を呼んだか、AddClippingVolume で関連付けを確立している必要がある。Component をバインドしていない場合はレンダリングの更新が一切トリガーされない。

複数のクリッピングボリュームをまとめて変更する場合は、1 つずつプロパティを変更した後にそれぞれ Refresh() を 1 回呼ぶ。

実行時に作成する

#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();          // 実行時のトランスフォームは自動更新されない

Blueprint のノードはシーン編集 - Blueprint のメソッドを参照する。

Notes

クリッピングはレンダリングにのみ影響し、コリジョンには影響しない。切り取られた領域も引き続きレイキャストで当たり、キャラクターを遮る。
複数のクリッピングボリュームが同時に作用する場合はそれぞれ独立に判定され、効果が重なる。Inside と Outside が混在すると予期しない結果になりやすい。
同時に有効になるクリッピングボリュームの数には上限があり、未ライセンスの場合は 50 個である。 超えた分はレンダリングに参加せず、警告を出力する。クリッピングボリュームと断面プレーンはこの枠を共有する。ライセンスの説明はエディションとライセンスを参照する。
クリッピングボリュームを破棄してもレンダリングの更新が 1 回トリガーされるだけで、Component の ClippingVolumes 配列から要素は削除されない。配列には無効なポインターが残る（レンダリング時に自動的にスキップされる）。配列をきれいに保ちたい場合は、破棄する前に RemoveClippingVolume を呼ぶ。