ULCCUtilLibrary: библиотека вспомогательных функций Blueprint

Библиотека статических вспомогательных функций: проверка пути, распознавание формата, работа с буфером обмена, запрос версии и прочие возможности.

#include "Tools/LCCUtilLibrary.h"

Все функции статические, вызывай их прямо по имени класса, экземпляр не нужен:

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

В Blueprint у этих узлов нет пина Target, достаточно найти их по имени функции.

Проверка пути и формата

Проверка перед загрузкой данных позволяет отделить «неверный путь» от «проблемы в самих данных» и экономит немало времени на поиск причины.

CheckPathValid

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

Проверяет, существует ли файл.

Возвращает bool: true, если файл существует.

Замечания по применению:

• Проверяется только файл; для пути к каталогу вернётся false. Внутри используется проверка существования файла.
• Проверяется только существование, а не то, являются ли данные корректными данными LCC.
• Это первая проверка в процессе загрузки, она сразу отсекает опечатки в пути и перемещённые файлы.

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

Проверяет, являются ли данные корректными данными LCC1.

Возвращает bool: true, если данные корректны.

Замечания по применению:

• LCC1 нужен сам файл .lcc плюс data.bin и index.bin в том же каталоге; при отсутствии любого из них вернётся false. Имя файла .lcc не фиксировано.
• Выходной OutWorkPath — это каталог без имени файла, он пригодится, когда нужно собрать путь к другому файлу того же каталога.
• Относительные пути поддерживаются: если переданный путь не существует, автоматически выполняется вторая попытка по пути Content/<переданный путь>, как и в правилах 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);

Проверяет путь LCC2 и извлекает рабочий каталог. Значение параметров такое же, как выше.

Замечания по применению:

• LCC2 не требует data.bin и index.bin, поэтому эта функция лишь подтверждает существование пути и берёт родительский каталог как OutWorkPath, не проверяя целостность содержимого данных. Настоящая проверка содержимого происходит на этапе загрузки.
• Когда есть путь и неясно, LCC1 это или LCC2, проще всего посмотреть на расширение (.lcc или .lcc2). Можно также попробовать обе функции проверки:

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

Примечание: не пытайся различать форматы по принципу «CheckLCC2Valid вернул true, значит это LCC2». Её проверка очень нестрогая, и для пути .lcc она тоже вернёт true, из-за чего данные LCC1 будут ошибочно приняты за LCC2. Сначала смотри расширение.

DetermineFileFormat

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

Определяет формат файла.

Возвращает EFileFormat. Фактически определение идёт по расширению и требует, чтобы путь существовал:

Замечания по применению:

• Эта функция не распознаёт .lcc2, .sog и .spz, для всех них она вернёт None. Когда нужно охватить эти форматы, определяй расширение самостоятельно.
• Для несуществующего пути тоже возвращается None, поэтому у None есть две причины: формат не поддерживается либо файла вообще нет. Чтобы их различить, сначала вызови CheckPathValid.

Из-за неполного охвата при разработке универсального загрузчика надёжнее смотреть прямо на расширение:

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

Полный пример см. в Actor SOG / SPZ / PLY.

DetermineSourceType

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

Определяет тип источника данных.

Возвращает ELCCSourceType: Local — локальный файл, Http — сетевой адрес.

Используется для разделения логики обработки, например когда сетевые данные нужно сначала скачать или загружать потоком.

DetermineCollisionType

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

Определяет формат данных коллизий.

Возвращает ECollisionType:

Замечания по применению:

• Передавай каталог, а не путь к файлу. Для пути к файлу .lcc всегда вернётся None. Каталог можно взять из OutWorkPath у CheckLCCValid.
• Возврат None означает, что данные идут без коллизий, и включение bEnableCollision в этом случае не даст эффекта.
• Если данные уже загружены, проще воспользоваться методом HaveValidCollisionData() у Component и не собирать путь к каталогу самостоятельно.

Версия и окружение

GetLCC4UnrealVersion

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

Возвращает строку с номером версии плагина.

Применение: показать в окне «О программе», записать в журнал, приложить при обращении с проблемой.

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

GetProjectId

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

Возвращает идентификатор текущего проекта. Его нужно указывать при запросе лицензии и разборе проблем с лицензированием.

GetLCCConfigPath

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

Возвращает путь к файлу настроек плагина.

GetLCC4UnrealRootPath

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

Возвращает путь к корневому каталогу плагина. Используй его для сборки пути, когда нужен доступ к ресурсам, входящим в состав плагина.

GetLocale

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

Возвращает текущую языковую среду, ELocale::EN_US или ELocale::ZH_CN.

Порядок определения: сначала проверяется пункт Language в настройках проекта, и при значении Always English сразу возвращается EN_US; иначе определение идёт по текущему языку редактора, и для китайского возвращается ZH_CN.

Применение: переключать текст своего интерфейса вслед за языковой настройкой плагина или выбирать домен официального сайта по региону.

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

Идентификаторы вьюпортов

GetPlayerUniqueID

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

Получает уникальный идентификатор контроллера игрока.

Возвращает bool: true при успешном получении.

Замечания по применению:

• Используй его как ключ, когда нужно самостоятельно вести таблицу соответствия «свой набор настроек для каждого вьюпорта».
• Для обычной настройки рендеринга с несколькими вьюпортами достаточно передать указатель на контроллер в SetPlayerLoadMode и SetPlayerRenderMode, получать ID вручную не нужно.

GetSceneCaptureUniqueID

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

Получает уникальный идентификатор компонента SceneCapture. Значение параметров и возвращаемого значения такое же, как выше.

Буфер обмена

CopyToClipboard

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

Записывает строку в системный буфер обмена.

Типичное применение: сделать кнопку «скопировать диагностические сведения», чтобы пользователю было проще сообщить о проблеме.

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

Читает содержимое системного буфера обмена.

Типичное применение: сделать кнопку «вставить путь из буфера обмена», чтобы не вводить длинный путь вручную.

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

Текстовое описание 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)

Текстуры

GetTextureFromBase64

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

Преобразует данные изображения в кодировке Base64 в текстуру времени выполнения.

Возвращает UTexture2D*: nullptr при неудачном преобразовании.

Применение: получить изображение в Base64 из сетевого интерфейса или файла настроек и сразу создать текстуру для интерфейса, без сохранения на диск и последующего импорта.

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

Разбор метаданных SOG

Эти функции читают метаданные файла .sog, не загружая данные для рендеринга, и подходят для предпросмотра данных и отображения в списках.

ParseSogMetaFromFile

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

Разбирает метаданные SOG из файла.

Возвращает bool: true при успешном разборе.

Замечания по применению:

• Читаются только метаданные, данные splat не загружаются, поэтому затраты невелики.
• По ним можно ещё до загрузки узнать количество точек и наличие сферических гармоник высокого порядка, чтобы решить, нужны ли пониженные настройки.

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 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 из массива байтов в памяти.

Этот вариант используется, когда данные получены по сети и ещё не сохранены на диск.

Описание полей FLCC2SogMeta см. в Structs.

Только C++

У перечисленных ниже функций нет пометки UFUNCTION, их можно вызывать только из C++.

ConvertStrToMetaInfo

static FLCCMetaInfo ConvertStrToMetaInfo(const FString& JsonStr);

Преобразует содержимое JSON из файла .lcc в структуру FLCCMetaInfo.

Используется, когда файл метаданных читается и разбирается самостоятельно, например при пакетном сканировании наборов данных в инструменте управления данными.

ConvertStrToLCC2MetaInfo

static FLCC2MetaInfo ConvertStrToLCC2MetaInfo(const FString& JsonStr);

Преобразует содержимое JSON из файла .lcc2 в структуру FLCC2MetaInfo.

SelectFile

static FString SelectFile(ELCCVersion LCCVersion);

Открывает диалог выбора файла с фильтром расширений по версии. Возвращает выбранный путь, а при отмене — пустую строку.

Доступно только в редакторе. Метод SelectFile() у Actor внутри вызывает именно её.

Примечание: в ULCCUtilLibrary есть и другие статические функции, предназначенные только для внутреннего использования плагином (расчёт пирамиды видимости, внутренняя реализация разбора SOG, проверка расширений в подкаталогах и прочее). При компиляции они видимы, но не относятся к внешнему API, их поведение может меняться от версии к версии, поэтому не полагайся на них.

Полный пример: проверка перед загрузкой

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

Смотрите также

• Actor SOG / SPZ / PLY: полный пример распределения по формату
• Enums: описание значений EFileFormat, ECollisionType, ELocale и других
• Structs: описание полей FLCCMetaInfo, FLCC2SogMeta