Blitz3D+ Command Reference

ClearSurface surface[,clear_vertices][,clear_triangles]

Parameters

surface - surface handle

clear_vertices (optional) - True to remove all vertices from the surface; True (default)
clear_triangles (optional) - True to remove all triangles from the surface; True (default)

Description

Removes all vertices and/or triangles from a surface.

This is the reset button for dynamic geometry: clear the surface, then rebuild it with AddVertex and AddTriangle. Games use it for meshes that change shape every frame - trails, beams, procedural water - or for swapping in a different level of detail. The change shows up immediately.

Be careful clearing only one of the two: triangles refer to vertices by index, so wiping the vertices while keeping the triangles leaves triangles pointing at corners that no longer exist. Unless you have a specific plan, clear both (the default).

After a clear, vertex and triangle index numbers start again from 0.

See also: CreateSurface, AddVertex, AddTriangle, CountVertices, CountTriangles.

Example

; ClearSurface Example
; --------------------

; ClearSurface removes ALL vertices and triangles from a surface,
; leaving it empty and ready to refill - ideal for geometry that is
; rebuilt on the fly. Space clears this fan and rebuilds it with a
; random number of blades.

Graphics3D 640,480
SetBuffer BackBuffer()

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

fan=CreateMesh()
surf=CreateSurface(fan)

; Show vertex colours without needing a light
EntityFX fan,2

SeedRnd MilliSecs()
spokes=6
rebuild=1

While Not KeyDown(1)

    ; Space empties the surface and rebuilds with a new blade count
    If KeyHit(57) Then spokes=Rand(3,12) : rebuild=1

    If rebuild Then
        rebuild=0
        ; The documented command: wipe the surface completely
        ClearSurface surf
        centre=AddVertex(surf,0,0,0)
        VertexColor surf,centre,255,255,255
        For i=0 To spokes-1
            ang#=i*360.0/spokes
            ; Two rim vertices per blade leave a gap between blades
            r0=AddVertex(surf,Cos(ang)*2,Sin(ang)*2,0)
            r1=AddVertex(surf,Cos(ang+24)*2,Sin(ang+24)*2,0)
            VertexColor surf,r0,255,160,0
            VertexColor surf,r1,255,60,0
            AddTriangle surf,centre,r1,r0
        Next
    EndIf

    ; Keep the fan spinning
    TurnEntity fan,0,0,1

    ; 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,"Space: ClearSurface and rebuild   Arrow keys: move camera   Esc: exit"
    Text 0,20,"Rebuilt with "+spokes+" blades: "+CountTriangles(surf)+" triangles, "+CountVertices(surf)+" vertices"

    Flip

Wend

End

Index