ULCCUtilLibrary: Blueprint Yardımcı Fonksiyon Kütüphanesi

Yol doğrulama, biçim algılama, pano işlemleri, sürüm sorgulama ve diğer yardımcı işlevleri sağlayan statik yardımcı fonksiyon kütüphanesi.

#include "Tools/LCCUtilLibrary.h"

Tüm fonksiyonlar statiktir ve örnek oluşturmadan sınıf adı üzerinden çağrılır:

const bool bValid = ULCCUtilLibrary::CheckPathValid(Path);

Bu düğümler Blueprint'te Target pinine ihtiyaç duymaz; fonksiyon adını doğrudan arayın.

Yol ve Biçim Doğrulama

Yüklemeden önce doğrulama yapmak, "yol yanlış" durumunu "verinin kendisinde sorun var" durumundan ayırır ve inceleme süresinden büyük ölçüde tasarruf sağlar.

CheckPathValid

UFUNCTION(BlueprintCallable, Category = "XGrids|Util")
static bool CheckPathValid(FString Path);

Bir dosyanın var olup olmadığını denetler.

bool döndürür: dosya varsa true.

Kullanım notları:

• Yalnızca dosyaları denetler; bir dizin yolu verilirse false döndürür. Dahili olarak dosya varlık denetimi kullanır.
• Yalnızca varlığı denetler, içeriğin geçerli LCC verisi olup olmadığına bakmaz.
• Yükleme sürecinin ilk denetimidir; hatalı yazılmış bir yolu veya taşınmış bir dosyayı eler.

if (!ULCCUtilLibrary::CheckPathValid(Path))
{
    UE_LOG(LogTemp, Error, TEXT("Path does not exist: %s"), *Path);
    return;
}

CheckLCCValid

UFUNCTION(BlueprintCallable, Category = "XGrids|Util")
static bool CheckLCCValid(FString Path, FString& OutWorkPath);

Verinin geçerli LCC1 verisi olup olmadığını denetler.

bool döndürür: geçerliyse true.

Kullanım notları:

• LCC1, .lcc dosyasının kendisine ek olarak aynı dizinde data.bin ve index.bin dosyalarını gerektirir; biri eksikse false döndürür. .lcc dosyasının adı sabit değildir.
• OutWorkPath çıktısı, dosya adı çıkarılmış dizindir; aynı dizindeki diğer dosyalarla yol oluşturmak gerektiğinde işe yarar.
• Göreli yollar desteklenir: verilen yol mevcut değilse Content/<given path> bir kez daha denenir; bu, Load() kuralıyla aynıdır.

FString WorkPath;
if (ULCCUtilLibrary::CheckLCCValid(Path, WorkPath))
{
    UE_LOG(LogTemp, Log, TEXT("Valid LCC1 data, work path: %s"), *WorkPath);
}

CheckLCC2Valid

UFUNCTION(BlueprintCallable, Category = "XGrids|Util")
static bool CheckLCC2Valid(FString Path, FString& OutWorkPath);

Bir LCC2 yolunu denetler ve çalışma dizinini çıkarır. Parametrelerin anlamı yukarıdakilerle aynıdır.

Kullanım notları:

• LCC2, data.bin ve index.bin dosyalarına ihtiyaç duymaz. Bu nedenle bu fonksiyon yalnızca yolun var olduğunu onaylar ve üst dizini OutWorkPath olarak alır. Veri içeriğinin bütünlüğünü doğrulamaz. Asıl içerik doğrulaması yükleme sırasında yapılır.
• Bir yolun LCC1 mi LCC2 mi olduğu belirsizse en doğrudan yöntem uzantıyı (.lcc veya .lcc2) kontrol etmektir. Her iki doğrulama fonksiyonunu denemek de işe yarar:

FString WorkPath;

if (Path.EndsWith(TEXT(".lcc2"), ESearchCase::IgnoreCase))
{
    if (ULCCUtilLibrary::CheckLCC2Valid(Path, WorkPath))
    {
        // use ALCC2Actor
    }
}
else if (Path.EndsWith(TEXT(".lcc"), ESearchCase::IgnoreCase))
{
    if (ULCCUtilLibrary::CheckLCCValid(Path, WorkPath))
    {
        // use ALCCActor
    }
}
else
{
    UE_LOG(LogTemp, Error, TEXT("Not an LCC dataset: %s"), *Path);
}

Not: "CheckLCC2Valid true döndürdü" sonucunu LCC2 kanıtı olarak görmeyin. Doğrulaması çok gevşektir ve bir .lcc yolu için de true döndürür. Bu durumda LCC1 verisi LCC2 sanılır. Önce uzantıyı kontrol edin.

DetermineFileFormat

UFUNCTION(BlueprintCallable, Category = "XGrids|Util")
static EFileFormat DetermineFileFormat(const FString& Path);

Dosya biçimini belirler.

EFileFormat döndürür. Aslında uzantıya göre karar verir ve yolun var olmasını gerektirir:

Kullanım notları:

• Bu fonksiyon .lcc2, .sog ve .spz biçimlerini tanımaz; hepsi için None döndürür. Bu biçimlerin de kapsanması gerekiyorsa uzantıyı elle kontrol edin.
• Var olmayan bir yol da None döndürür. Bu nedenle None iki anlama gelebilir: biçim desteklenmiyordur ya da dosya yoktur. Bunları ayırmak için önce CheckPathValid fonksiyonunu çağırın.

Kapsam eksik olduğundan, genel amaçlı bir yükleyici için uzantıyı doğrudan kontrol etmek daha sağlam bir yaklaşımdır:

UClass* PickActorClass(const FString& Path)
{
    const FString Ext = FPaths::GetExtension(Path).ToLower();

    if (Ext == TEXT("lcc"))  return ALCCActor::StaticClass();
    if (Ext == TEXT("lcc2")) return ALCC2Actor::StaticClass();
    if (Ext == TEXT("sog"))  return ASogActor::StaticClass();
    if (Ext == TEXT("spz"))  return ASpzActor::StaticClass();
    if (Ext == TEXT("ply"))  return APlyActor::StaticClass();

    return nullptr;
}

Tam örnek için SOG / SPZ / PLY Actor Nesneleri bölümüne bakın.

DetermineSourceType

UFUNCTION(BlueprintCallable, Category = "XGrids|Util")
static ELCCSourceType DetermineSourceType(const FString& Path);

Veri kaynağı türünü belirler.

ELCCSourceType döndürür: yerel dosya için Local, ağ adresi için Http.

İşleme mantığını dallandırmak için kullanın; örneğin ağ verisinin önce indirilmesi veya akış olarak alınması gerektiğinde.

DetermineCollisionType

UFUNCTION(BlueprintCallable, Category = "XGrids|Util")
static ECollisionType DetermineCollisionType(const FString& Path);

Çarpışma verisi biçimini belirler.

ECollisionType döndürür:

Kullanım notları:

• Dosya yolu değil, dizin verin. Bir .lcc dosyasının yolunu vermek her zaman None döndürür. Dizine, CheckLCCValid fonksiyonunun OutWorkPath değerinden ulaşabilirsiniz.
• None, verinin çarpışma içermediği anlamına gelir. Bu durumda bEnableCollision seçeneğini etkinleştirmek bir etki yapmaz.
• Veri yüklendikten sonra Component üzerindeki HaveValidCollisionData() daha kolaydır ve dizini elle oluşturmaktan kurtarır.

Sürüm ve Ortam

GetLCC4UnrealVersion

UFUNCTION(BlueprintCallable, Category = "XGrids|Util")
static FString GetLCC4UnrealVersion();

Eklenti sürüm dizesini döndürür.

Kullanım alanları: hakkında ekranında göstermek, günlüğe yazmak, hata raporuna eklemek.

UE_LOG(LogTemp, Log, TEXT("LCC4Unreal version: %s"),
    *ULCCUtilLibrary::GetLCC4UnrealVersion());

GetProjectId

UFUNCTION(BlueprintCallable, Category = "XGrids|Util")
static FString GetProjectId();

Geçerli projenin tanımlayıcısını döndürür. Lisans talep ederken veya lisans sorunlarını incelerken gereklidir.

GetLCCConfigPath

UFUNCTION(BlueprintCallable, Category = "XGrids|Util")
static FString GetLCCConfigPath();

Eklenti yapılandırma dosyasının yolunu döndürür.

GetLCC4UnrealRootPath

UFUNCTION(BlueprintCallable, Category = "XGrids|Util")
static FString GetLCC4UnrealRootPath();

Eklentinin kök dizin yolunu döndürür. Eklentiyle birlikte gelen kaynaklara erişmeniz gerektiğinde yolları oluşturmak için kullanın.

GetLocale

UFUNCTION(BlueprintCallable, Category = "XGrids|Util")
static ELocale GetLocale();

Geçerli yerel ayarı döndürür: ELocale::EN_US veya ELocale::ZH_CN.

Karar sırası: önce proje ayarlarındaki Language öğesine bakılır; değeri Always English ise doğrudan EN_US döndürülür. Aksi halde geçerli editör dili belirler ve Çince ise ZH_CN döndürülür.

Kullanım alanları: kendi arayüz metinlerinizi eklentinin dil ayarına uydurmak veya web sitesi alan adını bölgeye göre seçmek.

const FString DownloadUrl = (ULCCUtilLibrary::GetLocale() == ELocale::ZH_CN)
    ? TEXT("https://xgrids.cn/support/download")
    : TEXT("https://xgrids.com/intl/support/download");

Görünüm Alanı Tanımlayıcıları

GetPlayerUniqueID

UFUNCTION(BlueprintCallable, Category = "XGrids|Util")
static bool GetPlayerUniqueID(class APlayerController* PlayerController, int32& OutUniqueID);

Bir player controller için benzersiz tanımlayıcıyı alır.

bool döndürür: başarılı olursa true.

Kullanım notları:

• "Görünüm alanı başına bir yapılandırma" eşleme tablosunu kendiniz yönetirken anahtar olarak kullanın.
• Olağan çoklu görünüm alanı görüntüleme yapılandırması için yalnızca SetPlayerLoadMode ve SetPlayerRenderMode fonksiyonlarına controller işaretçisini vermek yeterlidir; kimliği elle almanız gerekmez.

GetSceneCaptureUniqueID

UFUNCTION(BlueprintCallable, Category = "XGrids|Util")
static bool GetSceneCaptureUniqueID(class USceneCaptureComponent2D* SceneCaptureComponent2D,
                                    int32& OutUniqueID);

Bir SceneCapture bileşeni için benzersiz tanımlayıcıyı alır. Parametreler ve dönüş değeri yukarıdakiyle aynı anlama gelir.

Pano

CopyToClipboard

UFUNCTION(BlueprintCallable, Category = "XGrids|Util")
static void CopyToClipboard(FString CopyString);

Bir dizeyi sistem panosuna yazar.

Tipik kullanım: kullanıcıların sorunları bildirmesini kolaylaştıran bir "tanılama bilgisini kopyala" düğmesi.

void AMyDebugUI::CopyDiagnostics()
{
    const FString Info = FString::Printf(
        TEXT("Plugin: %s\nProject: %s\nSplats: %d"),
        *ULCCUtilLibrary::GetLCC4UnrealVersion(),
        *ULCCUtilLibrary::GetProjectId(),
        Component->GetSplatNumber());

    ULCCUtilLibrary::CopyToClipboard(Info);
}

GetClipboardString

UFUNCTION(BlueprintCallable, Category = "XGrids|Util")
static FString GetClipboardString();

Sistem panosunun içeriğini okur.

Tipik kullanım: uzun bir yolu yazma zahmetinden kurtaran bir "yolu panodan yapıştır" düğmesi.

void AMyLoader::LoadFromClipboard()
{
    const FString Path = ULCCUtilLibrary::GetClipboardString();
    if (ULCCUtilLibrary::CheckPathValid(Path))
    {
        LCCActor->Load(Path);
    }
}

Metin olarak Blueprint:

[Button Clicked: PasteAndLoad]
        │
        ▼
[Get Clipboard String]
        │ Return Value ──┐
        ▼                │
[Check Path Valid] ◀─────┘
        Path = (Return Value)
        │ Return Value ──┐
        ▼                │
[Branch] ◀───────────────┘
        │ True
        ▼
[Load]
        Target = LCCActor
        String = (clipboard content)

Doku

GetTextureFromBase64

UFUNCTION(BlueprintCallable, Category = "XGrids|Util")
static UTexture2D* GetTextureFromBase64(const FString& Base64String);

Base64 kodlu görüntü verisini çalışma zamanı dokusuna dönüştürür.

UTexture2D* döndürür: dönüştürme başarısız olursa nullptr.

Kullanım: bir ağ arayüzünden veya yapılandırma dosyasından alınan Base64 görüntüsünü diske yazıp içe aktarmadan doğrudan arayüz için dokuya dönüştürmek.

UTexture2D* Texture = ULCCUtilLibrary::GetTextureFromBase64(Base64Data);
if (Texture)
{
    MyImageWidget->SetBrushFromTexture(Texture);
}

SOG Metaverisi Ayrıştırma

Bu fonksiyonlar, görüntüleme verisini yüklemeden bir .sog dosyasının metaverisini okur. Veri önizlemeleri ve liste sayfaları için uygundur.

ParseSogMetaFromFile

UFUNCTION(BlueprintCallable, Category = "XGrids|Util")
static bool ParseSogMetaFromFile(const FString& FilePath, FLCC2SogMeta& OutMeta);

SOG metaverisini bir dosyadan ayrıştırır.

bool döndürür: ayrıştırma başarılı olursa true.

Kullanım notları:

• Yalnızca metaveriyi okur, splat verisini yüklemez; maliyeti çok düşüktür.
• Yüklemeden önce nokta sayısını ve yüksek dereceli küresel harmoniklerin bulunup bulunmadığını gösterir. Bu, düşürülmüş bir yapılandırmanın gerekip gerekmediğine karar vermeye yardımcı olur.

FLCC2SogMeta Meta;
if (ULCCUtilLibrary::ParseSogMetaFromFile(TEXT("D:/Data/scene.sog"), Meta))
{
    UE_LOG(LogTemp, Log, TEXT("Splat count: %d, has high-order SH: %s"),
        Meta.Count, Meta.HasShN() ? TEXT("yes") : TEXT("no"));

    // lower the configuration in advance when the point count is too large
    if (Meta.Count > 5000000)
    {
        Component->SetMaxSplatNum(1000);
    }
}

ParseSogMetaFromData

UFUNCTION(BlueprintCallable, Category = "XGrids|Util")
static bool ParseSogMetaFromData(const TArray<uint8>& Data, FLCC2SogMeta& OutMeta);

SOG metaverisini bellekteki bir bayt dizisinden ayrıştırır.

Veri bir ağ indirmesinden geldiyse ve henüz diske yazılmadıysa bu sürümü kullanın.

FLCC2SogMeta alanları için Yapılar bölümüne bakın.

Yalnızca C++

Aşağıdaki fonksiyonlarda UFUNCTION işaretlemesi yoktur ve yalnızca C++ üzerinden çağrılabilir.

ConvertStrToMetaInfo

static FLCCMetaInfo ConvertStrToMetaInfo(const FString& JsonStr);

Bir .lcc dosyasının JSON içeriğini FLCCMetaInfo struct'ına dönüştürür.

Meta veri dosyalarını kendiniz okumak ve ayrıştırmak için kullanın; örneğin bir veri yönetimi aracı geliştirirken veri setlerini toplu olarak işlemek için.

ConvertStrToLCC2MetaInfo

static FLCC2MetaInfo ConvertStrToLCC2MetaInfo(const FString& JsonStr);

Bir .lcc2 dosyasının JSON içeriğini FLCC2MetaInfo struct'ına dönüştürür.

SelectFile

static FString SelectFile(ELCCVersion LCCVersion);

Dosya iletişim kutusunu, uzantı sürüme göre filtrelenmiş şekilde açar. Seçilen yolu döndürür; iptal edilirse boş bir dize döndürür.

Yalnızca Editor için. Actor üzerindeki SelectFile() bunu dahili olarak çağırır.

Not: ULCCUtilLibrary ayrıca yalnızca eklenti içi kullanım için tasarlanmış birçok statik fonksiyon içerir (frustum hesaplama, SOG ayrıştırmanın dahili uygulaması, alt dizin uzantı kontrolleri ve diğerleri). Bunlar derleyici tarafından görülebilir ancak herkese açık API'nin parçası değildir, davranışları sürümler arasında değişebilir ve bunlara güvenilmemelidir.

Tam Örnek: Yüklemeden Önce Doğrulama

#include "Tools/LCCUtilLibrary.h"
#include "LCCActor.h"
#include "LCC2Actor.h"

bool AMyLoader::ValidateAndLoad(const FString& Path)
{
    // 1. path existence
    if (!ULCCUtilLibrary::CheckPathValid(Path))
    {
        UE_LOG(LogTemp, Error, TEXT("Path does not exist: %s"), *Path);
        return false;
    }

    // 2. tell the format apart by extension
    const FString Ext = FPaths::GetExtension(Path).ToLower();
    const bool bIsLCC1 = (Ext == TEXT("lcc"));
    const bool bIsLCC2 = (Ext == TEXT("lcc2"));

    if (!bIsLCC1 && !bIsLCC2)
    {
        // for dispatching .sog / .spz / .ply see the SOG / SPZ / PLY Actors page
        UE_LOG(LogTemp, Error, TEXT("Not an LCC dataset: %s"), *Path);
        return false;
    }

    // 3. validate data integrity and take the work directory at the same time
    FString WorkPath;
    const bool bValid = bIsLCC2
        ? ULCCUtilLibrary::CheckLCC2Valid(Path, WorkPath)
        : ULCCUtilLibrary::CheckLCCValid(Path, WorkPath);

    if (!bValid)
    {
        UE_LOG(LogTemp, Error, TEXT("Incomplete LCC dataset: %s"), *Path);
        return false;
    }

    // 4. spawn the matching Actor and load
    UClass* ActorClass = bIsLCC2 ? ALCC2Actor::StaticClass() : ALCCActor::StaticClass();
    ALCCActorBase* Actor = GetWorld()->SpawnActor<ALCCActorBase>(ActorClass);
    if (!Actor)
    {
        return false;
    }
    Actor->Load(Path);

    // 5. confirm whether collision data exists while at it. Note the work directory is passed, not the file path
    const ECollisionType CollisionType =
        ULCCUtilLibrary::DetermineCollisionType(WorkPath);
    UE_LOG(LogTemp, Log, TEXT("Collision type: %d"),
        static_cast<int32>(CollisionType));

    return true;
}

Ayrıca Bakın

• SOG / SPZ / PLY Actor'ları: biçime göre yönlendirmenin tam örneği
• Enum'lar: EFileFormat, ECollisionType, ELocale ve diğerlerinin değerleri
• Struct'lar: FLCCMetaInfo ve FLCC2SogMeta alanları