b3dClearSurface

Clears all vertices and triangles from a surface, resetting it to empty state. Takes mesh (surface-based mesh entity), surface (surface handle, 0-based). Returns nothing. Validates mesh exists, type is ENTITY_MESH, surface-based, and surface index valid. Clears vertices array (surface->vertices.clear()). Clears indices array (surface->indices.clear()). Sets mesh->needsGPUUpload=true (flags for GPU buffer recreation on next unlock). Silently returns on validation errors. Surface still exists after clearing - only geometry removed, material preserved.

This function resets surface to post-creation state for reuse or geometry rebuilding. Clear operation deallocates vertex/index memory - surface becomes empty but remains part of mesh. Material unchanged - clearing affects only geometry data, not rendering properties. Use cases: (1) Dynamic mesh regeneration (clear surface each frame, rebuild with new vertices/triangles), (2) Mesh editing (remove all geometry before reconstruction), (3) Memory reclamation (clear unused surfaces without deleting), (4) Procedural animation (rebuild geometry procedurally each update). After clearing, surface ready for new AddVertex/AddTriangle calls - vertex indices restart at 0. needsGPUUpload flag critical - ensures GPU buffers recreated to match cleared state, prevents rendering stale geometry. Common workflow: b3dLockMesh(mesh), b3dClearSurface(mesh, surface), rebuild geometry with b3dAddVertex/b3dAddTriangle, b3dUnlockMesh(mesh). Clearing vs deleting: ClearSurface empties geometry but keeps surface slot (material, atlas settings preserved), deleting surface would remove from surfaces array (not provided in API - surfaces persist once created). Performance: O(1) operation - vector.clear() deallocates but doesn't reallocate, subsequent AddVertex may avoid reallocation if capacity remains. Alternative: delete entire mesh and recreate, create new surface and abandon old (wastes memory), conditional vertex addition (skip clear, overwrite existing). Surface material survives clearing - can reassign textures/colors without rebuilding material system. Empty surface valid but not renderable - must add at least 1 triangle (3 vertices) for visibility.