ALCCActorBase: 3DGS Actor Temel Sınıfı

Tüm LCC Actor'larının temel sınıfıdır; 3DGS verilerini seviyeye yerleştirmekten sorumludur. ALCCActor, ALCC2Actor, ASogActor, ASpzActor ve APlyActor sınıflarının tümü bu sınıftan türetilir.

#include "LCCActorBase.h"

Actor'ın kendisi görüntüleme yapmaz: bir ULCCComponentBase barındırır ve yükleme işlemlerini ona iletir. Görüntüleme parametreleri, renk, performans ve çarpışma ayarlarının tümü Component üzerindedir; bu Component'e GetLCCComponent ile erişilir.

Ölçekleme sınırlaması: LCC Actor'ları yalnızca düzgün (uniform) ölçeklemeyi destekler. Negatif değerli ölçekler (ör. (-1, 1, 1)) veya eksene göre farklı ölçekler (ör. (2, 1, 3)) kullanmayın; aksi halde görüntüleme artefaktları oluşur ve bunlar genellikle ekranda tek bir çizgi olarak görünür.

Özellikler

Her iki özellik de VisibleAnywhere + BlueprintReadOnly niteliğindedir: Details panelinde veya Blueprint'te değiştirilemez, yalnızca okunabilir.

Metotlar

Load

UFUNCTION(BlueprintCallable, Category = "XGrids")
virtual void Load(const FString& String) const;

3DGS verilerini bir yoldan yükler. Çalışma zamanında sahne yüklemenin ana giriş noktasıdır.

Parametreler:

Kabul edilen yol biçimi alt sınıfa göre değişir:

Not: .lcc ve .lcc2 dosyalarının adlarını veriyi üreten taraf belirler. Bu nedenle dosyanın her zaman meta.lcc adını taşıdığını varsaymayın. Biçimi uzantıdan veya ULCCUtilLibrary::DetermineFileFormat ile belirleyin.

Kullanım notları:

• Metot const olarak tanımlıdır; çünkü durum değişikliği LCCComponent içinde gerçekleşir ve Actor'ın kendisi değiştirilmez.
• Yükleme asenkrondur. Çağrı döndüğünde veri hazır değildir ve mevcut sürümde GetLCCComponent()->CheckIfLoaded() ile yoklama (polling) yapmak gerekir. Yükleme tamamlanma geri çağrısı sonraki bir sürümde sunulacaktır; bundan sonra yoklamaya gerek kalmayacaktır.
• CheckIfLoaded() fonksiyonunun true döndürmesi yalnızca meta verinin ve dizinin oluştuğu, parametrelerin güvenle okunup ayarlanabileceği anlamına gelir. Splat verisi görünüme göre akmaya devam eder ve görüntü dolmaya devam eder.
• Kod yazmadan seviyede bir yolu önceden ayarlamak için Details panelinde Component üzerindeki DefaultLoadPath değerini ayarlayın; veri çalışma zamanında otomatik olarak yüklenir.
• Boş bir yol aktarmak, mevcut veriyi kaldırmakla eşdeğerdir.
• Aktarılan yol şu anda yüklü olan yolla aynıysa çağrı hemen döner ve hiçbir şey yeniden yüklenmez.
• Şüpheli bir yol için önce ULCCUtilLibrary::CheckLCCValid ile doğrulama yapın; böylece yükleme hatası yalnızca bir günlük iletisi olarak kalmaz.

C++ örneği:

#include "LCCActor.h"
#include "LCCComponentBase.h"

void AMyGameMode::SpawnLCCScene()
{
    // spawn the Actor
    ALCCActor* LCCActor = GetWorld()->SpawnActor<ALCCActor>(
        ALCCActor::StaticClass(),
        FVector::ZeroVector,
        FRotator::ZeroRotator);

    if (!LCCActor)
    {
        return;
    }

    // load from an absolute path
    LCCActor->Load(TEXT("D:/Data/Tower/Tower.lcc"));

    // or load relative to the Content directory
    // LCCActor->Load(TEXT("Tower/Tower.lcc"));
}

Veri üzerinde işlem yapmadan önce yüklemenin tamamlanmasını bekleyin. Mevcut sürümde geri çağrı yoktur, bu nedenle tek seçenek yoklamadır:

void AMyActor::LoadAndConfigure()
{
    LCCActor->Load(TEXT("D:/Data/Tower/Tower.lcc"));

    // check readiness every 0.2 seconds
    GetWorld()->GetTimerManager().SetTimer(
        LoadCheckTimer, this, &AMyActor::OnCheckLoaded, 0.2f, true);
}

void AMyActor::OnCheckLoaded()
{
    ULCCComponentBase* Component = LCCActor->GetLCCComponent();
    if (!Component || !Component->CheckIfLoaded())
    {
        return;
    }

    GetWorld()->GetTimerManager().ClearTimer(LoadCheckTimer);

    // metadata is ready, parameters can be configured safely (splat data is still streaming)
    Component->SetRenderMode(ERenderMode::Splatting);
    UE_LOG(LogTemp, Log, TEXT("Total splats: %d"), Component->GetSplatNumber());
}

Metin olarak Blueprint:

[Event BeginPlay]
        │
        ▼
[Spawn Actor from Class]
        Class = LCCActor
        Spawn Transform = (default)
        │ Return Value ──┐
        ▼                │
[Load] ◀────────────────┘
        Target = (Return Value of the previous step)
        String = "D:/Data/Tower/Tower.lcc"

UnLoad

UFUNCTION(BlueprintCallable, CallInEditor, Category = "Actions",
    meta = (DisplayName = "UnLoad", DisplayPriority = 2))
virtual void UnLoad();

Mevcut veriyi kaldırır ve GPU arabellekleri, düğüm önbellekleri ve çarpışma gövdeleri dahil kaynakları serbest bırakır.

Kullanım notları:

• CallInEditor ile Details panelinin Actions kategorisinde bir UnLoad düğmesi görünür ve doğrudan editörde tıklanabilir.
• Kaldırma işleminden sonra Actor seviyede kalır ve yalnızca hiçbir şey görüntülemez. Load fonksiyonunu yeniden çağırmak başka bir veriyi yükler.
• Büyük sahneler arasında geçiş yaparken, iki veri kümesinin aynı anda video belleğini kaplamaması için Load öncesinde UnLoad çağırın.
• EndPlay içinde elle çağrı yapmak gerekmez; Component yok edilirken kendini temizler.

C++ örneği, sahne geçişi:

void AMyManager::SwitchScene(const FString& NewPath)
{
    // release the old data first, so the video memory peaks do not stack
    LCCActor->UnLoad();
    LCCActor->Load(NewPath);
}

Refresh

UFUNCTION(BlueprintCallable, CallInEditor, Category = "Actions",
    meta = (DisplayPriority = 3))
virtual void Refresh();

Mevcut veriyi yeniden yükler. Dahili olarak UnLoad() ve ardından Load() çalıştırır; bu nedenle maliyeti tam bir yeniden yüklemeyle aynıdır ve hafif bir işlem değildir.

"Mevcut" veriyi yeniden yüklemek mümkündür; çünkü başarılı bir yükleme yolu DefaultLoadPath değerine de yazar ve Refresh bu değeri okur.

Kullanım notları:

• Diskteki veri dosyaları değiştirildikten sonra diskten yeniden okumak için kullanın.
• Görüntüleme sonucunun yeniden hesaplanmasını sağlamak için kullanmayın. Bir özelliği Setter ile değiştirmek güncellemeyi otomatik olarak tetikler; tek bir kare göndermek için Component üzerindeki hafif seçenek olan ForceUpdate() fonksiyonunu kullanın.
• Yeniden yüklemeden sonra tekrar hazır olmasını bekleyin; Component üzerinde daha önce ayarlanan çalışma zamanı parametrelerinin yeniden ayarlanması gerekebilir.
• Editörde Details panelinin Actions kategorisinde karşılık gelen bir düğme görünür.

GetLCCComponent

UFUNCTION(BlueprintCallable, Category = "XGrids")
ULCCComponentBase* GetLCCComponent() const;

Actor içindeki Component'e işaretçiyi döndürür. Tüm görüntüleme yeteneklerinin giriş noktası budur.

Dönüş değeri: ULCCComponentBase*. Actor oluşturulurken yaratıldığı için normal koşullarda null değildir.

Kullanım notları:

• Alt sınıfa özgü bir yetenek gerektiğinde tür dönüşümü (downcast) yapın. ALCCActor bir ULCCComponent verir; ALCC2Actor ve üç tek dosyalı Actor ise bir ULCC2Component verir.
• Tür dönüşümünü her zaman Cast<> ile yapın, C tarzı dönüşüm kullanmayın. Tür uyuşmazlığında Cast, nullptr döndürür; bu da erken çıkışı kolaylaştırır.

C++ örneği, ortak temel sınıf parametrelerini değiştirme:

ULCCComponentBase* Component = LCCActor->GetLCCComponent();
if (Component)
{
    Component->SetSplatScale(0.8f);
    Component->SetGlobalAlpha(1.0f);
}

LCC2'ye özgü parametrelere erişmek için tür dönüşümü:

#include "LCC2Component.h"

ULCC2Component* LCC2Comp = Cast<ULCC2Component>(LCC2Actor->GetLCCComponent());
if (LCC2Comp)
{
    LCC2Comp->SetSHBands(2);
    LCC2Comp->NormalMode = ELCC2NormalGenerationMode::Hemispherical;
}

Metin olarak Blueprint; Blueprint'te dönüşüm için Cast To düğümü kullanılır:

[Get LCC Component]
        Target = LCCActor
        │ Return Value ──┐
        ▼                │
[Cast To LCC2Component] ◀┘
        Object = (Return Value of the previous step)
        │ Cast Succeeded
        ▼
[Set SH Bands]
        Target = (As LCC2 Component output of the Cast)
        In SH Bands = 2

SelectFile

UFUNCTION(BlueprintCallable, CallInEditor, Category = "Actions",
    meta = (DisplayName = "Load", DisplayPriority = 1))
virtual void SelectFile();

Sistem dosya iletişim kutusunu açar ve seçimi hemen yükler.

Kullanım notları:

• Details panelinde Load düğmesi olarak görünür; editörde veri yüklemenin en yaygın yoludur.
• Her alt sınıf, ilgili uzantıyı filtrelemek için bu fonksiyonu geçersiz kılar: ASogActor yalnızca .sog, ASpzActor yalnızca .spz, APlyActor yalnızca .ply dosyalarını listeler.
• Editör iletişim kutusu yeteneklerine bağlıdır; bu nedenle paketlenmiş çalışma zamanında kullanmayın. Çalışma zamanında bunun yerine Load fonksiyonunu kullanın.

DebugNodeBound

UFUNCTION(BlueprintCallable, CallInEditor, Category = "Actions",
    meta = (DisplayName = "Debug Node Bound", DisplayPriority = 4))
void DebugNodeBound();

Octree düğüm sınırlarının görselleştirmesini açar veya kapatır; o anda yüklü düğümleri tel kafes kutular olarak çizer.

Kutu rengi, düğüm Level değerine karşılık gelir: sırasıyla kırmızı, turuncu, sarı, yeşil, mavi ve mor. Kırmızı en düşük Level (en yüksek ayrıntı), beyaz ise en yüksek Level (en düşük ayrıntı) anlamına gelir.

Kullanım notları:

• LOD sorunlarını incelemek için kullanın. Uzakta hâlâ görüntülenen kırmızı kutular, LevelFactor değerinin çok küçük veya StartLevel değerinin çok düşük ayarlandığını ve performansın boşa harcandığını gösterir.
• Tersine, yakında soğuk renkli yüksek Level kutuları görünüyorsa ayrıntı gereğinden fazla bastırılmıştır ve görüntü bulanık görünür.
• Kapatmak için yeniden çağırın; bu bir aç/kapat anahtarıdır.
• Yalnızca editörde ve geliştirme (development) derlemelerinde etkilidir.

Stats

UFUNCTION(BlueprintCallable, CallInEditor, Category = "Actions",
    meta = (DisplayPriority = 5))
void Stats();

Görüntüleme istatistikleri panelini açar veya kapatır; konsolda stat XGrids çalıştırmaya eşdeğerdir.

Panel, o anda görüntülenen splat sayısını, yüklenmekte olan düğüm sayısını ve her aşamada harcanan süreyi verir. Performans parametrelerini ayarlarken bunu izlemek, tahmine dayalı ayar yapmaktan daha güvenilirdir.

ShowCollision

UFUNCTION(BlueprintCallable, CallInEditor, Category = "Actions",
    meta = (DisplayName = "Show Collision", DisplayPriority = 6))
void ShowCollision();

Çarpışma tel kafes görselleştirmesini açar veya kapatır; konsolda r.xgrids.DrawCollision çalıştırmaya eşdeğerdir.

Kullanım notları:

• Verinin kendisinin çarpışma bilgisi içermesini ve Component üzerinde bEnableCollision seçeneğinin etkin olmasını gerektirir; aksi halde hiçbir şey gösterilmez.
• Bir karakter geometrinin içinden geçtiğinde veya ışın testi hedefi ıskaladığında, çarpışma gövdelerinin yüklenip yüklenmediğini doğrulamak için önce bunu açın.
• Çarpışma verisi mesafeye göre akar; bu nedenle uzakta tel kafesin görünmemesi beklenen bir durumdur ve Performance.CollisionLoadMaxDistance ile denetlenir.

ShowFPS

UFUNCTION(BlueprintCallable, CallInEditor, Category = "Actions",
    meta = (DisplayName = "Show FPS", DisplayPriority = 7))
void ShowFPS();

Kare hızı göstergesini açar veya kapatır; konsolda stat fps çalıştırmaya eşdeğerdir. Kare hızını ve splat sayısını yan yana izlemek için Stats ile birlikte kullanın.

Tam Örnek

Çalışma zamanında bir LCC sahnesi yükleyin ve hazır olduğunda görüntüleme parametrelerini yapılandırın:

// MyLCCLoader.h
#pragma once

#include "CoreMinimal.h"
#include "GameFramework/Actor.h"
#include "MyLCCLoader.generated.h"

UCLASS()
class AMyLCCLoader : public AActor
{
    GENERATED_BODY()

public:
    /** Data path to load, absolute or relative to the Content directory */
    UPROPERTY(EditAnywhere, Category = "MyLCC")
    FString ScenePath = TEXT("Tower/Tower.lcc");

protected:
    virtual void BeginPlay() override;

private:
    void OnLoadCheck();

    UPROPERTY()
    TObjectPtr<class ALCCActor> LCCActor;

    FTimerHandle LoadCheckTimer;
};

// MyLCCLoader.cpp
#include "MyLCCLoader.h"
#include "LCCActor.h"
#include "LCCComponentBase.h"

void AMyLCCLoader::BeginPlay()
{
    Super::BeginPlay();

    LCCActor = GetWorld()->SpawnActor<ALCCActor>(
        ALCCActor::StaticClass(), GetActorTransform());
    if (!LCCActor)
    {
        return;
    }

    LCCActor->Load(ScenePath);

    GetWorld()->GetTimerManager().SetTimer(
        LoadCheckTimer, this, &AMyLCCLoader::OnLoadCheck, 0.2f, true);
}

void AMyLCCLoader::OnLoadCheck()
{
    ULCCComponentBase* Component = LCCActor ? LCCActor->GetLCCComponent() : nullptr;
    if (!Component || !Component->CheckIfLoaded())
    {
        return;
    }

    GetWorld()->GetTimerManager().ClearTimer(LoadCheckTimer);

    // metadata is ready, configure as needed
    Component->SetRenderMode(ERenderMode::Splatting);
    Component->SetSplatScale(0.9f);
    Component->SetMaxDistance(200);        // render up to 200 meters
    Component->SetMaxSplatNum(1500);       // at most 15 million splats per frame
    Component->SetLCCCollisionEnable(true);

    UE_LOG(LogTemp, Log, TEXT("LCC ready, splat number: %d"),
        Component->GetSplatNumber());
}

Ayrıca Bakın

• ULCCComponentBase: görüntüleme ve performans parametreleri burada bulunur
• SOG / SPZ / PLY Actor'ları: üç tek dosyalı biçim için özel Actor'lar
• ULCCUtilLibrary: yükleme öncesinde yol ve biçim doğrulaması