ULCCUtilLibrary: biblioteca de funciones de utilidad de Blueprint

Biblioteca estática de funciones de utilidad que proporciona validación de rutas, detección de formatos, operaciones de portapapeles, consultas de versión y otras ayudas.

#include "Tools/LCCUtilLibrary.h"

Todo son funciones estáticas, que se llaman mediante el nombre de la clase sin ninguna instancia:

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

Estos nodos no necesitan ningún pin Target en Blueprint; basta con buscar el nombre de la función.

Validación de rutas y formatos

Validar antes de cargar separa «la ruta es incorrecta» de «los propios datos tienen un problema» y ahorra mucho tiempo de investigación.

CheckPathValid

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

Comprueba si un archivo existe.

Devuelve bool: true cuando el archivo existe.

Notas de uso:

• Solo comprueba archivos, y pasar la ruta de un directorio devuelve false. Internamente usa una comprobación de existencia de archivo.
• Solo comprueba la existencia, no si el contenido son datos LCC válidos.
• Es la primera comprobación del proceso de carga, y descarta una ruta mal escrita o un archivo movido.

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

Comprueba si los datos son datos LCC1 válidos.

Devuelve bool: true cuando son válidos.

Notas de uso:

• LCC1 necesita el propio archivo .lcc más data.bin e index.bin en el mismo directorio, y si falta uno devuelve false. El nombre del archivo .lcc no es fijo.
• El OutWorkPath de salida es el directorio sin el nombre del archivo, útil cuando hay que componer otros archivos del mismo directorio.
• Se admiten rutas relativas: cuando la ruta que se pasa no existe, se prueba una vez más con Content/<ruta indicada>, siguiendo la regla de 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);

Comprueba una ruta LCC2 y extrae el directorio de trabajo. Los parámetros significan lo mismo que arriba.

Notas de uso:

• LCC2 no necesita data.bin ni index.bin, así que esta función solo confirma que la ruta existe y toma después el directorio padre como OutWorkPath; no valida la integridad del contenido de los datos. La validación real del contenido ocurre durante la carga.
• Cuando no está claro si una ruta es LCC1 o LCC2, comprobar la extensión (.lcc o .lcc2) es el enfoque más directo. Probar ambas funciones de validación también funciona:

FString WorkPath;

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

Nota: no tratar «CheckLCC2Valid devolvió true» como prueba de que se trata de LCC2. Su validación es muy laxa y una ruta .lcc también devuelve true, lo que confundiría datos LCC1 con LCC2. Comprobar primero la extensión.

DetermineFileFormat

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

Determina el formato del archivo.

Devuelve EFileFormat. En realidad decide por la extensión y requiere que la ruta exista:

Notas de uso:

• Esta función no reconoce .lcc2, .sog ni .spz; todos ellos devuelven None. Comprobar la extensión manualmente cuando haya que cubrir esos formatos.
• Una ruta que no existe también devuelve None, así que None tiene dos significados posibles: el formato no es compatible, o el archivo simplemente no está ahí. Para separarlos, llamar primero a CheckPathValid.

Como la cobertura es incompleta, comprobar la extensión directamente es un enfoque más sólido para un cargador general:

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

Para el ejemplo completo, consultar Actors SOG / SPZ / PLY.

DetermineSourceType

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

Determina el tipo de origen de los datos.

Devuelve ELCCSourceType: Local para un archivo local, Http para una dirección de red.

Usarlo para bifurcar la lógica de tratamiento, por ejemplo cuando los datos de red necesitan descargarse primero o transmitirse.

DetermineCollisionType

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

Determina el formato de los datos de colisión.

Devuelve ECollisionType:

Notas de uso:

• Pasar un directorio, no la ruta de un archivo. Pasar la ruta de un archivo .lcc devuelve siempre None. El directorio está disponible en el OutWorkPath de CheckLCCValid.
• None significa que los datos no incluyen colisión, en cuyo caso activar bEnableCollision no surte efecto.
• Una vez cargados los datos, HaveValidCollisionData() en el Component es más sencillo y evita componer el directorio manualmente.

Versión y entorno

GetLCC4UnrealVersion

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

Devuelve la cadena de versión del plugin.

Usos: mostrarla en una pantalla de información, escribirla en un log, adjuntarla a un informe de problema.

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

GetProjectId

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

Devuelve el identificador del proyecto actual. Necesario al solicitar una licencia o al investigar un problema de licencia.

GetLCCConfigPath

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

Devuelve la ruta del archivo de configuración del plugin.

GetLCC4UnrealRootPath

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

Devuelve la ruta del directorio raíz del plugin. Usarla para componer rutas cuando haya que acceder a los recursos que se distribuyen con el plugin.

GetLocale

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

Devuelve la configuración regional actual, ELocale::EN_US o ELocale::ZH_CN.

Orden de la decisión: el elemento Language de la configuración del proyecto tiene prioridad, y se devuelve EN_US directamente cuando está en Always English; en caso contrario decide el idioma actual del editor, y el chino devuelve ZH_CN.

Usos: hacer que el texto de la propia interfaz siga el ajuste de idioma del plugin, o elegir el dominio del sitio web según la región.

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

Identificadores de viewport

GetPlayerUniqueID

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

Obtiene el identificador único de un controlador de jugador.

Devuelve bool: true cuando tiene éxito.

Notas de uso:

• Usarlo como clave al mantener manualmente una tabla de correspondencias de «una configuración por viewport».
• La configuración habitual de renderizado en varios viewports solo necesita pasar el puntero del controlador a SetPlayerLoadMode y SetPlayerRenderMode, sin obtener ningún ID manualmente.

GetSceneCaptureUniqueID

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

Obtiene el identificador único de un componente SceneCapture. Los parámetros y el valor de retorno significan lo mismo que arriba.

Portapapeles

CopyToClipboard

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

Escribe una cadena en el portapapeles del sistema.

Uso típico: un botón de «copiar información de diagnóstico» que facilita a los usuarios notificar problemas.

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

Lee el contenido del portapapeles del sistema.

Uso típico: un botón de «pegar la ruta desde el portapapeles» que evita escribir una ruta larga.

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

Blueprint como texto:

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

Textura

GetTextureFromBase64

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

Convierte datos de imagen codificados en Base64 en una textura de tiempo de ejecución.

Devuelve UTexture2D*: nullptr cuando la conversión falla.

Uso: convertir directamente en textura para la interfaz una imagen Base64 obtenida de una interfaz de red o de un archivo de configuración, sin escribirla en disco ni importarla.

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

Análisis de los metadatos SOG

Estas funciones leen los metadatos de un archivo .sog sin cargar los datos de renderizado, lo que se adapta a las previsualizaciones de datos y a las páginas de listado.

ParseSogMetaFromFile

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

Analiza los metadatos SOG a partir de un archivo.

Devuelve bool: true cuando el análisis tiene éxito.

Notas de uso:

• Solo lee los metadatos y no carga los datos de splats, con un coste muy bajo.
• Revela el número de puntos y si hay armónicos esféricos de orden alto antes de cargar, lo que ayuda a decidir si se necesita una configuración reducida.

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

    // bajar la configuración por adelantado cuando el número de puntos es demasiado grande
    if (Meta.Count > 5000000)
    {
        Component->SetMaxSplatNum(1000);
    }
}

ParseSogMetaFromData

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

Analiza los metadatos SOG a partir de un array de bytes en memoria.

Usar esta versión cuando los datos provienen de una descarga de red y todavía no se han escrito en disco.

Para los campos de FLCC2SogMeta, consultar Structs.

Solo C++

Las funciones siguientes no tienen marcado UFUNCTION y solo se pueden llamar desde C++.

ConvertStrToMetaInfo

static FLCCMetaInfo ConvertStrToMetaInfo(const FString& JsonStr);

Convierte el contenido JSON de un archivo .lcc en un struct FLCCMetaInfo.

Usarla para leer y analizar los archivos de metadatos manualmente, por ejemplo para recorrer conjuntos de datos en bloque al construir una herramienta de gestión de datos.

ConvertStrToLCC2MetaInfo

static FLCC2MetaInfo ConvertStrToLCC2MetaInfo(const FString& JsonStr);

Convierte el contenido JSON de un archivo .lcc2 en un struct FLCC2MetaInfo.

SelectFile

static FString SelectFile(ELCCVersion LCCVersion);

Abre el diálogo de archivos con la extensión filtrada según la versión. Devuelve la ruta seleccionada, o una cadena vacía al cancelar.

Solo en el editor. SelectFile() del Actor llama a esta función internamente.

Nota: ULCCUtilLibrary también contiene varias funciones estáticas destinadas únicamente al uso interno del plugin (cálculo del frustum, la implementación interna del análisis SOG, comprobaciones de extensiones en subdirectorios y otras). Son visibles para el compilador pero no forman parte de la API pública, su comportamiento puede cambiar entre versiones y no conviene depender de ellas.

Ejemplo completo: validar antes de cargar

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

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

    // 2. distinguir el formato por la extensión
    const FString Ext = FPaths::GetExtension(Path).ToLower();
    const bool bIsLCC1 = (Ext == TEXT("lcc"));
    const bool bIsLCC2 = (Ext == TEXT("lcc2"));

    if (!bIsLCC1 && !bIsLCC2)
    {
        // para el reparto de .sog / .spz / .ply consultar la página de los Actors SOG / SPZ / PLY
        UE_LOG(LogTemp, Error, TEXT("Not an LCC dataset: %s"), *Path);
        return false;
    }

    // 3. validar la integridad de los datos y tomar a la vez el directorio de trabajo
    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. generar el Actor correspondiente y cargar
    UClass* ActorClass = bIsLCC2 ? ALCC2Actor::StaticClass() : ALCCActor::StaticClass();
    ALCCActorBase* Actor = GetWorld()->SpawnActor<ALCCActorBase>(ActorClass);
    if (!Actor)
    {
        return false;
    }
    Actor->Load(Path);

    // 5. confirmar de paso si existen datos de colisión. Nótese que se pasa el directorio de trabajo, no la ruta del archivo
    const ECollisionType CollisionType =
        ULCCUtilLibrary::DetermineCollisionType(WorkPath);
    UE_LOG(LogTemp, Log, TEXT("Collision type: %d"),
        static_cast<int32>(CollisionType));

    return true;
}

Véase también

• Actors SOG / SPZ / PLY: el ejemplo completo de reparto por formato
• Enumeraciones: valores de EFileFormat, ECollisionType, ELocale y otros
• Structs: campos de FLCCMetaInfo y FLCC2SogMeta