DotLabs Studios – Sviluppo Videogiochi

Documentazione di Texture Gen

Texture Gen ti permette di generare heightmap, noise, LUT, channel packing e mappe di dettaglio direttamente in Unreal Engine: installazione, guida ai dodici strumenti, esportazione e risoluzione dei problemi.

Installazione e Requisiti

Requisiti

  • Versione UE: Unreal Engine 5.8
  • IDE: Visual Studio 2022 (con compilatore MSVC compatibile)

Procedura di Installazione

  1. Copia la cartella del plugin UETextureGen all'interno della directory Plugins/ del tuo progetto Unreal Engine (es. IlTuoProgetto/Plugins/UETextureGen).
  2. Fai clic destro sul file del tuo progetto .uproject e seleziona Generate Visual Studio project files.
  3. Apri la soluzione .sln generata in Visual Studio e compila il progetto in modalità Development Editor.
  4. Apri l'Editor, vai su Edit > Plugins, cerca UETextureGen e assicurati che sia abilitato.
  5. Riavvia l'Editor se necessario.

Guida all'Uso (Utilizzo Utente)

Il plugin offre due modalità principali di utilizzo: la Finestra degli Strumenti (Tools Window) e il Menu Contestuale delle Texture.

A. Finestra degli Strumenti Principale (Window > UETextureGen Tools)

È possibile accedere alla finestra principale degli strumenti tramite il menu dell'Editor Window > UETextureGen Tools oppure cliccando sull'icona UETextureGen nella barra degli strumenti principale (Play Toolbar). La finestra è organizzata in 12 schede (Tab) funzionali:

1. Heightmap (Generatore di Terreni)

Genera mappe di altezza procedurali composte da più livelli di rumore combinati, con simulazione di erosione idraulica.

  • Parametri principali:
    • Resolution: Larghezza e altezza della texture generata (consigliato l'uso di dimensioni ottimali per i landscape di Unreal, come 1009x1009).
    • Seed: Valore numerico per inizializzare il generatore casuale.
    • Global Mask Radius: Applica una maschera circolare di sfumatura ai bordi (da 0 a 1), ideale per creare isole o montagne isolate.
    • Erosion Iterations: Numero di passaggi dell'algoritmo di erosione idraulica simulata sulla CPU. Rende il terreno molto più realistico creando gole e depositi di sedimenti.
    • Layers: Permette di aggiungere molteplici strati di disturbo (Noise Layers) oltre a quello di base, ciascuno con la propria scala, rotazione (Angle), forza (Strength), offset e ottave.

2. Noise (Rumori Procedurali)

Genera una singola mappa di rumore procedurale tiling (ripetibile senza giunzioni).

  • Tipi di Rumore: Perlin, Cellular, Billow, Ridge, Fractal, Worley.
  • Parametri:
    • Scale: Frequenza spaziale del disturbo.
    • Octaves: Livello di dettaglio del rumore frattale.
    • Persistence: Influenza il contributo delle ottave più alte sul risultato finale.

3. LUT (Color Lookup Table)

Genera una texture 3D o 2D neutra per il Color Grading (LUT), applicando correzioni di colore personalizzate.

  • Parametri:
    • LUT Size: Solitamente 16 o 32.
    • Contrast / Saturation: Regolazioni di base del contrasto e dell'intensità del colore.
    • Temperature / Tint: Sposta i colori verso toni caldi/freddi o tonalità verdi/magenta.

4. Channel Packing (Compressione Canali)

Consente di ottimizzare le prestazioni unendo fino a 4 texture a canale singolo (grigio) nei rispettivi canali R, G, B e A di una nuova texture.

  • Utilizzo tipico: Unire una mappa di Metallic (R), Roughness (G), Ambient Occlusion (B) e Alpha/Displacement (A) in una singola texture "ORM" per risparmiare chiamate al sampler dei materiali nei shader.

5. Channel Unpacking (Estrazione Canali)

Effettua l'operazione inversa rispetto al Channel Packing. Prende una texture RGBA esistente e separa i suoi canali salvandoli come singole texture in scala di grigi.

6. Swapping (Scambio Canali)

Permette di riordinare, invertire o sovrascrivere i singoli canali di una texture esistente. Ad esempio, è possibile copiare il canale rosso nel canale alfa, invertire il canale verde (utile per convertire normal map da formato DirectX a OpenGL) o riempire un canale con un valore fisso (Zero, One, Half).

7. Blending (Fusione Texture)

Combina fino a 4 livelli di texture differenti sovrapponendoli.

  • Metodi di fusione: Normal, Multiply, Screen, Overlay, Add, Subtract, Min, Max.
  • Ogni livello dispone di uno slider per controllare l'Opacità da 0.0 a 1.0.

8. Curvature (Mappa di Curvatura)

Calcola le aree concave (valli) e convesse (creste) a partire da una mappa di altezza o da una normal map. Molto utile per creare maschere di usura sui bordi dei modelli 3D.

9. Cavity (Mappa di Cavità)

Simile alla curvatura, ma calcola una mappa di cavità o convessità più marcata (applicando una sfocatura gaussiana di soglia) per evidenziare piccole fessure e micro-dettagli superficiali.

10. H→2N (Height to Normal)

Converte una mappa di altezze o una texture in scala di grigi in una Normal Map dettagliata.

  • Algoritmi: Sobel (consigliato per dettagli morbidi ed equilibrati) o Finite Differences (differenze finite, più nitido).
  • Parametri:
    • Strength: Intensità del rilievo della normal map.
    • Pre-Blur / Post-Blur: Rispettivamente una sfocatura gaussiana applicata all'altezza di input o alla normale generata, utile per eliminare il rumore ad alta frequenza.
    • Wrap (Seamless): Se abilitato, calcola i gradienti sui bordi avvolgendo le coordinate per garantire che la normal map mantenga il tiling perfetto.

11. Disp→Height (Normalizzatore di Displacement)

Prende una mappa di displacement e normalizza i valori per riportarli in un intervallo coerente [0, 1].

  • Modalità di normalizzazione:
    • MinMax: Ricalcola i pixel in base al minimo e massimo valore rilevati nell'immagine.
    • StdDev: Normalizza usando la deviazione standard.
    • Custom: Consente di rimappare i pixel definendo manualmente un intervallo minimo e massimo.

12. Patterns (Generatore di Pattern Geometrici)

Genera pattern strutturali ripetibili direttamente in memoria.

  • Tipi di Pattern: Voronoi, Bricks (mattoni), Hex (esagoni), Weave (intrecci).
  • Parametri: Distortion (distorsione tramite rumore), Edge Profile (morbidezza dei bordi), Scale.

B. Finestra di Anteprima Veloce (Menu Contestuale)

Se desideri convertire o estrarre rapidamente mappe da un asset esistente senza configurare la finestra principale:

  1. Fai clic destro su una qualsiasi texture 2D nel Content Browser.
  2. Nel menu contestuale, seleziona la voce UETextureGen.
  3. Scegli l'operazione rapida desiderata: Generate Normal Map, Generate AO Map, Generate Roughness Map o Generate Displacement Map.
  4. Si aprirà una finestra popup interattiva (STexturePreviewWindow) in cui potrai regolare i parametri fondamentali tramite cursori e visualizzare l'anteprima istantanea.
  5. Assegna un nome all'asset nel campo di testo e clicca su Save per salvarlo direttamente nel Content Browser.

Note di Esportazione e Salvataggio (Workflow)

Quando decidi di salvare una texture (sia dalla finestra principale che dall'anteprima veloce):

  • Save Path (Percorso): Di default, le texture vengono create nella cartella /Game/Textures. Puoi modificare questo percorso inserendo la directory desiderata (es. /Game/MioProgetto/Materials/MappeProcedurali). Se le cartelle non esistono, l'editor le creerà automaticamente.
  • sRGB Automatico: Il plugin configura l'impostazione sRGB in conformità agli standard di rendering PBR di Unreal Engine:
    • Disattivato (sRGB = false) per: Normal Map, Mappe AO, Roughness, Displacement, Curvatura e Cavità. Questo assicura che Unreal legga i dati dei pixel in modo lineare.
    • Attivato (sRGB = true) per: Colori base (Albedo), LUT di color grading e pattern di colore.
  • Esportazione su Disco: La finestra principale consente inoltre di esportare direttamente le heightmap prodotte in file esterni al progetto Unreal nei formati PNG o RAW 16-bit (tramite i pulsanti Save as PNG e Create RAW), ideali per essere importati direttamente nello strumento Landscape di Unreal Engine.

Panoramica del Codice (Documentazione C++)

Il plugin è implementato interamente in C++ ed estende l'interfaccia dell'editor tramite Slate. Non contiene asset binari o Blueprint (CanContainContent = false).

Struttura delle Classi Principali

classDiagram
    class FUETextureGenModule {
        +StartupModule()
        +ShutdownModule()
        -RegisterMenuExtensions()
    }
    class FTextureMapGenerator {
        +GenerateNormalMap()
        +GenerateAOMap()
        +GenerateRoughnessMap()
        +GenerateDisplacementMap()
        +GetTexturePixelsPublic()
        +GaussianBlur()
    }
    class FStandaloneGenerators {
        +GenerateHeightmap()
        +GeneratePerlinNoise()
        +GenerateLUT()
        +GeneratePatternPixels()
        +CreateAndSaveTexture()
    }
    class SUETextureGenToolsWindow {
        +Construct()
        -BuildTabButton()
        -TabSwitcher
    }
    class STexturePreviewWindow {
        +Construct()
        -UpdatePreview()
        -OnSaveClicked()
    }
    FUETextureGenModule --> SUETextureGenToolsWindow : Apre la finestra strumenti
    FUETextureGenModule --> STexturePreviewWindow : Apre anteprima da tasto destro
    SUETextureGenToolsWindow --> FStandaloneGenerators : Genera texture procedurale
    SUETextureGenToolsWindow --> FTextureMapGenerator : Elabora canali e filtri
    STexturePreviewWindow --> FTextureMapGenerator : Genera mappe da texture

1. FUETextureGenModule

Gestisce il ciclo di vita del plugin. All'avvio (StartupModule), carica gli stili Slate (icone del plugin in Resources/) e registra le estensioni dei menu contestuali dell'editor tramite UToolMenus.

2. FTextureMapGenerator

Contiene la logica matematica e gli algoritmi di elaborazione delle immagini. Opera estraendo i pixel da una texture esistente in memoria in un array lineare TArray<FColor>.

  • Tiling (Seamless): Utilizza la funzione interna SamplePixelWrap che permette di campionare i pixel confinanti oltre i bordi (coordinate modulo Larghezza/Altezza), garantendo mappe perfettamente ripetibili.
  • Estrazione Pixel: Tramite GetTexturePixelsPublic, il generatore blocca in sola lettura la mipmap 0 dell'asset sorgente (Source.LockMip) e ne copia i dati grezzi in un buffer compatibile BGRA8.

3. FStandaloneGenerators

Gestisce la sintesi da zero di texture (senza immagine sorgente).

  • Rumori procedurali: Calcolati su CPU tramite implementazioni matematiche di Perlin Noise, Cellular, Worley, ecc.
  • Erosione Idraulica: La funzione ApplyHydraulicErosion simula gocce di pioggia che si muovono lungo i pendii dell'altezza accumulata, erodendo il terreno nei punti ripidi e depositando sedimenti nei punti pianeggianti.

4. Interfacce Slate (SUETextureGenToolsWindow e STexturePreviewWindow)

Costruite interamente tramite il framework dichiarativo di Slate di Unreal.

  • Per velocizzare le risposte dell'interfaccia utente, la funzione Preview esegue l'algoritmo solo su una copia temporanea di pixel visualizzata in un widget SImage tramite una texture dinamica transitoria aggiornata a runtime (UpdateChannelPreview), evitando di creare e salvare asset fisici finché l'utente non clicca su Save.

Risoluzione dei Problemi e Limitazioni

  • Freeze Temporaneo dell'Editor: Poiché tutti gli algoritmi matematici di calcolo pixel ed erosione idraulica vengono eseguiti sul thread principale dell'editor (Game Thread), l'elaborazione di texture con risoluzione pari o superiore a 4096 pixel o l'esecuzione di un numero molto elevato di iterazioni di erosione (> 100) causerà il blocco temporaneo (freeze) della schermata di Unreal. Questo è un comportamento previsto dovuto all'esecuzione sincrona su CPU.
  • Le Texture create non appaiono nel Content Browser: Il plugin utilizza il modulo AssetRegistry per notificare all'editor la creazione del file. Se per qualche motivo un asset salvato non compare subito, effettua un click destro in uno spazio vuoto del Content Browser e seleziona Rescan Folder.
  • Texture Nere o Vuote: Assicurarsi che la texture sorgente selezionata abbia la risorsa sorgente valida all'interno del progetto (ad esempio, texture importate da file di immagine e non texture procedurali virtuali dell'editor che non possiedono pixel di origine estraibili su CPU).

Texture Gen

La pagina di Texture Gen: cosa fa, gli screenshot e dove trovarlo.

Scopri Texture Gen