Blitz3D+ Command Reference

DebugLightVolume light[,red][,green][,blue][,depth_test]

Parameters

light - light whose influence to draw

red (optional) - red part of the colour, 0-255; 255 (default)

green (optional) - green part of the colour, 0-255; 245 (default)

blue (optional) - blue part of the colour, 0-255; 120 (default)

depth_test (optional) - True hides the lines behind closer geometry, False draws them through everything; True (default)

Description

Queues a wireframe showing a light's position, direction and range for the next RenderWorld.

Lights are invisible, so lighting bugs usually come down to two questions you cannot answer by looking: where is the light really, and how far does it reach? DebugLightVolume draws the answer for each light type:

A directional light (type 1) draws a short arrow along its facing direction - only its orientation matters, so that is all you need to see.

A point light (type 2) draws three circles at its LightRange radius, marking the sphere inside which it has any effect.

A spot light (type 3) draws its cone from the light's position out to LightRange, with the cone's spread taken from the outer angle set by LightConeAngles.

When something sits unlit in a scene that should be bright, one frame of this overlay usually shows why: the object is just outside the range circle, or the spot cone is aimed past it.

Like every Debug command, the wireframe lives for exactly one RenderWorld: the queue is drawn by the next RenderWorld and then cleared, so call DebugLightVolume every frame for as long as you want it visible.

Requires Extended mode.

See also: CreateLight, LightRange, LightConeAngles, ClearDebugDraw.

Example

; DebugLightVolume Example
; ------------------------
; Requires Extended mode.

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

camera=CreateCamera()
PositionEntity camera,0,5,-12

AmbientLight 50,50,50

; A dark prison yard floor with some crates
floor=CreatePlane()
EntityColor floor,60,70,80

crate1=CreateCube()
PositionEntity crate1,-2,1,2
EntityColor crate1,150,110,70

crate2=CreateCube()
PositionEntity crate2,3,1,4
EntityColor crate2,150,110,70

; A searchlight sweeping the yard
light=CreateLight(3)
PositionEntity light,0,6,3
LightRange light,10
LightConeAngles light,15,35

show=True

While Not KeyDown(1)

    ; Space toggles the volume overlay
    If KeyHit(57) Then show=Not show

    ; Swing the searchlight back and forth
    angle#=angle+1
    RotateEntity light,65,50*Sin(angle),0

    ; DebugLightVolume queues the spot light's current range and cone
    If show Then DebugLightVolume light

    ; 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: toggle overlay   Esc: exit"
    If show Then Text 0,20,"The cone matches LightRange 10 and LightConeAngles 15,35" Else Text 0,20,"Overlay off - press Space"

    Flip

Wend

End

Index