Blitz3D+ Command Reference

LightShadows light[,enabled][,priority]

Parameters

light - light handle

enabled (optional) - True lets the light take part in shadow selection; True (default)

priority (optional) - higher values win selection; 0 (default)

Description

Controls whether a light may cast automatic shadows, and which light wins.

Shadows appear only when the whole chain is enabled: Shadows turns the system on, a shadow-enabled light is selected (this command), the camera keeps CameraShadows on, and casters and receivers keep EntityShadows on. Lights are created shadow-enabled at priority 0.

One light casts shadows per camera. The engine picks the enabled light with the highest priority; on equal priority a directional light beats spot and point lights, and creation order breaks remaining ties. Directional, spot and point lights are all supported, but point lights render six shadow faces and are only considered at ShadowQuality 2 or higher.

Two everyday uses: disable shadows on incidental lights - a muzzle flash or pickup glow should not steal the sun's shadows - and raise priority on the light that should win a scene, such as an interior spotlight overriding the outdoor sun while the player is inside.

Requires Extended mode.

See also: Shadows, ShadowQuality, CameraShadows, EntityShadows, CreateLight.

Example

; LightShadows Example
; --------------------
; Requires Extended mode.

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

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

AmbientLight 70,75,85

; Two directional suns from opposite sides; only one may cast shadows
warm_sun=CreateLight(1)
RotateEntity warm_sun,50,60,0
LightColor warm_sun,255,220,180

cool_sun=CreateLight(1)
RotateEntity cool_sun,50,-60,0
LightColor cool_sun,180,210,255

; 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

; Turn on the automatic shadow system
Shadows 1

; Start with the warm sun as the shadow caster
LightShadows warm_sun,1,10
LightShadows cool_sun,1,0
caster$="warm sun (priority 10 beats 0)"

While Not KeyDown(1)

    ; Press 1 or 2 to hand the higher priority to a sun; 0 disables both
    If KeyHit(2) Then
        LightShadows warm_sun,1,10
        LightShadows cool_sun,1,0
        caster="warm sun (priority 10 beats 0)"
    EndIf
    If KeyHit(3) Then
        LightShadows warm_sun,1,0
        LightShadows cool_sun,1,10
        caster="cool sun (priority 10 beats 0)"
    EndIf
    If KeyHit(11) Then
        LightShadows warm_sun,0
        LightShadows cool_sun,0
        caster="none (both lights excluded)"
    EndIf

    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,"1/2: pick shadow sun   0: disable both   Arrow keys: move camera   Esc: exit"
    Text 0,20,"LightShadows caster: "+caster

    Flip

Wend

End

Index