Blitz3D+ Command Reference

DebugGrid [size#][,step#][,y#][,red][,green][,blue][,depth_test]

Parameters

size# (optional) - overall width and depth of the grid in world units; must be positive; 20 (default)

step# (optional) - spacing between grid lines; must be positive; 1 (default)

y# (optional) - height of the grid plane; 0 (default)

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

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

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

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

Description

Queues a flat XZ reference grid, centred on the world origin, for the next RenderWorld.

DebugGrid gives an empty scene a floor. While you are blocking out a level or testing movement code, the grid makes position, scale and distance readable at a glance - each default cell is exactly one world unit. The grid spans size# by size# units, centred on 0,0 in X and Z, at height y#.

Like every Debug command, the grid lives for exactly one RenderWorld: the queue is drawn by the next RenderWorld and then cleared, so call DebugGrid every frame for as long as you want it on screen. A zero or negative size or step stops the program with a runtime error.

The default subdued grey stays readable without shouting over your scene; recolour it if it fights your background. A big grid with a tiny step eats into the shared 65,536-line debug budget quickly, so keep the step sensible.

For a grid that persists every frame without re-issuing, or one you can move and rotate like an entity, build one once with CreateLineList and AddLine instead.

Requires Extended mode.

See also: DebugLine, DebugEntityAxes, ClearDebugDraw, CreateLineList.

Example

; DebugGrid 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

; A hovering ship to give the grid a sense of scale
ship=CreateCone()
EntityColor ship,80,200,255

show=True
spacing#=1

While Not KeyDown(1)

    ; Space toggles the grid, [ and ] change its step size
    If KeyHit(57) Then show=Not show
    If KeyHit(26) And spacing>0.5 Then spacing=spacing-0.5
    If KeyHit(27) And spacing<4 Then spacing=spacing+0.5

    ; The ship bobs and drifts above the ground plane
    angle#=angle+1.5
    PositionEntity ship,3*Sin(angle),1.5+0.5*Sin(angle*3),2

    ; DebugGrid queues a centred XZ ground grid for the next RenderWorld
    If show Then DebugGrid 20,spacing,0,90,90,90

    ; 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 grid   [ / ] : step   Esc: exit"
    If show Then Text 0,20,"DebugGrid 20,"+spacing+",0" Else Text 0,20,"Grid off - press Space"

    Flip

Wend

End

Index