Caffeine

7.2 — Combinadores Booleanos de Heightmap

Historical Fase: 8 · **Prioridade:** Alta · **Esforço:** Médio Last updated:
> **Depende de:** 7.1 (múltiplos geradores/módulos) > **Bloqueia:** 7.3 (brush com máscaras)

Objetivo#

Permitir combinar dois ou mais heightmaps com operações booleanas ou matemáticas — ex.: montanhas + vales, máscaras de ilhas, túneis em relevo.


Conceito#

text
Terreno A (Montanhas)  ──┐
                         ├──► BlendOp ──► Heightmap final
Terreno B (Vales)      ──┘

Cada "fonte" é um heightmap temporário gerado por um sub-pipeline ou importado.


API Proposta#

cpp
enum class HeightmapBlendOp : u8 {
    Add,        // A + B (clamp 0–1)
    Subtract,   // A - B
    Max,        // max(A, B) — união de elevações
    Min,        // min(A, B) — interseção de vales
    Multiply,   // A * B
    Lerp,       // mix(A, B, mask)
    Difference, // abs(A - B) — picos isolados (XOR-like)
    Mask,       // A onde mask > 0.5, senão B
};

struct HeightmapBlendLayer {
    HeightmapBlendOp op = HeightmapBlendOp::Max;
    f32 weight = 1.0f;           // para Lerp / influência
    ECS::TerrainGenerationSettings settings;  // sub-gerador
    // ou char heightmapPath[256] para .cterrain / PNG importado
};

class HeightmapCombinerModule final : public ITerrainGeneratorModule {
    std::vector<HeightmapBlendLayer> layers;
};

Casos de Uso#

Operação Entrada A Entrada B Resultado
Max Noise montanhoso Noise plano Montanhas sobre base plana
Min Terreno alto Caverna (invertido) Vales/cavidades
Difference Ridged noise Smooth noise Picos isolados
Lerp + máscara Praia Oceano Costa com transição
Mask Detalhe local Base global Detalhe só numa região

Implementação#

Fluxo#

  1. TerrainHeightmap scratchA, scratchB, result
  2. Para cada layer no combinador:
    • Gerar ou carregar heightmap da layer
    • Aplicar op(result, layer, weight)
  3. Escrever result no heightmap principal do cache

Máscaras#

  • Máscara pode ser:
    • Procedural: noise Worley, gradiente radial, polígono
    • Pintada: splat channel R como máscara (reutilizar TerrainSplatmap)
    • Geometria: distância a ponto/linha (fault lines)
cpp
f32 sampleMask(u32 x, u32 z, const MaskDesc& mask);
// usado em Lerp: result = lerp(A, B, sampleMask(x,z));

Editor#

Inspector — secção Combinators#

text
[+] Add Layer
  Layer 0: [Max ▼]  Weight: 1.0  [Edit Generator...]
  Layer 1: [Lerp ▼] Weight: 0.6  Mask: [Radial ▼]
[Generate Combined]

Futuro (opcional)#

  • Node graph visual (reutilizar ShaderGraph como referência de UI)
  • Preset "Island" = Max(terrain, 0) com máscara radial

Serialização#

Blob terrain v3 ou ficheiro .cterrain-gen separado:

text
[layerCount]
repeat:
  [op: u8][weight: f32][generatorSettings...]
  [maskType: u8][maskParams...]

Critérios de Aceitação#

  • [ ] Pelo menos 5 ops implementadas: Add, Max, Min, Lerp, Difference
  • [ ] 2+ layers combináveis num único Generate
  • [ ] Resultado determinístico com mesmo seed
  • [ ] Sem alocações desnecessárias (reutilizar scratch buffers no cache)
  • [ ] Inspector permite adicionar/remover layers

Performance#

  • Cada layer extra = 1 geração completa de heightmap → pode ser lento em 257×257 com erosão
  • Mitigação: cache de layers intermediárias por hash de settings
  • Mitigação futura: 7.5 GPU Compute