Blitz3D+ Command Reference

AddVertex ( surface,x#,y#,z#[,u#][,v#][,w#] )

Parameters

surface - surface handle

x# - x coordinate of the vertex
y# - y coordinate of the vertex
z# - z coordinate of the vertex

u# (optional) - u texture coordinate; 0 (default)
v# (optional) - v texture coordinate; 0 (default)
w# (optional) - w texture coordinate; 1 (default). Accepted for compatibility but not used by the renderer.

Description

Adds a vertex to a surface and returns the vertex's index number, starting from 0.

A vertex is a corner point in 3D space; you need at least three to make a triangle. Keep the returned index numbers - AddTriangle uses them to say which three corners each triangle connects. Indices are per-surface: vertex 0 in one surface has nothing to do with vertex 0 in another.

The optional u and v parameters set texture coordinates, which control how a texture stretches over any triangle built from this vertex. The top-left of an image is u 0, v 0; the top-right is 1,0; the bottom-right is 1,1. Values outside 0-1 tile the texture. The same u,v is written to both texture coordinate sets (0 and 1) - use VertexTexCoords to set the two sets differently.

A new vertex starts with colour 255,255,255, alpha 1 and a normal of 0,0,0. That zero normal makes lighting look wrong until you either set normals yourself with VertexNormal or call UpdateNormals once the mesh is built.

See also: AddTriangle, CreateSurface, VertexCoords, VertexTexCoords, VertexColor, UpdateNormals.

Example

; AddVertex Example
; -----------------

; AddVertex adds a point to a surface and returns its index number,
; counting from 0. The optional u,v parameters say which part of a
; texture the vertex pins to: 0,0 is the texture's top-left corner,
; 1,1 its bottom-right.

Graphics3D 640,480
SetBuffer BackBuffer()

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

banner=CreateMesh()
surf=CreateSurface(banner)

; Four vertices make the corners of a banner - the documented command
v0=AddVertex(surf,-2,1,0,0,0)  ; top left     (u 0, v 0)
v1=AddVertex(surf,2,1,0,1,0)   ; top right    (u 1, v 0)
v2=AddVertex(surf,2,-1,0,1,1)  ; bottom right (u 1, v 1)
v3=AddVertex(surf,-2,-1,0,0,1) ; bottom left  (u 0, v 1)

; Two clockwise triangles connect the four corners into a quad
AddTriangle surf,v0,v1,v2
AddTriangle surf,v0,v2,v3

; Texture the banner so we can see the uv mapping at work
tex=LoadTexture("media/b3dlogo.jpg")
EntityTexture banner,tex

; Fullbright (1) + two-sided (16) so it stays visible while spinning
EntityFX banner,17

While Not KeyDown(1)

    TurnEntity banner,0,1,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,"AddVertex returned indices "+v0+","+v1+","+v2+","+v3
    Text 0,40,"Each vertex pins one texture corner: uv 0,0 = top left"

    Flip

Wend

End

Index