b3dAddTriangle

Adds triangle to surface using three vertex indices, defines renderable face. Takes mesh (surface-based mesh entity), surface (surface handle, 0-based), v0/v1/v2 (vertex indices from b3dAddVertex calls). Returns nothing. Validates mesh exists, type is ENTITY_MESH, surface-based, and surface index valid. Validates each vertex index in range [0, vertices.size()). Appends v0, v1, v2 to surface->indices array (3 consecutive indices = 1 triangle). Sets mesh->needsGPUUpload=true. Silently returns on validation errors. Triangle winding order determines front-facing: counter-clockwise (CCW) from outside = front, clockwise (CW) = back (culled unless double-sided).

This function connects vertices into renderable polygons for mesh geometry. Triangle = fundamental rendering primitive - GPU rasterizes triangles to pixels. Three vertices define triangle corners - winding order (v0->v1->v2 sequence) determines which side is front-facing. CCW winding (vertices ordered counter-clockwise when viewed from outside) = front face (rendered), CW winding = back face (culled by default backface culling). Index validation critical - referencing non-existent vertex causes GPU errors or crashes. Valid indices: 0 to (vertex count - 1). Indices array structure: [tri0_v0, tri0_v1, tri0_v2, tri1_v0, tri1_v1, tri1_v2, ...] - every 3 consecutive indices = 1 triangle. Triangle count = indices.size() / 3. Use cases: (1) Surface construction (connect grid of vertices into mesh), (2) Polygon tessellation (split quads/n-gons into triangles), (3) Dynamic geometry (add/remove triangles for morphing), (4) Procedural modeling (algorithm-generated faces). Common pattern: Create square from 4 vertices: v0=(0,0,0), v1=(1,0,0), v2=(1,1,0), v3=(0,1,0), add triangles (v0,v1,v2) and (v0,v2,v3) for CCW front face. Winding consistency important - all triangles in mesh should face consistently outward. Inconsistent winding causes lighting artifacts (some faces dark). Shared vertices efficient - multiple triangles reference same vertices, saves memory vs duplicating vertex data. Vertex normals averaged across adjacent triangles during b3dUpdateNormals - smooth shading between connected faces. Hard edges require duplicate vertices (same position, different normals) at shared edge. Must lock mesh before AddTriangle. After adding all triangles, unlock to upload. Degenerate triangles (v0=v1 or v1=v2 or v2=v0) create zero-area triangles - should avoid, some drivers reject. Triangle strips/fans not used - simple indexed triangle list for flexibility. GPU rendering: indices fetched from index buffer, vertex shader processes referenced vertices, rasterizer fills triangle area. Alternative: load mesh from file, use primitives, manual index buffer construction. Backface culling configurable via b3dCullMode - can render double-sided if needed.