Blitz3D+ Command Reference

AddLine ( line_list,x1#,y1#,z1#,x2#,y2#,z2# )

Parameters

line_list - a line-list entity created with CreateLineList

x1#, y1#, z1# - start of the segment, in the line list's local space

x2#, y2#, z2# - end of the segment, in the line list's local space

Description

Adds one segment to a line list and returns the new segment's index.

AddLine appends a segment that stays on screen every frame until you clear or replace it - unlike a DebugLine, which lasts one RenderWorld. The returned index is zero-based (the first segment is 0), and it is what you hand to SetLine later to move that segment. Growing a trail behind a moving object is the classic pattern: each frame, add one segment from the previous position to the new one.

Coordinates are local to the line-list entity, so moving, rotating or scaling the entity moves every segment with it.

Two things stop the program with a runtime error: passing an entity that is not a line list, and exceeding the list's 65,536-segment capacity. Coordinates must also be finite. If a long-running trail could grow forever, cap it - for example, ClearLines and rebuild, or reuse old indexes with SetLine.

Requires Extended mode.

See also: CreateLineList, SetLine, CountLines, ClearLines.

Example

; AddLine Example
; ---------------
; Requires Extended mode.

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

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

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

; A comet whose flight path we trace with a line list
comet=CreateSphere()
ScaleEntity comet,0.3,0.3,0.3
EntityColor comet,255,210,40

trail=CreateLineList()
EntityColor trail,255,210,40
LineWidth trail,2

; Starting point of the trail
old_x#=3
old_y#=0
old_z#=0

While Not KeyDown(1)

    ; Space restarts the trail
    If KeyHit(57) Then ClearLines trail

    ; Fly the comet along a looping path
    angle#=angle+2
    x#=3*Cos(angle)
    y#=1.5*Sin(angle*0.7)+1.5
    z#=3*Sin(angle)
    PositionEntity comet,x,y,z

    ; AddLine appends one segment from the previous position to the new one
    AddLine trail,old_x,old_y,old_z,x,y,z
    old_x=x
    old_y=y
    old_z=z

    ; 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: restart trail   Esc: exit"
    Text 0,20,"AddLine has built a trail of "+CountLines(trail)+" segments"

    Flip

Wend

End

Index