Blitz3D+ Command Reference

TerrainShading terrain,enable

Parameters

terrain - terrain handle

enable - True to light the terrain from its slopes, False to leave it flat-lit; False (default)

Description

Turns slope-based lighting of a terrain on or off.

With shading off - which is how a terrain starts - every point on the landscape is treated as though it faces straight up. Your lights still colour the terrain, but they colour all of it the same way, so hillsides, valleys and flat ground all come out at one brightness and the shape of the land only shows in its silhouette. With shading on, the terrain works out a proper normal at each point from the surrounding heights, and the light picks out every ridge and hollow.

Nearly always you want this on. The exception is a landscape whose lighting is already baked into its texture, where a second set of shadows on top just muddies it, or a deliberately flat art style. It is a per-terrain switch you can flip at any time, so it is easy to compare.

There are two costs. Shading makes the terrain do more work when it rebuilds a patch of ground, because the normals have to be recalculated along with the vertices; and because neighbouring detail levels can disagree slightly about which way a slope faces, it can make level-of-detail changes more noticeable than they were. If you turn shading on and start seeing the landscape shimmer in the middle distance, switch vertex morphing on in TerrainDetail - that is the fix, not turning shading back off.

Changing the setting marks the whole terrain for rebuild, so flip it when a level loads or when the player changes a graphics option, rather than every frame.

Shading needs something to light it. If the terrain looks identical either way, check that you have a light in the scene, that its range reaches the ground, and that AmbientLight is not so bright that it washes the shading out.

See also: TerrainDetail, CreateTerrain, LoadTerrain, AmbientLight, TerrainNormalMap.

Example

; TerrainShading Example
; ----------------------

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

camera=CreateCamera()
CameraRange camera,1,500

; An angled sun makes the shading obvious on the hillsides
light=CreateLight()
RotateEntity light,45,45,0

; Load a 256x256 height map as a terrain
terrain=LoadTerrain("media/Height_map.bmp")

; Stretch it into a landscape: 2 units per grid square, 60 units tall
ScaleEntity terrain,2,60,2

; Spend around 4000 triangles, with vertex morphing to hide LOD pop-in
TerrainDetail terrain,4000,True

; Texture the landscape
grass_tex=LoadTexture("media/MossyGround.BMP")
EntityTexture terrain,grass_tex

; Start in the middle of the terrain
PositionEntity camera,256,30,256

shade=False

While Not KeyDown(1)

    ; Space toggles lighting of the terrain on and off
    If KeyHit(57) Then shade=1-shade

    ; TerrainShading enables or disables shading of the terrain
    TerrainShading terrain,shade

    ; Drift forward on its own; arrow keys steer and speed up
    MoveEntity camera,0,0,0.2
    If KeyDown(200) Then MoveEntity camera,0,0,1
    If KeyDown(208) Then MoveEntity camera,0,0,-1
    If KeyDown(203) Then TurnEntity camera,0,1,0
    If KeyDown(205) Then TurnEntity camera,0,-1,0

    ; Glide at a fixed height above the ground
    x#=EntityX(camera)
    z#=EntityZ(camera)
    y#=TerrainY(terrain,x,EntityY(camera),z)+8
    PositionEntity camera,x,y,z

    RenderWorld

    Text 0,0,"Space: toggle shading   Arrows: fly   Esc: exit"
    If shade Then Text 0,20,"TerrainShading terrain,True (hillsides react to the light)" Else Text 0,20,"TerrainShading terrain,False (flat, unshaded terrain)"

    Flip

Wend

End

Index