ULCCUtilLibrary: Bibliothek der Blueprint-Hilfsfunktionen

Bibliothek statischer Hilfsfunktionen, die Pfadprüfung, Formaterkennung, Operationen auf der Zwischenablage, Versionsabfragen und weitere Helfer bereitstellt.

#include "Tools/LCCUtilLibrary.h"

Alles sind statische Funktionen, die ohne Instanz über den Klassennamen aufgerufen werden:

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

Diese Nodes brauchen in Blueprint keinen Target-Pin; einfach nach dem Funktionsnamen suchen.

Prüfung von Pfad und Format

Ein Prüfen vor dem Laden trennt „der Pfad ist falsch“ von „die Daten selbst haben ein Problem“ und spart viel Zeit bei der Untersuchung.

CheckPathValid

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

Prüft, ob eine Datei existiert.

Gibt bool zurück: true, wenn die Datei existiert.

Hinweise zur Verwendung:

• Sie prüft nur Dateien; die Übergabe eines Verzeichnispfads gibt false zurück. Intern wird eine Existenzprüfung für Dateien genutzt.
• Sie prüft nur die Existenz, nicht ob der Inhalt gültige LCC-Daten ist.
• Sie ist die erste Prüfung des Ladevorgangs und schließt einen falsch getippten Pfad oder eine verschobene Datei aus.

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);

Prüft, ob die Daten gültige LCC1-Daten sind.

Gibt bool zurück: true, wenn sie gültig sind.

Hinweise zur Verwendung:

• LCC1 benötigt die .lcc-Datei selbst sowie data.bin und index.bin im gleichen Verzeichnis; fehlt eines davon, wird false zurückgegeben. Der Name der .lcc-Datei ist nicht festgelegt.
• Das ausgegebene OutWorkPath ist das Verzeichnis ohne den Dateinamen, nützlich, wenn weitere Dateien im gleichen Verzeichnis zusammengesetzt werden müssen.
• Relative Pfade werden unterstützt: Existiert der übergebene Pfad nicht, wird zusätzlich Content/<übergebener Pfad> versucht, passend zur Regel von Load().

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);

Prüft einen LCC2-Pfad und entnimmt das Arbeitsverzeichnis. Die Parameter bedeuten dasselbe wie oben.

Hinweise zur Verwendung:

• LCC2 benötigt data.bin und index.bin nicht, diese Funktion bestätigt daher nur, dass der Pfad existiert, und nimmt dann das übergeordnete Verzeichnis als OutWorkPath; die Vollständigkeit des Dateninhalts wird nicht geprüft. Die eigentliche Inhaltsprüfung geschieht beim Laden.
• Ist unklar, ob ein Pfad LCC1 oder LCC2 ist, ist das Prüfen der Erweiterung (.lcc oder .lcc2) der unmittelbarste Weg. Beide Prüffunktionen zu versuchen funktioniert ebenfalls:

FString WorkPath;

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

Hinweis: „CheckLCC2Valid hat true zurückgegeben“ nicht als Beweis für LCC2 nehmen. Seine Prüfung ist sehr lose und ein .lcc-Pfad gibt ebenfalls true zurück, was LCC1-Daten für LCC2 halten würde. Zuerst die Erweiterung prüfen.

DetermineFileFormat

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

Bestimmt das Dateiformat.

Gibt EFileFormat zurück. Tatsächlich entscheidet sie anhand der Erweiterung und erfordert, dass der Pfad existiert:

Hinweise zur Verwendung:

• Diese Funktion erkennt .lcc2, .sog und .spz nicht; alle geben None zurück. Die Erweiterung von Hand prüfen, wenn diese Formate abgedeckt werden müssen.
• Ein Pfad, der nicht existiert, gibt ebenfalls None zurück, None hat daher zwei mögliche Bedeutungen: das Format wird nicht unterstützt, oder die Datei ist einfach nicht vorhanden. Um sie zu trennen, zuerst CheckPathValid aufrufen.

Da die Abdeckung unvollständig ist, ist das unmittelbare Prüfen der Erweiterung für einen allgemeinen Loader der robustere Weg:

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;
}

Zum vollständigen Beispiel siehe SOG- / SPZ- / PLY-Actors.

DetermineSourceType

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

Bestimmt den Typ der Datenquelle.

Gibt ELCCSourceType zurück: Local für eine lokale Datei, Http für eine Netzwerkadresse.

Damit die Behandlungslogik verzweigen, etwa wenn Netzwerkdaten zuerst heruntergeladen oder gestreamt werden müssen.

DetermineCollisionType

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

Bestimmt das Format der Kollisionsdaten.

Gibt ECollisionType zurück:

Hinweise zur Verwendung:

• Ein Verzeichnis übergeben, keinen Dateipfad. Die Übergabe des Pfads einer .lcc-Datei gibt immer None zurück. Das Verzeichnis liefert OutWorkPath von CheckLCCValid.
• None bedeutet, dass die Daten keine Kollision mitbringen; das Aktivieren von bEnableCollision hat dann keine Wirkung.
• Sind die Daten geladen, ist HaveValidCollisionData() an der Component einfacher und erspart das Zusammensetzen des Verzeichnisses von Hand.

Version und Umgebung

GetLCC4UnrealVersion

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

Gibt die Versionszeichenkette des Plugins zurück.

Verwendungen: Anzeige in einem Info-Bildschirm, Schreiben in ein Log, Beifügen zu einer Problemmeldung.

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

GetProjectId

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

Gibt den Bezeichner des aktuellen Projekts zurück. Erforderlich beim Anfordern einer Lizenz oder beim Untersuchen eines Lizenzproblems.

GetLCCConfigPath

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

Gibt den Pfad der Konfigurationsdatei des Plugins zurück.

GetLCC4UnrealRootPath

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

Gibt den Pfad des Wurzelverzeichnisses des Plugins zurück. Damit Pfade zusammensetzen, wenn auf die mit dem Plugin ausgelieferten Ressourcen zugegriffen werden muss.

GetLocale

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

Gibt die aktuelle Locale zurück, ELocale::EN_US oder ELocale::ZH_CN.

Reihenfolge der Entscheidung: Der Eintrag Language in den Projekteinstellungen kommt zuerst, und bei Always English wird unmittelbar EN_US zurückgegeben; andernfalls entscheidet die aktuelle Editorsprache, und Chinesisch gibt ZH_CN zurück.

Verwendungen: eigene UI-Texte der Spracheinstellung des Plugins folgen lassen oder die Domain der Website nach Region wählen.

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

Bezeichner der Viewports

GetPlayerUniqueID

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

Holt den eindeutigen Bezeichner eines Player Controllers.

Gibt bool zurück: true bei Erfolg.

Hinweise zur Verwendung:

• Ihn als Schlüssel nutzen, wenn eine eigene Zuordnungstabelle „eine Konfiguration je Viewport“ gepflegt wird.
• Eine reguläre Render-Konfiguration für mehrere Viewports braucht nur den an SetPlayerLoadMode und SetPlayerRenderMode übergebenen Controller-Zeiger, ohne die ID von Hand zu holen.

GetSceneCaptureUniqueID

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

Holt den eindeutigen Bezeichner einer SceneCapture-Component. Parameter und Rückgabewert bedeuten dasselbe wie oben.

Zwischenablage

CopyToClipboard

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

Schreibt eine Zeichenkette in die Zwischenablage des Systems.

Typische Verwendung: eine Schaltfläche „Diagnoseinformationen kopieren“, die es Nutzern erleichtert, Probleme zu melden.

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();

Liest den Inhalt der Zwischenablage des Systems.

Typische Verwendung: eine Schaltfläche „den Pfad aus der Zwischenablage einfügen“, die das Eintippen eines langen Pfads erspart.

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

Blueprint als Text:

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

Textur

GetTextureFromBase64

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

Wandelt Base64-kodierte Bilddaten in eine Laufzeittextur um.

Gibt UTexture2D* zurück: nullptr, wenn die Umwandlung fehlschlägt.

Verwendung: ein über eine Netzwerkschnittstelle oder aus einer Konfigurationsdatei erhaltenes Base64-Bild unmittelbar in eine Textur für die UI verwandeln, ohne es auf die Festplatte zu schreiben und zu importieren.

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

Auswerten der SOG-Metadaten

Diese Funktionen lesen die Metadaten einer .sog-Datei, ohne die Render-Daten zu laden, was zu Datenvorschauen und Listenseiten passt.

ParseSogMetaFromFile

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

Wertet SOG-Metadaten aus einer Datei aus.

Gibt bool zurück: true, wenn das Auswerten erfolgreich ist.

Hinweise zur Verwendung:

• Sie liest nur Metadaten und lädt keine Splat-Daten, zu sehr geringen Kosten.
• Sie zeigt die Punktzahl und ob Kugelflächenfunktionen höherer Ordnung vorhanden sind, bereits vor dem Laden, was bei der Entscheidung hilft, ob eine herabgestufte Konfiguration nötig ist.

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"));

    // die Konfiguration im Vorhinein senken, wenn die Punktzahl zu groß ist
    if (Meta.Count > 5000000)
    {
        Component->SetMaxSplatNum(1000);
    }
}

ParseSogMetaFromData

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

Wertet SOG-Metadaten aus einem Byte-Array im Arbeitsspeicher aus.

Diese Variante nutzen, wenn die Daten aus einem Netzwerk-Download stammen und noch nicht auf die Festplatte geschrieben wurden.

Zu den Feldern von FLCC2SogMeta siehe Structs.

Nur C++

Die folgenden Funktionen haben keine UFUNCTION-Auszeichnung und lassen sich nur aus C++ aufrufen.

ConvertStrToMetaInfo

static FLCCMetaInfo ConvertStrToMetaInfo(const FString& JsonStr);

Wandelt den JSON-Inhalt einer .lcc-Datei in ein FLCCMetaInfo-Struct um.

Damit Metadatendateien selbst lesen und auswerten, etwa beim Bauen eines Werkzeugs zur Datenverwaltung Datensätze in großer Zahl durchsuchen.

ConvertStrToLCC2MetaInfo

static FLCC2MetaInfo ConvertStrToLCC2MetaInfo(const FString& JsonStr);

Wandelt den JSON-Inhalt einer .lcc2-Datei in ein FLCC2MetaInfo-Struct um.

SelectFile

static FString SelectFile(ELCCVersion LCCVersion);

Öffnet den Dateidialog mit der nach Version gefilterten Erweiterung. Gibt den gewählten Pfad zurück, bei Abbruch eine leere Zeichenkette.

Nur im Editor. SelectFile() am Actor ruft sie intern auf.

Hinweis: ULCCUtilLibrary enthält außerdem eine Reihe statischer Funktionen, die nur für die interne Verwendung im Plugin gedacht sind (Frustum-Berechnung, die interne Umsetzung des SOG-Auswertens, Prüfungen der Erweiterungen in Unterverzeichnissen und weitere). Sie sind für den Compiler sichtbar, gehören aber nicht zur öffentlichen API, ihr Verhalten kann sich zwischen Versionen ändern, und man sollte sich nicht auf sie stützen.

Vollständiges Beispiel: vor dem Laden prüfen

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

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

    // 2. das Format anhand der Erweiterung unterscheiden
    const FString Ext = FPaths::GetExtension(Path).ToLower();
    const bool bIsLCC1 = (Ext == TEXT("lcc"));
    const bool bIsLCC2 = (Ext == TEXT("lcc2"));

    if (!bIsLCC1 && !bIsLCC2)
    {
        // zum Verteilen von .sog / .spz / .ply siehe die Seite der SOG- / SPZ- / PLY-Actors
        UE_LOG(LogTemp, Error, TEXT("Not an LCC dataset: %s"), *Path);
        return false;
    }

    // 3. die Vollständigkeit der Daten prüfen und gleichzeitig das Arbeitsverzeichnis entnehmen
    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. den passenden Actor erzeugen und laden
    UClass* ActorClass = bIsLCC2 ? ALCC2Actor::StaticClass() : ALCCActor::StaticClass();
    ALCCActorBase* Actor = GetWorld()->SpawnActor<ALCCActorBase>(ActorClass);
    if (!Actor)
    {
        return false;
    }
    Actor->Load(Path);

    // 5. dabei gleich bestätigen, ob Kollisionsdaten vorhanden sind. Beachten: das Arbeitsverzeichnis wird übergeben, nicht der Dateipfad
    const ECollisionType CollisionType =
        ULCCUtilLibrary::DetermineCollisionType(WorkPath);
    UE_LOG(LogTemp, Log, TEXT("Collision type: %d"),
        static_cast<int32>(CollisionType));

    return true;
}

Siehe auch

• SOG- / SPZ- / PLY-Actors: das vollständige Beispiel für das Verteilen nach Format
• Enums: Werte von EFileFormat, ECollisionType, ELocale und weiteren
• Structs: Felder von FLCCMetaInfo und FLCC2SogMeta