b3dAddVertex

Adds vertex to surface with position and UV coordinates, returns vertex index. Takes mesh (surface-based mesh entity), surface (surface handle, 0-based), x/y/z (position coordinates as doubles), u/v (texture coordinates as doubles, typically 0-1 range). Returns vertex index (0-based, sequential) or -1 on error. Validates mesh exists, type is ENTITY_MESH, surface-based, and surface index valid. Creates Vertex3D structure, zero-initializes all fields. Sets position to (x, -y, z) - NOTE: Y-axis negated for DirectX convention (user Y+ = up, DirectX Y- = up). Sets default normal to (0, -1, 0) - upward-pointing (negated). Sets texCoord to (u, v). Sets color to (1, 1, 1, 1) - white. Sets tangent to (1, 0, 0, 1), bitangent to (0, 1, 0). Appends vertex to surface->vertices array. Sets mesh->needsGPUUpload=true. Returns vertices.size()-1 as vertex index. Returns -1 on validation failure.

This function builds mesh geometry vertex-by-vertex for procedural mesh construction. Vertex represents single point in 3D space with attributes: position (where), normal (surface direction), UV (texture mapping), color (tint), tangent/bitangent (normal mapping). Zero-initialization critical - ensures all fields have valid values, prevents GPU crashes from uninitialized data. Y-axis negation convention: BambooBasic uses Y-up coordinate system (standard 3D), DirectX uses Y-down (legacy), negation converts between systems automatically. User specifies position as (0, 10, 0) meaning 10 units up, stored as (0, -10, 0) in DirectX coordinates. Default normal (0, -1, 0) points upward after negation - typically overwritten by normal calculation (b3dUpdateNormals) or manual assignment. UV coordinates: (0,0) = top-left corner of texture, (1,1) = bottom-right, outside 0-1 range causes tiling/clamping based on sampler settings. Default white color (1,1,1,1) means no tinting - vertex colors multiply with texture during rendering. Tangent/bitangent default values placeholder - proper values calculated during normal mapping setup if needed. Vertex index usage: save returned index for triangle construction with b3dAddTriangle. Indices sequential starting at 0 - first AddVertex returns 0, second returns 1, etc. Vertex duplication required for hard edges - shared position but different normals/UVs requires separate vertices. Use cases: (1) Procedural terrain (generate heightfield grid vertices), (2) Custom shapes (define box/sphere/torus vertices manually), (3) Dynamic meshes (modify vertex positions each frame for deformation), (4) Debug visualization (create line/point clouds). Common workflow: v0=b3dAddVertex(mesh, surf, x0,y0,z0, u0,v0), v1=b3dAddVertex(mesh, surf, x1,y1,z1, u1,v1), v2=b3dAddVertex(mesh, surf, x2,y2,z2, u2,v2), b3dAddTriangle(mesh, surf, v0,v1,v2). Must lock mesh before AddVertex: b3dLockMesh required before any vertex/triangle modifications. After adding all vertices/triangles, call b3dUnlockMesh to upload to GPU. UV coordinates unclamped - can use negative or >1 values for texture repetition. Vertex normal updated by b3dUpdateNormals after triangle topology established. Alternative: load mesh from file (b3dLoadMesh), use primitive creators (b3dCreateSphere/Cube/etc).