ULCCUtilLibrary : bibliothèque de fonctions utilitaires Blueprint

Bibliothèque de fonctions statiques, qui apporte la validation des chemins, la reconnaissance des formats, les opérations de presse-papiers, l'interrogation de version et d'autres capacités auxiliaires.

#include "Tools/LCCUtilLibrary.h"

Toutes les fonctions sont statiques : les appeler directement par le nom de la classe, sans instance :

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

Dans Blueprint, ces nodes n'ont pas de broche Target, il suffit de chercher le nom de la fonction.

Validation des chemins et des formats

Valider avant de charger les données permet de distinguer « le chemin est incorrect » de « les données elles-mêmes ont un problème », ce qui épargne beaucoup de temps de diagnostic.

CheckPathValid

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

Vérifie l'existence d'un fichier.

Renvoie un bool : true si le fichier existe.

Points d'utilisation :

• Ne teste que les fichiers ; passer un chemin de répertoire renvoie false. En interne, c'est un test d'existence de fichier.
• Ne vérifie que l'existence, pas si le contenu est une donnée LCC valide.
• Première vérification du processus de chargement, qui écarte d'emblée les fautes de frappe dans le chemin ou les fichiers déplacés.

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

Vérifie qu'il s'agit bien de données LCC1 valides.

Renvoie un bool : true si les données sont valides.

Points d'utilisation :

• LCC1 nécessite le fichier .lcc lui-même, ainsi que data.bin et index.bin dans le même répertoire ; il suffit qu'il en manque un pour que la fonction renvoie false. Le nom du fichier .lcc n'est pas fixé.
• Le OutWorkPath renvoyé est le répertoire obtenu en retirant le nom du fichier ; il sert à composer les chemins des autres fichiers du même répertoire.
• Les chemins relatifs sont pris en charge : lorsque le chemin fourni n'existe pas, Content/<chemin fourni> est automatiquement essayé, comme le fait 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);

Vérifie un chemin LCC2 et en extrait le répertoire de travail. Les paramètres ont le même sens que ci-dessus.

Points d'utilisation :

• LCC2 n'a pas besoin de data.bin ni de index.bin : cette fonction se contente donc de confirmer que le chemin existe, puis prend le répertoire parent comme OutWorkPath, sans vérifier l'intégrité du contenu. La véritable vérification du contenu a lieu à l'étape de chargement.
• Face à un chemin dont on ne sait pas s'il désigne du LCC1 ou du LCC2, regarder l'extension (.lcc ou .lcc2) est le plus direct. Il est aussi possible d'essayer les deux fonctions de validation :

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

Note : ne pas se fier à « CheckLCC2Valid renvoie true, donc c'est du LCC2 » pour faire la distinction. Sa vérification est très permissive, un chemin .lcc renvoie également true, ce qui ferait passer des données LCC1 pour du LCC2. Regarder d'abord l'extension.

DetermineFileFormat

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

Détermine le format d'un fichier.

Renvoie un EFileFormat. En pratique, la détermination se fait d'après l'extension et exige que le chemin existe :

Points d'utilisation :

• Cette fonction ne reconnaît pas .lcc2, .sog ni .spz : tous renvoient None. Pour couvrir ces formats, tester l'extension soi-même.
• Un chemin inexistant renvoie aussi None : un retour None a donc deux causes possibles, un format non pris en charge ou un fichier absent. Pour les distinguer, appeler d'abord CheckPathValid.

Sa couverture étant incomplète, il est plus sûr de regarder directement l'extension pour écrire un chargeur générique :

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

L'exemple complet figure dans Actors SOG / SPZ / PLY.

DetermineSourceType

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

Détermine le type de source des données.

Renvoie un ELCCSourceType : Local pour un fichier local, Http pour une adresse réseau.

Sert à séparer les traitements, par exemple lorsque des données distantes doivent d'abord être téléchargées ou passer par un chargement en flux.

DetermineCollisionType

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

Détermine le format des données de collision.

Renvoie un ECollisionType :

Points d'utilisation :

• Passer un répertoire, pas un chemin de fichier. Passer le chemin d'un fichier .lcc renvoie systématiquement None. Le répertoire peut être récupéré via le OutWorkPath de CheckLCCValid.
• Un retour None signifie que les données n'embarquent pas de collision ; activer bEnableCollision reste alors sans effet.
• Si les données sont déjà chargées, HaveValidCollisionData() sur le Component est plus commode, il évite de composer le répertoire soi-même.

Version et environnement

GetLCC4UnrealVersion

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

Renvoie la chaîne du numéro de version du plugin.

Usage : l'afficher dans un écran « À propos », l'écrire dans les journaux, la joindre à un signalement de problème.

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

GetProjectId

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

Renvoie l'identifiant du projet courant. Il doit être fourni lors d'une demande de licence ou du diagnostic d'un problème de licence.

GetLCCConfigPath

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

Renvoie le chemin du fichier de configuration du plugin.

GetLCC4UnrealRootPath

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

Renvoie le chemin du répertoire racine du plugin. L'utiliser pour composer un chemin lorsqu'il faut accéder aux ressources livrées avec le plugin.

GetLocale

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

Renvoie l'environnement linguistique courant, ELocale::EN_US ou ELocale::ZH_CN.

Ordre de détermination : l'entrée Language des réglages du projet est examinée d'abord ; si elle vaut Always English, EN_US est renvoyé directement ; sinon la langue courante de l'éditeur est prise en compte, et le chinois renvoie ZH_CN.

Usage : faire suivre à votre propre interface le réglage de langue du plugin, ou choisir le domaine du site officiel selon la région.

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

Identifiants de viewport

GetPlayerUniqueID

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

Récupère l'identifiant unique d'un player controller.

Renvoie un bool : true en cas de succès.

Points d'utilisation :

• L'utiliser comme clé lorsqu'il faut maintenir soi-même une table associant « un jeu de réglages par viewport ».
• Pour une configuration de rendu multi-viewport ordinaire, il suffit de passer le pointeur du controller à SetPlayerLoadMode et SetPlayerRenderMode, sans récupérer l'ID manuellement.

GetSceneCaptureUniqueID

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

Récupère l'identifiant unique d'un Component SceneCapture. Les paramètres et la valeur de retour ont le même sens que ci-dessus.

Presse-papiers

CopyToClipboard

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

Écrit une chaîne dans le presse-papiers du système.

Usage typique : un bouton « copier les informations de diagnostic », qui facilite le signalement de problèmes par les utilisateurs.

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

Lit le contenu du presse-papiers du système.

Usage typique : un bouton « coller le chemin depuis le presse-papiers », qui évite de saisir un long chemin à la main.

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

Blueprint sous forme de texte :

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

Texture

GetTextureFromBase64

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

Convertit des données d'image encodées en Base64 en une texture d'exécution.

Renvoie un UTexture2D* : nullptr en cas d'échec de conversion.

Usage : à partir d'une image Base64 obtenue d'une interface réseau ou d'un fichier de configuration, produire directement une texture pour l'interface, sans passer par une écriture sur disque puis un import.

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

Analyse des métadonnées SOG

Ces fonctions servent à lire les métadonnées d'un fichier .sog sans charger les données de rendu, ce qui convient pour un aperçu des données ou l'affichage d'une liste.

ParseSogMetaFromFile

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

Analyse les métadonnées SOG depuis un fichier.

Renvoie un bool : true si l'analyse réussit.

Points d'utilisation :

• Seules les métadonnées sont lues, les données de splat ne sont pas chargées : le coût est très faible.
• Cela permet de connaître avant le chargement le nombre de points et la présence d'harmoniques sphériques d'ordre élevé, afin de décider s'il faut abaisser la configuration.

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 settings ahead of time 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);

Analyse les métadonnées SOG depuis un tableau d'octets en mémoire.

Utiliser cette variante lorsque les données viennent d'un téléchargement réseau et n'ont pas encore été écrites sur disque.

La description des champs de FLCC2SogMeta figure dans Structs.

C++ uniquement

Les fonctions suivantes ne portent pas de marqueur UFUNCTION et ne peuvent être appelées que depuis C++.

ConvertStrToMetaInfo

static FLCCMetaInfo ConvertStrToMetaInfo(const FString& JsonStr);

Convertit le contenu JSON d'un fichier .lcc en une structure FLCCMetaInfo.

Sert à lire et analyser soi-même un fichier de métadonnées, par exemple pour parcourir en lot des jeux de données dans un outil de gestion.

ConvertStrToLCC2MetaInfo

static FLCC2MetaInfo ConvertStrToLCC2MetaInfo(const FString& JsonStr);

Convertit le contenu JSON d'un fichier .lcc2 en une structure FLCC2MetaInfo.

SelectFile

static FString SelectFile(ELCCVersion LCCVersion);

Ouvre une boîte de dialogue de sélection de fichier, en filtrant les extensions selon la version. Renvoie le chemin sélectionné, ou une chaîne vide en cas d'annulation.

Disponible dans l'éditeur uniquement. Le SelectFile() des Actors appelle cette fonction en interne.

Note : ULCCUtilLibrary contient encore plusieurs fonctions statiques réservées à l'usage interne du plugin (calcul du frustum, implémentation interne de l'analyse SOG, vérification des extensions dans les sous-répertoires, etc.). Elles sont visibles à la compilation mais ne font pas partie de l'API publique et leur comportement peut changer d'une version à l'autre : ne pas s'y fier.

Exemple complet : valider avant de charger

#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 from the 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. check data integrity and get the work path 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. also confirm whether collision data exists; note this takes the work path, not the file path
    const ECollisionType CollisionType =
        ULCCUtilLibrary::DetermineCollisionType(WorkPath);
    UE_LOG(LogTemp, Log, TEXT("Collision type: %d"),
        static_cast<int32>(CollisionType));

    return true;
}

Voir aussi

• Actors SOG / SPZ / PLY : exemple complet de répartition par format
• Enums : description des valeurs de EFileFormat, ECollisionType, ELocale et autres
• Structs : description des champs de FLCCMetaInfo et FLCC2SogMeta