Blitz3D+ Command Reference

TerrainSplatMap terrain,texture

Parameters

terrain - terrain entity created with CreateTerrain or LoadTerrain

texture - blend map stretched across the whole terrain; 0 clears the map

Description

Sets the blend map that decides where each terrain layer shows.

The splat map is one image stretched over the entire terrain - it is not tiled. Each colour channel is a weight for one layer: red weights layer 0, green layer 1, blue layer 2 and alpha layer 3. Paint green where you want the second layer's dirt and blue where you want rock, and that is where they appear.

The four weights are normalised in the pixel shader, so a hand-painted map does not have to add up to exactly one anywhere. Overlapping blobs blend instead of blowing out, and texture compression or filtering that nudges the channels does not wreck the result. Where every weight is zero, layer 0 shows through, which is why layer 0 makes a good base coat.

It is read as plain linear data rather than as sRGB colour, so the weights you paint are the weights the shader gets. The resolution is up to you and does not have to match the terrain grid: a small 64x64 map over a big landscape gives broad, soft biome regions, and a larger map gives crisper boundaries. Because it is stretched, a low-resolution map will look blurry if the camera stands still on one hillside.

One image covering the whole map also means you can paint it in code. Create a texture, draw into its TextureBuffer with ordinary 2D commands, and hand it over - that is enough for a procedurally generated world, an in-game terrain editor brush, or a scorch mark spreading after a bombing run.

Gotcha: passing 0 clears the map, which puts layer 0 back everywhere. A splat map on its own does nothing - it needs TerrainLayer textures or tints to blend between. And remember to free the old texture yourself when you replace one at runtime.

See also: TerrainLayer, TerrainLayerColor, TerrainNormalMap, ClearTerrainMaterial, TextureBuffer.

Example

; TerrainSplatMap Example
; -----------------------

Graphics3D 640,480,0,2
SetBuffer BackBuffer()

SeedRnd MilliSecs()

camera=CreateCamera()
PositionEntity camera,0,6,-40
CameraClsColor camera,110,150,200

light=CreateLight(1)
RotateEntity light,50,-30,0

; Rolling hills built from a sine-wave height field
terrain=CreateTerrain(128)
For z=0 To 127
    For x=0 To 127
        ModifyTerrain terrain,x,z,0.2+Sin(x*10)*Cos(z*10)*0.12
    Next
Next
ScaleEntity terrain,0.5,20,0.5
PositionEntity terrain,-32,-5,-32
TerrainShading terrain,True
TerrainDetail terrain,8000,True

; Three plain layer textures: grass, dirt and rock
grass=SolidTexture(75,135,60)
dirt=SolidTexture(140,100,60)
rock=SolidTexture(120,120,125)
TerrainLayer terrain,0,grass,0.2
TerrainLayer terrain,1,dirt,0.2
TerrainLayer terrain,2,rock,0.2

; Paint a blend map and stretch it across the whole terrain
splat=PaintSplat()
TerrainSplatMap terrain,splat

sun_angle#=-30

While Not KeyDown(1)

    ; Space paints a fresh random splat map
    If KeyHit(57)
        old=splat
        splat=PaintSplat()
        TerrainSplatMap terrain,splat
        FreeTexture old
    EndIf

    ; The sun slowly circles so the hills' shading shifts
    sun_angle=sun_angle+0.2
    RotateEntity light,50,sun_angle,0

    ; Arrow keys move the camera
    If KeyDown(200) Then MoveEntity camera,0,0,0.1
    If KeyDown(208) Then MoveEntity camera,0,0,-0.1
    If KeyDown(203) Then TurnEntity camera,0,1,0
    If KeyDown(205) Then TurnEntity camera,0,-1,0

    RenderWorld

    Text 0,0,"Arrow keys: move camera   Space: repaint splat map   Esc: exit"
    Text 0,20,"TerrainSplatMap blends grass, dirt and rock layers"

    Flip

Wend

End

Function SolidTexture(red,green,blue)
    texture=CreateTexture(8,8,1+8)
    SetBuffer TextureBuffer(texture)
    ClsColor red,green,blue
    Cls
    SetBuffer BackBuffer()
    Return texture
End Function

Function PaintSplat()
    ; Red weights layer 0, green layer 1, blue layer 2
    splat=CreateTexture(64,64,1)
    SetBuffer TextureBuffer(splat)
    Color 255,0,0
    Rect 0,0,64,64,True
    For patch=1 To 14
        Color 0,255,0
        Oval Rand(-10,54),Rand(-10,54),Rand(8,20),Rand(8,20),True
    Next
    For patch=1 To 8
        Color 0,0,255
        Oval Rand(-10,54),Rand(-10,54),Rand(6,16),Rand(6,16),True
    Next
    SetBuffer BackBuffer()
    Return splat
End Function

Index