b3dFlipSurfaceWindingOrder

Reverses triangle winding order in surface (flips front/back faces). Takes mesh (surface-based mesh entity), surface (surface handle, 0-based). Returns nothing. Validates mesh exists, type is ENTITY_MESH, is surface-based, and surface index valid. Swaps indices 1 and 2 of each triangle: (v0, v1, v2) becomes (v0, v2, v1). Reverses winding order: CCW -> CW or CW -> CCW. Sets surface->needsGPUUpload=true and mesh->needsGPUUpload=true. Silently returns on validation errors.

This function fixes inside-out meshes by reversing face orientation. Winding order determines front vs back face: Counter-Clockwise (CCW) from outside = front-facing (rendered), Clockwise (CW) = back-facing (culled by default backface culling). Swapping indices 1 and 2 reverses triangle direction while preserving first vertex. Use cases: (1) Fix imported meshes with inverted normals (inside-out geometry), (2) Create double-sided rendering (flip and duplicate), (3) Mirror mesh (flip after scaling by negative), (4) Correct modeling software coordinate system mismatch. Common pattern: If mesh appears dark or invisible (normals pointing inward), call b3dFlipSurfaceWindingOrder, then b3dUpdateNormals to recalculate normals. Triangle transformation: Original (v0, v1, v2) - CCW when viewed from front, Flipped (v0, v2, v1) - CW when viewed from front = CCW when viewed from back (new front). Why indices 1 and 2: preserves v0 as anchor, reverses edge direction v0->v1->v2 to v0->v2->v1. Must lock: not required, but common to call during mesh editing session. GPU upload deferred: changes rendered on b3dUnlockMesh. Alternative: b3dFlipMeshWindingOrder for entire mesh, manually rebuild with reversed vertex order, scale by negative on one axis (also flips). Backface culling: GPU discards CW triangles by default (configurable), flipping makes back faces visible. Normal update: after flipping winding, call b3dUpdateNormals - old normals now point inward (wrong direction). Performance: O(T) where T=triangle count in surface - swaps 2 indices per triangle. Side effects: breaks normal directions (now pointing opposite), may reveal backface textures/materials. Inside-out detection: mesh appears black (all normals facing inward), or invisible from outside (backface culled). Coordinate system conversion: some formats use left-handed coordinates (DirectX) vs right-handed (OpenGL) - flipping winding converts between them.