Blitz3D+ Command Reference

Shadows [enable]

Parameters

enable (optional) - True turns automatic shadows on, False turns them off; True (default). The system starts disabled.

Description

Turns the automatic shadow system on or off.

This is the master switch. Shadows appear only when the whole chain is enabled: Shadows turns the system on, a shadow-enabled light is selected (LightShadows), the camera keeps CameraShadows on, and casters and receivers keep EntityShadows on. Everything except Shadows itself is on by default, so Shadows True plus a directional light is normally all it takes:

sun=CreateLight(1)
RotateEntity sun,45,30,0
Shadows True

From there the engine does the work each RenderWorld: it picks the best shadow-enabled light per camera (directional, spot, or point - see LightShadows), fits shadow maps to each camera's view, and has opaque meshes and terrain cast and receive automatically. The tuning commands all have sensible defaults: quality preset 2, black shadows at strength 0.65, automatic distance.

Details worth knowing: alpha-masked surfaces cast using their texture's alpha, so leaves shadow correctly, while alpha-blended surfaces do not cast by default. Planes and sprites receive shadows but do not cast unless you say so with EntityShadows. Disabling the system skips all shadow CPU and GPU work.

Requires Extended mode.

See also: LightShadows, ShadowQuality, ShadowColor, ShadowDistance, EntityShadows, CameraShadows.

Example

; Shadows Example
; ---------------
; Requires Extended mode.

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

camera=CreateCamera()
PositionEntity camera,0,5,-9
RotateEntity camera,25,0,0

; A directional sun; the shadow system selects it automatically
sun=CreateLight(1)
AmbientLight 70,75,85

; Ground plane that receives the shadows
ground=CreateCube()
ScaleEntity ground,10,0.1,10
PositionEntity ground,0,-0.1,4
EntityColor ground,170,190,170

; A crate and a pillar to cast shadows
crate=CreateCube()
PositionEntity crate,-2.5,1,4
EntityColor crate,210,150,80

pillar=CreateCylinder()
ScaleEntity pillar,0.7,2,0.7
PositionEntity pillar,2.5,2,5
EntityColor pillar,120,160,220

enabled=1
angle#=0

While Not KeyDown(1)

    ; Press Space to toggle the whole shadow system
    If KeyHit(57) Then enabled=1-enabled

    ; Enable or disable automatic world shadows
    Shadows enabled

    ; Swing the sun so the shadows sweep across the ground
    angle=angle+0.3
    RotateEntity sun,55,angle,0

    TurnEntity crate,0,1,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,"Space: toggle shadows   Arrow keys: move camera   Esc: exit"
    Text 0,20,"Shadows "+enabled

    Flip

Wend

End

Index