Blitz3D+ Command Reference

CreateLineList ( [parent] )

Parameters

parent (optional) - parent entity for the new line list; 0 for no parent (default)

Description

Creates a persistent 3D line-list entity and returns its handle.

A line list is a real entity that stores line segments and draws them every frame until you remove them - the retained counterpart to the one-frame Debug commands. Build one for anything that should stay on screen: an editor grid, a waypoint path, a comet trail, a trajectory preview, a wireframe HUD element floating in the world.

Segments are added with AddLine, edited with SetLine and removed with ClearLines, and their coordinates are in the entity's local space. That is the line list's superpower: PositionEntity, RotateEntity and ScaleEntity move all of its lines as one object, and parenting it to another entity carries the whole drawing along.

The usual entity toolkit applies: EntityColor tints the lines, EntityAlpha fades them, EntityBlend changes how they blend, EntityOrder layers them, HideEntity and ShowEntity toggle them, CopyEntity duplicates the whole list, and FreeEntity destroys it. Lines render unlit and untextured, at a constant pixel width set by LineWidth, with depth behaviour set by LineDepthMode. A line list never takes part in collisions or shadows.

Each list holds up to 65,536 segments.

For throwaway one-frame markers, the immediate DebugLine family is less ceremony; for anything that persists, a line list is cheaper than re-issuing debug lines every frame.

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

Requires Extended mode.

See also: AddLine, SetLine, ClearLines, LineWidth, LineDepthMode, DebugLine.

Example

; CreateLineList Example
; ----------------------
; Requires Extended mode.

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

camera=CreateCamera()
PositionEntity camera,0,4,-10

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

; CreateLineList makes a retained line entity - here an editor-style floor grid
lines=CreateLineList()
EntityColor lines,30,180,255
LineWidth lines,2
For c=-4 To 4
    AddLine lines,c,0,-4,c,0,4
    AddLine lines,-4,0,c,4,0,c
Next

; A ball bouncing on the grid so the scene lives
ball=CreateSphere()
ScaleEntity ball,0.5,0.5,0.5
EntityColor ball,255,210,40

While Not KeyDown(1)

    ; Bounce the ball across the grid
    angle#=angle+2
    PositionEntity ball,2*Sin(angle*0.7),0.5+Abs(2*Sin(angle)),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   Esc: exit"
    Text 0,20,"The grid is one line-list entity holding "+CountLines(lines)+" segments"
    Text 0,40,"Line width stays constant however close the camera gets"

    Flip

Wend

End

Index