b3dPositionMesh

Translates mesh vertices permanently (modifies geometry, not transform). Takes entity (mesh entity handle), x (X-axis translation), y (Y-axis translation - positive up), z (Z-axis translation). Returns nothing. Validates entity and mesh exist, calls EnsureUniqueMesh for copy-on-write (prevents shared mesh corruption), translates all vertices in all surfaces by (x, -y, z) with Y-axis negation, recalculates bounding radius (max distance from origin after translation), handles locked meshes (sets needsGPUUpload, defers buffer rebuild), unlocked meshes immediately call RebuildGPUBuffersFromSurfaces. Permanent geometry modification.

This function permanently modifies mesh vertex positions. Mesh vs entity transform: PositionMesh changes vertex data directly (permanent geometry modification), affects mesh coordinates (not world position), entity transform unchanged (position/rotation/scale unaffected). Contrast with b3dPositionEntity which moves entity without changing geometry. Use case: PositionMesh for one-time adjustments (centering, offsetting pivot), PositionEntity for runtime movement (animation, physics). Y-axis negation: user +Y=up, internal -Y=up, function negates Y: vertices translated by (x, -y, z), maintains coordinate system consistency with PositionEntity. Copy-on-write: calls EnsureUniqueMesh() before modification, checks if mesh shared by multiple entities (refCount>1), creates independent mesh copy if shared (prevents corruption of other entities using same mesh), single-use meshes modified in-place (no copy overhead). Implementation: iterates all surfaces in mesh, for each vertex in each surface: vertex.position += XMFLOAT3(x, -y, z), also updates position.w if used (homogeneous coordinate, typically =1.0). Bounding radius recalculation: after translating vertices, calculates max distance from origin to any vertex: boundingRadius = max(sqrt(vx*vx + vy*vy + vz*vz)), affects frustum culling and LOD calculations (incorrect radius causes culling errors). Lock/unlock pattern: if mesh.locked==true (batching multiple operations), sets mesh.needsGPUUpload=true (defers GPU buffer update), doesn't rebuild buffers yet (prevents multiple uploads), b3dUnlockMesh later rebuilds once. If mesh.locked==false, immediately calls RebuildGPUBuffersFromSurfaces (uploads to GPU), single operation efficiency. Use cases: (1) Center mesh at origin (offset pivot point), (2) Align mesh to world coordinates (imported models with wrong origin), (3) Procedural mesh generation (build mesh in stages), (4) Vertex animation baking (pre-compute deformed positions), (5) Mesh repair (shift vertices to fix alignment). Common pattern: mesh=b3dLoadMesh("model.glb"), b3dPositionMesh(mesh, -centerX, -centerY, -centerZ) to center at origin. Typical workflow: b3dLockMesh, perform multiple PositionMesh/RotateMesh/ScaleMesh calls, b3dUnlockMesh (single GPU upload for all operations). Performance: O(N) where N=total vertex count across all surfaces, locked mesh mode defers expensive GPU upload (use for batch modifications), EnsureUniqueMesh may allocate/copy (expensive if many vertices). GPU upload: RebuildGPUBuffersFromSurfaces creates new vertex/index buffers, uploads to GPU, releases old buffers (synchronization required, potential stall). Coordinate space: operates in mesh local space (before entity transform applied), translated vertices permanently offset, subsequent entity transforms apply to already-translated mesh. Hierarchy: mesh modification doesn't affect children (only entity transform propagates to children), parent mesh modification independent of child entities. Validation: invalid entity/mesh handles silently ignored. Normals/tangents: PositionMesh doesn't modify normals/tangents (translation doesn't change surface orientation), for rotation use b3dRotateMesh which updates normals/tangents. Related: b3dPositionEntity moves entity without geometry change, b3dRotateMesh rotates vertices/normals, b3dScaleMesh scales vertices, EnsureUniqueMesh handles copy-on-write, b3dLockMesh/UnlockMesh for batching, RebuildGPUBuffersFromSurfaces uploads to GPU.