Blitz3D+ Command Reference

ShadowDistance [distance#]

Parameters

distance# (optional) - furthest distance from the camera that shadows cover, in world units; 0 selects automatic coverage (default)

Description

Limits how far from the camera shadows are drawn.

With the automatic setting, directional shadows cover out to the camera's far range and local lights cover out to their LightRange. A positive value caps that coverage.

Why cap it? A shadow map spread over less ground gives each texel more detail, so shadows get visibly sharper, and fewer casters need rendering into the maps. It is the classic outdoor tuning move: pull the distance in until nearby shadows look crisp, stopping before players notice shadows popping out in the distance. A racing game might cover 150 units; a corridor shooter can go much tighter.

The command tunes the running system - the on/off switch and the rest of the chain live in Shadows.

Requires Extended mode.

See also: Shadows, ShadowQuality, CameraRange, LightRange.

Example

; ShadowDistance Example
; ----------------------
; Requires Extended mode.

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

camera=CreateCamera()
PositionEntity camera,0,4,-6
RotateEntity camera,15,0,0

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

; A long road stretching away from the camera
road=CreateCube()
ScaleEntity road,6,0.1,60
PositionEntity road,0,-0.1,50
EntityColor road,170,190,170

; A parade of pillars marching into the distance
For i=0 To 11
    pillar=CreateCylinder()
    ScaleEntity pillar,0.6,2,0.6
    PositionEntity pillar,-3+6*(i Mod 2),2,4+i*8
    EntityColor pillar,120+i*10,160,220-i*10
Next

; Turn on the automatic shadow system
Shadows 1

dist#=40

While Not KeyDown(1)

    ; [ / ] shrink or extend the shadow range; A returns to automatic
    If KeyDown(26) And dist>5 Then dist=dist-0.5
    If KeyDown(27) And dist<150 Then dist=dist+0.5
    If KeyHit(30) Then dist=0

    ; Cap how far from the camera shadows are drawn (0 = automatic)
    ShadowDistance dist

    ; 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,"[ ]: shadow distance   A: automatic   Arrow keys: move camera   Esc: exit"
    If dist=0
        Text 0,20,"ShadowDistance 0   (automatic cap)"
    Else
        Text 0,20,"ShadowDistance "+dist
    EndIf
    Text 0,40,"Distant pillars lose their shadows as the cap shrinks"

    Flip

Wend

End

Index