Blitz3D+ Command Reference

UpdateNormals mesh

Parameters

mesh - mesh handle

Description

Recalculates the vertex normals of every surface in a mesh.

Normals tell the lighting which way each part of a surface faces. Vertices you add yourself start with a normal of 0,0,0, so a hand-built mesh looks flat or black under lights until you either set normals manually with VertexNormal or call UpdateNormals once the geometry is complete.

Call it again whenever you reshape the mesh - after moving vertices with VertexCoords for deformation effects, for instance - or the lighting will keep using the old directions.

Each vertex gets the average of the face directions of the triangles that touch it. The averaging goes by position, not by index: vertices sitting at exactly the same spot receive the same smoothed normal even if they belong to different triangles, so duplicating vertices does not create hard edges. For a deliberately sharp crease, set the normals yourself with VertexNormal after (or instead of) calling UpdateNormals.

See also: VertexNormal, VertexCoords, AddTriangle, CreateMesh.

Example

; UpdateNormals Example
; ---------------------

; Lighting needs normals. When you build or deform a mesh by hand its
; normals are missing or stale, so the lighting looks wrong.
; UpdateNormals recalculates every normal from the triangle shapes.
; Space crumples the ground; U repairs the lighting.

Graphics3D 640,480
SetBuffer BackBuffer()

camera=CreateCamera()
PositionEntity camera,0,3,-5
RotateEntity camera,30,0,0

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

SeedRnd MilliSecs()

; Build a 13 x 13 grid of vertices as rocky ground
ground=CreateMesh()
surf=CreateSurface(ground)
For j=0 To 12
    For i=0 To 12
        AddVertex surf,i*0.4-2.4,Rnd(0,0.5),2.4-j*0.4
    Next
Next

; Connect each grid cell with two upward-facing triangles
For j=0 To 11
    For i=0 To 11
        v00=j*13+i
        AddTriangle surf,v00,v00+1,v00+14
        AddTriangle surf,v00,v00+14,v00+13
    Next
Next

EntityColor ground,90,200,100

; Calculate correct normals for the starting terrain
UpdateNormals ground
stale=0

While Not KeyDown(1)

    ; Space crumples the terrain - normals are now STALE, so the
    ; lighting no longer matches the new shape
    If KeyHit(57) Then
        For j=0 To 12
            For i=0 To 12
                VertexCoords surf,j*13+i,i*0.4-2.4,Rnd(0,0.5),2.4-j*0.4
            Next
        Next
        stale=1
    EndIf

    ; U recalculates the normals - the documented command
    If KeyHit(22) Then UpdateNormals ground : stale=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,"Space: crumple terrain   U: UpdateNormals   Arrow keys: move camera   Esc: exit"
    If stale Then
        Text 0,20,"Normals STALE - lighting is wrong. Press U to fix it"
    Else
        Text 0,20,"UpdateNormals applied - lighting matches the shape"
    EndIf

    Flip

Wend

End

Index