Blitz3D+ Command Reference

ClearTerrainMaterial terrain

Parameters

terrain - terrain entity whose built-in layered material is released

Description

Drops every terrain layer and map and goes back to the plain single-texture path.

This is the undo button for the built-in layered material. It releases the four layer textures, their tints and scales, the splat map and the detail normal map, and puts the terrain back on the classic route - so whatever you set with EntityTexture shows again, or plain EntityColor if you never set a texture.

Games use it for quality toggles and for swapping whole biome sets at runtime. Clearing first and then setting the new layers means you are never holding two full sets of ground textures at once, and it guarantees no stale tint or splat map survives from the old set. It is also useful while debugging - strip the material back to a flat colour to see the shape of the land without the blending confusing you.

Clearing releases the material's references to those textures. Your own handles stay valid, so you can re-apply the same textures later with TerrainLayer; textures nothing else refers to are freed as normal.

Gotcha: it is all or nothing - there is no per-layer clear here, pass 0 to TerrainLayer for that. Anything that touches the built-in material afterwards (a layer, a tint, a splat map or a normal map) switches it straight back on with default values, so the settings you cleared really are gone and have to be set again.

See also: TerrainLayer, TerrainSplatMap, TerrainNormalMap, TerrainLayerColor, EntityTexture.

Example

; ClearTerrainMaterial Example
; ----------------------------

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

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

; Sandy texture for the classic single-texture path
sand=SolidTexture(200,175,120)
EntityTexture terrain,sand

; Layered material: grass west, rock east, blended by a splat map
grass=SolidTexture(75,135,60)
rock=SolidTexture(120,120,125)
splat=CreateTexture(64,64,1)
SetBuffer TextureBuffer(splat)
Color 255,0,0
Rect 0,0,64,64,True
Color 0,255,0
Rect 32,0,32,64,True
SetBuffer BackBuffer()

TerrainLayer terrain,0,grass,0.2
TerrainLayer terrain,1,rock,0.2
TerrainSplatMap terrain,splat
layered=1

sun_angle#=-30

While Not KeyDown(1)

    ; Space swaps between the layered material and the cleared state
    If KeyHit(57)
        If layered
            ; Drop every layer and map - the EntityTexture sand shows again
            ClearTerrainMaterial terrain
            layered=0
        Else
            TerrainLayer terrain,0,grass,0.2
            TerrainLayer terrain,1,rock,0.2
            TerrainSplatMap terrain,splat
            layered=1
        EndIf
    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: clear/restore material   Esc: exit"
    If layered
        Text 0,20,"Layered material active - Space calls ClearTerrainMaterial"
    Else
        Text 0,20,"ClearTerrainMaterial done - single EntityTexture path active"
    EndIf

    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

Index