b3dFlipMesh

Reverses mesh winding order and flips normals/tangents (inside-out flip). Takes entity (mesh entity handle). Returns nothing. Validates entity and mesh exist, calls EnsureUniqueMesh for copy-on-write, for each surface: reverses index order (triangle winding), negates normals (flips surface direction), negates tangents (maintains texture orientation), preserves tangent handedness (.w unchanged), handles locked meshes (sets needsGPUUpload, defers buffer rebuild), unlocked meshes immediately call RebuildGPUBuffersFromSurfaces. Permanent geometry modification.

This function turns mesh inside-out. Use case: fix incorrectly wound meshes (backface culling hides wrong side), mirror objects (negative scale breaks winding, flip fixes it), create hollow objects (render both sides with separate entities), procedural geometry (reverse orientation as needed). Copy-on-write: calls EnsureUniqueMesh() before modification, checks if mesh shared (refCount>1), creates independent copy if shared, single-use meshes modified in-place. Winding order reversal: iterates all surfaces, for each triangle (3 indices): swaps index[i] with index[i+2] (reverses triangle order), changes front face from CCW to CW or vice versa (affects backface culling), culling mode unchanged (flip mesh instead of changing cull mode preserves lighting). Backface culling: DirectX defaults to culling clockwise triangles (cull back faces), winding determines which side is front, flipping makes back face become front face. Normal negation: iterates all vertices in all surfaces, negates normal: normal = -normal (flips surface orientation), lighting calculations use negated normals (light reflects opposite direction), fixes lighting for inside-out meshes. Tangent negation: negates tangent.xyz (flips tangent direction), preserves tangent.w (handedness, used for bitangent calculation), maintains normal mapping correctness (tangent space flips with normal). UV coordinates: NOT modified (texture mapping unchanged, may appear flipped on opposite side). Position: NOT modified (vertices stay in place, only orientation flips). Bounding radius: NOT recalculated (flip doesn't change vertex positions, radius unchanged). Lock/unlock pattern: if mesh.locked==true, sets mesh.needsGPUUpload=true, defers GPU buffer update. If mesh.locked==false, immediately calls RebuildGPUBuffersFromSurfaces. Use cases: (1) Fix incorrectly exported models (inside-out geometry), (2) Mirror objects (after b3dScaleMesh with negative scale), (3) Create hollow shells (outer and inner surfaces with opposite winding), (4) Procedural generation (reverse sections as needed), (5) Debugging (visualize backfaces). Common pattern: mesh=b3dLoadMesh("model.glb"), b3dScaleMesh(mesh, -1, 1, 1), b3dFlipMesh(mesh) to mirror along X-axis with correct winding. Typical workflow: check if mesh renders wrong side, b3dFlipMesh to correct, or b3dLockMesh, scale/flip/modify, b3dUnlockMesh. Performance: O(N + M) where N=total vertex count (normal/tangent negation), M=total index count (winding reversal), relatively fast (simple negation/swap operations), locked mesh mode defers GPU upload. GPU upload: RebuildGPUBuffersFromSurfaces creates new vertex/index buffers, uploads to GPU. Coordinate space: operates in mesh local space, flipped geometry permanently reversed, subsequent entity transforms apply to flipped mesh. Hierarchy: mesh modification doesn't affect children, parent mesh flip independent of child entities. Validation: invalid entity/mesh handles silently ignored. Double flip: calling twice returns mesh to original state (flip is reversible operation). Lighting: flipped normals change lighting (surfaces lit from opposite direction), may require adjusting light positions after flip. Shadows: flipped winding may affect shadow rendering (depends on shadow algorithm). Reflection: flipped geometry appears correct in mirrors/reflections. Related: b3dScaleMesh with negative scale (requires flip to fix winding), EnsureUniqueMesh handles copy-on-write, b3dLockMesh/UnlockMesh for batching, RebuildGPUBuffersFromSurfaces uploads to GPU, b3dRotateMesh rotates without flipping.