Blitz3D+ Command Reference

DebugLine x1#,y1#,z1#,x2#,y2#,z2#[,red][,green][,blue][,depth_test]

Parameters

x1#, y1#, z1# - world-space start of the line

x2#, y2#, z2# - world-space end of the line

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

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

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

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

Description

Queues a one-frame debug line in world space for the next RenderWorld.

DebugLine is the simplest of the immediate debug-draw commands. Call it any time before RenderWorld and the line appears in that render, through every active camera, drawn after the scene. It is perfect for making invisible things visible while you build a game: the ray of a LinePick, an enemy's line of sight, a velocity vector, the path between two waypoints.

The central rule of the whole Debug family: shapes live for exactly one RenderWorld. The queue is drawn by the next RenderWorld and then cleared, so re-issue the call every frame for as long as you want the line on screen. If your line flashes up for a single frame and vanishes, the call is probably sitting outside your main loop.

With depth_test True (the default) the line is hidden by closer geometry like a normal object. Pass False to draw it on top of everything - handy when the thing you are inspecting is buried inside a wall or a mesh.

All Debug commands share one queue of 65,536 lines. If a frame fills it, the extra lines are dropped for that render and a warning is filed in the diagnostics store.

Debug lines are always one pixel wide and always temporary. For lines that persist from frame to frame, with adjustable width and depth behaviour, build a line-list entity with CreateLineList instead.

For the full story, see the Prototyping and Diagnostics guide.

Requires Extended mode.

See also: DebugPoint, DebugBox, DebugSphere, ClearDebugDraw, CreateLineList.

Example

; DebugLine Example
; -----------------
; Requires Extended mode.

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

camera=CreateCamera()
PositionEntity camera,0,3,-9

light=CreateLight()
RotateEntity light,45,45,0

; A turret watching an enemy circle the arena
turret=CreateCone()
EntityColor turret,120,140,160

enemy=CreateCube()
EntityColor enemy,220,60,60

show=True

While Not KeyDown(1)

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

    ; The enemy circles the turret
    angle#=angle+1.5
    PositionEntity enemy,5*Cos(angle),1+Sin(angle*3),5*Sin(angle)+3
    PointEntity turret,enemy

    ; DebugLine queues the turret's line of sight for the next RenderWorld
    If show Then DebugLine 0,1,0,EntityX(enemy),EntityY(enemy),EntityZ(enemy),255,255,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,"Arrow keys: move camera   Space: toggle overlay   Esc: exit"
    If show Then Text 0,20,"DebugLine draws the turret's line of sight" Else Text 0,20,"Overlay off - press Space"

    Flip

Wend

End

Index